WSAIoctl Function

Artikel
07/27/2011

The WSAIoctl function controls the mode of a socket.

Syntax

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

Parameter

s [in]
A descriptor identifying a socket.
dwIoControlCode [in]
The control code of operation to perform.
lpvInBuffer [in]
A pointer to the input buffer.
cbInBuffer [in]
The size, in bytes, of the input buffer.
lpvOutBuffer [out]
A pointer to the output buffer.
cbOutBuffer [in]
The size, in bytes, of the output buffer.
lpcbBytesReturned [out]
A pointer to actual number of bytes of output.
lpOverlapped [in]
A pointer to a WSAOVERLAPPED structure (ignored for non-overlapped sockets).
lpCompletionRoutine [in]
Hinweis A pointer to the completion routine called when the operation has been completed (ignored for non-overlapped sockets). See Remarks.

Rückgabewert

Upon successful completion, the WSAIoctl returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error code	Meaning
WSA_IO_PENDING	An overlapped operation was successfully initiated and completion will be indicated at a later time.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped, or lpCompletionRoutine parameter is not totally contained in a valid part of the user address space, or the cbInBuffer or cbOutBuffer parameter is too small.
WSAEINVAL	The dwIoControlCode parameter is not a valid command, or a specified input parameter is not acceptable, or the command is not applicable to the type of socket specified.
WSAEINPROGRESS	The function is invoked when a callback is in progress.
WSAENOTSOCK	The descriptor s is not a socket.
WSAEOPNOTSUPP	The specified IOCTL command cannot be realized. (For example, the FLOWSPEC structures specified in SIO_SET_QOS or SIO_SET_GROUP_QOS cannot be satisfied.)
WSAEWOULDBLOCK	The socket is marked as non-blocking and the requested operation would block.
WSAENOPROTOOPT	The socket option is not supported on the specified protocol. For example, an attempt to use the SIO_GET_BROADCAST_ADDRESS IOCTL was made on an IPv6 socket or an attempt to use the TCP SIO_KEEPALIVE_VALS IOCTL was made on a datagram socket.

Hinweise

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

If both lpOverlapped and lpCompletionRoutine are NULL, the socket in this function will be treated as a non-overlapped socket. For a non-overlapped socket, lpOverlapped and lpCompletionRoutine parameters are ignored, which causes the function to behave like the standard ioctlsocket function except that the function can block if socket s is in blocking mode. If socket s is in non-blocking mode, this function can return WSAEWOULDBLOCK when the specified operation cannot be finished immediately. In this case, the application may change the socket to blocking mode and reissue the request or wait for the corresponding network event (such as FD_ROUTING_INTERFACE_CHANGE or FD_ADDRESS_LIST_CHANGE in the case of SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE) using a Windows message (using WSAAsyncSelect)-based or event (using WSAEventSelect)-based notification mechanism.

For overlapped sockets, operations that cannot be completed immediately will be initiated, and completion will be indicated at a later time. The DWORD value pointed to by the lpcbBytesReturned parameter that is returned may be ignored. The final completion status and bytes returned can be retrieved when the appropriate completion method is signaled when the operation has completed.

Any IOCTL may block indefinitely, depending on the service provider's implementation. If the application cannot tolerate blocking in a WSAIoctl call, overlapped I/O would be advised for IOCTLs that are especially likely to block including:

SIO_ADDRESS_LIST_CHANGE

SIO_FINDROUTE

SIO_FLUSH

SIO_GET_QOS

SIO_GET_GROUP_QOS

SIO_ROUTING_INTERFACE_CHANGE

SIO_SET_QOS

SIO_SET_GROUP_QOS

Some protocol-specific IOCTLs may also be especially likely to block. Check the relevant protocol-specific annex for any available information.

The prototype for the completion routine pointed to by the lpCompletionRoutine parameter is as follows:

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")


void CALLBACK CompletionRoutine (
  IN DWORD dwError,
  IN DWORD cbTransferred,
  IN LPWSAOVERLAPPED lpOverlapped,
  IN DWORD dwFlags 
);

The CompletionRoutine is a placeholder for an application-supplied function name. The dwError parameter specifies the completion status for the overlapped operation as indicated by lpOverlapped parameter. The cbTransferred parameter specifies the number of bytes received. The dwFlags parameter is not used for this IOCTL. The completion routine does not return a value.

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

I	O	V	T	Vendor/address family	Code
3	3	2	2 2	2 2 2 2 2 2 2 1 1 1 1	1 1 1 1 1 1
1	0	9	8 7	6 5 4 3 2 1 0 9 8 7 6	5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0

Hinweis The bits in dwIoControlCode parameter displayed in the table must be read vertically from top to bottom by column. So the left-most bit is bit 31, the next bit is bit 30, and the right-most bit is bit 0.

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

