[mod-xhtml-neg-cvs] mod_xhtml_neg-2.0 mod_xhtml_neg.c,1.5,1.6

[<ru...@us...>]

Update of /cvsroot/mod-xhtml-neg/mod_xhtml_neg-2.0
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21686

Modified Files:
	mod_xhtml_neg.c 
Log Message:
Doxygenise the source code.

Index: mod_xhtml_neg.c
===================================================================
RCS file: /cvsroot/mod-xhtml-neg/mod_xhtml_neg-2.0/mod_xhtml_neg.c,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** mod_xhtml_neg.c	15 Mar 2004 04:29:17 -0000	1.5
--- mod_xhtml_neg.c	24 Mar 2004 10:25:55 -0000	1.6
***************
*** 57,61 ****
   */
  
! /*
   * mod_xhtml_neg -- a module to negotiate an appropriate content-type for
   * XHTML content. Clients that request application/xhtml+xml will be returned
--- 57,62 ----
   */
  
! /**
!  * @file
   * mod_xhtml_neg -- a module to negotiate an appropriate content-type for
   * XHTML content. Clients that request application/xhtml+xml will be returned
***************
*** 74,82 ****
   * adding our own suffix to Etag headers when a negotiation is successful.
   *
!  * Author: Nicholas Cull <ru...@us...>
!  * Date: 1 March 2004
!  *
!  * Version history:
   *
   * 0.5 Basic handling of Accept header
   * 0.6 Added charset handling
--- 75,82 ----
   * adding our own suffix to Etag headers when a negotiation is successful.
   *
!  * @author Nicholas Cull <ru...@us...>
!  * @date 1 March 2004
   *
+  * @history:
   * 0.5 Basic handling of Accept header
   * 0.6 Added charset handling
***************
*** 85,98 ****
   * 0.9 ETag handled correctly for different content types.
   *
!  * Directives:
!  *
!  * XhtmlNegActive Is this module enabled? Defaults to no.
!  * XhtmlNegLog  A file name for an output log file
!  * XhtmlNegTypes A file extension followed by one or more matching
!  *               content-type strings
!  * XhtmlNegStarsIgnore The number of stars in an Accept header which should
!  *                     be ignored if we match them
!  * XhtmlNegCache Should negotiated HTTP 1.0 requests be cacheable?
!  *               Defaults to no
   */
  
--- 85,97 ----
   * 0.9 ETag handled correctly for different content types.
   *
!  * @directive
!  * @c XhtmlNegActive Is this module enabled? Defaults to no. \n
!  * @c XhtmlNegLog    A file name for an output log file \n
!  * @c XhtmlNegTypes A file extension followed by one or more matching
!  *                  content-type strings \n
!  * @c XhtmlNegStarsIgnore The number of stars in an Accept header which should
!  *                        be ignored if we match them \n
!  * @c XhtmlNegCache Should negotiated HTTP 1.0 requests be cacheable?
!  *                  Defaults to no \n
   */
  
***************
*** 112,160 ****
  #include "http_log.h"
  
  static int xfer_flags = (APR_WRITE | APR_APPEND | APR_CREATE);
  static apr_fileperms_t xfer_perms = APR_OS_DEFAULT;
  
  /* #define MOD_XHTML_NEG_DEBUG 1 */
  #define DEFAULT_CHARSET_NAME "iso-8859-1"
  #define DEFAULT_TEXT_XML_CHARSET "us-ascii"
  
! #define ACTIVE_ON       1
! #define ACTIVE_OFF      0
! #define ACTIVE_DONTCARE 2
  
- #define CACHE_ON        1
- #define CACHE_OFF       0
- #define CACHE_DONTCARE  2
  
  module AP_MODULE_DECLARE_DATA xhtml_neg_module;
  
  typedef struct {
!     char *fname;          /* Name of the log file we write to, if any */
!     apr_file_t *log_fd;   /* File descriptor of the log file */
!     int cache_negotiated; /* Flag to caching negotiated content in HTTP 1.0 */
  } xhtml_neg_state;
  
  typedef struct {
!     int active;                 /* Is the module active for this directory? */
!     apr_array_header_t *extensions; /* An array of extension_rec records */
!     int stars_ignore;           /* How many content-type stars before
                                     we ignore */
  } xhtml_dir_config;
  
! /*
!  * Record of available info on a media type specified by the client
!  * (we also use 'em for encodings and languages)
   */
  
  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 name? */
!     char *hashcode;
  } accept_rec;
  
! /*
   * Record the maps a file extension to zero or more content-types. The content
   * types themselves are stored as an array of accept_rec records.
--- 111,200 ----
  #include "http_log.h"
  
+ /** Read/write flags used when opening the log file. */
  static int xfer_flags = (APR_WRITE | APR_APPEND | APR_CREATE);
+ 
+ /** Permission flags used when opening the log file. */
  static apr_fileperms_t xfer_perms = APR_OS_DEFAULT;
  
  /* #define MOD_XHTML_NEG_DEBUG 1 */
+ 
+ /** The default HTTP character set for most content types. */
  #define DEFAULT_CHARSET_NAME "iso-8859-1"
+ 
+ /** The default HTTP character set for text/xml and text/xml-external-entity
+   * content types. */
  #define DEFAULT_TEXT_XML_CHARSET "us-ascii"
  
! /**
!  * Enumeration for determining whether processing should be enabled for
!  * this module. By default, we set the directory config state to
!  * active_dontcare, meaning the value hasn't been explicitly set. When
!  * it is set by XhtmlNegActive, the directory config will be set to either
!  * active_on or active_off.
!  */
! typedef enum {
!     active_on = 1,          /**< processing should be active */
!     active_off = 0,         /**< processing should not be active */
!     active_dontcare = 2     /**< default processing state (not active) */
! } xhtml_neg_active;
! 
! /**
!  * Enumeration for determining whether HTTP 1.0 caching should be allowed
!  * for negotiated documents. By default, we set the server config state to
!  * caching_dontcare, meaning the value hasn't been explicitly set. When it
!  * set by the XhtmlNegCache parameter, the server config will be set to
!  * either caching_on or caching_off.
!  */
! typedef enum {
!     caching_on = 1,         /**< HTTP 1.0 caching should be active */
!     caching_off = 0,        /**< HTTP 1.0 caching should not be active */
!     caching_dontcare = 2    /**< default processing state (not active) */
! } http_caching;
  
  
  module AP_MODULE_DECLARE_DATA xhtml_neg_module;
  
+ /**
+  * A per-server configuration state for this module. Here we record any
+  * log file that we want to write to, the open file descriptor, and the
+  * caching state for HTTP 1.0 requests.
+  */
+ 
  typedef struct {
!     char *fname;          /**< Name of the log file we write to, if any */
!     apr_file_t *log_fd;   /**< File descriptor of the log file */
!     http_caching cache;   /**< Flag to cache negotiated content in
!                             *  HTTP 1.0 requests */
  } xhtml_neg_state;
  
+ /**
+  * A per-directory configuration state for this module. Here we record the
+  * file extension to content-type mappings, whether the module should be
+  * active for this directory, and the types of wildcard Accept headers that
+  * we should ignore.
+  */
+ 
  typedef struct {
!     xhtml_neg_active active;  /**< Is the module active for this directory? */
!     apr_array_header_t *extensions; /**< An array of extension_rec records */
!     int stars_ignore;         /**< How many content-type stars before
                                     we ignore */
  } xhtml_dir_config;
  
! /**
!  * 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 name? */
!     char *hashcode;         /**< The hashcode to be appended to Etags */
  } accept_rec;
  
! /**
   * Record the maps a file extension to zero or more content-types. The content
   * types themselves are stored as an array of accept_rec records.
***************
*** 162,167 ****
  
  typedef struct {
!     char *extension;                   /* Filename extension */
!     apr_array_header_t *content_types; /* Array of content accept headers */
  } extension_rec;
  
--- 202,207 ----
  
  typedef struct {
!     char *extension;                   /**< Filename extension */
!     apr_array_header_t *content_types; /**< Array of content accept headers */
  } extension_rec;
  
***************
*** 173,181 ****
   */
  
! /*
   * Test whether a string is empty without having to do a full scan of the
   * string just to return a length, as per strlen.
   *
!  * Todo: could macro-ise this function.
   */
  
--- 213,221 ----
   */
  
