SocketBind()

SocketError SocketBind(
        Socket 		s,
        SocketPort 		p,
        SocketBindFlags 		flags);

Use the SocketBind() routine to associate a socket with a port number on this side of the connection.

For any given domain, normally only one socket on the machine may be bound to any port number. If you have used SocketBind() to bind some other socket to this port, then you may only bind another socket to the port by setting the SBF_REUSE_PORT in the flags argument. If you have used SocketBindInDomain() to bind some other socket to this port, then you may not use SocketBind() to bind another socket to the port.

A given socket may only be bound to one port.

This routine takes the following arguments:

s: The socket to bind.
p: The port to monitor.
flags: Set the SBF_REUSE_PORT to bind the socket to the port even if another socket is bound to it. (You may not use this flag with datagram sockets.)

If successful, the routine will return SE_NORMAL (i.e., zero). Otherwise, it will return some other SocketError value. Be on the lookout for SE_SOCKET_ALREADY_BOUND, SE_PORT_IN_USE, or SE_BIND_CONFLICT.

See Also: SocketBindInDomain().

Include: socket.goh

SocketBindInDomain()

SocketError SocketBindInDomain(
        Socket 		s,
        SocketPort 		p,
        SocketBindFlags 		flags,
        TCHAR 		*domain);

Use the SocketBindInDomain() routine to associate a socket with a port number and domain on this side of the connection.

For any given domain, normally only one socket on the machine may be bound to any port number in any given domain. If you have used SocketBindInDomain() to bind some other socket to this port and domain, then you may only bind another socket to the port and domain by setting the SBF_REUSE_PORT in the flags argument. If you have used SocketBind() to bind some other socket to this port, then you may not use SocketBindInDomain() to bind another socket to the port.

A given socket may only be bound to one port.

This routine takes the following arguments:

s: The socket to bind
p: The port to monitor
flags: Set the SBF_REUSE_PORT to bind the socket to the port even if another socket is bound to it.
domain: The domain to monitor

See Also: SocketBind().

Include: socket.goh

SocketCheckListen()

int SocketCheckListen(
        SocketPort 		p,
        TCHAR 		*domain,
        int 		bufsize);

Use the SocketCheckListen() command on a port to find out the domain for the first connect request on a listening socket--that is, the first connection request which has not yet been accepted. You might think of this as a limited form of "caller ID"--a chance to find out a bit about the incoming connection before you accept it. If SocketCheckListen() returns SE_PORT_NOT_LISTENING, it means that you have not passed it a port to which a socket is listening.

This routine takes the following arguments:

p: The port to check
domain: Buffer to hold the domain name
bufsize: The size of the domain buffer

It returns the length of the domain name. If the return value is zero, there was an error. Look out for SE_PORT_NOT_LISTENING, which signals that there is no socket bound to the port in question which is listening.

See Also: SocketBind(), SocketBindInDomain(), SocketListen().

Include: socket.goh

SocketCheckReady()

int SocketCheckReady(
        SocketCheckRequest 		*requests,
        int 		numRequests,
        int 		timeout);

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, you would 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 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:

SC_ACCEPT: If a socket is listening for a connection, this condition indicates that another socket is in fact 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 figured out that something has gone 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), then SocketCheckReady() will return SE_IMPROPER_CONDITION.

This routine takes the following arguments:

requests: The array of SocketCheckRequests structures, as described above.
numRequests: Number of elements in the requests array.
timeout: Time to wait for success, in 1/60 second ticks, or SOCKET_NO_TIMEOUT to try as long as possible.

The routine returns the index of the first SocketCheckRequest to meet its conditions.

Include: socket.goh