[BACK]Return to HTAlert.html CVS log [TXT] [DIR] Up to [Public] / libwww / Library / src
File:  [Public] / libwww / Library / src / HTAlert.html
Revision 2.56: download - view: text, annotated - select for diffs
Wed Jun 30 20:15:03 1999 UTC (24 years, 10 months ago) by frystyk
Branches: MAIN
CVS tags: repeat-requests, before_webdav, Release-5-4-0, Release-5-3-1, HEAD, Amaya-6-3, Amaya-6-1, Amaya-5-2, Amaya-4-3-2, Amaya-4-3-1, Amaya-4-3, Amaya-4-1-2, Amaya-4-1-0, Amaya-4-0-0, Amaya-3-2-1, Amaya-3-2, Amaya
added note that progress callbacks shouldn't be used to interrupt a requests

<HTML>
<HEAD>
  <!-- Changed by: Henrik Frystyk Nielsen, 13-Jul-1996 -->
  <TITLE>W3C Sample Code Library libwww Library Alert Class</TITLE>
</HEAD>
<BODY>
<H1>
  The Alert Class
</H1>
<PRE>
/*
**	(c) COPYRIGHT MIT 1995.
**	Please first read the full copyright statement in the file COPYRIGH.
*/
</PRE>
<P>
The Alert class defines a set of methods to be used by libwww for passing
prompts and message to the application. In order to maintain libwww application
independent and natural language independent, it does not know how to communicate
with a <I>user</I>. Note here that a <I>user</I> is a somewhat abstract notion
for &nbsp;something that can receive a message or prompt from libwww. A
<EM>user</EM> can for example be a person, but is may also be handled
automatically by a robot or a client receiving a response from a HTTP server.
<P>
Libwww has a set of <B>opcodes</B> that classifies the nature of the message,
for example that it is a question that must be confirmed in order to continue
a request or simply a progress notification. The application can register
a callback for any number of the defined opcodes - in case libwww has a message
for an opcode that does not have a method associated, the message is ignored.
You can also globally disable any message send from libwww.
<P>
<B>Note</B>: The library <B>core</B> does not define any message or dialog
methods - they are all considered part of the application. However, it comes
with a <A HREF="HTDialog.html">default set of methods</A> which can be initiated
using the function <CODE>HTAlertInit()</CODE> in <A HREF="HTInit.html">HTInit
module</A>
<P>
This module is implemented by <A HREF="HTAlert.c">HTAlert.c</A>, and it is
a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
Library</A>.
<PRE>
#ifndef HTALERT_H
#define HTALERT_H

#include "HTReq.h"
</PRE>
<H2>
  <A NAME="Message">Message Opcodes and Messages</A>
</H2>
<P>
The callback functions are defined as a generic callback where the caller
can pass a set of input parameters and the callee can return a set of outptu
parameters. Also note that all the <CODE>*_PROG_*</CODE> opcodes are a subset
of <CODE>HT_A_PROGRESS</CODE>. This means that you easily can register a
callback for <EM>all</EM> progress reports. 
<P>
The callback handler for progress notifications <EM>SHOULD NOT</EM> be used
to interrupt the ongoing message as it is not guaranteed to be in a state
to do so. Instead you should use the <A HREF="HTEvent.html">event handlers</A>
or the <A HREF="HTTimer.html">timers</A> for this.
<PRE>
typedef enum _HTAlertOpcode {
    HT_PROG_DNS		= 0x1,		/* Doing DNS resolution */
    HT_PROG_CONNECT	= 0x2,		/* Connecting Active */
    HT_PROG_ACCEPT	= 0x4,		/* Connecting Passive */
    HT_PROG_READ	= 0x8,		/* Read data */
    HT_PROG_WRITE	= 0x10,		/* Write data */
    HT_PROG_DONE	= 0x20,		/* Request finished */
    HT_PROG_INTERRUPT   = 0x40,         /* Request interrupted */
    HT_PROG_OTHER       = 0x80,         /* Other progress notes */
    HT_PROG_TIMEOUT     = 0x100,        /* Request timed out */
    HT_PROG_LOGIN	= 0x200,	/* Automatic login notifications */
    HT_A_PROGRESS	= 0xFFFF,	/* Get all progress reports - no reply */

    /* First word are reserved for progresss notifications */

    HT_A_MESSAGE	= 0x1&lt;&lt;16, /* Send a message - no reply */
    HT_A_CONFIRM	= 0x2&lt;&lt;16, /* Want YES or NO back */
    HT_A_PROMPT		= 0x4&lt;&lt;16, /* Want full dialog */
    HT_A_SECRET		= 0x8&lt;&lt;16, /* Secret dialog (e.g. password) */
    HT_A_USER_PW	= 0x10&lt;&lt;16 /* Atomic userid and password */
} HTAlertOpcode;

