Ioctlsocket, WSAIoctl, and WSANSPIoctl

Ioctlsocket, WSAIoctl, and WSANSPIoctl

The socket ioctl functions are used to control the behavior of I/O on the socket, as well as to 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 on, and 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. In addition, 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, lpvInBuffer and cbInBuffer, describe the input parameters. The lpvInBuffer parameter is a pointer to the value passed in, and 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, and 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 5 for detailed information on using overlapped I/O.

Lastly, a new ioctl function, WSANSPIoctl, has been introduced for Windows XP. This function is used exclusively for making I/O control calls to name space providers. The function is defined as

int WSANSPIoctl( HANDLE hLookup, DWORD dwControlCode, LPVOID lpvInBuffer, DWORD cbInBuffer, LPVOID lpvOutBuffer, DWORD cbOutBuffer, LPDWORD lpcbBytesReturned, LPWSACOMPLETION lpCompletion );

The parameters to this function are the same as WSAIoctl except for hLookup and lpCompletion. The handle passed into this function is the handle returned from WSALookupServiceBegin. This handle identifies a name space query to a particular name space provider. The lpCompletion parameter specifies how the application should be notified if there is a change to the name space provider or query. This new ioctl function is used by the Network Location Awareness (NLA) service, which is described in detail in Chapter 8, so we won't explain it in full here.

Standard Ioctl Commands

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

FIONBIO

Which Function?	Input	Output	Winsock Version	Description
ioctlsocket/WSAIoctl	unsigned int	None	1+	Puts socket in non-blocking mode

This command enables or disables non-blocking 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 non-blocking 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 non-blocking 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 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 OOB data has been read