! /**
   * Test whether a string is empty without having to do a full scan of the
   * string just to return a length, as per strlen.
   *
!  * @todo could macro-ise this function.
   */
  
***************
*** 184,188 ****
  }
  
! /*
   * Re-implement strlen, since relying on it being included somewhere along
   * the way appears to be unsafe.
--- 224,228 ----
  }
  
! /**
   * Re-implement strlen, since relying on it being included somewhere along
   * the way appears to be unsafe.
***************
*** 203,207 ****
  }
  
! /*
   * Compare one string against another in a case-sensitive manner.
   */
--- 243,247 ----
  }
  
! /**
   * Compare one string against another in a case-sensitive manner.
   */
***************
*** 237,241 ****
  }
  
! /*
   * Compare one string against another in a case-insensitive manner.
   */
--- 277,281 ----
  }
  
! /**
   * Compare one string against another in a case-insensitive manner.
   */
***************
*** 280,284 ****
  }
  
! /*
   * Compare strings up to a specified limit in a case-sensitive manner.
   * If a NULL byte is encountered, finish comparing at that character.
--- 320,324 ----
  }
  
! /**
   * Compare strings up to a specified limit in a case-sensitive manner.
   * If a NULL byte is encountered, finish comparing at that character.
***************
*** 317,321 ****
  }
  
! /*
   * Compare strings up to a specified limit in a case-insensitive manner.
   * If a NULL byte is encountered, finish comparing at that character.
--- 357,361 ----
  }
  
! /**
   * Compare strings up to a specified limit in a case-insensitive manner.
   * If a NULL byte is encountered, finish comparing at that character.
***************
*** 364,368 ****
  }
  
! /*
   * Determines if the given string end with the given suffix. Case matching
   * can be enabled or disabled.
--- 404,408 ----
  }
  
! /**
   * Determines if the given string end with the given suffix. Case matching
   * can be enabled or disabled.
***************
*** 402,406 ****
  }
  
! /*
   * Given an array of extension_rec records, find one with the given file
   * extension. If a match is found, return the extension_rec, otherwise
--- 442,446 ----
  }
  
! /**
   * Given an array of extension_rec records, find one with the given file
   * extension. If a match is found, return the extension_rec, otherwise
***************
*** 432,436 ****
  }
  
! /*
   * Count the number of stars in an Accept content header. This helps determine
   * priority in case of a tie in q-value priorities.
--- 472,476 ----
  }
  
! /**
   * Count the number of stars in an Accept content header. This helps determine
   * priority in case of a tie in q-value priorities.
***************
*** 454,458 ****
  }
  
! /*
   * Reconstruct the original content-type, if required due to special "charset"
   * values. Normally the content-type will be a plain string without charset
--- 494,498 ----
  }
  
! /**
   * Reconstruct the original content-type, if required due to special "charset"
   * values. Normally the content-type will be a plain string without charset
***************
*** 461,465 ****
   * content-type string.
   *
!  * Todo: should we send the "profile" parameter as well?
   */
  
--- 501,505 ----
   * content-type string.
   *
!  * @todo should we send the "profile" parameter as well?
   */
  
***************
*** 481,485 ****
  }
  
! /*
   * Make a simple hash code for the given accept_rec structure. This allows
   * us to generate unique Etags for accepted content-types. The Etag
--- 521,525 ----
  }
  
! /**
   * Make a simple hash code for the given accept_rec structure. This allows
   * us to generate unique Etags for accepted content-types. The Etag
***************
*** 491,496 ****
   * concatenated as one long string.
   *
!  * Todo:
!  * If the content-type returned ever includes the "profile" parameter,
   * include it as part of the hash code.
   */
--- 531,535 ----
   * concatenated as one long string.
   *
!  * @todo If the content-type returned ever includes the "profile" parameter,
   * include it as part of the hash code.
   */
***************
*** 517,521 ****
  }
  
