File:  [Public] / libwww / Library / src / HTDialog.html
Revision 2.10: download - view: text, annotated - select for diffs
Fri Nov 11 14:03:15 2005 UTC (18 years, 7 months ago) by vbancrof
Branches: MAIN
CVS tags: candidate-5-4-1, HEAD
add extern c and HTFile_dirent_buf_size

<HTML>
<HEAD>
  <TITLE>W3C Sample Code Library libwww Messages and Dialogs</TITLE>
</HEAD>
<BODY>
<H1>
  Application side Error Messages And the like
</H1>
<PRE>
/*
**	(c) COPYRIGHT MIT 1995.
**	Please first read the full copyright statement in the file COPYRIGH.
*/
</PRE>
<P>
This module provides some "make life easier" functions in order to get the
application going. The functionality of this module was originally in
<A HREF="HTAccess.html">HTAccess</A>, but now It is part of the
<A HREF="WWWApp.html">application interface</A> which the application
<EM>may</EM> use it if desired.
<P>
This module is implemented by <A HREF="HTHome.c">HTHome.c</A>, and it is
a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
Library</A>.
<PRE>
#ifndef HTDIALOG_H
#define HTDIALOG_H
#include "WWWLib.h"

#ifdef __cplusplus
extern "C" { 
#endif 
</PRE>
<H2>
  <A NAME="English">Default English Error Messages and Progress Notifications</A>
</H2>
<P>
The following functions provide a default set of error messages and prompts
in plain English. You can of course change this as you like.
<H3>
  <A NAME="Prompt">Default English User Prompts and Questions</A>
</H3>
<P>
This list corresponds to the enumeration list defined in the
<A HREF="HTAlert.html#String">HTAlert module</A>
<PRE>
#define HT_MSG_ENGLISH_INITIALIZER \
    "Please enter username:", \
    "Please enter username for proxy authentication:", \
    "Please enter username for this FTP server:", \
    "Password:", \
    "Please give name of file to save in:", \
    "Plase enter account:", \
    "You might not be allowed to use this method here, continue?", \
    "Location has moved, continue?", \
    "A new set of rules is requested to be added to your setup - continue?", \
    "This file already exists - replace existing file?", \
    "Authentication failed - retry?", \
    "Proxy authentication failed - retry?", \
    "This method has already been performed - repeat operation?", \
    "This document is very big - continue operation?", \
    "The source document for this operation has moved - continue operation \
with new location?", \
    "The destination document for this operation has moved - continue \
operation with new location?", \
    "A redirection may change the behavior of this method - proceed anyway?", \
    "An automatic request for changing proxy has been encountered - continue?", \
    "The persistent cache is already in use by another user. If this is not \
the case then you can manually delete this lock and restart.", \
    "The server has sent you a cookie - accept?"
</PRE>
<H3>
  <A NAME="Messsages">Default English Messages and Progress Notifications</A>
</H3>
<P>
This list corresponds to the enumeration list defined in the
<A HREF="HTError.html#errorinfo">HTError module</A>
<PRE>
/*    CODE  ERROR MESSAGE				ERROR URL */
#define HTERR_ENGLISH_INITIALIZER \
    { 100, "Continue", 					"information" }, \
    { 101, "Switching Protocols",			"information" }, \
    { 200, "OK", 					"success" }, \
    { 201, "Created", 					"success" }, \
    { 202, "Accepted", 					"success" }, \
    { 203, "Non-authoritative Information",		"success" }, \
    { 204, "Document Updated",				"success" }, \
    { 205, "Reset Content",				"success" }, \
    { 206, "Partial Content",				"success" }, \
    { 207, "Partial Update OK",				"success" }, \
    { 300, "Multiple Choices",				"redirection" }, \
    { 301, "Moved Permanently",				"redirection" }, \
    { 302, "Found",  			                "redirection" }, \
    { 303, "See Other",					"redirection" }, \
    { 304, "Not Modified",       			"redirection" }, \
    { 305, "Use Proxy",					"redirection" }, \
    { 306, "Proxy Redirect",				"redirection" }, \
    { 307, "Temporary Redirect",			"redirection" }, \
    { 400, "Bad Request", 				"client_error" }, \
    { 401, "Unauthorized",				"client_error" }, \
    { 402, "Payment Required", 				"client_error" }, \
    { 403, "Forbidden", 				"client_error" }, \
    { 404, "Not Found",		       			"client_error" }, \
    { 405, "Method Not Allowed",	 		"client_error" }, \
    { 406, "Not Acceptable",		 		"client_error" }, \
    { 407, "Proxy Authentication Required", 		"client_error" }, \
    { 408, "Request Timeout",		 		"client_error" }, \
    { 409, "Conflict",			 		"client_error" }, \
    { 410, "Gone",			 		"client_error" }, \
    { 411, "Length Required",		 		"client_error" }, \
    { 412, "Precondition Failed",	 		"client_error" }, \
    { 413, "Request Entity Too Large",	 		"client_error" }, \
    { 414, "Request-URI Too Large",	 		"client_error" }, \
    { 415, "Unsupported Media Type",	 		"client_error" }, \
    { 416, "Range Not Satisfiable",	 		"client_error" }, \
    { 417, "Expectation Failed",	 		"client_error" }, \
    { 418, "Reauthentication Required",	 		"client_error" }, \
    { 419, "Proxy Reauthentication Reuired", 		"client_error" }, \
    { 500, "Internal Server Error",			"server_error" }, \
    { 501, "Not Implemented", 				"server_error" }, \
    { 502, "Bad Gateway", 				"server_error" }, \
    { 503, "Service Unavailable",			"server_error" }, \
    { 504, "Gateway Timeout", 				"server_error" }, \
    { 505, "HTTP Version not supported",		"server_error" }, \
    { 506, "Partial update Not Implemented",		"server_error" }, \
 \
    /* Cache Warnings */ \
    { 10,  "Response is Stale",				"cache" }, \
    { 11,  "Revalidation Failed",			"cache" }, \
    { 12,  "Disconnected Opeartion",			"cache" }, \
    { 13,  "Heuristic Expiration",			"cache" }, \
    { 14,  "Transformation Applied",			"cache" }, \
    { 99,  "Cache warning", 				"cache" }, \
 \
    /* Non-HTTP Error codes and warnings */ \
    { 0,   "Can't locate remote host", 			"internal" }, \
    { 0,   "No host name found", 			"internal" }, \
    { 0,   "No file name found or file not accessible", "internal" }, \
    { 0,   "FTP server replies", 			"internal" }, \
    { 0,   "FTP server doesn't reply", 			"internal" }, \
    { 0,   "FTP login failure", 			"internal" }, \
    { 0,   "Server timed out", 				"internal" }, \
    { 0,   "Gopher-server replies", 			"internal" }, \
    { 0,   "Data transfer interrupted", 		"internal" }, \
    { 0,   "Connection establishment interrupted", 	"internal" }, \
    { 0,   "CSO-server replies", 			"internal" }, \
    { 0,   "This is probably a HTTP server 0.9 or less","internal" }, \
    { 0,   "Bad, Incomplete, or Unknown Response",	"internal" }, \
    { 0,   "Unknown access authentication scheme",	"internal" }, \
    { 0,   "News-server replies",			"internal" }, \
    { 0,   "Trying `ftp://' instead of `file://'",	"internal" }, \
    { 0,   "Too many redirections",			"internal" }, \
    { 0,   "Method not suited for automatic redirection","internal" }, \
    { 0,   "Premature End Of File",			"internal" }, \
    { 0,   "Response from WAIS Server too Large - Extra lines \
ignored","internal"}, \
    { 0,   "WAIS-server doesn't return any data", 	"internal" }, \
    { 0,   "Can't connect to WAIS-server",		"internal" }, \
    { 0,   "operation failed",				"internal" }, \
    { 0,   "Wrong or unknown access scheme",		"internal" }, \
    { 0,   "Access scheme not allowed in this context",	"internal" }, \
    { 0,   "When you are connected, you can log in",	"internal" }, \
    { 0,   "This version has expired and will be automatically reloaded", "internal" }, \
    { 0,   "Loading new rules must be explicitly acknowledged", "internal" }, \
    { 0,   "Automatic proxy redirection must be explicitly acknowledged", "internal" }
</PRE>
<H3>
  Generate a Default Error Message
</H3>
<P>
This function provides an unformatted English string containing the possibly
nested status message that explains the result of a request. This is essentially
"flattening out" the information provided in the <A HREF="HTReq.html">request
error strack</A>. The string must be freed by the caller.
<PRE>
extern char * HTDialog_errorMessage (HTRequest * request, HTAlertOpcode op,
			             int msgnum, const char * dfault,
				     void * input);
</PRE>
<H3>
  Generate a Default Progress Notification Message
</H3>
<P>
This function provides a string containin an English progress message that
the application can present to the user if desired. The string must be freed
by the caller.
<PRE>
extern char * HTDialog_progressMessage (HTRequest * request, HTAlertOpcode op,
			                int msgnum, const char * dfault,
				        void * input);
</PRE>
<H2>
  Default User Interaction Handlers
</H2>
<P>
You can register a set of callback functions to handle user prompting, error
messages, confimations etc. Here we give a set of functions that can be used
on almost anu thinkable platform. If you want to provide your own platform
dependent implementation then fine :-)
<H3>
  Display a message, then wait for 'YES' or 'NO'
