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