--------------------- PatchSet 5216 Date: 2007/08/09 22:46:34 Author: amosjeffries Branch: docs Tag: (none) Log: Migrate Error Pages documentation. Members: doc/Programming-Guide/22_ErrorPages.dox:1.1.2.1->1.1.2.2(DEAD) src/errorpage.cc:1.46->1.46.2.1 src/errorpage.h:1.3->1.3.2.1 --- squid3/doc/Programming-Guide/22_ErrorPages.dox Fri Aug 10 00:19:03 2007 +++ /dev/null Fri Aug 10 00:19:03 2007 @@ -1,8 +0,0 @@ -/** -\page 22_ErrorPages Error Pages - -\section Infrastructure Infrastructure - -\todo Write documentation on Error Pages - - */ Index: squid3/src/errorpage.cc =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/errorpage.cc,v retrieving revision 1.46 retrieving revision 1.46.2.1 diff -u -r1.46 -r1.46.2.1 --- squid3/src/errorpage.cc 9 May 2007 09:51:14 -0000 1.46 +++ squid3/src/errorpage.cc 9 Aug 2007 22:46:35 -0000 1.46.2.1 @@ -1,6 +1,6 @@ /* - * $Id: errorpage.cc,v 1.46 2007/05/09 09:51:14 squidadm Exp $ + * $Id: errorpage.cc,v 1.46.2.1 2007/08/09 22:46:35 amosjeffries Exp $ * * DEBUG: section 4 Error Generation * AUTHOR: Duane Wessels @@ -33,13 +33,6 @@ * */ -/* - * Abstract: These routines are used to generate error messages to be - * sent to clients. The error type is used to select between - * the various message formats. (formats are stored in the - * Config.errorDirectory) - */ - #include "errorpage.h" #include "AuthUserRequest.h" #include "SquidTime.h" @@ -52,25 +45,39 @@ #include "URLScheme.h" #include "wordlist.h" +/** + \defgroup ErrorPageInternal Error Page Internals + \ingroup ErrorPage + * + \section Abstract Abstract: + * These routines are used to generate error messages to be + * sent to clients. The error type is used to select between + * the various message formats. (formats are stored in the + * Config.errorDirectory) + */ + + +/// \ingroup ErrorPageInternal CBDATA_CLASS_INIT(ErrorState); /* local types */ +/// \ingroup ErrorPageInternal typedef struct { int id; char *page_name; } - ErrorDynamicPageInfo; /* local constant and vars */ -/* - * note: hard coded error messages are not appended with %S automagically - * to give you more control on the format +/** +/// \ingroup ErrorPageInternal + * + \note hard coded error messages are not appended with %S + * automagically to give you more control on the format */ - static const struct { int type; /* and page_id */ @@ -94,12 +101,18 @@ } }; +/// \ingroup ErrorPageInternal static Vector ErrorDynamicPages; /* local prototypes */ +/// \ingroup ErrorPageInternal static const int error_hard_text_count = sizeof(error_hard_text) / sizeof(*error_hard_text); + +/// \ingroup ErrorPageInternal static char **error_text = NULL; + +/// \ingroup ErrorPageInternal static int error_page_count = 0; static char *errorTryLoadText(const char *page_name, const char *dir); @@ -113,6 +126,7 @@ static IOCB errorSendComplete; +/// \ingroup ErrorPageInternal err_type &operator++ (err_type &anErr) { int tmp = (int)anErr; @@ -120,20 +134,12 @@ return anErr; } +/// \ingroup ErrorPageInternal int operator - (err_type const &anErr, err_type const &anErr2) { return (int)anErr - (int)anErr2; } -/* - * Function: errorInitialize - * - * Abstract: This function finds the error messages formats, and stores - * them in error_text[]; - * - * Global effects: - * error_text[] - is modified - */ void errorInitialize(void) { @@ -182,6 +188,7 @@ error_page_count = 0; } +/// \ingroup ErrorPageInternal static const char * errorFindHardText(err_type type) { @@ -195,6 +202,7 @@ } +/// \ingroup ErrorPageInternal static char * errorLoadText(const char *page_name) { @@ -212,6 +220,7 @@ return text; } +/// \ingroup ErrorPageInternal static char * errorTryLoadText(const char *page_name, const char *dir) { @@ -255,6 +264,7 @@ return text; } +/// \ingroup ErrorPageInternal static ErrorDynamicPageInfo * errorDynamicPageInfoCreate(int id, const char *page_name) { @@ -264,6 +274,7 @@ return info; } +/// \ingroup ErrorPageInternal static void errorDynamicPageInfoDestroy(ErrorDynamicPageInfo * info) { @@ -272,6 +283,7 @@ delete info; } +/// \ingroup ErrorPageInternal static int errorPageId(const char *page_name) { @@ -303,6 +315,7 @@ return (err_type)id; } +/// \ingroup ErrorPageInternal static const char * errorPageName(int pageId) { @@ -315,11 +328,6 @@ return "ERR_UNKNOWN"; /* should not happen */ } -/* - * Function: errorCon - * - * Abstract: This function creates a ErrorState object. - */ ErrorState * errorCon(err_type type, http_status status, HttpRequest * request) { @@ -336,20 +344,6 @@ return err; } -/* - * Function: errorAppendEntry - * - * Arguments: err - This object is destroyed after use in this function. - * - * Abstract: This function generates a error page from the info contained - * by 'err' and then stores the text in the specified store - * entry. This function should only be called by ``server - * side routines'' which need to communicate errors to the - * client side. It should also be called from client_side.c - * because we now support persistent connections, and - * cannot assume that we can immediately write to the socket - * for an error. - */ void errorAppendEntry(StoreEntry * entry, ErrorState * err) { @@ -384,7 +378,7 @@ entry->buffer(); rep = errorBuildReply(err); /* Add authentication header */ - /* TODO: alter errorstate to be accel on|off aware. The 0 on the next line + /*! \todo alter errorstate to be accel on|off aware. The 0 on the next line * depends on authenticate behaviour: all schemes to date send no extra * data on 407/401 responses, and do not check the accel state on 401/407 * responses @@ -400,25 +394,6 @@ errorStateFree(err); } -/* - * Function: errorSend - * - * Arguments: err - This object is destroyed after use in this function. - * - * Abstract: This function generates a error page from the info contained - * by 'err' and then sends it to the client. - * The callback function errorSendComplete() is called after - * the page has been written to the client socket (fd). - * errorSendComplete() deallocates 'err'. We need to add - * 'err' to the cbdata because comm_write() requires it - * for all callback data pointers. - * - * Note, normally errorSend() should only be called from - * routines in ssl.c and pass.c, where we don't have any - * StoreEntry's. In client_side.c we must allocate a StoreEntry - * for errors and use errorAppendEntry() to account for - * persistent/pipeline connections. - */ void errorSend(int fd, ErrorState * err) { @@ -443,14 +418,14 @@ delete rep; } -/* - * Function: errorSendComplete +/** + \ingroup ErrorPageAPI * - * Abstract: Called by commHandleWrite() after data has been written - * to the client socket. + * Called by commHandleWrite() after data has been written + * to the client socket. * - * Note: If there is a callback, the callback is responsible for - * closeing the FD, otherwise we do it ourseves. + \note If there is a callback, the callback is responsible for + * closeing the FD, otherwise we do it ourseves. */ static void errorSendComplete(int fd, char *bufnotused, size_t size, comm_err_t errflag, int xerrno, void *data) @@ -487,6 +462,7 @@ cbdataFree(err); } +/// \ingroup ErrorPageInternal static int errorDump(ErrorState * err, MemBuf * mb) { @@ -562,41 +538,10 @@ return 0; } +/// \ingroup ErrorPageInternal #define CVT_BUF_SZ 512 -/* - * a - User identity x - * B - URL with FTP %2f hack x - * c - Squid error code x - * d - seconds elapsed since request received x - * e - errno x - * E - strerror() x - * f - FTP request line x - * F - FTP reply line x - * g - FTP server message x - * h - cache hostname x - * H - server host name x - * i - client IP address x - * I - server IP address x - * L - HREF link for more info/contact x - * M - Request Method x - * m - Error message returned by auth helper x - * o - Message returned external acl helper x - * p - URL port # x - * P - Protocol x - * R - Full HTTP Request x - * S - squid signature from ERR_SIGNATURE x - * s - caching proxy software with version x - * t - local time x - * T - UTC x - * U - URL without password x - * u - URL with password x - * w - cachemgr email address x - * W - error data (to be included in the mailto links) - * z - dns server error message x - * Z - Preformatted error message x - */ - +/// \ingroup ErrorPageInternal static const char * errorConvert(char token, ErrorState * err) { @@ -848,7 +793,6 @@ return p; } -/* allocates and initializes an error response */ HttpReply * errorBuildReply(ErrorState * err) { @@ -887,6 +831,7 @@ return rep; } +/// \ingroup ErrorPageInternal static MemBuf * errorBuildContent(ErrorState * err) { Index: squid3/src/errorpage.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/errorpage.h,v retrieving revision 1.3 retrieving revision 1.3.2.1 diff -u -r1.3 -r1.3.2.1 --- squid3/src/errorpage.h 9 May 2007 07:50:41 -0000 1.3 +++ squid3/src/errorpage.h 9 Aug 2007 22:46:35 -0000 1.3.2.1 @@ -1,7 +1,8 @@ - /* - * $Id: errorpage.h,v 1.3 2007/05/09 07:50:41 squidadm Exp $ + * $Id: errorpage.h,v 1.3.2.1 2007/08/09 22:46:35 amosjeffries Exp $ * + * DEBUG: section 4 Error Generation + * AUTHOR: Duane Wessels * * SQUID Web Proxy Cache http://www.squid-cache.org/ * ---------------------------------------------------------- @@ -38,8 +39,53 @@ #include "squid.h" #include "cbdata.h" +/** + \defgroup ErrorPage Error Pages + \ingroup Components + */ + +/** + \defgroup ErrorPageAPI Error Pages API + \ingroup ErrorPage + \section ErrorPageStringCodes Error Page % codes for text insertion. + * + \verbatim + a - User identity x + B - URL with FTP %2f hack x + c - Squid error code x + d - seconds elapsed since request received x + e - errno x + E - strerror() x + f - FTP request line x + F - FTP reply line x + g - FTP server message x + h - cache hostname x + H - server host name x + i - client IP address x + I - server IP address x + L - HREF link for more info/contact x + M - Request Method x + m - Error message returned by auth helper x + o - Message returned external acl helper x + p - URL port # x + P - Protocol x + R - Full HTTP Request x + S - squid signature from ERR_SIGNATURE x + s - caching proxy software with version x + t - local time x + T - UTC x + U - URL without password x + u - URL with password x + w - cachemgr email address x + W - error data (to be included in the mailto links) + z - dns server error message x + Z - Preformatted error message x + \endverbatim + */ + class AuthUserRequest; +/// \ingroup ErrorPageAPI class ErrorState { @@ -84,14 +130,77 @@ CBDATA_CLASS2(ErrorState); }; +/** + \ingroup ErrorPageAPI + * + * This function finds the error messages formats, and stores + * them in error_text[] + * + \par Global effects: + * error_text[] - is modified + */ SQUIDCEXTERN void errorInitialize(void); + +/// \ingroup ErrorPageAPI SQUIDCEXTERN void errorClean(void); + +/** + \ingroup ErrorPageInternal + * Allocates and initializes an error response + */ SQUIDCEXTERN HttpReply *errorBuildReply(ErrorState * err); -SQUIDCEXTERN void errorSend(int fd, ErrorState *); -SQUIDCEXTERN void errorAppendEntry(StoreEntry *, ErrorState *); + +/** + \ingroup ErrorPageAPI + * + * This function generates a error page from the info contained + * by err and then sends it to the client. + * The callback function errorSendComplete() is called after + * the page has been written to the client socket (fd). + * errorSendComplete() deallocates err. We need to add + * err to the cbdata because comm_write() requires it + * for all callback data pointers. + * + \note normally errorSend() should only be called from + * routines in ssl.c and pass.c, where we don't have any + * StoreEntry's. In client_side.c we must allocate a StoreEntry + * for errors and use errorAppendEntry() to account for + * persistent/pipeline connections. + * + \param fd socket where page object is to be written + \param err This object is destroyed after use in this function. + */ +SQUIDCEXTERN void errorSend(int fd, ErrorState *err); + +/** + \ingroup ErrorPageAPI + * + * This function generates a error page from the info contained + * by err and then stores the text in the specified store + * entry. + * This function should only be called by "server + * side routines" which need to communicate errors to the + * client side. It should also be called from client_side.c + * because we now support persistent connections, and + * cannot assume that we can immediately write to the socket + * for an error. + * + \param entry ?? + \param err This object is destroyed after use in this function. + */ +SQUIDCEXTERN void errorAppendEntry(StoreEntry *entry, ErrorState *err); + +/// \ingroup ErrorPageAPI SQUIDCEXTERN void errorStateFree(ErrorState * err); + +/// \ingroup ErrorPageAPI SQUIDCEXTERN err_type errorReservePageId(const char *page_name); -SQUIDCEXTERN ErrorState *errorCon(err_type type, http_status, HttpRequest * request); +/** + \ingroup ErrorPageAPI + * + * This function creates a ErrorState object. + */ +SQUIDCEXTERN ErrorState *errorCon(err_type type, http_status, HttpRequest * request); #endif /* SQUID_ERRORPAGE_H */