WSAIoctl

This function controls the mode of a socket.

At a Glance

Syntax

int WSAIoctl(SOCKET s,DWORD dwIoContorlCode,LPVOID lpvInBuffer,DWORD cbInBuffer,LPVOID lpvOutBuffer,DWORD cbOutBuffer,LPDWORD lpcbBytesReturned,LPWSAOVERLAPPED lpOverlapped,LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionROUTINE);

Parameters

s

[in] Descriptor that identifies a socket.

dwIoControlCode

[in] Specifies the control code of operation to perform.

lpvInBuffer

[in] Long void pointer to the input buffer.

cbInBuffer

[in] Number that indicates the size of the input buffer.

lpvOutBuffer

[out] Long void pointer to the output buffer.

cbOutBuffer

[in] Number that indicates the size of the output buffer.

lpcbBytesReturned

[out] For secure sockets, long pointer to the number of bytes returned in the output buffer.

lpOverlapped

[in] Unsupported; set to NULL.

lpCompletionRoutine

[in] Unsupported; set to NULL.

Return Values

Zero indicates success. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The WSAIoctl function is used to set or retrieve operating parameters associated with the socket, the transport protocol, or the communications subsystem.

It is possible to adopt an encoding scheme that preserves the currently defined ioctlsocket opcodes while providing a convenient way to partition the opcode identifier space in as much as the dwIoControlCode parameter is now a 32-bit entity. The dwIoControlCode parameter is designed to allow for protocol and vendor independence when adding new control codes while retaining backward compatibility with the Windows Sockets 1.1 and Unix control codes. The dwIoControlCode parameter has the following form:

I is set if the input buffer is valid for the code, as with IOC_IN.

O is set if the output buffer is valid for the code, as with IOC_OUT. Codes with both input and output parameters set both I and O.

V is set if there are no parameters for the code, as with IOC_VOID.

T is a two-bit quantity that defines the type of ioctl. The following values are defined:

0 – The ioctl is a standard Unix ioctl code, as with FIONREAD and FIONBIO.

1 – Not currently supported in Windows CE.

2 – The ioctl applies only to a specific address family.

3 – The ioctl applies only to a specific vendor's provider. This type allows companies to be assigned a vendor number that appears in the Vendor/Address family field. Then, the vendor can define new ioctls specific to that vendor without having to register the ioctl with a clearinghouse, thereby providing vendor flexibility and privacy.

Vendor/Address family – An 11-bit quantity that defines the vendor who owns the code (if T == 3) or that contains the address family to which the code applies (if T == 2). If this is a Unix ioctl code (T == 0) then this field has the same value as the code on Unix.

Code – The 16-bit quantity that contains the specific ioctl code for the operation.

The following Unix ioctl codes (commands) are supported:

FIONBIO

Enable or disable nonblocking mode on socket s. lpvInBuffer points at an unsigned long, which is nonzero if nonblocking mode is to be enabled and zero if it is to be disabled. When a socket is created, it operates in blocking mode (that is, nonblocking mode is disabled). This is consistent with BSD sockets.

FIONREAD

Determine the amount of data that can be read atomically from socket s. lpvOutBuffer points at an unsigned long in which WSAIoctl stores the result. If s is stream oriented (for example, type SOCK_STREAM), FIONREAD returns the total amount of data that can be read in a single receive operation; this is normally the same as the total amount of data queued on the socket (since data stream is byte-oriented, this is not guaranteed). If s is message oriented (for example, type SOCK_DGRAM), FIONREAD returns the size of the first datagram (message) queued on the socket.

SIOCATMARK

Determine whether or not all out-of-band data has been read. This applies only to a socket of stream-style (for example, type SOCK_STREAM) that has been configured for inline reception of any out-of-band data (SO_OOBINLINE). If no out-of-band data is waiting to be read, the operation returns TRUE. Otherwise, it returns FALSE, and the next receive operation performed on the socket will retrieve some or all of the data preceding the "mark"; the application should use the SIOCATMARK operation to determine whether any remains. If there is any normal data preceding the "urgent" (out of band) data, it will be received in order. (Note that receive operations will never mix out-of-band and normal data in the same call.) lpvOutBuffer points at a BOOL in which WSAIoctl stores the result.

In addition to the ioctlsocket control codes (FIONBIO, SIOCATMARK, FIONREAD), the dwIoControlCode parameter may also assume the following SSL-specific control flags:

SO_SSL_GET_CAPABILITIES

Retrieves a set of flags describing the WinSock security provider’s capabilities. The output buffer must be a pointer to a DWORD bit field. At present, only the SSL_CAP_CLIENT flag is defined.

SO_SSL_GET_FLAGS

Retrieves s-channel specific flags associated with a particular socket. The output buffer must be a pointer to a DWORD bit field. See SO_SSL_SET_FLAGS for details on valid flags.

SO_SSL_SET_FLAGS

Sets the sockets’ current s-channel-specific flag values. The input buffer must be a pointer to a DWORD bit field. Currently, only the SSL_FLAG_DEFER_HANDSHAKE flag is defined to allow the application to send and receive plain text data before switching to cipher text. It is required for setting up communication through proxy servers.

Normally the WinSock security provider performs the secure handshake in the WinSock connect API. However, if this flag is set, the handshake is deferred until the application issues the SO_SSL_PERFORM_HANDSHAKE control code. After the handshaking, this flag is reset.

SO_SSL_GET_PROTOCOLS

Retrieves a list of protocols that the provider currently supports on this socket. The output buffer must be a pointer to a SSLPROTOCOLS structure as described below:

typedef struct _SSLPROTOCOL {
DWORD dwProtocol;
DWORD dwVersion;
DWORD dwFlags;
} SSLPROTOCOL, *LPSSLPROTOCOL;

typedef struct _SSLPROTOCOLS {
DWORD dwCount;
SSLPROTOCOL ProtocolList[1];
} SSLPROTOCOLS, FAR *LPSSLPROTOCOLS;

Valid protocols include SSL_PROTOCOL_SSL2, SSL_PROTOCOL_SSL3, and SSL_PROTOCOL_PCT1.

SO_SSL_SET_PROTOCOLS

Specifies a list of protocols the provider is to support on this socket. The input buffer must be a pointer to SSLPROTOCOLS structure described above.

SO_SSL_SET_VALIDATE_CERT_HOOK

Sets the pointer to the socket’s certificate validation hook. It is used to specify the callback function invoked by the WinSock security provider when a set of credentials is received from the remote party. The input buffer must be a pointer to the SSLVALIDEATECERTHOOK structure, described below:

typedef struct {
SSLVALIDATECERTFUNC HookFunc;
LPVOID pvArg;
} SSLVALIDATEPROTOCOLCERTHOOK, *PSSLVALIDATECERTHOOK;

where HookFunc is a pointer to the certificate validation callback function (see “Certificate Validation Callback” below). pvArg is a pointer to application specific data and may be used by the application for any purpose.

SO_SSL_PERFORM_HANDSHAKE

Initiates the secure handshake sequence on a connected socket where the SSL_FLAG_DEFER_HANDSHAKE flag has been set prior to the connection. Data buffers are not required, but the SSL_FLAG_DEFER_HANDSHAKE flag will be reset.

Certificate Validation Callback

The WinSock security provider invokes the certificate validation callback when the remote party receives a certificate for server authentication. All the client applications must implement the callback function to ensure that the certificate should meet the following minimum requirements:

• The certificate has not expired;
  
  
• The identity contained within the certificate matches that of the remote party.

The certificate validation callback function is of the following type:

typedef int (CALLBACK *SSLVALIDATECERTFUNC){
DWORD dwType, // in
LPVOID pvArg, // in
DWORD dwChainLen, // in
LPBLOB pCertChain, // in
DWORD dwFlags // in
};

The parameters are defined in the following table.

dwType

Specifies the type of data pointed to be pCertChain. This must be SSL_CERT_X59 to specify that pCertChain be a pointer to an X509 style certificate.

PvArg

An application-defined context passed into the SSLVALIDATECERTHOOK structure.

DwChainLen

The number of certificates pointed to by pCertChain. In Windows CE this will always be one.

PCertChain

Pointer to the remote party’s certificate.

DwFlags

To be designed to indicate that the certificate issuer list has been checked with the list of known certificate authorities and that the certificate is either trusted or not. This is required since not all the certificate chain is passed to the application.

The application-defined callback function will typically return one of the following error values:

If the output buffer is not large enough to return all the data, WSAIoctl returns SOCKET_ERROR. The value for WSAGetLastError is WSAEFAULT and lpcbReturned contains the number of bytes required to successfully complete the operation.