SIO_QUERY_TRANSPORT_SETTING control code

The SIO_QUERY_TRANSPORT_SETTING control code queries the transport settings on a socket.

To perform this operation, call the WSAIoctl or WSPIoctl function with the following parameters.


int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,     // pointer to the output buffer
  (DWORD) cbOutBuffer,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);


int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,     // pointer to the output buffer
  (DWORD) cbOutBuffer,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure 
  (LPINT) lpErrno   // a pointer to the error code.
);

Parameters

s

A descriptor identifying a socket.

dwIoControlCode

The control code for the operation. Use SIO_QUERY_TRANSPORT_SETTING for this operation.

lpvInBuffer

A pointer to the input buffer. This parameter contains a pointer to a structure where the first member of the structure is a TRANSPORT_SETTING_ID stucture that determines what transport setting is being queried.

cbInBuffer

The size, in bytes, of the input buffer. This parameter depends on the transport setting being queried.

lpvOutBuffer

A pointer to the output buffer. This parameter depends on the transport setting being queried if the lpOverlapped and lpCompletionRoutine parameters are NULL.

cbOutBuffer

The size, in bytes, of the output buffer.

lpcbBytesReturned

A pointer to a variable that receives the size, in bytes, of the data stored in the output buffer.

If the output buffer is too small, the call fails, WSAGetLastError returns WSAEINVAL, and the lpcbBytesReturned parameter points to a DWORD value of zero.

If lpOverlapped is NULL, the DWORD value pointed to by the lpcbBytesReturned parameter that is returned on a successful call cannot be zero.

If the lpOverlapped parameter is not NULL 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 zero since the size of the data stored can't be determined until the overlapped operation has completed. The final completion status can be retrieved when the appropriate completion method is signaled when the operation has completed.

lpvOverlapped

A pointer to a WSAOVERLAPPED structure.

If socket s was created without the overlapped attribute, the lpOverlapped parameter is ignored.

If s was opened with the overlapped attribute and the lpOverlapped parameter is not NULL, the operation is performed as an overlapped (asynchronous) operation. In this case, lpOverlapped parameter must point to a valid WSAOVERLAPPED structure.

For overlapped sockets, operations that cannot be completed immediately will be initiated, and completion will be indicated at a later time. The WSAIoctl or WSPIoctl function returns immediately, and the appropriate completion method is signaled when the operation has been completed.

Otherwise, the function does not return until the operation has been completed or an error occurs.

lpCompletionRoutine

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

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 to same) until after the WPUQueueApc function returns.

Note  This parameter applies only to the WSPIoctl function.

lpErrno

A pointer to the error code.

Note  This parameter applies only to the WSPIoctl function.

Return value

If the operation completes successfully, the WSAIoctl or WSPIoctl function returns zero.

If the operation fails or is pending, the WSAIoctl or WSPIoctl function returns SOCKET_ERROR. To get extended error information, call WSAGetLastError.

Error codeMeaning
ERROR_INSUFFICIENT_BUFFER

The data area passed to a system call is too small. This error is returned if the buffer pointed to by the lpvOutBuffer parameter with a buffer size passed in the cbOutBuffer parameter is too small. The buffer size required will be returned in the lpcbBytesReturned parameter.

WSA_IO_PENDING

An overlapped operation was successfully initiated and completion will be indicated at a later time.

WSA_OPERATION_ABORTED

An overlapped operation was canceled due to the closure of the socket or the execution of the SIO_FLUSH IOCTL command.

WSAEFAULT

The lpvOutBuffer, lpcbBytesReturned, lpOverlapped, or lpCompletionRoutine parameter is not totally contained in a valid part of the user address space.

WSAEINPROGRESS

The function is invoked when a callback is in progress.

WSAEINTR

A blocking operation was interrupted.

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.

WSAENETDOWN

The network subsystem has failed.

WSAENOPROTOOPT

The socket option is not supported on the specified protocol.

WSAENOTCONN

The socket s is not connected.

WSAENOTSOCK

The descriptor s is not a socket.

WSAEOPNOTSUPP

The specified IOCTL command is not supported. This error is returned if the SIO_QUERY_TRANSPORT_SETTING IOCTL is not supported by the transport provider.

 

Remarks

The SIO_QUERY_TRANSPORT_SETTING IOCTL is supported on Windows 8, and Windows Server 2012, and later versions of the operating system.

The SIO_QUERY_TRANSPORT_SETTING IOCTL is a generic IOCTL used to query the transport settings on a socket. The transport setting being queried is based on the TRANSPORT_SETTING_ID passed in the lpvInBuffer parameter.

The only transport setting currently defines is for the REAL_TIME_NOTIFICATION_CAPABILITY capability on a TCP socket.

If the TRANSPORT_SETTING_ID passed in the lpvInBuffer parameter has the Guid member set to REAL_TIME_NOTIFICATION_CAPABILITY, then this is a request to query the real time notification settings for the TCP socket used with the ControlChannelTrigger to receive background network notifications in a Windows Store app. The lpvInBuffer parameter should point to a TRANSPORT_SETTING_ID structure. The lpvOutBuffer parameter should point to a REAL_TIME_NOTIFICATION_SETTING_OUTPUT structure. This transport setting applies only to TCP sockets. This transport setting provides a way for WinInet or similar network services to query a given TCP socket to determine the ControlChannelTrigger status. A Windows Store app will not call this IOCTL directly. If the WSAIoctl or WSPIoctl call is successful, this IOCTL returns a REAL_TIME_NOTIFICATION_SETTING_OUTPUT structure with the current status.

The SIO_QUERY_TRANSPORT_SETTING IOCTL provides a way for WinInet or similar network services to query for the transport setting status for a given TCP socket to determine if ControlChannelTrigger is enabled on the socket. A Windows Store app will not call this IOCTL directly.

This IOCTL applies only to TCP sockets.

Requirements

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Mstcpip.h

See also

CONTROL_CHANNEL_TRIGGER_STATUS
ControlChannelTrigger
REAL_TIME_NOTIFICATION_SETTING_OUTPUT
SIO_APPLY_TRANSPORT_SETTING
socket
WSAGetLastError
WSAGetOverlappedResult
WSAIoctl
WSAOVERLAPPED
WSASocket
WSPIoctl

 

 

Community Additions

ADD
Show:
© 2014 Microsoft