When a socket has been configured to receive OOB data and has been set to receive this data inline (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 1 for more information on OOB data.

Other Ioctl Commands

These ioctl commands are specific to Winsock 2 except for those dealing with Secure Sockets Layer (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. In addition, as you will see, not all ioctl commands work on all (or any) Windows platform, 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 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 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.

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 Windows platforms does not implement this ioctl command.

SIO_FLUSH

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	None	None	2+	Discards the send buffers

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, this option is supported on Windows NT 4 Service Pack 4, Windows 2000, and Windows XP.

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. Windows 95, Windows 98, and Windows Me 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 the 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 globally unique identifiers (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. See Chapter 6 for more information on the Microsoft-specific extensions. Also, this ioctl command is an important part of developing a layered service provider. See Chapter 12 for more details about the service provider interface.

SIO_CHK_QOS

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	DWORD	DWORD	2+	Checks 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 and later versions. Six 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 10. Use the ALLOWED_TO_SEND_DATA flag to see if 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 if 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) because the structure might contain provider-specific information. For more information on QOS, see Chapter 10. 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, Windows Me, and Windows 2000 and later versions.

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 10 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, Windows Me, and Windows 2000 and later versions.

SIO_MULTIPOINT_LOOPBACK

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	BOOL	BOOL	2+	Sets or 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 or sets the 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 get 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 will change 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

 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 and later versions.

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 IPv4 packets on the network. This option is currently not implemented for IPv6 sockets, so the socket handle that must be passed to WSAIoctl must be of address family AF_INET, socket type SOCK_RAW, and protocol IPPROTO_IP. In addition, 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 IPv4 datagrams. Keep in mind that these are datagrams—you must supply a sufficiently large buffer. Because the total length field of the IPv4 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. In addition, this ioctl command is available in Windows 2000 and later versions.

	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 just described. The same usage rules mentioned for SIO_RCVALL also apply to this command except that the socket passed to WSAIoctl should be created with the protocol equal to IPPROTO_UDP. The one difference is that only multicast IPv4 traffic is returned, as opposed to all IP packets. This means that only IPv4 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 and later versions.

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 about how to use this option. This ioctl is available in Windows 2000 and later versions.

SIO_ROUTING_INTERFACE_QUERY

Which Function?	Input	Output	Winsock Version	Description
Both	SOCKADDR	None	2+	Returns the local interface used to reach the supplied destination

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 remote machine's address should be supplied in the form of a SOCKADDR structure as the lpvInBuffer parameter. In addition, 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 and Windows XP 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 in 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.

	See the code sample in the directory SIO_ROUTING_INTERFACE on the companion CD for an example on how to use these ioctls.

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 non-blocking 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 that the application supplied 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 that the socket can bind to

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, and the Address field is an array of protocol family–specific addresses.

In Windows plug-and-play environments, the number of valid addresses can change dynamically; therefore, applications cannot rely on the information this ioctl command returns to remain constant. 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. This ioctl is supported in Windows 2000 or later versions.

	See the code sample in the directory SIO_ADDRESS_LIST on the companion CD for an example of how to use these ioctls.

SIO_ADDRESS_LIST_SORT

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	SOCKET_ ADDRESS_LIST	SOCKET_ ADDRESS_LIST	2+	Sorts the address list by preference

This option takes the SOCKET_ADDRESS_LIST structure returned from an SIO_ADDRESS_LIST_QUERY command and sorts the addresses as well as fills in the appropriate scope IDs in the case of IPv6 addresses. Note that the scope IDs are only set for site-local addresses when there is a global address in the list, and the global address falls within one of the global site-prefixes. This iocl is available in Windows XP and later versions.

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 that the application can bind to. 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 non-blocking 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. In addition, 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 on a routing change. This ioctl is supported in Windows 2000 and later versions.

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 about each interface on the local machine. Nothing is required on input, but on output, an array of INTERFACE_INFO structures is returned. These 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.

SIO_GET_INTERFACE_LIST_EX

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

This ioctl is the same as SIO_GET_INTERFACE_LIST except the structure returned contains embedded SOCKET_ADDRESS structure to describe each local interface, as opposed to SOCKADDR_GEN structure. This removes the dependency the size of the socket address structure. The INTERFACE_INFO_EX structure is defined as

typedef struct _INTERFACE_INFO_EX {     u_long          iiFlags;            /* Interface flags */     SOCKET_ADDRESS  iiAddress;          /* Interface address */     SOCKET_ADDRESS  iiBroadcastAddress; /* Broadcast address */     SOCKET_ADDRESS  iiNetmask;          /* Network mask */ } INTERFACE_INFO_EX, FAR * LPINTERFACE_INFO_EX;

The fields have the same meaning as the INTERFACE_INFO structure described previously. This ioctl is supported in Windows XP and later versions.

SIO_GET_MULTICAST_FILTER

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	None	struct ip_msfilter	2+	Returns the multicast filter set on a socket

This ioctl retrieves the multicast filter set on a given socket. The multicast state is set with the SIO_SET_MULTICAST_FILTER ioctl. This ioctl requires an IGMPv3-enabled network and is supported in only Windows XP. See Chapter 9 for more information about multicasting.

SIO_SET_MULTICAST_FILTER

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	struct ip_msfilter	None	2+	Sets a multicast filter on a socket

This ioctl sets the multicast state. The input parameter is a struct ip_msfilter, which is defined as

struct ip_msfilter {          struct in_addr imsf_multiaddr;          struct in_addr imsf_interface;          u_long         imsf_fmode;          u_long         imsf_numsrc;          struct in_addr imsf_slist[1]; };

The first field is the multicast address to join and the second field is the local interface to join the group. The imsf_fmode indicates whether the filter state is include or exclude by the defines MCAST_INCLUDE and MCAST_EXCLUDE, respectively. The imsf_numsrc indicates the number of IPv4 source addresses contained in the imsf_slist array.

This ioctl can be used to set the multicast state in a single call instead of multiple calls to IP_ADD_SOURCE_MEMBERSHIP, IP_DROP_SOURCE_MEMBERSHIP, IP_BLOCK_SOURCE, and IP_UNBLOCK_SOURCE. This ioctl requires an IGMPv3-enabled network and Windows XP. See Chapter 9 for more information.

SIO_INDEX_BIND

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	int	None	2+	Binds the socket to the given interface index

This ioctl binds a socket to an interface index specified as the input parameter instead of an address. This ioctl is supported in Windows 2000 and later versions.

SIO_INDEX_MCASTIF

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	Int	None	2+	Sets the multicast send interface to the specified index

This ioctl sets the outgoing interface for multicast traffic via an interface index as the input parameter instead of an address. This ioctl is supported on Windows 2000 and later versions.

SIO_INDEX_ADD_MCAST

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	struct ip_mreq	None	2+	Joins a multicast group on the specified interface index

This ioctl joins a multicast group using an interface index instead of an address. The input parameter is a struct ip_mreq structure except that the imr_interface field contains the interface index. See Chapter 9 for more information. This ioctl is supported in Windows 2000 and later versions.

SIO_INDEX_DEL_MCAST

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	struct ip_mreq	None	2+	Drops a multicast group from the specified interface index

This ioctl drops membership to the specified multicast group from the selected interface. This ioctl is supported in Windows 2000 and later versions. See Chapter 9 for more details.

SIO_NSP_NOTIFY_CHANGE

Which Function?	Input	Output	Winsock Version	Description
WSANSPIoctl	None	None	2+	Notifies when a name space query is no longer valid

This ioctl is used to receive notification when the available networks change. This ioctl is supported in Windows XP and later versions. See Chapter 8 for more information about this ioctl.

SIO_QUERY_TARGET_PNP_HANDLE

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	None	SOCKET	2+	Returns the underlying provider's SOCKET handle

This ioctl queries the underlying provider for a handle that can be used to receive plug and play event notifications. This ioctl is supported in Windows 2000 and later versions.

SIO_UDP_CONNRESET

Which Function?	Input	Output	Winsock Version	Description
WSAIoctl	BOOL	None	2+	Enables ICMP errors to be propagated to the socket

By default, any ICMP errors generated by traffic sent on a UDP socket are not propagated to the socket. For example, if data is sent to an endpoint where there is no socket listening, an ICMP error is returned. When this ioctl is set to TRUE, these errors are propagated to the sending socket, usually in the form of a WSAECONNRESET error. This ioctl is supported in Windows 2000 and later versions.

Secure Socket Layer Ioctl Commands

SSL commands are supported only in Windows CE. Currently, Windows 95, Windows 98, Windows Me, Windows NT, Windows 2000, and Windows XP do not provide an SSL-capable provider. Because these commands 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

The input buffer here must be a pointer to a DWORD bit field. Currently, the only flag defined is SSL_FLAG_DEFER_HANDSHAKE, which allows the application to send and receive plain text data before switching to cipher text. 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 that the security provider supports

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 previously.

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 the Windows Sockets security provider invokes when it receives a set of credentials 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

The ioctl commands in this section 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 4 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 Virtual Path/Channel Identifier (VPI/VCI) values, which are defined in the earlier entry for SIO_ASSOCIATE_PVC.