IOCTLSOCKET and WSAIOCTL

The socket ioctl functions are used to control the behavior of I/O upon the socket, as well as obtain information about I/O pending on that socket. The first function, ioctlsocket, originated in the Winsock 1 specification and is declared as

 int ioctlsocket ( SOCKET s, long cmd, u_long FAR *argp ); 

The parameter s is the socket descriptor to act upon, while cmd is a predefined flag for the I/O control command to execute. The last parameter, argp, is a pointer to a variable specific to the given command. When each command is described, the type of the required variable is given. Winsock 2 introduced a new ioctl function that adds quite a few new options. First, it breaks the single argp parameter into a set of input parameters for values passed into the function and a set of output parameters used to return data from the call. Additionally, the function call can use overlapped I/O. This function is WSAIoctl, which is defined as

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

The first two parameters are the same as those in ioctlsocket. The second two parameters, lpvInBuffer and cbInBuffer, describe the input parameters. The lpvInBuffer parameter is a pointer to the value passed in, while cbInBuffer is the size of that data in bytes. Likewise, lpvOutBuffer and cbOutBuffer are used for any data returned from the call. The lpvOutBuffer parameter points to a data buffer in which any information returned is placed. The cbOutBuffer parameter is the size in bytes of the buffer passed in as lpvOutBuffer. Note that some calls might use only input or output parameters, while others will use both. The seventh parameter, lpcbBytesReturned, is the number of bytes actually returned. The last two parameters, lpOverlapped and lpCompletionRoutine, are used when calling this function with overlapped I/O. Consult Chapter 8 for detailed information on using overlapped I/O.

Standard Ioctl Commands

These three ioctl commands are the most common and are carryovers from the Unix world. They are available on all Win32 platforms. Also, these three commands can be called using either ioctlsocket or WSAIoctl.

FIONBIO

Which Function?	Input	Output	Winsock Version	Description
ioctlsocket/WSAIoctl	unsigned	None	1+	Puts socket in nonblocking mode

This command enables or disables nonblocking mode on socket s. By default, all sockets are blocking sockets upon creation. When you call ioctlsocket with the FIONBIO ioctl command, set argp to pass a pointer to an unsigned long integer whose value is nonzero if nonblocking mode is to be enabled. The value 0 places the socket in blocking mode. If you use WSAIoctl instead, simply pass the unsigned long integer in as the lpvInBuffer parameter.

Calling the WSAAsyncSelect or WSAEventSelect function automatically sets a socket to nonblocking mode. If either of these functions has been called, any attempt to set the socket back to blocking mode fails with WSAEINVAL. To set the socket back to blocking mode, an application must first disable WSAAsyncSelect by calling WSAAsyncSelect with the lEvent parameter equal to 0, or disable WSAEventSelect by calling WSAEventSelect with the lNetworkEvents parameter equal to 0.

FIONREAD

Which Function?	Input	Output	Winsock Version	Description
Both	None	unsigned long	1+	Returns the amount of data to be read on the socket

This command determines the amount of data that can be read atomically from the socket. For ioctlsocket, the argp value returns with an unsigned integer that will contain the number of bytes to be read. When using WSAIoctl, the unsigned integer is returned in lpvOutBuffer. If socket s is stream-oriented (SOCK_STREAM), FIONREAD returns the total amount of data that can be read in a single receive call. Remember that using this or any other message-peeking mechanism is not always guaranteed to return the correct amount. When this ioctl command is used on a datagram socket (SOCK_DGRAM), the return value is the size of the first message queued on the socket.

SIOCATMARK

Which Function?	Input	Output	Winsock Version	Description
Both	None	BOOL	1+	Determines whether out-of-band data has been read

When a socket has been configured to receive out-of-band (OOB) data and has been set to receive this OOB data in line (by setting the SO_OOBINLINE socket option), this ioctl command returns a Boolean value indicating TRUE if the OOB data is to be read next. Otherwise, FALSE is returned and the next receive operation returns all or some of the data that precedes the OOB data. For ioctlsocket, argp returns with a pointer to a Boolean variable, while for WSAIoctl, the pointer to the Boolean variable returns in lpvOutBuffer. Remember that a receive call will never mix OOB data and normal data in the same call. Refer back to Chapter 7 for more information on OOB data.

Other Ioctl Commands

These ioctl commands are specific to Winsock 2 except for those dealing with SSL, which are available only on Windows CE. If you examine the Winsock 2 headers, you might actually see other ioctl commands declared; however, the ioctls listed in this section are the only ones that are meaningful or available to a user's application. Additionally, as you will see, not all ioctl commands work on all (or any) Win32 platforms, but of course this could change with operating system updates. For Winsock 2, a majority of these commands are defined in Winsock2.h. Some of the newer, Windows 2000-specific, ioctls are defined in Mstcpip.h.

SIO_ENABLE_CIRCULAR_QUEUEING

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	BOOL	BOOL	2+	If the incoming buffer queue overflows, discard oldest message first.

This ioctl command controls how the underlying service provider handles incoming datagram messages when the queues are full. By default, when the incoming queue is full, any datagram messages subsequently received are dropped. When this option is set to TRUE, it indicates that the newly arrived messages should never be dropped as a result of buffer overflow; instead, the oldest message in the queue should be discarded in order to make room for the newly arrived message. This command is valid only for sockets associated with unreliable, message-oriented, protocols. If this ioctl command is used on a socket of another type (such as a stream-oriented protocol socket), or if the service provider doesn't support the command, the error WSAENOPROTOOPT is returned. This option is supported only on Windows NT and Windows 2000.

This ioctl command can be used either to set circular queuing on or off or to query the current state of the option. When you are setting the option, only the input parameters need to be used. When you are querying the current value of the option, only the output BOOL parameter needs to be supplied.

SIO_FIND_ROUTE

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	SOCKADDR	BOOL	2+	Verifies that a route to the given address exists

This ioctl command is used to check whether a particular address can be reached via the network. The lpvInBuffer parameter points to a SOCKADDR structure for the given protocol. If the address already exists in the local cache, it is invalidated. For IPX, this call initiates an IPX GetLocalTarget call that queries the network for the given remote address. Unfortunately, the Microsoft provider for current Win32 platforms does not implement this ioctl command.

SIO_FLUSH

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	None	None	2+	Determines whether OOB data has been read

This ioctl command discards the current contents of the sending queue associated with the given socket. There are no input or output parameters for this option. Currently only Windows 2000 and Windows NT 4 Service Pack 4 implement this option.

SIO_GET_BROADCAST_ADDRESS

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	None	SOCKADDR	2+	Returns a broadcast address for the address family of the socket

This ioctl command returns a SOCKADDR structure (via lpvOutBuffer) that contains the broadcast address for the address family of socket s that can be used in sendto or WSASendTo. This ioctl works only on Windows NT and Windows 2000. Windows 95 and Windows 98 return WSAEINVAL.

SIO_GET_EXTENSION_FUNCTION_POINTER

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	GUID	function pointer?	2+	Retrieves a function pointer specific to underlying provider

This ioctl command is used to obtain functions that are provider-specific but are not part of the Winsock specification. If a provider chooses, it can make functions available to programmers through this ioctl command by assigning each function a GUID. Then an application can obtain a pointer to this function by using the SIO_GET_EXTENSION_FUNCTION_POINTER ioctl. The header file Mswsock.h defines those Winsock functions that Microsoft has added, including their GUIDs. For example, to query whether the installed Winsock provider supports the TransmitFile function, you can query the provider by using its GUID, which is given by the following define:

 #define WSAID_TRANSMITFILE \ {0xb5367df0,0xcbac,0x11cf,{0x95,0xca,0x00,0x80,0x5f,0x48,0xa1,0x92}} 

