Annotation of libwww/Library/src/HTDialog.html, revision 2.9
2.1 frystyk 1: <HTML>
2: <HEAD>
2.9 ! frystyk 3: <TITLE>W3C Sample Code Library libwww Messages and Dialogs</TITLE>
2.1 frystyk 4: </HEAD>
5: <BODY>
2.8 frystyk 6: <H1>
7: Application side Error Messages And the like
8: </H1>
2.1 frystyk 9: <PRE>
10: /*
11: ** (c) COPYRIGHT MIT 1995.
12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
2.8 frystyk 15: <P>
16: This module provides some "make life easier" functions in order to get the
17: application going. The functionality of this module was originally in
18: <A HREF="HTAccess.html">HTAccess</A>, but now It is part of the
19: <A HREF="WWWApp.html">application interface</A> which the application
20: <EM>may</EM> use it if desired.
21: <P>
22: This module is implemented by <A HREF="HTHome.c">HTHome.c</A>, and it is
23: a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
24: Library</A>.
2.1 frystyk 25: <PRE>
2.9 ! frystyk 26: #ifndef HTDIALOG_H
! 27: #define HTDIALOG_H
2.1 frystyk 28: #include "WWWLib.h"
29: </PRE>
2.8 frystyk 30: <H2>
2.9 ! frystyk 31: <A NAME="English">Default English Error Messages and Progress Notifications</A>
2.8 frystyk 32: </H2>
33: <P>
2.9 ! frystyk 34: The following functions provide a default set of error messages and prompts
! 35: in plain English. You can of course change this as you like.
! 36: <H3>
! 37: <A NAME="Prompt">Default English User Prompts and Questions</A>
! 38: </H3>
! 39: <P>
! 40: This list corresponds to the enumeration list defined in the
! 41: <A HREF="HTAlert.html#String">HTAlert module</A>
! 42: <PRE>
! 43: #define HT_MSG_ENGLISH_INITIALIZER \
! 44: "Please enter username:", \
! 45: "Please enter username for proxy authentication:", \
! 46: "Please enter username for this FTP server:", \
! 47: "Password:", \
! 48: "Please give name of file to save in:", \
! 49: "Plase enter account:", \
! 50: "You might not be allowed to use this method here, continue?", \
! 51: "Location has moved, continue?", \
! 52: "A new set of rules is requested to be added to your setup - continue?", \
! 53: "This file already exists - replace existing file?", \
! 54: "Authentication failed - retry?", \
! 55: "Proxy authentication failed - retry?", \
! 56: "This method has already been performed - repeat operation?", \
! 57: "This document is very big - continue operation?", \
! 58: "The source document for this operation has moved - continue operation \
! 59: with new location?", \
! 60: "The destination document for this operation has moved - continue \
! 61: operation with new location?", \
! 62: "A redirection may change the behavior of this method - proceed anyway?", \
! 63: "An automatic request for changing proxy has been encountered - continue?", \
! 64: "The persistent cache is already in use by another user. If this is not \
! 65: the case then you can manually delete this lock and restart.", \
! 66: "The server has sent you a cookie - accept?"
! 67: </PRE>
! 68: <H3>
! 69: <A NAME="Messsages">Default English Messages and Progress Notifications</A>
! 70: </H3>
! 71: <P>
! 72: This list corresponds to the enumeration list defined in the
! 73: <A HREF="HTError.html#errorinfo">HTError module</A>
! 74: <PRE>
! 75: /* CODE ERROR MESSAGE ERROR URL */
! 76: #define HTERR_ENGLISH_INITIALIZER \
! 77: { 100, "Continue", "information" }, \
! 78: { 101, "Switching Protocols", "information" }, \
! 79: { 200, "OK", "success" }, \
! 80: { 201, "Created", "success" }, \
! 81: { 202, "Accepted", "success" }, \
! 82: { 203, "Non-authoritative Information", "success" }, \
! 83: { 204, "Document Updated", "success" }, \
! 84: { 205, "Reset Content", "success" }, \
! 85: { 206, "Partial Content", "success" }, \
! 86: { 207, "Partial Update OK", "success" }, \
! 87: { 300, "Multiple Choices", "redirection" }, \
! 88: { 301, "Moved Permanently", "redirection" }, \
! 89: { 302, "Found", "redirection" }, \
! 90: { 303, "See Other", "redirection" }, \
! 91: { 304, "Not Modified", "redirection" }, \
! 92: { 305, "Use Proxy", "redirection" }, \
! 93: { 306, "Proxy Redirect", "redirection" }, \
! 94: { 307, "Temporary Redirect", "redirection" }, \
! 95: { 400, "Bad Request", "client_error" }, \
! 96: { 401, "Unauthorized", "client_error" }, \
! 97: { 402, "Payment Required", "client_error" }, \
! 98: { 403, "Forbidden", "client_error" }, \
! 99: { 404, "Not Found", "client_error" }, \
! 100: { 405, "Method Not Allowed", "client_error" }, \
! 101: { 406, "Not Acceptable", "client_error" }, \
! 102: { 407, "Proxy Authentication Required", "client_error" }, \
! 103: { 408, "Request Timeout", "client_error" }, \
! 104: { 409, "Conflict", "client_error" }, \
! 105: { 410, "Gone", "client_error" }, \
! 106: { 411, "Length Required", "client_error" }, \
! 107: { 412, "Precondition Failed", "client_error" }, \
! 108: { 413, "Request Entity Too Large", "client_error" }, \
! 109: { 414, "Request-URI Too Large", "client_error" }, \
! 110: { 415, "Unsupported Media Type", "client_error" }, \
! 111: { 416, "Range Not Satisfiable", "client_error" }, \
! 112: { 417, "Expectation Failed", "client_error" }, \
! 113: { 418, "Reauthentication Required", "client_error" }, \
! 114: { 419, "Proxy Reauthentication Reuired", "client_error" }, \
! 115: { 500, "Internal Server Error", "server_error" }, \
! 116: { 501, "Not Implemented", "server_error" }, \
! 117: { 502, "Bad Gateway", "server_error" }, \
! 118: { 503, "Service Unavailable", "server_error" }, \
! 119: { 504, "Gateway Timeout", "server_error" }, \
! 120: { 505, "HTTP Version not supported", "server_error" }, \
! 121: { 506, "Partial update Not Implemented", "server_error" }, \
! 122: \
! 123: /* Cache Warnings */ \
! 124: { 10, "Response is Stale", "cache" }, \
! 125: { 11, "Revalidation Failed", "cache" }, \
! 126: { 12, "Disconnected Opeartion", "cache" }, \
! 127: { 13, "Heuristic Expiration", "cache" }, \
! 128: { 14, "Transformation Applied", "cache" }, \
! 129: { 99, "Cache warning", "cache" }, \
! 130: \
! 131: /* Non-HTTP Error codes and warnings */ \
! 132: { 0, "Can't locate remote host", "internal" }, \
! 133: { 0, "No host name found", "internal" }, \
! 134: { 0, "No file name found or file not accessible", "internal" }, \
! 135: { 0, "FTP server replies", "internal" }, \
! 136: { 0, "FTP server doesn't reply", "internal" }, \
! 137: { 0, "FTP login failure", "internal" }, \
! 138: { 0, "Server timed out", "internal" }, \
! 139: { 0, "Gopher-server replies", "internal" }, \
! 140: { 0, "Data transfer interrupted", "internal" }, \
! 141: { 0, "Connection establishment interrupted", "internal" }, \
! 142: { 0, "CSO-server replies", "internal" }, \
! 143: { 0, "This is probably a HTTP server 0.9 or less","internal" }, \
! 144: { 0, "Bad, Incomplete, or Unknown Response", "internal" }, \
! 145: { 0, "Unknown access authentication scheme", "internal" }, \
! 146: { 0, "News-server replies", "internal" }, \
! 147: { 0, "Trying `ftp://' instead of `file://'", "internal" }, \
! 148: { 0, "Too many redirections", "internal" }, \
! 149: { 0, "Method not suited for automatic redirection","internal" }, \
! 150: { 0, "Premature End Of File", "internal" }, \
! 151: { 0, "Response from WAIS Server too Large - Extra lines \
! 152: ignored","internal"}, \
! 153: { 0, "WAIS-server doesn't return any data", "internal" }, \
! 154: { 0, "Can't connect to WAIS-server", "internal" }, \
! 155: { 0, "operation failed", "internal" }, \
! 156: { 0, "Wrong or unknown access scheme", "internal" }, \
! 157: { 0, "Access scheme not allowed in this context", "internal" }, \
! 158: { 0, "When you are connected, you can log in", "internal" }, \
! 159: { 0, "This version has expired and will be automatically reloaded", "internal" }, \
! 160: { 0, "Loading new rules must be explicitly acknowledged", "internal" }, \
! 161: { 0, "Automatic proxy redirection must be explicitly acknowledged", "internal" }
! 162: </PRE>
! 163: <H3>
! 164: Generate a Default Error Message
! 165: </H3>
! 166: <P>
2.8 frystyk 167: This function provides an unformatted English string containing the possibly
168: nested status message that explains the result of a request. This is essentially
169: "flattening out" the information provided in the <A HREF="HTReq.html">request
170: error strack</A>. The string must be freed by the caller.
171: <PRE>
172: extern char * HTDialog_errorMessage (HTRequest * request, HTAlertOpcode op,
173: int msgnum, const char * dfault,
174: void * input);
175: </PRE>
2.9 ! frystyk 176: <H3>
! 177: Generate a Default Progress Notification Message
! 178: </H3>
2.8 frystyk 179: <P>
180: This function provides a string containin an English progress message that
181: the application can present to the user if desired. The string must be freed
182: by the caller.
183: <PRE>
184: extern char * HTDialog_progressMessage (HTRequest * request, HTAlertOpcode op,
185: int msgnum, const char * dfault,
186: void * input);
187: </PRE>
188: <H2>
189: Default User Interaction Handlers
190: </H2>
191: <P>
192: You can register a set of callback functions to handle user prompting, error
193: messages, confimations etc. Here we give a set of functions that can be used
194: on almost anu thinkable platform. If you want to provide your own platform
195: dependent implementation then fine :-)
196: <H3>
197: Display a message, then wait for 'YES' or 'NO'
198: </H3>
199: <P>
200: This function prompts the user for a confirmation on the message passed as
201: a parameter. If the user reacts in the affirmative, returns <EM>TRUE</EM>,
202: returns <EM>FALSE</EM> otherwise.
2.1 frystyk 203: <PRE>
204: extern HTAlertCallback HTConfirm;
205: </PRE>
2.8 frystyk 206: <H3>
207: Prompt the User a Question
208: </H3>
209: <P>
210: Prompt for answer and get text back. Reply text is either NULL on error or
211: a dynamic string which the caller must free.
2.1 frystyk 212: <PRE>
213: extern HTAlertCallback HTPrompt;
214: </PRE>
2.8 frystyk 215: <H3>
216: Prompt for a Password
217: </H3>
218: <P>
219: Prompt for password without echoing the reply. Reply text is weither NULL
220: on error or a dynamic string which the caller must free.
221: <P>
222: <B>NOTE:</B> The current version uses <EM>getpass</EM> which on many systems
223: returns a string of 8 or 16 bytes.
2.1 frystyk 224: <PRE>
225: extern HTAlertCallback HTPromptPassword;
226: </PRE>
2.8 frystyk 227: <H3>
228: Prompt for a UserID and a Password
229: </H3>
230: <P>
2.1 frystyk 231: This is just a composite function using <EM>HTPrompt</EM> and
2.8 frystyk 232: <EM>HTPromptPassword</EM>. The strings returned must be freed by caller.
2.1 frystyk 233: <PRE>
234: extern HTAlertCallback HTPromptUsernameAndPassword;
235: </PRE>
2.8 frystyk 236: <H3>
237: Display a Message
238: </H3>
239: <P>
2.1 frystyk 240: This function simply puts out the message passed.
241: <PRE>
242: extern HTAlertCallback HTAlert;
243: </PRE>
2.8 frystyk 244: <H3>
245: Progress Notification
246: </H3>
247: <P>
248: This function can be used to indicate the current status of a certain action.
249: In order to avoid having strings directly in the core parts of the Library,
250: this function is passed a "state" argument from which the message can be
251: generated in this module. The "param" argument is for additional information
252: to be passed.
2.1 frystyk 253: <PRE>
254: extern HTAlertCallback HTProgress;
255: </PRE>
2.8 frystyk 256: <H3>
257: Generating a User Error Message of a request
258: </H3>
259: <P>
260: This function outputs the content of the error list to standard output (used
261: in Line Mode Browser), but smart clients and servers might overwrite this
262: function so that the error messages can be handled to the user in a nice(r)
263: way. That is the reason for putting the actual implementation in
264: <A HREF="HTAlert.c">HTAlert.c</A>.
265: <P>
2.1 frystyk 266: <PRE>
267: extern HTAlertCallback HTError_print;
2.2 frystyk 268: </PRE>
2.8 frystyk 269: <H3>
270: Generating a Server Error Message of a request
271: </H3>
272: <P>
273: Default function that creates an error message using HTAlert() to put out
274: the contents of the error_stack messages. Furthermore, the error_info structure
275: contains a name of a help file that might be put up as a link. This file
276: can then be multi-linguistic.
2.2 frystyk 277: <PRE>
278: extern BOOL HTError_response (HTRequest * request, HTAlertOpcode op,
2.3 frystyk 279: int msgnum, const char * dfault, void * input,
2.2 frystyk 280: HTAlertPar * reply);
2.1 frystyk 281: </PRE>
282: <PRE>
2.9 ! frystyk 283: #endif /* HTDIALOG_H */
2.1 frystyk 284: </PRE>
2.8 frystyk 285: <P>
286: <HR>
2.5 frystyk 287: <ADDRESS>
2.9 ! frystyk 288: @(#) $Id: HTDialog.html,v 2.8 1998/10/13 19:18:30 frystyk Exp $
2.5 frystyk 289: </ADDRESS>
2.8 frystyk 290: </BODY></HTML>
Webmaster