MarshallSoft
WIL Reference Manual</FONT>

Winsock Interface Library

Reference Manual


(SEE_REF)


Version 3.1

May 9, 2000




This software is provided as-is.
There are no warranties, expressed or implied.



Copyright (C) 2000
All rights reserved



MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815 USA



Voice : 256-881-4630

FAX : 256-880-0925

email : info@marshallsoft.com

web : www.marshallsoft.com


MarshallSoft is a member of the Association of Shareware Professionals

MARSHALLSOFT is a registered ® trademark of MarshallSoft Computing.




TABLE OF CONTENTS


1 Introduction
2 WIL Functions
2.1 wilAccept
2.2 wilAttach
2.3 wilAwaitEvent
2.4 wilBind
2.5 wilCancelBlocking
2.6 wilCloseSocket
2.7 wilConnect
2.8 wilDataIsReady
2.9 wilDebug
2.10 wilDecode64
2.11 wilDecodeUU
2.12 wilEncode64
2.13 wilEncodeUU
2.14 wilErrorText
2.15 wilGetDescription
2.16 wilGetHostAddr
2.17 wilGetHostAlias
2.18 wilGetHostDotted
2.19 wilGetHostName
2.20 wilGetMaxSockets
2.21 wilGetMaxUDPSize
2.22 wilGetMyHostAddr
2.23 wilGetMyHostDotted
2.24 wilGetMyHostName
2.25 wilGetProtoName
2.26 wilGetProtoNumber
2.27 wilGetServName
2.28 wilGetServPort
2.29 wilGetSystemInfo
2.30 wilGetVendorInfo
2.31 wilIsBlocking
2.32 wilIsConnected
2.33 wilIsDotted
2.34 wilListen
2.35 wilLocalSockAddr
2.36 wilLocalSockPort
2.37 wilMakeAddr
2.38 wilMakeDotted
2.39 wilParseDecimal
2.40 wilPeekSocket
2.41 wilPing
2.42 wilReadLine
2.43 wilReadOOB
2.44 wilReadSocket
2.45 wilReadString
2.46 wilReadUdpSocket
2.47 wilRelease
2.48 wilRemoteSockAddr
2.49 wilRemoteSockPort
2.50 wilSetOOB
2.51 wilSocketStatus
2.52 wilTcpSocket
2.53 wilUdpSocket
2.54 wilWaitLine
2.55 wilWriteLine
2.56 wilWriteOOB
2.57 wilWriteSocket
2.58 wilWriteString
2.59 wilWriteUdpSoscket
3 WIL Error Codes

1. Introduction

All functions return an integer code. Negative values are always errors. Non-negative return codes are never errors.


2. WIL Functions


2.1 wilAccept: Accepts incoming connection.

SYNTAX

SOCKET wilAccept(SOCKET Socket, LONG Timeout)
// Socket  : Winsock socket number.
// Timeout : Timeout in milliseconds.

REMARKS

The wilAccept function accepts an incoming connection on a specified socket, dequeueing the first connection request on the listening socket, and returning a new socket which may be used immediately to send or receive data. wilBind and wilListen are called before wilAccept.

RETURNS


OTHER

See wilBind and wilListen.



2.2 wilAttach: Attaches (initializes) Winsock.

SYNTAX

int wilAttach(void)

REMARKS

The wilAttach function prepares the WIL system for processing. It should be the first WIL function called.

RETURNS


OTHER

See wilRelease.


2.3 wilAwaitEvent: Set asynchronous event Winsock mask.


SYNTAX

int wilAwaitEvent(SOCKET Socket, HWND hWnd, WORD Message, ULONG EventMask)
// Socket    : Winsock socket number.
// hWnd      : Window handle for message posting.
// Message   : Message number.
// EventMask : Event Mask.

REMARKS

The wilAwaitEvent function enables asynchronous processing by enabling the events specified by the EventMask. Event mask values are defined in WINSOCK.H as
   FD_ACCEPT : Sends message when socket has incoming connection.
  FD_CLOSE : Sends message when socket has been closed.
