[mod-xhtml-neg-cvs] mod_xhtml_neg mod_xhtml_neg.c,1.20,1.21

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

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

Modified Files:
	mod_xhtml_neg.c 
Log Message:
Added Doxygen compliant comments to the source code.

Index: mod_xhtml_neg.c
===================================================================
RCS file: /cvsroot/mod-xhtml-neg/mod_xhtml_neg/mod_xhtml_neg.c,v
retrieving revision 1.20
retrieving revision 1.21
diff -C2 -d -r1.20 -r1.21
*** mod_xhtml_neg.c	13 Mar 2004 01:35:26 -0000	1.20
--- mod_xhtml_neg.c	24 Mar 2004 09:25:54 -0000	1.21
***************
*** 104,108 ****
--- 104,111 ----
  #include "http_log.h"
  
+ /** Read/write flags used when opening the log file. */
  static int xfer_flags = (O_WRONLY | O_APPEND | O_CREAT);
+ 
+ /** Permission flags used when opening the log file. */
  #if defined(OS2) || defined(WIN32) || defined(NETWARE)
  /* OS/2 dosen't support users and groups */
***************
*** 113,157 ****
  
  /* #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 MODULE_VAR_EXPORT xhtml_neg_module;
  
  typedef struct {
!     char *fname;          /* Name of the log file we write to, if any */
!     int log_fd;           /* File descriptor of the log file, or -1 */
!     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? */
!     array_header *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.
--- 116,197 ----
  
  /* #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 MODULE_VAR_EXPORT 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 */
!     int log_fd;             /**< File descriptor of the log file, or -1 */
!     http_caching cache;     /**< Flag to caching negotiated content
!                               *  in HTTP 1.0 */
  } 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? */
!     array_header *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.
***************
*** 159,164 ****
  
  typedef struct {
!     char *extension;             /* Filename extension */
!     array_header *content_types; /* Array of content accept headers */
  } extension_rec;
  
--- 199,204 ----
  
  typedef struct {
!     char *extension;             /**< Filename extension */
!     array_header *content_types; /**< Array of content accept headers */
  } extension_rec;
  
***************
*** 170,178 ****
   */
  
! /*
   * 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.
   */
  
--- 210,218 ----
   */
  
! /**
   * 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.
   */
  
***************
*** 181,185 ****
  }
  
! /*
   * Re-implement strlen, since relying on it being included somewhere along
   * the way appears to be unsafe.
--- 221,225 ----
  }
  
! /**
   * Re-implement strlen, since relying on it being included somewhere along
   * the way appears to be unsafe.
***************
*** 200,204 ****
  }
  
! /*
   * Compare one string against another in a case-sensitive manner.
   */
--- 240,244 ----
  }
  
! /**
   * Compare one string against another in a case-sensitive manner.
   */
***************
*** 234,238 ****
  }
  
! /*
   * Compare one string against another in a case-insensitive manner.
   */
--- 274,278 ----
  }
  
! /**
   * Compare one string against another in a case-insensitive manner.
   */
***************
*** 277,281 ****
  }
  
! /*
   * 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-sensitive manner.
   * If a NULL byte is encountered, finish comparing at that character.
***************
*** 314,318 ****
  }
  
! /*
   * Compare strings up to a specified limit in a case-insensitive manner.
   * If a NULL byte is encountered, finish comparing at that character.
--- 354,358 ----
  }
  
! /**
   * Compare strings up to a specified limit in a case-insensitive manner.
   * If a NULL byte is encountered, finish comparing at that character.
***************
*** 361,365 ****
  }
  
! /*
   * Determines if the given string end with the given suffix. Case matching
   * can be enabled or disabled.
--- 401,405 ----
  }
  
! /**
   * Determines if the given string end with the given suffix. Case matching
   * can be enabled or disabled.
***************
*** 399,403 ****
  }
  
! /*
   * Given an array of extension_rec records, find one with the given file
   * extension. If a match is found, return the extension_rec, otherwise
--- 439,443 ----
  }
  
! /**
   * Given an array of extension_rec records, find one with the given file
   * extension. If a match is found, return the extension_rec, otherwise
***************
*** 429,433 ****
  }
  
! /*
   * Count the number of stars in an Accept content header. This helps determine
   * priority in case of a tie in q-value priorities.
--- 469,473 ----
  }
  
! /**
   * Count the number of stars in an Accept content header. This helps determine
   * priority in case of a tie in q-value priorities.
***************
*** 451,455 ****
  }
  
! /*
   * Reconstruct the original content-type, if required due to special "charset"
   * values. Normally the content-type will be a plain string without charset
--- 491,495 ----
  }
  
! /**
   * Reconstruct the original content-type, if required due to special "charset"
   * values. Normally the content-type will be a plain string without charset
***************
*** 458,462 ****
   * content-type string.
   *
!  * Todo: should we send the "profile" parameter as well?
   */
  
