Ns_SockCallback

Overview

Syntax

    int Ns_SockCallback (
    SOCKET sock,
    Ns_SockProc *proc,
    void *ctx,
    int when
    );

Description

Ns_SockCallback registers a user-defined socket callback function and should be called by your module at startup time. You must create a listening TCP socket (named sock). The ctx argument is your context which will be passed back as the second argument of your callback function.

The when argument is a bitmask with one or more of the following options specified:

NS_SOCK_READ:	the socket is readable
NS_SOCK_WRITE:	the socket is writeable
NS_SOCK_EXCEPTION:	the socket has an exceptional condition
NS_SOCK_EXIT:	the server is shutting down

The proc is your socket callback function in the following format:

    typedef int (Ns_SockProc) (int sock, void *arg, int why);

The sock will be a readable, writable socket. The arg is the ctx you passed to Ns_SockCallback. The why argument is the when you passed to Ns_SockCallback.

At startup time, AOLserver creates a single socket service thread dedicated to handling socket callbacks. Since several sockets are needed to listen for connection requests, and because connection requests are handled so quickly, all the socket drivers share a single thread for that purpose.

Examples

1. Create a C callback function to handle a request. The callback function must execute without blocking so that other sockets can get serviced. Typically, the callback function just performs an accept() call and queues the request. The prototype is:

       typedef int (Ns_SockProc) (SOCKET sock, void *context, int 
   why);
   

   The parameters are:

   sock	the registered socket
   context	your context passed to Ns_SockCallback()
   why	the reason the function was called, which is one of the following: NS_SOCK_READ: the socket is readable NS_SOCK_WRITE: the socket is writeable NS_SOCK_EXCEPTION: the socket has an exceptional condition NS_SOCK_EXIT: the server is shutting down

   The callback function must return either NS_TRUE to tell the socket thread to keep watching the socket or NS_FALSE to tell the socket thread to stop watching the socket.

   For example:

       int
       MySock(SOCKET sock, void *context, int why)
       {
       	  if (why == NS_SOCK_READ) {
       		  .. handle read ..
       	  	if (error) {	
       		  	    return NS_FALSE;
       	  	} else {
       	      		return NS_TRUE;
       		  }
       	  } else if (why == NS_SOCK_EXIT) {
       		  .. free(context) ..
       		  return NS_FALSE;
       	  }
       }
   

2. At server startup time, your module must register your callback function with the server using the Ns_SockCallback() function.

   This example specifies that MySock will be called when the socket is readable or when the server is shutting down:

       Ns_SockCallback(sock, MySock, myCtx, 
       	NS_SOCK_READ | NS_SOCK_EXIT);
   

   Remember that there is only one socket service thread, so your callback function must return immediately without blocking!