As the IP networking functions (with a few exceptions) are exact clones of identically-named WinSock functions, many references and tutorials are available on their use. Perhaps the best function reference for WinSock is online at http://www.sockets.com/winsock.htm.
Also, as WinSock is based on the BSD socket design, almost all UNIX systems have man pages describing these functions and their behavior. However, as this library is based on WinSock, there may be minor differences in operation between the UNIX descriptions and the operation of these functions.
The functions not reflected in WinSock or BSD sockets are InitSocket(), ExitSocket(), Socket_SetCallback(), and Socket_AddCallback(). InitSocket() and ExitSocket() function similarly to the initialization and shutdown functions in other modules of PModeLib. Socket_AddCallback() is essentially a mapping of WinSock's WSAAsyncSelect() function into the DOS assembly environment.
STRUC SOCKADDR .Port resw 1 ; Port number .Address resd 1 ; 32-bit IP address ENDSTRUC
STRUC HOSTENT
.Name resd 1 ; Pointer to official name of host
; (0-terminated string)
.Aliases resd 1 ; Pointer to 0-terminated array of pointers to
; 0-terminated alias name strings
.AddrList resd 1 ; Pointer to 0-terminated array of pointers to
; 32-bit IP addresses
ENDSTRUC
The "any" address (0.0.0.0). Use this address when it doesn't matter what address a socket has.
The "loopback" address (127.0.0.1). Also called "localhost", this address refers to the local machine.
The "broadcast" address (255.255.255.255). This address refers to all reachable hosts on the local network.
A stream (TCP/IP) socket.
A datagram (UDP/IP) socket.
Socket is ready for reading.
Socket is ready for writing.
Socket received out-of-band data.
Socket is ready to accept a new incoming connection.
Socket completed connection process.
Socket closed (possibly by remote end).
TCP protocol/layer.
Specifies Sockets layer for Socket_getsockopt() and Socket_setsockopt() (not really a protocol).
Socket options may be set using the Socket_getsockopt() and Socket_setsockopt() functions. Some options may be read-only in some cases (e.g. changes may be ignored or have no effect when trying to set them with Socket_setsockopt()).
Boolean indicating if the socket is in the listen state. False (0) unless a Socket_listen() has been performed.
Boolean indicating if the socket is configured for the transmission of broadcast messages. Defaults to false (0).
Read-only boolean indicating if debugging is enabled for the socket. Defaults to false (0).
Boolean indicating if the SOCKOPT_LINGER option is disabled. Defaults to true (1).
Read-only boolean indicating if routing is disabled for the socket. Defaults to false (0).
Integer error status for the socket. When read, cleared to 0. Default value is 0.
Boolean indicating if keepalives are being sent for the socket. Defaults to false (0).
The current linger options. Not available in current implementation.
Boolean indicating if out-of-band data is being received in the normal data stream. Defaults to false (0).
Read-only integer buffer size for receives on the socket.
Boolean indicating if the address to which the socket is bound can be used by other sockets. Defaults to false (0).
Read-only integer buffer size for sends on the socket.
Integer indicating the type of the socket (e.g. SOCK_STREAM). Defaults to the type specified when the socket was created (via Socket_create()).
Boolean indicating if the Nagle algorithm for send coalescing is disabled.
Shuts down socket driver.
None
None
Assumes InitSocket() has been called.
Sets the callback function used for socket event notification.
HandlerAddress, address of the callback procedure.
Returns 1 on error, 0 on success.
Callback procedure should use the C calling convention, compatible with the following C declaration:
Socket is the socket that triggered the event(s).
Event is the bitmask of the event(s) triggering the callback. The bitmask is an OR'ed combination of SOCKEVENT_ constants, listed in Section A.12.2.3.
Requests event notification for a socket.
Socket, the socket to enable notification events for.
EventMask, bitmask designating which events to call the callback for. This should be an OR'ed combination of SOCKEVENT_ constants, listed in Section A.12.2.3.
Returns 1 on error, 0 on success.
Assumes Socket_SetCallback() has been called to set a socket callback handler.
If called more than once for a particular socket, only the last call's EventMask is active. To disable callbacks for a particular socket, call with EventMask=0.
Accepts a connection on a socket.
Socket, a socket which is listening for connections after a Socket_listen().
Name, an optional (may be 0) pointer to a SOCKADDR structure which receives the network address of the connecting entity.
Returns -1 on error, otherwise returns the socket for the accepted connection and fills the SOCKADDR structure pointed to by Name (if Name is not 0).
Associates a local address with a socket.
Socket, an unbound socket.
Name, a pointer to a SOCKADDR structure containing the network address to assign to the socket.
Returns 1 on error, 0 on success.
Establishes a connection to a peer.
Socket, an unconnected socket.
Name, a pointer to a SOCKADDR structure containing the network address of the peer to which the socket is to be connected.
Returns 1 on error, 0 on success.
Creates a socket.
Type, the type of socket to create, must be one of the types listed in Section A.12.2.2.
Returns -1 on error, or the created socket on success.
Gets the address of the peer to which a socket is connected.
Socket, a connected socket.
Name, a pointer to a SOCKADDR structure which will receive the network address of the remote peer.
Returns 1 on error, otherwise returns 0 and fills the SOCKADDR structure pointed to by Name.
Retrieves a socket option.
Socket, a socket.
Level, the level at which the option is defined. Supported levels are SOL_SOCKET (socket level) and IPPROTO_TCP (TCP level).
OptName, the option for which the value is to be retrieved. See Section A.12.2.5 for a complete list of options.
OptVal, the buffer in which the value for the requested option is to be returned.
OptLen, (pointer to) the size of the buffer pointed to by OptVal.
Returns 1 on error, otherwise returns 0 and fills the buffer pointed to by OptVal.
Converts a string containing a dotted address into a 32-bit address.
DottedAddress, pointer to 0-terminated string representing a number expressed in the Internet standard "." notation.
Returns the Internet address corresponding to DottedAddress in network byte order, or 0 if DottedAddress is invalid.
Converts a 32-bit network address into a string in dotted decimal format.
Address, Internet address, in network byte order, to convert.
Returns pointer to a 0-terminated static string containing the address in standard "." notation. This buffer is overwritten on subsequent calls to this function.
Enables a socket to listen for incoming connections.
Socket, a bound (using Socket_bind()), unconnected socket.
BackLog, the maximum length to which the queue of pending connections may grow.
Returns 1 on error, 0 on success.
BackLog is silently limited to between 1 and 5, inclusive.
Receives data from a connected socket.
Socket, a connected socket.
Buffer, the starting address of the buffer to be filled with the incoming data.
MaxLen, the maximum number of bytes to receive.
Flags, bitmask specifying special operation for the function:
Bit 0 = PEEK: peek at the incoming data. The data is copied into the buffer but is not removed from the input queue.
Bit 1 = OOB: get out-of-band data instead of normal data.
Returns the number of bytes received, or 0 if the connection has been closed, or -1 on error.
Receives a datagram and stores its source address.
Socket, a bound socket.
Buffer, the starting address of the buffer to be filled with the incoming data.
MaxLen, the maximum number of bytes to receive.
Flags, bitmask specifying special operation for the function:
Bit 0 = PEEK: peek at the incoming data. The data is copied into the buffer but is not removed from the input queue.
Bit 1 = OOB: get out-of-band data instead of normal data.
From, an optional (may be 0) pointer to the SOCKADDR structure which is to receive the network address of the source.
Returns -1 on error, otherwise returns the number of bytes received and fills the SOCKADDR structure pointed to by From (if From is not 0).
Transmits data on a connected socket.
Socket, a connected socket.
Buffer, the starting address of the buffer containing the data to be transmitted.
Len, the maximum number of bytes to transmit.
Flags, bitmask specifying special operation for the function:
Bit 0 = OOB: send out-of-band data. This is only valid for stream (TCP) sockets.
Returns the number of bytes actually transmitted, or -1 on error.
Sends a datagram to a specific destination address.
Socket, a socket.
Buffer, the starting address of the buffer containing the data to be transmitted.
Len, the maximum number of bytes to transmit.
Flags, bitmask specifying special operation for the function:
Bit 0 = OOB: send out-of-band data. This is only valid for stream (TCP) sockets.
To, a pointer to a SOCKADDR structure which contains the network address of the destination.
Returns the number of bytes actually transmitted, or -1 on error.
Sets a socket option.
Socket, a socket.
Level, the level at which the option is defined. Supported levels are SOL_SOCKET (socket level) and IPPROTO_TCP (TCP level).
OptName, the option for which the value is to be set. See Section A.12.2.5 for a complete list of options.
OptVal, the buffer in which the value for the requested option is supplied.
OptLen, the size of the buffer pointed to by OptVal.
Returns 1 on error, otherwise returns 0.
Disables sends and/or receives on a socket.
Socket, a socket.
Flags, a bitmask specifying what to disable:
Bit 0 = subsequent receives on the socket will be disallowed.
Bit 1 = subsequent sends on the socket will be disallowed. A FIN is sent for TCP stream sockets.
Returns 1 on error, 0 on success.
Flags=0 has no effect. Flags=3 (both bits set) disables both sends and receives; however, the socket will not be closed and resources used by the socket will not be freed until Socket_close() is called.
Gets host information corresponding to an address.
Address, the network address to retrieve information about, in network byte order.
Returns a pointer to a static HOSTENT structure, or 0 on error. This buffer is overwritten on subsequent calls to this function.
Gets host information corresponding to a hostname.
Name, pointer to a 0-terminated string containing the name of the host.
Returns a pointer to a static HOSTENT structure, or 0 on error. This buffer is overwritten on subsequent calls to this function.
Gets the "standard" host name for the local machine.
Name, pointer to a buffer that will receive the name of the host.
NameLen, the length of the buffer in bytes.
Returns 1 on error, otherwise returns 0 and fills the buffer pointed to by Name with a 0-terminated string containing the name of the local machine.