</H3>
<P>
This function prompts the user for a confirmation on the message passed as
a parameter. If the user reacts in the affirmative, returns <EM>TRUE</EM>,
returns <EM>FALSE</EM> otherwise.
<PRE>
extern HTAlertCallback HTConfirm;
</PRE>
<H3>
  Prompt the User a Question
</H3>
<P>
Prompt for answer and get text back. Reply text is either NULL on error or
a dynamic string which the caller must free.
<PRE>		
extern HTAlertCallback HTPrompt;
</PRE>
<H3>
  Prompt for a Password
</H3>
<P>
Prompt for password without echoing the reply. Reply text is weither NULL
on error or a dynamic string which the caller must free.
<P>
<B>NOTE:</B> The current version uses <EM>getpass</EM> which on many systems
returns a string of 8 or 16 bytes.
<PRE>
extern HTAlertCallback HTPromptPassword;
</PRE>
<H3>
  Prompt for a UserID and a Password
</H3>
<P>
This is just a composite function using <EM>HTPrompt</EM> and
<EM>HTPromptPassword</EM>. The strings returned must be freed by caller.
<PRE>
extern HTAlertCallback HTPromptUsernameAndPassword;
</PRE>
<H3>
  Display a Message
</H3>
<P>
This function simply puts out the message passed.
<PRE>
extern HTAlertCallback HTAlert;
</PRE>
<H3>
  Progress Notification
