< IP, IPV6, RM & IPX | Socket Options & IOCTLs Main | SSL & ATM Options >

---

 

 

Socket Options and IOCTLs 7 part 3

 

 

What do we have in this chapter 7 part 3?

104. Standard Ioctl Commands

105. FIONBIO

106. FIONREAD

107. SIOCATMARK

108. Other Ioctl Commands

109. SIO_ENABLE_CIRCULAR_QUEUEING

110. SIO_FIND_ROUTE

111. SIO_FLUSH

112. SIO_GET_BROADCAST_ADDRESS

113. SIO_GET_EXTENSION_FUNCTION_POINTER

114. SIO_CHK_QOS

115. SIO_GET_QOS

116. SIO_SET_QOS

117. SIO_MULTIPOINT_LOOPBACK

118. SIO_MULTICAST_SCOPE

119. SIO_KEEPALIVE_VALS

120. SIO_RCVALL

121. SIO_RCVALL_MCAST

122. SIO_RCVALL_IGMPMCAST

123. SIO_ROUTING_INTERFACE_QUERY

124. SIO_ROUTING_INTERFACE_CHANGE

125. SIO_ADDRESS_LIST_QUERY

126. SIO_ADDRESS_LIST_SORT

127. SIO_ADDRESS_LIST_CHANGE

128. SIO_GET_INTERFACE_LIST

129. SIO_GET_INTERFACE_LIST_EX

130. SIO_GET_MULTICAST_FILTER

131. SIO_SET_MULTICAST_FILTER

132. SIO_INDEX_BIND

133. SIO_INDEX_MCASTIF

134. SIO_INDEX_ADD_MCAST

135. SIO_INDEX_DEL_MCAST

136. SIO_NSP_NOTIFY_CHANGE

137. SIO_QUERY_TARGET_PNP_HANDLE

138. SIO_UDP_CONNRESET

 

 

SIOCATMARK

 

 

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.

 

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

 

 

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

 

 

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

 

 

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

 

 

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

 

 

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. Also, this IOCTL command is an important part of developing a layered service provider.

 

SIO_CHK_QOS

 

 

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

 

 

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

 

 

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

 

 

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

 

 

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

 

 

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

 

 

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.

 

SIO_RCVALL_MCAST

 

 

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

 

 

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

 

 

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.

 

SIO_ROUTING_INTERFACE_CHANGE

 

 

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

 

 

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.

 

SIO_ADDRESS_LIST_SORT

 

 

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 ioctl is available in Windows XP and later versions.

 

SIO_ADDRESS_LIST_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

 

 

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

 

 

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

 

 

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.

 

SIO_SET_MULTICAST_FILTER

 

 

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.

 

SIO_INDEX_BIND

 

 

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

 

 

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

 

 

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. This ioctl is supported in Windows 2000 and later versions.

 

SIO_INDEX_DEL_MCAST

 

 

This ioctl drops membership to the specified multicast group from the selected interface. This ioctl is supported in Windows 2000 and later versions.

 

SIO_NSP_NOTIFY_CHANGE

 

 

This ioctl is used to receive notification when the available networks change. This ioctl is supported in Windows XP and later versions.

 

SIO_QUERY_TARGET_PNP_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

 

 

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.

 

 

 

---

< IP, IPV6, RM & IPX | Socket Options & IOCTLs Main | SSL & ATM Options >