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