Annotation of libwww/Library/src/HTError.html, revision 2.30
2.1 frystyk 1: <HTML>
2: <HEAD>
2.26 frystyk 3: <TITLE>Error Manager</TITLE>
2.30 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 8-Nov-1995 -->
2.1 frystyk 5: <NEXTID N="z1">
6: </HEAD>
7: <BODY>
2.18 frystyk 8:
2.9 frystyk 9: <H1>Reporting Errors and Messages to the Client</H1>
2.1 frystyk 10:
2.18 frystyk 11: <PRE>
12: /*
2.22 frystyk 13: ** (c) COPYRIGHT MIT 1995.
2.18 frystyk 14: ** Please first read the full copyright statement in the file COPYRIGH.
15: */
16: </PRE>
17:
2.30 ! frystyk 18: This is the implementaion of an error message reporting system that
! 19: reports errors occured either in a stream module (structured streams
! 20: inclusive) or in a protocol module. A list of errors are put into the
! 21: a list which can be bound to a request object or to a stream. <P>
2.18 frystyk 22:
23: This module is implemented by <A HREF="HTError.c">HTError.c</A>, and
2.30 ! frystyk 24: it is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C
! 25: Reference Library</A>.
2.4 frystyk 26:
2.1 frystyk 27: <PRE>
28: #ifndef HTERROR_H
29: #define HTERROR_H
2.28 frystyk 30: #include "HTReq.h"
2.1 frystyk 31: </PRE>
32:
2.30 ! frystyk 33: <A NAME="errorinfo"><H2>Error Codes and Messages</H2></A>
2.1 frystyk 34:
2.15 frystyk 35: <NOTE><B>Note: </B></NOTE> All non-HTTP error codes have index numbers
36: > HTERR_HTTP_CODES, and they will not be shown in the error-message
37: generated.
38:
2.1 frystyk 39: <PRE>
40: typedef enum _HTErrorElement {
41: HTERR_OK = 0, /* 200 */
42: HTERR_CREATED, /* 201 */
43: HTERR_ACCEPTED, /* 202 */
44: HTERR_PARTIAL, /* 203 */
2.23 frystyk 45: HTERR_NO_CONTENT, /* 204 */
2.1 frystyk 46: HTERR_MOVED, /* 301 */
47: HTERR_FOUND, /* 302 */
48: HTERR_METHOD, /* 303 */
49: HTERR_NOT_MODIFIED, /* 304 */
50: HTERR_BAD_REQUEST, /* 400 */
51: HTERR_UNAUTHORIZED, /* 401 */
52: HTERR_PAYMENT_REQUIRED, /* 402 */
53: HTERR_FORBIDDEN, /* 403 */
54: HTERR_NOT_FOUND, /* 404 */
2.20 frystyk 55: HTERR_NOT_ALLOWED, /* 405 */
56: HTERR_NONE_ACCEPTABLE, /* 406 */
57: HTERR_PROXY, /* 407 */
58: HTERR_TIMEOUT, /* 408 */
2.1 frystyk 59: HTERR_INTERNAL, /* 500 */
60: HTERR_NOT_IMPLEMENTED, /* 501 */
2.20 frystyk 61: HTERR_BAD_GATE, /* 502 */
62: HTERR_DOWN, /* 503 */
63: HTERR_GATE_TIMEOUT, /* 504 */
2.1 frystyk 64: HTERR_HTTP_CODES_END, /* Put all non-HTTP status codes after this */
65: HTERR_NO_REMOTE_HOST,
2.13 frystyk 66: HTERR_NO_HOST,
2.1 frystyk 67: HTERR_FTP_SERVER,
68: HTERR_FTP_NO_RESPONSE,
69: HTERR_TIME_OUT,
2.2 frystyk 70: HTERR_GOPHER_SERVER,
71: HTERR_INTERRUPTED,
2.13 frystyk 72: HTERR_CON_INTR,
2.2 frystyk 73: HTERR_CSO_SERVER,
2.20 frystyk 74: HTERR_HTTP09,
75: HTERR_BAD_REPLY,
2.16 frystyk 76: HTERR_UNKNOWN_AA,
2.5 frystyk 77: HTERR_NEWS_SERVER,
2.7 frystyk 78: HTERR_FILE_TO_FTP,
2.8 frystyk 79: HTERR_MAX_REDIRECT,
2.16 frystyk 80: HTERR_EOF,
2.14 frystyk 81: HTERR_WAIS_OVERFLOW,
82: HTERR_WAIS_MODULE,
2.12 frystyk 83: HTERR_WAIS_NO_CONNECT,
2.2 frystyk 84: HTERR_SYSTEM,
2.29 frystyk 85: HTERR_CLASS,
2.1 frystyk 86: HTERR_ELEMENTS /* This MUST be the last element */
87: } HTErrorElement;
2.30 ! frystyk 88: </PRE>
2.19 roeber 89:
2.30 ! frystyk 90: <H2>Creation and Deletion Methods</H2>
! 91:
! 92: <H3>Add an Error</H3>
! 93:
! 94: Add an error message to the error list. `par' and `where' might be set
! 95: to NULL. If par is a string, it is sufficient to let length be
! 96: unspecified, i.e., 0. If only a part of the string is wanted then
! 97: specify a length inferior to strlen((char *) par). The string is '\0'
! 98: terminated automaticly. See also HTError_addSystem for system errors. Returns YES if OK, else NO.
! 99:
! 100: <PRE>
! 101: typedef struct _HTError HTError;
! 102:
! 103: typedef enum _HTSeverity {
2.3 frystyk 104: ERR_FATAL = 0x1,
2.7 frystyk 105: ERR_NON_FATAL = 0x2,
2.20 frystyk 106: ERR_WARN = 0x4,
2.7 frystyk 107: ERR_INFO = 0x8
2.30 ! frystyk 108: } HTSeverity;
! 109:
! 110: extern BOOL HTError_add (HTList * list,
! 111: HTSeverity severity,
! 112: BOOL ignore,
! 113: int element,
! 114: void * par,
! 115: unsigned int length,
! 116: char * where);
! 117:
! 118: </PRE>
! 119:
! 120: <H3>Add a System Error</H3>
! 121:
! 122: Add a system error message to the error list. syscall is the name of
! 123: the system call, e.g. "close". The message put to the list is that
! 124: corresponds to the error number passed. See also HTError_add. Returns
! 125: YES if OK, else NO.
! 126:
! 127: <PRE>
! 128: extern BOOL HTError_addSystem (HTList * list,
! 129: HTSeverity severity,
! 130: int errornumber,
! 131: BOOL ignore,
! 132: char * syscall);
! 133: </PRE>
! 134:
! 135:
! 136: <H3>Delete an Entire Error Stack</H3>
2.3 frystyk 137:
2.30 ! frystyk 138: Deletes all errors in a list.
! 139:
! 140: <PRE>
! 141: extern BOOL HTError_deleteAll (HTList * list);
2.1 frystyk 142: </PRE>
143:
2.30 ! frystyk 144: <H3>Deletes the Last Edded Entry</H3>
! 145:
! 146: Deletes the last error entry added to the list. Return YES if OK, else NO
! 147:
! 148: <PRE>
! 149: extern BOOL HTError_deleteLast (HTList * list);
! 150: </PRE>
! 151:
! 152: <H2>How Should Errors be Presented</H2>
2.3 frystyk 153:
2.15 frystyk 154: This variable dictates which errors should be put out when generating
155: the message to the user. The first four enumerations make it possible
156: to see `everything as bad or worse than' this level, e.g.
157: HT_ERR_SHOW_NON_FATAL shows messages of type HT_ERR_SHOW_NON_FATAL and
158: HT_ERR_SHOW_FATAL. <P>
159:
160: <B>Note:</B> The default value is made so that it only puts a message
161: to <EM>stderr</EM> if a `real' error has occurred. If a separate
162: widget is available for information and error messages then probably
163: HT_ERR_SHOW_DETAILED would be more appropriate.
2.3 frystyk 164:
165: <PRE>
166: typedef enum _HTErrorShow {
167: HT_ERR_SHOW_FATAL = 0x1,
168: HT_ERR_SHOW_NON_FATAL = 0x3,
169: HT_ERR_SHOW_WARNING = 0x7,
2.6 frystyk 170: HT_ERR_SHOW_INFO = 0xF,
171: HT_ERR_SHOW_PARS = 0x10,
172: HT_ERR_SHOW_LOCATION = 0x20,
173: HT_ERR_SHOW_IGNORE = 0x40,
174: HT_ERR_SHOW_FIRST = 0x80,
2.15 frystyk 175: HT_ERR_SHOW_LINKS = 0x100,
2.7 frystyk 176: HT_ERR_SHOW_DEFAULT = 0x13,
177: HT_ERR_SHOW_DETAILED = 0x1F,
2.10 frystyk 178: HT_ERR_SHOW_DEBUG = 0x7F
2.3 frystyk 179: } HTErrorShow;
180:
2.30 ! frystyk 181: extern HTErrorShow HTError_show (void);
! 182: extern BOOL HTError_setShow (HTErrorShow mask);
2.3 frystyk 183: </PRE>
2.1 frystyk 184:
2.30 ! frystyk 185: <H3>Show the Error Entry?</H3>
! 186:
! 187: Should we show this entry in the list or just continue to the next one?
2.1 frystyk 188:
189: <PRE>
2.30 ! frystyk 190: extern BOOL HTError_doShow (HTError * info);
2.1 frystyk 191: </PRE>
192:
2.30 ! frystyk 193: <H2>Ignore last Added Error</H2>
2.3 frystyk 194:
2.30 ! frystyk 195: Turns on the `ignore' flag for the most recent error entered the
! 196: error list. Returns YES if OK else NO
2.1 frystyk 197:
198: <PRE>
2.30 ! frystyk 199: extern BOOL HTError_ignoreLast (HTList * list);
! 200: extern BOOL HTError_setIgnore (HTError * info);
2.2 frystyk 201: </PRE>
202:
2.30 ! frystyk 203: <H2>Error Codes and Messages</H2>
2.2 frystyk 204:
2.30 ! frystyk 205: The error code can be set as part of the error message in the
! 206: <CODE>HTErrors</CODE> structure in the <A HREF="HTError.c">HTError.c
! 207: file</A>. The convention is that HTTP errors have an error code
! 208: equivalent to hte ones specified by the <A
! 209: HREF="http://www.w3.org/pub/WWW/Protocols/">HTTP specification</A> and
! 210: that internal errors have a code of 0.
2.15 frystyk 211:
2.2 frystyk 212: <PRE>
2.30 ! frystyk 213: extern int HTError_code (HTError * info);
2.1 frystyk 214: </PRE>
215:
2.30 ! frystyk 216: The Error Message is also a part of the <CODE>HTErrors</CODE>
! 217: structure in the <A HREF="HTError.c">HTError.c file</A>. It's hard
! 218: wired i order to make sure that the Librray always have a set of error
! 219: messages to provide to the user. The content can of course be changed.
2.15 frystyk 220:
2.1 frystyk 221: <PRE>
2.30 ! frystyk 222: extern CONST char * HTError_message (HTError * info);
2.1 frystyk 223: </PRE>
224:
2.30 ! frystyk 225: <H2>Error Object Specific Information</H2>
2.15 frystyk 226:
2.30 ! frystyk 227: The following methods provide the registered information in the
! 228: <CODE>Error object</CODE>.
2.15 frystyk 229:
230: <PRE>
2.30 ! frystyk 231: extern HTSeverity HTError_severity (HTError * info);
! 232: extern void * HTError_parameter (HTError * info, int * length);
! 233: extern CONST char * HTError_location (HTError * info);
2.1 frystyk 234: </PRE>
235:
2.30 ! frystyk 236: <H2>Error URLs</H2>
! 237:
! 238: Each error message can point to a URL with extended description of
! 239: what went wrong. This can for example also be used by a server in
! 240: order to send back a error URL to the client. The file names of the
! 241: URLs are given in the error message table but the prefix where to find
! 242: them can be handled with the following functions
2.1 frystyk 243:
244: <PRE>
2.30 ! frystyk 245: extern void HTError_setPrefix (CONST char * path);
! 246: extern CONST char *HTError_prefix (void);
! 247: extern void HTError_freePrefix (void);
2.1 frystyk 248: </PRE>
249:
250: <PRE>
251: #endif
252: </PRE>
2.30 ! frystyk 253: End of Declaration Manager
2.1 frystyk 254: </BODY>
255: </HTML>
256:
257:
Webmaster