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
- Return >0 : Socket.
- Return < 0 : Error. See error list.
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
- Return = WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- WIL_NO_ERROR : No error.
- Return = 0 : Error. See error list.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- TRUE: Data is ready
- FALSE : No incoming data is ready.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- NULL : Text not available.
- Else : Pointer to text.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- NULL : Text not available.
- Else : Pointer to text.
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
- NULL : Text not available.
- Else : Pointer to text.
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
- NULL : Text not available.
- Else : Pointer to text.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- Return > 0 : Maximum size of UDP packets.
- Return < 0 : Error. See error list.
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
- Return > 0 : Host address [host byte order].
- Return < 0 : Error. See error list.
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
- NULL : Text not available.
- Else : Pointer to text.
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
- NULL : Text not available.
- Else : Pointer to text.
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
- Return > 0 : Protocol number.
- Return < 0 : Error. See error list.
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
- NULL : Text not available.
- Else : Pointer to text.
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
- Return > 0 : Server port number.
- Return < 0 : Error. See error list.
OTHER
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
- NULL : Text not available.
- Else : Pointer to text.
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
- NULL : Text not available.
- Else : Pointer to text.
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
- TRUE : Socket is currently blocking.
- FALSE : Socket is not blocking.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- TRUE : Name is good dotted address.
- FALSE : Name has errors.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- Return > 0 : Local socket address.
- Return < 0 : Error. See error list.
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
- Return > 0 : Local socket port number.
- Return < 0 : Error. See error list.
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
- Return = 0 : Bad dotted address.
- Return > 0 : IP address.
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
- Return = 0 : Data not available.
- Return > 0 : Number of bytes actually read.
- Return < 0 : Error. See error list.
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
- Return > 0 : Sequence number in returned packet.
- Return < 0 : Error. See error list.
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
- Return = 0 : Data not available.
- Return > 0 : Number of bytes actually read.
- Return < 0 : Error. See error list.
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
- Return = 0 : Data not available.
- Return > 0 : Number of bytes actually read.
- Return < 0 : Error. See error list.
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
- Return = 0 : Data not available.
- Return > 0 : Number of bytes actually read.
- Return < 0 : Error. See error list.
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
- Return = 0 : Data not available.
- Return > 0 : Number of bytes actually read.
- Return < 0 : Error. See error list.
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
- Return = 0 : Data not available.
- Return > 0 : Number of bytes actually read.
- Return < 0 : Error. See error list.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- Return != 0 : Remote socket address [host byte order].
- Return = 0 : Address not available.
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
- Return != 0 : Port number of remote socket.
- Return = 0 : Port not available.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- WIL_NO_ERROR : No error.
- Return < 0 : Error. See error list.
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
- Return > 0 : TCP socket.
- Return < 0 : Error. See error list.
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
- Return > 0 : UDP socket.
- Return < 0 : Error. See error list.
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
- Return = 0 : Data not available.
- Return > 0 : Number of bytes actually read.
- Return < 0 : Error. See error list.
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
- Return = 0 : Could not write.
- Return > 0 : Number of bytes actually written.
- Return < 0 : Error. See error list.
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
- Return = 0 : Could not write.
- Return > 0 : Number of bytes actually written.
- Return < 0 : Error. See error list.
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
- Return = 0 : Could not write.
- Return > 0 : Number of bytes actually written.
- Return < 0 : Error. See error list.
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
- Return = 0 : Could not write.
- Return > 0 : Number of bytes actually written.
- Return < 0 : Error. See error list.
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
- Return = 0 : Could not write.
- Return > 0 : Number of bytes actually written.
- Return < 0 : Error. See error list.
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!