WSAIoctl()

简述：控制一个套接口的模式。
　　#include <winsock2.h>
　　int WSAAPI WSAIoctl(SOCKET s, DWORD
　　dwIoControlCode, LPVOID lpvInBuffer, DWORD
　　cbInBuffer, LPVOID lpvOutBuffer, DWORD
　　cbOutBuffer, LPDWORD lpcbBytesReturned,
　　LPWSAOVERLAPPED lpOverlapped,
　　LPWSAOVERLAPPED_COMPLETION_ROUTINE
　　lpCompletionRoutine);
　　s：一个套接口的句柄。
　　dwIoControlCode：将进行的操作的控制代码。
　　lpvInBuffer：输入缓冲区的地址。
　　cbInBuffer：输入缓冲区的大小。
　　lpvOutBuffer：输出缓冲区的地址。
　　cbOutBuffer：输出缓冲区的大小。
　　lpcbBytesReturned：输出实际字节数的地址。
　　lpOverlapped：WSAOVERLAPPED结构的地址。
　　lpCompletionRoutine：一个指向操作结束后调用的例程指针。
　　返回值：
　　调用成功后，WSAIoctl ()函数返回0。否则的话，将返回INVALID_SOCKET错误，应用程序可通过WSAGetLastError()来获取相应的错误代码。
　　错误代码：
　　WSANOTINITIALISED 在调用本API之前应成功调用WSAStartup()。
　　WSAENETDOWN 网络子系统失效。
　　WSAEINVAL cmd不是一个合法的命令；或者一个输入参数非法；或者命令对于该种类型的套接口不适用。
　　WSAEINPROGRESS 在一个回调函数运行时调用了该函数。
　　WSAENOTSOCK 描述字不是一个套接口。
　　WSAEOPNOTSUPP 指定的ioctl命令无法实现，例如在SIO_SET_QOS或 SIO_SET_GROUP_QOS中指定的流描述无法实现。
　　WSA_IO_PENDING 一个重叠操作被成功启动，过后将报告完成情况。
　　WSAEWOULDBLOCK 套接口标志为非阻塞，且所需操作将产生阻塞。

 

http://msdn.microsoft.com/en-us/library/ms741621(VS.85).aspx

 

Code:

 

The following Windows Sockets 2 commands are supported.

SIO_ACQUIRE_PORT_RESERVATION (opcode setting: I, T==3)

Request a runtime reservation for a block of TCP or UDP ports. For runtime port reservations, the port pool requires that reservations be consumed from the process on whose socket the reservation was granted. Runtime port reservations last only as long as the lifetime of the socket on which the SIO_ACQUIRE_PORT_RESERVATION IOCTL was called. In contrast, persistent port reservations created using theCreatePersistentTcpPortReservation or CreatePersistentUdpPortReservation function may be consumed by any process with the ability to obtain persistent reservations.

For more detailed information, see the SIO_ACQUIRE_PORT_RESERVATION reference.

SIO_ACQUIRE_PORT_RESERVATION is supported on Windows Vista and later versions of the operating system.

SIO_ADDRESS_LIST_CHANGE (opcode setting: V, T==1)

To receive notification of changes in the list of local transport addresses of the socket's protocol family to which the application can bind. No output information will be provided upon completion of this IOCTL; the completion merely indicates that list of available local address has changed and should be queried again through SIO_ADDRESS_LIST_QUERY.

It is assumed (although not required) that the application uses overlapped I/O to be notified of change by completion ofSIO_ADDRESS_LIST_CHANGE request. Alternatively, if the SIO_ADDRESS_LIST_CHANGE IOCTL is issued on a non-blocking socket and without overlapped parameters (lpOverlapped/lpCompletionRoutine are set to NULL), it will complete immediately with errorWSAEWOULDBLOCK. The application can then wait for address list change events through a call toWSAEventSelect or WSAAsyncSelect with FD_ADDRESS_LIST_CHANGE bit set in the network event bitmask.

SIO_ADDRESS_LIST_QUERY (opcode setting: O, T==1)

Obtains a list of local transport addresses of the socket's protocol family to which the application can bind. The list of addresses varies based on address family and some addresses are excluded from the list.

Note  In Windows Plug-n-Play environments, addresses can be added and removed dynamically. Therefore, applications cannot rely on the information returned bySIO_ADDRESS_LIST_QUERY to be persistent. Applications may register for address change notifications through theSIO_ADDRESS_LIST_CHANGE IOCTL which provides for notification through either overlapped I/O or FD_ADDRESS_LIST_CHANGE event. The following sequence of actions can be used to guarantee that the application always has current address list information:

• Issue SIO_ADDRESS_LIST_CHANGE IOCTL
• Issue SIO_ADDRESS_LIST_QUERY IOCTL
• Whenever SIO_ADDRESS_LIST_CHANGE IOCTL notifies the application of address list change (either through overlapped I/O or by signaling FD_ADDRESS_LIST_CHANGE event), the whole sequence of actions should be repeated.

For more detailed information, see the SIO_ADDRESS_LIST_QUERY reference. SIO_ADDRESS_LIST_QUERY is supported on Windows 2000 and later.

SIO_ASSOCIATE_HANDLE (opcode setting: I, T==1)

Associate this socket with the specified handle of a companion interface. The input buffer contains the integer value corresponding to the manifest constant for the companion interface (for example, TH_NETDEV and TH_TAPI.), followed by a value that is a handle of the specified companion interface, along with any other required information. Refer to the appropriate section inWinsock Annexes for details specific to a particular companion interface. The total size is reflected in the input buffer length. No output buffer is required. TheWSAENOPROTOOPT error code is indicated for service providers that do not support this IOCTL. The handle associated by this IOCTL can be retrieved usingSIO_TRANSLATE_HANDLE.

A companion interface might be used, for example, if a particular provider provides (1) a great deal of additional controls over the behavior of a socket and (2) the controls are provider-specific enough that they do not map to existing Windows Socket functions or ones likely to be defined in the future. It is recommend that the Component Object Model (COM) be used instead of this IOCTL to discover and track other interfaces that might be supported by a socket. This IOCTL is present for (reverse) compatibility with systems where COM is not available or cannot be used for some other reason.

SIO_ASSOCIATE_PORT_RESERVATION (opcode setting: I, T==3)

Associate a socket with a persistent or runtime reservation for a block of TCP or UDP ports identified by the port reservation token. TheSIO_ASSOCIATE_PORT_RESERVATION IOCTL must be issued before the socket is bound. If and when the socket is bound, the port assigned to it will be selected from the port reservation identified by the given token. If no ports are available from the specified reservation, the bind function call will fail.

For more detailed information, see the SIO_ASSOCIATE_PORT_RESERVATION reference.

SIO_ASSOCIATE_PORT_RESERVATION is supported on Windows Vista and later versions of the operating system.

SIO_BASE_HANDLE (opcode setting: O, T==1)

Retrieves the base service provider handle for a given socket. The returned value is aSOCKET.

A layered service provider would never intercept this IOCTL since the return value must be the socket handle from the base service provider.

If the output buffer is not large enough for a socket handle (the cbOutBuffer is less than the size of aSOCKET) or the lpvOutBuffer parameter is a NULL pointer,SOCKET_ERROR is returned as the result of this IOCTL and WSAGetLastError returns WSAEFAULT.

SIO_BASE_HANDLE is defined in the Mswsock.h header file and supported on Windows Vista and later.

SIO_BSP_HANDLE (opcode setting: O, T==1)

Retrieves the base service provider handle for a socket used by the WSASendMsg function. The returned value is a SOCKET.

This Ioctl is used by a layered service provider to ensure the provider intercept theWSASendMsg function.

If the output buffer is not large enough for a socket handle (the cbOutBuffer is less than the size of aSOCKET) or the lpvOutBuffer parameter is a NULL pointer,SOCKET_ERROR is returned as the result of this IOCTL and WSAGetLastError returns WSAEFAULT.

SIO_BSP_HANDLE is defined in the Mswsock.h header file and supported on Windows Vista and later.

SIO_BSP_HANDLE_SELECT (opcode setting: O, T==1)

Retrieves the base service provider handle for a socket used by the select function. The returned value is a SOCKET.

This Ioctl is used by a layered service provider to ensure the provider intercept theselect function.

If the output buffer is not large enough for a socket handle (the cbOutBuffer is less than the size of aSOCKET) or the lpvOutBuffer parameter is a NULL pointer,SOCKET_ERROR is returned as the result of this IOCTL and WSAGetLastError returns WSAEFAULT.

SIO_BSP_HANDLE_SELECT is defined in the Mswsock.h header file and supported on Windows Vista and later.

SIO_BSP_HANDLE_POLL (opcode setting: O, T==1)

Retrieves the base service provider handle for a socket used by the WSAPoll function. The lpOverlapped parameter must be aNULL pointer. The returned value is a SOCKET.

This Ioctl is used by a layered service provider to ensure the provider intercept theWSAPoll function.

If the output buffer is not large enough for a socket handle (the cbOutBuffer is less than the size of aSOCKET), the lpvOutBuffer parameter is a NULL pointer, or thelpOverlapped parameter is not a NULL pointer, SOCKET_ERROR is returned as the result of this IOCTL andWSAGetLastError returns WSAEFAULT.

SIO_BSP_HANDLE_POLL is defined in the Mswsock.h header file and supported on Windows Vista and later.

SIO_CHK_QOS (opcode setting: I, O, T==3)

Retrieves information about QoS traffic characteristics. During the transitional phase on the sending system between flow setup and the receipt of a RESV message (seeHow the RSVP Service Invokes TC for more information on the transitional phase), traffic associated with an RSVP flow is shaped based on service type (BEST EFFORT, CONTROLLED LOAD, or GUARANTEED). For more information, see Using SIO_CHK_QOS in the Quality of Service section of the Platform Software Development Kit (SDK).

SIO_ENABLE_CIRCULAR_QUEUEING (opcode setting: V, T==1)

Indicates to the underlying message-oriented service provider that a newly arrived message should never be dropped because of a buffer queue overflow. Instead, the oldest message in the queue should be eliminated in order to accommodate the newly arrived message. No input and output buffers are required. Note that this IOCTL is only valid for sockets associated with unreliable, message-oriented protocols. TheWSAENOPROTOOPT error code is indicated for service providers that do not support this IOCTL.

SIO_FIND_ROUTE (opcode setting: O, T==1)

When issued, this IOCTL requests that the route to the remote address specified as asockaddr in the input buffer be discovered. If the address already exists in the local cache, its entry is invalidated. In the case of Novell's IPX, this call initiates an IPX GetLocalTarget (GLT), which queries the network for the given remote address.

SIO_FLUSH (opcode setting: V, T==1)

Discards current contents of the sending queue associated with this socket. No input and output buffers are required. TheWSAENOPROTOOPT error code is indicated for service providers that do not support this IOCTL.

SIO_GET_BROADCAST_ADDRESS (opcode setting: O, T==1)

This IOCTL fills the output buffer with a sockaddr structure containing a suitable broadcast address for use with sendto/ WSASendTo. Not supported for IPv6 sockets (returns WSAENOPROTOOPT).

SIO_GET_EXTENSION_FUNCTION_POINTER (opcode setting: O, I, T==1)

Retrieve a pointer to the specified extension function supported by the associated service provider. The input buffer contains a globally unique identifier (GUID) whose value identifies the extension function in question. The pointer to the desired function is returned in the output buffer. Extension function identifiers are established by service provider vendors and should be included in vendor documentation that describes extension function capabilities and semantics.

The GUID values for extension functions supported by the Windows TCP/IP service provider are defined in theMswsock.h header file. The possible value for these GUIDs are as follows:

TermDescription

WSAID_ACCEPTEX

The AcceptEx extension function.

WSAID_CONNECTEX

The ConnectEx extension function.

WSAID_DISCONNECTEX

The DisconnectEx extension function.

WSAID_GETACCEPTEXSOCKADDRS

The GetAcceptExSockaddrs extension function.

WSAID_TRANSMITFILE

The TransmitFile extension function.

WSAID_TRANSMITPACKETS

The TransmitPackets extension function.

WSAID_WSARECVMSG

The WSARecvMsg extension function.

WSAID_WSASENDMSG

The WSASendMsg extension function.

 

SIO_GET_GROUP_QOS (opcode setting: O, I, T==1)

Reserved for future use with sockets.

Retrieve the QOS structure associated with the socket group to which this socket belongs. The input buffer is optional. Some protocols (for example, RSVP) allow the input buffer to be used to qualify a quality of service request. TheQOS structure will be copied into the output buffer. If this socket does not belong to an appropriate socket group, theSendingFlowspec and ReceivingFlowspec members of the returnedQOS structure are set to NULL. The WSAENOPROTOOPT error code is indicated for service providers that do not support quality of service.

SIO_GET_INTERFACE_LIST (opcode setting: O, T==0)

Returns a list of configured IP interfaces and their parameters as an array ofINTERFACE_INFO structures.

Note  Support of this command is mandatory for Windows Sockets 2-compliant TCP/IP service providers.

The lpvOutBuffer parameter points to the buffer in which to store the information about interfaces as an array ofINTERFACE_INFO structures for unicast IP addresses on the interfaces. ThecbOutBuffer parameter specifies the length of the output buffer. The number of interfaces returned (number of structures returned in the buffer pointed to bylpvOutBuffer parameter) can be determined based on the actual length of the output buffer returned inlpcbBytesReturned parameter.

