4.3 Microsoft Windows-specific Extensions

4.3.1 WSAAsyncGetHostByAddr()

Description	Get host information corresponding to an address - asynchronous version.
	#include <winsock.h>
	HANDLE PASCAL FAR WSAAsyncGetHostByAddr ( HWND hWnd, unsigned int wMsg, const char FAR * addr, int len, int type, char FAR * buf, int buflen );

	hWnd	The handle of the window which should receive a message when the asynchronous request completes.
	wMsg	The message to be received when the asynchronous request completes.
	addr	A pointer to the network address for the host. Host addresses are stored in network byte order.
	len	The length of the address, which must be 4 for PF_INET.
	type	The type of the address, which must be PF_INET.
	buf	A pointer to the data area to receive the hostent data. Note that this must be larger than the size of a hostent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a hostent structure but any and all of the data which is referenced by members of the hostent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.
	buflen	The size of data area buf above.

Remarks

This function is an asynchronous version of gethostbyaddr(), and is used to retrieve host name and address information corresponding to a network address. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code may be any error as defined in winsock.h. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a hostent structure. To access the elements of this structure, the original buffer address should be cast to a hostent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetHostByAddr() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.
If the operation was successfully initiated, WSAAsyncGetHostByAddr() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.
If the asynchronous operation could not be initiated, WSAAsyncGetHostByAddr() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments

The buffer supplied to this function is used by the Windows Sockets implementation to construct a hostent structure together with the contents of data areas referenced by members of the same hostent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in winsock.h).

Notes For Windows Sockets

Suppliers	It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists. Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.
Error Codes	The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN

WSAENOBUFS
WSAHOST_NOT_FOUND
WSATRY_AGAIN

WSANO_RECOVERY

WSANO_DATA

The Windows Sockets implementation has detected that the network subsystem has failed.
No/insufficient buffer space is available
Authoritative Answer Host not found.
Non-Authoritative Host not found, or SERVERFAIL.
Non recoverable errors, FORMERR, REFUSED, NOTIMP.
Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED

WSAENETDOWN

WSAEINPROGRESS

WSAEWOULDBLOCK

A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
A blocking Windows Sockets operation is in progress.
The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

See Also

gethostbyaddr(), WSACancelAsyncRequest()

4.3.2 WSAAsyncGetHostByName()

Description	Get host information corresponding to a hostname - asynchronous version.
	#include <winsock.h>
	HANDLE PASCAL FAR WSAAsyncGetHostByName ( HWND hWnd, unsigned int wMsg, const char FAR * name, char FAR * buf, int buflen );

	hWnd	The handle of the window which should receive a message when the asynchronous request completes.
	wMsg	The message to be received when the asynchronous request completes.
	name	A pointer to the name of the host.
	buf	A pointer to the data area to receive the hostent data. Note that this must be larger than the size of a hostent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a hostent structure but any and all of the data which is referenced by members of the hostent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.
	buflen	The size of data area buf above.

Remarks

This function is an asynchronous version of gethostbyname(), and is used to retrieve host name and address information corresponding to a hostname. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetHostByName() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.
If the operation was successfully initiated, WSAAsyncGetHostByName() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.
If the asynchronous operation could not be initiated, WSAAsyncGetHostByName() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments

Notes For Windows Sockets

Suppliers	It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists. Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.
Error Codes	The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

WSAENETDOWN

WSAENOBUFS
WSAHOST_NOT_FOUND
WSATRY_AGAIN

WSANO_RECOVERY

WSANO_DATA

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED

WSAENETDOWN

WSAEINPROGRESS

WSAEWOULDBLOCK

See Also

gethostbyname(), WSACancelAsyncRequest()

4.3.3 WSAAsyncGetProtoByName()

Description	Get protocol information corresponding to a protocol name - asynchronous version.
	#include <winsock.h>
	HANDLE PASCAL FAR WSAAsyncGetProtoByName ( HWND hWnd, unsigned int wMsg, const char FAR * name, char FAR * buf, int buflen );

	hWnd	The handle of the window which should receive a message when the asynchronous request completes.
	wMsg	The message to be received when the asynchronous request completes.
	name	A pointer to the protocol name to be resolved.
	buf	A pointer to the data area to receive the protoent data. Note that this must be larger than the size of a protoent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a protoent structure but any and all of the data which is referenced by members of the protoent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.
	buflen	The size of data area buf above.

Remarks

This function is an asynchronous version of getprotobyname(), and is used to retrieve the protocol name and number corresponding to a protocol name. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code may be any error as defined in winsock.h. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a protoent structure. To access the elements of this structure, the original buffer address should be cast to a protoent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetProtoByName() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.
If the operation was successfully initiated, WSAAsyncGetProtoByName() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.
If the asynchronous operation could not be initiated, WSAAsyncGetProtoByName() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments

The buffer supplied to this function is used by the Windows Sockets implementation to construct a protoent structure together with the contents of data areas referenced by members of the same protoent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in winsock.h).

Notes For Windows Sockets

Suppliers	It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists. Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.
Error Codes	The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

	WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
	WSAENOBUFS	No/insufficient buffer space is available
	WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
	WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
	WSANO_RECOVERY	Non recoverable errors, FORMERR, REFUSED, NOTIMP.
	WSANO_DATA	Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

	WSANOTINITIALISED	A successful WSAStartup() must occur before using this API.
	WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
	WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
	WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

See Also

getprotobyname(), WSACancelAsyncRequest()

4.3.4 WSAAsyncGetProtoByNumber()

