Annotation of libwww/Library/src/HTError.html, revision 2.51
2.51 ! kirschpi 1: <html>
! 2: <head>
! 3: <meta http-equiv="Content-Type" content="text/html">
2.40 frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 4-Jul-1996 -->
2.51 ! kirschpi 5: <title>W3C Sample Code Library libwww Error Class</title>
! 6: </head>
! 7:
! 8: <body>
! 9: <h1>The Error Class</h1>
! 10: <pre>/*
2.22 frystyk 11: ** (c) COPYRIGHT MIT 1995.
2.18 frystyk 12: ** Please first read the full copyright statement in the file COPYRIGH.
2.51 ! kirschpi 13: */</pre>
! 14:
! 15: <p>The Error class provides an easy API for registering errors ocurring while
! 16: libwww serves a request. All errors are registered in an "error stack" in the
! 17: <a href="HTReq.html">Request object</a> which allows for nested errors. The
! 18: Error class is both natural language independent and application independent
! 19: in that it uses enumerations in order to refer to specific errors. It is for
! 20: the application to provide an error presentation module which interprets the
! 21: errors associated with a request. An eample of such an implementation can be
! 22: found in the <a href="HTDialog.html">HTDialog module</a>.</p>
! 23:
! 24: <p>This module is implemented by <a href="HTError.c">HTError.c</a>, and it is
! 25: a part of the <a href="http://www.w3.org/Library/"> W3C Sample Code
! 26: Library</a>.</p>
! 27: <pre>#ifndef HTERROR_H
2.1 frystyk 28: #define HTERROR_H
2.36 frystyk 29:
30: typedef struct _HTError HTError;
31:
32: typedef enum _HTSeverity {
33: ERR_UNKNOWN = 0x0,
34: ERR_FATAL = 0x1,
35: ERR_NON_FATAL = 0x2,
36: ERR_WARN = 0x4,
37: ERR_INFO = 0x8
38: } HTSeverity;
39:
2.51 ! kirschpi 40: #include "HTReq.h"</pre>
! 41:
! 42: <h2><a name="errorinfo">The Error Message Object</a></h2>
! 43:
! 44: <p>An error consists of a messsage code, a short, natural language specific
2.49 frystyk 45: message, and a URI which can point to more information. This module also
2.51 ! kirschpi 46: provides a <a href="#Lang">default set of error objects with English
! 47: text</a>. Errors are registered together with a severity and you can also set
! 48: the mode for <a href="#What">what class of error severities should be shown
! 49: and which should be ignored</a>.</p>
! 50: <pre>typedef struct _HTErrorMessage {
2.49 frystyk 51: int code; /* Error number */
52: char * msg; /* Short explanation */
53: char * url; /* Explaning URL */
2.51 ! kirschpi 54: } HTErrorMessage;</pre>
! 55:
! 56: <h3><a name="Codes">Error Message Index</a></h3>
! 57:
! 58: <p><b>Note:</b> All non-HTTP error codes have (<code>index number >
! 59: HTERR_HTTP_CODES</code>), and they will not be shown in the error-message
! 60: generated.</p>
! 61:
! 62: <p>Error codes are registered in an array where the following enumerations
! 63: serve as an index. They must <strong>not</strong> be replaced! See the <a
! 64: href="HTDialog.html#Messsages">HTDialog module</a> for default initialization
! 65: of these messages.</p>
! 66: <pre>typedef enum _HTErrorElement {
2.38 frystyk 67: HTERR_CONTINUE = 0, /* 100 */
68: HTERR_SWITCHING, /* 101 */
69: HTERR_OK, /* 200 */
2.1 frystyk 70: HTERR_CREATED, /* 201 */
71: HTERR_ACCEPTED, /* 202 */
2.38 frystyk 72: HTERR_NON_AUTHORITATIVE, /* 203 */
2.23 frystyk 73: HTERR_NO_CONTENT, /* 204 */
2.38 frystyk 74: HTERR_RESET, /* 205 */
75: HTERR_PARTIAL, /* 206 */
2.45 frystyk 76: HTERR_PARTIAL_OK, /* 207 */
2.38 frystyk 77: HTERR_MULTIPLE, /* 300 */
2.1 frystyk 78: HTERR_MOVED, /* 301 */
79: HTERR_FOUND, /* 302 */
80: HTERR_METHOD, /* 303 */
81: HTERR_NOT_MODIFIED, /* 304 */
2.38 frystyk 82: HTERR_USE_PROXY, /* 305 */
2.45 frystyk 83: HTERR_PROXY_REDIRECT, /* 306 */
84: HTERR_TEMP_REDIRECT, /* 307 */
2.1 frystyk 85: HTERR_BAD_REQUEST, /* 400 */
86: HTERR_UNAUTHORIZED, /* 401 */
87: HTERR_PAYMENT_REQUIRED, /* 402 */
88: HTERR_FORBIDDEN, /* 403 */
89: HTERR_NOT_FOUND, /* 404 */
2.20 frystyk 90: HTERR_NOT_ALLOWED, /* 405 */
91: HTERR_NONE_ACCEPTABLE, /* 406 */
2.38 frystyk 92: HTERR_PROXY_UNAUTHORIZED, /* 407 */
2.20 frystyk 93: HTERR_TIMEOUT, /* 408 */
2.38 frystyk 94: HTERR_CONFLICT, /* 409 */
95: HTERR_GONE, /* 410 */
96: HTERR_LENGTH_REQUIRED, /* 411 */
97: HTERR_PRECON_FAILED, /* 412 */
98: HTERR_TOO_BIG, /* 413 */
99: HTERR_URI_TOO_BIG, /* 414 */
100: HTERR_UNSUPPORTED, /* 415 */
2.45 frystyk 101: HTERR_BAD_RANGE, /* 416 */
102: HTERR_EXPECTATION_FAILED, /* 417 */
103: HTERR_REAUTH, /* 418 */
104: HTERR_PROXY_REAUTH, /* 419 */
2.1 frystyk 105: HTERR_INTERNAL, /* 500 */
106: HTERR_NOT_IMPLEMENTED, /* 501 */
2.20 frystyk 107: HTERR_BAD_GATE, /* 502 */
108: HTERR_DOWN, /* 503 */
109: HTERR_GATE_TIMEOUT, /* 504 */
2.38 frystyk 110: HTERR_BAD_VERSION, /* 505 */
2.45 frystyk 111: HTERR_NO_PARTIAL_UPDATE, /* 506 */
2.38 frystyk 112:
2.51 ! kirschpi 113: #ifdef HT_DAV /* WebDAV error codes */
! 114: HTERR_UNPROCESSABLE, /* 422 */
! 115: HTERR_LOCKED, /* 423 */
! 116: HTERR_FAILED_DEPENDENCY, /* 424 */
! 117: HTERR_INSUFFICIENT_STORAGE, /* 507 */
! 118: #endif
! 119:
2.38 frystyk 120: /* Cache warnings */
121: HTERR_STALE, /* 10 */
122: HTERR_REVALIDATION_FAILED, /* 11 */
123: HTERR_DISCONNECTED_CACHE, /* 12 */
124: HTERR_HEURISTIC_EXPIRATION, /* 13 */
125: HTERR_TRANSFORMED, /* 14 */
126: HTERR_CACHE, /* 99 */
127:
128: /* Put all non-HTTP status codes after this */
2.1 frystyk 129: HTERR_NO_REMOTE_HOST,
2.13 frystyk 130: HTERR_NO_HOST,
2.31 frystyk 131: HTERR_NO_FILE,
2.1 frystyk 132: HTERR_FTP_SERVER,
133: HTERR_FTP_NO_RESPONSE,
2.46 frystyk 134: HTERR_FTP_LOGIN_FAILURE,
2.1 frystyk 135: HTERR_TIME_OUT,
2.2 frystyk 136: HTERR_GOPHER_SERVER,
137: HTERR_INTERRUPTED,
2.13 frystyk 138: HTERR_CON_INTR,
2.2 frystyk 139: HTERR_CSO_SERVER,
2.20 frystyk 140: HTERR_HTTP09,
141: HTERR_BAD_REPLY,
2.16 frystyk 142: HTERR_UNKNOWN_AA,
2.5 frystyk 143: HTERR_NEWS_SERVER,
2.7 frystyk 144: HTERR_FILE_TO_FTP,
2.39 frystyk 145: HTERR_AUTO_REDIRECT,
2.8 frystyk 146: HTERR_MAX_REDIRECT,
2.16 frystyk 147: HTERR_EOF,
2.14 frystyk 148: HTERR_WAIS_OVERFLOW,
149: HTERR_WAIS_MODULE,
2.12 frystyk 150: HTERR_WAIS_NO_CONNECT,
2.2 frystyk 151: HTERR_SYSTEM,
2.29 frystyk 152: HTERR_CLASS,
2.31 frystyk 153: HTERR_ACCESS,
154: HTERR_LOGIN,
2.41 frystyk 155: HTERR_CACHE_EXPIRED,
2.44 frystyk 156: HTERR_NO_AUTO_RULES,
157: HTERR_NO_AUTO_PROXY,
2.1 frystyk 158: HTERR_ELEMENTS /* This MUST be the last element */
2.51 ! kirschpi 159: } HTErrorElement;</pre>
! 160:
! 161: <h3><a name="Lang">Default English Language Messages</a></h3>
! 162:
! 163: <p>Default set of error messages arranged in an array into which the <a
! 164: href="#Codes">index codes</a> serve as index. See the <a
! 165: href="HTDialog.html#Messsages">HTDialog module</a> for default initialization
! 166: of these strings.</p>
! 167:
! 168: <h2><a name="What">What Errors should be Ignored or Passed Through?</a></h2>
! 169:
! 170: <p>This variable dictates which errors should be put out when generating the
2.49 frystyk 171: message to the user. The first four enumerations make it possible to see
2.51 ! kirschpi 172: `everything as bad or worse than' this level, e.g.
! 173: <code>HT_ERR_SHOW_NON_FATAL </code>shows messages of type
! 174: <code>HT_ERR_SHOW_NON_FATAL </code>and <code>HT_ERR_SHOW_FATAL</code>.</p>
! 175:
! 176: <p><b>Note:</b> The default value is made so that it only puts a message to
! 177: <em>stderr</em> if a `real' error has occurred. If a separate widget is
! 178: available for information and error messages then probably
! 179: <code>HT_ERR_SHOW_DETAILED</code> would be more appropriate.</p>
! 180: <pre>typedef enum _HTErrorShow {
2.49 frystyk 181: HT_ERR_SHOW_FATAL = 0x1,
182: HT_ERR_SHOW_NON_FATAL = 0x3,
183: HT_ERR_SHOW_WARNING = 0x7,
184: HT_ERR_SHOW_INFO = 0xF,
185: HT_ERR_SHOW_PARS = 0x10,
186: HT_ERR_SHOW_LOCATION = 0x20,
187: HT_ERR_SHOW_IGNORE = 0x40,
188: HT_ERR_SHOW_FIRST = 0x80,
189: HT_ERR_SHOW_LINKS = 0x100,
190: HT_ERR_SHOW_DEFAULT = 0x13,
191: HT_ERR_SHOW_DETAILED = 0x1F,
192: HT_ERR_SHOW_DEBUG = 0x7F
193: } HTErrorShow;
2.44 frystyk 194:
2.37 frystyk 195: extern HTErrorShow HTError_show (void);
2.51 ! kirschpi 196: extern BOOL HTError_setShow (HTErrorShow mask);</pre>
! 197:
! 198: <h2>Creation and Deletion Methods</h2>
! 199:
! 200: <h3>Add an Error</h3>
! 201:
! 202: <p>Add an error message to the error list. `par' and `where' might be set to
2.37 frystyk 203: NULL. If par is a string, it is sufficient to let length be unspecified,
2.51 ! kirschpi 204: i.e., 0. If only a part of the string is wanted then specify a length
! 205: inferior to strlen((char *) par). The string is '\0' terminated automaticly.
! 206: See also HTError_addSystem for system errors. Returns YES if OK, else NO.</p>
! 207: <pre>extern BOOL HTError_add (HTList * list,
2.30 frystyk 208: HTSeverity severity,
209: BOOL ignore,
210: int element,
211: void * par,
212: unsigned int length,
2.51 ! kirschpi 213: char * where);</pre>
! 214:
! 215: <h3>Add a System Error</h3>
2.30 frystyk 216:
2.51 ! kirschpi 217: <p>Add a system error message to the error list. syscall is the name of the
! 218: system call, e.g. "close". The message put to the list is that corresponds to
! 219: the error number passed. See also HTError_add. Returns YES if OK, else NO.</p>
! 220: <pre>extern BOOL HTError_addSystem (HTList * list,
2.30 frystyk 221: HTSeverity severity,
222: int errornumber,
223: BOOL ignore,
2.51 ! kirschpi 224: char * syscall);</pre>
! 225:
! 226: <h3>Delete an Entire Error Stack</h3>
! 227:
! 228: <p>Deletes all errors in a list.</p>
! 229: <pre>extern BOOL HTError_deleteAll (HTList * list);</pre>
! 230:
! 231: <h3>Deletes the Last Edded Entry</h3>
! 232:
! 233: <p>Deletes the last error entry added to the list. Return YES if OK, else
! 234: NO</p>
! 235: <pre>extern BOOL HTError_deleteLast (HTList * list);</pre>
! 236:
! 237: <h2>Object Methods</h2>
! 238:
! 239: <h3>Show the Error Entry?</h3>
! 240:
! 241: <p>Should we show this entry in the list or just continue to the next one?</p>
! 242: <pre>extern BOOL HTError_doShow (HTError * info);</pre>
! 243:
! 244: <h3>Ignore last Added Error</h3>
! 245:
! 246: <p>Turns on the `ignore' flag for the most recent error entered the error
! 247: list. Returns YES if OK else NO</p>
! 248: <pre>extern BOOL HTError_ignoreLast (HTList * list);
! 249: extern BOOL HTError_setIgnore (HTError * info);</pre>
! 250:
! 251: <h3>Error Index Number</h3>
! 252:
! 253: <p>Each error object is assigned an index number as defined by the
! 254: <code>HTErrorElement</code> above. The mapping from this index to an error
! 255: code and a message must be done by the application. The Library provides a
! 256: default implementation in the <a href="HTDialog.html"> HTDialog module</a>,
! 257: but that can of course be changed depending on the application.</p>
! 258: <pre>extern int HTError_index (HTError * info);</pre>
! 259:
! 260: <h3>Error Severity</h3>
! 261:
! 262: <p>This function returns the severity of the error object passed by the
! 263: caller</p>
! 264: <pre>extern HTSeverity HTError_severity (HTError * info);</pre>
! 265:
! 266: <p>You can ask whether a list of errors contains any error object with a
! 267: severity level which is higher than the one specifed.</p>
! 268: <pre>extern BOOL HTError_hasSeverity (HTList * list, HTSeverity severity);</pre>
! 269:
! 270: <h3>Parameters Asscotiated with Error</h3>
! 271: <pre>extern void * HTError_parameter (HTError * info, int * length);</pre>
! 272:
! 273: <h3>Where did it happen?</h3>
! 274: <pre>extern const char * HTError_location (HTError * info);</pre>
! 275: <pre>#endif /* HTERROR_H */</pre>
! 276:
! 277: <p></p>
! 278: <hr>
! 279: <address>
! 280: @(#) $Id: HTError.html,v 2.50 1999/04/01 19:35:39 frystyk Exp $
! 281: </address>
! 282: </body>
! 283: </html>
Webmaster