[mod-xhtml-neg-cvs] mod_xhtml_neg-2.0 mod_xhtml_neg.c,1.11,1.12
Brought to you by:
run2000
Menu
▾
▴
[mod-xhtml-neg-cvs] mod_xhtml_neg-2.0 mod_xhtml_neg.c,1.11,1.12
|
From: <ru...@us...> - 2004-03-26 11:03:52
|
Update of /cvsroot/mod-xhtml-neg/mod_xhtml_neg-2.0 In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv28182 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-2.0/mod_xhtml_neg.c,v retrieving revision 1.11 retrieving revision 1.12 diff -C2 -d -r1.11 -r1.12 *** mod_xhtml_neg.c 25 Mar 2004 10:20:54 -0000 1.11 --- mod_xhtml_neg.c 26 Mar 2004 10:52:55 -0000 1.12 *************** *** 116,120 **** #include "http_request.h" ! /* This is naughty */ #define CORE_PRIVATE --- 116,124 ---- #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 *************** *** 200,206 **** 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? */ --- 204,210 ---- 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? */ *************** *** 227,230 **** --- 231,237 ---- * 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. */ *************** *** 235,240 **** /** ! * Re-implement strlen, since relying on it being included somewhere along ! * the way appears to be unsafe. */ --- 242,250 ---- /** ! * 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 */ *************** *** 255,258 **** --- 265,275 ---- /** * 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 */ *************** *** 289,292 **** --- 306,316 ---- /** * 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 */ *************** *** 333,336 **** --- 357,368 ---- * 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 */ *************** *** 370,373 **** --- 402,413 ---- * 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 */ *************** *** 417,420 **** --- 457,466 ---- * 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 */ *************** *** 456,459 **** --- 502,509 ---- * 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? */ *************** *** 477,480 **** --- 527,534 ---- * 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 */ *************** *** 506,509 **** --- 560,567 ---- * 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 */ *************** *** 532,535 **** --- 590,597 ---- * 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? */ *************** *** 562,565 **** --- 624,631 ---- * 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. *************** *** 592,595 **** --- 658,670 ---- * 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 */ *************** *** 618,621 **** --- 693,704 ---- * 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 */ *************** *** 669,672 **** --- 752,760 ---- * 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 */ *************** *** 692,695 **** --- 780,789 ---- * 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 */ *************** *** 793,796 **** --- 887,895 ---- * 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 */ *************** *** 817,820 **** --- 916,926 ---- * Deal explicitly with 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 */ *************** *** 870,873 **** --- 976,984 ---- * 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 */ *************** *** 914,917 **** --- 1025,1037 ---- * 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 */ *************** *** 1031,1034 **** --- 1151,1170 ---- * 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 */ *************** *** 1130,1133 **** --- 1266,1271 ---- * If "Vary: *" exists, return it unaltered. Otherwise, we need to merge two * new tokens: "Accept" and "Accept-Charset". + * + * @param r the current HTTP request to which we merge Vary tokens */ *************** *** 1159,1162 **** --- 1297,1304 ---- * We do this so that the default handler will always run, and so that * ETag is handled correctly for both 200 OK and 304 Not Modified cases. + * + * @param r the current HTTP request + * @return DECLINED, to indicate the request should be processed by the + * next handler in the chain */ *************** *** 1301,1308 **** /** * Is this module active for the given directory. */ static const char *set_xhtml_active(cmd_parms *cmd, ! void *in_dir_config, int arg) { xhtml_dir_config *dir_config = in_dir_config; --- 1443,1454 ---- /** * Is this module active for the given directory. + * + * @param in_dir_config the configuration information for this directory + * @param active a yes/no flag indicating whether the module should be active + * @return NULL to indicate that processing was successful */ static const char *set_xhtml_active(cmd_parms *cmd, ! void *in_dir_config, int active) { xhtml_dir_config *dir_config = in_dir_config; *************** *** 1311,1315 **** * set the active flag */ ! if ( arg ) { dir_config->active = active_on; } else { --- 1457,1461 ---- * set the active flag */ ! if ( active ) { dir_config->active = active_on; } else { *************** *** 1322,1329 **** * 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; --- 1468,1480 ---- * 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; *************** *** 1332,1344 **** &xhtml_neg_module); ! if( arg ) { xns->cache = caching_on; } else { xns->cache = caching_off; } } /** * Add content types for the given file extension. */ --- 1483,1501 ---- &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 in_dir_config the configuration information for this directory + * @param ext the file extension we're configuring + * @param type the content type to be added for this file extension + * @return NULL to indicate that processing was successful */ *************** *** 1377,1380 **** --- 1534,1542 ---- * Note the minimun number of stars in an Accept token that should be * ignored when performing negotiation. + * + * @param in_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 */ *************** *** 1400,1403 **** --- 1562,1570 ---- /** * 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 */ *************** *** 1418,1421 **** --- 1585,1592 ---- /** * 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 */ *************** *** 1434,1437 **** --- 1605,1612 ---- /** * 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 */ *************** *** 1450,1453 **** --- 1625,1634 ---- /** * 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 */ *************** *** 1493,1496 **** --- 1674,1682 ---- /** * 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 */ |
