Socket: 9 Checking the Connection

SocketCheckListen(), SocketCheckReady()

The Socket library provides utility routines that query the status of a connection. This can be helpful when figuring out why a connection may not be working or confirming that a connection is working.

Use SocketCheckListen() on a port to find out the domain and medium for the first connection request on the port; that is, the first connection request which has not yet been accepted. Think of this as a limited form of "caller ID" -- a chance to find out about the incoming connection before accepting it. If SocketCheckListen() returns SE_PORT_NOT_LISTENING, it means there is no socket that is bound to the port and listening.

To "peek" at the next packet of incoming data, call SocketRecv() and pass the SRF_PEEK flag. This allows you to get the size of the next packet of incoming data and to look at its contents without destroying it.

To check one or more sockets to see if they have received data, received connection requests, or are ready to write, call SocketCheckReady() . It can check connections for incoming data or just incoming urgent data.

For programs which need to poll many sockets, SocketCheckReady() provides a tidy means to do this without spawning a thread for each socket.

The SocketCheckReady() routine takes an array of SocketCheckRequest structures. Each one of these structures contains a socket and a condition. SocketCheckReady() looks at each SocketCheckRequest structure in the array and returns the index of the first structure whose socket meets the condition.

Thus, to determine if a given socket is properly set up so that you can send data through it, pass SocketCheckReady() a one-element array (represented in pseudo-code):

{ mySocket, SC_WRITE, 0 }

To check several sockets to see whether any of them had received any connection requests, pass to SocketCheckReady() an array of the form (represented in pseudo-code):

{ socket1, SC_ACCEPT, 0 },
{ socket2, SC_ACCEPT, 0 },
{ socket3, SC_ACCEPT, 0 }

For any socket, you may check for one or more of the following conditions, as represented by SocketCondition values:

SC_ACCEPT: If a socket is listening for a connection, this condition indicates that another socket is trying to connect to the listening socket.
SC_READ: If a socket is connected, this condition indicates that a packet of data has come in and is ready to be read.
SC_EXCEPTION: If a socket is connected, this condition indicates that the socket has discovered something wrong with its connection.
SC_URGENT: If a socket is connected, this condition indicates that it has received a packet of data that was marked urgent.
SC_WRITE: This condition indicates that data may be sent through the socket.

If you query a socket about a condition that does not apply to its current state ( e.g. , ask a non-listening socket if it is ready to accept connections), then SocketCheckReady() returns SE_IMPROPER_CONDITION.

GEOS SDK TechDocs|

8 Closing the Connection | Next:

10 Domain-Specific Information