If the WSAIoctl function is called with SIO_GET_INTERFACE_LIST and the level member of the sockets parameter is not defined as IPPROTO_IP, WSAEINVAL is returned. A call to theWSAIoctl function with SIO_GET_INTERFACE_LIST returnsWSAEFAULT if the cbOutBuffer parameter that specifies the length of the output buffer is too small ro receive the list of configured interfaces.

SIO_GET_INTERFACE_LIST_EX (opcode setting: O, T==0)

Reserved for future use with sockets.

Returns a list of configured IP interfaces and their parameters as an array ofINTERFACE_INFO_EX structures.

The lpvOutBuffer parameter points to the buffer in which to store the information about interfaces as an array ofINTERFACE_INFO_EX structures for unicast IP addresses on the interface. ThecbOutBuffer parameter specifies the length of the output buffer. The number of interfaces returned (number of structures returned inlpvOutBuffer) can be determined based on the actual length of the output buffer returned inlpcbBytesReturned parameter.

SIO_GET_INTERFACE_LIST_EX is not currently supported on Windows.

SIO_GET_QOS (opcode setting: O, T==1)

Reserved for future use with sockets. Retrieve the QOS structure associated with the socket. The input buffer is optional. Some protocols (for example, RSVP) allow the input buffer to be used to qualify a quality of service request. TheQOS structure will be copied into the output buffer. The output buffer must be sized large enough to be able to contain the fullQOS structure. The WSAENOPROTOOPT error code is indicated for service providers that do not support quality of service.

A sender may not call SIO_GET_QOS until the socket is connected.

A receiver may call SIO_GET_QOS as soon as it is bound.

SIO_IDEAL_SEND_BACKLOG_CHANGE (opcode setting: V, T==0)

Notifies an application when the ideal send backlog (ISB) value changes for the underlying connection.

When sending data over a TCP connection using Windows sockets, it is important to keep a sufficient amount of data outstanding (sent but not acknowledged yet) in TCP in order to achieve the highest throughput. The ideal value for the amount of data outstanding to achieve the best throughput for the TCP connection is called the ideal send backlog (ISB) size. The ISB value is a function of the bandwidth-delay product of the TCP connection and the receiver's advertised receive window (and partly the amount of congestion in the network).

The ISB value per connection is available from the TCP protocol implementation in Windows Server 2008, Windows Vista with Service Pack 1 (SP1), and later versions of the operating system. TheSIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL can be used by an application to get notification when the ISB value changes dynamically for a connection.

For more detailed information, see the SIO_IDEAL_SEND_BACKLOG_CHANGE reference.

SIO_IDEAL_SEND_BACKLOG_CHANGE is supported on Windows Server 2008, Windows Vista with SP1, and later versions of the operating system.

SIO_IDEAL_SEND_BACKLOG_QUERY (opcode setting: O, T==0)

Retrieves the ideal send backlog (ISB) value for the underlying connection.

When sending data over a TCP connection using Windows sockets, it is important to keep a sufficient amount of data outstanding (sent but not acknowledged yet) in TCP in order to achieve the highest throughput. The ideal value for the amount of data outstanding to achieve the best throughput for the TCP connection is called the ideal send backlog (ISB) size. The ISB value is a function of the bandwidth-delay product of the TCP connection and the receiver's advertised receive window (and partly the amount of congestion in the network).

The ISB value per connection is available from the TCP protocol implementation in Windows Server 2008 and later. TheSIO_IDEAL_SEND_BACKLOG_QUERY IOCTL can be used by an application to query the ISB value for a connection.

For more detailed information, see the SIO_IDEAL_SEND_BACKLOG_QUERY reference.

SIO_IDEAL_SEND_BACKLOG_QUERY is supported on Windows Server 2008, Windows Vista with SP1, and later versions of the operating system.

SIO_KEEPALIVE_VALS (opcode setting: I, T==3)

Enables or disables the per-connection setting of the TCP keep-alive option which specifies the TCP keep-alive timeout and interval. For more information on the keep-alive option, see section 4.2.3.6 on theRequirements for Internet Hosts—Communication Layers specified in RFC 1122 available at theIETF website. (This resource may only be available in English.)

SIO_KEEPALIVE_VALS can be used to enable or disable keep-alive probes and set the keep-alive timeout and interval. The keep-alive timeout specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent. The keep-alive interval specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received.