--- 498,502 ----
   * content-type string.
   *
!  * @todo should we send the "profile" parameter as well?
   */
  
***************
*** 478,482 ****
  }
  
! /*
   * Make a simple hash code for the given accept_rec structure. This allows
   * us to generate unique Etags for accepted content-types. The Etag
--- 518,522 ----
  }
  
! /**
   * Make a simple hash code for the given accept_rec structure. This allows
   * us to generate unique Etags for accepted content-types. The Etag
***************
*** 488,493 ****
   * concatenated as one long string.
   *
!  * Todo:
!  * If the content-type returned ever includes the "profile" parameter,
   * include it as part of the hash code.
   */
--- 528,532 ----
   * concatenated as one long string.
   *
!  * @todo If the content-type returned ever includes the "profile" parameter,
   * include it as part of the hash code.
   */
***************
*** 514,518 ****
  }
  
! /*
   * Merge vlist_validators from different modules. This code is adapted
   * from code in http_protocol.c in the Apache 1.3 core.
--- 553,557 ----
  }
  
! /**
   * Merge vlist_validators from different modules. This code is adapted
   * from code in http_protocol.c in the Apache 1.3 core.
***************
*** 564,568 ****
  
  
! /*
   * 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,
--- 603,607 ----
  
  
! /**
   * 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,
***************
*** 586,594 ****
  }
  
! /*
!  * 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
   */
  
--- 625,633 ----
  }
  
! /* 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.
   */
  
***************
*** 678,683 ****
  }
  
! /*
!  * Dealing with Accept header lines ...
   *
   * The Accept request header is handled by do_accept_line() - it has the
--- 717,722 ----
  }
  
! /**
!  * Deal with Accept header lines.
   *
   * The Accept request header is handled by do_accept_line() - it has the
***************
*** 712,716 ****
  }
  
! /*
   * Deal explicitly with Accept-Charset headers. There is an extra record
   * inserted when neither "*" nor "ISO-8859-1" are mentioned.
--- 751,755 ----
  }
  
! /**
   * Deal explicitly with Accept-Charset headers. There is an extra record
   * inserted when neither "*" nor "ISO-8859-1" are mentioned.
***************
*** 765,769 ****
  }
  
! /*
   * 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.
--- 804,808 ----
  }
  
! /**
   * 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.
***************
*** 920,924 ****
  }
  
! /*
   * Implements the best match algorithm for a given Accept header, possible
   * content-type headers and an optional default content-type in the event of
--- 959,963 ----
  }
  
! /**
   * Implements the best match algorithm for a given Accept header, possible
   * content-type headers and an optional default content-type in the event of
***************
*** 1010,1014 ****
  }
  
! /*
   * 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
--- 1049,1053 ----
  }
  
! /**
   * 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
***************
*** 1039,1044 ****
  }
  
! /*
!  * The actual content-negotiation phase of this module goes here...
   */
  
--- 1078,1083 ----
  }
  
! /**
!  * The actual content-negotiation phase of this module goes here.
   */
  
***************
*** 1066,1070 ****
  
      /* Return OK if either active isn't ON, or stars_ignore is 0. */
!     if( conf->active != ACTIVE_ON ) {
          return OK;
      }
--- 1105,1109 ----
  
      /* Return OK if either active isn't ON, or stars_ignore is 0. */
!     if( conf->active != active_on ) {
          return OK;
      }
***************
*** 1175,1179 ****
           * Similarly to mod_negotiate, we make it configurable.
           */
!         if( xns->cache_negotiated != CACHE_ON ) {
              r->no_cache = 1;
          }
--- 1214,1218 ----
           * Similarly to mod_negotiate, we make it configurable.
           */
!         if( xns->cache != caching_on ) {
              r->no_cache = 1;
          }
***************
*** 1188,1192 ****
  /* All Apache configuration file code goes here... */
  
! /*
   * Is this module active for the given directory.
   */
--- 1227,1231 ----
  /* All Apache configuration file code goes here... */
  
! /**
   * Is this module active for the given directory.
   */
***************
*** 1199,1210 ****
       */
      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.
--- 1238,1249 ----
       */
      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.
***************
*** 1220,1230 ****
  
      if( arg ) {
!         xns->cache_negotiated = CACHE_ON;
      } else {
!         xns->cache_negotiated = CACHE_OFF;
      }
  }
  
! /*
   * Add content types for the given file extension.
   */
