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