Description	Get protocol information corresponding to a protocol number - asynchronous version.
	#include <winsock.h>
	HANDLE PASCAL FAR WSAAsyncGetProtoByNumber ( HWND hWnd, unsigned int wMsg, int number, char FAR * buf, int buflen );

	hWnd	The handle of the window which should receive a message when the asynchronous request completes.
	wMsg	The message to be received when the asynchronous request completes.
	number	The protocol number to be resolved, in host byte order.
	buf	A pointer to the data area to receive the protoent data. Note that this must be larger than the size of a protoent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a protoent structure but any and all of the data which is referenced by members of the protoent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.
	buflen	The size of data area buf above.

Remarks

This function is an asynchronous version of getprotobynumber(), and is used to retrieve the protocol name and number corresponding to a protocol number. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code may be any error as defined in winsock.h. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a protoent structure. To access the elements of this structure, the original buffer address should be cast to a protoent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetProtoByNumber() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.
If the operation was successfully initiated, WSAAsyncGetProtoByNumber() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.
If the asynchronous operation could not be initiated, WSAAsyncGetProtoByNumber() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments

Notes For Windows Sockets

Suppliers	It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists. Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.
Error Codes	The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

	WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
	WSAENOBUFS	No/insufficient buffer space is available
	WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
	WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
	WSANO_RECOVERY	Non recoverable errors, FORMERR, REFUSED, NOTIMP.
	WSANO_DATA	Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

	WSANOTINITIALISED	A successful WSAStartup() must occur before using this API.
	WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
	WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
	WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

See Also

getprotobynumber(), WSACancelAsyncRequest()

4.3.5 WSAAsyncGetServByName()

Description	Get service information corresponding to a service name and port - asynchronous version.
	#include <winsock.h>
	HANDLE PASCAL FAR WSAAsyncGetServByName ( HWND hWnd, unsigned int wMsg, const char FAR * name, const char FAR * proto, char FAR * buf, int buflen );

	hWnd	The handle of the window which should receive a message when the asynchronous request completes.
	wMsg	The message to be received when the asynchronous request completes.
	name	A pointer to a service name.
	proto	A pointer to a protocol name. This may be NULL, in which case WSAAsyncGetServByName() will search for the first service entry for which s_name or one of the s_aliases matches the given name. Otherwise WSAAsyncGetServByName() matches both name and proto.
	buf	A pointer to the data area to receive the servent data. Note that this must be larger than the size of a servent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a servent structure but any and all of the data which is referenced by members of the servent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.
	buflen	The size of data area buf above.

Remarks

This function is an asynchronous version of getservbyname(), and is used to retrieve service information corresponding to a service name. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetServByName() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.
If the operation was successfully initiated, WSAAsyncGetServByName() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.
If the asynchronous operation could not be initiated, WSAAsyncServByName() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments

Notes For Windows Sockets

Suppliers	It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists. Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.
Error Codes	The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

	WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
	WSAENOBUFS	No/insufficient buffer space is available
	WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
	WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
	WSANO_RECOVERY	Non recoverable errors, FORMERR, REFUSED, NOTIMP.
	WSANO_DATA	Valid name, no data record of requested type.

The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

	WSANOTINITIALISED	A successful WSAStartup() must occur before using this API.
	WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
	WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
	WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

See Also

getservbyname(), WSACancelAsyncRequest()

4.3.6 WSAAsyncGetServByPort()

Description	Get service information corresponding to a port and protocol - asynchronous version.
	#include <winsock.h>
	HANDLE PASCAL FAR WSAAsyncGetServByPort ( HWND hWnd, unsigned int wMsg, int port, const char FAR * proto, char FAR * buf, int buflen );

	hWnd	The handle of the window which should receive a message when the asynchronous request completes.
	wMsg	The message to be received when the asynchronous request completes.
	port	The port for the service, in network byte order.
	proto	A pointer to a protocol name. This may be NULL, in which case WSAAsyncGetServByPort() will search for the first service entry for which s_port match the given port. Otherwise WSAAsyncGetServByPort() matches both port and proto.
	buf	A pointer to the data area to receive the servent data. Note that this must be larger than the size of a servent structure. This is because the data area supplied is used by the Windows Sockets implementation to contain not only a servent structure but any and all of the data which is referenced by members of the servent structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.
	buflen	The size of data area buf above.

Remarks

This function is an asynchronous version of getservbyport(), and is used to retrieve service information corresponding to a port number. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.

When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code may be any error as defined in winsock.h. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a servent structure. To access the elements of this structure, the original buffer address should be cast to a servent structure pointer and accessed as appropriate.

Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetServByPort() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:

#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)
#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

Return Value

The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself.
If the operation was successfully initiated, WSAAsyncGetServByPort() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.

If the asynchronous operation could not be initiated, WSAAsyncGetServByPort() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().

Comments	The buffer supplied to this function is used by the Windows Sockets implementation to construct a servent structure together with the contents of data areas referenced by members of the same servent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in winsock.h).
Suppliers	It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists. Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

Notes For Windows Sockets

Error Codes

The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.

	WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
	WSAENOBUFS	No/insufficient buffer space is available
	WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
	WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
	WSANO_RECOVERY	Non recoverable errors, FORMERR, REFUSED, NOTIMP.
	WSANO_DATA	Valid name, no data record of requested type. The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.
	WSANOTINITIALISED	A successful WSAStartup() must occur before using this API.
	WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
	WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
	WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

See Also

getservbyport(), WSACancelAsyncRequest()

4.3.7 WSAAsyncSelect()

Description	Request event notification for a socket.
	#include <winsock.h>
	int PASCAL FAR WSAAsyncSelect ( SOCKET s, HWND hWnd, unsigned int wMsg, long lEvent );

	s	A descriptor identifying the socket for which event notification is required.
	hWnd	A handle identifying the window which should receive a message when a network event occurs.
	wMsg	The message to be received when a network event occurs.
	lEvent	A bitmask which specifies a combination of network events in which the application is interested.

Remarks

This function is used to request that the Windows Sockets DLL should send a message to the window hWnd whenever it detects any of the network events specified by the lEvent parameter. The message which should be sent is specified by the wMsg parameter. The socket for which notification is required is identified by s.

This function automatically sets socket s to non-blocking mode.

The lEvent parameter is constructed by or'ing any of the values specified in the following list.

Value	Meaning
FD_READ	Want to receive notification of readiness for reading
FD_WRITE	Want to receive notification of readiness for writing
FD_OOB	Want to receive notification of the arrival of out-of-band data
FD_ACCEPT	Want to receive notification of incoming connections
FD_CONNECT	Want to receive notification of completed connection
FD_CLOSE	Want to receive notification of socket closure

Issuing a WSAAsyncSelect() for a socket cancels any previous WSAAsyncSelect() for the same socket. For example, to receive notification for both reading and writing, the application must call WSAAsyncSelect() with both FD_READ and FD_WRITE, as follows:

rc = WSAAsyncSelect(s, hWnd, wMsg, FD_READ|FD_WRITE);

It is not possible to specify different messages for different events. The following code will not work; the second call will cancel the effects of the first, and only FD_WRITE events will be reported with message wMsg2:

rc = WSAAsyncSelect(s, hWnd, wMsg1, FD_READ);
rc = WSAAsyncSelect(s, hWnd, wMsg2, FD_WRITE);

To cancel all notification - i.e., to indicate that the Windows Sockets implementation should send no further messages related to network events on the socket - lEvent should be set to zero.

rc = WSAAsyncSelect(s, hWnd, 0, 0);

Although in this instance WSAAsyncSelect() immediately disables event message posting for the socket, it is possible that messages may be waiting in the application's message queue. The application must therefore be prepared to receive network event messages even after cancellation. Closing a socket with closesocket() also cancels WSAAsyncSelect() message sending, but the same caveat about messages in the queue prior to the closesocket() still applies.

Since an accept()'ed socket has the same properties as the listening socket used to accept it, any WSAAsyncSelect() events set for the listening socket apply to the accepted socket. For example, if a listening socket has WSAAsyncSelect() events FD_ACCEPT, FD_READ, and FD_WRITE, then any socket accepted on that listening socket will also have FD_ACCEPT, FD_READ, and FD_WRITE events with the same wMsg value used for messages. If a different wMsg or events are desired, the application should call WSAAsyncSelect(), passing the accepted socket and the desired new information.7

When one of the nominated network events occurs on the specified socket s, the application's window hWnd receives message wMsg. The wParam argument identifies the socket on which a network event has occurred. The low word of lParam specifies the network event that has occurred. The high word of lParam contains any error code. The error code be any error as defined in winsock.h.

The error and event codes may be extracted from the lParam using the macros WSAGETSELECTERROR and WSAGETSELECTEVENT, defined in winsock.h as:

#define WSAGETSELECTERROR(lParam)            HIWORD(lParam)
#define WSAGETSELECTEVENT(lParam)            LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

The possible network event codes which may be returned are as follows:

Value	Meaning
FD_READ	Socket s ready for reading
FD_WRITE	Socket s ready for writing
FD_OOB	Out-of-band data ready for reading on socket s.
FD_ACCEPT	Socket s ready for accepting a new incoming connection
FD_CONNECT	Connection on socket s completed
FD_CLOSE	Connection identified by socket s has been closed

Return Value	The return value is 0 if the application's declaration of interest in the network event set was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().
Comments	Although WSAAsyncSelect() can be called with interest in multiple events, the application window will receive a single message for each network event.

As in the case of the select() function, WSAAsyncSelect() will frequently be used to determine when a data transfer operation (send() or recv()) can be issued with the expectation of immediate success. Nevertheless, a robust application must be prepared for the possibility that it may receive a message and issue a Windows Sockets API call which returns WSAEWOULDBLOCK immediately. For example, the following sequence of events is possible:

(i)	data arrives on socket s; Windows Sockets posts WSAAsyncSelect message
(ii)	application processes some other message
(iii)	while processing, application issues an ioctlsocket(s, FIONREAD...) and notices that there is data ready to be read
(iv)	application issues a recv(s,...) to read the data
(v)	application loops to process next message, eventually reaching the WSAAsyncSelect message indicating that data is ready to read
(vi)	application issues recv(s,...), which fails with the error WSAEWOULDBLOCK.

Other sequences are possible.

The Windows Sockets DLL will not continually flood an application with messages for a particular network event. Having successfully posted notification of a particular event to an application window, no further message(s) for that network event will be posted to the application window until the application makes the function call which implicitly reenables notification of that network event.

Event	Re-enabling function
FD_READ	recv() or recvfrom()
FD_WRITE	send() or sendto()
FD_OOB	recv()
FD_ACCEPT	accept()
FD_CONNECT	NONE
FD_CLOSE	NONE

Any call to the reenabling routine, even one which fails, results in reenabling of message posting for the relevant event.

For FD_READ, FD_OOB, and FD_ACCEPT events, message posting is "level-triggered." This means that if the reenabling routine is called and the relevant event is still valid after the call, a WSAAsyncSelect() message is posted to the application. This allows an application to be event-driven and not concern itself with the amount of data that arrives at any one time. Consider the following sequence:

(i)	Windows Sockets DLL receives 100 bytes of data on socket s and posts an FD_READ message.
(ii)	The application issues recv( s, buffptr, 50, 0) to read 50 bytes.
(iii)	The Windows Sockets DLL posts another FD_READ message since there is still data to be read.

With these semantics, an application need not read all available data in response to an FD_READ message--a single recv() in response to each FD_READ message is appropriate. If an application issues multiple recv() calls in response to a single FD_READ, it may receive multiple FD_READ messages. Such an application may wish to disable FD_READ messages before starting the recv() calls by calling WSAAsyncSelect() with the FD_READ event not set.

If an event is true when the application initially calls WSAAsyncSelect() or when the reenabling function is called, then a message is posted as appropriate. For example, if an application calls listen(), a connect attempt is made, then the application calls WSAAsyncSelect() specifying that it wants to receive FD_ACCEPT messages for the socket, the Windows Sockets implementation posts an FD_ACCEPT message immediately.

The FD_WRITE event is handled slightly differently. An FD_WRITE message is posted when a socket is first connected with connect() or accepted with accept(), and then after a send() or sendto() fails with WSAEWOULDBLOCK and buffer space becomes available. Therefore, an application can assume that sends are possible starting from the first FD_WRITE message and lasting until a send returns WSAEWOULDBLOCK. After such a failure the application will be notified that sends are again possible with an FD_WRITE message.

The FD_OOB event is used only when a socket is configured to receive out-of-band data separately. If the socket is configured to receive out-of-band data in-line, the out-of-band (expedited) data is treated as normal data and the application should register an interest in, and will receive, FD_READ events, not FD_OOB events. An application may set or inspect the way in which out-of-band data is to be handled by using setsockopt() or getsockopt() for the SO_OOBINLINE option.

The error code in an FD_CLOSE message indicates whether the socket close was graceful or abortive. If the error code is 0, then the close was graceful; if the error code is WSAECONNRESET, then the socket's virtual socket was reset. This only applies to sockets of type SOCK_STREAM.

The FD_CLOSE message is posted when a close indication is received for the virtual circuit corresponding to the socket. In TCP terms, this means that the FD_CLOSE is posted when the connection goes into the FIN WAIT or CLOSE WAIT states. This results from the remote end performing a shutdown() on the send side or a closesocket().

Please note your application will receive ONLY an FD_CLOSE message to indicate closure of a virtual circuit. It will NOT receive an FD_READ message to indicate this condition.

Error Codes

WSANOTINITIALISED

WSAENETDOWN

WSAEINVAL
WSAEINPROGRESS

A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
Indicates that one of the specified parameters was invalid
A blocking Windows Sockets operation is in progress.

Additional error codes may be set when an application window receives a message. This error code is extracted from the lParam in the reply message using the WSAGETSELECTERROR macro. Possible error codes for each network event are:

Event: FD_CONNECT

Error Code

Meaning

WSAEADDRINUSE
WSAEADDRNOTAVAIL
WSAEAFNOSUPPORT
WSAECONNREFUSED
WSAEDESTADDRREQ
WSAEFAULT
WSAEINVAL
WSAEISCONN
WSAEMFILE
WSAENETUNREACH
WSAENOBUFS
WSAENOTCONN
WSAENOTSOCK
WSAETIMEDOUT

The specified address is already in use.
The specified address is not available from the local machine.
Addresses in the specified family cannot be used with this socket.
The attempt to connect was forcefully rejected.
A destination address is required.
The namelen argument is incorrect.
The socket is already bound to an address.
The socket is already connected.
No more file descriptors are available.
The network can't be reached from this host at this time.
No buffer space is available. The socket cannot be connected.
The socket is not connected.
The descriptor is a file, not a socket.
Attempt to connect timed out without establishing a connection

Event: FD_CLOSE

Error Code	Meaning
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAECONNRESET	The connection was reset by the remote side.
WSAECONNABORTED	The connection was aborted due to timeout or other failure.

Event: FD_READ
Event: FD_WRITE
Event: FD_OOB
Event: FD_ACCEPT

Error Code	Meaning
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.

Notes For Windows Sockets

Suppliers

It is the responsibility of the Windows Sockets Supplier to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation MUST re-post that message as long as the window exists.
Windows Sockets suppliers should use the WSAMAKESELECTREPLY macro when constructing the lParam in the message.
When a socket is closed, the Windows Sockets Supplier should purge any messages remaining for posting to the application window. However the application must be prepared to receive, and discard, any messages which may have been posted prior to the closesocket().

See Also

select()

4.3.8 WSACancelAsyncRequest()

Description	Cancel an incomplete asynchronous operation.
	#include <winsock.h>
	int PASCAL FAR WSACancelAsyncRequest ( HANDLE hAsyncTaskHandle );

hAsyncTaskHandle

Specifies the asynchronous operation to be canceled.

Remarks	The WSACancelAsyncRequest() function is used to cancel an asynchronous operation which was initiated by one of the WSAAsyncGetXByY() functions such as WSAAsyncGetHostByName(). The operation to be canceled is identified by the hAsyncTaskHandle parameter, which should be set to the asynchronous task handle as returned by the initiating function.
Return Value	The value returned by WSACancelAsyncRequest() is 0 if the operation was successfully canceled. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().
Comments	An attempt to cancel an existing asynchronous WSAAsyncGetXByY() operation can fail with an error code of WSAEALREADY for two reasons. First, the original operation has already completed and the application has dealt with the resultant message. Second, the original operation has already completed but the resultant message is still waiting in the application window queue.

Notes For Windows Sockets

Suppliers

It is unclear whether the application can usefully distinguish between WSAEINVAL and WSAEALREADY, since in both cases the error indicates that there is no asynchronous operation in progress with the indicated handle. [Trivial exception: 0 is always an invalid asynchronous task handle.] The Windows Sockets specification does not prescribe how a conformant Windows Sockets implementation should distinguish between the two cases. For maximum portability, a Windows Sockets application should treat the two errors as equivalent.

Error Codes

WSANOTINITIALISED

WSAENETDOWN

WSAEINVAL

WSAEINPROGRESS

WSAEALREADY

A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
Indicates that the specified asynchronous task handle was invalid
A blocking Windows Sockets operation is in progress.
The asynchronous routine being canceled has already completed.

See Also

WSAAsyncGetHostByAddr(), WSAAsyncGetHostByName(), WSAAsyncGetProtoByNumber(), WSAAsyncGetProtoByName(), WSAAsyncGetHostByName(), WSAAsyncGetServByPort(), WSAAsyncGetServByName().

4.3.9 WSACancelBlockingCall()

Description	Cancel a blocking call which is currently in progress.
	#include <winsock.h>
	int PASCAL FAR WSACancelBlockingCall ( void );
Remarks	This function cancels any outstanding blocking operation for this task. It is normally used in two situations: (1) An application is processing a message which has been received while a blocking call is in progress. In this case, WSAIsBlocking() will be true. (2) A blocking call is in progress, and Windows Sockets has called back to the application's "blocking hook" function (as established by WSASetBlockingHook()). In each case, the original blocking call will terminate as soon as possible with the error WSAEINTR. (In (1), the termination will not take place until Windows message scheduling has caused control to revert to the blocking routine in Windows Sockets. In (2), the blocking call will be terminated as soon as the blocking hook function completes.) In the case of a blocking connect() operation, the Windows Sockets implementation will terminate the blocking call as soon as possible, but it may not be possible for the socket resources to be released until the connection has completed (and then been reset) or timed out. This is likely to be noticeable only if the application immediately tries to open a new socket (if no sockets are available), or to connect() to the same peer. Cancelling an accept() or a select() call does not adversely impact the sockets passed to these calls. Only the particular call fails; any operation that was legal before the cancel is legal after the cancel, and the state of the socket is not affected in any way. Cancelling any operation other than accept() and select() can leave the socket in an indeterminate state. If an application cancels a blocking operation on a socket, the only operation that the application can depend on being able to perform on the socket is a call to closesocket(), although other operations may work on some Windows Sockets implementations. If an application desires maximum portability, it must be careful not to depend on performing operations after a cancel. An application may reset the connection by setting the timeout on SO_LINGER to 0. If a cancel operation compromised the integrity of a SOCK_STREAM's data stream in any way, the Windows Sockets implementation must reset the connection and fail all future operations other than closesocket() with WSAECONNABORTED.
Return Value	The value returned by WSACancelBlockingCall() is 0 if the operation was successfully canceled. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().
Comments	Note that it is possible that the network operation completes before the WSACancelBlockingCall() is processed, for example if data is received into the user buffer at interrupt time while the application is in a blocking hook. In this case, the blocking operation will return successfully as if WSACancelBlockingCall() had never been called. Note that the WSACancelBlockingCall() still succeeds in this case; the only way to know with certainty that an operation was actually canceled is to check for a return code of WSAEINTR from the blocking call.

Error Codes

WSANOTINITIALISED

WSAENETDOWN

WSAEINVAL

A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
Indicates that there is no outstanding blocking call.

4.3.10 WSACleanup()

Description	Terminate use of the Windows Sockets DLL.
	#include <winsock.h>
	int PASCAL FAR WSACleanup ( void );
Remarks	An application or DLL is required to perform a (successful) WSAStartup() call before it can use Windows Sockets services. When it has completed the use of Windows Sockets, the application or DLL must call WSACleanup() to deregister itself from a Windows Sockets implementation and allow the implementation to free any resources allocated on behalf of the application or DLL. Any open SOCK_STREAM sockets that are connected when WSACleanup() is called are reset; sockets which have been closed with closesocket() but which still have pending data to be sent are not affected--the pending data is still sent. There must be a call to WSACleanup() for every call to WSAStartup() made by a task. Only the final WSACleanup() for that task does the actual cleanup; the preceding calls simply decrement an internal reference count in the Windows Sockets DLL. A naive application may ensure that WSACleanup() was called enough times by calling WSACleanup() in a loop until it returns WSANOTINITIALISED.
Return Value	The return value is 0 if the operation was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().
Comments	Attempting to call WSACleanup() from within a blocking hook and then failing to check the return code is a common Windows Sockets programming error. If an application needs to quit while a blocking call is outstanding, the application must first cancel the blocking call with WSACancelBlockingCall() then issue the WSACleanup() call once control has been returned to the application.

Notes For Windows Sockets

Suppliers