FD_CONNECT : Sends message when socket has completed connecting.
    FD_OOB : Sends message when out-of-band data can be read.
   FD_READ : Sends message when data is available to read.
  FD_WRITE : Sends message when socket is ready for writing.

When the specified event occurs, the specified message is posted to the specified window.

Several macros are defined for calling wilAwaitEvent. Refer to wilAwaitConnect, wilAwaitAccept, wilAwaitRead, wilAwaitWrite, wilAwaitClose, and wilAwaitCancel (in WIL.H).

RETURNS


OTHER

See wilListen and wilAccept.


2.4 wilBind: Bind socket to specified address and port number.


SYNTAX

int wilBind(SOCKET Socket, ULONG LocalAddr, short LocalPort)
// Socket    : Winsock socket number.
// LocalAddr : Local socket address.
// LocalPort : Local port number.

REMARKS

The wilBind function binds a socket address and a port number to a particular socket. The bind function specifies the local interface address and port number for the specified socket.

RETURNS


OTHER


See wilListen and wilAccept. Also FTP.C example program



2.5 wilCancelBlocking: Cancels blocking call.


SYNTAX

int wilCancelBlocking(void)

REMARKS

The wilCancelBlocking function cancels any blocking call in progress.

RETURNS


OTHER

See wilIsBlocking.


2.6 wilCloseSocket: Close the socket.


SYNTAX

int wilCloseSocket(SOCKET Socket, int Linger)
// Socket : Winsock socket number.
// Linger : Linger time (milliseconds) after closing the socket.

REMARKS

The wilCloseSocket function closes a socket. The linger time is the maximum time to allow for all I/O to complete. A linger time of zero is known as a "hard close". After closing, I/O can no longer be performed on the socket.

RETURNS


OTHER

See wilTcpSocket and wilUdpSocket.



2.7 wilConnect: Initiate connection to remote port.


SYNTAX

int wilConnect(SOCKET Socket, ULONG RemoteAddr, short RemotePort)
// Socket     : Winsock socket number.
// RemoteAddr : Remote socket address.
// RemotePort : Remote port number.

REMARKS

The wilConnect function requests connection to a remote port. The connection does not occur before wilConnect returns. Rather, wilIsConnected can be called to determine when the connection is completed and ready for I/O. wilConnect is used in client side programs, but usually not in server side programs.

RETURNS


OTHER

See wilIsConnected


2.8 wilDataIsReady: Is socket readable (data is ready).


SYNTAX

int wilDataIsReady(SOCKET Socket, ULONG Timeout)
// Socket  : Winsock socket number.
// Timeout : Timeout in milliseconds.

REMARKS

The wilDataIsReady function returns TRUE if data is ready for reading on the specified socket. This function will wait up to 'Timeout' milliseconds for incoming data before returning FALSE.

RETURNS


OTHER

See wilIsConnected.



2.9 wilDebug: Get debug information from the DLL.


SYNTAX

int wilDataIsReady(int Parm)
// Parm  : Debug parameter.

REMARKS

The two user parameters are WIL_GET_VERSION and WIL_GET_BUILD, which return the version number (X.Y.Z) and the build number of the DLL. Version numbers are 3 digit numbers. Refer to the WILVER sample program for an example.

RETURNS

The requested parameter.

OTHER

None.

2.10 wilDecode64: Decode Base 64 buffer.


SYNTAX

void wilDecode64(LPSTR CodedPtr, LPSTR BinaryPtr)
//  CodedPtr : Pointer to 4-byte source buffer
// BinaryPtr : Pointer to 3-byte target buffer

REMARKS

The wilDecode64 function decodes a 4 byte buffer (previously Base 64 encoded) into the original 3 bytes. The primary purpose of this function is to decode MIME Base64 mail attachments.

RETURNS

None.

