Return-Path: Delivered-To: apmail-apache-cvs-archive@apache.org Received: (qmail 77418 invoked by uid 500); 5 Aug 2000 19:20:24 -0000 Mailing-List: contact apache-cvs-help@apache.org; run by ezmlm Precedence: bulk X-No-Archive: yes Reply-To: new-httpd@apache.org list-help: list-unsubscribe: list-post: Delivered-To: mailing list apache-cvs@apache.org Received: (qmail 77407 invoked by uid 500); 5 Aug 2000 19:20:24 -0000 Delivered-To: apmail-apache-2.0-cvs@apache.org Date: 5 Aug 2000 19:20:23 -0000 Message-ID: <20000805192023.77403.qmail@locus.apache.org> From: rbb@locus.apache.org To: apache-2.0-cvs@apache.org Subject: cvs commit: apache-2.0/src/include http_protocol.h rbb 00/08/05 12:20:23 Modified: src/include http_protocol.h Log: Update http_protocol.h to use ScanDoc. Revision Changes Path 1.21 +318 -49 apache-2.0/src/include/http_protocol.h Index: http_protocol.h =================================================================== RCS file: /home/cvs/apache-2.0/src/include/http_protocol.h,v retrieving revision 1.20 retrieving revision 1.21 diff -u -r1.20 -r1.21 --- http_protocol.h 2000/08/02 05:25:28 1.20 +++ http_protocol.h 2000/08/05 19:20:23 1.21 @@ -67,29 +67,47 @@ extern "C" { #endif +/** + * @package HTTP protocol handling + */ + /* * Prototypes for routines which either talk directly back to the user, * or control the ones that eventually do. */ -/* Read a request and fill in the fields. */ - +/** + * Read a request and fill in the fields. + * @param c The current connection + * @return The new request_rec + */ request_rec *ap_read_request(conn_rec *c); - -/* Send a single HTTP header field */ +/** + * Send a single HTTP header field + * @param r The current request + * @param fieldname The Header field to send + * @param fieldval The value of the header + * @deffunc int ap_send_header_field(request_rec *r, const char *fieldname, const char *fieldval) + */ API_EXPORT_NONSTD(int) ap_send_header_field(request_rec *r, const char *fieldname, const char *fieldval); -/* Send the minimal part of an HTTP response header... but modules should be - * very careful about using this, and should prefer ap_send_http_header(). - * Much of the HTTP/1.1 implementation correctness depends on code in - * ap_send_http_header(). +/** + * Send the minimal part of an HTTP response header. + * @param r The current request + * @warning Modules should be very careful about using this, and should + * prefer ap_send_http_header(). Much of the HTTP/1.1 implementation + * correctness depends on code in ap_send_http_header(). + * @deffunc void ap_basic_http_header(request_rec *r) */ API_EXPORT(void) ap_basic_http_header(request_rec *r); - -/* Send the Status-Line and header fields for HTTP response */ +/** + * Send the Status-Line and header fields for HTTP response + * @param l The current request + * @deffunc void ap_send_http_header(request_rec *l) + */ API_EXPORT(void) ap_send_http_header(request_rec *l); /* Send the response to special method requests */ @@ -97,17 +115,24 @@ API_EXPORT(int) ap_send_http_trace(request_rec *r); int ap_send_http_options(request_rec *r); -/* Finish up stuff after a request */ - +/** + * Called at completion of sending the response. It sends the terminating + * protocol information. + * @param r The current request + * @deffunc void ap_finalize_request_protocol(request_rec *r) + */ API_EXPORT(void) ap_finalize_request_protocol(request_rec *r); -/* Send error back to client... last arg indicates error status in case - * we get an error in the process of trying to deal with an ErrorDocument - * to handle some other error. In that case, we print the default report - * for the first thing that went wrong, and more briefly report on the - * problem with the ErrorDocument. +/** + * Send error back to client. + * @param r The current request + * @param recursive_error last arg indicates error status in case we get + * an error in the process of trying to deal with an ErrorDocument + * to handle some other error. In that case, we print the default + * report for the first thing that went wrong, and more briefly report + * on the problem with the ErrorDocument. + * @deffunc void ap_send_error_response(request_rec *r, int recursive_error) */ - API_EXPORT(void) ap_send_error_response(request_rec *r, int recursive_error); /* Set last modified header line from the lastmod date of the associated file. @@ -117,12 +142,60 @@ * permit_cache argument is set to one). */ +/** + * Set the content length for this request + * @param r The current request + * @param length The new content length + * @return Always 0, can be safely ignored + * @deffunc int ap_set_content_length(request_rec *r, long length) + */ API_EXPORT(int) ap_set_content_length(request_rec *r, long length); +/** + * Set the keepalive status for this request + * @param r The current request + * @return 1 if keepalive can be set, 0 otherwise + * @deffunc int ap_set_keepalive(request_rec *r) + */ API_EXPORT(int) ap_set_keepalive(request_rec *r); +/** + * Return the latest rational time from a request/mtime pair. Mtime is + * returned unless it's in the future, in which case we return the current time. + * @param r The current request + * @param mtime The last modified time + * @return the latest rational time. + * @deffunc apr_time_t ap_rationalize_mtime(request_rec *r, apr_time_t mtime) + */ API_EXPORT(apr_time_t) ap_rationalize_mtime(request_rec *r, apr_time_t mtime); +/** + * Construct an entity tag from the resource information. If it's a real + * file, build in some of the file characteristics. + * @param r The current request + * @param force_weak Force the entity tag to be weak - it could be modified + * again in as short an interval. + * @return The entity tag + * @deffunc char *ap_make_etag(request_rec *r, int force_weak) + */ API_EXPORT(char *) ap_make_etag(request_rec *r, int force_weak); +/** + * Set the E-tag outgoing header + * @param The current request + * @deffunc void ap_set_etag(request_rec *r) + */ API_EXPORT(void) ap_set_etag(request_rec *r); +/** + * Set the last modified time for the file being sent + * @param r The current request + * @deffunc void ap_set_last_modified(request_rec *r) + */ API_EXPORT(void) ap_set_last_modified(request_rec *r); +/** + * Implements condition GET rules for HTTP/1.1 specification. This function + * inspects the client headers and determines if the response fulfills + * the requirements specified. + * @param r The current request + * @return 1 if the response fulfills the condition GET rules, 0 otherwise + * @deffunc int ap_meets_conditions(request_rec *r) + */ API_EXPORT(int) ap_meets_conditions(request_rec *r); /* Other ways to send stuff at the client. All of these keep track @@ -136,12 +209,44 @@ * (Ditto the send_header stuff). */ +/** + * Send an entire file to the client, using sendfile if supported by the + * current platform + * @param fd The file to send. + * @param r The current request + * @param offset Offset into the file to start sending. + * @param length Amount of data to send + * @param nbytes Amount of data actually sent + * @deffunc apr_status_t ap_send_fd(apr_file_t *fd, request_rec *r, apr_off_t offset, apr_size_t length, apr_size_t *nbytes); + */ API_EXPORT(apr_status_t) ap_send_fd(apr_file_t *fd, request_rec *r, apr_off_t offset, apr_size_t length, apr_size_t *nbytes); - +/** + * Send the body of a response to the client + * @param f The BUFF structure associated with a client + * @param r The current request + * @return The number of bytes sent + * @deffunc long ap_send_fb(BUFF *f, request_rec *r) + */ API_EXPORT(long) ap_send_fb(BUFF *f, request_rec *r); +/** + * Send a specified number of bytes from the body of the response to the client + * @param f the BUFF structure associated with a client + * @param r The current request + * @param length The number of bytes to send + * @return The number of bytes sent + * @deffunc long ap_send_fb_length(BUFF *f, request_rec *r, long length) + */ API_EXPORT(long) ap_send_fb_length(BUFF *f, request_rec *r, long length); - +/** + * Send an MMAP'ed file to the client + * @param mm The MMAP'ed file to send + * @param r The current request + * @param offset The offset into the MMAP to start sending + * @param length The amount of data to send + * @return The number of bytes sent + * @deffunc size_t ap_send_mmap(apr_mmap_t *mm, request_rec *r, size_t offset, size_t length) + */ API_EXPORT(size_t) ap_send_mmap(apr_mmap_t *mm, request_rec *r, size_t offset, size_t length); @@ -149,67 +254,190 @@ * definitions of the macros would get a whole lot hairier. */ +/** + * Output one character for this request + * @param c the character to output + * @param r the current request + * @return The number of bytes sent + * @deffunc int ap_rputc(int c, request_rec *r) + */ API_EXPORT(int) ap_rputc(int c, request_rec *r); +/** + * Output a string for the current request + * @param str The string to output + * @param r The current request + * @return The number of bytes sent + * @deffunc int ap_rputs(const char *str, request_rec *r) + */ API_EXPORT(int) ap_rputs(const char *str, request_rec *r); +/** + * Write a buffer for the current request + * @param buf The buffer to write + * @param nbyte The number of bytes to send from the buffer + * @param r The current request + * @return The number of bytes sent + * @deffunc int ap_rwrite(const void *buf, int nbyte, request_rec *r) + */ API_EXPORT(int) ap_rwrite(const void *buf, int nbyte, request_rec *r); +/** + * Write an unspecified number of strings to the request + * @param r The current request + * @param ... The strings to write + * @return The number of bytes sent + * @deffunc int ap_rvputs(request_rec *r, ...) + */ API_EXPORT_NONSTD(int) ap_rvputs(request_rec *r,...); +/** + * Output data to the client in a printf format + * @param r The current request + * @param fmt The format string + * @param vlist The arguments to use to fill out the format string + * @return The number of bytes sent + * @deffunc int ap_vrprintf(request_rec *r, const char *fmt, va_list vlist) + */ API_EXPORT(int) ap_vrprintf(request_rec *r, const char *fmt, va_list vlist); +/** + * Output data to the client in a printf format + * @param r The current request + * @param fmt The format string + * @param ... The arguments to use to fill out the format string + * @return The number of bytes sent + * @deffunc int ap_rprintf(request_rec *r, const char *fmt, ...) + */ API_EXPORT_NONSTD(int) ap_rprintf(request_rec *r, const char *fmt,...) __attribute__((format(printf,2,3))); +/** + * Flush all of the data for the current request to the client + * @param r The current request + * @return The number of bytes sent + * @deffunc int ap_rflush(request_rec *r) + */ API_EXPORT(int) ap_rflush(request_rec *r); -/* +/** * Index used in custom_responses array for a specific error code * (only use outside protocol.c is in getting them configured). + * @param status HTTP status code + * @return The index of the response + * @deffunc int ap_index_of_response(int status) */ - API_EXPORT(int) ap_index_of_response(int status); -/* +/** * Return the Status-Line for a given status code (excluding the * HTTP-Version field). If an invalid or unknown status code is * passed, "500 Internal Server Error" will be returned. + * @param status The HTTP status code + * @return The Status-Line + * @deffunc const char *ap_get_status_line(int status) */ API_EXPORT(const char *) ap_get_status_line(int status); /* Reading a block of data from the client connection (e.g., POST arg) */ +/** + * Setup the client to allow Apache to read the request body. + * @param r The current request + * @param read_policy How the server should interpret a chunked + * transfer-encoding. One of: 
  + *    REQUEST_NO_BODY          Send 413 error if message has any body
  + *    REQUEST_CHUNKED_ERROR    Send 411 error if body without Content-Length
  + *    REQUEST_CHUNKED_DECHUNK  If chunked, remove the chunks for me.
  + *    REQUEST_CHUNKED_PASS     Pass the chunks to me without removal.
  + *
+ * @return either OK or an error code + * @deffunc int ap_setup_cleint_block(request_rec *r, int read_policy) + */ API_EXPORT(int) ap_setup_client_block(request_rec *r, int read_policy); +/** + * Determine if the client has sent any data. This also sends a + * 100 Continue resposne to HTTP/1.1 clients, so modules should not be called + * until the module is ready to read content. + * @warning Never call this function more than once. + * @param r The current request + * @return 0 if there is no message to read, 1 otherwise + * @deffunc int ap_should_client_block(request_rec *r) + */ API_EXPORT(int) ap_should_client_block(request_rec *r); +/** + * Call this in a loop. It will put data into a buffer and return the length + * of the input block + * @param r The current request + * @param buffer The buffer in which to store the data + * @param bufsiz The size of the buffer + * @return Number of bytes inserted into the buffer. When done reading, 0 + * if EOF, or -1 if there was an error + * @deffunc long ap_get_client_block(request_rec *r, char *buffer, int bufsiz) + */ API_EXPORT(long) ap_get_client_block(request_rec *r, char *buffer, int bufsiz); +/** + * In HTTP/1.1, any method can have a body. However, most GET handlers + * wouldn't know what to do with a request body if they received one. + * This helper routine tests for and reads any message body in the request, + * simply discarding whatever it receives. We need to do this because + * failing to read the request body would cause it to be interpreted + * as the next request on a persistent connection. + * @param r The current request + * @return error status if request is malformed, OK otherwise + * @deffunc int ap_discard_request_body(request_rec *r) + */ API_EXPORT(int) ap_discard_request_body(request_rec *r); /* Sending a byterange */ +/** + * Setup the request to send Byte Range requests + * @param r the current request + * @return 1 if request was setup for byte range requests, 0 otherwise + * @deffunc int ap_set_byterange(request_rec *r) + */ API_EXPORT(int) ap_set_byterange(request_rec *r); +/** + * Send one byte range chunk for a byte range request + * @param r The current request + * @param offset Set to the position it should be after the chunk is sent + * @param length Set to the length in should be after the chunk is sent + * @deffunc int ap_each_byterange(request_rec *r, apr_off_t *offset, apr_size_t *length) + */ API_EXPORT(int) ap_each_byterange(request_rec *r, apr_off_t *offset, apr_size_t *length); - -/* Support for the Basic authentication protocol. Note that there's - * nothing that prevents these from being in mod_auth.c, except that other - * modules which wanted to provide their own variants on finding users and - * passwords for Basic auth (a fairly common request) would then require - * mod_auth to be loaded or they wouldn't work. - * - * get_basic_auth_pw returns 0 (OK) if it set the 'pw' argument (and assured - * a correct value in r->connection->user); otherwise it returns an error - * code, either HTTP_INTERNAL_SERVER_ERROR if things are really confused, - * HTTP_UNAUTHORIZED if no authentication at all seemed to be in use, or - * DECLINED if there was authentication but it wasn't Basic (in which case, - * the caller should presumably decline as well). - * - * note_basic_auth_failure arranges for the right stuff to be scribbled on - * the HTTP return so that the client knows how to authenticate itself the - * next time. As does note_digest_auth_failure for Digest auth. - * - * note_auth_failure does the same thing, but will call the correct one - * based on the authentication type in use. - * - */ - +/** + * Setup the output headers so that the client knows how to authenticate + * itself the next time, if an authentication request failed. This function + * works for both basic and digest authentication + * @param r The current request + * @deffunc void ap_note_auth_failure(request_rec *r) + */ API_EXPORT(void) ap_note_auth_failure(request_rec *r); +/** + * Setup the output headers so that the client knows how to authenticate + * itself the next time, if an authentication request failed. This function + * works only for basic authentication + * @param r The current request + * @deffunc void ap_note_basic_auth_failure(request_rec *r) + */ API_EXPORT(void) ap_note_basic_auth_failure(request_rec *r); +/** + * Setup the output headers so that the client knows how to authenticate + * itself the next time, if an authentication request failed. This function + * works only for digest authentication + * @param r The current request + * @deffunc void ap_note_digest_auth_failure(request_rec *r) + */ API_EXPORT(void) ap_note_digest_auth_failure(request_rec *r); +/** + * Get the password from the request headers + * @param r The current request + * @param pw The password as set in the headers + * @return 0 (OK) if it set the 'pw' argument (and assured + * a correct value in r->connection->user); otherwise it returns + * an error code, either HTTP_INTERNAL_SERVER_ERROR if things are + * really confused, HTTP_UNAUTHORIZED if no authentication at all + * seemed to be in use, or DECLINED if there was authentication but + * it wasn't Basic (in which case, the caller should presumably + * decline as well). + * @deffunc int ap_get_basic_auth_pw(request_rec *r, const char **pw) + */ API_EXPORT(int) ap_get_basic_auth_pw(request_rec *r, const char **pw); /* @@ -220,12 +448,25 @@ void ap_set_sub_req_protocol(request_rec *rnew, const request_rec *r); void ap_finalize_sub_req_protocol(request_rec *sub_r); -/* This is also useful for putting sub_reqs and internal_redirects together */ - +/** + * parse_uri: break apart the uri + * @warning Side Effects: 
  + *    - sets r->args to rest after '?' (or NULL if no '?')
  + *    - sets r->uri to request uri (without r->args part)
  + *    - sets r->hostname (if not set already) from request (scheme://host:port)
  + *
+ * @param r The current request + * @param uri The uri to break apart + * @deffunc void ap_parse_uri(request_rec *r, const char *uri) + */ CORE_EXPORT(void) ap_parse_uri(request_rec *r, const char *uri); -/* Get the method number associated with the given string, assumed to +/** + * Get the method number associated with the given string, assumed to * contain an HTTP method. Returns M_INVALID if not recognized. + * @param method A string containing a valid HTTP method + * @return The method number + * @deffunc int ap_method_number_of(const char *method) */ API_EXPORT(int) ap_method_number_of(const char *method); @@ -234,9 +475,37 @@ * post_read_request --- run right after read_request or internal_redirect, * and not run during any subrequests. */ +/** + * This hook allows modules to affect the request immediately after the request + * has been read, and before any other phases have been processes. This allows + * modules to make decisions based upon the input header fields + * @param r The current request + * @return OK or DECLINED + * @deffunc ap_run_post_read_request(request_rec *r) + */ AP_DECLARE_HOOK(int,post_read_request,(request_rec *)) +/** + * This hook allows modules to perform any module-specific logging activities + * over and above the normal server things. + * @param r The current request + * @return OK, DECLINED, or HTTP_... + * @deffunc int ap_run_log_transaction(request_rec *r) + */ AP_DECLARE_HOOK(int,log_transaction,(request_rec *)) +/** + * This hook allows modules to retrieve the http method from a request. This + * allows Apache modules to easily extend the methods that Apache understands + * @param r The current request + * @return The http method from the request + * @deffunc const char *ap_run_http_method(const request_rec *r) + */ AP_DECLARE_HOOK(const char *,http_method,(const request_rec *)) +/** + * Return the default port from the current request + * @param r The current request + * @return The current port + * @deffunc unsigned short ap_run_default_port(const request_rec *r) + */ AP_DECLARE_HOOK(unsigned short,default_port,(const request_rec *)) #ifdef __cplusplus