Annotation of libwww/Library/src/HTEvtLst.html, revision 2.7
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>
2.7 ! frystyk 17: This module provides a default event registry and an eventloop which may
! 18: be used by an application if desired. See also the libwww timers defined
! 19: in the <A HREF="HTTimer.html">HTTimer module</A>. An application may use
! 20: this module for:
2.1 frystyk 21: <UL>
2.7 ! frystyk 22: <LI>
! 23: <STRONG>Eventloop and registry</STRONG> - Application registers
! 24: <A HREF="#registry">HTEvntrg_register and HTEvntrg_unregister</A> and calls
! 25: <A HREF="#eventLoop">HTEventList_loop</A> to dispatch events as they occur.
! 26: <LI>
! 27: <STRONG>Event registry</STRONG> - Application just registers its own
! 28: <A HREF="HTEvent.html#eventHandlers">event handlers</A> and chains them to
! 29: <A HREF="#registry">HTEvntrg_register and HTEvntrg_unregister</A>. When the
! 30: application's eventloop gets activity on a socket, it calls
! 31: <A HREF="#dispatch">HTEvent_dispatch</A> to handle it.
! 32: <LI>
! 33: <STRONG>Nothing</STRONG> - Application registers its own
! 34: <A HREF="HTEvent.html#eventHandlers">event handler</A> uses its own eventloop
! 35: to dispatch those events.
2.1 frystyk 36: </UL>
2.7 ! frystyk 37: <P>
! 38: This module is implemented by <A HREF="HTEvtLst.c">HTEvtLst.c</A>, and it
2.6 frystyk 39: is a part of the <A HREF="http://www.w3.org/Library/">W3C Sample Code
2.1 frystyk 40: Library</A>.
41: <PRE>
2.2 frystyk 42: #ifndef HTEVTLST_H
43: #define HTEVTLST_H
2.1 frystyk 44:
2.5 frystyk 45: #include "wwwsys.h"
2.1 frystyk 46: #include "HTEvent.h"
47: #include "HTReq.h"
48: </PRE>
49: <H3>
50: Windows Specific Handles
51: </H3>
52: <PRE>
53: #if defined(WWW_WIN_ASYNC) || defined(WWW_WIN_DLL)
54: extern BOOL HTEventList_winHandle (HTRequest * request);
55: extern BOOL HTEventList_setWinHandle (HWND window, unsigned long message);
56: extern HWND HTEventList_getWinHandle (unsigned long * pMessage);
57: extern LRESULT CALLBACK AsyncWindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam);
58: #endif
59: </PRE>
60: <H2>
61: <A NAME="registry">Event Registry</A>
62: </H2>
2.7 ! frystyk 63: <P>
! 64: The libwww event registry binds a socket and operation (<TT>FD_READ</TT>,
! 65: <TT>FD_WRITE</TT>, ...) to a callback function. Events are registered,
! 66: unregistered, and dispatched as they come in.
2.1 frystyk 67: <H3>
68: Register an Event Handler
69: </H3>
70: <P>
71: For a given socket, reqister a request structure, a set of operations, a
72: HTEventCallback function, and a priority. For this implementation, we allow
73: only a single HTEventCallback function for all operations. and the priority
74: field is ignored.
75: <PRE>
76: extern HTEvent_registerCallback HTEventList_register;
77: </PRE>
78: <H3>
79: Unregister an Event Handler
80: </H3>
81: <P>
82: Remove the registered information for the specified socket for the actions
83: specified in ops. if no actions remain after the unregister, the registered
84: info is deleted, and, if the socket has been registered for notification,
85: the HTEventCallback will be invoked.
86: <PRE>
87: extern HTEvent_unregisterCallback HTEventList_unregister;
88: </PRE>
89: <H3>
90: Unregister ALL Event Handlers
91: </H3>
92: <P>
93: Unregister all sockets. N.B. we just remove them for our internal data
94: structures: it is up to the application to actually close the socket.
95: <PRE>
96: extern int HTEventList_unregisterAll (void);
97: </PRE>
98: <H3>
2.7 ! frystyk 99: <A NAME="dispatch">Lookup and Dispatch Event Handlers</A>
2.1 frystyk 100: </H3>
101: <P>
2.7 ! frystyk 102: Callbacks can be looked up or dispatched based on the socket and operation
2.1 frystyk 103: (read/write/oob)
104: <PRE>
2.3 eric 105: extern int HTEventList_dispatch (SOCKET s, HTEventType type, ms_t now);
2.1 frystyk 106: extern HTEvent * HTEventList_lookup (SOCKET s, HTEventType type);
107: </PRE>
108: <H2>
2.7 ! frystyk 109: <A NAME="eventLoop">Libwww Default EventLoop</A>
2.1 frystyk 110: </H2>
111: <P>
2.7 ! frystyk 112: The libwww default eventloop dispatches events to the <A HREF="#registry">event
! 113: registry</A>.
2.1 frystyk 114: <H3>
115: Start and Stop the Event Manager
116: </H3>
117: <PRE>
118: extern BOOL HTEventInit (void);
119: extern BOOL HTEventTerminate (void);
120: </PRE>
121: <H3>
2.7 ! frystyk 122: Start the Eventloop
2.1 frystyk 123: </H3>
124: <P>
125: That is, we wait for activity from one of our registered channels, and dispatch
126: on that. Under Windows/NT, we must treat the console and sockets as distinct.
127: That means we can't avoid a busy wait, but we do our best.
128: <PRE>
2.7 ! frystyk 129: extern int HTEventList_newLoop (void);
! 130: </PRE>
! 131: <P>
! 132: The next version is an old version of the eventloop start. The request is
! 133: not used for anything and can be NULL.
! 134: <PRE>
2.1 frystyk 135: extern int HTEventList_loop (HTRequest * request);
136: </PRE>
137: <H3>
2.7 ! frystyk 138: Stop the Eventloop
2.1 frystyk 139: </H3>
140: <P>
2.7 ! frystyk 141: Stops the (select based) eventloop immediately. The function does not guarantee
! 142: that all requests have terminated so it is important that the application
! 143: does this before this function is called. This can be done using the
! 144: <TT>HTNet_isIdle()</TT> function in the <A HREF="HTNet.html">HTNet Module</A>
2.1 frystyk 145: <PRE>
146: extern void HTEventList_stopLoop (void);
147: </PRE>
148: <PRE>
149: #endif /* HTEVTLST_H */
150: </PRE>
151: <P>
152: <HR>
153: <ADDRESS>
2.7 ! frystyk 154: @(#) $Id: HTEvtLst.html,v 2.6 1998/05/14 02:10:26 frystyk Exp $
2.1 frystyk 155: </ADDRESS>
156: </BODY></HTML>
Webmaster