OTHER

See wilEncode64.

2.11 wilDecodeUU: Decodes UU encoded buffer.


SYNTAX

void wilDecodeUU(LPSTR CodedPtr, LPSTR BinaryPtr)
//  CodedPtr : Pointer to 4-byte source buffer
// BinaryPtr : Pointer to 3-byte target buffer

REMARKS

The wilDecodeUU function decodes a 4 byte buffer (previously UU encoded) into the original 3 bytes. The primary purpose of this function is to decode UU encoded mail attachments.

RETURNS

None.

OTHER

See wilEncodeUU.

2.12 wilEncode64: Encode into Base 64.


SYNTAX

void wilEncode64(LPSTR BinaryPtr, LPSTR CodedPtr)
//  BinaryPtr : Pointer to 3-byte target buffer
//  CodedPtr  : Pointer to 4-byte source buffer

REMARKS

The wilEncode64 function encodes a 3 byte buffer into a 4 byte Base 64 encoded form. The primary purpose of this function is to encode MIME Base64 mail attachments.

RETURNS

None.

OTHER

See wilDecode64.

2.13 wilEncodeUU: Encodes UU encoded buffer.


SYNTAX

void wilEncodeUU(LPSTR CodedPtr, LPSTR BinaryPtr)
//  CodedPtr  : Pointer to 4-byte source buffer
//  BinaryPtr : Pointer to 3-byte target buffer

REMARKS

The wilEncodeUU function encodes a 3 byte buffer into a 4 byte UU encode form. The primary purpose of this function is to encode MIME Base64 mail attachments.

RETURNS

None.

OTHER

See wilEncodeUU.

2.14 wilErrorText: Get text associated with error code.


SYNTAX

int wilErrorText(WORD Code, LPSTR Buffer, int Size)
// Code   : Error code.
// Buffer : Buffer for error text.
// Size   : Size of error text buffer.

REMARKS

The wilErrorText function retrieves the error text associated with the passed error code and returns it in Buffer.

RETURNS


OTHER

None.



2.15 wilGetDescription: Get Winsock description text.


SYNTAX

void wilGetDescription(LPSTR Buffer, int BufLen)
//  Buffer : Buffer into which data is copied.
//  BufLen : Size of Buffer.

REMARKS

The wilGetDescription function copies the Winsock description text into 'Buffer' after initializing (by calling wilAttach).
The text returned is determined by the implementer of the WINSOCK.

RETURNS


OTHER

See wilGetVendorInfo and wilGetSystemInfo.


2.16 wilGetHostAddr: Get host address.


SYNTAX

ULONG wilGetHostAddr(LPSTR HostName, int Index)
// HostName : Host name.
// Index    : Host address index.

REMARKS

The wilGetHostAddr function gets the host address, The first (or only) host address corresponds to Index=0. Additional host addresses are returned for Index>0. No more host addresses are available when 0 is returned. See HOST.C for an example.

RETURNS


OTHER

See wilGetHostName and wilGetHostAddr.



2.17 wilGetHostAlias: Get host name alias.


SYNTAX

int wilGetHostAlias(ULONG HostIP, int Index, LPSTR Buffer, int BufLen)
// HostIP : Host IP address.
// Index  : Host alias (address) index.
// Buffer : Buffer into which data is copied.
// BufLen : Size of Buffer.

REMARKS

The wilGetHostAlias function gets the host alias name. The first (if any) name alias corresponds to Index=0. No more host aliases are available when NULL is returned. See HOST.C for an example.

RETURNS


OTHER

See wilGetHostName and wilGetHost


2.18 wilGetHostDotted: Get host dotted address.


SYNTAX

int wilGetHostDotted(LPSTR HostName, int Index, LPSTR Buffer, int BufLen)
// HostName : Host name.
//    Index : Host address index.
//   Buffer : Buffer into which data is copied.
//   BufLen : Size of Buffer.

REMARKS