</H3>
<P>
This function can be used to indicate the current status of a certain action.
In order to avoid having strings directly in the core parts of the Library,
this function is passed a "state" argument from which the message can be
generated in this module. The "param" argument is for additional information
to be passed.
<PRE>
extern HTAlertCallback HTProgress;
</PRE>
<H3>
  Generating a User Error Message of a request
</H3>
<P>
This function outputs the content of the error list 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(r)
way. That is the reason for putting the actual implementation in
<A HREF="HTAlert.c">HTAlert.c</A>.
<P>
<PRE>
extern HTAlertCallback HTError_print;
</PRE>
<H3>
  Generating a Server Error Message of a request
</H3>
<P>
Default function that creates an error message using HTAlert() to put out
the contents of the error_stack messages. Furthermore, the error_info structure
contains a name of a help file that might be put up as a link. This file
can then be multi-linguistic.
<PRE>
extern BOOL HTError_response (HTRequest * request, HTAlertOpcode op,
			      int msgnum, const char * dfault, void * input,
			      HTAlertPar * reply);
</PRE>
<PRE>
#ifdef __cplusplus
}
#endif

#endif /* HTDIALOG_H */
</PRE>
<P>
  <HR>
<ADDRESS>
  @(#) $Id: HTDialog.html,v 2.10 2005/11/11 14:03:15 vbancrof Exp $
</ADDRESS>
</BODY></HTML>

Webmaster