Annotation of libwww/Library/src/HTAlert.html, revision 2.38
2.6 timbl 1: <HTML>
2: <HEAD>
2.38 ! frystyk 3: <TITLE>W3C Reference Library libwww Library Alert Class</TITLE>
2.6 timbl 4: </HEAD>
5: <BODY>
2.38 ! frystyk 6: <H1>
! 7: The Alert Class
! 8: </H1>
2.12 frystyk 9: <PRE>
10: /*
2.18 frystyk 11: ** (c) COPYRIGHT MIT 1995.
2.12 frystyk 12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
2.38 ! frystyk 15: <P>
! 16: The Alert class defines a set of methods to be used by libwww to be used
! 17: for passing prompts and message to a user. In order to maintain the Library
! 18: core application independent and natural language independent, libwww does
! 19: not know how to communicate with a <I>user</I>. Note here that a <I>user</I>
! 20: is a somewhat abstract notion for something that can receive a message
! 21: or prompt from the Library. This can for example be a person, but is may
! 22: also be handled automatically by a robot or a client receiving a response
! 23: from a HTTP server.
! 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
! 28: a method for any number of the defined opcodes - in case the Library has
! 29: a message for an opcode that does not have a method associated, the message
! 30: is ignored. You can also globally disable any message send from the Library.
! 31: <P>
! 32: <B>Note</B>: The library <B>core</B> does not define any message or dialog
! 33: methods - they are all considered part of the application. The library comes
! 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
! 39: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference
! 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.11 frystyk 46: </PRE>
2.38 ! frystyk 47: <H2>
! 48: Message Opcodes and Messages
! 49: </H2>
! 50: <P>
! 51: The callback functions are defined as a generic callback where the caller
! 52: can pass a set of input parameters and the callee can return a set of outptu
! 53: parameters. Also note that all the <CODE>*_PROG_*</CODE> opcodes are a subset
! 54: of <CODE>HT_A_PROGRESS</CODE>. This means that you easily can register a
! 55: callback for <EM>all</EM> progress reports.
2.32 frystyk 56: <PRE>
57: typedef enum _HTAlertOpcode {
58: HT_PROG_DNS = 0x1, /* Doing DNS resolution */
59: HT_PROG_CONNECT = 0x2, /* Connecting Active */
60: HT_PROG_ACCEPT = 0x4, /* Connecting Passive */
61: HT_PROG_READ = 0x8, /* Read data */
62: HT_PROG_WRITE = 0x10, /* Write data */
63: HT_PROG_DONE = 0x20, /* Request finished */
64: HT_PROG_WAIT = 0x40, /* Wait for socket */
65: HT_A_PROGRESS = 0xFF, /* Send a progress report - no reply */
66:
67: /* First word are reserved for progresss notifications */
68:
69: HT_A_MESSAGE = 0x1<<8, /* Send a message - no reply */
70: HT_A_CONFIRM = 0x2<<8, /* Want YES or NO back */
71: HT_A_PROMPT = 0x4<<8, /* Want full dialog */
72: HT_A_SECRET = 0x8<<8, /* Secret dialog (e.g. password) */
73: HT_A_USER_PW = 0x10<<8 /* Atomic userid and password */
74: } HTAlertOpcode;
2.15 frystyk 75:
2.32 frystyk 76: typedef struct _HTAlertPar HTAlertPar;
2.8 luotonen 77:
2.32 frystyk 78: typedef BOOL HTAlertCallback (HTRequest * request, HTAlertOpcode op,
2.35 frystyk 79: int msgnum, const char * dfault, void * input,
2.32 frystyk 80: HTAlertPar * reply);
2.6 timbl 81: </PRE>
2.38 ! frystyk 82: <P>
! 83: If you don't expect any return values then <CODE>reply</CODE> can be NULL.
! 84: The return value of the callback function can be used to indicate confirmation
! 85: on a prompt (Yes or No).
! 86: <H3>
! 87: String Messages
! 88: </H3>
! 89: <P>
! 90: This is an enumerated list of messages that can be converted into a string
! 91: table etc.
2.15 frystyk 92: <PRE>
2.32 frystyk 93: typedef enum _HTAlertMsg {
94: HT_MSG_NULL = -1,
95: HT_MSG_UID = 0,
96: HT_MSG_PW,
97: HT_MSG_FILENAME,
98: HT_MSG_ACCOUNT,
99: HT_MSG_METHOD,
100: HT_MSG_MOVED,
101: HT_MSG_RULES,
102: HT_MSG_ELEMENTS /* This MUST be the last element */
103: } HTAlertMsg;
2.15 frystyk 104: </PRE>
2.38 ! frystyk 105: <H2>
! 106: Enable or Disable Messages
! 107: </H2>
! 108: <P>
! 109: If you really don't want the library to prompt for anything at all then enable
! 110: this constant. The default value is <EM>Interactive</EM>.
2.32 frystyk 111: <PRE>
112: extern void HTAlert_setInteractive (BOOL interative);
113: extern BOOL HTAlert_interactive (void);
2.15 frystyk 114: </PRE>
2.38 ! frystyk 115: <H2>
! 116: Creation and Deletion Methods
! 117: </H2>
! 118: <P>
! 119: Message methods are registered in lists. By default a list is not enabled
! 120: before you assign it as being <I><A HREF="#active">active</A></I>. This allows
! 121: the application to maintain multiple lists of message handlers which can
! 122: be swapped in and out as neeeded.
! 123: <H3>
! 124: Add a Callback Function
! 125: </H3>
! 126: <P>
! 127: Register a call back function that is to be called when generating messages,
! 128: dialog, prompts, progress reports etc. The opcode signifies which call back
! 129: function to call depending of the type of the message. Opcode can be any
! 130: combination of the bitflags defined by <CODE>HTAlertOpcode</CODE>. If you
! 131: register one callback for <CODE>HT_A_PROGRESS </CODE>then this will get called
! 132: on all progress notifications.
2.15 frystyk 133: <PRE>
2.32 frystyk 134: extern BOOL HTAlertCall_add (HTList * list, HTAlertCallback * cbf,
135: HTAlertOpcode opcode);
2.15 frystyk 136: </PRE>
2.38 ! frystyk 137: <H3>
! 138: Delete a Callback function
! 139: </H3>
! 140: <P>
2.32 frystyk 141: Unregister a call back function from a list
2.8 luotonen 142: <PRE>
2.32 frystyk 143: extern BOOL HTAlertCall_delete (HTList * list, HTAlertCallback * cbf);
2.15 frystyk 144: </PRE>
2.38 ! frystyk 145: <H3>
! 146: Delete a list of Callback Functions
! 147: </H3>
! 148: <P>
2.32 frystyk 149: Unregisters all call back functions
150: <PRE>
151: extern BOOL HTAlertCall_deleteAll (HTList * list);
152: </PRE>
2.38 ! frystyk 153: <H3>
! 154: Find a Callback Function
! 155: </H3>
! 156: <P>
! 157: Finds a callback function corresponding to the opcode. If none has been
! 158: registered then NULL is returned.
2.6 timbl 159: <PRE>
2.32 frystyk 160: extern HTAlertCallback * HTAlertCall_find(HTList * list, HTAlertOpcode opcode);
2.6 timbl 161: </PRE>
2.38 ! frystyk 162: <H2>
! 163: The Reply Object
! 164: </H2>
! 165: <P>
! 166: The reply object is used for communicating input from the <I>user</I> back
! 167: to the Library. This is only required to use when for example the user is
! 168: prompted for a file name etc. You can find several examples on how to use
! 169: this in the <A HREF="HTDialog.html">default message and dialog module</A>
! 170: provided together with the Library.
! 171: <PRE>extern HTAlertPar * HTAlert_newReply (void);
2.32 frystyk 172: extern void HTAlert_deleteReply (HTAlertPar * old);
173: </PRE>
2.38 ! frystyk 174: <H3>
! 175: Handle the Reply Message
! 176: </H3>
! 177: <P>
! 178: These methods provide the API for handling the reply message. There are two
! 179: ways of assigning a message to the reply message - either by copying the
! 180: buffer or by reusing the same buffer. In the latter case, the caller must
! 181: make sure <B>not</B> to free the reply message before it has been used.
2.34 frystyk 182: <PRE>
2.35 frystyk 183: extern BOOL HTAlert_setReplyMessage (HTAlertPar * me, const char *message);
2.34 frystyk 184: extern BOOL HTAlert_assignReplyMessage (HTAlertPar * me, char * message);
185: </PRE>
2.38 ! frystyk 186: <P>
2.34 frystyk 187: You can get the data back again by using this method:
2.32 frystyk 188: <PRE>
189: extern char * HTAlert_replyMessage (HTAlertPar * me);
2.34 frystyk 190: </PRE>
191: <PRE>
2.32 frystyk 192: extern char * HTAlert_replySecret (HTAlertPar * me);
2.35 frystyk 193: extern BOOL HTAlert_setReplySecret (HTAlertPar * me, const char * secret);
2.6 timbl 194:
2.32 frystyk 195: extern void * HTAlert_replyOutput (HTAlertPar * me);
196: extern BOOL HTAlert_setReplyOutput (HTAlertPar * me, void * output);
2.17 frystyk 197: </PRE>
2.38 ! frystyk 198: <H2>
! 199: <A NAME="active">Active set of Callback Functions</A>
! 200: </H2>
! 201: <P>
! 202: A list can be assigned as being active in which case it is <I>visible</I>
! 203: for libwww. The Library does not know about inactive lists of methods.
2.32 frystyk 204: <PRE>
205: extern void HTAlert_setGlobal (HTList * list);
206: extern HTList * HTAlert_global (void);
207: </PRE>
2.38 ! frystyk 208: <P>
! 209: You can also assign a callback directly to the global list. In this case
! 210: you do not need to worry about creating the list - it will be created
! 211: automatically.
2.17 frystyk 212: <PRE>
2.33 frystyk 213: extern BOOL HTAlert_add (HTAlertCallback * cbf, HTAlertOpcode opcode);
214: extern BOOL HTAlert_delete (HTAlertCallback * cbf);
2.32 frystyk 215: extern HTAlertCallback * HTAlert_find (HTAlertOpcode opcode);
216: </PRE>
217: <PRE>
2.12 frystyk 218: #endif
219: </PRE>
2.38 ! frystyk 220: <P>
! 221: <HR>
2.37 frystyk 222: <ADDRESS>
2.38 ! frystyk 223: @(#) $Id: HTAlert.html,v 2.37 1996/04/12 17:45:42 frystyk Exp $
2.37 frystyk 224: </ADDRESS>
2.38 ! frystyk 225: </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