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 &nbsp;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&lt;&lt;8, /* Send a message - no reply */
                     71:     HT_A_CONFIRM       = 0x2&lt;&lt;8, /* Want YES or NO back */
                     72:     HT_A_PROMPT                = 0x4&lt;&lt;8, /* Want full dialog */
                     73:     HT_A_SECRET                = 0x8&lt;&lt;8, /* Secret dialog (e.g. password) */
                     74:     HT_A_USER_PW       = 0x10&lt;&lt;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