Annotation of libwww/Library/src/HTEvent.html, revision 2.7.2.7
2.1 eric 1: <HTML>
2: <HEAD>
2.4 frystyk 3: <TITLE>W3C Reference 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
39: <A HREF="HTEvntrg.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
44: a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C Reference
45: Library</A>.
46: <PRE>
2.1 eric 47: #ifndef HTEVENT_H
48: #define HTEVENT_H
2.2 frystyk 49: #include "sysdep.h"
50:
2.7.2.4 eric 51: #if 0
2.4 frystyk 52: #define FD_NONE 0
53: #define FD_ALL (FD_READ | FD_WRITE | FD_OOB | FD_ACCEPT | FD_CONNECT |FD_CLOSE)
54: #define FD_UNREGISTER (((FD_ALL) << 1) & (~(FD_ALL)))
2.7.2.4 eric 55: #endif
2.4 frystyk 56:
2.2 frystyk 57: typedef enum _HTPriority {
58: HT_PRIORITY_INV = -1,
59: HT_PRIORITY_OFF = 0,
60: HT_PRIORITY_MIN = 1,
61: HT_PRIORITY_MAX = 20
62: } HTPriority;
63:
2.7.2.1 eric 64: typedef enum {
2.7.2.5 frystyk 65: HTEvent_READ = (0x001 | 0 << 16),
66: HTEvent_ACCEPT = (0x002 | 0 << 16),
67: HTEvent_CLOSE = (0x004 | 0 << 16),
68: HTEvent_WRITE = (0x008 | 1 << 16),
69: HTEvent_CONNECT = (0x010 | 1 << 16),
70: HTEvent_OOB = (0x020 | 2 << 16),
2.7.2.6 eric 71: HTEvent_TIMEOUT = (0x040 | 3 << 16),
2.7.2.5 frystyk 72: HTEvent_BEGIN = (0x000 | 3 << 16),
73: HTEvent_END = (0x080 | 3 << 16),
2.7.2.6 eric 74: HTEvent_FLUSH = (0x100 | 3 << 16),
2.7.2.7 ! eric 75: HTEvent_RESET = (0x200 | 3 << 16),
2.7.2.5 frystyk 76: HTEvent_ALL = 0xFFFF,
2.7.2.6 eric 77: HTEvent_TYPES = 3 /* only READ, WRITE, and OOB are real types */
2.7.2.3 frystyk 78: } HTEventType;
79:
2.7.2.5 frystyk 80: #define HTEvent_BITS(type) (type & 0xFFFF)
81: #define HTEvent_INDEX(type) (type >> 16)
2.1 eric 82:
2.7.2.1 eric 83: /* Avoid circular include for HTReq->HTNet->HTHost: HTEvent blah */
84: typedef struct _HTEvent HTEvent;
2.1 eric 85: #include "HTReq.h"
86: </PRE>
2.3 frystyk 87: <H2>
2.7 eric 88: <A NAME="eventHandlers">Event Handlers</A>
2.3 frystyk 89: </H2>
90: <P>
2.4 frystyk 91: A <I>location</I> is a function that can be registered by the event manager
92: and called at a later point in time in order to continue an operation. All
93: locations must be of type <CODE>HTEventCallback</CODE> as defined here:
2.2 frystyk 94: <PRE>
2.7.2.2 eric 95: typedef int HTEventCallback (SOCKET, void *, HTEventType);
2.2 frystyk 96: </PRE>
2.4 frystyk 97: <P>
98: There are many default event handlers provided with the Library. For example,
99: all the protocol modules such as the <A HREF="HTTP.html">HTTP client module</A>
100: are implemented as event handlers. In stead of using blocking sockets, this
101: allows a protocol module to register itself when performing an operation
102: that would block. When the sockets becomes ready the handler is called with
103: th socket in question, the request object, and the socket operation
2.3 frystyk 104: <H2>
2.4 frystyk 105: Registering and Unregistering Event Handlers
2.3 frystyk 106: </H2>
107: <P>
2.4 frystyk 108: As mentioned above, the only interface libwww requires from an event manager
109: is a method to <I>register</I> an event handler when an operation would block
110: and <I>unregister</I> it when the operation has completed The library registers
111: and unregisters event handlers by calling the following two functions:
2.7.2.1 eric 112: <PRE>
2.7.2.2 eric 113: extern int HTEvent_register (SOCKET, HTEventType, HTEvent *);
114: extern int HTEvent_unregister (SOCKET, HTEventType);
2.4 frystyk 115: </PRE>
116: <P>
117: The register function contains information about which socket we are waiting
118: on to get ready and which operation we are waiting for (read, write, etc.),
119: the request object containing the current request, the event handler that
120: we want to be called when the socket becomes reasy, and finally the priority
121: by which we want the thread to be processed by the event manager. Likewise,
122: libwww can unregister a operation on a socket which means that libwww is
123: no longer waiting for this actiion to become ready.
124: <H2>
125: Registering an Event Manager
126: </H2>
127: <P>
128: The Library core does not contain any event manager as it depends on whether
129: you want to use pseudo threads no threads, or real threads. Instead, libwww
130: comes with a <A HREF="HTEvntrg.html">default implementation</A> that you
131: may register, but you may as well implement and register your own. The register
132: and unregister functions above actually does nothing than looking for a
133: registered event manager and then passes the call on to that. You register
134: your own event manager by using the methods below:
2.1 eric 135: <PRE>
2.7.2.5 frystyk 136: struct _HTEvent {
137: HTPriority priority; /* Priority of this request (event) */
138: int millis; /* Timeout in ms for this event */
139: HTEventCallback * cbf; /* Protocol state machine */
140: void * param; /* HTEvent_register parameter */
141: HTRequest * request;
142: };
143:
2.7.2.2 eric 144: typedef int HTEvent_registerCallback(SOCKET, HTEventType, HTEvent *);
145: typedef int HTEvent_unregisterCallback(SOCKET, HTEventType);
2.1 eric 146:
147: extern void HTEvent_setRegisterCallback(HTEvent_registerCallback *);
148: extern void HTEvent_setUnregisterCallback(HTEvent_unregisterCallback *);
2.7.2.1 eric 149: extern BOOL HTEvent_setCallback(HTEvent * event, HTEventCallback * cbf);
2.7.2.5 frystyk 150:
151: extern HTEvent * HTEvent_new (HTEventCallback * cbf, void * context,
152: HTPriority pritority, int timeoutInMillis);
153: extern BOOL HTEvent_delete (HTEvent * event);
154:
2.7.2.1 eric 155: extern BOOL HTEvent_setParam(HTEvent * event, void * param);
156: extern BOOL HTEvent_setPriority(HTEvent * event, HTPriority priority);
2.7.2.5 frystyk 157: extern BOOL HTEvent_setTimeout(HTEvent * event, int timeoutInMillis);
2.1 eric 158: </PRE>
2.3 frystyk 159: <P>
2.4 frystyk 160: You can register the event manager provided together with libwww by using
2.6 frystyk 161: the <CODE>HTEventInit()</CODE> in the <A HREF="HTInit.html">HTInit module</A>
2.1 eric 162: <PRE>
163: #endif /* HTEVENT_H */
164: </PRE>
2.3 frystyk 165: <P>
166: <HR>
2.1 eric 167: <ADDRESS>
2.7.2.7 ! eric 168: @(#) $Id: HTEvent.html,v 2.7.2.6 1996/11/18 05:00:51 eric Exp $
2.1 eric 169: </ADDRESS>
2.3 frystyk 170: </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