The wilGetHostDotted function gets the host address in dotted decimal notation. The first (or only) host address corresponds to Index=0. Additional host addresses are returning for Index>0. No more host addresses are available when 0 is returned. See HOST.C for an example.

RETURNS


OTHER

See wilGetHostName and wilGetHostAddr.



2.19 wilGetHostName: Get host name.


SYNTAX

int wilGetHostName(LPSTR Dotted, LPSTR Buffer, int BufLen)
// Dotted : Host name in dotted address text format.
// Buffer : Buffer into which data is copied.
// BufLen : Size of Buffer.

REMARKS

The wilGetHostName function gets the host address name associated with the host address. See HOST.C for an example.

RETURNS


OTHER

See wilGetHostAddr and wilGetHostDotted.


2.20 wilGetMaxSockets: Get maximum number of sockets supported.


SYNTAX

int wilGetMaxSockets(void)

REMARKS

The wilGetMaxSockets function returns the maximum number of sockets available to the calling application.

RETURNS


OTHER

None.



2.21 wilGetMaxUDPSize: Get maximum UDP packet size.


SYNTAX

int wilGetMaxUDPSize(void)

REMARKS

The wilGetMaxUDPSize function returns the maximum size of UDP packets.

RETURNS


OTHER

See wilUdpSocket.


2.22 wilGetMyHostAddr: Get local host address.


SYNTAX

ULONG wilGetMyHostAddr(int Index, LPSTR Buffer, int BufLen)
//  Index : Local host address index.
// Buffer : Buffer into which data is copied.
// BufLen : Size of Buffer.

REMARKS

The wilGetMyHostAddr function gets the address of the local host (in host byte order). The first (or only) host address corresponds to Index=0. No more host addresses are available when 0 is returned.

RETURNS


OTHER

See wilGetMyHostDotted and wilGetMyHostName.



2.23 wilGetMyHostDotted: Get local host (dotted) address.


SYNTAX

LPSTR wilGetMyHostDotted(int Index, LPSTR Buffer, int BufLen)
//  Index : Local host address index.
// Buffer : Buffer into which data is copied.
// BufLen : Size of Buffer.

REMARKS

The wilGetMyHostDotted function gets the host name of the local host in dotted decimal notation. The first (or only) host address corresponds to Index=0. No more host addresses are available when NULL is returned.

RETURNS


OTHER

See wilGetMyHostName and wilGetMyHostAddr.


2.24 wilGetMyHostName: Get local host name.


SYNTAX

LPSTR wilGetMyHostName(LPSTR Buffer, int BufLen)
// Buffer : Buffer into which data is copied.
// BufLen : Size of Buffer.

REMARKS

The wilGetMyHostName function gets the name of the local host.

RETURNS


OTHER

See wilGetMyHostAddr and wilGetMyHostDotted.



2.25 wilGetProtoName: Get protocol name


SYNTAX

int wilGetProtoName(int ProtoNumber, LPSTR Buffer, int Buflen)
// ProtoNumber : protocol number.
// Buffer : Buffer into which data is copied.
// BufLen : Size of Buffer.

REMARKS

The wilGetProtoName function returns the protocol name associated with the protocol number. See HOST.C for an example.

RETURNS

OTHER

See wilGetProtoByNumber.

2.26 wilGetProtoNumber: Get protocol number.


SYNTAX

short wilGetProtoNumber(LPSTR ProtoName)
// ProtoName : Protocol name.

REMARKS

The wilGetProtoNumber function returns the protocol number of 'ProtoName'. See HOST.C for an example.

RETURNS


OTHER

See wilAskProtoByName and wilAskProtoByNumber.



2.27 wilGetServName: Get server name.


SYNTAX

int wilGetServName(int Number, LPSTR ProtoN, Buffer, LPSTR Buffer, int BufLen);
// Number : Port number.
// ProtoN : Protocol name.
// Buffer : Buffer into which data is copied.
// BufLen : Size of Buffer.

