ICELIB0.NLM   →   ICE_SockServer()

ICE_SockServer

Description:

Sets up a listener threadgroup on a socket and spins up child threadgroups for each incomming connection.
 

Syntax for C:

int ICE_SockServer (
  unsigned int specialValue,
  unsigned int listenerIP <or char *listenerIP>,
  unsigned int listenerPort <or char *listenerPort>,
  void *childCounter,
  unsigned int timeout,
  unsigned int backlog,
  void *shutdownSignal,
  void *childThread,
  void *shutdownThread,
  int flags
);
 

Syntax for Assembly:

Call ICE_SockServer C, [specialValue], {offset} listenerIP, {offset} listenerPort, offset childCounter, [timeout], [backlog], offset shutdownSignal, offset childThread, offset shutdownThread, [flags]
 

Parameters:

specialValue

(IN) 32-bit value that will be passed to child thread
 

listenerIP

(IN) 32-bit IPv4 address to listen on (or 0.0.0.0 for all)
 

listenerPort

(IN) 32-bit port number to listen on
 

childCounter

(IN) 32-bit pointer to 32-bit value (default value should be 0).  Incremented before childThread is started.  The childThread is responsible for decrementing this value.  This value is provided for the developer's convenience, and is not used in any other way by ICE_SockServer(), except when the shutdownSignal is set to 1.
 

timeout

(IN) 32-bit timeout value, used by select() function for checking the contents of shutdownSignal.  Recommended value to be 10 or less.
 

backlog

(IN) 32-bit backlog value, representing number of pending connections which may remain queued -- same as that used by listen() function
 

shutdownSignal

(IN) 32-bit pointer to 32-bit signal value:
0 = Accept new connections (this must be the default)
-1 = Shutdown if childCounter = 0, but accept new conns.
-2 = Shutdown when childCounter = 0, reject new conns.
-3 = Shutdown immediately
 

childThread

(IN) 32-bit pointer to child thread to call.  See note 1 for details about the structure passed to this thread.
 

shutdownThread

(IN) 32-bit pointer to thread to call upon shutdown.  If NULL, then shutdownThread won't be called.  See note 2 for details about when this function may be called.
 

flags

(IN) Some rules to be enforced during the query.  All undocumented bit flags are considered reserved for future use, and should remain cleared (0) to ensure upward compatibility with newer versions of ICELIB0.NLM.  Currently supported flags are as follows:

1 = listenerIP is a 32-bit pointer to ASCIIZ string IP address

2 = listenerPort is a 32-bit pointer to ASCIIZ string port number
 

Returns:

32-bit value which will contain one of the following return codes (the threadgroup is active only if the return code is "0"):

0 = Successful
-1 = Not enough memory, malloc() failed
-2 = Failed to open socket
-3 = Failed to set socket mode
-4 = Failed to bind socket
-5 = Failed to listen on socket
 

Remarks:

Socket servers are cumbersome to write, and especially for servers that need to listen on multiple ports, a function such as ICE_SockServer() simplifies this process so the developer can be more productive.

Note 1

When the childThread is started, a single 32-bit parameter can be passed to it.  This 32-bit value is a pointer to memory containing the following structure, which is an array of 32-bit values:
          0: 32-bit specialValue
          1: 32-bit socket stream handle for this connection
          2: 32-bit pointer to copy of server socket structure data
          3: 32-bit listener's IP address
          4: 32-bit listener's port number
          5: 32-bit childCounter value (current number of child threads)

Prior to thread termination, the childThread code must:
          - Close the socket handle using the close() function
          - Free this memory using the free() function
 

Note 2 (not yet supported, may change later)

The listener may shut down for any number of different reasons, and when it is the following structure will be passed to it:
          0: 32-bit specialValue
          1: 32-bit socket stream handle for this connection
          2: 32-bit pointer to copy of server socket structure data
          3: 32-bit listener's IP address
          4: 32-bit listener's port number
          5: 32-bit childCounter value (current number of child threads)

Reasons for shutdown will be one of the following values:
          0 = Signalled shutdown was complete
          -1 = Not enough memory, malloc() failed
          -2 = Error waiting for timeout, select() failed
          -3 = Error accepting new connection on socket, accept() failed

Prior to thread termination, the shutdownThread code must:
          - Free this memory using the free() function

Once this thread is started, it indicates that the listener has been terminated.