Annotation of libwww/Library/src/HTError.html, revision 2.15.2.1
2.1 frystyk 1: <HTML>
2: <HEAD>
3: <TITLE>Error message module for libwww</TITLE>
2.15.2.1! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 2-Jun-1996 -->
2.1 frystyk 5: <NEXTID N="z1">
6: </HEAD>
7: <BODY>
2.9 frystyk 8: <H1>Reporting Errors and Messages to the Client</H1>
2.1 frystyk 9:
2.15 frystyk 10: This module maintaines a list of error messages that might occur
11: during load of a requested URL. The error list is put out to standard
12: output by a simple function that easily can be overwritten by a smart
13: server or client. The module is a part of the <A
14: HREF="Overview.html">CERN Common WWW Library</A>.<P>
15:
16: <NOTE><B>Note: </B></NOTE> At the moment, <A
17: HREF="HTErrorMsg.c">HTErrorMsg()</A> is called, if the flag
18: HTRequest->error_block is set to YES, then a stream has been put up
19: or taken down in the library and therefore it is <B>VERY</B> unsafe to
20: put anything more to the stream.
2.4 frystyk 21:
2.1 frystyk 22: <PRE>
23: #ifndef HTERROR_H
24: #define HTERROR_H
2.15 frystyk 25: #include "HTAccess.h"
2.1 frystyk 26: </PRE>
27:
2.3 frystyk 28: <H2>Data Structures</H2>
2.1 frystyk 29:
2.15 frystyk 30: The basic data structure is HTErrorInfo, but in addition the following
31: types are used:
2.1 frystyk 32:
2.3 frystyk 33: <H3>Error Numbers</H3>
2.1 frystyk 34:
2.15 frystyk 35: <NOTE><B>Note: </B></NOTE> All non-HTTP error codes have index numbers
36: > HTERR_HTTP_CODES, and they will not be shown in the error-message
37: generated.
38:
2.1 frystyk 39: <PRE>
40: typedef enum _HTErrorElement {
41: HTERR_OK = 0, /* 200 */
42: HTERR_CREATED, /* 201 */
43: HTERR_ACCEPTED, /* 202 */
44: HTERR_PARTIAL, /* 203 */
45: HTERR_NO_RESPONSE, /* 204 */
46: HTERR_MOVED, /* 301 */
47: HTERR_FOUND, /* 302 */
48: HTERR_METHOD, /* 303 */
49: HTERR_NOT_MODIFIED, /* 304 */
50: HTERR_BAD_REQUEST, /* 400 */
51: HTERR_UNAUTHORIZED, /* 401 */
52: HTERR_PAYMENT_REQUIRED, /* 402 */
53: HTERR_FORBIDDEN, /* 403 */
54: HTERR_NOT_FOUND, /* 404 */
55: HTERR_INTERNAL, /* 500 */
56: HTERR_NOT_IMPLEMENTED, /* 501 */
57: HTERR_HTTP_CODES_END, /* Put all non-HTTP status codes after this */
58: HTERR_NO_REMOTE_HOST,
2.13 frystyk 59: HTERR_NO_HOST,
2.1 frystyk 60: HTERR_FTP_SERVER,
61: HTERR_FTP_NO_RESPONSE,
62: HTERR_TIME_OUT,
2.2 frystyk 63: HTERR_GOPHER_SERVER,
64: HTERR_INTERRUPTED,
2.13 frystyk 65: HTERR_CON_INTR,
2.2 frystyk 66: HTERR_CSO_SERVER,
2.5 frystyk 67: HTERR_BAD_REPLY, /* HTTP */
68: HTERR_NEWS_SERVER,
2.7 frystyk 69: HTERR_FILE_TO_FTP,
2.8 frystyk 70: HTERR_MAX_REDIRECT,
2.14 frystyk 71: HTERR_WAIS_OVERFLOW,
72: HTERR_WAIS_MODULE,
2.12 frystyk 73: HTERR_WAIS_NO_CONNECT,
2.2 frystyk 74: HTERR_SYSTEM,
2.1 frystyk 75: HTERR_ELEMENTS /* This MUST be the last element */
76: } HTErrorElement;
2.3 frystyk 77:
78: typedef enum _HTErrSeverity {
79: ERR_FATAL = 0x1,
2.7 frystyk 80: ERR_NON_FATAL = 0x2,
81: ERR_WARNING = 0x4,
82: ERR_INFO = 0x8
2.3 frystyk 83: } HTErrSeverity;
84:
85: typedef struct _HTErrorInfo {
2.7 frystyk 86: int handle; /* Unique number in this stack */
2.3 frystyk 87: HTErrorElement element; /* Index number into HTErrorMsgInfo */
88: HTErrSeverity severity; /* A la VMS */
89: BOOL ignore; /* YES if msg should not go to user */
90: void * par; /* Explanation, e.g. filename */
91: unsigned int par_length; /* For copying by generic routine */
92: char * where; /* Which function */
93: } HTErrorInfo;
2.1 frystyk 94: </PRE>
95:
2.3 frystyk 96: <H2>Controling Globals</H2>
97:
2.15 frystyk 98: This variable dictates which errors should be put out when generating
99: the message to the user. The first four enumerations make it possible
100: to see `everything as bad or worse than' this level, e.g.
101: HT_ERR_SHOW_NON_FATAL shows messages of type HT_ERR_SHOW_NON_FATAL and
102: HT_ERR_SHOW_FATAL. <P>
103:
104: <B>Note:</B> The default value is made so that it only puts a message
105: to <EM>stderr</EM> if a `real' error has occurred. If a separate
106: widget is available for information and error messages then probably
107: HT_ERR_SHOW_DETAILED would be more appropriate.
2.3 frystyk 108:
109: <PRE>
110: typedef enum _HTErrorShow {
111: HT_ERR_SHOW_FATAL = 0x1,
112: HT_ERR_SHOW_NON_FATAL = 0x3,
113: HT_ERR_SHOW_WARNING = 0x7,
2.6 frystyk 114: HT_ERR_SHOW_INFO = 0xF,
115: HT_ERR_SHOW_PARS = 0x10,
116: HT_ERR_SHOW_LOCATION = 0x20,
117: HT_ERR_SHOW_IGNORE = 0x40,
118: HT_ERR_SHOW_FIRST = 0x80,
2.15 frystyk 119: HT_ERR_SHOW_LINKS = 0x100,
2.7 frystyk 120: HT_ERR_SHOW_DEFAULT = 0x13,
121: HT_ERR_SHOW_DETAILED = 0x1F,
2.10 frystyk 122: HT_ERR_SHOW_DEBUG = 0x7F
2.3 frystyk 123: } HTErrorShow;
124:
125: extern unsigned int HTErrorShowMask;
126: </PRE>
2.1 frystyk 127:
2.15 frystyk 128: This is the table containing the actual error-messages and links for
129: more information:
2.1 frystyk 130:
131: <PRE>
2.3 frystyk 132: typedef struct _HTErrorMsgInfo {
133: int code; /* Error number */
134: char * msg; /* Short explanation */
135: char * url; /* Explaning URL */
136: } HTErrorMsgInfo;
137:
138: extern HTErrorMsgInfo error_info[];
2.1 frystyk 139: </PRE>
140:
2.3 frystyk 141: <H2>Public Error Functions</H2>
142:
2.1 frystyk 143: <H3>Add an Error Message</H3>
144:
145: This function adds an error message to the error_stack list in the HTRequest
2.3 frystyk 146: structure. It always returns a negative value.
2.1 frystyk 147: <PRE>
2.3 frystyk 148: extern int HTErrorAdd PARAMS(( HTRequest * request,
2.1 frystyk 149: HTErrSeverity severity,
150: BOOL ignore,
151: int element,
152: void * par,
153: unsigned int par_length,
154: char * where));
2.2 frystyk 155: </PRE>
156:
157: <H3>Add a System Error Message</H3>
158:
2.15 frystyk 159: This function adds an error from a system call that initializes errno
160: or equivalent and adds it to the error_stack list in the HTRequest
161: structure. It always returns a negative value.
162:
2.2 frystyk 163: <PRE>
2.3 frystyk 164: extern int HTErrorSysAdd PARAMS(( HTRequest * request,
2.2 frystyk 165: HTErrSeverity severity,
166: BOOL ignore,
167: char * syscall));
2.1 frystyk 168: </PRE>
169:
170: <H3>Ignoring an Error Message</H3>
171:
2.15 frystyk 172: If an error message is not to be send to the user, e.g., output to the
173: stream, then the ignore flag must be turn on. Theese functions turns
174: it on for the latest error appended to the list or an arbitrary error
175: refered to by its handle.
176:
2.1 frystyk 177: <PRE>
2.7 frystyk 178: extern void HTErrorIgnore PARAMS((HTRequest * request, int handle));
179: extern void HTErrorIgnoreLast PARAMS((HTRequest * request));
2.1 frystyk 180: </PRE>
181:
2.15 frystyk 182: <H3>Handling Prefix for Links in Error Message</H3>
183:
184: Two functions handle the URL prefix of the links inside the error
185: message. They are quite obvious:
186:
187: <PRE>
188: PUBLIC void HTErrorSetPrefix PARAMS((char *path));
189: PUBLIC CONST char *HTErrorGetPrefix NOPARAMS;
190: </PRE>
191:
2.7 frystyk 192: <H3>Generating an Error Message (default to standard error)</H3>
2.3 frystyk 193:
2.8 frystyk 194: This function outputs the content of the error_stack to standard output
195: (used in Line Mode Browser), but smart clients and servers might overwrite
196: this function so that the error messages can be handled to the user in a nice
197: way. That is the reason for putting the actual implementation in HTErrorMsg.c,
198: that can be overwritten by clients and servers apart from Line Mode Browser.<P>
2.3 frystyk 199:
2.4 frystyk 200: <NOTE><B>Note: </B></NOTE>
2.1 frystyk 201:
2.8 frystyk 202: If a stream <EM>has</EM> been put up (and maybe taken down again) inside the
203: Library, then request->error_block has been set to YES. This indicates that
204: it is NOT possible any more to use the stream as output for the message.
2.1 frystyk 205: <PRE>
2.15 frystyk 206: PUBLIC void HTErrorMsg PARAMS((HTRequest * request));
2.15.2.1! frystyk 207: </PRE>
! 208:
! 209: <H3>Find an Error URL</H3>
! 210:
! 211: <PRE>
! 212: extern char * HTError_findUrl (int code);
! 213: extern BOOL HTError_addUrl (int code, CONST char * url);
! 214: extern BOOL HTError_deleteUrl (int code);
2.1 frystyk 215: </PRE>
216:
217: <H3>Freeing an Error List</H3>
218:
2.8 frystyk 219: This is normally done when the HTRequest structure is freed but it might be
220: done at any other time in order to ignore a whole series of errors.
2.1 frystyk 221: <PRE>
2.15 frystyk 222: PUBLIC void HTErrorFree PARAMS((HTRequest * request));
2.1 frystyk 223: </PRE>
224:
225: <PRE>
226: #endif
227: </PRE>
228: end
229: </BODY>
230: </HTML>
231:
232:
Webmaster