REMARKS

The wilGetServName function gets the server name for port number 'Number' and protocol name 'ProtoN'. See HOST.C for an example.

RETURNS


OTHER

See wilAskServByName and wilAskServByPort.


2.28 wilGetServPort: Get server port.


SYNTAX

int wilGetServPort(LPSTR ServeN, LPSTR ProtoN)
// ServeN : Server name.
// ProtoN : Server name.

REMARKS

The wilGetServPort function gets the server port for Server 'ServN' and protocol 'ProtoN'. See HOST.C for an example.

RETURNS


See wilAskServByName and wilAskServByPort.



2.29 wilGetSystemInfo: Get Winsock system information.


SYNTAX

void wilGetSystemInfo(LPSTR Buffer, int BufLen)
// Buffer : Buffer into which data is copied.
// BufLen : Size of Buffer.

REMARKS

The wilGetSystemInfo function returns system WINSOCK information. The text returned is determined by the implementer of the WINSOCK.

RETURNS


OTHER

See wilGetVendorInfo and wilGetDescription.


2.30 wilGetVendorInfo: Get Winsock vendor information.


SYNTAX

void wilGetVendorInfo(LPSTR Buffer, int BufLen)
// Buffer : Buffer into which data is copied.
// BufLen : Size of Buffer.

REMARKS

The wilGetVendorInfo function returns vendor specific WINSOCK information. The text returned is determined by the implementer of the WINSOCK.

RETURNS


OTHER

See wilGetDescription and wilGetSystemInfo.



2.31 wilIsBlocking: Is Winsock currently blocking ?


SYNTAX

int wilIsBlocking(void)

REMARKS

The wilIsBlocking function returns TRUE or FALSE to indicate if the socket is currently blocking.

RETURNS


OTHER

See wilCancelBlocking.


2.32 wilIsConnected: Is socket connected to remote ?


SYNTAX

int wilIsConnected(SOCKET Socket, ULONG Timeout)
// Socket   : Winsock socket number.
// Timeout : Timeout in millisecs.

REMARKS

The wilIsConnected function returns TRUE or FALSE to indicate if the specified socket is writable, which means that a connection has been completed to a remote host. This function will wait up to 'Timeout' milliseconds for a connection before returning FALSE.

RETURNS


OTHER

See wilDataIsReady.



2.33 wilIsDotted: Is dotted string properly formed ?


SYNTAX

int wilIsDotted(LPSTR Name)
// Name : Host name in dotted notation.

REMARKS

The wilIsDotted function returns TRUE or FALSE to indicate if the passed text Name is in legal dotted format. A legal dotted name consists of 4 components separated by decimal points each of which is in the ranger of zero to 255.

RETURNS


OTHER

See wilMakeDotted and wilMakeAddr.


2.34 wilListen: Listen for incoming connection attempts.


SYNTAX

int wilListen(SOCKET Socket, int BackLog)
// Socket : Winsock socket number.
// BackLog : Number of concurrent sessions.

REMARKS

The wilListen function specifies the socket to be used to listen for incoming connection requests. A call to wilListen is usually preceded by a call to wilBind. After calling wilListen, incoming connection requests can be accepted by wilAccept.

RETURNS


OTHER

See wilBind and wilAccept.



2.35 wilLocalSockAddr: Get local sock address for connected socket.


SYNTAX

ULONG wilLocalSockAddr(SOCKET Socket)
// Socket : Winsock socket number.

REMARKS

The wilLocalSockAddr function returns the local socket address associated with an open socket.

RETURNS


OTHER

See wilLocalSockPort.


2.36 wilLocalSockPort: Get local sock port number for connected sock.


SYNTAX

short wilLocalSockPort(SOCKET Socket)
// Socket : Winsock socket number.

REMARKS

The wilLocalSockPort function returns the local socket port associated with an open socket.

RETURNS


OTHER

See wilLocalSockAddr.



