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