You are viewing a plain text version of this content. The canonical link for it is here.
Posted to apreq-cvs@httpd.apache.org by jo...@apache.org on 2005/03/16 14:59:59 UTC
svn commit: r157753 - in httpd/apreq/branches/multi-env-unstable:
build/doxygen.conf.in include/apreq_error.h include/apreq_module.h
include/apreq_parser.h include/apreq_util.h module/apache2/filter.c
Author: joes
Date: Wed Mar 16 05:59:58 2005
New Revision: 157753
URL: http://svn.apache.org/viewcvs?view=rev&rev=157753
Log:
Doxygen fixes.
Modified:
httpd/apreq/branches/multi-env-unstable/build/doxygen.conf.in
httpd/apreq/branches/multi-env-unstable/include/apreq_error.h
httpd/apreq/branches/multi-env-unstable/include/apreq_module.h
httpd/apreq/branches/multi-env-unstable/include/apreq_parser.h
httpd/apreq/branches/multi-env-unstable/include/apreq_util.h
httpd/apreq/branches/multi-env-unstable/module/apache2/filter.c
Modified: httpd/apreq/branches/multi-env-unstable/build/doxygen.conf.in
URL: http://svn.apache.org/viewcvs/httpd/apreq/branches/multi-env-unstable/build/doxygen.conf.in?view=diff&r1=157752&r2=157753
==============================================================================
--- httpd/apreq/branches/multi-env-unstable/build/doxygen.conf.in (original)
+++ httpd/apreq/branches/multi-env-unstable/build/doxygen.conf.in Wed Mar 16 05:59:58 2005
@@ -27,13 +27,13 @@
WARN_IF_DOC_ERROR = YES
WARN_FORMAT = "$file:$line: $text"
-INPUT = . include library module/apache module/apache2
-FILE_PATTERNS = *.c *.h *.dox CHANGES STATUS
+INPUT = . include module/apache module/apache2
+FILE_PATTERNS = *.h *.dox CHANGES STATUS
RECURSIVE = NO
+EXTRACT_STATIC = YES
EXCLUDE =
EXCLUDE_SYMLINKS = NO
-EXCLUDE_PATTERNS = apreq_tables* \
- apreq_config*
+EXCLUDE_PATTERNS = apreq_config* apreq_private*
EXAMPLE_PATH = .
EXAMPLE_PATTERNS = README INSTALL LICENSE NOTICE *.html *.man
IMAGE_PATH =
Modified: httpd/apreq/branches/multi-env-unstable/include/apreq_error.h
URL: http://svn.apache.org/viewcvs/httpd/apreq/branches/multi-env-unstable/include/apreq_error.h?view=diff&r1=157752&r2=157753
==============================================================================
--- httpd/apreq/branches/multi-env-unstable/include/apreq_error.h (original)
+++ httpd/apreq/branches/multi-env-unstable/include/apreq_error.h Wed Mar 16 05:59:58 2005
@@ -24,42 +24,64 @@
extern "C" {
#endif
+/**
+ * apreq's wrapper around apr_strerror();
+ * recognizes APREQ_ERROR_* status codes.
+ */
APREQ_DECLARE(char *)
apreq_strerror(apr_status_t s, char *buf, apr_size_t bufsize);
/**
- * Beginning work on error-codes ...
- *
+ * @file apreq_error.h
+ * @brief Error status codes.
+ * @ingroup libapreq2
*
+ * Define the APREQ_ error codes.
*/
+
#ifndef APR_EBADARG
#define APR_EBADARG APR_BADARG /* XXX: don't use APR_BADARG */
#endif
-/* 0's: generic error status codes */
+/** Internal apreq error. */
#define APREQ_ERROR_GENERAL APR_OS_START_USERERR
+/** Attempted to perform unsafe action with tainted data. */
#define APREQ_ERROR_TAINTED (APREQ_ERROR_GENERAL + 1)
+/** Parsing interrupted. */
+#define APREQ_ERROR_INTERRUPT (APREQ_ERROR_GENERAL + 2)
-/* 10's: malformed input */
+
+/** Invalid input data. */
#define APREQ_ERROR_BADDATA (APREQ_ERROR_GENERAL + 10)
-#define APREQ_ERROR_BADSEQ (APREQ_ERROR_BADDATA + 1)
-#define APREQ_ERROR_BADCHAR (APREQ_ERROR_BADDATA + 2)
-#define APREQ_ERROR_BADTOKEN (APREQ_ERROR_BADDATA + 3)
-#define APREQ_ERROR_NOTOKEN (APREQ_ERROR_BADDATA + 4)
-#define APREQ_ERROR_BADATTR (APREQ_ERROR_BADDATA + 5)
-#define APREQ_ERROR_BADHEADER (APREQ_ERROR_BADDATA + 6)
+/** Invalid character. */
+#define APREQ_ERROR_BADCHAR (APREQ_ERROR_BADDATA + 1)
+/** Invalid byte sequence. */
+#define APREQ_ERROR_BADSEQ (APREQ_ERROR_BADDATA + 2)
+/** Invalid attribute. */
+#define APREQ_ERROR_BADATTR (APREQ_ERROR_BADDATA + 3)
+/** Invalid header. */
+#define APREQ_ERROR_BADHEADER (APREQ_ERROR_BADDATA + 4)
+
-/* 20's: missing input */
+/** Missing input data. */
#define APREQ_ERROR_NODATA (APREQ_ERROR_GENERAL + 20)
-#define APREQ_ERROR_NOATTR (APREQ_ERROR_NODATA + 1)
-#define APREQ_ERROR_NOHEADER (APREQ_ERROR_NODATA + 2)
-#define APREQ_ERROR_NOPARSER (APREQ_ERROR_NODATA + 3)
-#define APREQ_ERROR_INTERRUPT (APREQ_ERROR_NODATA + 4)
+/** Missing required token. */
+#define APREQ_ERROR_NOTOKEN (APREQ_ERROR_NODATA + 1)
+/** Missing attribute. */
+#define APREQ_ERROR_NOATTR (APREQ_ERROR_NODATA + 2)
+/** Missing header. */
+#define APREQ_ERROR_NOHEADER (APREQ_ERROR_NODATA + 3)
+/** Missing parser. */
+#define APREQ_ERROR_NOPARSER (APREQ_ERROR_NODATA + 4)
+
-/* 30's: configuration conflicts */
+/** Conflicting information. */
#define APREQ_ERROR_MISMATCH (APREQ_ERROR_GENERAL + 30)
+/** Exceeds configured maximum limit. */
#define APREQ_ERROR_OVERLIMIT (APREQ_ERROR_MISMATCH + 1)
+/** Below configured minimum limit. */
#define APREQ_ERROR_UNDERLIMIT (APREQ_ERROR_MISMATCH + 2)
+/** Setting already configured. */
#define APREQ_ERROR_NOTEMPTY (APREQ_ERROR_MISMATCH + 3)
Modified: httpd/apreq/branches/multi-env-unstable/include/apreq_module.h
URL: http://svn.apache.org/viewcvs/httpd/apreq/branches/multi-env-unstable/include/apreq_module.h?view=diff&r1=157752&r2=157753
==============================================================================
--- httpd/apreq/branches/multi-env-unstable/include/apreq_module.h (original)
+++ httpd/apreq/branches/multi-env-unstable/include/apreq_module.h Wed Mar 16 05:59:58 2005
@@ -97,8 +97,16 @@
} apreq_module_t;
+/**
+ * Defines the module-specific status codes which
+ * are commonly considered to be non-fatal.
+ *
+ * @param s status code returned by an apreq_module_t method.
+ *
+ * @return 1 if s is fatal, 0 otherwise.
+ */
static APR_INLINE
-unsigned char apreq_module_status_is_error(apr_status_t s) {
+unsigned apreq_module_status_is_error(apr_status_t s) {
switch (s) {
case APR_SUCCESS:
case APR_INCOMPLETE:
@@ -115,12 +123,12 @@
/**
* Expose the parsed "cookie" header associated to this handle.
- * @param req the apreq request handle
- * @arg t The resulting table, or which may point to NULL
- * when the return value is not APR_SUCCESS. Otherwise
- * it must point to a valid table object.
- * @return APR_SUCCESS on success.
- * @return APREQ_ERROR_NODATA if no "Cookie" header data is available.
+ *
+ * @param req The request handle
+ * @param t The resulting table, which will either be NULL or a
+ * valid table object on return.
+ *
+ * @return APR_SUCCESS or a module-specific error status code.
*/
static APR_INLINE
apr_status_t apreq_jar(apreq_handle_t *req, const apr_table_t **t)
@@ -130,12 +138,12 @@
/**
* Expose the parsed "query string" associated to this handle.
- * @param req the apreq request handle
- * @arg t The resulting table, or which may point to NULL
- * when the return value is not APR_SUCCESS. Otherwise
- * it must point to a valid table object.
- * @return APR_SUCCESS on success.
- * @return APREQ_ERROR_NODATA if no query string is available.
+ *
+ * @param req The request handle
+ * @param t The resulting table, which will either be NULL or a
+ * valid table object on return.
+ *
+ * @return APR_SUCCESS or a module-specific error status code.
*/
static APR_INLINE
apr_status_t apreq_args(apreq_handle_t *req, const apr_table_t **t)
@@ -145,13 +153,12 @@
/**
* Expose the parsed "request body" associated to this handle.
- * @param req the apreq request handle
- * @arg t The resulting table, or which may point to NULL
- * when the return value is not APR_SUCCESS. Otherwise
- * it must point to a valid table object.
- * @return APR_SUCCESS on success.
- * @return APREQ_ERROR_NODATA if no request content is available.
- * @remark Will parse the request as necessary.
+ *
+ * @param req The request handle
+ * @param t The resulting table, which will either be NULL or a
+ * valid table object on return.
+ *
+ * @return APR_SUCCESS or a module-specific error status code.
*/
static APR_INLINE
apr_status_t apreq_body(apreq_handle_t *req, const apr_table_t **t)
@@ -162,9 +169,11 @@
/**
* Fetch the first cookie with the given name.
- * @param req the apreq request handle
- * @arg name Case-insensitive cookie name.
- * @return Desired cookie, or NULL if none match.
+ *
+ * @param req The request handle
+ * @param name Case-insensitive cookie name.
+ *
+ * @return First matching cookie, or NULL if none match.
*/
static APR_INLINE
apreq_cookie_t *apreq_jar_get(apreq_handle_t *req, const char *name)
@@ -174,9 +183,11 @@
/**
* Fetch the first query string param with the given name.
- * @param req the apreq request handle
- * @arg name Case-insensitive param name.
- * @return Desired param, or NULL if none match.
+ *
+ * @param req The request handle
+ * @param name Case-insensitive param name.
+ *
+ * @return First matching param, or NULL if none match.
*/
static APR_INLINE
apreq_param_t *apreq_args_get(apreq_handle_t *req, const char *name)
@@ -185,11 +196,12 @@
}
/**
- * Fetch the first cookie with the given name.
- * @param req the apreq request handle
- * @arg name Case-insensitive cookie name.
- * @return Desired cookie, or NULL if none match.
- * @remark Will parse the request as necessary.
+ * Fetch the first body param with the given name.
+ *
+ * @param req The request handle
+ * @param name Case-insensitive cookie name.
+ *
+ * @return First matching param, or NULL if none match.
*/
static APR_INLINE
apreq_param_t *apreq_body_get(apreq_handle_t *req, const char *name)
@@ -199,11 +211,11 @@
/**
* Fetch the active body parser.
- * @param req the apreq request handle
- * @arg parser Points to the active parser on return.
- * @return Parser's current status. Use apreq_body
- * if you need its final status (the return values
- * will be identical once the parser has finished).
+ *
+ * @param req The request handle
+ * @param parser Points to the active parser on return.
+ *
+ * @return APR_SUCCESS or module-specific error.
*
*/
static APR_INLINE
@@ -216,9 +228,11 @@
/**
* Set the body parser for this request.
- * @param req the apreq request handle
- * @arg parser New parser to use.
- * @return APR_SUCCESS if the action was succesful, error otherwise.
+ *
+ * @param req The request handle
+ * @param parser New parser to use.
+ *
+ * @return APR_SUCCESS or module-specific error.
*/
static APR_INLINE
apr_status_t apreq_parser_set(apreq_handle_t *req,
@@ -229,9 +243,11 @@
/**
* Add a parser hook for this request.
- * @param req the apreq request handle
- * @arg hook Hook to add.
- * @return APR_SUCCESS if the action was succesful, error otherwise.
+ *
+ * @param req The request handle
+ * @param hook Hook to add.
+ *
+ * @return APR_SUCCESS or module-specific error.
*/
static APR_INLINE
apr_status_t apreq_hook_add(apreq_handle_t *req, apreq_hook_t *hook)
@@ -243,9 +259,11 @@
/**
* Fetch the header value (joined by ", " if there are multiple headers)
* for a given header name.
- * @param req the apreq request handle
+ *
+ * @param req The request handle.
* @param name The header name.
- * @return The value of the header, NULL if not found.
+ *
+ * @return The value of the header, or NULL if not found.
*/
static APR_INLINE
const char *apreq_header_in(apreq_handle_t *req, const char *name)
@@ -256,12 +274,13 @@
/**
* Add a header field to the environment's outgoing response headers
- * @param req the apreq request handle
+ *
+ * @param req The request handle
* @param name The name of the outgoing header.
- * @param val Value of the outgoing header.
- * @return APR_SUCCESS on success, error code otherwise.
+ * @param val Value of the outgoing header.
+ *
+ * @return APR_SUCCESS or module-specific error code.
*/
-
static APR_INLINE
apr_status_t apreq_header_out(apreq_handle_t *req,
const char *name, char *val)
@@ -269,7 +288,15 @@
return req->module->header_out(req, name, val);
}
-
+/**
+ * Set the active brigade limit.
+ *
+ * @param req The handle.
+ * @param bytes New limit to use.
+ *
+ * @return APR_SUCCESS or module-specific error.
+ *
+ */
static APR_INLINE
apr_status_t apreq_brigade_limit_set(apreq_handle_t *req,
apr_size_t bytes)
@@ -277,6 +304,15 @@
return req->module->brigade_limit_set(req, bytes);
}
+/**
+ * Get the active brigade limit.
+ *
+ * @param req The handle.
+ * @param bytes Pointer to resulting (current) limit.
+ *
+ * @return APR_SUCCESS or a module-specific error,
+ * which may leave bytes undefined.
+ */
static APR_INLINE
apr_status_t apreq_brigade_limit_get(apreq_handle_t *req,
apr_size_t *bytes)
@@ -284,6 +320,15 @@
return req->module->brigade_limit_get(req, bytes);
}
+/**
+ * Set the active read limit.
+ *
+ * @param req The handle.
+ * @param bytes New limit to use.
+ *
+ * @return APR_SUCCESS or a module-specific error.
+ *
+ */
static APR_INLINE
apr_status_t apreq_read_limit_set(apreq_handle_t *req,
apr_uint64_t bytes)
@@ -291,6 +336,15 @@
return req->module->read_limit_set(req, bytes);
}
+/**
+ * Get the active read limit.
+ *
+ * @param req The request handle.
+ * @param bytes Pointer to resulting (current) limit.
+ *
+ * @return APR_SUCCESS or a module-specific error,
+ * which may leave bytes undefined.
+ */
static APR_INLINE
apr_status_t apreq_read_limit_get(apreq_handle_t *req,
apr_uint64_t *bytes)
@@ -298,12 +352,30 @@
return req->module->read_limit_get(req, bytes);
}
+/**
+ * Set the active temp directory.
+ *
+ * @param req The handle.
+ * @param path New path to use; may be NULL.
+ *
+ * @return APR_SUCCESS or a module-specific error .
+ */
static APR_INLINE
apr_status_t apreq_temp_dir_set(apreq_handle_t *req, const char *path)
{
return req->module->temp_dir_set(req, path);
}
+/**
+ * Get the active temp directory.
+ *
+ * @param req The handle.
+ * @param path Resulting path to temp dir.
+ *
+ * @return APR_SUCCESS implies path is valid, but may also be NULL.
+ * Any other return value is module-specific, and may leave
+ * path undefined.
+ */
static APR_INLINE
apr_status_t apreq_temp_dir_get(apreq_handle_t *req, const char **path)
{
@@ -315,9 +387,11 @@
/**
* Convenience macro for defining a module by mapping
* a function prefix to an associated apreq_module_t structure.
+ *
* @param pre Prefix to define new environment. All attributes of
- * the apreq_env_module_t struct are defined with this as their prefix. The
- * generated struct is named by appending "_module" to the prefix.
+ * the apreq_env_module_t struct are defined with this as their
+ * prefix. The generated struct is named by appending "_module" to
+ * the prefix.
* @param mmn Magic number (i.e. version number) of this environment.
*/
#define APREQ_MODULE(pre, mmn) const apreq_module_t \
@@ -330,9 +404,17 @@
pre##_temp_dir_get, pre##_temp_dir_set, \
pre##_header_in, pre##_header_out }
+
/**
* Create an apreq handle which is suitable for a CGI program. It
* reads input from stdin and writes output to stdout.
+ *
+ * @param pool Pool associated to this handle.
+ *
+ * @return New handle; can only be NULL if the pool allocation failed.
+ *
+ * @remarks The handle gets cached in the pool's userdata, so subsequent
+ * calls will retrieve the original cached handle.
*/
APREQ_DECLARE(apreq_handle_t*) apreq_handle_cgi(apr_pool_t *pool);
@@ -340,13 +422,16 @@
* Create a custom apreq handle which knows only some static
* values. Useful if you want to test the parser code or if you have
* got data from a custom source (neither Apache 2 nor CGI).
- * @param pool the APR pool
- * @param query_string the query string
- * @param cookie value of the request "Cookie" header
- * @param cookie2 value of the request "Cookie2" header
- * @param parser parser for handling the request body
- * @param read_limit maximum number of bytes to read from the body
- * @param in a bucket brigade containing the request body
+ *
+ * @param pool allocates the parse data,
+ * @param query_string parsed into args table
+ * @param cookie value of the request "Cookie" header
+ * @param cookie2 value of the request "Cookie2" header
+ * @param parser parses the request body
+ * @param read_limit maximum bytes to read from the body
+ * @param in brigade containing the request body
+ *
+ * @return new handle; can only be NULL if the pool allocation failed.
*/
APREQ_DECLARE(apreq_handle_t*) apreq_handle_custom(apr_pool_t *pool,
const char *query_string,
@@ -359,8 +444,10 @@
/**
* Add the cookie to the outgoing "Set-Cookie" headers.
*
- * @param c The cookie.
- * @param req the apreq request handle
+ * @param c The cookie.
+ * @param req The request handle which set the outgoing header.
+ *
+ * @return APR_SUCCESS or error.
*/
APREQ_DECLARE(apr_status_t) apreq_cookie_bake(const apreq_cookie_t *c,
apreq_handle_t *req);
@@ -368,41 +455,56 @@
/**
* Add the cookie to the outgoing "Set-Cookie2" headers.
*
- * @param c The cookie.
- * @param req the apreq request handle
+ * @param c cookie
+ * @param req request handle
+ *
+ * @return APR_SUCCESS or error.
*/
APREQ_DECLARE(apr_status_t) apreq_cookie_bake2(const apreq_cookie_t *c,
apreq_handle_t *req);
/**
* Looks for the presence of a "Cookie2" header to determine whether
- * or not the current User-Agent supports rfc2965.
+ * or not the current User-Agent responsible for this request supports
+ * rfc2965.
+ *
* @param req the apreq request handle
- * @return APREQ_COOKIE_VERSION_RFC if rfc2965 is supported,
- * APREQ_COOKIE_VERSION_NETSCAPE otherwise.
+ *
+ * @return ::APREQ_COOKIE_VERSION_RFC if rfc2965 is supported
+ * by the user-agent, ::APREQ_COOKIE_VERSION_NETSCAPE otherwise.
*/
APREQ_DECLARE(unsigned)apreq_ua_cookie_version(apreq_handle_t *req);
/**
* Find the first query string parameter or body parameter with the
- * specified name.
+ * specified name. The match is case-insensitive.
*
- * @param req the apreq request handle
- * @param key the requested parameter name
- * @return the parameter, or NULL if not found
- * @remark Will parse the request as necessary.
+ * @param req request handle.
+ * @param key desired parameter name
+ *
+ * @return The first matching parameter (with args searched first) or NULL.
*/
APREQ_DECLARE(apreq_param_t *)apreq_param(apreq_handle_t *req, const char *key);
+/**
+ * Find the first cookie with the specified name.
+ * The match is case-insensitive.
+ *
+ * @param req request handle.
+ * @param key desired cookie name
+ *
+ * @return The first matching parameter (with args searched first) or NULL.
+ */
#define apreq_cookie(req, name) apreq_jar_get(req, name)
/**
* Returns a table containing key-value pairs for the full request
* (args + body).
*
- * @param req the apreq request handle
- * @param p Allocates the returned table.
- * @remark Also parses the request if necessary.
+ * @param req request handle
+ * @param p allocates the returned table.
+ *
+ * @return table representing all available params; is never NULL.
*/
APREQ_DECLARE(apr_table_t *) apreq_params(apreq_handle_t *req, apr_pool_t *p);
@@ -416,13 +518,13 @@
APREQ_DECLARE(apr_table_t *)apreq_cookies(apreq_handle_t *req, apr_pool_t *p);
/**
- * Force a complete parse.
- * @param req the apreq request handle
- * @return APR_SUCCESS on an error-free parse of the request data.
- * Any other status code indicates a problem somewhere.
+ * Force a complete parse of everything.
+ *
+ * @param req The request handle
*
+ * @return APR_SUCCESS on an error-free parse of the request data.
+ * Any other status code indicates a potential problem somewhere.
*/
-
static APR_INLINE
apr_status_t apreq_parse(apreq_handle_t *req)
{
Modified: httpd/apreq/branches/multi-env-unstable/include/apreq_parser.h
URL: http://svn.apache.org/viewcvs/httpd/apreq/branches/multi-env-unstable/include/apreq_parser.h?view=diff&r1=157752&r2=157753
==============================================================================
--- httpd/apreq/branches/multi-env-unstable/include/apreq_parser.h (original)
+++ httpd/apreq/branches/multi-env-unstable/include/apreq_parser.h Wed Mar 16 05:59:58 2005
@@ -142,22 +142,22 @@
/**
- * Rfc822 Header parser. It will reject all data
+ * RFC 822 Header parser. It will reject all data
* after the first CRLF CRLF sequence (an empty line).
- * See #apreq_run_parser for more info on rejected data.
+ * See apreq_parser_run() for more info on rejected data.
*/
APREQ_DECLARE_PARSER(apreq_parse_headers);
/**
- * Rfc2396 application/x-www-form-urlencoded parser.
+ * RFC 2396 application/x-www-form-urlencoded parser.
*/
APREQ_DECLARE_PARSER(apreq_parse_urlencoded);
/**
- * Rfc2388 multipart/form-data (and XForms 1.0 multipart/related)
+ * RFC 2388 multipart/form-data (and XForms 1.0 multipart/related)
* parser. It will reject any buckets representing preamble and
* postamble text (this is normal behavior, not an error condition).
- * See #apreq_run_parser for more info on rejected data.
+ * See apreq_parser_run() for more info on rejected data.
*/
APREQ_DECLARE_PARSER(apreq_parse_multipart);
@@ -244,9 +244,8 @@
* @param enctype The MIME type.
* @param pfn The function to use during parsing. Setting
* parser == NULL will remove an existing parser.
- * @remark This is not a thread-safe operation, so applications
- * should only call this during process startup,
- * or within a request-thread mutex.
+ *
+ * @return APR_SUCCESS or error.
*/
APREQ_DECLARE(apr_status_t) apreq_register_parser(const char *enctype,
Modified: httpd/apreq/branches/multi-env-unstable/include/apreq_util.h
URL: http://svn.apache.org/viewcvs/httpd/apreq/branches/multi-env-unstable/include/apreq_util.h?view=diff&r1=157752&r2=157753
==============================================================================
--- httpd/apreq/branches/multi-env-unstable/include/apreq_util.h (original)
+++ httpd/apreq/branches/multi-env-unstable/include/apreq_util.h Wed Mar 16 05:59:58 2005
@@ -47,7 +47,7 @@
* @param arr Array of apreq_value_t entries.
* @param mode Join type- see apreq_join_t.
*
- * @return Resulting string or NULL on error
+ * @return Joined string, or NULL on error
*/
APREQ_DECLARE(char *) apreq_join(apr_pool_t *p,
const char *sep,
@@ -63,7 +63,7 @@
* @param nlen Length of search string.
* @param type Match type.
*
- * @return Offset of match string, or -1 if mo match is found.
+ * @return Offset of match string, or -1 if no match is found.
*
*/
APREQ_DECLARE(apr_ssize_t) apreq_index(const char* hay, apr_size_t hlen,
@@ -86,6 +86,7 @@
const apr_size_t slen);
/**
+ *
* Same as apreq_quote() except when src begins and ends in quote marks. In
* that case it assumes src is quoted correctly, and just copies src to dest.
*
@@ -122,11 +123,13 @@
* @param src Original string.
* @param slen Length of original string.
*
- * @return ::APR_SUCCESS.
+ * @return APR_SUCCESS.
* @return ::APREQ_ERROR_BADSEQ or ::APREQ_ERROR_BADCHAR on malformed input.
*
- * @remarks In the non-APR_SUCCESS case, dlen will be set to include
- * the last succesfully decoded value.
+ * @remarks In the non-success case, dlen will be set to include
+ * the last succesfully decoded value. This function decodes
+ * \%uXXXX into a utf8 (wide) character, following ECMA-262
+ * (the Javascript spec) Section B.2.1.
*/
APREQ_DECLARE(apr_status_t) apreq_decode(char *dest, apr_size_t *dlen,
@@ -141,13 +144,15 @@
* @param v Array of iovecs that represent the source string
* @param nelts Number of iovecs in the array.
*
- * @return ::APR_SUCCESS.
- * @return ::APR_INCOMPLETE if the iovec ends in the middle of an %XX escape
+ * @return APR_SUCCESS.
+ * @return ::APR_INCOMPLETE if the iovec ends in the middle of an \%XX escape
* sequence.
* @return ::APREQ_ERROR_BADSEQ or ::APREQ_ERROR_BADCHAR on malformed input.
*
* @remarks In the non-APR_SUCCESS case, dlen will be set to include
- * the last succesfully decoded value.
+ * the last succesfully decoded value. This function decodes
+ * \%uXXXX into a utf8 (wide) character, following ECMA-262
+ * (the Javascript spec) Section B.2.1.
*/
APREQ_DECLARE(apr_status_t) apreq_decodev(char *dest, apr_size_t *dlen,
@@ -162,8 +167,8 @@
*
* @return The url-encoded string.
*
- * @remarks Use this function insead of apreq_encode if its
- * caller might otherwise overflow dest.
+ * @remarks Use this function insead of apreq_encode if its
+ * caller might otherwise overflow dest.
*/
static APR_INLINE
char *apreq_escape(apr_pool_t *p, const char *src, const apr_size_t slen)
@@ -184,13 +189,11 @@
* @param str The string to decode
*
* @return Length of decoded string, or < 0 on error.
- *
- * @remarks Equivalent to apreq_decode(str,str,strlen(str)).
*/
static APR_INLINE apr_ssize_t apreq_unescape(char *str)
{
apr_size_t len;
- apr_status_t rv = apreq_decode(str,&len,str,strlen(str));
+ apr_status_t rv = apreq_decode(str, &len, str, strlen(str));
if (rv == APR_SUCCESS)
return (apr_ssize_t)len;
else
@@ -204,8 +207,8 @@
*
* @return 64-bit integer representation of s.
*
- * @remarks XXX What happens when s is malformed? Should this return
- * an unsigned value instead?
+ * @todo What happens when s is malformed? Should this return
+ * an unsigned value instead?
*/
APREQ_DECLARE(apr_int64_t) apreq_atoi64f(const char *s);
@@ -217,8 +220,8 @@
*
* @return 64-bit integer representation of s as seconds.
*
- * @remarks XXX What happens when s is malformed? Should this return
- * an unsigned value instead?
+ * @todo What happens when s is malformed? Should this return
+ * an unsigned value instead?
*/
APREQ_DECLARE(apr_int64_t) apreq_atoi64t(const char *s);
@@ -232,9 +235,9 @@
* the file.
* @param bb Bucket brigade.
*
- * @return ::APR_SUCCESS.
- * @return XXX error code resulting from apr_bucket_read().
- * @return XXX error code resulting from apr_file_writev().
+ * @return APR_SUCCESS.
+ * @return Error status code from either an unsuccessful apr_bucket_read(),
+ * or a failed apr_file_writev().
*
* @remarks In the future, this function may do something
* intelligent with file buckets.
@@ -254,9 +257,9 @@
* If param == NULL, the directory will be selected via
* tempnam(). See the tempnam manpage for details.
*
- * @return ::APR_SUCCESS.
- * @return XXX error code resulting from apreq_filepath_merge().
- * @return XXX error code resulting from apr_file_mktemp().
+ * @return APR_SUCCESS.
+ * @return Error status code from unsuccessful apr_filepath_merge(),
+ * or a failed apr_file_mktemp().
*/
APREQ_DECLARE(apr_status_t) apreq_file_mktemp(apr_file_t **fp,
@@ -268,17 +271,22 @@
*
* @param bb Brigade.
* @param p Setaside buckets into this pool.
+ * @return APR_SUCCESS.
+ * @return Error status code from an unsuccessful apr_bucket_setaside().
*/
static APR_INLINE
-void apreq_brigade_setaside(apr_bucket_brigade *bb, apr_pool_t *p)
+apr_status_t apreq_brigade_setaside(apr_bucket_brigade *bb, apr_pool_t *p)
{
apr_bucket *e;
for (e = APR_BRIGADE_FIRST(bb); e != APR_BRIGADE_SENTINEL(bb);
e = APR_BUCKET_NEXT(e))
{
- apr_bucket_setaside(e, p);
+ apr_status_t rv = apr_bucket_setaside(e, p);
+ if (rv != APR_SUCCESS)
+ return rv;
}
+ return APR_SUCCESS;
}
@@ -288,19 +296,26 @@
* @param d (destination) Copied buckets are appended to this brigade.
* @param s (source) Brigade to copy from.
*
+ * @return APR_SUCCESS.
+ * @return Error status code from an unsuccessful apr_bucket_copy().
+ *
* @remarks s == d produces Undefined Behavior.
*/
static APR_INLINE
-void apreq_brigade_copy(apr_bucket_brigade *d, apr_bucket_brigade *s) {
+apr_status_t apreq_brigade_copy(apr_bucket_brigade *d, apr_bucket_brigade *s) {
apr_bucket *e;
for (e = APR_BRIGADE_FIRST(s); e != APR_BRIGADE_SENTINEL(s);
e = APR_BUCKET_NEXT(e))
{
apr_bucket *c;
- apr_bucket_copy(e, &c); /*XXX may fail! */
+ apr_status_t rv = apr_bucket_copy(e, &c);
+ if (rv != APR_SUCCESS)
+ return rv;
+
APR_BRIGADE_INSERT_TAIL(d, c);
}
+ return APR_SUCCESS;
}
/**
@@ -343,9 +358,9 @@
* @param val Location of (first) matching value.
* @param vlen Length of matching value.
*
- * @return ::APR_SUCCESS.
- * @return ::APREQ_ERROR_NOATTR if the attribute isn't found.
- * @return ::APREQ_ERROR_BADTOKEN if the header is unparseable.
+ * @return APR_SUCCESS.
+ * @return ::APREQ_ERROR_NOATTR if the attribute is not found.
+ * @return ::APREQ_ERROR_BADSEQ if an unpaired quote mark was detected.
*/
APREQ_DECLARE(apr_status_t) apreq_header_attribute(const char *hdr,
const char *name,
@@ -356,8 +371,7 @@
/**
* Concatenates the brigades, spooling large brigades into
- * a tempfile bucket according to the environment's max_brigade
- * setting- see apreq_env_max_brigade().
+ * a tempfile (APREQ_SPOOL) bucket.
*
* @param pool Pool for creating a tempfile bucket.
* @param temp_dir Directory for tempfile creation.
@@ -366,11 +380,11 @@
* @param out Resulting brigade.
* @param in Brigade to append.
*
- * @return ::APR_SUCCESS.
- * @return XXX error code resulting from apr_brigade_length().
- * @return XXX error code resulting from apreq_file_mktemp().
- * @return XXX error code resulting from apreq_brigade_fwrite().
- * @return XXX error code resulting from apr_file_seek().
+ * @return APR_SUCCESS.
+ * @return Error status code resulting from either apr_brigade_length(),
+ * apreq_file_mktemp(), apreq_brigade_fwrite(), or apr_file_seek().
+ *
+ * @todo Flesh out these error codes, making them as explicit as possible.
*/
APREQ_DECLARE(apr_status_t) apreq_brigade_concat(apr_pool_t *pool,
const char *temp_dir,
@@ -380,11 +394,11 @@
/**
* Determines the spool file used by the brigade. Returns NULL if the
- * brigade is not spooled in a file (does not use a APREQ_SPOOL
+ * brigade is not spooled in a file (does not use an APREQ_SPOOL
* bucket).
*
* @param bb the bucket brigade
- * @return the spool file, or NULL
+ * @return the spool file, or NULL.
*/
APREQ_DECLARE(apr_file_t *)apreq_brigade_spoolfile(apr_bucket_brigade *bb);
Modified: httpd/apreq/branches/multi-env-unstable/module/apache2/filter.c
URL: http://svn.apache.org/viewcvs/httpd/apreq/branches/multi-env-unstable/module/apache2/filter.c?view=diff&r1=157752&r2=157753
==============================================================================
--- httpd/apreq/branches/multi-env-unstable/module/apache2/filter.c (original)
+++ httpd/apreq/branches/multi-env-unstable/module/apache2/filter.c Wed Mar 16 05:59:58 2005
@@ -432,7 +432,7 @@
break;
case AP_MODE_EXHAUSTIVE: /* not worth supporting at this level */
- case AP_MODE_GETLINE: /* punt- chunked trailers are b0rked in ap_http_filter */
+ case AP_MODE_GETLINE: /* chunked trailers are b0rked in ap_http_filter */
return ap_get_brigade(f->next, bb, mode, block, readbytes);
default: