Annotation of libwww/Library/src/HTError.html, revision 2.18
2.1 frystyk 1: <HTML>
2: <HEAD>
3: <TITLE>Error message module for libwww</TITLE>
4: <NEXTID N="z1">
5: </HEAD>
6: <BODY>
2.18 ! frystyk 7:
2.9 frystyk 8: <H1>Reporting Errors and Messages to the Client</H1>
2.1 frystyk 9:
2.18 ! frystyk 10: <PRE>
! 11: /*
! 12: ** (c) COPYRIGHT CERN 1994.
! 13: ** Please first read the full copyright statement in the file COPYRIGH.
! 14: */
! 15: </PRE>
! 16:
2.15 frystyk 17: This module maintaines a list of error messages that might occur
18: during load of a requested URL. The error list is put out to standard
19: output by a simple function that easily can be overwritten by a smart
2.18 ! frystyk 20: server or client. <P>
2.15 frystyk 21:
22: <NOTE><B>Note: </B></NOTE> At the moment, <A
23: HREF="HTErrorMsg.c">HTErrorMsg()</A> is called, if the flag
24: HTRequest->error_block is set to YES, then a stream has been put up
25: or taken down in the library and therefore it is <B>VERY</B> unsafe to
2.18 ! frystyk 26: put anything more to the stream. <P>
! 27:
! 28: This module is implemented by <A HREF="HTError.c">HTError.c</A>, and
! 29: it is a part of the <A
! 30: HREF="http://info.cern.ch/hypertext/WWW/Library/User/Guide/Guide.html">
! 31: Library of Common Code</A>.
2.4 frystyk 32:
2.1 frystyk 33: <PRE>
34: #ifndef HTERROR_H
35: #define HTERROR_H
2.15 frystyk 36: #include "HTAccess.h"
2.1 frystyk 37: </PRE>
38:
2.3 frystyk 39: <H2>Data Structures</H2>
2.1 frystyk 40:
2.15 frystyk 41: The basic data structure is HTErrorInfo, but in addition the following
42: types are used:
2.1 frystyk 43:
2.3 frystyk 44: <H3>Error Numbers</H3>
2.1 frystyk 45:
2.15 frystyk 46: <NOTE><B>Note: </B></NOTE> All non-HTTP error codes have index numbers
47: > HTERR_HTTP_CODES, and they will not be shown in the error-message
48: generated.
49:
2.1 frystyk 50: <PRE>
51: typedef enum _HTErrorElement {
52: HTERR_OK = 0, /* 200 */
53: HTERR_CREATED, /* 201 */
54: HTERR_ACCEPTED, /* 202 */
55: HTERR_PARTIAL, /* 203 */
56: HTERR_NO_RESPONSE, /* 204 */
57: HTERR_MOVED, /* 301 */
58: HTERR_FOUND, /* 302 */
59: HTERR_METHOD, /* 303 */
60: HTERR_NOT_MODIFIED, /* 304 */
61: HTERR_BAD_REQUEST, /* 400 */
62: HTERR_UNAUTHORIZED, /* 401 */
63: HTERR_PAYMENT_REQUIRED, /* 402 */
64: HTERR_FORBIDDEN, /* 403 */
65: HTERR_NOT_FOUND, /* 404 */
66: HTERR_INTERNAL, /* 500 */
67: HTERR_NOT_IMPLEMENTED, /* 501 */
68: HTERR_HTTP_CODES_END, /* Put all non-HTTP status codes after this */
69: HTERR_NO_REMOTE_HOST,
2.13 frystyk 70: HTERR_NO_HOST,
2.1 frystyk 71: HTERR_FTP_SERVER,
72: HTERR_FTP_NO_RESPONSE,
73: HTERR_TIME_OUT,
2.2 frystyk 74: HTERR_GOPHER_SERVER,
75: HTERR_INTERRUPTED,
2.13 frystyk 76: HTERR_CON_INTR,
2.2 frystyk 77: HTERR_CSO_SERVER,
2.16 frystyk 78: HTERR_HTTP09, /* HTTP */
2.5 frystyk 79: HTERR_BAD_REPLY, /* HTTP */
2.16 frystyk 80: HTERR_UNKNOWN_AA,
2.5 frystyk 81: HTERR_NEWS_SERVER,
2.7 frystyk 82: HTERR_FILE_TO_FTP,
2.8 frystyk 83: HTERR_MAX_REDIRECT,
2.16 frystyk 84: HTERR_EOF,
2.14 frystyk 85: HTERR_WAIS_OVERFLOW,
86: HTERR_WAIS_MODULE,
2.12 frystyk 87: HTERR_WAIS_NO_CONNECT,
2.2 frystyk 88: HTERR_SYSTEM,
2.1 frystyk 89: HTERR_ELEMENTS /* This MUST be the last element */
90: } HTErrorElement;
2.3 frystyk 91:
92: typedef enum _HTErrSeverity {
93: ERR_FATAL = 0x1,
2.7 frystyk 94: ERR_NON_FATAL = 0x2,
95: ERR_WARNING = 0x4,
96: ERR_INFO = 0x8
2.3 frystyk 97: } HTErrSeverity;
98:
99: typedef struct _HTErrorInfo {
2.7 frystyk 100: int handle; /* Unique number in this stack */
2.3 frystyk 101: HTErrorElement element; /* Index number into HTErrorMsgInfo */
102: HTErrSeverity severity; /* A la VMS */
103: BOOL ignore; /* YES if msg should not go to user */
104: void * par; /* Explanation, e.g. filename */
105: unsigned int par_length; /* For copying by generic routine */
106: char * where; /* Which function */
107: } HTErrorInfo;
2.1 frystyk 108: </PRE>
109:
2.3 frystyk 110: <H2>Controling Globals</H2>
111:
2.15 frystyk 112: This variable dictates which errors should be put out when generating
113: the message to the user. The first four enumerations make it possible
114: to see `everything as bad or worse than' this level, e.g.
115: HT_ERR_SHOW_NON_FATAL shows messages of type HT_ERR_SHOW_NON_FATAL and
116: HT_ERR_SHOW_FATAL. <P>
117:
118: <B>Note:</B> The default value is made so that it only puts a message
119: to <EM>stderr</EM> if a `real' error has occurred. If a separate
120: widget is available for information and error messages then probably
121: HT_ERR_SHOW_DETAILED would be more appropriate.
2.3 frystyk 122:
123: <PRE>
124: typedef enum _HTErrorShow {
125: HT_ERR_SHOW_FATAL = 0x1,
126: HT_ERR_SHOW_NON_FATAL = 0x3,
127: HT_ERR_SHOW_WARNING = 0x7,
2.6 frystyk 128: HT_ERR_SHOW_INFO = 0xF,
129: HT_ERR_SHOW_PARS = 0x10,
130: HT_ERR_SHOW_LOCATION = 0x20,
131: HT_ERR_SHOW_IGNORE = 0x40,
132: HT_ERR_SHOW_FIRST = 0x80,
2.15 frystyk 133: HT_ERR_SHOW_LINKS = 0x100,
2.7 frystyk 134: HT_ERR_SHOW_DEFAULT = 0x13,
135: HT_ERR_SHOW_DETAILED = 0x1F,
2.10 frystyk 136: HT_ERR_SHOW_DEBUG = 0x7F
2.3 frystyk 137: } HTErrorShow;
138:
139: extern unsigned int HTErrorShowMask;
140: </PRE>
2.1 frystyk 141:
2.15 frystyk 142: This is the table containing the actual error-messages and links for
143: more information:
2.1 frystyk 144:
145: <PRE>
2.3 frystyk 146: typedef struct _HTErrorMsgInfo {
147: int code; /* Error number */
148: char * msg; /* Short explanation */
149: char * url; /* Explaning URL */
150: } HTErrorMsgInfo;
151:
152: extern HTErrorMsgInfo error_info[];
2.1 frystyk 153: </PRE>
154:
2.3 frystyk 155: <H2>Public Error Functions</H2>
156:
2.1 frystyk 157: <H3>Add an Error Message</H3>
158:
159: This function adds an error message to the error_stack list in the HTRequest
2.3 frystyk 160: structure. It always returns a negative value.
2.1 frystyk 161: <PRE>
2.3 frystyk 162: extern int HTErrorAdd PARAMS(( HTRequest * request,
2.1 frystyk 163: HTErrSeverity severity,
164: BOOL ignore,
165: int element,
166: void * par,
167: unsigned int par_length,
168: char * where));
2.2 frystyk 169: </PRE>
170:
171: <H3>Add a System Error Message</H3>
172:
2.15 frystyk 173: This function adds an error from a system call that initializes errno
174: or equivalent and adds it to the error_stack list in the HTRequest
175: structure. It always returns a negative value.
176:
2.2 frystyk 177: <PRE>
2.3 frystyk 178: extern int HTErrorSysAdd PARAMS(( HTRequest * request,
2.2 frystyk 179: HTErrSeverity severity,
180: BOOL ignore,
181: char * syscall));
2.1 frystyk 182: </PRE>
183:
184: <H3>Ignoring an Error Message</H3>
185:
2.15 frystyk 186: If an error message is not to be send to the user, e.g., output to the
187: stream, then the ignore flag must be turn on. Theese functions turns
188: it on for the latest error appended to the list or an arbitrary error
189: refered to by its handle.
190:
2.1 frystyk 191: <PRE>
2.7 frystyk 192: extern void HTErrorIgnore PARAMS((HTRequest * request, int handle));
193: extern void HTErrorIgnoreLast PARAMS((HTRequest * request));
2.1 frystyk 194: </PRE>
195:
2.15 frystyk 196: <H3>Handling Prefix for Links in Error Message</H3>
197:
198: Two functions handle the URL prefix of the links inside the error
199: message. They are quite obvious:
200:
201: <PRE>
2.17 frystyk 202: extern void HTErrorSetPrefix PARAMS((char *path));
203: extern CONST char *HTErrorGetPrefix NOPARAMS;
2.15 frystyk 204: </PRE>
205:
2.7 frystyk 206: <H3>Generating an Error Message (default to standard error)</H3>
2.3 frystyk 207:
2.8 frystyk 208: This function outputs the content of the error_stack to standard output
209: (used in Line Mode Browser), but smart clients and servers might overwrite
210: this function so that the error messages can be handled to the user in a nice
211: way. That is the reason for putting the actual implementation in HTErrorMsg.c,
212: that can be overwritten by clients and servers apart from Line Mode Browser.<P>
2.3 frystyk 213:
2.4 frystyk 214: <NOTE><B>Note: </B></NOTE>
2.1 frystyk 215:
2.8 frystyk 216: If a stream <EM>has</EM> been put up (and maybe taken down again) inside the
217: Library, then request->error_block has been set to YES. This indicates that
218: it is NOT possible any more to use the stream as output for the message.
2.1 frystyk 219: <PRE>
2.17 frystyk 220: extern void HTErrorMsg PARAMS((HTRequest * request));
2.1 frystyk 221: </PRE>
222:
223: <H3>Freeing an Error List</H3>
224:
2.8 frystyk 225: This is normally done when the HTRequest structure is freed but it might be
226: done at any other time in order to ignore a whole series of errors.
2.1 frystyk 227: <PRE>
2.17 frystyk 228: extern void HTErrorFree PARAMS((HTRequest * request));
2.1 frystyk 229: </PRE>
230:
231: <PRE>
232: #endif
233: </PRE>
234: end
235: </BODY>
236: </HTML>
237:
238:
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