The SO_KEEPALIVE option, which is one of the SOL_SOCKET Socket Options, can also be used to enable or disable the TCP keep-alive on a connection, as well as query the current state of this option. To query whether TCP keep-alive is enabled on a socket, thegetsockopt function can be called with the SO_KEEPALIVE option. To enable or disable TCP keep-alive, thesetsockopt function can be called with the SO_KEEPALIVE option. If TCP keep-alive is enabled with SO_KEEPALIVE, then the default TCP settings are used for keep-alive timeout and interval unless these values have been changed usingSIO_KEEPALIVE_VALS.

For more detailed information, see the SIO_KEEPALIVE_VALS reference. SIO_KEEPALIVE_VALS is supported on Windows 2000 and later.

SIO_MULTIPOINT_LOOPBACK (opcode setting: V, T==1)

Controls whether data sent by an application on the local computer (not necessarily by the same socket) in a multicast session will be received by a socket joined to the multicast destination group on the loopback interface. A value ofTRUE causes multicast data sent by an application on the local computer to be delivered to a listening socket on the loopback interface. A value ofFALSE prevents multicast data sent by an application on the local computer from being delivered to a listening socket on the loopback interface. By default,IP_MULTICAST_LOOPBACK is enabled.

SIO_MULTICAST_SCOPE (opcode setting: I, T==1)

Specifies the scope over which multicast transmissions will occur. Scope is defined as the number of routed network segments to be covered. A scope of zero would indicate that the multicast transmission would not be placed on the wire but could be disseminated across sockets within the local host. A scope value of one (the default) indicates that the transmission will be placed on the wire, but will not cross any routers. Higher scope values determine the number of routers that can be crossed. Note that this corresponds to the time-to-live (TTL) parameter in IP multicasting. By default, scope is 1.

SIO_QUERY_RSS_SCALABILITY_INFO (opcode setting: O, T==3)

Queries offload interfaces for receive-side scaling (RSS) capability. The argument structure returned forSIO_QUERY_RSS_SCALABILITY_INFO is specified in the RSS_SCALABILITY_INFO structure defined in theMstcpip.h header file. This structure is defined as follows:

C++

Copy

// Scalability info for the transporttypedef struct _RSS_SCALABILITY_INFO {   BOOLEAN RssEnabled;} RSS_SCALABILITY_INFO, *PRSS_SCALABILITY_INFO;

The value returned in the RssEnabled member indicates if RSS is enabled on at least one interface.

If the output buffer is not large enough for the RSS_SCALABILITY_INFO structure (thecbOutBuffer is less than the size of a RSS_SCALABILITY_INFO) or thelpvOutBuffer parameter is a NULL pointer, SOCKET_ERROR is returned as the result of this IOCTL andWSAGetLastError returns WSAEINVAL.

In high-speed networking where multiple CPUs reside within a single system, the ability of the networking protocol stack to scale well on a multi-CPU system is inhibited because the architecture of NDIS 5.1 and earlier versions limits receive protocol processing to a single CPU. Receive-side scaling (RSS) resolves this issue by allowing the network load from a network adapter to be balanced across multiple CPUs.

SIO_QUERY_RSS_SCALABILITY_INFO is supported on Windows Vista and later.

SIO_QUERY_WFP_ALE_ENDPOINT_HANDLE (opcode setting: O, T==3)

Queries the Application Layer Enforcement (ALE) endpoint handle.

The Windows Filtering Platform (WFP) supports network traffic inspection and modification. On Windows Vista, WFP focuses on scenarios where the host machine is the communication endpoint. On Windows Server 2008 , however, there are edge firewall implementations which would like to leverage the WFP platform to inspect and proxy pass-through traffic. The Internet Security and Acceleration (ISA) server is an example of such an edge device.

There are some firewall scenarios that may require the ability to inject an inbound packet into the send path associated with an existing endpoint. There needs to be a mechanism to discover the transport layer endpoint handle associated with the destination endpoint. The application that created the endpoint owns these transport layer endpoints. This IOCTL is used to provide socket handle to transport layer endpoint handle mapping.

If the output buffer is not large enough for the endpoint handle (the cbOutBuffer is less than the size of aUINT64) or the lpvOutBuffer parameter is a NULL pointer,SOCKET_ERROR is returned as the result of this IOCTL and WSAGetLastError returns WSAEINVAL.

SIO_QUERY_WFP_ALE_ENDPOINT_HANDLE is supported on Windows Vista and later.

SIO_RCVALL (opcode setting: I, T==3)

Enables a socket to receive all IPv4 or IPv6 packets passing throuigh a network interface. The socket handle passed to theWSAIoctl function must be one of the following:

• An IPv4 socket that was created with the address family set to AF_INET, the socket type set to SOCK_RAW, and the protocol set to IPPROTO_IP.
• An IPv6 socket that was created with the address family set to AF_INET6, the socket type set to SOCK_RAW, and the protocol set to IPPROTO_IPV6.

The socket also must be bound to an explicit local IPv4 or IPv6 interface, which means that you cannot bind toINADDR_ANY or in6addr_any.

On Windows Server 2008 and earlier, the SIO_RCVALL IOCTL setting would not capture local packets sent out of a network interface. This included packets received on another interface and forwarded out the network interface specified for theSIO_RCVALL IOCTL.

On Windows 7 and Windows Server 2008 R2 , this was changed so that local packets sent out of a network interface are also captured. This includes packets received on another interface and then forwarded out the network interface bound to the socket withSIO_RCVALL IOCTL.

Setting this IOCTL requires Administrator privilege on the local computer.

This feature is sometimes referred to as promiscuous mode.

The possible values for the SIO_RCVALL IOCTL option are specified in theRCVALL_VALUE enumeration defined in the Mstcpip.h header file. The possible values for SIO_RCVALL are as follows:

TermDescription

RCVALL_OFF

Disable this option so a socket does not receive all IPv4 or IPv6 packets on the network.

RCVALL_ON

Enable this option so a socket receives all IPv4 or IPv6 packets on the network. This option enables promiscuous mode on the network interface card (NIC), if the NIC supports promiscuous mode. On a LAN segment with a network hub, a NIC that supports promiscuous mode will capture all IPv4 or IPv6 traffic on the LAN, including traffic between other computers on the same LAN segment. All of the captured packets (IPv4 or IPv6, depending on the socket) will be delivered to the raw socket.

This option will not capture other packets (ARP, IPX, and NetBEUI packets, for example) on the interface.

Netmon uses the same mode for the network interface, but does not use this option to capture traffic.

RCVALL_SOCKETLEVELONLY

This feature is not currently implemented, so setting this option does not have any affect.

RCVALL_IPLEVEL

Enable this option so an IPv4 or IPv6 socket receives all packets at the IP level on the network. This option does not enable promiscuous mode on the network interface card. This option only affects packet processing at the IP level. The NIC still receives only packets directed to its configured unicast and multicast addresses. However, a socket with this option enabled will receive not only packets directed to specific IP addresses, but will receive all the IPv4 or IPv6 packets the NIC receives.

This option will not capture other packets (ARP, IPX, and NetBEUI packets, for example) received on the interface.

 

For more detailed information, see the SIO_RCVALL reference.

SIO_RCVALL is supported on Windows 2000 and later.

SIO_RCVALL_IGMPMCAST (opcode setting: I, T==3)

Enables a socket to receive all IGMP multicast IP traffic on the network, without receiving other multicast IP traffic. The socket handle passed to theWSAIoctl function must be of AF_INET address family, SOCK_RAW socket type, and IPPROTO_IGMP protocol. The socket also must be bound to an explicit local interface, which means that you cannot bind to INADDR_ANY.

Once the socket is bound and the IOCTL set, calls to the WSARecv or recv functions return multicast IP datagrams passing through the given interface. Note that you must supply a sufficiently large buffer. Setting this IOCTL requires Administrator privilege on the local computer.

SIO_RCVALL_IGMPMCAST is supported on Windows 2000 and later.

SIO_RCVALL_MCAST (opcode setting: I, T==3)

Enables a socket to receive all multicast IP traffic on the network (that is, all IP packets destined for IP addresses in the range of 224.0.0.0 to 239.255.255.255). The socket handle passed to theWSAIoctl function must be of AF_INET address family, SOCK_RAW socket type, and IPPROTO_UDP protocol. The socket also must bind to an explicit local interface, which means that you cannot bind to INADDR_ANY. The socket should bind to port zero.

Once the socket is bound and the IOCTL set, calls to the WSARecv or recv functions return multicast IP datagrams passing through the given interface. Note that you must supply a sufficiently large buffer. Setting this IOCTL requires Administrator privilege on the local computer.

SIO_RCVALL_MCAST is supported on Windows 2000 and later.

SIO_RELEASE_PORT_RESERVATION (opcode setting: I, T==3)

Releases a runtime reservation for a block of TCP or UDP ports. The runtime reservation to be released must have been obtained from the issuing process using theSIO_ACQUIRE_PORT_RESERVATION IOCTL.

For more detailed information, see the SIO_RELEASE_PORT_RESERVATION reference.

SIO_RELEASE_PORT_RESERVATION is supported on Windows Vista and later versions of the operating system.

SIO_ROUTING_INTERFACE_CHANGE (opcode setting: I, T==1)

