Annotation of libwww/Library/src/HTAlert.html, revision 2.39
2.6 timbl 1: <HTML>
2: <HEAD>
2.38 frystyk 3: <TITLE>W3C Reference Library libwww Library Alert Class</TITLE>
2.39 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 13-Jul-1996 -->
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
40: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference
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 */
65: HT_PROG_WAIT = 0x40, /* Wait for socket */
66: HT_A_PROGRESS = 0xFF, /* Send a progress report - no reply */
67:
68: /* First word are reserved for progresss notifications */
69:
70: HT_A_MESSAGE = 0x1<<8, /* Send a message - no reply */
71: HT_A_CONFIRM = 0x2<<8, /* Want YES or NO back */
72: HT_A_PROMPT = 0x4<<8, /* Want full dialog */
73: HT_A_SECRET = 0x8<<8, /* Secret dialog (e.g. password) */
74: HT_A_USER_PW = 0x10<<8 /* Atomic userid and password */
75: } HTAlertOpcode;
2.15 frystyk 76:
2.32 frystyk 77: typedef struct _HTAlertPar HTAlertPar;
2.8 luotonen 78:
2.32 frystyk 79: typedef BOOL HTAlertCallback (HTRequest * request, HTAlertOpcode op,
2.35 frystyk 80: int msgnum, const char * dfault, void * input,
2.32 frystyk 81: HTAlertPar * reply);
2.6 timbl 82: </PRE>
2.38 frystyk 83: <P>
84: If you don't expect any return values then <CODE>reply</CODE> can be NULL.
85: The return value of the callback function can be used to indicate confirmation
86: on a prompt (Yes or No).
87: <H3>
88: String Messages
89: </H3>
90: <P>
91: This is an enumerated list of messages that can be converted into a string
92: table etc.
2.15 frystyk 93: <PRE>
2.32 frystyk 94: typedef enum _HTAlertMsg {
95: HT_MSG_NULL = -1,
96: HT_MSG_UID = 0,
97: HT_MSG_PW,
98: HT_MSG_FILENAME,
99: HT_MSG_ACCOUNT,
100: HT_MSG_METHOD,
101: HT_MSG_MOVED,
102: HT_MSG_RULES,
2.39 ! frystyk 103: HT_MSG_FILE_REPLACE,
! 104: HT_MSG_RETRY_AUTHENTICATION,
2.32 frystyk 105: HT_MSG_ELEMENTS /* This MUST be the last element */
106: } HTAlertMsg;
2.15 frystyk 107: </PRE>
2.38 frystyk 108: <H2>
109: Enable or Disable Messages
110: </H2>
111: <P>
112: If you really don't want the library to prompt for anything at all then enable
113: this constant. The default value is <EM>Interactive</EM>.
2.32 frystyk 114: <PRE>
115: extern void HTAlert_setInteractive (BOOL interative);
116: extern BOOL HTAlert_interactive (void);
2.15 frystyk 117: </PRE>
2.38 frystyk 118: <H2>
119: Creation and Deletion Methods
120: </H2>
121: <P>
122: Message methods are registered in lists. By default a list is not enabled
123: before you assign it as being <I><A HREF="#active">active</A></I>. This allows
124: the application to maintain multiple lists of message handlers which can
125: be swapped in and out as neeeded.
126: <H3>
127: Add a Callback Function
128: </H3>
129: <P>
130: Register a call back function that is to be called when generating messages,
131: dialog, prompts, progress reports etc. The opcode signifies which call back
132: function to call depending of the type of the message. Opcode can be any
133: combination of the bitflags defined by <CODE>HTAlertOpcode</CODE>. If you
134: register one callback for <CODE>HT_A_PROGRESS </CODE>then this will get called
135: on all progress notifications.
2.15 frystyk 136: <PRE>
2.32 frystyk 137: extern BOOL HTAlertCall_add (HTList * list, HTAlertCallback * cbf,
138: HTAlertOpcode opcode);
2.15 frystyk 139: </PRE>
2.38 frystyk 140: <H3>
141: Delete a Callback function
142: </H3>
143: <P>
2.32 frystyk 144: Unregister a call back function from a list
2.8 luotonen 145: <PRE>
2.32 frystyk 146: extern BOOL HTAlertCall_delete (HTList * list, HTAlertCallback * cbf);
2.15 frystyk 147: </PRE>
2.38 frystyk 148: <H3>
149: Delete a list of Callback Functions
150: </H3>
151: <P>
2.32 frystyk 152: Unregisters all call back functions
153: <PRE>
154: extern BOOL HTAlertCall_deleteAll (HTList * list);
155: </PRE>
2.38 frystyk 156: <H3>
157: Find a Callback Function
158: </H3>
159: <P>
160: Finds a callback function corresponding to the opcode. If none has been
161: registered then NULL is returned.
2.6 timbl 162: <PRE>
2.32 frystyk 163: extern HTAlertCallback * HTAlertCall_find(HTList * list, HTAlertOpcode opcode);
2.6 timbl 164: </PRE>
2.38 frystyk 165: <H2>
166: The Reply Object
167: </H2>
168: <P>
169: The reply object is used for communicating input from the <I>user</I> back
170: to the Library. This is only required to use when for example the user is
171: prompted for a file name etc. You can find several examples on how to use
172: this in the <A HREF="HTDialog.html">default message and dialog module</A>
173: provided together with the Library.
174: <PRE>extern HTAlertPar * HTAlert_newReply (void);
2.32 frystyk 175: extern void HTAlert_deleteReply (HTAlertPar * old);
176: </PRE>
2.38 frystyk 177: <H3>
178: Handle the Reply Message
179: </H3>
180: <P>
181: These methods provide the API for handling the reply message. There are two
182: ways of assigning a message to the reply message - either by copying the
183: buffer or by reusing the same buffer. In the latter case, the caller must
184: make sure <B>not</B> to free the reply message before it has been used.
2.34 frystyk 185: <PRE>
2.35 frystyk 186: extern BOOL HTAlert_setReplyMessage (HTAlertPar * me, const char *message);
2.34 frystyk 187: extern BOOL HTAlert_assignReplyMessage (HTAlertPar * me, char * message);
188: </PRE>
2.38 frystyk 189: <P>
2.34 frystyk 190: You can get the data back again by using this method:
2.32 frystyk 191: <PRE>
192: extern char * HTAlert_replyMessage (HTAlertPar * me);
2.34 frystyk 193: </PRE>
194: <PRE>
2.32 frystyk 195: extern char * HTAlert_replySecret (HTAlertPar * me);
2.35 frystyk 196: extern BOOL HTAlert_setReplySecret (HTAlertPar * me, const char * secret);
2.6 timbl 197:
2.32 frystyk 198: extern void * HTAlert_replyOutput (HTAlertPar * me);
199: extern BOOL HTAlert_setReplyOutput (HTAlertPar * me, void * output);
2.17 frystyk 200: </PRE>
2.38 frystyk 201: <H2>
202: <A NAME="active">Active set of Callback Functions</A>
203: </H2>
204: <P>
205: A list can be assigned as being active in which case it is <I>visible</I>
206: for libwww. The Library does not know about inactive lists of methods.
2.32 frystyk 207: <PRE>
208: extern void HTAlert_setGlobal (HTList * list);
209: extern HTList * HTAlert_global (void);
210: </PRE>
2.38 frystyk 211: <P>
212: You can also assign a callback directly to the global list. In this case
213: you do not need to worry about creating the list - it will be created
214: automatically.
2.17 frystyk 215: <PRE>
2.33 frystyk 216: extern BOOL HTAlert_add (HTAlertCallback * cbf, HTAlertOpcode opcode);
217: extern BOOL HTAlert_delete (HTAlertCallback * cbf);
2.32 frystyk 218: extern HTAlertCallback * HTAlert_find (HTAlertOpcode opcode);
219: </PRE>
220: <PRE>
2.12 frystyk 221: #endif
222: </PRE>
2.38 frystyk 223: <P>
224: <HR>
2.37 frystyk 225: <ADDRESS>
2.39 ! frystyk 226: @(#) $Id: HTAlert.html,v 2.38 1996/05/20 15:06:23 frystyk Exp $
2.37 frystyk 227: </ADDRESS>
2.38 frystyk 228: </BODY></HTML>
Webmaster