typedef struct _HTAlertPar HTAlertPar;

typedef BOOL HTAlertCallback   (HTRequest * request, HTAlertOpcode op,
				int msgnum, const char * dfault, void * input,
				HTAlertPar * reply);
</PRE>
<P>
If you don't expect any return values then <CODE>reply</CODE> can be NULL.
The return value of the callback function can be used to indicate confirmation
on a prompt (Yes or No).
<H2>
  <A NAME="String">User Prompts and Questions</A>
</H2>
<P>
This is an enumerated list of messages that can be converted into a string
table etc. See the <A HREF="HTDialog.html#Prompt">HTDialog module</A> for
default initialization of these strings.
<PRE>
typedef enum _HTAlertMsg {
    HT_MSG_NULL = -1,
    HT_MSG_UID = 0,
    HT_MSG_PROXY_UID,
    HT_MSG_FTP_UID,
    HT_MSG_PW,
    HT_MSG_FILENAME,
    HT_MSG_ACCOUNT,
    HT_MSG_METHOD,
    HT_MSG_MOVED,
    HT_MSG_RULES,
    HT_MSG_FILE_REPLACE,
    HT_MSG_RETRY_AUTHENTICATION,
    HT_MSG_RETRY_PROXY_AUTH,
    HT_MSG_REDO,
    HT_MSG_BIG_PUT,
    HT_MSG_SOURCE_MOVED,
    HT_MSG_DESTINATION_MOVED,
    HT_MSG_REDIRECTION,
    HT_MSG_PROXY,
    HT_MSG_CACHE_LOCK,
    HT_MSG_ACCEPT_COOKIE,
    HT_MSG_ELEMENTS		            /* This MUST be the last element */
} HTAlertMsg;
</PRE>
<H2>
  <A NAME="Enable">Enable or Disable Messages</A>
</H2>
<P>
If you really don't want the library to prompt for anything at all then enable
this constant. The default value is <EM>Interactive</EM>.
<PRE>
extern void HTAlert_setInteractive	(BOOL interative);
extern BOOL HTAlert_interactive		(void);
</PRE>
<H2>
  <A NAME="Creation">Creation and Deletion Methods</A>
</H2>
<P>
Message methods are registered in lists. By default a list is not enabled
before you assign it as being <I><A HREF="#active">active</A></I>. This allows
the application to maintain multiple lists of message handlers which can
be swapped in and out as neeeded.
<H3>
  Add a Callback Function
</H3>
<P>
Register a call back function that is to be called when generating messages,
dialog, prompts, progress reports etc. The opcode signifies which call back
function to call depending of the type of the message. Opcode can be any
combination of the bitflags defined by <CODE>HTAlertOpcode</CODE>. If you
register one callback for <CODE>HT_A_PROGRESS </CODE>then this will get called
on all progress notifications.
<PRE>
extern BOOL HTAlertCall_add (HTList * list, HTAlertCallback * cbf,
			     HTAlertOpcode opcode);
</PRE>
<H3>
  Delete a Callback function
</H3>
<P>
Unregister a call back function from a list
<PRE>
extern BOOL HTAlertCall_delete (HTList * list, HTAlertCallback * cbf);
</PRE>
<H3>
  Delete all Callbacks With this Opcode