! /*
   * Merge vlist_validators from different modules. This code is adapted
   * from code in http_protocol.c in the Apache 1.3 core.
--- 556,560 ----
  }
  
! /**
   * Merge vlist_validators from different modules. This code is adapted
   * from code in http_protocol.c in the Apache 1.3 core.
***************
*** 567,571 ****
  
  
! /*
   * For a given filename, scan through an array of extension_rec records
   * until we find a match. The first match wins. If no match is found,
--- 606,610 ----
  
  
! /**
   * For a given filename, scan through an array of extension_rec records
   * until we find a match. The first match wins. If no match is found,
***************
*** 589,595 ****
  }
  
! /*
!  * Following code modified from mod_negotiate.c
!  *
   * Get a single mime type entry --- one media type and parameters;
   * enter the values we recognize into the argument accept_rec
--- 628,634 ----
  }
  
!  /* Following code modified from mod_negotiate.c */
! 
! /**
   * Get a single mime type entry --- one media type and parameters;
   * enter the values we recognize into the argument accept_rec
***************
*** 681,686 ****
  }
  
! /*
!  * Dealing with Accept header lines ...
   *
   * The Accept request header is handled by do_accept_line() - it has the
--- 720,725 ----
  }
  
! /**
!  * Deal with Accept header lines.
   *
   * The Accept request header is handled by do_accept_line() - it has the
***************
*** 716,720 ****
  }
  
! /*
   * Deal explicitly with Accept-Charset headers. There is an extra record
   * inserted when neither "*" nor "ISO-8859-1" are mentioned.
--- 755,759 ----
  }
  
! /**
   * Deal explicitly with Accept-Charset headers. There is an extra record
   * inserted when neither "*" nor "ISO-8859-1" are mentioned.
***************
*** 769,773 ****
  }
  
! /*
   * 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.
--- 808,812 ----
  }
  
! /**
   * 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.
***************
*** 924,928 ****
  }
  
! /*
   * Implements the best match algorithm for a given Accept header, possible
   * content-type headers and an optional default content-type in the event of
--- 963,967 ----
  }
  
! /**
   * Implements the best match algorithm for a given Accept header, possible
   * content-type headers and an optional default content-type in the event of
***************
*** 1016,1020 ****
  }
  
! /*
   * For HTTP 1.1 responses, where the content has been modified based on HTTP
   * request headers, need to set the Vary header to name the headers that the
--- 1055,1059 ----
  }
  
! /**
   * For HTTP 1.1 responses, where the content has been modified based on HTTP
   * request headers, need to set the Vary header to name the headers that the
***************
*** 1045,1049 ****
  }
  
! /*
   * The actual content-negotiation phase of this module goes here.
   *
--- 1084,1088 ----
  }
  
! /**
   * The actual content-negotiation phase of this module goes here.
   *
***************
*** 1176,1180 ****
           * Similarly to mod_negotiate, we make it configurable.
           */
!         if( xns->cache_negotiated != CACHE_ON ) {
              r->no_cache = 1;
          }
--- 1215,1219 ----
           * Similarly to mod_negotiate, we make it configurable.
           */
!         if( xns->cache != caching_on ) {
              r->no_cache = 1;
          }
***************
*** 1189,1193 ****
  /* All Apache configuration file code goes here... */
  
! /*
   * Is this module active for the given directory.
   */
--- 1228,1232 ----
  /* All Apache configuration file code goes here... */
  
! /**
   * Is this module active for the given directory.
   */
***************
*** 1202,1213 ****
       */
      if ( arg ) {
!         dir_config->active = ACTIVE_ON;
      } else {
!         dir_config->active = ACTIVE_OFF;
      }
      return NULL;
  }
  
! /*
   * Set whether HTTP 1.0 caching should be allowed. Default to "no" unless
   * specifically overridden.
--- 1241,1252 ----
       */
      if ( arg ) {
!         dir_config->active = active_on;
      } else {
!         dir_config->active = active_off;
      }
      return NULL;
  }
  
! /**
   * Set whether HTTP 1.0 caching should be allowed. Default to "no" unless
   * specifically overridden.
***************
*** 1223,1233 ****
  
      if( arg ) {
!         xns->cache_negotiated = CACHE_ON;
      } else {
!         xns->cache_negotiated = CACHE_OFF;
      }
  }
  
! /*
   * Add content types for the given file extension.
   */
--- 1262,1272 ----
  
      if( arg ) {
!         xns->cache = caching_on;
      } else {
!         xns->cache = caching_off;
      }
  }
  
! /**
   * Add content types for the given file extension.
   */
***************
*** 1264,1268 ****
  }
  
! /*
   * Note the minimun number of stars in an Accept token that should be
   * ignored when performing negotiation.
--- 1303,1307 ----
  }
  
! /**
   * Note the minimun number of stars in an Accept token that should be
   * ignored when performing negotiation.
***************
*** 1288,1292 ****
  }
  
! /*
   * Set the log file name for this module.
   */
--- 1327,1331 ----
  }
  
! /**
   * Set the log file name for this module.
   */
***************
*** 1306,1310 ****
  }
  
! /*
   * Create a default XHTML negotiation module configuration record.
   */
--- 1345,1349 ----
  }
  
! /**
   * Create a default XHTML negotiation module configuration record.
   */
***************
*** 1317,1326 ****
      xns->fname = NULL;
      xns->log_fd = NULL;
!     xns->cache_negotiated = CACHE_DONTCARE;
  
      return (void *)xns;
  }
  
! /*
   * Create a default directory configuration module.
   */
--- 1356,1365 ----
      xns->fname = NULL;
      xns->log_fd = NULL;
!     xns->cache = caching_dontcare;
  
      return (void *)xns;
  }
  
! /**
   * Create a default directory configuration module.
   */
***************
*** 1331,1335 ****
      xhtml_dir_config *new =
          (xhtml_dir_config *) apr_pcalloc(p, sizeof(xhtml_dir_config));
!     new->active = ACTIVE_DONTCARE;
      new->extensions = apr_array_make(p, 5, sizeof(extension_rec));
      new->stars_ignore = -1;
--- 1370,1374 ----
      xhtml_dir_config *new =
          (xhtml_dir_config *) apr_pcalloc(p, sizeof(xhtml_dir_config));
!     new->active = active_dontcare;
      new->extensions = apr_array_make(p, 5, sizeof(extension_rec));
      new->stars_ignore = -1;
***************
*** 1338,1342 ****
  }
  
! /*
   * Merge configuration info from different directories.
   */
--- 1377,1381 ----
  }
  
! /**
   * Merge configuration info from different directories.
   */
***************
*** 1352,1356 ****
      int i;
  
!     if (add->active == ACTIVE_DONTCARE) {
          new->active = base->active;
      } else {
--- 1391,1395 ----
      int i;
  
!     if (add->active == active_dontcare) {
          new->active = base->active;
      } else {
***************
*** 1381,1385 ****
  }
  
! /*
   * Initialize the log file, if one is specified.
   */
--- 1420,1424 ----
  }
  
! /**
   * Initialize the log file, if one is specified.
   */
***************
*** 1417,1421 ****
  }
  
! /* Apache module declaration. */
  
  static void xhtml_register_hooks(apr_pool_t *p)
--- 1456,1460 ----
  }
  
! /** Register specific hooks during request processing. */
  
  static void xhtml_register_hooks(apr_pool_t *p)
***************
*** 1425,1428 ****
--- 1464,1469 ----
  }
  
+ /** Record for registering commands with the Apache 2.0.x server. */
+ 
  command_rec config_xhtml_cmds[] = {
      AP_INIT_FLAG("XhtmlNegActive", set_xhtml_active, NULL, OR_INDEXES,
***************
*** 1442,1454 ****
  };
  
  module AP_MODULE_DECLARE_DATA xhtml_neg_module =
  {
      STANDARD20_MODULE_STUFF,
!     create_xhtml_dir_config,    /* dir config creater */
!     merge_xhtml_dir_configs,    /* dir config merger */
!     make_xhtml_neg_state,       /* server config */
!     NULL,                       /* merge server configs */
!     config_xhtml_cmds,          /* command table */
!     xhtml_register_hooks,       /* set up other request processing hooks */
  };
  
--- 1483,1497 ----
  };
  
+ /** Module declaration for registering hooks into the Apache 2.0.x server. */
+ 
  module AP_MODULE_DECLARE_DATA xhtml_neg_module =
  {
      STANDARD20_MODULE_STUFF,
!     create_xhtml_dir_config,    /**< dir config creater */
!     merge_xhtml_dir_configs,    /**< dir config merger */
!     make_xhtml_neg_state,       /**< server config */
!     NULL,                       /**< merge server configs */
!     config_xhtml_cmds,          /**< command table */
!     xhtml_register_hooks,       /**< set up other request processing hooks */
  };