Well-behaved Windows Sockets applications will make a WSACleanup() call to indicate deregistration from a Windows Sockets implementation. This function can thus, for example, be utilized to free up resources allocated to the specific application.
A Windows Sockets implementation must be prepared to deal with an application which terminates without invoking WSACleanup() - for example, as a result of an error.
In a multithreaded environment, WSACleanup() terminates Windows Sockets operations for all threads.
A Windows Sockets implementation must ensure that WSACleanup() leaves things in a state in which the application can invoke WSAStartup() to re-establish Windows Sockets usage.

Error Codes

WSANOTINITIALISED

WSAENETDOWN

WSAEINPROGRESS

A successful WSAStartup() must occur before using this API.

The Windows Sockets implementation has detected that the network subsystem has failedA

A blocking Windows Sockets operation is in progress.

See Also

WSAStartup()

4.3.11 WSAGetLastError()

Description	Get the error status for the last operation which failed.
	#include <winsock.h>
	int PASCAL FAR WSAGetLastError ( void );
Remarks	This function returns the last network error that occurred. When a particular Windows Sockets API function indicates that an error has occurred, this function should be called to retrieve the appropriate error code.
Return Value	The return value indicates the error code for the last Windows Sockets API routine performed by this thread.

Notes For Windows Sockets

Suppliers

The use of the WSAGetLastError() function to retrieve the last error code, rather than relying on a global error variable (cf. errno), is required in order to provide compatibility with future multi-threaded environments.
Note that in a nonpreemptive Windows environment WSAGetLastError() is used to retrieve only Windows Sockets API errors. In a preemptive environment, WSAGetLastError() will invoke GetLastError(), which is used to retrieve the error status for all Win32 API functions on a per-thread basis. For portability, an application should use WSAGetLastError() immediately after the Windows Sockets API function which failed.

See Also

WSASetLastError()

4.3.12 WSAIsBlocking()

Description	Determine if a blocking call is in progress.
	#include <winsock.h>
	BOOL PASCAL FAR WSAIsBlocking ( void );
Remarks	This function allows a task to determine if it is executing while waiting for a previous blocking call to complete.
Return Value	The return value is TRUE if there is an outstanding blocking function awaiting completion. Otherwise, it is FALSE.
Comments	Although a call issued on a blocking socket appears to an application program as though it "blocks", the Windows Sockets DLL has to relinquish the processor to allow other applications to run. This means that it is possible for the application which issued the blocking call to be re-entered, depending on the message(s) it receives. In this instance, the WSAIsBlocking() function can be used to ascertain whether the task has been re-entered while waiting for an outstanding blocking call to complete. Note that Windows Sockets prohibits more than one outstanding call per thread.

Notes For Windows Sockets

Suppliers

A Windows Sockets implementation must prohibit more than one outstanding blocking call per thread.

4.3.13 WSASetBlockingHook()

Description	Establish an application-specific blocking hook function.
	#include <winsock.h>
	FARPROC PASCAL FAR WSASetBlockingHook ( FARPROC lpBlockFunc );

lpBlockFunc

A pointer to the procedure instance address of the blocking function to be installed.

Remarks

This function installs a new function which a Windows Sockets implementation should use to implement blocking socket function calls.

A Windows Sockets implementation includes a default mechanism by which blocking socket functions are implemented. The function WSASetBlockingHook() gives the application the ability to execute its own function at "blocking" time in place of the default function.

When an application invokes a blocking Windows Sockets API operation, the Windows Sockets implementation initiates the operation and then enters a loop which is similar to the following pseudocode:

for(;;) {
     /* flush messages for good user response */
     while(BlockingHook())
          ;
     /* check for WSACancelBlockingCall() */
     if(operation_cancelled())
          break;
     /* check to see if operation completed */
     if(operation_complete())
          break;     /* normal completion */
}

Note that Windows Sockets implementations may perform the above steps in a different order; for example, the check for operation complete may occur before calling the blocking hook. The default BlockingHook() function is equivalent to:

BOOL DefaultBlockingHook(void) {
     MSG msg;
     BOOL ret;
     /* get the next message if any */
     ret = (BOOL)PeekMessage(&msg,NULL,0,0,PM_REMOVE);
     /* if we got one, process it */
     if (ret) {
          TranslateMessage(&msg);
          DispatchMessage(&msg);
     }
     /* TRUE if we got a message */
     return ret;
}

The WSASetBlockingHook() function is provided to support those applications which require more complex message processing - for example, those employing the MDI (multiple document interface) model. It is not intended as a mechanism for performing general applications functions. In particular, the only Windows Sockets API function which may be issued from a custom blocking hook function is WSACancelBlockingCall(), which will cause the blocking loop to terminate.

This function must be implemented on a per-task basis for non-multithreaded versions of Windows and on a per-thread basis for multithreaded versions of Windows such as Windows NT. It thus provides for a particular task or thread to replace the blocking mechanism without affecting other tasks or threads.

In multithreaded versions of Windows, there is no default blocking hook--blocking calls block the thread that makes the call. However, an application may install a specific blocking hook by calling WSASetBlockingHook().

This allows easy portability of applications that depend on the blocking hook behavior.

Return Value

The return value is a pointer to the procedure-instance of the previously installed blocking function. The application or library that calls the WSASetBlockingHook () function should save this return value so that it can be restored if necessary. (If "nesting" is not important, the application may simply discard the value returned by WSASetBlockingHook() and eventually use WSAUnhookBlockingHook() to restore the default mechanism.) If the operation fails, a NULL pointer is returned, and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes

WSANOTINITIALISED

WSAENETDOWN

WSAEINPROGRESS

A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
A blocking Windows Sockets operation is in progress.

