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