Annotation of libwww/Library/src/HTError.html, revision 2.47
2.1 frystyk 1: <HTML>
2: <HEAD>
2.40 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 4-Jul-1996 -->
2.43 frystyk 4: <TITLE>W3C Sample Code Library libwww Error Class</TITLE>
2.1 frystyk 5: </HEAD>
6: <BODY>
2.37 frystyk 7: <H1>
8: The Error Class
9: </H1>
2.18 frystyk 10: <PRE>
11: /*
2.22 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.18 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
2.37 frystyk 16: <P>
17: The Error class provides an easy API for registering errors ocurring while
18: the Library serves a request. All errors are registered in an "error
19: stack" in the <A HREF="HTReq.html">Request object</A> which allows for
20: nested errors. The Error class is both natural language independent and
21: application independent in that it uses enumerations in order to refer to
22: specific errors. It is for the application to provide an error presentation
23: module which interprets the errors associated with a request. An eample of
24: such an implementation can be found in the <A HREF="HTDialog.html">HTDialog
25: module</A>.
26: <P>
27: This module is implemented by <A HREF="HTError.c">HTError.c</A>, and it is
2.47 ! frystyk 28: a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.37 frystyk 29: Library</A>.
2.1 frystyk 30: <PRE>
31: #ifndef HTERROR_H
32: #define HTERROR_H
2.36 frystyk 33:
34: typedef struct _HTError HTError;
35:
36: typedef enum _HTSeverity {
37: ERR_UNKNOWN = 0x0,
38: ERR_FATAL = 0x1,
39: ERR_NON_FATAL = 0x2,
40: ERR_WARN = 0x4,
41: ERR_INFO = 0x8
42: } HTSeverity;
43:
2.28 frystyk 44: #include "HTReq.h"
2.1 frystyk 45: </PRE>
2.37 frystyk 46: <H2>
47: <A NAME="errorinfo">Error Codes and Messages</A>
48: </H2>
49: <P>
50: <B>Note:</B> All non-HTTP error codes have index numbers > HTERR_HTTP_CODES,
51: and they will not be shown in the error-message generated.
2.1 frystyk 52: <PRE>
53: typedef enum _HTErrorElement {
2.38 frystyk 54: HTERR_CONTINUE = 0, /* 100 */
55: HTERR_SWITCHING, /* 101 */
56: HTERR_OK, /* 200 */
2.1 frystyk 57: HTERR_CREATED, /* 201 */
58: HTERR_ACCEPTED, /* 202 */
2.38 frystyk 59: HTERR_NON_AUTHORITATIVE, /* 203 */
2.23 frystyk 60: HTERR_NO_CONTENT, /* 204 */
2.38 frystyk 61: HTERR_RESET, /* 205 */
62: HTERR_PARTIAL, /* 206 */
2.45 frystyk 63: HTERR_PARTIAL_OK, /* 207 */
2.38 frystyk 64: HTERR_MULTIPLE, /* 300 */
2.1 frystyk 65: HTERR_MOVED, /* 301 */
66: HTERR_FOUND, /* 302 */
67: HTERR_METHOD, /* 303 */
68: HTERR_NOT_MODIFIED, /* 304 */
2.38 frystyk 69: HTERR_USE_PROXY, /* 305 */
2.45 frystyk 70: HTERR_PROXY_REDIRECT, /* 306 */
71: HTERR_TEMP_REDIRECT, /* 307 */
2.1 frystyk 72: HTERR_BAD_REQUEST, /* 400 */
73: HTERR_UNAUTHORIZED, /* 401 */
74: HTERR_PAYMENT_REQUIRED, /* 402 */
75: HTERR_FORBIDDEN, /* 403 */
76: HTERR_NOT_FOUND, /* 404 */
2.20 frystyk 77: HTERR_NOT_ALLOWED, /* 405 */
78: HTERR_NONE_ACCEPTABLE, /* 406 */
2.38 frystyk 79: HTERR_PROXY_UNAUTHORIZED, /* 407 */
2.20 frystyk 80: HTERR_TIMEOUT, /* 408 */
2.38 frystyk 81: HTERR_CONFLICT, /* 409 */
82: HTERR_GONE, /* 410 */
83: HTERR_LENGTH_REQUIRED, /* 411 */
84: HTERR_PRECON_FAILED, /* 412 */
85: HTERR_TOO_BIG, /* 413 */
86: HTERR_URI_TOO_BIG, /* 414 */
87: HTERR_UNSUPPORTED, /* 415 */
2.45 frystyk 88: HTERR_BAD_RANGE, /* 416 */
89: HTERR_EXPECTATION_FAILED, /* 417 */
90: HTERR_REAUTH, /* 418 */
91: HTERR_PROXY_REAUTH, /* 419 */
2.1 frystyk 92: HTERR_INTERNAL, /* 500 */
93: HTERR_NOT_IMPLEMENTED, /* 501 */
2.20 frystyk 94: HTERR_BAD_GATE, /* 502 */
95: HTERR_DOWN, /* 503 */
96: HTERR_GATE_TIMEOUT, /* 504 */
2.38 frystyk 97: HTERR_BAD_VERSION, /* 505 */
2.45 frystyk 98: HTERR_NO_PARTIAL_UPDATE, /* 506 */
2.38 frystyk 99:
100: /* Cache warnings */
101: HTERR_STALE, /* 10 */
102: HTERR_REVALIDATION_FAILED, /* 11 */
103: HTERR_DISCONNECTED_CACHE, /* 12 */
104: HTERR_HEURISTIC_EXPIRATION, /* 13 */
105: HTERR_TRANSFORMED, /* 14 */
106: HTERR_CACHE, /* 99 */
107:
108: /* Put all non-HTTP status codes after this */
2.1 frystyk 109: HTERR_NO_REMOTE_HOST,
2.13 frystyk 110: HTERR_NO_HOST,
2.31 frystyk 111: HTERR_NO_FILE,
2.1 frystyk 112: HTERR_FTP_SERVER,
113: HTERR_FTP_NO_RESPONSE,
2.46 frystyk 114: HTERR_FTP_LOGIN_FAILURE,
2.1 frystyk 115: HTERR_TIME_OUT,
2.2 frystyk 116: HTERR_GOPHER_SERVER,
117: HTERR_INTERRUPTED,
2.13 frystyk 118: HTERR_CON_INTR,
2.2 frystyk 119: HTERR_CSO_SERVER,
2.20 frystyk 120: HTERR_HTTP09,
121: HTERR_BAD_REPLY,
2.16 frystyk 122: HTERR_UNKNOWN_AA,
2.5 frystyk 123: HTERR_NEWS_SERVER,
2.7 frystyk 124: HTERR_FILE_TO_FTP,
2.39 frystyk 125: HTERR_AUTO_REDIRECT,
2.8 frystyk 126: HTERR_MAX_REDIRECT,
2.16 frystyk 127: HTERR_EOF,
2.14 frystyk 128: HTERR_WAIS_OVERFLOW,
129: HTERR_WAIS_MODULE,
2.12 frystyk 130: HTERR_WAIS_NO_CONNECT,
2.2 frystyk 131: HTERR_SYSTEM,
2.29 frystyk 132: HTERR_CLASS,
2.31 frystyk 133: HTERR_ACCESS,
134: HTERR_LOGIN,
2.41 frystyk 135: HTERR_CACHE_EXPIRED,
2.44 frystyk 136: HTERR_NO_AUTO_RULES,
137: HTERR_NO_AUTO_PROXY,
2.1 frystyk 138: HTERR_ELEMENTS /* This MUST be the last element */
139: } HTErrorElement;
2.30 frystyk 140: </PRE>
2.37 frystyk 141: <H2>
142: What Errors should be Parsed Through?
143: </H2>
144: <P>
145: This variable dictates which errors should be put out when generating the
146: message to the user. The first four enumerations make it possible to see
147: `everything as bad or worse than' this level, e.g. <CODE>HT_ERR_SHOW_NON_FATAL
148: </CODE>shows messages of type <CODE>HT_ERR_SHOW_NON_FATAL </CODE>and
149: <CODE>HT_ERR_SHOW_FATAL</CODE>.
150: <P>
151: <B>Note:</B> The default value is made so that it only puts a message to
152: <EM>stderr</EM> if a `real' error has occurred. If a separate widget is available
153: for information and error messages then probably
154: <CODE>HT_ERR_SHOW_DETAILED</CODE> would be more appropriate.
155: <PRE>
156: typedef enum _HTErrorShow {
157: HT_ERR_SHOW_FATAL = 0x1,
158: HT_ERR_SHOW_NON_FATAL = 0x3,
159: HT_ERR_SHOW_WARNING = 0x7,
160: HT_ERR_SHOW_INFO = 0xF,
161: HT_ERR_SHOW_PARS = 0x10,
162: HT_ERR_SHOW_LOCATION = 0x20,
163: HT_ERR_SHOW_IGNORE = 0x40,
164: HT_ERR_SHOW_FIRST = 0x80,
165: HT_ERR_SHOW_LINKS = 0x100,
166: HT_ERR_SHOW_DEFAULT = 0x13,
167: HT_ERR_SHOW_DETAILED = 0x1F,
168: HT_ERR_SHOW_DEBUG = 0x7F
169: } HTErrorShow;
2.19 roeber 170:
2.42 eric 171: typedef struct _HTErrorMessage {
172: int code; /* Error number */
173: char * msg; /* Short explanation */
174: char * url; /* Explaning URL */
175: } HTErrorMessage;
176:
177: /* CODE ERROR MESSAGE ERROR URL */
178: #define HTERR_ENGLISH_INITIALIZER \
179: { 100, "Continue", "information" }, \
180: { 101, "Switching Protocols", "information" }, \
181: { 200, "OK", "success" }, \
182: { 201, "Created", "success" }, \
183: { 202, "Accepted", "success" }, \
184: { 203, "Non-authoritative Information", "success" }, \
185: { 204, "No Content", "success" }, \
186: { 205, "Reset Content", "success" }, \
187: { 206, "Partial Content", "success" }, \
2.45 frystyk 188: { 207, "Partial Update OK", "success" }, \
2.42 eric 189: { 300, "Multiple Choices", "redirection" }, \
190: { 301, "Moved Permanently", "redirection" }, \
2.45 frystyk 191: { 302, "Found", "redirection" }, \
2.42 eric 192: { 303, "See Other", "redirection" }, \
193: { 304, "Not Modified", "redirection" }, \
194: { 305, "Use Proxy", "redirection" }, \
2.45 frystyk 195: { 306, "Proxy Redirect", "redirection" }, \
196: { 307, "Temporary Redirect", "redirection" }, \
2.42 eric 197: { 400, "Bad Request", "client_error" }, \
198: { 401, "Unauthorized", "client_error" }, \
199: { 402, "Payment Required", "client_error" }, \
200: { 403, "Forbidden", "client_error" }, \
201: { 404, "Not Found", "client_error" }, \
202: { 405, "Method Not Allowed", "client_error" }, \
203: { 406, "Not Acceptable", "client_error" }, \
204: { 407, "Proxy Authentication Required", "client_error" }, \
205: { 408, "Request Timeout", "client_error" }, \
206: { 409, "Conflict", "client_error" }, \
207: { 410, "Gone", "client_error" }, \
208: { 411, "Length Required", "client_error" }, \
209: { 412, "Precondition Failed", "client_error" }, \
210: { 413, "Request Entity Too Large", "client_error" }, \
211: { 414, "Request-URI Too Large", "client_error" }, \
212: { 415, "Unsupported Media Type", "client_error" }, \
2.45 frystyk 213: { 416, "Range Not Satisfiable", "client_error" }, \
214: { 417, "Expectation Failed", "client_error" }, \
215: { 418, "Reauthentication Required", "client_error" }, \
216: { 419, "Proxy Reauthentication Reuired", "client_error" }, \
2.42 eric 217: { 500, "Internal Server Error", "server_error" }, \
218: { 501, "Not Implemented", "server_error" }, \
219: { 502, "Bad Gateway", "server_error" }, \
220: { 503, "Service Unavailable", "server_error" }, \
221: { 504, "Gateway Timeout", "server_error" }, \
222: { 505, "HTTP Version not supported", "server_error" }, \
2.45 frystyk 223: { 506, "Partial update Not Implemented", "server_error" }, \
2.42 eric 224: \
225: /* Cache Warnings */ \
226: { 10, "Response is Stale", "cache" }, \
227: { 11, "Revalidation Failed", "cache" }, \
228: { 12, "Disconnected Opeartion", "cache" }, \
229: { 13, "Heuristic Expiration", "cache" }, \
230: { 14, "Transformation Applied", "cache" }, \
231: { 99, "Cache warning", "cache" }, \
232: \
233: /* Non-HTTP Error codes and warnings */ \
234: { 0, "Can't locate remote host", "internal" }, \
235: { 0, "No host name found", "internal" }, \
236: { 0, "No file name found or file not accessible", "internal" }, \
2.46 frystyk 237: { 0, "FTP server replies", "internal" }, \
238: { 0, "FTP server doesn't reply", "internal" }, \
239: { 0, "FTP login failure", "internal" }, \
2.42 eric 240: { 0, "Server timed out", "internal" }, \
241: { 0, "Gopher-server replies", "internal" }, \
242: { 0, "Data transfer interrupted", "internal" }, \
243: { 0, "Connection establishment interrupted", "internal" }, \
244: { 0, "CSO-server replies", "internal" }, \
245: { 0, "This is probably a HTTP server 0.9 or less","internal" }, \
246: { 0, "Bad, Incomplete, or Unknown Response", "internal" }, \
247: { 0, "Unknown access authentication scheme", "internal" }, \
248: { 0, "News-server replies", "internal" }, \
249: { 0, "Trying `ftp://' instead of `file://'", "internal" }, \
250: { 0, "Too many redirections", "internal" }, \
251: { 0, "Method not suited for automatic redirection","internal" }, \
252: { 0, "Premature End Of File", "internal" }, \
253: { 0, "Response from WAIS Server too Large - Extra lines \
254: ignored","internal"}, \
255: { 0, "WAIS-server doesn't return any data", "internal" }, \
256: { 0, "Can't connect to WAIS-server", "internal" }, \
257: { 0, "System replies", "internal" }, \
258: { 0, "Wrong or unknown access scheme", "internal" }, \
259: { 0, "Access scheme not allowed in this context", "internal" }, \
260: { 0, "When you are connected, you can log in", "internal" }, \
2.44 frystyk 261: { 0, "This version has expired and will be automatically reloaded", "internal" }, \
262: { 0, "Loading new rules must be explicitly acknowledged", "internal" }, \
263: { 0, "Automatic proxy redirection must be explicitly acknowledged", "internal" }
2.42 eric 264:
2.44 frystyk 265:
2.37 frystyk 266: extern HTErrorShow HTError_show (void);
267: extern BOOL HTError_setShow (HTErrorShow mask);
268: </PRE>
269: <H2>
270: Creation and Deletion Methods
271: </H2>
272: <H3>
273: Add an Error
274: </H3>
275: <P>
276: Add an error message to the error list. `par' and `where' might be set to
277: NULL. If par is a string, it is sufficient to let length be unspecified,
278: i.e., 0. If only a part of the string is wanted then specify a length inferior
279: to strlen((char *) par). The string is '\0' terminated automaticly. See also
280: HTError_addSystem for system errors. Returns YES if OK, else NO.
2.30 frystyk 281: <PRE>
282: extern BOOL HTError_add (HTList * list,
283: HTSeverity severity,
284: BOOL ignore,
285: int element,
286: void * par,
287: unsigned int length,
288: char * where);
289:
290: </PRE>
2.37 frystyk 291: <H3>
292: Add a System Error
293: </H3>
294: <P>
295: Add a system error message to the error list. syscall is the name of the
296: system call, e.g. "close". The message put to the list is that corresponds
297: to the error number passed. See also HTError_add. Returns YES if OK, else
298: NO.
2.30 frystyk 299: <PRE>
300: extern BOOL HTError_addSystem (HTList * list,
301: HTSeverity severity,
302: int errornumber,
303: BOOL ignore,
304: char * syscall);
305: </PRE>
2.37 frystyk 306: <H3>
307: Delete an Entire Error Stack
308: </H3>
309: <P>
2.30 frystyk 310: Deletes all errors in a list.
311: <PRE>
312: extern BOOL HTError_deleteAll (HTList * list);
2.1 frystyk 313: </PRE>
2.37 frystyk 314: <H3>
315: Deletes the Last Edded Entry
316: </H3>
317: <P>
2.30 frystyk 318: Deletes the last error entry added to the list. Return YES if OK, else NO
319: <PRE>
320: extern BOOL HTError_deleteLast (HTList * list);
321: </PRE>
2.37 frystyk 322: <H2>
2.40 frystyk 323: Object Methods
2.37 frystyk 324: </H2>
325: <H3>
326: Show the Error Entry?
327: </H3>
328: <P>
2.30 frystyk 329: Should we show this entry in the list or just continue to the next one?
2.1 frystyk 330: <PRE>
2.30 frystyk 331: extern BOOL HTError_doShow (HTError * info);
2.1 frystyk 332: </PRE>
2.37 frystyk 333: <H3>
334: Ignore last Added Error
335: </H3>
336: <P>
337: Turns on the `ignore' flag for the most recent error entered the error list.
338: Returns YES if OK else NO
2.1 frystyk 339: <PRE>
2.30 frystyk 340: extern BOOL HTError_ignoreLast (HTList * list);
341: extern BOOL HTError_setIgnore (HTError * info);
2.2 frystyk 342: </PRE>
2.37 frystyk 343: <H3>
344: Error Index Number
345: </H3>
346: <P>
347: Each error object is assigned an index number as defined by the
348: <CODE>HTErrorElement</CODE> above. The mapping from this index to an error
349: code and a message must be done by the application. The Library provides
350: a default implementation in the <A HREF="HTDialog.html"> HTDialog module</A>,
351: but that can of course be changed depending on the application.
2.15 frystyk 352: <PRE>
2.31 frystyk 353: extern int HTError_index (HTError * info);
2.37 frystyk 354: </PRE>
355: <H3>
356: Error Severity
357: </H3>
2.40 frystyk 358: <P>
359: This function returns the severity of the error object passed by the caller
360: <PRE>extern HTSeverity HTError_severity (HTError * info);
361: </PRE>
362: <P>
363: You can ask whether a list of errors contains any error object with a severity
364: level which is higher than the one specifed.
365: <PRE>extern BOOL HTError_hasSeverity (HTList * list, HTSeverity severity);
2.37 frystyk 366: </PRE>
367: <H3>
368: Parameters Asscotiated with Error
369: </H3>
370: <PRE>
2.30 frystyk 371: extern void * HTError_parameter (HTError * info, int * length);
2.37 frystyk 372: </PRE>
373: <H3>
374: Where did it happen?
375: </H3>
376: <PRE>
2.34 frystyk 377: extern const char * HTError_location (HTError * info);
2.1 frystyk 378: </PRE>
379: <PRE>
380: #endif
381: </PRE>
2.37 frystyk 382: <P>
383: <HR>
2.36 frystyk 384: <ADDRESS>
2.47 ! frystyk 385: @(#) $Id: HTError.html,v 2.46 1998/03/20 17:52:49 frystyk Exp $
2.36 frystyk 386: </ADDRESS>
2.37 frystyk 387: </BODY></HTML>
Webmaster