[mod-xhtml-neg-cvs] mod_xhtml_neg mod_xhtml_neg.c,1.26,1.27
Brought to you by:
run2000
Menu
▾
▴
[mod-xhtml-neg-cvs] mod_xhtml_neg mod_xhtml_neg.c,1.26,1.27
|
From: <ru...@us...> - 2004-03-26 10:42:22
|
Update of /cvsroot/mod-xhtml-neg/mod_xhtml_neg In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv24551 Modified Files: mod_xhtml_neg.c Log Message: More documentation on parameters and return values for each function. Some other minor tidy-ups. Index: mod_xhtml_neg.c =================================================================== RCS file: /cvsroot/mod-xhtml-neg/mod_xhtml_neg/mod_xhtml_neg.c,v retrieving revision 1.26 retrieving revision 1.27 diff -C2 -d -r1.26 -r1.27 *** mod_xhtml_neg.c 25 Mar 2004 10:20:37 -0000 1.26 --- mod_xhtml_neg.c 26 Mar 2004 10:31:25 -0000 1.27 *************** *** 108,112 **** #include "http_request.h" ! /* This is naughty */ #define CORE_PRIVATE --- 108,116 ---- #include "http_request.h" ! /* This is naughty, because it gives us access to private areas of ! * http_core.c. We use this to retrieve default charset information ! * from the core module. This is populated by the AddDefaultCharset ! * directive. ! */ #define CORE_PRIVATE *************** *** 168,172 **** * caching state for HTTP 1.0 requests. */ - typedef struct { char *fname; /**< Name of the log file we write to, if any */ --- 172,175 ---- *************** *** 182,186 **** * we should ignore. */ - typedef struct { xhtml_neg_active active; /**< Is the module active for this directory? */ --- 185,188 ---- *************** *** 192,202 **** /** * Record of available info on a media type specified by the client. ! * We also use them for encodings and profiles. */ - typedef struct { ! char *name; /**< MUST be lowercase */ float q_value; /**< Quality value, from 0 to 1. */ ! char *charset; /**< for content-type only */ char *profile; /**< The XHTML profile, as per RFC 3236 */ int stars; /**< How many stars in this accept token? */ --- 194,203 ---- /** * Record of available info on a media type specified by the client. ! * We also use it for encoding and profile information. */ typedef struct { ! char *name; /**< The name, normalised to lowercase */ float q_value; /**< Quality value, from 0 to 1. */ ! char *charset; /**< Charset parameter, for content-type only */ char *profile; /**< The XHTML profile, as per RFC 3236 */ int stars; /**< How many stars in this accept token? */ *************** *** 208,212 **** * types themselves are stored as an array of accept_rec records. */ - typedef struct { char *extension; /**< Filename extension */ --- 209,212 ---- *************** *** 214,219 **** } extension_rec; - /* String utility functions start here. */ - /* * Utility functions for strings, since we can't rely on these functions being --- 214,217 ---- *************** *** 225,228 **** --- 223,229 ---- * string just to return a length, as per strlen. * + * @param str a string pointer, possibly NULL, to be tested + * @return non-zero if the pointer is NULL, or points to a zero-length + * string, otherwise zero * @todo could macro-ise this function. */ *************** *** 233,238 **** /** ! * Re-implement strlen, since relying on it being included somewhere along ! * the way appears to be unsafe. */ --- 234,242 ---- /** ! * Calculate the length of the given string. The pointer may be NULL. ! * ! * @param str a string pointer, possibly NULL, to be tested ! * @return the length of the string if the pointer is non-NULL, otherwise ! * zero */ *************** *** 253,256 **** --- 257,267 ---- /** * Compare one string against another in a case-sensitive manner. + * Will correctly deal with either pointer being NULL. + * + * @param str1 the first string pointer to be compared + * @param str2 the second string pointer to be compared + * @return zero if the strings are identical, less than zero if the + * first string is less than the second, or greater than zero if the + * first string is greater than the second */ *************** *** 287,290 **** --- 298,308 ---- /** * Compare one string against another in a case-insensitive manner. + * Will correctly deal with either pointer being NULL. + * + * @param str1 the first string pointer to be compared + * @param str2 the second string pointer to be compared + * @return zero if the strings are identical, less than zero if the + * first string is less than the second, or greater than zero if the + * first string is greater than the second */ *************** *** 331,334 **** --- 349,360 ---- * Compare strings up to a specified limit in a case-sensitive manner. * If a NULL byte is encountered, finish comparing at that character. + * Will correctly deal with either pointer being NULL. + * + * @param str1 the first string pointer to be compared + * @param str2 the second string pointer to be compared + * @param len the maximum number of characters to be compared + * @return zero if the substrings are identical, less than zero if the + * first substring is less than the second, or greater than zero if the + * first substring is greater than the second */ *************** *** 368,371 **** --- 394,405 ---- * Compare strings up to a specified limit in a case-insensitive manner. * If a NULL byte is encountered, finish comparing at that character. + * Will correctly deal with either pointer being NULL. + * + * @param str1 the first string pointer to be compared + * @param str2 the second string pointer to be compared + * @param len the maximum number of characters to be compared + * @return zero if the substrings are identical, less than zero if the + * first substring is less than the second, or greater than zero if the + * first substring is greater than the second */ *************** *** 415,418 **** --- 449,458 ---- * Determines if the given string end with the given suffix. Case matching * can be enabled or disabled. + * + * @param reference the reference string to be tested, possibly NULL + * @param suffix the suffix to test against, possibly NULL + * @param casecompare non-zero if a case sensitive compare is wanted, + * otherwise zero for a case insensitive compare + * @return non-zero if the suffix matches, otherwise zero */ *************** *** 454,457 **** --- 494,501 ---- * to find the default character set. * + * @param r the current HTTP request from which we can determine the + * configuration of the Apache core + * @return the default character set as configured in the Apache core, + * or NULL if no value is configured * @todo Is there a cleaner way to find the default charset information? */ *************** *** 475,478 **** --- 519,526 ---- * extension. If a match is found, return the extension_rec, otherwise * return NULL. + * + * @param extensions an array of extension_rec elements to be scanned + * @param ext the file extension to match + * @return the matching extension_rec item if one was found, otherwise NULL */ *************** *** 504,507 **** --- 552,559 ---- * Count the number of stars in an Accept content token. This helps determine * priority in case of a tie in q-value priorities. + * + * @param content_type the content token that we're interested in, possibly + * NULL + * @return the number of '*' characters in the string */ *************** *** 530,533 **** --- 582,589 ---- * content-type string. * + * @param p a memory pool from which we can allocate temporary memory for this + * request + * @param content_rec the accept_rec that matched the content negotiation + * @param a string that contains a correctly formatted content-type value * @todo should we send the "profile" parameter as well? */ *************** *** 560,563 **** --- 616,623 ---- * concatenated as one long string. * + * @param p a memory pool from which we can allocate temporary memory for this + * request + * @param rec the accept_rec that matched the content negotiation; the hash + * value will be added to this structure * @todo If the content-type returned ever includes the "profile" parameter, * include it as part of the hash code. *************** *** 590,593 **** --- 650,662 ---- * parameter default_charset is used. Note that default_charset can be * NULL, in which case charset will be set to the empty string. + * + * @param p a memory pool from which we can allocate temporary memory for this + * request + * @param rec the accept_rec that matched the content negotiation + * @param default_charset the default character set as configured in the + * Apache core + * @return the original accept_rec if it already contains a charset parameter, + * otherwise a new accept_rec containing the same information and the default + * charset parameter */ *************** *** 615,618 **** --- 684,695 ---- * Merge vlist_validators from different modules. This code is adapted * from code in http_protocol.c in the Apache 1.3 core. + * + * @param p a memory pool from which we can allocate temporary memory for this + * request + * @param old_variant an Etag variant taken from the vlist_validator parameter + * of the current request + * @param new_variant an Etag variant as supplied by make_etag_hashcode + * @return a correctly merged Etag variant, taking into account whether either + * variant has a weak validator attached, or whether either variant is NULL */ *************** *** 666,669 **** --- 743,751 ---- * until we find a match. The first match wins. If no match is found, * NULL is returned. + * + * @param extensions an array of extension_rec elements containing filename + * suffixes to be matched + * @param filename the filename we want to match + * @return the matching extension_rec item if one exists, otherwise NULL */ *************** *** 689,692 **** --- 771,780 ---- * Get a single mime type entry --- one media type and parameters; * enter the values we recognize into the argument accept_rec. + * + * @param p a memory pool from which we can allocate temporary memory for this + * request + * @param result the accept_rec to be populated by parsing the accept_line + * @param accept_line a string containing the accept token to be parsed + * @return any remaining accept_line string left to be parsed */ *************** *** 777,781 **** /** ! * Deal with Accept header lines. * * The Accept request header is handled by do_accept_line() - it has the --- 865,869 ---- /** ! * Parse and tokenise Accept header lines. * * The Accept request header is handled by do_accept_line() - it has the *************** *** 790,793 **** --- 878,886 ---- * These probably won't appear at an origin server, but we handle * them explicitly if they do. + * + * @param p a memory pool from which we can allocate temporary memory for this + * request + * @param accept_line the HTTP Accept request value to be parsed + * @return an array of accept_rec items containing the parsed Accept tokens */ *************** *** 811,816 **** /** ! * Deal explicitly with Accept-Charset headers. There is an extra record * inserted when neither "*" nor "ISO-8859-1" are mentioned. */ --- 904,916 ---- /** ! * Parse and tokenise Accept-Charset headers. There is an extra record * inserted when neither "*" nor "ISO-8859-1" are mentioned. + * + * @param p a memory pool from which we can allocate temporary memory for this + * request + * @param accept_charset_line the HTTP Accept-Charset request value to be + * parsed + * @return an array of accept_rec items containing the parsed Accept-Charset + * tokens */ *************** *** 866,869 **** --- 966,974 ---- * Look for a matching charset within the given array of accept_recs. If we * find a match, return the corresponding q value, otherwise return 0.0. + * + * @param accept_charsets an array of accept_rec items containing + * Accept-Charset tokens to be matched + * @param content_charset the target charset parameter to match + * @return the q value of the best match, or 0.0f if no match was found */ *************** *** 910,913 **** --- 1015,1027 ---- * the q value of the Accept-Charset header. Where no q-value is specified, * the value "1.0" is used. + * + * @param content_type the content-type token to match + * @param content_accept the accept token to be matched + * @param accept_charsets an array of accept_rec items containing + * Accept-Charset tokens to be matched + * @param default_charset the default charset value as configured in the + * Apache core + * @return the q value of the best matching content-type and charset + * combination, or 0.0f if no match was found */ *************** *** 1027,1030 **** --- 1141,1160 ---- * content-type headers and an optional default content-type in the event of * a star-slash-star match. + * + * @param accept_type an array of accept_rec items containing Accept tokens + * @param content_type an array of accept_rec items containing possible + * content-type tokens to be matched + * @param accept_charset an array of accept_rec items containing + * Accept-Charset tokens + * @param default_charset the default character set as configured in the + * Apache core + * @param stars_to_match the number of '*' tokens at which we start ignoring + * the Accept token + * @param xns the configuration state of the module in case we need to write + * to the log file + * @param p a memory pool from which we can allocate temporary memory for this + * request + * @return an accept_rec structure containing the best match we could find for + * the current request, or NULL if we couldn't find a match */ *************** *** 1124,1127 **** --- 1254,1259 ---- * If "Vary: *" exists, return it unaltered. Otherwise, we need to merge two * new tokens: "Accept" and "Accept-Charset". + * + * @param r the current HTTP request */ *************** *** 1145,1151 **** /** ! * The main routine for the content-negotiation phase of this module ! * goes here. This is mainly setup, control flow and logging going on ! * here. */ --- 1277,1285 ---- /** ! * The main routine for the content-negotiation phase of this module goes ! * here. This is mainly setup, control flow and logging going on here. ! * ! * @param r the current HTTP request ! * @return OK, to indicate the request was succesfully handled by this module */ *************** *** 1300,1303 **** --- 1434,1441 ---- /** * Is this module active for the given directory. + * + * @param dir_config the configuration information for this directory + * @param arg a yes/no flag indicating whether the module should be active + * @return NULL to indicate that processing was successful */ *************** *** 1319,1326 **** * Set whether HTTP 1.0 caching should be allowed. Default to "no" unless * specifically overridden. */ static const char *set_xhtml_cache_negotiated(cmd_parms *cmd, void *dummy, ! int arg) { xhtml_neg_state *xns; --- 1457,1469 ---- * Set whether HTTP 1.0 caching should be allowed. Default to "no" unless * specifically overridden. + * + * @param cmd the configuration information for this module on a per-server + * basis + * @param cache a flag indicating whether HTTP 1.0 caching should be enabled + * @return NULL to indicate that processing was successful */ static const char *set_xhtml_cache_negotiated(cmd_parms *cmd, void *dummy, ! int cache) { xhtml_neg_state *xns; *************** *** 1329,1344 **** &xhtml_neg_module); ! if( arg ) { xns->cache = caching_on; } else { xns->cache = caching_off; } } /** * Add content types for the given file extension. */ ! static const char *add_xhtml_type(cmd_parms *cmd, xhtml_dir_config *t, char *ext, char *contenttype) { --- 1472,1494 ---- &xhtml_neg_module); ! if( cache ) { xns->cache = caching_on; } else { xns->cache = caching_off; } + return NULL; } /** * Add content types for the given file extension. + * + * @param dir_config the configuration information for this directory + * @param ext the file extension we're configuring + * @param contenttype the content type to be added for this file extension + * @return NULL to indicate that processing was successful */ ! static const char *add_xhtml_type(cmd_parms *cmd, ! xhtml_dir_config *dir_config, char *ext, char *contenttype) { *************** *** 1346,1350 **** accept_rec *new; ! /* Probably don't want this bit... */ /* if (*ext == '.') --- 1496,1500 ---- accept_rec *new; ! /* Probably don't need this bit... */ /* if (*ext == '.') *************** *** 1354,1360 **** ap_str_tolower(contenttype); ! rec = find_extension( t->extensions, ext ); if( rec == NULL ) { ! rec = (extension_rec *) ap_push_array(t->extensions); rec->extension = ext; rec->content_types = ap_make_array( cmd->pool, 10, --- 1504,1510 ---- ap_str_tolower(contenttype); ! rec = find_extension( dir_config->extensions, ext ); if( rec == NULL ) { ! rec = (extension_rec *) ap_push_array(dir_config->extensions); rec->extension = ext; rec->content_types = ap_make_array( cmd->pool, 10, *************** *** 1370,1378 **** /** ! * Note the minimun number of stars in an Accept token that should be * ignored when performing negotiation. */ ! static const char *add_xhtml_ignore(cmd_parms *cmd, xhtml_dir_config *t, char *stars) { --- 1520,1534 ---- /** ! * Set the minimun number of stars in an Accept token that should be * ignored when performing negotiation. + * + * @param dir_config the configuration information for this directory + * @param stars the number of '*' tokens at which we start ignoring any + * Accept tokens + * @return NULL to indicate that processing was successful */ ! static const char *add_xhtml_ignore(cmd_parms *cmd, ! xhtml_dir_config *dir_config, char *stars) { *************** *** 1388,1392 **** } ! t->stars_ignore = ignore_stars; return NULL; } --- 1544,1548 ---- } ! dir_config->stars_ignore = ignore_stars; return NULL; } *************** *** 1394,1397 **** --- 1550,1558 ---- /** * Set the log file name for this module. + * + * @param cmd the configuration information for this module on a per-server + * basis + * @param logfile the name of the log file to which the module should write + * @return NULL to indicate that processing was successful */ *************** *** 1411,1414 **** --- 1572,1579 ---- /** * Create a default XHTML negotiation module configuration record. + * + * @param p a memory pool from which we can allocate memory that can later + * be recycled + * @return a new per-server configuration structure for this module */ *************** *** 1427,1430 **** --- 1592,1599 ---- /** * Create a default directory configuration module. + * + * @param p a memory pool from which we can allocate memory that can later + * be recycled + * @return a new per-directory configuration structure for this module */ *************** *** 1442,1445 **** --- 1611,1620 ---- /** * Merge configuration info from different directories. + * + * @param p a memory pool from which we can allocate memory that can later + * be recycled + * @param basev the base directory configuration to be merged + * @param addv the additional directory configuration to be merged + * @return a merged per-directory configuration structure for this module */ *************** *** 1485,1488 **** --- 1660,1668 ---- /** * Initialize the log file, if one is specified. + * + * @param s the server configuration from which we derive the state of this + * module + * @param p a memory pool from which we can allocate memory that can later + * be recycled */ |