--- 1259,1269 ----
  
      if( arg ) {
!         xns->cache = caching_on;
      } else {
!         xns->cache = caching_off;
      }
  }
  
! /**
   * Add content types for the given file extension.
   */
***************
*** 1259,1263 ****
  }
  
! /*
   * Note the minimun number of stars in an Accept token that should be
   * ignored when performing negotiation.
--- 1298,1302 ----
  }
  
! /**
   * Note the minimun number of stars in an Accept token that should be
   * ignored when performing negotiation.
***************
*** 1282,1286 ****
  }
  
! /*
   * Set the log file name for this module.
   */
--- 1321,1325 ----
  }
  
! /**
   * Set the log file name for this module.
   */
***************
*** 1299,1303 ****
  }
  
! /*
   * Create a default XHTML negotiation module configuration record.
   */
--- 1338,1342 ----
  }
  
! /**
   * Create a default XHTML negotiation module configuration record.
   */
***************
*** 1310,1319 ****
      xns->fname = NULL;
      xns->log_fd = -1;
!     xns->cache_negotiated = CACHE_DONTCARE;
  
      return (void *)xns;
  }
  
! /*
   * Create a default directory configuration module.
   */
--- 1349,1358 ----
      xns->fname = NULL;
      xns->log_fd = -1;
!     xns->cache = caching_dontcare;
  
      return (void *)xns;
  }
  
! /**
   * Create a default directory configuration module.
   */
***************
*** 1323,1327 ****
      xhtml_dir_config *new =
          (xhtml_dir_config *) ap_pcalloc(p, sizeof(xhtml_dir_config));
!     new->active = ACTIVE_DONTCARE;
      new->extensions = ap_make_array(p, 5, sizeof(extension_rec));
      new->stars_ignore = -1;
--- 1362,1366 ----
      xhtml_dir_config *new =
          (xhtml_dir_config *) ap_pcalloc(p, sizeof(xhtml_dir_config));
!     new->active = active_dontcare;
      new->extensions = ap_make_array(p, 5, sizeof(extension_rec));
      new->stars_ignore = -1;
***************
*** 1330,1334 ****
  }
  
! /*
   * Merge configuration info from different directories.
   */
--- 1369,1373 ----
  }
  
! /**
   * Merge configuration info from different directories.
   */
***************
*** 1344,1348 ****
      int i;
  
!     if (add->active == ACTIVE_DONTCARE) {
          new->active = base->active;
      } else {
--- 1383,1387 ----
      int i;
  
!     if (add->active == active_dontcare) {
          new->active = base->active;
      } else {
***************
*** 1373,1377 ****
  }
  
! /*
   * Initialize the log file, if one is specified.
   */
--- 1412,1416 ----
  }
  
! /**
   * Initialize the log file, if one is specified.
   */
***************
*** 1404,1408 ****
  }
  
! /* Apache module declaration. */
  
  command_rec config_xhtml_cmds[] = {
--- 1443,1447 ----
  }
  
! /** Record for registering commands with the Apache 1.3.x server. */
  
  command_rec config_xhtml_cmds[] = {
***************
*** 1422,1446 ****
  };
  
  module MODULE_VAR_EXPORT xhtml_neg_module =
  {
      STANDARD_MODULE_STUFF,
!     init_xhtml_log,             /* initializer */
!     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 */
!     NULL,                       /* handlers */
!     NULL,                       /* filename translation */
!     NULL,                       /* check_user_id */
!     NULL,                       /* check auth */
!     NULL,                       /* check access */
!     NULL,                       /* type_checker */
!     xhtml_negotiate,            /* fixups */
!     NULL,                       /* logger */
!     NULL,                       /* header parser */
!     NULL,                       /* child_init */
!     NULL,                       /* child_exit */
!     NULL                        /* post read-request */
  };
  
--- 1461,1487 ----
  };
  
+ /** Module declaration for registering hooks into the Apache 1.3.x server. */
+ 
  module MODULE_VAR_EXPORT xhtml_neg_module =
  {
      STANDARD_MODULE_STUFF,
!     init_xhtml_log,             /**< initializer */
!     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 */
!     NULL,                       /**< handlers */
!     NULL,                       /**< filename translation */
!     NULL,                       /**< check_user_id */
!     NULL,                       /**< check auth */
!     NULL,                       /**< check access */
!     NULL,                       /**< type_checker */
!     xhtml_negotiate,            /**< fixups */
!     NULL,                       /**< logger */
!     NULL,                       /**< header parser */
!     NULL,                       /**< child_init */
!     NULL,                       /**< child_exit */
!     NULL                        /**< post read-request */
  };