2.37 wilMakeAddr: Make IP address.


SYNTAX

ULONG wilMakeAddr(LPSTR Dotted)
// Dotted : IP address in dotted text format.

REMARKS

The wilMakeAddr function creates an IP address from the dotted text equivalent. A legal dotted name consists of 4 components separated by decimal points each of which is in the ranger of zero to 255.

RETURNS


OTHER

wilMakeDotted.


2.38 wilMakeDotted: Make dotted address.


SYNTAX

void wilMakeDotted(ULONG IP, LPSTR Buffer, int BufLen)
// IP     : IP address.
// Buffer : Buffer into which data is copied.
// BufLen : Size of Buffer.

REMARKS

The wilMakeDotted function creates a dotted text address in 'Buffer' corresponding to 'IP'. A legal dotted name consists of 4 components separated by decimal points each of which is in the ranger of zero to 255.

OTHER

wilMakeAddr.

2.39 wilParseDecimal: Parse decimal response code.


SYNTAX

ULONG ParseDecimal(LPSTR Buffer)
// Buffer : Text buffer to parse.

REMARKS

The wilParseDecimal function parses the text string in Buffer and returns the decimal value. A zero is returned if the text string does not begin with a decimal digit. The function is used to return the decimal result codes preceding many protocol response messages, and to return the (unsigned long) article numbers in NTTP.

RETURNS

Unsigned long decimal value.

OTHER

None.

2.40 wilPeekSocket: Peek ahead into socket.


SYNTAX

int wilPeekSocket(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket  : Winsock socket number.
// Buffer  : Data buffer.
// BufSize : Size of data buffer.

REMARKS

The wilPeekSocket function performs a non-destructive read or "look ahead".

RETURNS


OTHER

See wilReadSocket.



2.41 wilPing: Pings an IP address.


SYNTAX

int wilPing(ULONG  Addr, ULONG TimeOut, USHORT Port, USHORT Seq);
// Addr    : Remote Address.
// TimeOut : Data buffer.
// Port    : Size of data buffer.
// Seq     : Sequence number.

REMARKS

The wilPing function uses raw sockets to "ping" the specified port address. The 'Seq' sequence number is inserted into the transmitted packet. See the PING.C example program.

RETURNS



2.42 wilReadLine: Read line terminated with linefeed.


SYNTAX

int wilReadLine(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket  : Winsock socket number.
// Buffer  : Data buffer.
// BufSize : Size of data buffer.

REMARKS

The wilReadLine function reads the requested number of bytes or until a linefeed ('\n') character is read. Upon return, the last character of Buffer can be examined to see if an entire line was read. Do not assume that an entire line was read without checking that the last character is a linefeed ('\n').

RETURNS


OTHER

See wilReadSocket and wilReadString.



2.43 wilReadOOB: Read Out Of Bound data.


SYNTAX

int wilReadOOB(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket  : Winsock socket number.
// Buffer  : Data buffer.
// BufSize : Size of data buffer.

REMARKS

The wilReadOOB function reads the specified number of Out-Of-Bounds (OOB) bytes for the socket. The function will return 0 if no bytes are currently available. Note that fewer bytes may be read than requested. Reading of OOB data must be enabled (wilSetOOB) before calling this function.

RETURNS


OTHER

See wilReadSocket and wilReadString.


2.44 wilReadSocket: Read from socket.


SYNTAX

int wilReadSocket(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket  : Winsock socket number.
// Buffer  : Data buffer.
// BufSize : Size of data buffer.

REMARKS

The wilReadSocket function reads the specified number of bytes for the socket. The function will return 0 if no bytes are currently available. Note that fewer bytes may be read than requested.

RETURNS


OTHER

See wilReadLine and wilReadString.



2.45 wilReadString: Read string from socket.


SYNTAX

int wilReadString(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket  : Winsock socket number.
// Buffer  : Data buffer.
// BufSize : Size of data buffer.

REMARKS

The wilReadString function performs a wilReadSocket, then appends the NUL character '\0'.

RETURNS


OTHER

See wilReadSocket and wilReadLine.


2.46 wilReadUdpSocket: Read string from socket


SYNTAX

int wilReadUdpSocket(SOCKET Socket, LPSTR Buffer, int BufSize, LPSTR RemoteIP)
// Socket   : Winsock socket number.
// Buffer   : Data buffer.
// BufSize  : Size of data buffer.
// RemoteIP : Buffer for remote IP address (dotted).

REMARKS

The wilReadUdpSocket reads from the UDP socket opened by wilUdpSocket. The packet is returned in 'Buffer', and the IP address of the remote host is returned in RemoteIP in dotted text notation. See the UECHOC.C (client) and UECHOS.C (server) examples.

RETURNS


OTHER

See wilUdpSocket and wilWriteUdpSocket.



2.47 wilRelease: Release (free) Winsock.


SYNTAX

int wilRelease(void)

REMARKS

The wilRelease function releases the WINSOCK resources, after which socket functions should not be called.

wilRelease should be called before exiting the application program.

RETURNS


OTHER

See wilAttach.


2.48 wilRemoteSockAddr: Get remote sock address for connected socket.


SYNTAX

ULONG wilRemoteSockAddr(SOCKET Socket)
// Socket : Winsock socket number.

REMARKS

The wilRemoteSockAddr function returns the address of the connected remote socket.

RETURNS


OTHER

See wilRemoteSockAddr.



2.49 wilRemoteSockPort: Get remote port number for connected socket.


SYNTAX

short wilRemoteSockPort(SOCKET Socket)
// Socket : Winsock socket number.

REMARKS

The wilRemoteSockPort function returns the port number of the connected remote host.

RETURNS


OTHER

See wilRemoteSockAddr.


2.50 wilSetOOB: Sets Out Of Bound (OOB) data state.


SYNTAX

int wilSetOOB(SOCKET Socket, int StateFlag)
// Socket    : Winsock socket number.
// StateFlag : Enable OOB if TRUE.

REMARKS

The wilSetOOB function enables or disables Out-Of-Bound (OOB) data depending on the value StateFlag. OOB data is data that is processed ahead of any other data that is not OOB. Typically, OOB data is used to indicate an error condition of some sort. When OOB is enabled, only OOB data can be read.

RETURNS


OTHER

See wilReadOOB and wilWriteOOB.



2.51 wilSocketStatus: Get socket read/write status.


SYNTAX

int wilSocketStatus(SOCKET Socket, int StatusFlag)
// Socket     : Winsock socket number.
// StatusFlag : Status type requested (see below).

REMARKS

The wilSocketStatus function returns the socket status requested as follows:
 WIL_READ_STATUS : Returns TRUE if socket has incoming data.
WIL_WRITE_STATUS : Returns TRUE if socket is writable.
WIL_ERROR_STATUS : Returns TRUE if socket has error.

A socket is connected if it is writable.

RETURNS


OTHER


See wilDataIsReady and wilIsConnected.


2.52 wilTcpSocket: Creates TCP socket.


SYNTAX

SOCKET wilTcpSocket(void)

REMARKS

The wilTcpSocket function creates a TCP socket. WilTcpSocket must be called before calling wilBind or wilConnect.

RETURNS


OTHER

See wilCloseSocket.



2.53 wilUdpSocket: Creates UDP socket.


SYNTAX

SOCKET wilUdpSocket(void)

REMARKS

The wilUdpSocket function creates a UDP socket. WilUdpSocket must be called before calling wilReadUdpSocket or wilWriteUdpSoscket.

RETURNS


OTHER

See wilCloseSocket, wilReadUdpSocket and wilWriteUdpSocket.


2.54 wilWaitLine: Read line, waiting for terminating linefeed.


SYNTAX

int wilWaitLine(SOCKET Socket, LPSTR Buffer, int BufSize,

                ULONG InitWait, ULONG LineWait)
// Socket  : Winsock socket number.
// Buffer  : Data buffer.
// BufSize : Size of data buffer.
// InitWait: Time-out (ms) waiting for start of line.
// LineWait: Time-out (ms) waiting for remainder of line.

REMARKS

The wilWaitLine function reads the requested number of bytes or until a linefeed ('\n') character is read.

The wilWaitLine function will wait up to a maximum of 'InitWait' milliseconds for the first character of the line and up to 'LineWait' for a terminating linefeed ('\n') character. Examine the last byte of 'Buffer' to determine if the linefeed was actually read.

RETURNS


OTHER

See wilReadLine.



2.55 wilWriteLine: Write linefeed terminated line to socket.


SYNTAX

int wilWriteLine(SOCKET Socket, LPSTR String)
// Socket  : Winsock socket number.
// String  : String buffer.

REMARKS

The wilWriteLine function performs wilWriteString, then writes carriage return ('\r') and linefeed ('\n') to the socket.

RETURNS


OTHER

See wilWriteSocket and wilWriteString.


2.56 wilWriteOOB: Write Out Of Bounds (OOB) data to socket.


SYNTAX

int wilWriteOOB(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket  : Winsock socket number.
// Buffer  : Data buffer.
// BufSize : Size of data buffer.

REMARKS

The wilWriteOOB function attempts to write the requested bytes in Buffer to the specified socket.

RETURNS


OTHER



2.57 wilWriteSocket: Write buffer to socket.


SYNTAX

int wilWriteSocket(SOCKET Socket, LPSTR Buffer, int BufSize)
// Socket  : Winsock socket number.
// Buffer  : Data buffer.
// BufSize : Size of data buffer.

REMARKS

The wilWriteSocket function attempts to write the requested number of bytes to the specified socket. Note that fewer bytes may be written than requested.

RETURNS


OTHER

wilWriteString and wilWriteLine.


2.58 wilWriteString: Write string to socket.


SYNTAX

int wilWriteString(SOCKET Socket, LPSTR String)
// Socket  : Winsock socket number.
// String  : String buffer (terminated with '\0').

REMARKS

The wilWriteString function performs wilWriteSocket, using the string length of String for the requested bytes to write.

RETURNS


OTHER

wilWriteLine, wilWriteString.



2.59 wilWriteUdpSocket: Write buffer to UDP socket.


SYNTAX

int wilWriteUdpSocket(SOCKET Socket,LPSTR Buffer, int BufLen, ULONG RemoteIP,

USHORT RemotePort)
// Socket     : Winsock socket number.
// Buffer     : Data buffer.
// BufSize    : Size of data buffer.
// RemoteIP   : Remote IP address.
// RemotePort : Remote port number.

REMARKS

The wilWriteUdpSoscket function writes the first 'BufLen' bytes of 'Buffer' to the UDP socket 'Socket' using remote IP address 'RemoteIP' and remote port 'RemotePort'.

RETURNS


OTHER

wilUdpSocket and wilReadUdpSocket.


3 WIL Error Codes

       WIL_NO_ERROR : No error.
  WIL_CANNOT_COMPLY : Cannot comply. Not necessarily an error.
            WIL_EOF : End of file (socket has been closed).
    WIL_IS_BLOCKING : Socket is currently blocking.
WIL_BAD_STATUS_FLAG : Bad status flag passed to wilSocketStatus.
     WIL_BAD_DOTTED : Bad dotted address.
 WIL_INVALID_SOCKET : Invalid socket number.
      WIL_TIMED_OUT : Socket timed out awaiting data.
   WIL_NO_SOCK_ADDR : Socket address pool exhausted.
        WIL_NO_HOST : Error returning host information.
        WIL_ABORTED : The shareware DLL has been corrupted.

WIL_ABORTED will be returned if the DLL has been modified. You should never get this message!