Annotation of libwww/Library/src/HTEvent.html, revision 2.17
2.1 eric 1: <HTML>
2: <HEAD>
2.13 frystyk 3: <TITLE>W3C Sample Code Library libwww Event Class</TITLE>
2.1 eric 4: </HEAD>
5: <BODY>
2.4 frystyk 6: <H1>
7: The Event Class
2.3 frystyk 8: </H1>
2.1 eric 9: <PRE>
10: /*
11: ** (c) COPYRIGHT MIT 1995.
12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
2.4 frystyk 14: </PRE>
15: <P>
16: The Event Class defines any event manager to be used by libwww for handling
17: events. An <I>event</I> is not strictly defined as it is highly platform
18: dependent and hence out of scope for the Library. If you are using the libwww
19: pseudo threads on Unix then an event is when the <I>select()</I> system
20: call returns a notification on a socket descriptor, but it may as well
21: be an asynchronous event from the windows manager etc. If your application
22: is not using anything but traditional blocking sockets then you do not need
23: an event manager at all. In that case, libwww will block on any socket or
24: system call until the process can proceed.
25: <P>
26: The libwww interface to an event manager is very simple as it consists of
27: <B>registering</B> a <I>socket descriptor</I>, the <I>location</I> in the
28: program, and the <I>current state</I> when an operation (for example
29: <CODE>read</CODE>) would block. When the event manager at a later point in
30: time gets a notification that the socket has become ready, it can then call
31: libwww with the state saved from the registration and libwww can continue.
32: Second, libwww must be able to <B>unregister</B> a socket when it is not
33: anymore in a state where it can block. <I>Only</I> in case the application
34: wishes to use <I>non-blocking</I> sockets it should register methods for
35: handling the <B>registration</B> process as described below.
36: <P>
37: <B>Note</B>: The library <B>core</B> does <I>not</I> define any event manager
38: - it is considered part of the application. The library comes with a
2.17 ! frystyk 39: <A HREF="HTEvtLst.html">default event manager</A> which can be initiated
2.6 frystyk 40: using the function <CODE>HTEventInit()</CODE> in <A HREF="HTInit.html">HTInit
41: module</A>
2.4 frystyk 42: <P>
43: This module is implemented by <A HREF="HTEvent.c">HTEvent.c</A>, and it is
2.16 frystyk 44: a part of the <A HREF="http://www.w3.org/Library/">W3C Sample Code Library</A>.
2.4 frystyk 45: <PRE>
2.1 eric 46: #ifndef HTEVENT_H
47: #define HTEVENT_H
2.14 frystyk 48: #include "wwwsys.h"
2.11 eric 49: #ifdef IN_EVENT
50: typedef struct _HTTimer HTTimer;
51: #endif
2.2 frystyk 52:
53: typedef enum _HTPriority {
54: HT_PRIORITY_INV = -1,
55: HT_PRIORITY_OFF = 0,
56: HT_PRIORITY_MIN = 1,
57: HT_PRIORITY_MAX = 20
58: } HTPriority;
59:
2.10 eric 60: #define HTEVENT_INDEX 0x10
2.8 frystyk 61: typedef enum {
2.9 eric 62: #ifdef WWW_WIN_ASYNC
2.10 eric 63: HTEvent_READ = (0x001 | 0 << HTEVENT_INDEX),
64: HTEvent_WRITE = (0x002 | 1 << HTEVENT_INDEX),
65: HTEvent_OOB = (0x004 | 2 << HTEVENT_INDEX),
66: HTEvent_ACCEPT = (0x008 | 3 << HTEVENT_INDEX),
67: HTEvent_CONNECT = (0x010 | 4 << HTEVENT_INDEX),
68: HTEvent_CLOSE = (0x020 | 5 << HTEVENT_INDEX),
2.9 eric 69: HTEvent_TYPES = 6, /* winsock has seperate events for all of these */
2.10 eric 70: #define HTEVENT_TYPES 6 /* use in constructing the fake event below */
2.9 eric 71: #else /* WWW_WIN_ASYNC */
2.10 eric 72: HTEvent_READ = (0x001 | 0 << HTEVENT_INDEX),
73: HTEvent_ACCEPT = (0x002 | 0 << HTEVENT_INDEX),
74: HTEvent_CLOSE = (0x004 | 0 << HTEVENT_INDEX),
75: HTEvent_WRITE = (0x008 | 1 << HTEVENT_INDEX),
76: HTEvent_CONNECT = (0x010 | 1 << HTEVENT_INDEX),
77: HTEvent_OOB = (0x020 | 2 << HTEVENT_INDEX),
2.9 eric 78: HTEvent_TYPES = 3, /* only READ, WRITE, and OOB are real types */
2.10 eric 79: #define HTEVENT_TYPES 3 /* use in constructing the fake event below */
2.9 eric 80: #endif /* !WWW_WIN_ASYNC */
2.10 eric 81: /*
82: ** fake events - these don't correspond to event manager events, but they
83: ** are usefull for communicating with the protocol modules
84: */
85: HTEvent_TIMEOUT = (0x040 | HTEVENT_TYPES << HTEVENT_INDEX),
86: HTEvent_BEGIN = (0x000 | HTEVENT_TYPES << HTEVENT_INDEX),
87: HTEvent_END = (0x080 | HTEVENT_TYPES << HTEVENT_INDEX),
88: HTEvent_FLUSH = (0x100 | HTEVENT_TYPES << HTEVENT_INDEX),
89: HTEvent_RESET = (0x200 | HTEVENT_TYPES << HTEVENT_INDEX),
2.9 eric 90: HTEvent_ALL = 0xFFFF
2.8 frystyk 91: } HTEventType;
2.1 eric 92:
2.16 frystyk 93: #define HTEvent_BITS(type) (type & 0xFFFF)
94: #define HTEvent_INDEX(type) (type >> HTEVENT_INDEX)
2.8 frystyk 95:
2.11 eric 96: #define HT_EVENT_INITIALIZER \
97: {HTEvent_READ, "HTEvent_READ"}, \
98: {HTEvent_ACCEPT, "HTEvent_ACCEPT"}, \
99: {HTEvent_CLOSE, "HTEvent_CLOSE"}, \
100: {HTEvent_WRITE, "HTEvent_WRITE"}, \
101: {HTEvent_CONNECT, "HTEvent_CONNECT"}, \
102: {HTEvent_OOB, "HTEvent_OOB"}, \
103: {HTEvent_TIMEOUT, "HTEvent_TIMEOUT"}, \
104: {HTEvent_BEGIN, "HTEvent_BEGIN"}, \
105: {HTEvent_END, "HTEvent_END"}, \
106: {HTEvent_FLUSH, "HTEvent_FLUSH"}, \
107: {HTEvent_RESET, "HTEvent_RESET"}
108:
109: extern char * HTEvent_type2str(HTEventType type);
2.12 frystyk 110: </PRE>
2.3 frystyk 111: <H2>
2.7 eric 112: <A NAME="eventHandlers">Event Handlers</A>
2.3 frystyk 113: </H2>
114: <P>
2.4 frystyk 115: A <I>location</I> is a function that can be registered by the event manager
116: and called at a later point in time in order to continue an operation. All
117: locations must be of type <CODE>HTEventCallback</CODE> as defined here:
2.2 frystyk 118: <PRE>
2.8 frystyk 119: typedef int HTEventCallback (SOCKET, void *, HTEventType);
2.12 frystyk 120: typedef struct _HTEvent HTEvent;
121:
2.16 frystyk 122: /* Avoid circular include for HTReq->HTNet->HTHost: HTEvent blah */
2.12 frystyk 123: #include "HTReq.h"
2.2 frystyk 124: </PRE>
2.4 frystyk 125: <P>
126: There are many default event handlers provided with the Library. For example,
127: all the protocol modules such as the <A HREF="HTTP.html">HTTP client module</A>
128: are implemented as event handlers. In stead of using blocking sockets, this
129: allows a protocol module to register itself when performing an operation
130: that would block. When the sockets becomes ready the handler is called with
131: th socket in question, the request object, and the socket operation
2.3 frystyk 132: <H2>
2.17 ! frystyk 133: Registering and Unregistering Events
2.3 frystyk 134: </H2>
135: <P>
2.4 frystyk 136: As mentioned above, the only interface libwww requires from an event manager
2.17 ! frystyk 137: is a method to <I>register</I> an event when an operation would block and
! 138: <I>unregister</I> it when the operation has completed The library registers
! 139: and unregisters events by calling the following two functions:
2.8 frystyk 140: <PRE>
141: extern int HTEvent_register (SOCKET, HTEventType, HTEvent *);
142: extern int HTEvent_unregister (SOCKET, HTEventType);
2.4 frystyk 143: </PRE>
144: <P>
145: The register function contains information about which socket we are waiting
146: on to get ready and which operation we are waiting for (read, write, etc.),
147: the request object containing the current request, the event handler that
148: we want to be called when the socket becomes reasy, and finally the priority
149: by which we want the thread to be processed by the event manager. Likewise,
150: libwww can unregister a operation on a socket which means that libwww is
151: no longer waiting for this actiion to become ready.
152: <H2>
153: Registering an Event Manager
154: </H2>
155: <P>
2.17 ! frystyk 156: Libwww core does not contain any event manager as it depends on whether you
! 157: want to use pseudo threads no threads, or real threads. Instead, libwww comes
! 158: with a <A HREF="HTEvtLst.html">default implementation</A> that you may register,
! 159: but you may as well implement and register your own. The register and unregister
! 160: functions above actually does nothing than looking for a registered event
! 161: manager and then passes the call on to that. You register your own event
! 162: manager by using the methods below:
2.1 eric 163: <PRE>
2.8 frystyk 164: typedef int HTEvent_registerCallback(SOCKET, HTEventType, HTEvent *);
165: typedef int HTEvent_unregisterCallback(SOCKET, HTEventType);
2.1 eric 166:
167: extern void HTEvent_setRegisterCallback(HTEvent_registerCallback *);
168: extern void HTEvent_setUnregisterCallback(HTEvent_unregisterCallback *);
2.17 ! frystyk 169: </PRE>
! 170: <H3>
! 171: Has Register and Unregister Callbacks been setup?
! 172: </H3>
! 173: <P>
! 174: Replies YES if both an <TT>HTEvent_setRegisterCallback</TT> and
! 175: <TT>HTEvent_setUnregisterCallback</TT> have been called with non NULL callbacks.
! 176: <PRE>
! 177: extern BOOL HTEvent_isCallbacksRegistered(void);
! 178: </PRE>
! 179: <H2>
! 180: Create and Delete Events
! 181: </H2>
! 182: <PRE>
2.8 frystyk 183: extern HTEvent * HTEvent_new (HTEventCallback * cbf, void * context,
184: HTPriority pritority, int timeoutInMillis);
185: extern BOOL HTEvent_delete (HTEvent * event);
2.17 ! frystyk 186: </PRE>
! 187: <H3>
! 188: Event Timeouts, Priorities, Callbacks, and Contexts
! 189: </H3>
! 190: <P>
! 191: Normally, these are set when creating the event.
! 192: <PRE>
2.8 frystyk 193: extern BOOL HTEvent_setParam(HTEvent * event, void * param);
194: extern BOOL HTEvent_setPriority(HTEvent * event, HTPriority priority);
195: extern BOOL HTEvent_setTimeout(HTEvent * event, int timeoutInMillis);
2.17 ! frystyk 196: extern BOOL HTEvent_setCallback(HTEvent * event, HTEventCallback * cbf);
! 197: </PRE>
! 198: <H2>
! 199: The Raw Event Type
! 200: </H2>
! 201: <P>
! 202: Don't use this directly, use the methods above instead.
! 203: <PRE>
! 204: struct _HTEvent {
! 205: HTPriority priority; /* Priority of this request (event) */
! 206: int millis; /* Timeout in ms for this event */
! 207: #ifdef IN_EVENT
! 208: HTTimer * timer;
! 209: #endif
! 210: HTEventCallback * cbf; /* Protocol state machine */
! 211: void * param; /* HTEvent_register parameter */
! 212: HTRequest * request;
! 213: };
2.1 eric 214: </PRE>
2.3 frystyk 215: <P>
2.4 frystyk 216: You can register the event manager provided together with libwww by using
2.6 frystyk 217: the <CODE>HTEventInit()</CODE> in the <A HREF="HTInit.html">HTInit module</A>
2.1 eric 218: <PRE>
219: #endif /* HTEVENT_H */
220: </PRE>
2.3 frystyk 221: <P>
222: <HR>
2.1 eric 223: <ADDRESS>
2.17 ! frystyk 224: @(#) $Id: HTEvent.html,v 2.16 1998/05/26 21:21:10 frystyk Exp $
2.1 eric 225: </ADDRESS>
2.3 frystyk 226: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTEvent.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src