Annotation of libwww/Library/src/HTError.html, revision 2.6
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.4 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. <P>
10:
11: <NOTE><B>Note: </B></NOTE>
12: At the moment, HTErrorMsg() is called, if the flag HTRequest->error_block is set to YES, then a stream has been put up or taken down in the library and therefore it is <B>VERY</B> unsafe to put anything more to the stream.
2.1 frystyk 13: <PRE>
14: #ifndef HTERROR_H
15: #define HTERROR_H
16: </PRE>
17:
2.3 frystyk 18: <H2>Data Structures</H2>
2.1 frystyk 19:
2.3 frystyk 20: The basic data structure is HTErrorInfo, but in addition the following types are used:
2.1 frystyk 21:
2.3 frystyk 22: <H3>Error Numbers</H3>
2.1 frystyk 23:
2.4 frystyk 24: <NOTE><B>Note: </B></NOTE>
25: All non-HTTP error codes have index numbers > HTERR_HTTP_CODES, and they will not be shown in the error-message generated.
2.1 frystyk 26: <PRE>
27: typedef enum _HTErrorElement {
28: HTERR_OK = 0, /* 200 */
29: HTERR_CREATED, /* 201 */
30: HTERR_ACCEPTED, /* 202 */
31: HTERR_PARTIAL, /* 203 */
32: HTERR_NO_RESPONSE, /* 204 */
33: HTERR_MOVED, /* 301 */
34: HTERR_FOUND, /* 302 */
35: HTERR_METHOD, /* 303 */
36: HTERR_NOT_MODIFIED, /* 304 */
37: HTERR_BAD_REQUEST, /* 400 */
38: HTERR_UNAUTHORIZED, /* 401 */
39: HTERR_PAYMENT_REQUIRED, /* 402 */
40: HTERR_FORBIDDEN, /* 403 */
41: HTERR_NOT_FOUND, /* 404 */
42: HTERR_INTERNAL, /* 500 */
43: HTERR_NOT_IMPLEMENTED, /* 501 */
44: HTERR_HTTP_CODES_END, /* Put all non-HTTP status codes after this */
45: HTERR_NO_REMOTE_HOST,
46: HTERR_FTP_SERVER,
47: HTERR_FTP_NO_RESPONSE,
48: HTERR_TIME_OUT,
2.2 frystyk 49: HTERR_GOPHER_SERVER,
50: HTERR_INTERRUPTED,
51: HTERR_CSO_SERVER,
2.5 frystyk 52: HTERR_BAD_REPLY, /* HTTP */
53: HTERR_NEWS_SERVER,
2.2 frystyk 54: HTERR_SYSTEM,
2.1 frystyk 55: HTERR_ELEMENTS /* This MUST be the last element */
56: } HTErrorElement;
2.3 frystyk 57:
58: typedef enum _HTErrSeverity {
59: ERR_FATAL = 0x1,
60: ERR_NON_FATAL = 0x3,
2.6 ! frystyk 61: ERR_WARNING = 0x7,
! 62: ERR_INFO = 0xF
2.3 frystyk 63: } HTErrSeverity;
64:
65: typedef struct _HTErrorInfo {
66: HTErrorElement element; /* Index number into HTErrorMsgInfo */
67: HTErrSeverity severity; /* A la VMS */
68: BOOL ignore; /* YES if msg should not go to user */
69: void * par; /* Explanation, e.g. filename */
70: unsigned int par_length; /* For copying by generic routine */
71: char * where; /* Which function */
72: } HTErrorInfo;
2.1 frystyk 73: </PRE>
74:
2.3 frystyk 75: <H2>Controling Globals</H2>
76:
77: This variable dictates which errors should be put out.
78:
79: <PRE>
80: typedef enum _HTErrorShow {
81: HT_ERR_SHOW_FATAL = 0x1,
82: HT_ERR_SHOW_NON_FATAL = 0x3,
83: HT_ERR_SHOW_WARNING = 0x7,
2.6 ! frystyk 84: HT_ERR_SHOW_INFO = 0xF,
! 85: HT_ERR_SHOW_PARS = 0x10,
! 86: HT_ERR_SHOW_LOCATION = 0x20,
! 87: HT_ERR_SHOW_IGNORE = 0x40,
! 88: HT_ERR_SHOW_FIRST = 0x80,
! 89: HT_ERR_SHOW_ALL = 0x6F /* All bits except HT_ERR_SHOW_FIRST */
2.3 frystyk 90: } HTErrorShow;
91:
92: extern unsigned int HTErrorShowMask;
93: </PRE>
2.1 frystyk 94:
2.3 frystyk 95: This is the table containing the actual error-messages and links for more information:
2.1 frystyk 96:
97: <PRE>
2.3 frystyk 98: typedef struct _HTErrorMsgInfo {
99: int code; /* Error number */
100: char * msg; /* Short explanation */
101: char * url; /* Explaning URL */
102: } HTErrorMsgInfo;
103:
104: extern HTErrorMsgInfo error_info[];
2.1 frystyk 105: </PRE>
106:
2.3 frystyk 107: <H2>Public Error Functions</H2>
108:
2.1 frystyk 109: <H3>Add an Error Message</H3>
110:
111: This function adds an error message to the error_stack list in the HTRequest
2.3 frystyk 112: structure. It always returns a negative value.
2.1 frystyk 113: <PRE>
2.3 frystyk 114: extern int HTErrorAdd PARAMS(( HTRequest * request,
2.1 frystyk 115: HTErrSeverity severity,
116: BOOL ignore,
117: int element,
118: void * par,
119: unsigned int par_length,
120: char * where));
2.2 frystyk 121: </PRE>
122:
123: <H3>Add a System Error Message</H3>
124:
2.3 frystyk 125: 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 126: <PRE>
2.3 frystyk 127: extern int HTErrorSysAdd PARAMS(( HTRequest * request,
2.2 frystyk 128: HTErrSeverity severity,
129: BOOL ignore,
130: char * syscall));
2.1 frystyk 131: </PRE>
132:
133: <H3>Ignoring an Error Message</H3>
134:
135: 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.
136: <PRE>
137: extern void HTErrorIgnore PARAMS((HTRequest * request));
138: </PRE>
139:
2.3 frystyk 140: <H3>Generating an Error Message (default to standard output)</H3>
141:
142: 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>
143:
2.4 frystyk 144: <NOTE><B>Note: </B></NOTE>
2.1 frystyk 145:
2.3 frystyk 146: 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 147: <PRE>
148: extern void HTErrorMsg PARAMS((HTRequest * request));
149: </PRE>
150:
151: <H3>Freeing an Error List</H3>
152:
153: 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.
154: <PRE>
155: extern void HTErrorFree PARAMS((HTRequest * request));
156: </PRE>
157:
158: <PRE>
159: #endif
160: </PRE>
161: end
162: </BODY>
163: </HTML>
164:
165:
Webmaster