From 1da7450f13aa95fc3034ad0c9df1510f917b1a01 Mon Sep 17 00:00:00 2001 From: Ryan Bloom Date: Thu, 10 Aug 2000 06:00:17 +0000 Subject: [PATCH] Begin to document httpd.h with ScanDoc git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@86040 13f79535-47bb-0310-9956-ffa450edef68 --- include/httpd.h | 656 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 509 insertions(+), 147 deletions(-) diff --git a/include/httpd.h b/include/httpd.h index 7d443b70ea..79a810e166 100644 --- a/include/httpd.h +++ b/include/httpd.h @@ -71,6 +71,9 @@ extern "C" { * make this file smaller */ +/** + * @package HTTP Daemon routines + */ /* Headers in which EVERYONE has an interest... */ #include "ap_config.h" @@ -528,14 +531,18 @@ API_EXPORT(const char *) ap_get_server_built(void); * pointer is, in fact, zero. */ -/* This represents the result of calling htaccess; these are cached for +/** + * This represents the result of calling htaccess; these are cached for * each request. */ struct htaccess_result { - const char *dir; /* the directory to which this applies */ - int override; /* the overrides allowed for the .htaccess file */ - void *htaccess; /* the configuration directives */ -/* the next one, or NULL if no more; N.B. never change this */ + /** the directory to which this applies */ + const char *dir; + /** the overrides allowed for the .htaccess file */ + int override; + /** the configuration directives */ + void *htaccess; + /** the next one, or NULL if no more; N.B. never change this */ const struct htaccess_result *next; }; @@ -556,103 +563,140 @@ typedef struct request_rec request_rec; #ifdef APACHE_XLATE #include "apr_xlate.h" +/** structure to aid charset translate between machine and network */ struct ap_rr_xlate { /* contents are experimental! expect it to change! */ + /** translation handle to use when going to the network */ apr_xlate_t *to_net; - int to_net_sb; /* whether or not write translation is single-byte-only */ + /** whether or not write translation is single-byte-only */ + int to_net_sb; + /** translation handle to use when coming from the network */ apr_xlate_t *from_net; }; #endif /*APACHE_XLATE*/ +/** A structure that represents one process */ struct process_rec { - apr_pool_t *pool; /* Global pool. Please try to cleared on _all_ exits */ - apr_pool_t *pconf; /* aka configuration pool, cleared on restarts */ + /** Global pool. Please try to cleared on _all_ exits */ + apr_pool_t *pool; + /** aka configuration pool, cleared on restarts */ + apr_pool_t *pconf; + /** How many command line arguments were pass to the program */ int argc; + /** The command line arguments */ char *const *argv; + /** The program name used to execute the program */ const char *short_name; }; +/** A structure that represents the current request */ struct request_rec { - + /** The pool associated with the request */ apr_pool_t *pool; + /** The connection over which this connection has been read */ conn_rec *connection; + /** The virtual host this request is for */ server_rec *server; - request_rec *next; /* If we wind up getting redirected, - * pointer to the request we redirected to. - */ - request_rec *prev; /* If this is an internal redirect, - * pointer to where we redirected *from*. - */ + /** If we wind up getting redirected, pointer to the request we + * redirected to. */ + request_rec *next; + /** If this is an internal redirect, pointer to where we redirected + * *from*. */ + request_rec *prev; - request_rec *main; /* If this is a sub_request (see request.h) - * pointer back to the main request. - */ + /** If this is a sub_request (see request.h) pointer back to the + * main request. */ + request_rec *main; /* Info about the request itself... we begin with stuff that only * protocol.c should ever touch... */ - char *the_request; /* First line of request, so we can log it */ - int assbackwards; /* HTTP/0.9, "simple" request */ - int proxyreq; /* A proxy request (calculated during - * post_read_request or translate_name) */ - int header_only; /* HEAD request, as opposed to GET */ - char *protocol; /* Protocol, as given to us, or HTTP/0.9 */ - int proto_num; /* Number version of protocol; 1.1 = 1001 */ - const char *hostname; /* Host, as set by full URI or Host: */ - - apr_time_t request_time; /* When the request started */ - - const char *status_line; /* Status line, if set by script */ - int status; /* In any case */ + /** First line of request, so we can log it */ + char *the_request; + /** HTTP/0.9, "simple" request */ + int assbackwards; + /** A proxy request (calculated during post_read_request/translate_name) */ + int proxyreq; + /** HEAD request, as opposed to GET */ + int header_only; + /** Protocol, as given to us, or HTTP/0.9 */ + char *protocol; + /** Number version of protocol; 1.1 = 1001 */ + int proto_num; + /** Host, as set by full URI or Host: */ + const char *hostname; + + /** When the request started */ + apr_time_t request_time; + + /** Status line, if set by script */ + const char *status_line; + /** In any case */ + int status; /* Request method, two ways; also, protocol, etc.. Outside of protocol.c, * look, but don't touch. */ - const char *method; /* GET, HEAD, POST, etc. */ - int method_number; /* M_GET, M_POST, etc. */ - - /* - allowed is a bitvector of the allowed methods. - - A handler must ensure that the request method is one that - it is capable of handling. Generally modules should DECLINE - any request methods they do not handle. Prior to aborting the - handler like this the handler should set r->allowed to the list - of methods that it is willing to handle. This bitvector is used - to construct the "Allow:" header required for OPTIONS requests, - and HTTP_METHOD_NOT_ALLOWED and HTTP_NOT_IMPLEMENTED status codes. - - Since the default_handler deals with OPTIONS, all modules can - usually decline to deal with OPTIONS. TRACE is always allowed, - modules don't need to set it explicitly. - - Since the default_handler will always handle a GET, a - module which does *not* implement GET should probably return - HTTP_METHOD_NOT_ALLOWED. Unfortunately this means that a Script GET - handler can't be installed by mod_actions. - */ + /** GET, HEAD, POST, etc. */ + const char *method; + /** M_GET, M_POST, etc. */ + int method_number; + + /** 
+     *  allowed is a bitvector of the allowed methods.
+     *
+     *  A handler must ensure that the request method is one that
+     *  it is capable of handling.  Generally modules should DECLINE
+     *  any request methods they do not handle.  Prior to aborting the
+     *  handler like this the handler should set r->allowed to the list
+     *  of methods that it is willing to handle.  This bitvector is used
+     *  to construct the "Allow:" header required for OPTIONS requests,
+     *  and HTTP_METHOD_NOT_ALLOWED and HTTP_NOT_IMPLEMENTED status codes.
+     *
+     *  Since the default_handler deals with OPTIONS, all modules can
+     *  usually decline to deal with OPTIONS.  TRACE is always allowed,
+     *  modules don't need to set it explicitly.
+     *
+     *  Since the default_handler will always handle a GET, a
+     *  module which does *not* implement GET should probably return
+     *  HTTP_METHOD_NOT_ALLOWED.  Unfortunately this means that a Script GET
+     *  handler can't be installed by mod_actions.
+ */ int allowed; /* Allowed methods - for 405, OPTIONS, etc */ - int sent_bodyct; /* byte count in stream is for body */ - long bytes_sent; /* body byte count, for easy access */ - apr_time_t mtime; /* Time the resource was last modified */ + /** byte count in stream is for body */ + int sent_bodyct; + /** body byte count, for easy access */ + long bytes_sent; + /** Time the resource was last modified */ + apr_time_t mtime; /* HTTP/1.1 connection-level features */ - int chunked; /* sending chunked transfer-coding */ - int byterange; /* number of byte ranges */ - char *boundary; /* multipart/byteranges boundary */ - const char *range; /* The Range: header */ - long clength; /* The "real" content length */ - - long remaining; /* bytes left to read */ - long read_length; /* bytes that have been read */ - int read_body; /* how the request body should be read */ - int read_chunked; /* reading chunked transfer-coding */ - unsigned expecting_100; /* is client waiting for a 100 response? */ + /** sending chunked transfer-coding */ + int chunked; + /** number of byte ranges */ + int byterange; + /** multipart/byteranges boundary */ + char *boundary; + /** The Range: header */ + const char *range; + /** The "real" content length */ + long clength; + + /** bytes left to read */ + long remaining; + /** bytes that have been read */ + long read_length; + /** how the request body should be read */ + int read_body; + /** reading chunked transfer-coding */ + int read_chunked; + /** is client waiting for a 100 response? */ + unsigned expecting_100; /* MIME header environments, in and out. Also, an array containing * environment variables to be passed to subprocesses, so people can @@ -666,65 +710,93 @@ struct request_rec { * other set purpose in mind... */ + /** MIME header environment from the request */ apr_table_t *headers_in; + /** MIME header environment for the response */ apr_table_t *headers_out; + /** MIME header environment for the response, printed even on errors and + * persist across internal redirects */ apr_table_t *err_headers_out; + /** Array of environment variables to be used for sub processes */ apr_table_t *subprocess_env; + /** Notes from one module to another */ apr_table_t *notes; /* content_type, handler, content_encoding, content_language, and all * content_languages MUST be lowercased strings. They may be pointers * to static strings; they should not be modified in place. */ + /** The content-type for the current request */ const char *content_type; /* Break these out --- we dispatch on 'em */ + /** The handler string that we use to call a handler function */ const char *handler; /* What we *really* dispatch on */ + /** How to encode the data */ const char *content_encoding; - const char *content_language; /* for back-compat. only -- do not use */ - apr_array_header_t *content_languages; /* array of (char*) */ + /** for back-compat. only -- do not use */ + const char *content_language; + /** array of (char*) representing the content languages */ + apr_array_header_t *content_languages; - char *vlist_validator; /* variant list validator (if negotiated) */ + /** variant list validator (if negotiated) */ + char *vlist_validator; - char *user; /* If an authentication check was made, - * this gets set to the user name. - */ - char *ap_auth_type; /* Ditto. */ + /** If an authentication check was made, this gets set to the user name. */ + char *user; + /** If an authentication check was made, this gets set to the auth type. */ + char *ap_auth_type; + /** This response is non-cache-able */ int no_cache; + /** There is no local copy of this response */ int no_local_copy; /* What object is being requested (either directly, or via include * or content-negotiation mapping). */ - char *unparsed_uri; /* the uri without any parsing performed */ - char *uri; /* the path portion of the URI */ + /** the uri without any parsing performed */ + char *unparsed_uri; + /** the path portion of the URI */ + char *uri; + /** The filename on disk that this response corresponds to */ char *filename; + /** The path_info for this request if there is any. */ char *path_info; - char *args; /* QUERY_ARGS, if any */ - apr_finfo_t finfo; /* ST_MODE set to zero if no such file */ - uri_components parsed_uri; /* components of uri, dismantled */ + /** QUERY_ARGS, if any */ + char *args; + /** ST_MODE set to zero if no such file */ + apr_finfo_t finfo; + /** components of uri, dismantled */ + uri_components parsed_uri; /* Various other config info which may change with .htaccess files * These are config vectors, with one void* pointer for each module * (the thing pointed to being the module's business). */ - void *per_dir_config; /* Options set in config files, etc. */ - void *request_config; /* Notes on *this* request */ + /** Options set in config files, etc. */ + void *per_dir_config; + /** Notes on *this* request */ + void *request_config; -/* +/** * a linked list of the configuration directives in the .htaccess files * accessed by this request. * N.B. always add to the head of the list, _never_ to the end. * that way, a sub request's list can (temporarily) point to a parent's list + * @defvar const htaccess_result *htaccess */ const struct htaccess_result *htaccess; #ifdef APACHE_XLATE + /** The translation headers for dealing with this request + * @defvar ap_rr_xlate *rrx */ struct ap_rr_xlate *rrx; #endif /*APACHE_XLATE*/ + /** A list of filters to be used for this request + * @defvar ap_filter_t *filters */ struct ap_filter_t *filters; /* Things placed at the end of the record to avoid breaking binary @@ -735,49 +807,61 @@ struct request_rec { }; -/* Things which are per connection - */ - +/** Structure to store things which are per connection */ struct conn_rec { - + /** Pool associated with this connection */ apr_pool_t *pool; - server_rec *base_server; /* Physical vhost this conn come in on */ - void *vhost_lookup_data; /* used by http_vhost.c */ + /** Physical vhost this conn come in on */ + server_rec *base_server; + /** used by http_vhost.c */ + void *vhost_lookup_data; /* Information about the connection itself */ - BUFF *client; /* Connection to the guy */ + /** Connection to the client */ + BUFF *client; /* Who is the client? */ - struct sockaddr_in local_addr; /* local address */ - struct sockaddr_in remote_addr; /* remote address */ - char *remote_ip; /* Client's IP address */ - char *remote_host; /* Client's DNS name, if known. - * NULL if DNS hasn't been checked, - * "" if it has and no address was found. - * N.B. Only access this though - * get_remote_host() */ - char *remote_logname; /* Only ever set if doing rfc1413 lookups. - * N.B. Only access this through - * get_remote_logname() */ - - unsigned aborted:1; /* Are we still talking? */ - signed int keepalive:2; /* Are we using HTTP Keep-Alive? - * -1 fatal error, 0 undecided, 1 yes */ - unsigned keptalive:1; /* Did we use HTTP Keep-Alive? */ - signed int double_reverse:2;/* have we done double-reverse DNS? - * -1 yes/failure, 0 not yet, 1 yes/success */ - int keepalives; /* How many times have we used it? */ - char *local_ip; /* server IP address */ - char *local_host; /* used for ap_get_server_name when - * UseCanonicalName is set to DNS - * (ignores setting of HostnameLookups) */ - long id; /* ID of this connection; unique at any - * point in time */ - void *conn_config; /* Notes on *this* connection */ - apr_table_t *notes; /* send note from one module to another, must - * remain valid for all requests on this conn */ + /** local address */ + struct sockaddr_in local_addr; + /** remote address */ + struct sockaddr_in remote_addr; + /** Client's IP address */ + char *remote_ip; + /** Client's DNS name, if known. NULL if DNS hasn't been checked, + * "" if it has and no address was found. N.B. Only access this though + * get_remote_host() */ + char *remote_host; + /** Only ever set if doing rfc1413 lookups. N.B. Only access this through + * get_remote_logname() */ + char *remote_logname; + + /** Are we still talking? */ + unsigned aborted:1; + /** Are we using HTTP Keep-Alive? -1 fatal error, 0 undecided, 1 yes */ + signed int keepalive:2; + /** Did we use HTTP Keep-Alive? */ + unsigned keptalive:1; + /** have we done double-reverse DNS? -1 yes/failure, 0 not yet, + * 1 yes/success */ + signed int double_reverse:2; + + /** How many times have we used it? */ + int keepalives; + /** server IP address */ + char *local_ip; + /** used for ap_get_server_name when UseCanonicalName is set to DNS + * (ignores setting of HostnameLookups) */ + char *local_host; + + /** ID of this connection; unique at any point in time */ + long id; + /** Notes on *this* connection */ + void *conn_config; + /** send note from one module to another, must remain valid for all + * requests on this conn */ + apr_table_t *notes; }; /* Per-vhost config... */ @@ -788,62 +872,93 @@ struct conn_rec { #define DEFAULT_VHOST_ADDR 0xfffffffful typedef struct server_addr_rec server_addr_rec; + +/** A structure to be used for Per-vhost config */ struct server_addr_rec { + /** The next server in the list server_addr_rec *next; - apr_in_addr host_addr; /* The bound address, for this server */ - unsigned short host_port; /* The bound port, for this server */ - char *virthost; /* The name given in */ + /** The bound address, for this server */ + apr_in_addr host_addr; + /** The bound port, for this server */ + unsigned short host_port; + /** The name given in */ + char *virthost; }; +/** A structure to store information for each virtual server */ struct server_rec { + /** The process this server is running in */ process_rec *process; + /** The next server in the list */ server_rec *next; - /* description of where the definition came from */ + /** The name of the server */ const char *defn_name; + /** The line of the config file that the server was defined on */ unsigned defn_line_number; /* Contact information */ + /** The admin's contact information */ char *server_admin; + /** The server hostname */ char *server_hostname; - unsigned short port; /* for redirects, etc. */ + /** for redirects, etc. */ + unsigned short port; /* Log files --- note that transfer log is now in the modules... */ + /** The name of the error log */ char *error_fname; + /** A file descriptor that references the error log */ apr_file_t *error_log; + /** The log level for this server */ int loglevel; /* Module-specific configuration for server, and defaults... */ - int is_virtual; /* true if this is the virtual server */ + /** true if this is the virtual server */ + int is_virtual; + /** Config vector containing pointers to modules' per-server config + * structures. */ void *module_config; /* Config vector containing pointers to - * modules' per-server config structures. - */ + /** MIME type info, etc., before we start checking per-directory info. */ void *lookup_defaults; /* MIME type info, etc., before we start - * checking per-directory info. - */ + /* Transaction handling */ + /** I haven't got a clue */ server_addr_rec *addrs; - int timeout; /* Timeout, in seconds, before we give up */ - int keep_alive_timeout; /* Seconds we'll wait for another request */ - int keep_alive_max; /* Maximum requests per connection */ - int keep_alive; /* Use persistent connections? */ - - const char *path; /* Pathname for ServerPath */ - int pathlen; /* Length of path */ - - apr_array_header_t *names; /* Normal names for ServerAlias servers */ - apr_array_header_t *wild_names; /* Wildcarded names for ServerAlias servers */ - - uid_t server_uid; /* effective user id when calling exec wrapper */ - gid_t server_gid; /* effective group id when calling exec wrapper */ - - int limit_req_line; /* limit on size of the HTTP request line */ - int limit_req_fieldsize; /* limit on size of any request header field */ - int limit_req_fields; /* limit on number of request header fields */ + /** Timeout, in seconds, before we give up */ + int timeout; + /** Seconds we'll wait for another request */ + int keep_alive_timeout; + /** Maximum requests per connection */ + int keep_alive_max; + /** Use persistent connections? */ + int keep_alive; + + /** Pathname for ServerPath */ + const char *path; + /** Length of path */ + int pathlen; + + /** Normal names for ServerAlias servers */ + apr_array_header_t *names; + /** Wildcarded names for ServerAlias servers */ + apr_array_header_t *wild_names; + + /** effective user id when calling exec wrapper */ + uid_t server_uid; + /** effective group id when calling exec wrapper */ + gid_t server_gid; + + /** limit on size of the HTTP request line */ + int limit_req_line; + /** limit on size of any request header field */ + int limit_req_fieldsize; + /** limit on number of request header fields */ + int limit_req_fields; }; /* stuff marked API_EXPORT is part of the API, and intended for use @@ -892,47 +1007,294 @@ struct server_rec { #endif #endif -/* Time */ - +/** + * Examine a field value (such as a media-/content-type) string and return + * it sans any parameters; e.g., strip off any ';charset=foo' and the like. + * @param p Pool to allocate memory out of + * @param intype The field to examine + * @return the field minus any parameters + * @deffunc char *ap_field_noparam(apr_pool_t *p, const char *intype); + */ API_EXPORT(char *) ap_field_noparam(apr_pool_t *p, const char *intype); + +/** + * Convert a time from an integer into a string in a specified format + * @param p The pool to allocate memory out of + * @param t The time to convert + * @param fmt The format to use for the conversion + * @param gmt Convert the time for GMT? + * @return The string that represents the specified time + * @deffunc char *ap_ht_time(apr_pool_t *p, apr_time_t t, const char *fmt, int gmt) + */ API_EXPORT(char *) ap_ht_time(apr_pool_t *p, apr_time_t t, const char *fmt, int gmt); /* String handling. The *_nc variants allow you to use non-const char **s as arguments (unfortunately C won't automatically convert a char ** to a const char **) */ +/** + * Get the characters until the first occurance of a specified character + * @param p The pool to allocate memory out of + * @param line The string to get the characters from + * @param stop The character to stop at + * @return A copy of the characters up to the first stop character + * @deffunc char *ap_getword(apr_pool_t *p, const char **line, char stop); + */ API_EXPORT(char *) ap_getword(apr_pool_t *p, const char **line, char stop); +/** + * Get the characters until the first occurance of a specified character + * @param p The pool to allocate memory out of + * @param line The string to get the characters from + * @param stop The character to stop at + * @return A copy of the characters up to the first stop character + * @tip This is the same as ap_getword, except it doesn't use const char **. + * @deffunc char *ap_getword_nc(apr_pool_t *p, char **line, char stop); + */ API_EXPORT(char *) ap_getword_nc(apr_pool_t *p, char **line, char stop); + +/** + * Get the first word from a given string. A word is defined as all characters + * up to the first whitespace. + * @param p The pool to allocate memory from + * @param line The string to traverse + * @retrn The first word in the line + * @deffunc char *ap_getword_white(apr_pool_t *p, const char **line) + */ API_EXPORT(char *) ap_getword_white(apr_pool_t *p, const char **line); +/** + * Get the first word from a given string. A word is defined as all characters + * up to the first whitespace. + * @param p The pool to allocate memory from + * @param line The string to traverse + * @retrn The first word in the line + * @tip The same as ap_getword_white, except it doesn't use const char **. + * @deffunc char *ap_getword_white_nc(apr_pool_t *p, const char **line) + */ API_EXPORT(char *) ap_getword_white_nc(apr_pool_t *p, char **line); + +/** + * Get all characters from the first occurance of stop to the first '\0' + * @param p The pool to allocate memory out of + * @param line The line to traverse + * @param stop The character to start at + * @return A copy of all caracters after the first occurance of the specified + * character + * @deffunc char *ap_getword_nulls(apr_pool_t *p, const char **line, char stop) + */ API_EXPORT(char *) ap_getword_nulls(apr_pool_t *p, const char **line, char stop); +/** + * Get all characters from the first occurance of stop to the first '\0' + * @param p The pool to allocate memory out of + * @param line The line to traverse + * @param stop The character to start at + * @return A copy of all caracters after the first occurance of the specified + * character + * @tip The same as ap_getword_nulls, except it doesn't use const char **. + * @deffunc char *ap_getword_nulls_nc(apr_pool_t *p, char **line, char stop) + */ API_EXPORT(char *) ap_getword_nulls_nc(apr_pool_t *p, char **line, char stop); + +/** + * Get the second word in the string paying attention to quoting + * @param p The pool to allocate out of + * @param line The line to traverse + * @return A copy of the string + * @deffunc char *ap_getword_conf(apr_pool_t *p, const char **line) + */ API_EXPORT(char *) ap_getword_conf(apr_pool_t *p, const char **line); +/** + * Get the second word in the string paying attention to quoting + * @param p The pool to allocate out of + * @param line The line to traverse + * @return A copy of the string + * @tip The same as ap_getword_conf, except it doesn't use const char **. + * @deffunc char *ap_getword_conf_nc(apr_pool_t *p, char **line) + */ API_EXPORT(char *) ap_getword_conf_nc(apr_pool_t *p, char **line); + +/** + * Check a string for any ${ENV} environment variable construct and replace + * each them by the value of that environment variable, if it exists. If the + * environment value does not exist, leave the ${ENV} construct alone; it + * means something else. + * @param p The pool to allocate out of + * @param word The string to check + * @return The string with the replaced environment variables + * @deffunc const char *ap_resolve_env(apr_pool_t *p, const char *word) + */ API_EXPORT(const char *) ap_resolve_env(apr_pool_t *p, const char * word); +/** + * Size an HTTP header field list item, as separated by a comma. + * @param field The field to size + * @param len The length of the field + * @return The return value is a pointer to the beginning of the non-empty + * list item within the original string (or NULL if there is none) and the + * address of field is shifted to the next non-comma, non-whitespace + * character. len is the length of the item excluding any beginning whitespace. + * @deffunc const char *ap_size_list_item(const char **field, int *len) + */ API_EXPORT(const char *) ap_size_list_item(const char **field, int *len); + +/** + * Retrieve an HTTP header field list item, as separated by a comma, + * while stripping insignificant whitespace and lowercasing anything not in + * a quoted string or comment. + * @param p The pool to allocate out of + * @param field The field to retrieve + * @return The return value is a new string containing the converted list + * item (or NULL if none) and the address pointed to by field is + * shifted to the next non-comma, non-whitespace. + * @deffunc char *ap_get_list_item(apr_pool_t *p, const char **field) + */ API_EXPORT(char *) ap_get_list_item(apr_pool_t *p, const char **field); + +/** + * Find an item in canonical form (lowercase, no extra spaces) within + * an HTTP field value list. + * @param p The pool to allocate out of + * @param line The field value list to search + * @param tok The token to search for + * @return 1 if found, 0 if not found. + * @deffunc int ap_find_list_item(apr_pool_t *p, const char *line, const char *tok) + */ API_EXPORT(int) ap_find_list_item(apr_pool_t *p, const char *line, const char *tok); +/** + * Retrieve a token, spacing over it and returning a pointer to + * the first non-white byte afterwards. Note that these tokens + * are delimited by semis and commas; and can also be delimited + * by whitespace at the caller's option. + * @param p The pool to allocate out of + * @param accept_line The line to retrieve the token from + * @param accept_white Is it delimited by whitespace + * @return the first non-white byte after the token + * @deffunc char *ap_get_token(apr_pool_t *p, const char **accept_line, int accept_white) + */ API_EXPORT(char *) ap_get_token(apr_pool_t *p, const char **accept_line, int accept_white); + +/** + * find http tokens, see the definition of token from RFC2068 + * @param p The pool to allocate out of + * @param line The line to find the token + * @param tok The token to find + * @return 1 if the token is found, 0 otherwise + * @deffunc int ap_find_token(apr_pool_t *p, const char *line, const char *tok) + */ API_EXPORT(int) ap_find_token(apr_pool_t *p, const char *line, const char *tok); + +/** + * find http tokens from the end of the line + * @param p The pool to allocate out of + * @param line The line to find the token + * @param tok The token to find + * @return 1 if the token is found, 0 otherwise + * @deffunc int ap_find_last_token(apr_pool_t *p, const char *line, const char *tok) + */ API_EXPORT(int) ap_find_last_token(apr_pool_t *p, const char *line, const char *tok); +/** + * Check for an Absolute URI syntax + * @param u The string to check + * @return 1 if URI, 0 otherwise + * @deffunc int ap_is_url(const char *u) + */ API_EXPORT(int) ap_is_url(const char *u); + +/** + * Unescape a URL + * @param url The url to unescapte + * @return 0 on success, non-zero otherwise + * @deffunc int ap_unescape_url(char *url) + */ API_EXPORT(int) ap_unescape_url(char *url); +/** + * Remove all double slashes from a string + * @param name The string to parse + * @deffunc void ap_no2slash(char *name) + */ API_EXPORT(void) ap_no2slash(char *name); + +/** + * Remove all ./ and ../ substrings from a file name + * @param name the file name to parse + * @deffunc void ap_getparents(char *name) + */ API_EXPORT(void) ap_getparents(char *name); + +/** + * Escape a path segment, as defined in RFC 1808 + * @param p The pool to allocate out of + * @param s The path to convert + * @return The converted URL + * @deffunc char *ap_escape_path_segment(apr_pool_t *p, const char *s) + */ API_EXPORT(char *) ap_escape_path_segment(apr_pool_t *p, const char *s); +/** + * convert an OS path to a URL in an OS dependant way. + * @param p The pool to allocate out of + * @param path The path to convert + * @param partial if set, assume that the path will be appended to something + * with a '/' in it (and thus does not prefix "./") + * @return The converted URL + * @deffunc char *ap_os_escape_path(apr_pool_t *p, const char *path, int partial) + */ API_EXPORT(char *) ap_os_escape_path(apr_pool_t *p, const char *path, int partial); #define ap_escape_uri(ppool,path) ap_os_escape_path(ppool,path,1) + +/** + * Escape an html string + * @param p The pool to allocate out of + * @param s The html to escape + * @return The escaped string + * @deffunc char *ap_escape_html(apr_pool_t *p, const char *s) + */ API_EXPORT(char *) ap_escape_html(apr_pool_t *p, const char *s); + +/** + * Construct a full hostname + * @param p The pool to allocate out of + * @param hostname The hostname of the server + * @param port The port the server is running on + * @param r The current request + * @return The server's hostname + * @deffunc char *ap_construct_server(apr_pool_t *p, const char *hostname, unsiged port, const request_rec *r) + */ API_EXPORT(char *) ap_construct_server(apr_pool_t *p, const char *hostname, unsigned port, const request_rec *r); +/** + * Escape a shell command + * @param p The pool to allocate out of + * @param s The command to escape + * @return The escaped hostname + * @deffunc char *ap_escape_shell_cmd(apr_pool_t *p, const char *s) + */ API_EXPORT(char *) ap_escape_shell_cmd(apr_pool_t *p, const char *s); +/** + * Count the number of directories in a path + * @param The path to count + * @return The number of directories + * @deffunc int ap_count_dirs(const char *path) + */ API_EXPORT(int) ap_count_dirs(const char *path); +/** + * copy at most n leading directories of s into d d should be at least as + * large as s plus 1 extra byte assumes n > 0 + * @param d The location to copy to + * @param s The location to copy from + * @param n The number of directories to copy + * @return value is the ever useful pointer to the trailing \0 of d + * @deffunc char *ap_make_dirstr_prefix(char *d, const char *s, int n) + */ API_EXPORT(char *) ap_make_dirstr_prefix(char *d, const char *s, int n); +/** + * return the parent directory name including trailing / of the file s + * @param p The pool to allocate out of + * @param s The file to get the parent of + * @return A copy of the file's parent directory + * @deffunc char *ap_make_dirstr_parent(apr_pool_t *p, const char *s) + */ API_EXPORT(char *) ap_make_dirstr_parent(apr_pool_t *p, const char *s); /* deprecated. The previous two routines are preferred. */ API_EXPORT(char *) ap_make_dirstr(apr_pool_t *a, const char *s, int n); -- 2.40.0