See Also

WSAUnhookBlockingHook()

4.3.14 WSASetLastError()

Description	Set the error code which can be retrieved by WSAGetLastError().
	#include <winsock.h> void PASCAL FAR WSASetLastError ( int iError );
Remarks	This function allows an application to set the error code to be returned by a subsequent WSAGetLastError() call for the current thread. Note that any subsequent Windows Sockets routine called by the application will override the error code as set by this routine.

iError

Specifies the error code to be returned by a subsequent WSAGetLastError() call.

Notes For Windows Sockets

Suppliers	In a Win32 environment, this function will invoke SetLastError().
Return Value	None.

Error Codes

WSANOTINITIALISED

A successful WSAStartup() must occur before using this API.

See Also

WSAGetLastError()

4.3.15 WSAStartup()

Description

	#include <winsock.h>
	int PASCAL FAR WSAStartup ( WORD wVersionRequested, LPWSADATA lpWSAData );
wVersionRequested	The highest version of Windows Sockets API support that the caller can use. The high order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.
lpWSAData	A pointer to the WSADATA data structure that is to receive details of the Windows Sockets implementation.
Remarks	This function MUST be the first Windows Sockets function called by an application or DLL. It allows an application or DLL to specify the version of Windows Sockets API required and to retrieve details of the specific Windows Sockets implementation. The application or DLL may only issue further Windows Sockets API functions after a successful WSAStartup() invocation.

In order to support future Windows Sockets implementations and applications which may have functionality differences from Windows Sockets 1.1, a negotiation takes place in WSAStartup(). The caller of WSAStartup() and the Windows Sockets DLL indicate to each other the highest version that they can support, and each confirms that the other's highest version is acceptable. Upon entry to WSAStartup(), the Windows Sockets DLL examines the version requested by the application. If this version is higher than the lowest version supported by the DLL, the call succeeds and the DLL returns in wHighVersion the highest version it supports and in wVersion the minimum of its high version and wVersionRequested. The Windows Sockets DLL then assumes that the application will use wVersion. If the wVersion field of the WSADATA structure is unacceptable to the caller, it should call WSACleanup() and either search for another Windows Sockets DLL or fail to initialize.

This negotiation allows both a Windows Sockets DLL and a Windows Sockets application to support a range of Windows Sockets versions. An application can successfully utilize a Windows Sockets DLL if there is any overlap in the version ranges. The following chart gives examples of how WSAStartup() works in conjunction with different application and Windows Sockets DLL versions:

App version	DLL Version	wVersionRequested	wVersion	wHighVersion	End Result
1.1	1.1	1.1	1.1	1.1	use 1.1
1.0 1.1	1.0	1.1	1.0	1.0	use 1.0
1.0	1.0 1.1	1.0	1.0	1.1	use 1.0
1.1	1.0 1.1	1.1	1.1	1.1	use 1.1
1.1	1.0	1.1	1.0	1.0	Application fails
1.0	1.1	1.0	---	---	WSAVERNOTSUPPORTED
1.0 1.1	1.0 1.1	1.1	1.1	1.1	use 1.1
1.1 2.0	1.1	2.0	1.1	1.1	use 1.1
2.0	1.1	2.0	1.1	1.1	Application fails

The following code fragment demonstrates how an application which supports only version 1.1 of Windows Sockets makes a WSAStartup() call:

WORD wVersionRequested;
WSADATA wsaData;
int err;

wVersionRequested = MAKEWORD( 1, 1 );

err = WSAStartup( wVersionRequested, &wsaData );
if ( err != 0 ) {
    /* Tell the user that we couldn't find a useable */
    /* winsock.dll.                                  */
    return;
}

/* Confirm that the Windows Sockets DLL supports 1.1.*/
/* Note that if the DLL supports versions greater    */
/* than 1.1 in addition to 1.1, it will still return */
/* 1.1 in wVersion since that is the version we      */
/* requested.                                        */

if ( LOBYTE( wsaData.wVersion ) != 1 ||
         HIBYTE( wsaData.wVersion ) != 1 ) {
    /* Tell the user that we couldn't find a useable */
    /* winsock.dll.                                  */
    WSACleanup( );
    return;   
}

/* The Windows Sockets DLL is acceptable.  Proceed.  */

And this code fragment demonstrates how a Windows Sockets DLL which supports only version 1.1 performs the WSAStartup() negotiation:

/* Make sure that the version requested is >= 1.1.   */
/* The low byte is the major version and the high    */
/* byte is the minor version.                        */

