Annotation of libwww/Library/src/HTAlert.html, revision 2.54
2.6 timbl 1: <HTML>
2: <HEAD>
2.51 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 13-Jul-1996 -->
2.46 frystyk 4: <TITLE>W3C Sample Code Library libwww Library Alert Class</TITLE>
2.6 timbl 5: </HEAD>
6: <BODY>
2.38 frystyk 7: <H1>
8: The Alert Class
9: </H1>
2.12 frystyk 10: <PRE>
11: /*
2.18 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.12 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
2.38 frystyk 16: <P>
17: The Alert class defines a set of methods to be used by libwww to be used
18: for passing prompts and message to a user. In order to maintain the Library
19: core application independent and natural language independent, libwww does
20: not know how to communicate with a <I>user</I>. Note here that a <I>user</I>
21: is a somewhat abstract notion for something that can receive a message
22: or prompt from the Library. This can for example be a person, but is may
23: also be handled automatically by a robot or a client receiving a response
24: from a HTTP server.
25: <P>
26: Libwww has a set of <B>opcodes</B> that classifies the nature of the message,
27: for example that it is a question that must be confirmed in order to continue
28: a request or simply a progress notification. The application can register
29: a method for any number of the defined opcodes - in case the Library has
30: a message for an opcode that does not have a method associated, the message
31: is ignored. You can also globally disable any message send from the Library.
32: <P>
33: <B>Note</B>: The library <B>core</B> does not define any message or dialog
34: methods - they are all considered part of the application. The library comes
35: with a <A HREF="HTDialog.html">default set of methods</A> which can be initiated
36: using the function <CODE>HTAlertInit()</CODE> in <A HREF="HTInit.html">HTInit
37: module</A>
38: <P>
39: This module is implemented by <A HREF="HTAlert.c">HTAlert.c</A>, and it is
2.50 frystyk 40: a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.38 frystyk 41: Library</A>.
2.11 frystyk 42: <PRE>
2.12 frystyk 43: #ifndef HTALERT_H
44: #define HTALERT_H
2.17 frystyk 45:
2.27 frystyk 46: #include "HTReq.h"
2.11 frystyk 47: </PRE>
2.38 frystyk 48: <H2>
49: Message Opcodes and Messages
50: </H2>
51: <P>
52: The callback functions are defined as a generic callback where the caller
53: can pass a set of input parameters and the callee can return a set of outptu
54: parameters. Also note that all the <CODE>*_PROG_*</CODE> opcodes are a subset
55: of <CODE>HT_A_PROGRESS</CODE>. This means that you easily can register a
56: callback for <EM>all</EM> progress reports.
2.32 frystyk 57: <PRE>
58: typedef enum _HTAlertOpcode {
59: HT_PROG_DNS = 0x1, /* Doing DNS resolution */
60: HT_PROG_CONNECT = 0x2, /* Connecting Active */
61: HT_PROG_ACCEPT = 0x4, /* Connecting Passive */
62: HT_PROG_READ = 0x8, /* Read data */
63: HT_PROG_WRITE = 0x10, /* Write data */
64: HT_PROG_DONE = 0x20, /* Request finished */
2.53 frystyk 65: HT_PROG_INTERRUPT = 0x40, /* Request interrupted */
66: HT_PROG_OTHER = 0x80, /* Other progress notes */
67: HT_PROG_TIMEOUT = 0x100, /* Request timed out */
2.54 ! frystyk 68: HT_PROG_LOGIN = 0x200, /* Automatic login notifications */
2.53 frystyk 69: HT_A_PROGRESS = 0xFFFF, /* Get all progress reports - no reply */
2.32 frystyk 70:
71: /* First word are reserved for progresss notifications */
72:
2.53 frystyk 73: HT_A_MESSAGE = 0x1<<16, /* Send a message - no reply */
74: HT_A_CONFIRM = 0x2<<16, /* Want YES or NO back */
75: HT_A_PROMPT = 0x4<<16, /* Want full dialog */
76: HT_A_SECRET = 0x8<<16, /* Secret dialog (e.g. password) */
77: HT_A_USER_PW = 0x10<<16 /* Atomic userid and password */
2.32 frystyk 78: } HTAlertOpcode;
2.15 frystyk 79:
2.32 frystyk 80: typedef struct _HTAlertPar HTAlertPar;
2.8 luotonen 81:
2.32 frystyk 82: typedef BOOL HTAlertCallback (HTRequest * request, HTAlertOpcode op,
2.35 frystyk 83: int msgnum, const char * dfault, void * input,
2.32 frystyk 84: HTAlertPar * reply);
2.6 timbl 85: </PRE>
2.38 frystyk 86: <P>
87: If you don't expect any return values then <CODE>reply</CODE> can be NULL.
88: The return value of the callback function can be used to indicate confirmation
89: on a prompt (Yes or No).
90: <H3>
91: String Messages
92: </H3>
93: <P>
94: This is an enumerated list of messages that can be converted into a string
95: table etc.
2.15 frystyk 96: <PRE>
2.32 frystyk 97: typedef enum _HTAlertMsg {
98: HT_MSG_NULL = -1,
99: HT_MSG_UID = 0,
2.43 frystyk 100: HT_MSG_PROXY_UID,
101: HT_MSG_FTP_UID,
2.32 frystyk 102: HT_MSG_PW,
103: HT_MSG_FILENAME,
104: HT_MSG_ACCOUNT,
105: HT_MSG_METHOD,
106: HT_MSG_MOVED,
107: HT_MSG_RULES,
2.39 frystyk 108: HT_MSG_FILE_REPLACE,
109: HT_MSG_RETRY_AUTHENTICATION,
2.41 frystyk 110: HT_MSG_RETRY_PROXY_AUTH,
2.40 frystyk 111: HT_MSG_REDO,
112: HT_MSG_BIG_PUT,
113: HT_MSG_SOURCE_MOVED,
114: HT_MSG_DESTINATION_MOVED,
2.41 frystyk 115: HT_MSG_REDIRECTION,
2.47 frystyk 116: HT_MSG_PROXY,
2.48 frystyk 117: HT_MSG_CACHE_LOCK,
2.32 frystyk 118: HT_MSG_ELEMENTS /* This MUST be the last element */
119: } HTAlertMsg;
2.45 eric 120:
121: #define HT_MSG_ENGLISH_INITIALIZER \
122: "Please enter username:", \
123: "Please enter username for proxy authentication:", \
124: "Please enter username for this FTP server:", \
125: "Password:", \
126: "Please give name of file to save in:", \
127: "Plase enter account:", \
128: "You might not be allowed to use this method here, continue?", \
129: "Location has moved, continue?", \
2.47 frystyk 130: "A new set of rules is requested to be added to your setup - continue?", \
2.45 eric 131: "This file already exists - replace existing file?", \
132: "Authentication failed - retry?", \
133: "Proxy authentication failed - retry?", \
134: "This method has already been performed - repeat operation?", \
135: "This document is very big - continue operation?", \
136: "The source document for this operation has moved - continue operation \
137: with new location?", \
138: "The destination document for this operation has moved - continue \
139: operation with new location?", \
2.47 frystyk 140: "A redirection may change the behavior of this method - proceed anyway?", \
2.48 frystyk 141: "An automatic request for changing proxy has been encountered - continue?", \
142: "The persistent cache is already in use by another user. If this is not \
143: the case then you can manually delete this lock and restart."
2.15 frystyk 144: </PRE>
2.38 frystyk 145: <H2>
146: Enable or Disable Messages
147: </H2>
148: <P>
149: If you really don't want the library to prompt for anything at all then enable
150: this constant. The default value is <EM>Interactive</EM>.
2.32 frystyk 151: <PRE>
152: extern void HTAlert_setInteractive (BOOL interative);
153: extern BOOL HTAlert_interactive (void);
2.15 frystyk 154: </PRE>
2.38 frystyk 155: <H2>
156: Creation and Deletion Methods
157: </H2>
158: <P>
159: Message methods are registered in lists. By default a list is not enabled
160: before you assign it as being <I><A HREF="#active">active</A></I>. This allows
161: the application to maintain multiple lists of message handlers which can
162: be swapped in and out as neeeded.
163: <H3>
164: Add a Callback Function
165: </H3>
166: <P>
167: Register a call back function that is to be called when generating messages,
168: dialog, prompts, progress reports etc. The opcode signifies which call back
169: function to call depending of the type of the message. Opcode can be any
170: combination of the bitflags defined by <CODE>HTAlertOpcode</CODE>. If you
171: register one callback for <CODE>HT_A_PROGRESS </CODE>then this will get called
172: on all progress notifications.
2.15 frystyk 173: <PRE>
2.32 frystyk 174: extern BOOL HTAlertCall_add (HTList * list, HTAlertCallback * cbf,
175: HTAlertOpcode opcode);
2.15 frystyk 176: </PRE>
2.38 frystyk 177: <H3>
178: Delete a Callback function
179: </H3>
180: <P>
2.32 frystyk 181: Unregister a call back function from a list
2.8 luotonen 182: <PRE>
2.32 frystyk 183: extern BOOL HTAlertCall_delete (HTList * list, HTAlertCallback * cbf);
2.15 frystyk 184: </PRE>
2.38 frystyk 185: <H3>
2.51 frystyk 186: Delete all Callbacks With this Opcode
187: </H3>
188: <P>
189: Unregister all handlers registered for a given opcode.
190: <PRE>
191: extern BOOL HTAlertCall_deleteOpcode (HTList * list, HTAlertOpcode opcode);
192: </PRE>
193: <H3>
2.38 frystyk 194: Delete a list of Callback Functions
195: </H3>
196: <P>
2.32 frystyk 197: Unregisters all call back functions
198: <PRE>
199: extern BOOL HTAlertCall_deleteAll (HTList * list);
200: </PRE>
2.38 frystyk 201: <H3>
202: Find a Callback Function
203: </H3>
204: <P>
205: Finds a callback function corresponding to the opcode. If none has been
206: registered then NULL is returned.
2.6 timbl 207: <PRE>
2.32 frystyk 208: extern HTAlertCallback * HTAlertCall_find(HTList * list, HTAlertOpcode opcode);
2.6 timbl 209: </PRE>
2.38 frystyk 210: <H2>
211: The Reply Object
212: </H2>
213: <P>
214: The reply object is used for communicating input from the <I>user</I> back
215: to the Library. This is only required to use when for example the user is
216: prompted for a file name etc. You can find several examples on how to use
217: this in the <A HREF="HTDialog.html">default message and dialog module</A>
218: provided together with the Library.
219: <PRE>extern HTAlertPar * HTAlert_newReply (void);
2.32 frystyk 220: extern void HTAlert_deleteReply (HTAlertPar * old);
221: </PRE>
2.38 frystyk 222: <H3>
223: Handle the Reply Message
224: </H3>
225: <P>
226: These methods provide the API for handling the reply message. There are two
227: ways of assigning a message to the reply message - either by copying the
228: buffer or by reusing the same buffer. In the latter case, the caller must
229: make sure <B>not</B> to free the reply message before it has been used.
2.34 frystyk 230: <PRE>
2.35 frystyk 231: extern BOOL HTAlert_setReplyMessage (HTAlertPar * me, const char *message);
2.34 frystyk 232: extern BOOL HTAlert_assignReplyMessage (HTAlertPar * me, char * message);
233: </PRE>
2.38 frystyk 234: <P>
2.34 frystyk 235: You can get the data back again by using this method:
2.32 frystyk 236: <PRE>
237: extern char * HTAlert_replyMessage (HTAlertPar * me);
2.34 frystyk 238: </PRE>
239: <PRE>
2.32 frystyk 240: extern char * HTAlert_replySecret (HTAlertPar * me);
2.35 frystyk 241: extern BOOL HTAlert_setReplySecret (HTAlertPar * me, const char * secret);
2.6 timbl 242:
2.32 frystyk 243: extern void * HTAlert_replyOutput (HTAlertPar * me);
244: extern BOOL HTAlert_setReplyOutput (HTAlertPar * me, void * output);
2.17 frystyk 245: </PRE>
2.38 frystyk 246: <H2>
247: <A NAME="active">Active set of Callback Functions</A>
248: </H2>
249: <P>
250: A list can be assigned as being active in which case it is <I>visible</I>
2.51 frystyk 251: for libwww by assigning the list as the <I>global alert list</I>. Libwww
252: does not know about inactive lists of alert handlers.
2.32 frystyk 253: <PRE>
254: extern void HTAlert_setGlobal (HTList * list);
255: extern HTList * HTAlert_global (void);
256: </PRE>
2.51 frystyk 257: <H3>
258: Global Alert List Methods
259: </H3>
2.38 frystyk 260: <P>
2.51 frystyk 261: You can assign a callback directly to the global list in which case it becomes
262: immediately available to libwww. In this case you do not need to worry about
263: creating the list - it will be created as well as deleted automatically.
264: <H4>
265: Add an Alert Handler
266: </H4>
267: <PRE>
268: extern BOOL HTAlert_add (HTAlertCallback * cbf, HTAlertOpcode opcode);
269: </PRE>
270: <H4>
271: Delete an Alert Handler
272: </H4>
273: <P>
274: You can either delete a handler by referring to its address or to the opcode
275: that it has been registered for.
276: <PRE>
277: extern BOOL HTAlert_delete (HTAlertCallback * cbf);
278: extern BOOL HTAlert_deleteOpcode (HTAlertOpcode opcode);
279: </PRE>
280: <H4>
281: Delete all Alert Handlers
282: </H4>
2.17 frystyk 283: <PRE>
2.49 frystyk 284: extern BOOL HTAlert_deleteAll (void);
2.51 frystyk 285: </PRE>
286: <H4>
287: Find an Alert Handler
288: </H4>
289: <PRE>
2.32 frystyk 290: extern HTAlertCallback * HTAlert_find (HTAlertOpcode opcode);
291: </PRE>
292: <PRE>
2.12 frystyk 293: #endif
294: </PRE>
2.38 frystyk 295: <P>
296: <HR>
2.37 frystyk 297: <ADDRESS>
2.54 ! frystyk 298: @(#) $Id: HTAlert.html,v 2.53 1998/09/01 18:02:18 frystyk Exp $
2.37 frystyk 299: </ADDRESS>
2.38 frystyk 300: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTAlert.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src