Implemented Generic select hook for ZOOM (bug #803). This is achieved with

[yaz-moved-to-github.git] / include / yaz / zoom.h

diff --git a/include/yaz/zoom.h b/include/yaz/zoom.h
index 7909b4d..1128239 100644 (file)
--- a/include/yaz/zoom.h
+++ b/include/yaz/zoom.h
@@ -24,7 +24,7 @@
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/* $Id: zoom.h,v 1.41 2007-01-03 08:42:14 adam Exp $ */
+/* $Id: zoom.h,v 1.42 2007-01-09 13:56:48 adam Exp $ */
 
 /**
  * \file zoom.h
@@ -339,17 +339,115 @@ ZOOM_options_get_int (ZOOM_options opt, const char *name, int defa);
 ZOOM_API(void)
 ZOOM_options_set_int(ZOOM_options opt, const char *name, int value);
 
-/* ----------------------------------------------------------- */
-/* events */
-/* poll for events on a number of connections. Returns positive
-   integer if event occurred ; zero if none occurred and no more
-   events are pending. The positive integer specifies the
-   connection for which the event occurred. */
+/** \brief select/poll socket mask: read */
+#define ZOOM_SELECT_READ 1
+/** \brief select/poll socket mask: write */
+#define ZOOM_SELECT_WRITE 2
+/** \brief select/poll socket mask: except */
+#define ZOOM_SELECT_EXCEPT 4
+
+/** \brief wait for events on connection(s) (BLOCKING)
+    \param no number of connections (size of cs)
+    \param cs connection array
+    \retval 0 no event was fired
+    \retval >0 event was fired for connection at (retval-1)
+    
+    blocking poll for events on a number of connections. Returns positive
+    integer if event occurred ; zero if none occurred and no more
+    events are pending. The positive integer specifies the
+    connection for which the event occurred.
+*/
 ZOOM_API(int)
 ZOOM_event (int no, ZOOM_connection *cs);
 
+
+/** \brief determines if connection is idle (no active or pending work)
+    \param c connection
+    \retval 1 is idle
+    \retval 0 is non-idle (active)
+*/
+ZOOM_API(int)
+ZOOM_connection_is_idle(ZOOM_connection c);
+
+
+/** \brief processes one event for one of connections given
+    \param no number of connections (size of cs)
+    \param cs connection array
+    \retval 0 no event was processed
+    \retval >0 event was processed for connection at (retval-1)
+
+    This function attemps to deal with outstandings events in 
+    a non-blocking fashion. If no events was processed (return value of 0),
+    then the system should attempt to deal with sockets in blocking mode
+    using socket select/poll which means calling the following functions:
+    ZOOM_connection_get_socket, ZOOM_connection_get_mask,
+    ZOOM_connection_get_timeout.
+*/
+ZOOM_API(int)
+    ZOOM_process_event(int no, ZOOM_connection *cs);
+
+
+/** \brief get socket fd for ZOOM connection
+    \param c connection
+    \retval -1 no socket assigned for connection
+    \retval >=0 socket for connection
+
+    Use this function when preparing for socket/poll and
+    in conjunction with ZOOM_connection_get_mask.
+*/
+ZOOM_API(int)
+    ZOOM_connection_get_socket(ZOOM_connection c);
+
+
+/** \brief get socket mask for connection 
+    \param c connection
+    \returns mask for connection (possibly 0)
+
+    Use this function when preparing for socket select/poll and
+    in conjunction with ZOOM_connection_get_socket.
+*/
 ZOOM_API(int)
-ZOOM_connection_is_idle(ZOOM_connection cs);
+    ZOOM_connection_get_mask(ZOOM_connection c);
+
+
+/** \brief set socket mask for connection (DO NOT call outside zoom) */
+ZOOM_API(int)
+    ZOOM_connection_set_mask(ZOOM_connection c, int mask);
+
+
+/** \brief get timeout in seconds for ZOOM connection
+    \param c connection
+    \returns timeout value in seconds
+
+    Use this function when preparing for socket/poll and
+    in conjunction with ZOOM_connection_get_socket.
+*/
+ZOOM_API(int)
+    ZOOM_connection_get_timeout(ZOOM_connection c);
+
+
+/** \brief fire socket event timeout
+    \param c connection
+    \retval 0 event was fired OK
+    \retval -1 event was not fired
+
+    Call this function when a timeout occurs - for example in the
+    case of select(2) returning 0.
+*/
+ZOOM_API(int)
+    ZOOM_connection_fire_event_timeout(ZOOM_connection c);
+
+
+/** \brief fire socket event activity (read,write,except)
+    \param c connection
+    \param mask or'ed mask of ZOOM_SELECT_.. values
+    \retval 0 event was fired OK
+    \retval -1 event was not fired
+*/
+ZOOM_API(int)
+    ZOOM_connection_fire_event_socket(ZOOM_connection c, int mask);
+
+
 
 ZOOM_END_CDECL
 /*