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