Annotation of libwww/Library/src/HTEvtLst.html, revision 1.1.2.3
1.1.2.1 eric 1: <HTML>
2: <HEAD>
3: <!-- Changed by: Henrik Frystyk Nielsen, 16-May-1996 -->
4: <TITLE>W3C Reference Library libwww Default Event Manager</TITLE>
5: </HEAD>
6: <BODY>
7: <H1>
8: Default Event Manager
9: </H1>
10: <PRE>
11: /*
12: ** (c) COPYRIGHT MIT 1995.
13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
16: <P>
17: This module provides an event registry and a multi-threaded event
18: loop. An application may use this module for:
19: <UL>
20: <LI>event loop and registry - Application registers <A
21: HREF="#registry">HTEvntrg_register and HTEvntrg_unregister</A> and
22: calls <A HREF="#eventLoop">HTEventList_loop</A> to dispatch events as
23: they occur.<P>
24:
25: <LI>event registry - Application just registers its own <A
26: HREF="HTEvent.html#eventHandlers">event handlers</A> and chains them
27: to <A HREF="#registry">HTEvntrg_register and
28: HTEvntrg_unregister</A>. When the application's event loop gets
29: activity on a socket, it calls <A
30: HREF="#dispatch">HTEvent_dispatch</A> to handle it.<P>
31:
32: <LI>nothing - Application registers its own <A
33: HREF="HTEvent.html#eventHandlers">event handler</A> uses its own event
34: loop to dispatch those events.<P>
35: </UL>
36:
37: This module is implemented by <A HREF="HTEvntrg.c">HTEvntrg.c</A>, and it
38: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C Reference
39: Library</A>.
40: <PRE>
41: #ifndef HTEVNTLST_H
42: #define HTEVNTLST_H
43:
44: #include "sysdep.h"
45: #include "HTEvent.h"
46: #include "HTReq.h"
47: </PRE>
48: <H3>
49: Windows Specific Handles
50: </H3>
51: <PRE>
52: #if defined(WWW_WIN_ASYNC) || defined(WWW_WIN_DLL)
53: extern BOOL HTEventList_winHandle (HTRequest * request);
54: extern BOOL HTEventList_setWinHandle (HWND window, unsigned long message);
55: extern HWND HTEventList_getWinHandle (unsigned long * pMessage);
56: extern LRESULT CALLBACK AsyncWindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam);
57: #endif
58: </PRE>
59: <H2>
60: <A NAME="registry">Event Reagistry</A>
61: </H2>
62: The libwww's event registry binds a socket and operation (FD_READ,
63: FD_WRITE...) to a callback function. Event are registered,
64: unregistered, and dispatched.
65: <H3>
66: Register an Event Handler
67: </H3>
68: <P>
69: For a given socket, reqister a request structure, a set of operations, a
70: HTEventCallback function, and a priority. For this implementation, we allow
71: only a single HTEventCallback function for all operations. and the priority
72: field is ignored.
73: <PRE>
1.1.2.2 eric 74: extern int HTEventList_register (SOCKET, HTEventType, HTEvent *);
1.1.2.1 eric 75: </PRE>
76: <H3>
77: Unregister an Event Handler
78: </H3>
79: <P>
80: Remove the registered information for the specified socket for the actions
81: specified in ops. if no actions remain after the unregister, the registered
82: info is deleted, and, if the socket has been registered for notification,
83: the HTEventCallback will be invoked.
84: <PRE>
1.1.2.2 eric 85: extern int HTEventList_unregister (SOCKET, HTEventType);
1.1.2.1 eric 86: </PRE>
87: <H3>
88: Unregister ALL Event Handlers
89: </H3>
90: <P>
91: Unregister all sockets. N.B. we just remove them for our internal data
92: structures: it is up to the application to actually close the socket.
93: <PRE>
94: extern int HTEventList_unregisterAll (void);
95: </PRE>
96: <H3>
1.1.2.3 ! eric 97: <A NAME="dispatch">HTEventList_lookup/dispatch</A>
1.1.2.1 eric 98: </H3>
99: <P>
1.1.2.3 ! eric 100: Callbacks can be looked up or dispatched based on the socket and operation
! 101: (read/write/oob)
1.1.2.1 eric 102: <PRE>
1.1.2.3 ! eric 103: extern int HTEventList_dispatch (SOCKET, HTEventType);
! 104: extern HTEvent * HTEventList_lookup (SOCKET s, HTEventType type);
1.1.2.1 eric 105: </PRE>
106: <H2>
107: Handler for Timeout on Sockets
108: </H2>
109: <P>
110: This function sets the timeout for sockets in the <CODE>select()</CODE> call
111: and registers a timeout function that is called if select times out. This
112: does only works on NON windows platforms as we need to poll for the console
113: on windows If <CODE>tv = NULL</CODE> then timeout is disabled. Default is
114: no timeout. If <EM>always=YES</EM> then the callback is called at all times,
115: if NO then only when Library sockets are active. Returns YES if OK else NO.
116: <PRE>
117: typedef int HTEventTimeout (HTRequest *);
118:
119: extern BOOL HTEventList_registerTimeout (struct timeval *tp, HTRequest * request,
120: HTEventTimeout *tcbf, BOOL always);
121: </PRE>
122: <H2>
123: <A NAME="eventLoop">Event Loop</A>
124: </H2>
125: The libwww's default event loop dispatches events to the <A
126: HREF="#registry">event registry</A>.
127: <H3>
128: Start and Stop the Event Manager
129: </H3>
130: <PRE>
131: extern BOOL HTEventInit (void);
132: extern BOOL HTEventTerminate (void);
133: </PRE>
134: <H3>
135: Start the Event Loop
136: </H3>
137: <P>
138: That is, we wait for activity from one of our registered channels, and dispatch
139: on that. Under Windows/NT, we must treat the console and sockets as distinct.
140: That means we can't avoid a busy wait, but we do our best.
141: <PRE>
142: extern int HTEventList_loop (HTRequest * request);
143: </PRE>
144: <H3>
145: Stop the Event Loop
146: </H3>
147: <P>
148: Stops the (select based) event loop. The function does not guarantee that
149: all requests have terminated. This is for the app to do
150: <PRE>
151: extern void HTEventList_stopLoop (void);
152: </PRE>
153: <PRE>
154: #endif /* HTEVTLST_H */
155: </PRE>
156: <P>
157: <HR>
158: <ADDRESS>
1.1.2.3 ! eric 159: @(#) $Id: HTEvtLst.html,v 1.1.2.2 1996/11/02 19:26:29 eric Exp $
1.1.2.1 eric 160: </ADDRESS>
161: </BODY></HTML>
Webmaster