Annotation of libwww/Library/src/HTError.html, revision 2.4
2.1 frystyk 1: <HTML>
2: <HEAD>
3: <TITLE>Error message module for libwww</TITLE>
4: <NEXTID N="z1">
5: </HEAD>
6: <BODY>
7: <H1>Error reporting functions</H1>
8:
2.4 ! 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. <P>
! 10:
! 11: <NOTE><B>Note: </B></NOTE>
! 12: At the moment, HTErrorMsg() 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 13: <PRE>
14: #ifndef HTERROR_H
15: #define HTERROR_H
16: </PRE>
17:
2.3 frystyk 18: <H2>Data Structures</H2>
2.1 frystyk 19:
2.3 frystyk 20: The basic data structure is HTErrorInfo, but in addition the following types are used:
2.1 frystyk 21:
2.3 frystyk 22: <H3>Error Numbers</H3>
2.1 frystyk 23:
2.4 ! frystyk 24: <NOTE><B>Note: </B></NOTE>
! 25: 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 26: <PRE>
27: typedef enum _HTErrorElement {
28: HTERR_OK = 0, /* 200 */
29: HTERR_CREATED, /* 201 */
30: HTERR_ACCEPTED, /* 202 */
31: HTERR_PARTIAL, /* 203 */
32: HTERR_NO_RESPONSE, /* 204 */
33: HTERR_MOVED, /* 301 */
34: HTERR_FOUND, /* 302 */
35: HTERR_METHOD, /* 303 */
36: HTERR_NOT_MODIFIED, /* 304 */
37: HTERR_BAD_REQUEST, /* 400 */
38: HTERR_UNAUTHORIZED, /* 401 */
39: HTERR_PAYMENT_REQUIRED, /* 402 */
40: HTERR_FORBIDDEN, /* 403 */
41: HTERR_NOT_FOUND, /* 404 */
42: HTERR_INTERNAL, /* 500 */
43: HTERR_NOT_IMPLEMENTED, /* 501 */
44: HTERR_HTTP_CODES_END, /* Put all non-HTTP status codes after this */
45: HTERR_NO_REMOTE_HOST,
46: HTERR_FTP_SERVER,
47: HTERR_FTP_NO_RESPONSE,
48: HTERR_TIME_OUT,
2.2 frystyk 49: HTERR_GOPHER_SERVER,
50: HTERR_INTERRUPTED,
51: HTERR_CSO_SERVER,
52: HTERR_SYSTEM,
2.1 frystyk 53: HTERR_ELEMENTS /* This MUST be the last element */
54: } HTErrorElement;
2.3 frystyk 55:
56: typedef enum _HTErrSeverity {
57: ERR_FATAL = 0x1,
58: ERR_NON_FATAL = 0x3,
59: ERR_WARNING = 0x7
60: } HTErrSeverity;
61:
62: typedef struct _HTErrorInfo {
63: HTErrorElement element; /* Index number into HTErrorMsgInfo */
64: HTErrSeverity severity; /* A la VMS */
65: BOOL ignore; /* YES if msg should not go to user */
66: void * par; /* Explanation, e.g. filename */
67: unsigned int par_length; /* For copying by generic routine */
68: char * where; /* Which function */
69: } HTErrorInfo;
2.1 frystyk 70: </PRE>
71:
2.3 frystyk 72: <H2>Controling Globals</H2>
73:
74: This variable dictates which errors should be put out.
75:
76: <PRE>
77: typedef enum _HTErrorShow {
78: HT_ERR_SHOW_FATAL = 0x1,
79: HT_ERR_SHOW_NON_FATAL = 0x3,
80: HT_ERR_SHOW_WARNING = 0x7,
81: HT_ERR_SHOW_PARS = 0x8,
82: HT_ERR_SHOW_LOCATION = 0x10,
83: HT_ERR_SHOW_IGNORE = 0x20,
84: HT_ERR_SHOW_FIRST = 0x40,
85: HT_ERR_SHOW_ALL = 0x3F
86: } HTErrorShow;
87:
88: extern unsigned int HTErrorShowMask;
89: </PRE>
2.1 frystyk 90:
2.3 frystyk 91: This is the table containing the actual error-messages and links for more information:
2.1 frystyk 92:
93: <PRE>
2.3 frystyk 94: typedef struct _HTErrorMsgInfo {
95: int code; /* Error number */
96: char * msg; /* Short explanation */
97: char * url; /* Explaning URL */
98: } HTErrorMsgInfo;
99:
100: extern HTErrorMsgInfo error_info[];
2.1 frystyk 101: </PRE>
102:
2.3 frystyk 103: <H2>Public Error Functions</H2>
104:
2.1 frystyk 105: <H3>Add an Error Message</H3>
106:
107: This function adds an error message to the error_stack list in the HTRequest
2.3 frystyk 108: structure. It always returns a negative value.
2.1 frystyk 109: <PRE>
2.3 frystyk 110: extern int HTErrorAdd PARAMS(( HTRequest * request,
2.1 frystyk 111: HTErrSeverity severity,
112: BOOL ignore,
113: int element,
114: void * par,
115: unsigned int par_length,
116: char * where));
2.2 frystyk 117: </PRE>
118:
119: <H3>Add a System Error Message</H3>
120:
2.3 frystyk 121: 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 122: <PRE>
2.3 frystyk 123: extern int HTErrorSysAdd PARAMS(( HTRequest * request,
2.2 frystyk 124: HTErrSeverity severity,
125: BOOL ignore,
126: char * syscall));
2.1 frystyk 127: </PRE>
128:
129: <H3>Ignoring an Error Message</H3>
130:
131: If an error message is not to be send to the user, e.g., output to the stream, then the ignore flag must be turn on. This function turns it on for the latest error appended to the list.
132: <PRE>
133: extern void HTErrorIgnore PARAMS((HTRequest * request));
134: </PRE>
135:
2.3 frystyk 136: <H3>Generating an Error Message (default to standard output)</H3>
137:
138: This function outputs the content of the error_stack to standard output (used in Line Mode Browser), but smart clients and servers might overwrite this function so that the error messages can be handled to the user in a nice way. That is the reason for putting the actual implementation in HTML.c, that normally gets overwritten by clients and servers apart from Line Mode Browser. <P>
139:
2.4 ! frystyk 140: <NOTE><B>Note: </B></NOTE>
2.1 frystyk 141:
2.3 frystyk 142: If a stream <EM>has</EM> been put up (and maybe taken down again) inside the Library, then request->error_block has been set to YES. This indicates that it is NOT possible any more to use the stream as output for the message.
2.1 frystyk 143: <PRE>
144: extern void HTErrorMsg PARAMS((HTRequest * request));
145: </PRE>
146:
147: <H3>Freeing an Error List</H3>
148:
149: This is normally done when the HTRequest structure is freed but it might be done at any other time in order to ignore a whole series of errors.
150: <PRE>
151: extern void HTErrorFree PARAMS((HTRequest * request));
152: </PRE>
153:
154: <PRE>
155: #endif
156: </PRE>
157: end
158: </BODY>
159: </HTML>
160:
161:
Webmaster