O is set if the output buffer is valid for the code, as with IOC_OUT. Control codes using both input and output buffers set both I and O.

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

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

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

1 The IOCTL is a generic Windows Sockets 2 IOCTL code. New IOCTL codes defined for Windows Sockets 2 will have T == 1.

2 The IOCTL applies only to a specific address family.

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

Vendor/Address family An 11-bit quantity that defines the vendor who owns the code (if T == 3) or that contains the address family to which the code applies (if T == 2). If this is a Unix IOCTL code (T == 0) then this parameter has the same value as the code on Unix. If this is a generic Windows Sockets 2 IOCTL (T == 1) then this parameter can be used as an extension of the code parameter to provide additional code values.

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

The following Unix IOCTL codes (commands) are supported.

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

The WSAAsyncSelect or WSAEventSelect routine automatically sets a socket to non-blocking mode. If WSAAsyncSelect or WSAEventSelect has been issued on a socket, then any attempt to use WSAIoctl to set the socket back to blocking mode will fail 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 zero, or disable WSAEventSelect by calling WSAEventSelect with the lNetworkEvents parameter equal to zero.
FIONREAD
Determine the amount of data that can be read atomically from socket s. The lpvOutBuffer parameter points at an unsigned long in which WSAIoctl stores the result.

If the socket passed in the s parameter is stream oriented (for example, type SOCK_STREAM), FIONREAD returns the total amount of data that can be read in a single receive operation; this is normally the same as the total amount of data queued on the socket (since a data stream is byte-oriented, this is not guaranteed).

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

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 the CreatePersistentTcpPortReservation 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 of SIO_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 error WSAEWOULDBLOCK. The application can then wait for address list change events through a call to WSAEventSelect 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.

Hinweis In Windows Plug-n-Play environments, addresses can be added and removed dynamically. Therefore, applications cannot rely on the information returned by SIO_ADDRESS_LIST_QUERY to be persistent. Applications may register for address change notifications through the SIO_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 in Winsock Annexes for details specific to a particular companion interface. The total size is reflected in the input buffer length. No output buffer is required. The WSAENOPROTOOPT error code is indicated for service providers that do not support this IOCTL. The handle associated by this IOCTL can be retrieved using SIO_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. The SIO_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 a SOCKET.

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 a SOCKET) 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 the WSASendMsg function.

If the output buffer is not large enough for a socket handle (the cbOutBuffer is less than the size of a SOCKET) 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 the select function.

If the output buffer is not large enough for a socket handle (the cbOutBuffer is less than the size of a SOCKET) 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 a NULL pointer. The returned value is a SOCKET.

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