Once you obtain the function pointer for an extension function such as TransmitFile, you can call it directly without having to link your application to the Mswsock.lib library. This will actually reduce one intermediate function call that is made in Mswsock.lib.

You can look through Mswsock.h for other Microsoft-specific extensions that have these GUIDs defined for them. This ioctl command is an important part of developing a layered service provider. See Chapter 14 for more details of the service provider interface.

SIO_CHK_QOS

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	DWORD	DWORD	2+	Sets the QOS attributes for the given socket

This ioctl command can be used to check the status of six states within QOS and is currently supported only on Windows 2000. Six different flags correspond to these states: ALLOWED_TO_SEND_DATA, ABLE_TO_RECV_RSVP, LINE_RATE, LOCAL_TRAFFIC_CONTROL, LOCAL_QOSABILITY, and END_TO_END_QOSABILITY.

The first flag, ALLOWED_TO_SEND_DATA, is used once QOS levels are set on a socket using SIO_SET_QOS but before any RSVP reservation request (RESV) message has been received. Receiving a RESV message indicates that the desired bandwidth requirements have been allocated to your flow. Prior to receiving the RESV message, the flow corresponding to the socket is given only best-effort service. The RSVP protocol and reservation of network resources are covered in greater detail in Chapter 12. Use the ALLOWED_TO_SEND_DATA flag to see whether the current best-effort service is sufficient for the levels of QOS requested by SIO_SET_QOS. The return value will be either 1—meaning that the current best-effort bandwidth is sufficient—or 0, meaning that the bandwidth cannot accommodate the requested levels. If the ALLOWED_TO_SEND_DATA flag returns 0, the sending application should wait until a RESV message is received before sending data.

The second flag, ABLE_TO_RECV_RSVP, indicates whether the host is able to receive and process RSVP messages on the interface that the given socket is bound to. The return value is either 1 or 0, corresponding to whether RSVP messages can or cannot be received, respectively.

The next flag, LINE_RATE, returns the best-effort line rate in kilobits per second (kbps). If the line rate is not known, the value INFO_NOT_AVAILABLE is returned.

The last three flags indicate whether certain capabilities exist on the local machine or the network. All three options return 1 to indicate the option is supported, 0 if it is not supported, or INFO_NOT_AVAILABLE if there is no way to check. LOCAL_TRAFFIC_CONTROL is used to determine whether the Traffic Control component is installed and available on the machine. LOCAL_QOSABILITY determines whether QOS is supported on the local machine. Finally END_TO_END_QOSABILITY indicates whether the local network is QOS-enabled.

SIO_GET_QOS

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	None	QOS	2+	Returns the QOS structure associated with the socket

This ioctl command retrieves the QOS structure associated with the socket. The supplied buffer must be large enough to contain the whole structure, which in some cases is larger than sizeof(QOS), as the structure might contain provider-specific information. For more information on QOS, see Chapter 12. If this ioctl command is used on a socket whose address family does not support QOS, the error WSAENOPROTOOPT is returned. This option and SIO_SET_QOS are available only on platforms that provide a QOS-capable transport, such as Windows 98 and Windows 2000.

SIO_SET_QOS

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	QOS	None	2+	Sets the QOS attributes for the given socket

This ioctl command is the companion to SIO_GET_QOS. The input parameter for this call is a QOS structure that defines the bandwidth requirements for this socket. This call does not return any output values. See Chapter 12 for more information about QOS. This option and SIO_GET_QOS are available only on those platforms that provide a QOS-capable transport, such as Windows 98 and Windows 2000.

SIO_MULTIPOINT_LOOPBACK

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	BOOL	BOOL	2+	Sets/gets whether multicast data will be looped back to the socket

When sending multicast data, the default behavior is to have any data sent to the multicast group posted as incoming data on the socket's receive queue. Of course, this loopback is in effect only if the socket is also a member of the multicast group that it is sending to. Currently this loopback behavior is seen only in IP multicasting and is not present in ATM multicasting. To disable this loopback, pass a Boolean variable with the value FALSE into the input parameter lpvInBuffer. To obtain the current value of this option, leave the input value as NULL and supply a Boolean variable as the output parameter.

SIO_MULTICAST_SCOPE

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	int	int	2+	Gets/sets the time-to-live (TTL) value for multicast data

This ioctl command controls the lifetime, or scope, of multicast data. The scope is the number of routed network segments that data is allowed to traverse; by default, the value is only 1. When a multicast packet hits a router, the TTL value is decremented by 1. Once the TTL reaches 0, the packet is discarded. To set the value, pass an integer with the desired TTL as lpvInBuffer; otherwise, to simply obtain the current TTL value, call WSAIoctl with the lpvOutBuffer pointing to an integer.

SIO_KEEPALIVE_VALS

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	tcp_keepalive	tcp_keepalive	2+	Sets the TCP keepalive active on a per-connection basis

This ioctl command allows setting the TCP keepalive active on a per-connection basis and allows you to specify the keepalive interval. The socket option SO_KEEPALIVE also enables TCP keepalives, but the interval on which they are sent is set in the Registry. Changing the Registry value changes the keepalive interval for all processes on the machine. This ioctl command allows you to set the interval on a per-socket basis. To set the keepalive active on the given connected socket, initialize a tcp_keepalive structure and pass it as the input buffer. The structure is defined as follows:

 struct tcp_keepalive { u_long onoff; u_long keepalivetime; u_long keepaliveinterval; } 

The meaning of the structure fields keepalivetime and keepaliveinterval are identical to the Registry values discussed in the SO_KEEPALIVE option presented earlier in this chapter. Once a keepalive is set, you can query for the current keepalive values by calling WSAIoctl with the SIO_KEEPALIVE_VALS ioctl command and supplying a tcp_keepalive structure as the output buffer. This ioctl command is available on Windows 2000 only.

SIO_RCVALL

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	unsigned int	None	2+	Receives all packets on the network

Using this ioctl command with the value TRUE allows the given socket to receive all IP packets on the network. This requires that the socket handle be passed to WSAIoctl and that the socket be of address family AF_INET, socket type SOCK_RAW, and protocol IPPROTO_IP. Additionally, the socket must be bound to an explicit local interface. That is, you cannot bind to INADDR_ANY. Once the socket is bound and the ioctl is set, calls to recv/WSARecv return IP datagrams. Keep in mind that these are datagrams—you must supply a sufficiently large buffer. Because the total length field of the IP header is a 16-bit quantity, the maximum theoretical limit is 65,535 bytes; however, in practice the maximum transmission unit (MTU) of networks is much lower. Using this ioctl command requires Administrator privileges on the local machine. Additionally, this ioctl command is available on Windows 2000 only. A sample application on the companion CD, Rcvall.c, illustrates using this and the other two SIO_RCVALL ioctl commands.

SIO_RCVALL_MCAST

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	unsigned int	None	2+	Receives all multicast packets on the network

This ioctl command is similar to the SIO_RCVALL command described earlier. The same usage rules mentioned for SIO_RCVALL also apply here except that the socket passed to WSAIoctl should be created with the protocol equal to IPPROTO_IGMP. The one difference is that only multicast IP traffic is returned, as opposed to all IP packets. This means that only IP packets destined for addresses in the range 224.0.0.0 through 239.255.255.255 are returned. This ioctl command is available on Windows 2000 only.

SIO_RCVALL_IGMPMCAST

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	unsigned int	None	2+	Receives all IGMP packets on the network

Again, this ioctl command is the same as SIO_RCVALL, except that the socket passed into WSAIoctl should be created with the protocol equal to IPPROTO_IGMP. Setting this option returns only IGMP packets. See the SIO_RCVALL entry for instructions on how to use this option. This ioctl is available on Windows 2000 only.

SIO_ROUTING_INTERFACE_QUERY

Which Function?	Input	Output	Winsock Version	Description
Both	SOCKADDR	None	2+	Determines whether OOB data has been read

