Annotation of libwww/Library/src/HTError.html, revision 2.3
2.1 frystyk 1: <HTML>
2: <HEAD>
3: <TITLE>Error message module for libwww</TITLE>
4: <NEXTID N="z1">
5: </HEAD>
6: <BODY>
7: <H1>Error reporting functions</H1>
8:
2.3 ! frystyk 9: This module maintaines a list of error messages that might occur during load of a requested URL. The error list is put out to standard output by a simple function that easily can be overwritten by a smart server or client. It is garanteed that at the moment, HTErrorMsg() is called no stream has been put up or taken down in the library.
2.1 frystyk 10: <PRE>
11: #ifndef HTERROR_H
12: #define HTERROR_H
13: </PRE>
14:
2.3 ! frystyk 15: <H2>Data Structures</H2>
2.1 frystyk 16:
2.3 ! frystyk 17: The basic data structure is HTErrorInfo, but in addition the following types are used:
2.1 frystyk 18:
2.3 ! frystyk 19: <H3>Error Numbers</H3>
2.1 frystyk 20:
21: <B>Note:</B> All non-HTTP error codes have index numbers > HTERR_HTTP_CODES, and they will not be shown in the error-message generated.
22: <PRE>
23: typedef enum _HTErrorElement {
24: HTERR_OK = 0, /* 200 */
25: HTERR_CREATED, /* 201 */
26: HTERR_ACCEPTED, /* 202 */
27: HTERR_PARTIAL, /* 203 */
28: HTERR_NO_RESPONSE, /* 204 */
29: HTERR_MOVED, /* 301 */
30: HTERR_FOUND, /* 302 */
31: HTERR_METHOD, /* 303 */
32: HTERR_NOT_MODIFIED, /* 304 */
33: HTERR_BAD_REQUEST, /* 400 */
34: HTERR_UNAUTHORIZED, /* 401 */
35: HTERR_PAYMENT_REQUIRED, /* 402 */
36: HTERR_FORBIDDEN, /* 403 */
37: HTERR_NOT_FOUND, /* 404 */
38: HTERR_INTERNAL, /* 500 */
39: HTERR_NOT_IMPLEMENTED, /* 501 */
40: HTERR_HTTP_CODES_END, /* Put all non-HTTP status codes after this */
41: HTERR_NO_REMOTE_HOST,
42: HTERR_FTP_SERVER,
43: HTERR_FTP_NO_RESPONSE,
44: HTERR_TIME_OUT,
2.2 frystyk 45: HTERR_GOPHER_SERVER,
46: HTERR_INTERRUPTED,
47: HTERR_CSO_SERVER,
48: HTERR_SYSTEM,
2.1 frystyk 49: HTERR_ELEMENTS /* This MUST be the last element */
50: } HTErrorElement;
2.3 ! frystyk 51:
! 52: typedef enum _HTErrSeverity {
! 53: ERR_FATAL = 0x1,
! 54: ERR_NON_FATAL = 0x3,
! 55: ERR_WARNING = 0x7
! 56: } HTErrSeverity;
! 57:
! 58: typedef struct _HTErrorInfo {
! 59: HTErrorElement element; /* Index number into HTErrorMsgInfo */
! 60: HTErrSeverity severity; /* A la VMS */
! 61: BOOL ignore; /* YES if msg should not go to user */
! 62: void * par; /* Explanation, e.g. filename */
! 63: unsigned int par_length; /* For copying by generic routine */
! 64: char * where; /* Which function */
! 65: } HTErrorInfo;
2.1 frystyk 66: </PRE>
67:
2.3 ! frystyk 68: <H2>Controling Globals</H2>
! 69:
! 70: This variable dictates which errors should be put out.
! 71:
! 72: <PRE>
! 73: typedef enum _HTErrorShow {
! 74: HT_ERR_SHOW_FATAL = 0x1,
! 75: HT_ERR_SHOW_NON_FATAL = 0x3,
! 76: HT_ERR_SHOW_WARNING = 0x7,
! 77: HT_ERR_SHOW_PARS = 0x8,
! 78: HT_ERR_SHOW_LOCATION = 0x10,
! 79: HT_ERR_SHOW_IGNORE = 0x20,
! 80: HT_ERR_SHOW_FIRST = 0x40,
! 81: HT_ERR_SHOW_ALL = 0x3F
! 82: } HTErrorShow;
! 83:
! 84: extern unsigned int HTErrorShowMask;
! 85: </PRE>
2.1 frystyk 86:
2.3 ! frystyk 87: This is the table containing the actual error-messages and links for more information:
2.1 frystyk 88:
89: <PRE>
2.3 ! frystyk 90: typedef struct _HTErrorMsgInfo {
! 91: int code; /* Error number */
! 92: char * msg; /* Short explanation */
! 93: char * url; /* Explaning URL */
! 94: } HTErrorMsgInfo;
! 95:
! 96: extern HTErrorMsgInfo error_info[];
2.1 frystyk 97: </PRE>
98:
2.3 ! frystyk 99: <H2>Public Error Functions</H2>
! 100:
2.1 frystyk 101: <H3>Add an Error Message</H3>
102:
103: This function adds an error message to the error_stack list in the HTRequest
2.3 ! frystyk 104: structure. It always returns a negative value.
2.1 frystyk 105: <PRE>
2.3 ! frystyk 106: extern int HTErrorAdd PARAMS(( HTRequest * request,
2.1 frystyk 107: HTErrSeverity severity,
108: BOOL ignore,
109: int element,
110: void * par,
111: unsigned int par_length,
112: char * where));
2.2 frystyk 113: </PRE>
114:
115: <H3>Add a System Error Message</H3>
116:
2.3 ! frystyk 117: This function adds an error from a system call that initializes errno or equivalent and adds it to the error_stack list in the HTRequest structure. It always returns a negative value.
2.2 frystyk 118: <PRE>
2.3 ! frystyk 119: extern int HTErrorSysAdd PARAMS(( HTRequest * request,
2.2 frystyk 120: HTErrSeverity severity,
121: BOOL ignore,
122: char * syscall));
2.1 frystyk 123: </PRE>
124:
125: <H3>Ignoring an Error Message</H3>
126:
127: If an error message is not to be send to the user, e.g., output to the stream, then the ignore flag must be turn on. This function turns it on for the latest error appended to the list.
128: <PRE>
129: extern void HTErrorIgnore PARAMS((HTRequest * request));
130: </PRE>
131:
2.3 ! frystyk 132: <H3>Generating an Error Message (default to standard output)</H3>
! 133:
! 134: This function outputs the content of the error_stack to standard output (used in Line Mode Browser), but smart clients and servers might overwrite this function so that the error messages can be handled to the user in a nice way. That is the reason for putting the actual implementation in HTML.c, that normally gets overwritten by clients and servers apart from Line Mode Browser. <P>
! 135:
! 136: <NOTE>NOTE</NOTE>
2.1 frystyk 137:
2.3 ! frystyk 138: If a stream <EM>has</EM> been put up (and maybe taken down again) inside the Library, then request->error_block has been set to YES. This indicates that it is NOT possible any more to use the stream as output for the message.
2.1 frystyk 139: <PRE>
140: extern void HTErrorMsg PARAMS((HTRequest * request));
141: </PRE>
142:
143: <H3>Freeing an Error List</H3>
144:
145: This is normally done when the HTRequest structure is freed but it might be done at any other time in order to ignore a whole series of errors.
146: <PRE>
147: extern void HTErrorFree PARAMS((HTRequest * request));
148: </PRE>
149:
150: <PRE>
151: #endif
152: </PRE>
153: end
154: </BODY>
155: </HTML>
156:
157:
Webmaster