Annotation of libwww/Library/src/HTEvtLst.html, revision 2.6
2.1 frystyk 1: <HTML>
2: <HEAD>
3: <!-- Changed by: Henrik Frystyk Nielsen, 16-May-1996 -->
2.4 frystyk 4: <TITLE>W3C Sample Code Library libwww Default Event Manager</TITLE>
2.1 frystyk 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
2.6 ! frystyk 38: is a part of the <A HREF="http://www.w3.org/Library/">W3C Sample Code
2.1 frystyk 39: Library</A>.
40: <PRE>
2.2 frystyk 41: #ifndef HTEVTLST_H
42: #define HTEVTLST_H
2.1 frystyk 43:
2.5 frystyk 44: #include "wwwsys.h"
2.1 frystyk 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 Registry</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>
74: extern HTEvent_registerCallback HTEventList_register;
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>
85: extern HTEvent_unregisterCallback HTEventList_unregister;
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>
97: <A NAME="dispatch">HTEventList_lookup/dispatch</A>
98: </H3>
99: <P>
100: Callbacks can be looked up or dispatched based on the socket and operation
101: (read/write/oob)
102: <PRE>
2.3 eric 103: extern int HTEventList_dispatch (SOCKET s, HTEventType type, ms_t now);
2.1 frystyk 104: extern HTEvent * HTEventList_lookup (SOCKET s, HTEventType type);
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: #if 0
118: typedef int HTEventTimeout (HTRequest *);
119:
120: extern BOOL HTEventList_registerTimeout (struct timeval *tp, HTRequest * request,
121: HTEventTimeout *tcbf, BOOL always);
122: #endif
123: </PRE>
124: <H2>
125: <A NAME="eventLoop">Event Loop</A>
126: </H2>
127: The libwww's default event loop dispatches events to the <A
128: HREF="#registry">event registry</A>.
129: <H3>
130: Start and Stop the Event Manager
131: </H3>
132: <PRE>
133: extern BOOL HTEventInit (void);
134: extern BOOL HTEventTerminate (void);
135: </PRE>
136: <H3>
137: Start the Event Loop
138: </H3>
139: <P>
140: That is, we wait for activity from one of our registered channels, and dispatch
141: on that. Under Windows/NT, we must treat the console and sockets as distinct.
142: That means we can't avoid a busy wait, but we do our best.
143: <PRE>
144: extern int HTEventList_loop (HTRequest * request);
145: </PRE>
146: <H3>
147: Stop the Event Loop
148: </H3>
149: <P>
150: Stops the (select based) event loop. The function does not guarantee that
151: all requests have terminated. This is for the app to do
152: <PRE>
153: extern void HTEventList_stopLoop (void);
154: </PRE>
155: <PRE>
156: #endif /* HTEVTLST_H */
157: </PRE>
158: <P>
159: <HR>
160: <ADDRESS>
2.6 ! frystyk 161: @(#) $Id: HTEvtLst.html,v 2.5 1998/05/04 19:36:30 frystyk Exp $
2.1 frystyk 162: </ADDRESS>
163: </BODY></HTML>
Webmaster