Annotation of libwww/Library/src/HTEvtLst.html, revision 2.1
2.1 ! frystyk 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 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>
! 103: extern int HTEventList_dispatch (SOCKET, HTEventType);
! 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>
! 161: @(#) $Id: HTEvtLst.html,v 1.1.2.4 1996/11/11 20:52:03 frystyk Exp $
! 162: </ADDRESS>
! 163: </BODY></HTML>
Webmaster