To receive notification of a routing interface change that should be used to reach the remote address in the input buffer (specified as asockaddr structure). No output information on the new routing interface will be provided upon completion of this IOCTL; the completion merely indicates that the routing interface for a given destination has changed and should be queried using the SIO_ROUTING_INTERFACE_QUERY IOCTL.

It is assumed (although not required) that the application uses overlapped I/O to be notified of the routing interface change through completion ofSIO_ROUTING_INTERFACE_CHANGE request. Alternatively, if the SIO_ROUTING_INTERFACE_CHANGE IOCTL is issued on a non-blocking socket with thelpOverlapped and lpCompletionRoutine parameters set to NULL), it will complete immediately returning and WSAEWOULDBLOCK as an error, and the application can then wait for routing change events through call toWSAEventSelect or WSAAsyncSelect with FD_ROUTING_INTERFACE_CHANGE bit set in the network event bitmask.

It is recognized that routing information remains stable in most cases so that requiring the application to keep multiple outstanding IOCTLs to get notifications about all destinations that it is interested in as well as having the service provider keep track of these notification requests will use a significant amount system resources. This situation can be avoided by extending the meaning of the input parameters and relaxing the service provider requirements as follows:

• The application can specify a protocol family specific wildcard address (same as one used inbind call when requesting to bind to any available address) to request notifications of any routing changes. This allows the application to keep only one outstandingSIO_ROUTING_INTERFACE_CHANGE for all the sockets and destinations it has and then useSIO_ROUTING_INTERFACE_QUERY to get the actual routing information.
• A service provider has the option to ignore the information specified by the application in the input buffer of theSIO_ROUTING_INTERFACE_CHANGE (as though the application specified a wildcard address) and complete theSIO_ROUTING_INTERFACE_CHANGE IOCTL or signal FD_ROUTING_INTERFACE_CHANGE event in the event of any routing information change (not just the route to the destination specified in the input buffer).

SIO_ROUTING_INTERFACE_QUERY (opcode setting: I, O, T==1)

To obtain the address of the local interface (represented as sockaddr structure) which should be used to send to the remote address specified in the input buffer (assockaddr). Remote multicast addresses may be submitted in the input buffer to get the address of the preferred interface for multicast transmission. In any case, the interface address returned may be used by the application in a subsequent bind() request.

Note that routes are subject to change. Therefore, applications cannot rely on the information returned bySIO_ROUTING_INTERFACE_QUERY to be persistent. Applications may register for routing change notifications through theSIO_ROUTING_INTERFACE_CHANGE IOCTL which provides for notification through either overlapped I/O or a FD_ROUTING_INTERFACE_CHANGE event. The following sequence of actions can be used to guarantee that the application always has current routing interface information for a given destination:

• Issue SIO_ROUTING_INTERFACE_CHANGE IOCTL
• Issue SIO_ROUTING_INTERFACE_QUERY IOCTL
• Whenever SIO_ROUTING_INTERFACE_CHANGE IOCTL notifies the application of routing change (either through overlapped I/O or by signaling FD_ROUTING_INTERFACE_CHANGE event), the whole sequence of actions should be repeated.

If the output buffer is not large enough to contain the interface address, SOCKET_ERROR is returned as the result of this IOCTL andWSAGetLastError returns WSAEFAULT. The required size of the output buffer will be returned in lpcbBytesReturned in this case. Note the WSAEFAULT error code is also returned if thelpvInBuffer, lpvOutBuffer, or lpcbBytesReturned parameter is not totally contained in a valid part of the user address space.

If the destination address specified in the input buffer cannot be reached through any of the available interfaces, SOCKET_ERROR is returned as the result of this IOCTL andWSAGetLastError returns WSAENETUNREACH or even WSAENETDOWN if all of the network connectivity is lost.

SIO_SET_COMPATIBILITY_MODE (opcode setting: I, T==3)

Requests how the networking stack should handle certain behaviors for which the default way of handling the behavior may differ across Windows versions. The argument structure forSIO_SET_COMPATIBILITY_MODE is specified in the WSA_COMPATIBILITY_MODE structure defined in theMswsockdef.h header file. This structure is defined as follows:

C++

Copy

/* Argument structure for SIO_SET_COMPATIBILITY_MODE */typedef struct _WSA_COMPATIBILITY_MODE {    WSA_COMPATIBILITY_BEHAVIOR_ID BehaviorId;    ULONG TargetOsVersion;} WSA_COMPATIBILITY_MODE, *PWSA_COMPATIBILITY_MODE;

