Annotation of libwww/Library/src/HTError.html, revision 2.7
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.7 ! frystyk 54: HTERR_FILE_TO_FTP,
2.2 frystyk 55: HTERR_SYSTEM,
2.1 frystyk 56: HTERR_ELEMENTS /* This MUST be the last element */
57: } HTErrorElement;
2.3 frystyk 58:
59: typedef enum _HTErrSeverity {
60: ERR_FATAL = 0x1,
2.7 ! frystyk 61: ERR_NON_FATAL = 0x2,
! 62: ERR_WARNING = 0x4,
! 63: ERR_INFO = 0x8
2.3 frystyk 64: } HTErrSeverity;
65:
66: typedef struct _HTErrorInfo {
2.7 ! frystyk 67: int handle; /* Unique number in this stack */
2.3 frystyk 68: HTErrorElement element; /* Index number into HTErrorMsgInfo */
69: HTErrSeverity severity; /* A la VMS */
70: BOOL ignore; /* YES if msg should not go to user */
71: void * par; /* Explanation, e.g. filename */
72: unsigned int par_length; /* For copying by generic routine */
73: char * where; /* Which function */
74: } HTErrorInfo;
2.1 frystyk 75: </PRE>
76:
2.3 frystyk 77: <H2>Controling Globals</H2>
78:
2.7 ! frystyk 79: This variable dictates which errors should be put out. The first four
! 80: enumerations make it possible to see `everything as bad or worse than' this
! 81: level, e.g. HT_ERR_SHOW_NON_FATAL shows messages of type HT_ERR_SHOW_NON_FATAL
! 82: and HT_ERR_SHOW_FATAL. <P>
! 83:
! 84: <NOTE>Note:</NOTE> The default value is made so that it only puts a message to
! 85: stderr if a `real' error has occurred. If a separate widget is available for
! 86: information and error messages then probably HT_ERR_SHOW_DETAILED would be more
! 87: appropriate.
2.3 frystyk 88:
89: <PRE>
90: typedef enum _HTErrorShow {
91: HT_ERR_SHOW_FATAL = 0x1,
92: HT_ERR_SHOW_NON_FATAL = 0x3,
93: HT_ERR_SHOW_WARNING = 0x7,
2.6 frystyk 94: HT_ERR_SHOW_INFO = 0xF,
95: HT_ERR_SHOW_PARS = 0x10,
96: HT_ERR_SHOW_LOCATION = 0x20,
97: HT_ERR_SHOW_IGNORE = 0x40,
98: HT_ERR_SHOW_FIRST = 0x80,
2.7 ! frystyk 99: HT_ERR_SHOW_DEFAULT = 0x13,
! 100: HT_ERR_SHOW_DETAILED = 0x1F,
! 101: HT_ERR_SHOW_DEBUG = 0x7F,
2.3 frystyk 102: } HTErrorShow;
103:
104: extern unsigned int HTErrorShowMask;
105: </PRE>
2.1 frystyk 106:
2.3 frystyk 107: This is the table containing the actual error-messages and links for more information:
2.1 frystyk 108:
109: <PRE>
2.3 frystyk 110: typedef struct _HTErrorMsgInfo {
111: int code; /* Error number */
112: char * msg; /* Short explanation */
113: char * url; /* Explaning URL */
114: } HTErrorMsgInfo;
115:
116: extern HTErrorMsgInfo error_info[];
2.1 frystyk 117: </PRE>
118:
2.3 frystyk 119: <H2>Public Error Functions</H2>
120:
2.1 frystyk 121: <H3>Add an Error Message</H3>
122:
123: This function adds an error message to the error_stack list in the HTRequest
2.3 frystyk 124: structure. It always returns a negative value.
2.1 frystyk 125: <PRE>
2.3 frystyk 126: extern int HTErrorAdd PARAMS(( HTRequest * request,
2.1 frystyk 127: HTErrSeverity severity,
128: BOOL ignore,
129: int element,
130: void * par,
131: unsigned int par_length,
132: char * where));
2.2 frystyk 133: </PRE>
134:
135: <H3>Add a System Error Message</H3>
136:
2.3 frystyk 137: 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 138: <PRE>
2.3 frystyk 139: extern int HTErrorSysAdd PARAMS(( HTRequest * request,
2.2 frystyk 140: HTErrSeverity severity,
141: BOOL ignore,
142: char * syscall));
2.1 frystyk 143: </PRE>
144:
145: <H3>Ignoring an Error Message</H3>
146:
2.7 ! frystyk 147: If an error message is not to be send to the user, e.g., output to the stream,
! 148: then the ignore flag must be turn on. Theese functions turns it on for the
! 149: latest error appended to the list or an arbitrary error refered to by its
! 150: handle.
2.1 frystyk 151: <PRE>
2.7 ! frystyk 152: extern void HTErrorIgnore PARAMS((HTRequest * request, int handle));
! 153: extern void HTErrorIgnoreLast PARAMS((HTRequest * request));
2.1 frystyk 154: </PRE>
155:
2.7 ! frystyk 156: <H3>Generating an Error Message (default to standard error)</H3>
2.3 frystyk 157:
158: 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>
159:
2.4 frystyk 160: <NOTE><B>Note: </B></NOTE>
2.1 frystyk 161:
2.3 frystyk 162: 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 163: <PRE>
164: extern void HTErrorMsg PARAMS((HTRequest * request));
165: </PRE>
166:
167: <H3>Freeing an Error List</H3>
168:
169: 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.
170: <PRE>
171: extern void HTErrorFree PARAMS((HTRequest * request));
172: </PRE>
173:
174: <PRE>
175: #endif
176: </PRE>
177: end
178: </BODY>
179: </HTML>
180:
181:
Webmaster