This ioctl command allows you to find the address of the local interface that should be used to send data to a remote machine. The address of the remote machine should be supplied in the form of a SOCKADDR structure as the lpvInBuffer parameter. Additionally, a sufficiently large buffer needs to be supplied as the lpvOutBuffer, which will contain an array of one or more SOCKADDR structures describing the local interface(s) that can be used. This command can be used for either unicast or multicast endpoints, and the interface returned from this call can be used in a subsequent call to bind.

The Windows 2000 plug-and-play capabilities are the motivation for having an ioctl like this. The user can insert or remove a PCMCIA network card, affecting which interfaces an application can use. A well-written application on Windows 2000 should take this into account.

Therefore, applications cannot rely on the information returned by SIO_ROUTING_INTERFACE_QUERY to be persistent. To handle this situation, you should also use the SIO_ROUTING_INTERFACE_CHANGE ioctl command, which notifies your application when the interfaces change. Once this occurs, call SIO_ROUTING_INTERFACE_QUERY once again to obtain the latest information.

SIO_ROUTING_INTERFACE_CHANGE

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	SOCKADDR	None	2+	Sends notification when an interface to an endpoint has changed

Using this ioctl command indicates that you want to be notified of any change in the local routing interface that is used to access the specified remote address. When you use this command, a SOCKADDR structure to the remote address in question is submitted in the input buffer and no data is returned upon successful completion. However, if the interface to that route changes in some way, the application will be notified, at which point the application can call SIO_ROUTING_INTERFACE_QUERY to determine which interface to use as a result.

There are several ways to make a call to this command. If the socket is blocking, the WSAIoctl call will not complete until some point at which the interface changes. If the socket is in nonblocking mode, the error WSAEWOULDBLOCK is returned. Then the application can wait for routing-change events through either WSAEventSelect or WSAAsyncSelect, with the FD_ROUTING_INTERFACE_CHANGE flag set in the network event bitmask. Overlapped I/O can also be used to make the call. With this method, you supply an event handle in the WSAOVERLAPPED structure, which is signaled upon a routing change.

The address specified in the input SOCKADDR structure can be a specific address, or you can use the wildcard INADDR_ANY, indicating that you want to be notified of any routing changes. Note that because routing information remains fairly static, providers have the option of ignoring the information supplied by the application in the input buffer and simply sending a notification upon any interface change. As a result, it is probably a good idea to register for notification on any change and simply call SIO_ROUTING_INTERFACE_QUERY to see whether the change affects your application.

SIO_ADDRESS_LIST_QUERY

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	None	SOCKET_ADDRESS_LIST	2+	Returns a list of interfaces to which the socket can bind

This ioctl is used to obtain a list of local transport addresses matching the socket's protocol family that the application can bind to. The output buffer is a SOCKET_ADDRESS_LIST structure, defined as

 typedef struct _SOCKET_ADDRESS_LIST { INT iAddressCount;   SOCKET_ADDRESS Address[1]; } SOCKET_ADDRESS_LIST, FAR * LPSOCKET_ADDRESS_LIST; typedef struct _SOCKET_ADDRESS { LPSOCKADDR lpSockaddr; INT iSockaddrLength; } SOCKET_ADDRESS, *PSOCKET_ADDRESS, FAR * LPSOCKET_ADDRESS; 

The iAddressCount field returns the number of address structures in the list, while the Address field is an array of protocol family-specific addresses.

In Win32 plug-and-play environments, the number of valid addresses can change dynamically; therefore, applications cannot rely on the information returned from this ioctl command to remain constant. In order to take this into account, applications should first call SIO_ADDRESS_LIST_QUERY to obtain current interface information and then call SIO_ADDRESS_LIST_CHANGE to receive notification of future changes. If the address list changes, the application should again make a query.

If the supplied output buffer is not of sufficient size, WSAIoctl fails with WSAEFAULT, and the lcbBytesReturned parameter indicates the required buffer size.

