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