1 /* $MirOS: src/usr.sbin/httpd/src/include/http_protocol.h,v 1.2 2013/10/31 20:07:21 tg Exp $ */ 2 /* $OpenBSD: http_protocol.h,v 1.11 2005/03/28 23:26:51 niallo Exp $ */ 3 4 /* ==================================================================== 5 * The Apache Software License, Version 1.1 6 * 7 * Copyright © 2013 8 * Thorsten “mirabilos” Glaser <tg@mirbsd.org> 9 * Copyright (c) 2000-2003 The Apache Software Foundation. All rights 10 * reserved. 11 * 12 * Redistribution and use in source and binary forms, with or without 13 * modification, are permitted provided that the following conditions 14 * are met: 15 * 16 * 1. Redistributions of source code must retain the above copyright 17 * notice, this list of conditions and the following disclaimer. 18 * 19 * 2. Redistributions in binary form must reproduce the above copyright 20 * notice, this list of conditions and the following disclaimer in 21 * the documentation and/or other materials provided with the 22 * distribution. 23 * 24 * 3. The end-user documentation included with the redistribution, 25 * if any, must include the following acknowledgment: 26 * "This product includes software developed by the 27 * Apache Software Foundation (http://www.apache.org/)." 28 * Alternately, this acknowledgment may appear in the software itself, 29 * if and wherever such third-party acknowledgments normally appear. 30 * 31 * 4. The names "Apache" and "Apache Software Foundation" must 32 * not be used to endorse or promote products derived from this 33 * software without prior written permission. For written 34 * permission, please contact apache@apache.org. 35 * 36 * 5. Products derived from this software may not be called "Apache", 37 * nor may "Apache" appear in their name, without prior written 38 * permission of the Apache Software Foundation. 39 * 40 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED 41 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 42 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 43 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR 44 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 47 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 48 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 49 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 50 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 51 * SUCH DAMAGE. 52 * ==================================================================== 53 * 54 * This software consists of voluntary contributions made by many 55 * individuals on behalf of the Apache Software Foundation. For more 56 * information on the Apache Software Foundation, please see 57 * <http://www.apache.org/>. 58 * 59 * Portions of this software are based upon public domain software 60 * originally written at the National Center for Supercomputing Applications, 61 * University of Illinois, Urbana-Champaign. 62 */ 63 64 #ifndef APACHE_HTTP_PROTOCOL_H 65 #define APACHE_HTTP_PROTOCOL_H 66 67 #ifdef __cplusplus 68 extern "C" { 69 #endif 70 71 /* 72 * Prototypes for routines which either talk directly back to the user, 73 * or control the ones that eventually do. 74 */ 75 76 /* Read a request and fill in the fields. */ 77 78 API_EXPORT(request_rec *) ap_read_request(conn_rec *c); 79 80 /* Send a single HTTP header field */ 81 82 API_EXPORT_NONSTD(int) ap_send_header_field(request_rec *r, 83 const char *fieldname, const char *fieldval); 84 85 /* Send the minimal part of an HTTP response header... but modules should be 86 * very careful about using this, and should prefer ap_send_http_header(). 87 * Much of the HTTP/1.1 implementation correctness depends on code in 88 * ap_send_http_header(). 89 */ 90 API_EXPORT(void) ap_basic_http_header(request_rec *r); 91 92 /* Send the Status-Line and header fields for HTTP response */ 93 94 API_EXPORT(void) ap_send_http_header(request_rec *l); 95 96 /* Send the response to special method requests */ 97 98 API_EXPORT(int) ap_send_http_trace(request_rec *r); 99 API_EXPORT(int) ap_send_http_options(request_rec *r); 100 101 /* Finish up stuff after a request */ 102 103 API_EXPORT(void) ap_finalize_request_protocol(request_rec *r); 104 105 /* Send error back to client... last arg indicates error status in case 106 * we get an error in the process of trying to deal with an ErrorDocument 107 * to handle some other error. In that case, we print the default report 108 * for the first thing that went wrong, and more briefly report on the 109 * problem with the ErrorDocument. 110 */ 111 112 API_EXPORT(void) ap_send_error_response(request_rec *r, int recursive_error); 113 114 /* Set last modified header line from the lastmod date of the associated file. 115 * Also, set content length. 116 * 117 * May return an error status, typically USE_LOCAL_COPY (that when the 118 * permit_cache argument is set to one). 119 */ 120 121 API_EXPORT(int) ap_set_content_length(request_rec *r, long length); 122 API_EXPORT(int) ap_set_keepalive(request_rec *r); 123 API_EXPORT(time_t) ap_rationalize_mtime(request_rec *r, time_t mtime); 124 API_EXPORT(char *) ap_make_etag(request_rec *r, int force_weak); 125 API_EXPORT(void) ap_set_etag(request_rec *r); 126 API_EXPORT(void) ap_set_last_modified(request_rec *r); 127 API_EXPORT(int) ap_meets_conditions(request_rec *r); 128 129 /* Other ways to send stuff at the client. All of these keep track 130 * of bytes_sent automatically. This indirection is intended to make 131 * it a little more painless to slide things like HTTP-NG packetization 132 * underneath the main body of the code later. In the meantime, it lets 133 * us centralize a bit of accounting (bytes_sent). 134 * 135 * These also return the number of bytes written by the call. 136 * They should only be called with a timeout registered, for obvious reaasons. 137 * (Ditto the send_header stuff). 138 */ 139 140 API_EXPORT(long) ap_send_fd(FILE *f, request_rec *r); 141 API_EXPORT(long) ap_send_fd_length(FILE *f, request_rec *r, long length); 142 143 API_EXPORT(long) ap_send_fb(BUFF *f, request_rec *r); 144 API_EXPORT(long) ap_send_fb_length(BUFF *f, request_rec *r, long length); 145 146 API_EXPORT(size_t) ap_send_mmap(void *mm, request_rec *r, size_t offset, 147 size_t length); 148 149 /* Hmmm... could macrofy these for now, and maybe forever, though the 150 * definitions of the macros would get a whole lot hairier. 151 */ 152 153 API_EXPORT(int) ap_rputc(int c, request_rec *r); 154 API_EXPORT(int) ap_rputs(const char *str, request_rec *r); 155 API_EXPORT(int) ap_rwrite(const void *buf, int nbyte, request_rec *r); 156 API_EXPORT_NONSTD(int) ap_rvputs(request_rec *r,...); 157 API_EXPORT(int) ap_vrprintf(request_rec *r, const char *fmt, va_list vlist); 158 API_EXPORT_NONSTD(int) ap_rprintf(request_rec *r, const char *fmt,...) 159 __attribute__((__format__(__printf__, 2, 3))); 160 API_EXPORT(int) ap_rflush(request_rec *r); 161 162 /* 163 * Index used in custom_responses array for a specific error code 164 * (only use outside protocol.c is in getting them configured). 165 */ 166 167 API_EXPORT(int) ap_index_of_response(int status); 168 169 /* Reading a block of data from the client connection (e.g., POST arg) */ 170 171 API_EXPORT(int) ap_setup_client_block(request_rec *r, int read_policy); 172 API_EXPORT(int) ap_should_client_block(request_rec *r); 173 API_EXPORT(long) ap_get_client_block(request_rec *r, char *buffer, int bufsiz); 174 API_EXPORT(int) ap_discard_request_body(request_rec *r); 175 176 /* Sending a byterange */ 177 178 API_EXPORT(int) ap_set_byterange(request_rec *r); 179 API_EXPORT(int) ap_each_byterange(request_rec *r, long *offset, long *length); 180 181 /* Support for the Basic authentication protocol. Note that there's 182 * nothing that prevents these from being in mod_auth.c, except that other 183 * modules which wanted to provide their own variants on finding users and 184 * passwords for Basic auth (a fairly common request) would then require 185 * mod_auth to be loaded or they wouldn't work. 186 * 187 * get_basic_auth_pw returns 0 (OK) if it set the 'pw' argument (and assured 188 * a correct value in r->connection->user); otherwise it returns an error 189 * code, either SERVER_ERROR if things are really confused, AUTH_REQUIRED 190 * if no authentication at all seemed to be in use, or DECLINED if there 191 * was authentication but it wasn't Basic (in which case, the caller should 192 * presumably decline as well). 193 * 194 * note_basic_auth_failure arranges for the right stuff to be scribbled on 195 * the HTTP return so that the client knows how to authenticate itself the 196 * next time. As does note_digest_auth_failure for Digest auth. 197 * 198 * note_auth_failure does the same thing, but will call the correct one 199 * based on the authentication type in use. 200 * 201 */ 202 203 API_EXPORT(void) ap_note_auth_failure(request_rec *r); 204 API_EXPORT(void) ap_note_basic_auth_failure(request_rec *r); 205 API_EXPORT(void) ap_note_digest_auth_failure(request_rec *r); 206 API_EXPORT(int) ap_get_basic_auth_pw(request_rec *r, const char **pw); 207 208 /* 209 * Setting up the protocol fields for subsidiary requests... 210 * Also, a wrapup function to keep the internal accounting straight. 211 */ 212 213 API_EXPORT(void) ap_set_sub_req_protocol(request_rec *rnew, 214 const request_rec *r); 215 API_EXPORT(void) ap_finalize_sub_req_protocol(request_rec *sub_r); 216 217 /* This is also useful for putting sub_reqs and internal_redirects together */ 218 219 CORE_EXPORT(void) ap_parse_uri(request_rec *r, const char *uri); 220 221 /* Get the method number associated with the given string, assumed to 222 * contain an HTTP method. Returns M_INVALID if not recognized. 223 */ 224 API_EXPORT(int) ap_method_number_of(const char *method); 225 226 API_EXPORT(int) ap_getline(char *s, int n, BUFF *in, int fold); 227 228 API_EXPORT(long) ap_get_chunk_size(char *b); 229 230 API_EXPORT(void) ap_init_etag(pool *pconf); 231 232 #ifdef __cplusplus 233 } 234 #endif 235 236 #endif /* !APACHE_HTTP_PROTOCOL_H */ 237