[Modcplusplus-devel] (johnksterling) mod_cplusplus/include cpp_request.h

[Mod C. C. L. <mod...@so...>]

Mod Cplusplus CVS committal

Author  : johnksterling
Project : mod_cplusplus
Module  : include
Dir     : mod_cplusplus/include



Modified Files:
	cpp_request.h 


Log Message:
more documentation fixes
===================================================================
RCS file: /cvsroot/modcplusplus/mod_cplusplus/include/cpp_request.h,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -3 -r1.13 -r1.14
--- cpp_request.h	3 Apr 2005 19:38:24 -0000	1.13
+++ cpp_request.h	23 Apr 2005 12:03:14 -0000	1.14
@@ -189,44 +189,153 @@
     /** \return Array of strings representing content languages **/
     const apr_array_header_t *content_languages() const
     { return mRequest->content_languages; }
-    
+   
+    /** \return variant list validator (if negotiated) **/
     const char *vlist_validator() const { return mRequest->vlist_validator; }
+
+    /** \return If an authentication check was made, this gets set to the user name. */
     const char *user() const { return mRequest->user; }
+
+    /** \return If an authentication check was made, this gets set to the auth type. */
     const char *ap_auth_type() const { return mRequest->ap_auth_type; }
+
+    /** \return The URI without any parsing performed */
     const char *unparsed_uri() const { return mRequest->unparsed_uri; }
+
+    /** \return Just the path portion of the URI */
     const char *uri() const { return mRequest->uri; }
+
+    /** \return The filename on disk corresponding to this response */
     const char *filename() const { return mRequest->filename; }
+
+    /** \return The PATH_INFO extracted from this request */
     const char *path_info() const { return mRequest->path_info; }
+
+    /** \return The QUERY_ARGS extracted from this request */
     const char *args() const { return mRequest->args; }
     
+    /** \return true if this response can not be cached */
     int no_cache() const { return mRequest->no_cache; }
+
+    /** \return true if there is no local copy of this response */
     int no_local_copy() const { return mRequest->no_local_copy; }
     
+    /** \return finfo.protection (st_mode) set to zero if no such file */
     apr_finfo_t finfo() const { return mRequest->finfo; }
+
+    /** \return a struct containing the components of URI */
     apr_uri_t parsed_uri() const { return mRequest->parsed_uri; }
     
+    /** 
+     * \brief pass in a module and this method will returrn you its per-dir config 
+     * \param m a pointer to the static module definition
+     * \return a void pointer to the config structure that was set for module m
+     **/
     void *get_dir_config(module *m);
+
+    /** 
+     * \brief pass in a module and this method will returrn you its per-server config 
+     * \param m a pointer to the static module definition
+     * \return a void pointer to the config structure that was set for module m
+     **/
     void *get_server_config(module *m);
     
+    /**
+     * \brief gives you access to the encoded password sent by the client
+     * \param sent_pw a reference to a string pointer into the request where the password is
+     * \return 0 (OK) if it set the 'pw' argument (and assured
+     *         a correct value in r->user); otherwise it returns 
+     *         an error code, either HTTP_INTERNAL_SERVER_ERROR if things are 
+     *         really confused, HTTP_UNAUTHORIZED if no authentication at all 
+     *         seemed to be in use, or DECLINED if there was authentication but 
+     *         it wasn't Basic (in which case, the caller should presumably 
+     *         decline as well).
+     **/
     int get_basic_auth_pw(const char **sent_pw);
+
+    /**
+     * \brief this method writes a character for this request
+     * \param c the character to write
+     * \return the number of bytes sent
+     **/
     int rputc(int c);
+
+    /**
+     * \brief this method writes a string for this request
+     * \param c the character to write
+     * \return the number of bytes sent
+     **/
     int rputs(const char *str) const;
+
+    /**
+     * \brief writes a buffer for this request
+     * \param buf the content to write
+     * \param nbyte the number of bytes to send from buf
+     * \return the number of bytes sent
+     **/
     int rwrite(const void *buf, int nbyte);
+
+    /**
+     * \brief a printf style way to write data to the request
+     * \param fmt The format string
+     * \param ... Thee arguments used to fill the format string
+     * \return the number of bytes sent
+     **/
     int rprintf(const char *fmt, ...);
+
+    /**
+     * \brief Flushn all the data for this request to the client
+     * \return number of bytes sent
+     **/
     int rflush();
     
+    /**
+     * \brief the allow options tell you what options are set for this request:
+     * indexes, includes, sym links, execcgi
+     * \return a bitmap of the options set
+     **/
     int allow_options() { return ap_allow_options(mRequest); }
+
+    /** \return bitmask of the allowoverrides for this request **/
     int allow_overrides(){ return ap_allow_overrides(mRequest); }
+
+    /** \return default type from the configuration, or text/plain if not set **/
     const char *default_type() { return ap_default_type(mRequest); } 
+
+    /**
+     * \brief WARNING: This is in to be backward compatible, but is not always 
+     * acurate (e.g. if mod_userdir is enabled).  This should not be used
+     * \return the document root from the configuration (not necessarily the active one for this request)
+     **/
     const char *document_root() { return ap_document_root(mRequest); }
+
+    /** \return Lookup the login name of the remote user.  Undefined if it cannot be determined **/
     const char *get_remote_logname() { return ap_get_remote_logname(mRequest); }
+
+    /** \return the server name from the reuqest **/
     const char *get_server_name() { return ap_get_server_name(mRequest); }
+
+    /**
+     * \brief Install a custom response handler for a given status)
+     * \param status the status to hook into
+     * \param str the custom response - it can be a static string, the full path to a file, or a URL
+     **/
     void custom_response(int status, const char *str)
         { ap_custom_response(mRequest, status, (char *)str); }
     
+    /**
+     * \brief run an internal redirect to another URI in this server
+     * \param new_uri the new uri to fire
+     **/
     void internal_redirect(const char *new_uri)
         { ap_internal_redirect(new_uri, mRequest); }
     
+    /**
+     * \brief This function is designed for things like actions or CGI scripts, when
+     * using AddHandler, and you want to preserve the content type across
+     * an internal redirect.
+     * \param new_uri the URI to replace the current request with
+     **/
     void internal_redirect_handler(const char *new_uri)
     { ap_internal_redirect(new_uri, mRequest); }