LPWSPIOCTL callback function (ws2spi.h)

Article
08/23/2022

The LPWSPIoctl function controls the mode of a socket.

Syntax

LPWSPIOCTL Lpwspioctl;

int Lpwspioctl(
  [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,
  [in]  LPWSATHREADID lpThreadId,
  [in]  LPINT lpErrno
)
{...}

Parameters

[in] s

A descriptor identifying a socket.

[in] dwIoControlCode

The control code of the operation to perform.

[in] lpvInBuffer

A pointer to the input buffer.

[in] cbInBuffer

The size, in bytes, of the input buffer.

[out] lpvOutBuffer

A pointer to the output buffer.

[in] cbOutBuffer

The size, in bytes, of the output buffer.

[out] lpcbBytesReturned

A pointer to actual number of bytes of output.

[in] lpOverlapped

A pointer to a WSAOverlapped structure (ignored for non-overlapped sockets).

[in] lpCompletionRoutine

Type: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

A pointer to the completion routine called when the operation has been completed (ignored for non-overlapped sockets). See Remarks.

[in] lpThreadId

A pointer to a WSATHREADID structure to be used by the provider in a subsequent call to WPUQueueApc. The provider should store the referenced WSATHREADID structure (not the pointer) until after the WPUQueueApc function returns.

[in] lpErrno

A pointer to the error code.

Return value

If no error occurs and the operation has completed immediately, LPWSPIoctl returns zero. Note that in this case the completion routine, if specified, will have already been queued. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code is available in lpErrno. The error code WSA_IO_PENDING indicates that an overlapped operation has been successfully initiated and that completion will be indicated at a later time. Any other error code indicates that no overlapped operation was initiated and no completion indication will occur.

Error code	Meaning
WSA_IO_PENDING	An overlapped operation was successfully initiated and completion will be indicated at a later time.
WSAEFAULT	The lpvInBuffer, lpvOutBuffer or lpcbBytesReturned 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 is not a valid command, or a supplied input parameter is not acceptable, or the command is not applicable to the type of socket supplied.
WSAEINPROGRESS	The function is invoked when a callback is in progress.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor s is not a socket.
WSAEOPNOTSUPP	The specified IOCTL command cannot be realized. For example, the flow specifications specified in SIO_SET_QOS cannot be satisfied.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the requested operation would block.

Remarks

This routine 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 nonoverlapped socket.

For non-overlapped sockets, lpOverlapped and lpCompletionRoutine parameters are ignored and this function can block if socket s is in blocking mode. Note that if socket s is in nonblocking mode, this function can return WSAEWOULDBLOCK if the specified operation cannot be finished immediately. In this case, the Windows Sockets SPI client 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 case of SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE) using Windows message (through LPWSPAsyncSelect or event (using LPWSPEventSelect) 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 implementation of the service provider. If the Windows Sockets SPI client cannot tolerate blocking in a LPWSPIoctl call, overlapped I/O would be advised for IOCTLs that are most 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 particularly likely to block. Check the relevant protocol-specific annex for available information.

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

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.

In as much as the dwIoControlCode parameter is now a 32-bit entity, it is possible to adopt an encoding scheme that provides a convenient way to partition the opcode identifier space. The dwIoControlCode parameter is constructed to allow for protocol and vendor independence when adding new control codes, while retaining backward compatibility with Windows Sockets 1.1 and UNIX control codes. The dwIoControlCode parameter has the following form.

bit 31	bit 30	bit 29	bits 28 and 27	bits 26 thru 16	bits 15 thru 0
I	O	V	T	Vendor/Address family	Code

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. Note that for codes with both input and output parameters, both I and O will be set.

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

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

0 indicates that the IOCTL is a standard UNIX IOCTL code, as with FIONREAD, FIONBIO, and so on.
1 indicates that the IOCTL is a generic Windows Sockets 2 IOCTL code. New IOCTL codes defined for Windows Sockets 2 will have T == 1.
2 indicates that the IOCTL applies only to a specific address family.
3 The IOCTL applies only to a specific vendor's provider. This type allows companies to be assigned a vendor number that appears in the Vendor/Address family member. 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 is 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 member has the same value as the code on UNIX. If this is a generic Windows Sockets 2 IOCTL (T == 1) then this member can be used as an extension of the code member to provide additional code values.

Code is the specific IOCTL code for the operation.

The following UNIX commands are supported:

FIONBIO

Enables or disables nonblocking mode on socket s. The lpvInBuffer parameter points at an unsigned long, which is nonzero if nonblocking 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, nonblocking mode is disabled). This is consistent with Berkeley Software Distribution (BSD) sockets.

The LPWSPAsyncSelect or LPWSPEventSelect routine automatically sets a socket to nonblocking mode. If LPWSPAsyncSelect or LPWSPEventSelect has been issued on a socket, then any attempt to use LPWSPIoctl to set the socket back to blocking mode will fail with WSAEINVAL. To set the socket back to blocking mode, a Windows Sockets SPI client must first disable LPWSPAsyncSelect by calling LPWSPAsyncSelect with the lEvent parameter equal to zero, or disable LPWSPEventSelect by calling LPWSPEventSelect 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

Determines 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 Windows Sockets SPI client should use the SIOCATMARK operation to determine whether any remains. If there is any normal data preceding the urgent (OOB) data, it will be received in order. (Note that receive operations will never mix OOB and normal data in the same call.) lpvOutBuffer points at a BOOL in which LPWSPIoctl 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: T==1)

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

It is assumed (although not required) that the Windows Sockets SPI client 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 nonblocking socket and without overlapped parameters (lpOverlapped and lpCompletionRoutine are set to NULL), it will complete immediately with error WSAEWOULDBLOCK. The Windows Sockets SPI client can then wait for address list change events through a call to LPWSPEventSelect or LPWSPAsyncSelect with the 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 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)

Associates 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 the Windows Sockets 2 Protocol-Specific Annex and/or documentation for the particular companion interface for additional details. (These resources may only be available in English.) 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:

A great deal of additional control over the behavior of a socket.
Provider-specific controls that do not map to existing Windows Socket functions (or those likely for the future).

It is recommended 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_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 should 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.

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.

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 a 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), that 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 LPWSPSendTo.

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:

Term	Description
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 LPFN_WSARECVMSG (WSARecvMsg) extension function.
WSAID_WSASENDMSG	The WSASendMsg extension function.

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

Reserved.

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.

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

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

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

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 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 the Requirements for Internet Hosts—Communication Layers specified in RFC 1122 available at the IETF website.

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 acknowledgment 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: I, 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, SIO_MULTIPOINT_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 1 (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.

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.

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

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. In Windows Vista, WFP focuses on scenarios where the host machine is the communication endpoint. In 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_QUERY_PNP_TARGET_HANDLE (opcode setting: O, T==1)

To obtain the socket descriptor of the next provider in the chain on which the current socket depends in PnP sense. This IOCTL is invoked by the Windows Sockets 2 DLL only on sockets of non-IFS service providers created through WPUCreateSocketHandle call. The provider should return in the output buffer the socket handle of the next provider in the chain on which a given socket handle depends in PnP sense (for example, the removal of the device that supports the underlying handle will result in the invalidation of the handle above it in the chain).

If an overlapped operation completes immediately, this function 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 LPWSPGetOverlappedResult.

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

Enables a socket to receive all IPv4 or IPv6 packets passing through 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:

Term	Description
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_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 with error WSAEWOULDBLOCK and the Windows Socket SPI client can then wait for routing change events using a call to LPWSPEventSelect or LPWSPAsyncSelect with the 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 Windows Sockets SPI client 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 Windows Sockets SPI client 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.

The service provider can opt to ignore the information supplied by the Windows Sockets SPI client in the input buffer of the SIO_ROUTING_INTERFACE_CHANGE (as though the Windows Sockets SPI client 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) that 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, Windows Socket SPI clients cannot rely on the information returned by SIO_ROUTING_INTERFACE_QUERY to be persistent. SPI clients may register for routing change notifications using 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 Windows Socket SPI client 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 WinSock SPI client 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 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:

} 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

Term	Description
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 supplied 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 the Windows Sockets 2 Protocol-Specific Annex and/or documentation for the particular companion interface for additional details. 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 recommended that 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.

When called with an overlapped socket, the lpOverlapped parameter must be valid for the duration of the overlapped operation.

If the lpCompletionRoutine parameter is NULL, the service provider signals the hEvent member of lpOverlapped when the overlapped operation completes if it contains a valid event object handle. The Windows Sockets SPI client can use LPWSPGetOverlappedResult to poll or wait on the event object.

If lpCompletionRoutine is not NULL, the hEvent member is ignored and can be used by the Windows Sockets SPI client to pass context information to the completion routine. A client 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 member is undefined, and attempting to wait on the hEvent member would produce unpredictable results.

It is the service provider's responsibility to arrange for invocation of the client specified–completion routine when the overlapped operation completes. Since the completion routine must be executed in the context of the same thread that initiated the overlapped operation, it cannot be invoked directly from the service provider. The WS2_32.DLL offers an asynchronous procedure call (APC) mechanism to facilitate invocation of completion routines.

A service provider arranges for a function to be executed in the proper thread and process context by calling WPUQueueApc. This function can be called from any process and thread context, even a context different from the thread and process that was used to initiate the overlapped operation.

WPUQueueApc takes as input parameters a pointer to a WSATHREADID structure (supplied to the provider through the lpThreadId input parameter), a pointer to an APC function to be invoked, and a 32-bit context value that is subsequently passed to the APC function. Because only a single 32-bit context value is available, the APC function itself cannot be the client specified–completion routine. The service provider must instead supply a pointer to its own APC function that uses the supplied context value to access the needed result information for the overlapped operation, and then invokes the client specified–completion routine.

The prototype for the client-supplied completion routine is as follows:

);

CompletionRoutine is a placeholder for a client supplied function. The dwError specifies the completion status for the overlapped operation as indicated by lpOverlapped. The cbTransferred specifies the number of bytes returned. Currently, there are no flag values defined and dwFlags will be zero. This 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, though not necessarily in the same order that 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.

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. See ExitThread for more information.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	ws2spi.h

LPWSPIOCTL callback function (ws2spi.h)

Syntax

Parameters

Return value

Remarks

Compatibility

Requirements

See also

Feedback

Feedback

Additional resources