The value specified in the BehaviorId member indicates the behavior requested. The value specified in theTargetOsVersion member indicates the Windows version that is being requested for the behavior.

The BehaviorId member can be one of the values from the WSA_COMPATIBILITY_BEHAVIOR_ID enumeration type defined in the Mswsockdef.h header file. The possible values for theBehaviorId member are as follows

TermDescription

WsaBehaviorAll

This is equivalent to requesting all of the possible compatible behaviors defined forWSA_COMPATIBILITY_BEHAVIOR_ID.

WsaBehaviorReceiveBuffering

When the TargetOsVersion member is set to a value for Windows Vista or later, reductions to the TCP receive buffer size on this socket using theSO_RCVBUF socket option are allowed even after a TCP connection has been establishment.

When the TargetOsVersion member is set to a value earlier than Windows Vista, reductions to the TCP receive buffer size on this socket using theSO_RCVBUF socket option are not allowed after connection establishment.

WsaBehaviorAutoTuning

When the TargetOsVersion member is set to a value for Windows Vista or later, receive window auto-tuning is enabled and the TCP window scale factor is reduced to 2 from the default value of 8.

When the TargetOsVersion is set to a value earlier than Windows Vista, receive window auto-tuning is disabled. The TCP window scaling option is also disabled and the maximum true receive window size is limited to 65,535 bytes. The TCP window scaling option can't be negotiated on the connection even if the SO_RCVBUF socket option was called on this socket specifying a value greater than 65,535 bytes before the connection was established.

 

For more detailed information, see the SIO_SET_COMPATIBILITY_MODE reference.

SIO_SET_COMPATIBILITY_MODE is supported on Windows Vista and later.

SIO_SET_GROUP_QOS (opcode setting: I, T==1)

Reserved.

SIO_SET_QOS (opcode setting: I, T==1)

Associate the specified QOS structure with the socket. No output buffer is required, theQOS structure will be obtained from the input buffer. The WSAENOPROTOOPT error code is indicated for service providers that do not support quality of service.

SIO_TRANSLATE_HANDLE (opcode setting: I, O, T==1)

To obtain a corresponding handle for socket s that is valid in the context of a companion interface (for example, TH_NETDEV and TH_TAPI). A manifest constant identifying the companion interface along with any other needed parameters are specified in the input buffer. The corresponding handle will be available in the output buffer upon completion of this function. Refer to the appropriate section inWinsock Annexes for details specific to a particular companion interface. TheWSAENOPROTOOPT error code is indicated for service providers that do not support this IOCTL for the specified companion interface. This IOCTL retrieves the handle associated usingSIO_TRANSLATE_HANDLE.

It is recommend that the Component Object Model (COM) be used instead of this IOCTL to discover and track other interfaces that might be supported by a socket. This IOCTL is present for backward compatibility with systems where COM is not available or cannot be used for some other reason.

SIO_UDP_CONNRESET (opcode setting: I, T==3)

Windows XP:  Controls whether UDP PORT_UNREACHABLE messages are reported. Set toTRUE to enable reporting. Set to FALSE to disable reporting.

If an overlapped operation completes immediately, WSAIoctl returns a value of zero and thelpcbBytesReturned parameter is updated with the number of bytes in the output buffer. If the overlapped operation is successfully initiated and will complete later, this function returns SOCKET_ERROR and indicates error codeWSA_IO_PENDING. In this case, lpcbBytesReturned is not updated. When the overlapped operation completes the amount of data in the output buffer is indicated either through thecbTransferred parameter in the completion routine (if specified), or through thelpcbTransfer parameter in WSAGetOverlappedResult.

When called with an overlapped socket, the lpOverlapped parameter must be valid for the duration of the overlapped operation. ThelpOverlapped parameter contains the address of a WSAOVERLAPPED structure.

If the lpCompletionRoutine parameter is NULL, the hEvent parameter of lpOverlapped is signaled when the overlapped operation completes if it contains a valid event object handle. An application can useWSAWaitForMultipleEvents or WSAGetOverlappedResult to wait or poll on the event object.

Note  All I/O initiated by a given thread is canceled when that thread exits. For overlapped sockets, pending asynchronous operations can fail if the thread is closed before the operations complete. SeeExitThread for more information.

If lpCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used by the application to pass context information to the completion routine. A caller that passes a non-NULLlpCompletionRoutine and later calls WSAGetOverlappedResult for the same overlapped I/O request may not set thefWait parameter for that invocation of WSAGetOverlappedResult toTRUE. In this case, the usage of the hEvent parameter is undefined, and attempting to wait on thehEvent parameter would produce unpredictable results.