SIO_ADDRESS_LIST_CHANGE

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	None	None	2+	Notifies when local interfaces change

An application can use this command to receive notification of changes in the list of local transport addresses of the given socket's protocol family to which the application can bind. No information is returned in the output parameters upon successful completion of the call.

There are several ways to make a call to this command. If the socket is blocking, the WSAIoctl call will not complete until some point at which the interface changes. If the socket is in nonblocking mode, the error WSAEWOULDBLOCK is returned. Then the application can wait for routing-change events through either WSAEventSelect or WSAAsyncSelect with the FD_ADDRESS_LIST_CHANGE flag set in the network event bitmask. Additionally, overlapped I/O can be used to make the call. With this method, you supply an event handle in the WSAOVERLAPPED structure, which is signaled upon a routing change.

SIO_GET_INTERFACE_LIST

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	None	INTERFACE_INFO []	2+	Returns a list of local interfaces

This ioctl is defined in Ws2tcpip.h. It is used to return information regarding each interface on the local machine. Nothing is required on input, but upon output, an array of INTERFACE_INFO structures is returned. The structures are defined as

 typedef struct _INTERFACE_INFO { u_long iiFlags; /* Interface flags */ sockaddr_gen iiAddress; /* Interface address */ sockaddr_gen iiBroadcastAddress; /* Broadcast address */ sockaddr_gen iiNetmask; /* Network mask */ } INTERFACE_INFO, FAR * LPINTERFACE_INFO; #define IFF_UP 0x00000001 /* Interface is up */ #define IFF_BROADCAST 0x00000002 /* Broadcast is supported */ #define IFF_LOOPBACK 0x00000004 /* This is loopback interface */ #define IFF_POINTTOPOINT 0x00000008 /* This is point-to-point interface*/ #define IFF_MULTICAST 0x00000010 /* Multicast is supported */ typedef union sockaddr_gen { struct sockaddr Address; struct sockaddr_in AddressIn; struct sockaddr_in6 AddressIn6; } sockaddr_gen; 

The iiFlags member returns a bitmask of flags indicating whether the interface is up (IFF_UP) as well as whether broadcast (IFF_BROADCAST) or multicast (IFF_MULTICAST) is supported. It also indicates whether the interface is loopback (IFF_LOOPBACK) or point-to-point (IFF_POINTTOPOINT). The other three fields contain the address of the interface, the broadcast address, and the corresponding netmask.

Secure Socket Layer Ioctl Commands

Secure Socket Layer (SSL) commands are supported only in Windows CE. Currently Windows 95 and 98, Windows NT, and Windows 2000 do not provide an SSL-capable provider. As these are available only in Windows CE, the only version of Winsock currently supported for these options is version 1.

SO_SSL_GET_CAPABILITIES

Which Function?	Input	Output	Description
WSAIoctl	None	DWORD	Returns the Winsock security provider's capabilities

This command retrieves a set of flags describing the Windows Sockets security provider's capabilities. The output buffer must be a pointer to a DWORD bit field. At present, only the flag SO_CAP_CLIENT is defined.

SO_SSL_GET_FLAGS

Which Function?	Input	Output	Description
WSAIoctl	None	DWORD	Returns s-channel-specific flags associated with socket

This command 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 below for details of valid flags.

SO_SSL_SET_FLAGS

Which Function?	Input	Output	Description
WSAIoctl	DWORD	None	Sets the socket's s-channel-specific flags

Here the input buffer must be a pointer to a DWORD bit field. Currently only the SSL_FLAG_DEFER_HANDSHAKE flag, which allows the application to send and receive plain text data before switching to cipher text, is defined. This flag is required for setting up communication through proxy servers.

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

SO_SSL_GET_PROTOCOLS

Which Function?	Input	Output	Description
WSAIoctl	None	SSLPROTOCOLS	Returns a list of protocols supported by the security provider

This command 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 here:

 typedef struct _SSLPROTOCOL { DWORD dwProtocol; DWORD dwVersion; DWORD dwFlags; } SSLPROTOCOL, *LPSSLPROTOCOL; typedef struct _SSLPROTOCOLS { DWORD dwCount; SSLPROTOCOL ProtocolList[1]; } SSLPROTOCOLS, FAR *LPSSLPROTOCOLS; 

Valid protocols for the dwProtocol field include SSL_PROTOCOL_SSL2, SSL_PROTOCOL_SSL3, and SSL_PROTOCOL_PCT1.

SO_SSL_SET_PROTOCOLS

Which Function?	Input	Output	Description
WSAIoctl	SSLPROTOCOLS	None	Sets a list of protocols that the underlying provider should support

This ioctl command specifies a list of protocols that the provider is to support on this socket. The input buffer must be a pointer to the SSLPROTOCOLS structure described above.

SO_SSL_SET_VALIDATE_CERT_HOOK

Which Function?	Input	Output	Description
WSAIoctl	SSLVALIDATECERTHOOK	None	Sets the validation function for accepting SSL certificates

This ioctl command sets the pointer to the socket's certificate validation hook. It is used to specify the callback function invoked by the Windows Sockets security provider when a set of credentials is received from the remote party. The input buffer must be a pointer to the SSLVALIDATECERTHOOK structure, described as follows:

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

The HookFunc field is a pointer to a certificate validation callback function; pvArg is a pointer to application-specific data and can be used by the application for any purpose.

SO_SSL_PERFORM_HANDSHAKE

Which Function?	Input	Output	Description
WSAIoctl	None	None	Initiates a secure handshake on a connected socket

This ioctl command initiates the secure handshake sequence on a connected socket in which 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.

ATM Ioctl Commands

These ioctl commands are specific to the ATM protocol family. They are fairly basic, dealing mainly with obtaining the number of ATM devices and ATM addresses of the local interfaces. See Chapter 6 for more detailed information about the addressing mechanisms for ATM.

SIO_GET_NUMBER_OF_ATM_DEVICES

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	None	DWORD	2+	Returns the number of ATM adapters

This ioctl command fills the output buffer pointed to by lpvOutBuffer with a DWORD containing the number of ATM devices in the system. Each specific device is identified by a unique ID, in the range 0 to the number returned by this ioctl command minus 1.

SIO_GET_ATM_ADDRESS

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	DWORD	ATM_ADDRESS	2+	Returns the ATM address for the given device

This ioctl command retrieves the local ATM address associated with the specified device. A device ID of type DWORD is specified in the input buffer for this ioctl command, and the output buffer pointed to by lpvOutBuffer will be filled with an ATM_ADDRESS structure containing a local ATM address suitable for use with bind.

SIO_ASSOCIATE_PVC

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	ATM_PVC_PARAMS	None	2+	Associates socket with a permanent virtual circuit

This ioctl command associates the socket with a permanent virtual circuit (PVC), as indicated in the input buffer, which contains the ATM_PVC_PARAMS structure. The socket should be of the AF_ATM address family. After successfully returning from this function, the application is able to start sending and receiving data as if the connection has been set up.

The ATM_PVC_PARAMS structure is defined as

 typedef struct { ATM_CONNECTION_ID PvcConnectionId; QOS PvcQos; } ATM_PVC_PARAMS; typedef struct { DWORD DeviceNumber; DWORD VPI; DWORD VCI; } ATM_CONNECTION_ID; 

SIO_GET_ATM_CONNECTION_ID

Which Function?	Input	Output	Winsock Version	Description
Both	None	ATM_CONNECTION_ID	2+	Determines whether OOB data has been read

This ioctl command retrieves the ATM Connection ID associated with the socket. Upon successfully returning from this function, the output buffer pointed to by lpvOutBuffer is filled with an ATM_CONNECTION_ID structure containing the device number and VPI/VCI values, which are defined in the earlier entry for SIO_ASSOCIATE_PVC.