if ( LOBYTE( wVersionRequested ) < 1 ||
     ( LOBYTE( wVersionRequested ) == 1 &&
       HIBYTE( wVersionRequested ) < 1 ) {
    return WSAVERNOTSUPPORTED;
}

/* Since we only support 1.1, set both wVersion and  */
/* wHighVersion to 1.1.                              */

lpWsaData->wVersion = MAKEWORD( 1, 1 );
lpWsaData->wHighVersion = MAKEWORD( 1, 1 );

Once an application or DLL has made a successful WSAStartup() call, it may proceed to make other Windows Sockets API calls as needed. When it has finished using the services of the Windows Sockets DLL, the application or DLL must call WSACleanup() in order to allow the Windows Sockets DLL to free any resources for the application.

Details of the actual Windows Sockets implementation are described in the WSAData structure defined as follows:

struct WSAData {
    WORD            wVersion;
    WORD            wHighVersion;
    char             szDescription[WSADESCRIPTION_LEN+1];
    char            szSystemStatus[WSASYSSTATUS_LEN+1];
    unsigned short    iMaxSockets;
    unsigned short    iMaxUdpDg;
    char FAR *        lpVendorInfo;
};

The members of this structure are:

Element	Usage
wVersion	The version of the Windows Sockets specification that the Windows Sockets DLL expects the caller to use.
wHighVersion	The highest version of the Windows Sockets specification that this DLL can support (also encoded as above). Normally this will be the same as wVersion.
szDescription	A null-terminated ASCII string into which the Windows Sockets DLL copies a description of the Windows Sockets implementation, including vendor identification. The text (up to 256 characters in length) may contain any characters, but vendors are cautioned against including control and formatting characters: the most likely use that an application will put this to is to display it (possibly truncated) in a status message.
szSystemStatus	A null-terminated ASCII string into which the Windows Sockets DLL copies relevant status or configuration information. The Windows Sockets DLL should use this field only if the information might be useful to the user or support staff: it should not be considered as an extension of the szDescription field.
iMaxSockets	The maximum number of sockets which a single process can potentially open. A Windows Sockets implementation may provide a global pool of sockets for allocation to any process; alternatively it may allocate per-process resources for sockets. The number may well reflect the way in which the Windows Sockets DLL or the networking software was configured. Application writers may use this number as a crude indication of whether the Windows Sockets implementation is usable by the application. For example, an X Windows server might check iMaxSockets when first started: if it is less than 8, the application would display an error message instructing the user to reconfigure the networking software. (This is a situation in which the szSystemStatus text might be used.) Obviously there is no guarantee that a particular application can actually allocate iMaxSockets sockets, since there may be other Windows Sockets applications in use.
iMaxUdpDg	The size in bytes of the largest UDP datagram that can be sent or received by a Windows Sockets application. If the implementation imposes no limit, iMaxUdpDg is zero. In many implementations of Berkeley sockets, there is an implicit limit of 8192 bytes on UDP datagrams (which are fragmented if necessary). A Windows Sockets implementation may impose a limit based, for instance, on the allocation of fragment reassembly buffers. The minimum value of iMaxUdpDg for a compliant Windows Sockets implementation is 512. Note that regardless of the value of iMaxUdpDg, it is inadvisable to attempt to send a broadcast datagram which is larger than the Maximum Transmission Unit (MTU) for the network. (The Windows Sockets API does not provide a mechanism to discover the MTU, but it must be no less than 512 bytes.)
lpVendorInfo	A far pointer to a vendor-specific data structure. The definition of this structure (if supplied) is beyond the scope of this specification.

An application or DLL may call WSAStartup() more than once if it needs to obtain the WSAData structure information more than once. However, the wVersionRequired parameter is assumed to be the same on all calls to WSAStartup(); that is, an application or DLL cannot change the version of Windows Sockets it expects after the initial call to WSAStartup().

There must be one WSACleanup() call corresponding to every WSAStartup() call to allow third-party DLLs to make use of a Windows Sockets DLL on behalf of an application. This means, for example, that if an application calls WSAStartup() three times, it must call WSACleanup() three times. The first two calls to WSACleanup() do nothing except decrement an internal counter; the final WSACleanup() call for the task does all necessary resource deallocation for the task.

Return Value

WSAStartup() returns zero if successful. Otherwise it returns one of the error codes listed below. Note that the normal mechanism whereby the application calls WSAGetLastError() to determine the error code cannot be used, since the Windows Sockets DLL may not have established the client data area where the "last error" information is stored.

Notes For Windows Sockets

Suppliers

Each Windows Sockets application MUST make a WSAStartup() call before issuing any other Windows Sockets API calls. This function can thus be utilized for initialization purposes.
Further issues are discussed in the notes for WSACleanup().

Error Codes

WSASYSNOTREADY

WSAVERNOTSUPPORTED

WSAEINVAL

Indicates that the underlying network subsystem is not ready for network communication.
The version of Windows Sockets API support requested is not provided by this particular Windows Sockets implementation.
The Windows Sockets version specified by the application is not supported by this DLL.

See Also

send(), sendto(), WSACleanup()

4.3.16 WSAUnhookBlockingHook()

Description	Restore the default blocking hook function.
	#include <winsock.h>
	int PASCAL FAR WSAUnhookBlockingHook ( void );
Remarks	This function removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism.

WSAUnhookBlockingHook() will always install the default mechanism, not the previous mechanism. If an application wish to nest blocking hooks - i.e. to establish a temporary blocking hook function and then revert to the previous mechanism (whether the default or one established by an earlier WSASetBlockingHook()) - it must save and restore the value returned by WSASetBlockingHook(); it cannot use WSAUnhookBlockingHook().

In multithreaded versions of Windows such as Windows NT, there is no default blocking hook. Calling WSAUnhookBlockingHook() disables any blocking hook installed by the application and any blocking calls made block the thread which made the call.

Return Value

The return value is 0 if the operation was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().

Error Codes

WSANOTINITIALISED

A successful WSAStartup() must occur before using this API.

See Also

WSASetBlockingHook()

7 Note that there is a timing window between the accept() call and the call to WSAAsyncSelect() to change the events or wMsg. An application which desires a different wMsg for the listening and accept()'ed sockets should ask for only FD_ACCEPT events on the listening socket, then set appropriate events after the accept(). Since FD_ACCEPT is never sent for a connected socket and FD_READ, FD_WRITE, FD_OOB, and FD_CLOSE are never sent for listening sockets, this will not impose difficulties.