If the output buffer is not large enough for a socket handle (the cbOutBuffer is less than the size of a SOCKET), the lpvOutBuffer parameter is a NULL pointer, or the lpOverlapped parameter is not a NULL pointer, SOCKET_ERROR is returned as the result of this IOCTL and WSAGetLastError 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 (see How 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. The WSAENOPROTOOPT 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 a sockaddr 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. The WSAENOPROTOOPT 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 the Mswsock.h header file. The possible value for these GUIDs are as follows:

Benennung	Beschreibung
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. The QOS structure will be copied into the output buffer. If this socket does not belong to an appropriate socket group, the SendingFlowspec and ReceivingFlowspec members of the returned QOS 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 of INTERFACE_INFO structures.

Hinweis 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 of INTERFACE_INFO structures for unicast IP addresses on the interfaces. The cbOutBuffer parameter specifies the length of the output buffer. The number of interfaces returned (number of structures returned in the buffer pointed to by lpvOutBuffer parameter) can be determined based on the actual length of the output buffer returned in lpcbBytesReturned parameter.

If the WSAIoctl function is called with SIO_GET_INTERFACE_LIST and the level member of the socket s parameter is not defined as IPPROTO_IP, WSAEINVAL is returned. A call to the WSAIoctl function with SIO_GET_INTERFACE_LIST returns WSAEFAULT 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 of INTERFACE_INFO_EX structures.

The lpvOutBuffer parameter points to the buffer in which to store the information about interfaces as an array of INTERFACE_INFO_EX structures for unicast IP addresses on the interface. The cbOutBuffer parameter specifies the length of the output buffer. The number of interfaces returned (number of structures returned in lpvOutBuffer) can be determined based on the actual length of the output buffer returned in lpcbBytesReturned 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. The QOS structure will be copied into the output buffer. The output buffer must be sized large enough to be able to contain the full QOS 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 mit Service Pack 1 (SP1), and later versions of the operating system. The SIO_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 mit 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. The SIO_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 mit 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 the Requirements for Internet Hosts—Communication Layers specified in RFC 1122 available at the IETF 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, the getsockopt function can be called with the SO_KEEPALIVE option. To enable or disable TCP keep-alive, the setsockopt 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 using SIO_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 of TRUE causes multicast data sent by an application on the local computer to be delivered to a listening socket on the loopback interface. A value of FALSE 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 for SIO_QUERY_RSS_SCALABILITY_INFO is specified in the RSS_SCALABILITY_INFO structure defined in the Mstcpip.h header file. This structure is defined as follows:
```
// Scalability info for the transport
typedef 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 (the cbOutBuffer is less than the size of a RSS_SCALABILITY_INFO) or the lpvOutBuffer parameter is a NULL pointer, SOCKET_ERROR is returned as the result of this IOCTL and WSAGetLastError 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 a UINT64) 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 the WSAIoctl 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 to INADDR_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 the SIO_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 with SIO_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 the RCVALL_VALUE enumeration defined in the Mstcpip.h header file. The possible values for SIO_RCVALL are as follows:

Benennung	Beschreibung
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 the WSAIoctl 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 the WSAIoctl 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 the SIO_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 a sockaddr 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 of SIO_ROUTING_INTERFACE_CHANGE request. Alternatively, if the SIO_ROUTING_INTERFACE_CHANGE IOCTL is issued on a non-blocking socket with the lpOverlapped 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 to WSAEventSelect 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 in bind call when requesting to bind to any available address) to request notifications of any routing changes. This allows the application to keep only one outstanding SIO_ROUTING_INTERFACE_CHANGE for all the sockets and destinations it has and then use SIO_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 the SIO_ROUTING_INTERFACE_CHANGE (as though the application specified a wildcard address) and complete the SIO_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 (as sockaddr). 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 by SIO_ROUTING_INTERFACE_QUERY to be persistent. Applications may register for routing change notifications through the SIO_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 and WSAGetLastError 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 the lpvInBuffer, 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 and WSAGetLastError 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 for SIO_SET_COMPATIBILITY_MODE is specified in the WSA_COMPATIBILITY_MODE structure defined in the Mswsockdef.h header file. This structure is defined as follows:

/* 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 the TargetOsVersion 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 the BehaviorId member are as follows

Benennung	Beschreibung
WsaBehaviorAll	This is equivalent to requesting all of the possible compatible behaviors defined for WSA_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 the SO_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 the SO_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.

WsaBehaviorAll

This is equivalent to requesting all of the possible compatible behaviors defined for WSA_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 the SO_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 the SO_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, the QOS 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 in Winsock Annexes for details specific to a particular companion interface. The WSAENOPROTOOPT error code is indicated for service providers that do not support this IOCTL for the specified companion interface. This IOCTL retrieves the handle associated using SIO_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 to TRUE to enable reporting. Set to FALSE to disable reporting.

If an overlapped operation completes immediately, WSAIoctl returns a value of zero and the lpcbBytesReturned 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 code WSA_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 the cbTransferred parameter in the completion routine (if specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult.

When called with an overlapped socket, the lpOverlapped parameter must be valid for the duration of the overlapped operation. The lpOverlapped 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 use WSAWaitForMultipleEvents or WSAGetOverlappedResult to wait or poll on the event object.

Hinweis 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. See ExitThread 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-NULL lpCompletionRoutine and later calls WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait parameter for that invocation of WSAGetOverlappedResult to TRUE. In this case, the usage of the hEvent parameter is undefined, and attempting to wait on the hEvent parameter would produce unpredictable results.

The prototype of the completion routine is as follows:


void CALLBACK CompletionRoutine(
  IN DWORD dwError, 
  IN DWORD cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD dwFlags 
);

This CompletionRoutine is a placeholder for an application-defined or library-defined function. The completion routine is invoked only if the thread is in an alertable state. To put a thread into an alertable state, use the WSAWaitForMultipleEvents, WaitForSingleObjectEx, or WaitForMultipleObjectsEx function with the fAlertable or bAlertable parameter set to TRUE.

The dwError parameter of CompletionRoutine specifies the completion status for the overlapped operation as indicated by lpOverlapped. The cbTransferred parameter specifies the number of bytes returned. Currently, no flag values are defined and dwFlags will be zero. The CompletionRoutine function does not return a value.

Returning from this function allows invocation of another pending completion routine for this socket. The completion routines can be called in any order, not necessarily in the same order the overlapped operations are completed.

Compatibility

The IOCTL codes with T == 0 are a subset of the IOCTL codes used in Berkeley sockets. In particular, there is no command that is equivalent to FIOASYNC.

Hinweis Some IOCTL codes require additional header files. For example, use of the SIO_RCVALL IOCTL requires the Mstcpip.h header file.

Anforderungen

Mindestens unterstützter Client	Windows 2000 Professional
Mindestens unterstützter Server	Windows 2000 Server
Header	Winsock2.h; Mstcpip.h
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll