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