</H3>
<P>
Unregister all handlers registered for a given opcode.
<PRE>
extern BOOL HTAlertCall_deleteOpcode (HTList * list, HTAlertOpcode opcode);
</PRE>
<H3>
  Delete a list of Callback Functions
</H3>
<P>
Unregisters all call back functions
<PRE>
extern BOOL HTAlertCall_deleteAll (HTList * list);
</PRE>
<H3>
  Find a Callback Function
</H3>
<P>
Finds a callback function corresponding to the opcode. If none has been
registered then NULL is returned.
<PRE>
extern HTAlertCallback * HTAlertCall_find(HTList * list, HTAlertOpcode opcode);
</PRE>
<H2>
  <A NAME="Reply">The Reply Object</A>
</H2>
<P>
The reply object is used for communicating input from the <I>user</I> back
to the Library. This is only required to use when for example the user is
prompted for a file name etc. You can find several examples on how to use
this in the <A HREF="HTDialog.html">default message and dialog module</A>
provided together with the Library.
<PRE>extern HTAlertPar * HTAlert_newReply	(void);
extern void HTAlert_deleteReply		(HTAlertPar * old);
</PRE>
<H3>
  Handle the Reply Message
</H3>
<P>
These methods provide the API for handling the reply message. There are two
ways of assigning a message to the reply message - either by copying the
buffer or by reusing the same buffer. In the latter case, the caller must
make sure <B>not</B> to free the reply message before it has been used.
<PRE>
extern BOOL HTAlert_setReplyMessage	(HTAlertPar * me, const char *message);
extern BOOL HTAlert_assignReplyMessage	(HTAlertPar * me, char * message);
</PRE>
<P>
You can get the data back again by using this method:
<PRE>
extern char * HTAlert_replyMessage	(HTAlertPar * me);
</PRE>
<PRE>
extern char * HTAlert_replySecret	(HTAlertPar * me);
extern BOOL HTAlert_setReplySecret	(HTAlertPar * me, const char * secret);

extern void * HTAlert_replyOutput	(HTAlertPar * me);
extern BOOL HTAlert_setReplyOutput	(HTAlertPar * me, void * output);
</PRE>
<H2>
  <A NAME="active">Active set of Callback Functions</A>
</H2>
<P>
A list can be assigned as being active in which case it is <I>visible</I>
for libwww by assigning the list as the <I>global alert list</I>. Libwww
does not know about inactive lists of alert handlers.
<PRE>
extern void HTAlert_setGlobal	(HTList * list);
extern HTList * HTAlert_global	(void);
</PRE>
<H3>
  Global Alert List Methods
</H3>
<P>
You can assign a callback directly to the global list in which case it becomes
immediately available to libwww. In this case you do not need to worry about
creating the list - it will be created as well as deleted automatically.
<H4>
  Add an Alert Handler
</H4>
<PRE>
extern BOOL HTAlert_add	(HTAlertCallback * cbf, HTAlertOpcode opcode);
</PRE>
<H4>
  Delete an Alert Handler
</H4>
<P>
You can either delete a handler by referring to its address or to the opcode
that it has been registered for.
<PRE>
extern BOOL HTAlert_delete (HTAlertCallback * cbf);
extern BOOL HTAlert_deleteOpcode (HTAlertOpcode opcode);
</PRE>
<H4>
  Delete all Alert Handlers
</H4>
<PRE>
extern BOOL HTAlert_deleteAll (void);
</PRE>
<H4>
  Find an Alert Handler
</H4>
<PRE>
extern HTAlertCallback * HTAlert_find (HTAlertOpcode opcode);
</PRE>
<PRE>
#endif
</PRE>
<P>
  <HR>
<ADDRESS>
  @(#) $Id: HTAlert.html,v 2.56 1999/06/30 20:15:03 frystyk Exp $
</ADDRESS>
</BODY></HTML>
Webmaster