SIO_TCP_INFO Control Code

Article
06/22/2021

Description

The SIO_TCP_INFO control code retrieves the Transmission Control Protocol (TCP) statistics for a specified socket.

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

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_TCP_INFO,                // dwIoControlCode
  (LPVOID) lpvInBuffer,   // pointer to a DWORD
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,         // pointer to a TCP_INFO_v0 structure
  (DWORD) cbOutBuffer,       // size of the 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_TCP_INFO,                // dwIoControlCode
  (LPVOID) lpvInBuffer,   // pointer to a DWORD
  (DWORD) cbInBuffer,           // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,         // pointer to a TCP_INFO_v0 structure
  (DWORD) cbOutBuffer,       // size of the 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 that identifies a socket.

dwIoControlCode

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

lpvInBuffer

A pointer to the input buffer. This parameter contains a pointer to a DWORD that specifies the version of the SIO_TCP_INFO control code that you are using. Specify 0 to use TCP_INFO_v0. Specify 1 to use TCP_INFO_v1, which provides more fields.

cbInBuffer

The size, in bytes, of the input buffer. This parameter should be the size of the DWORD data type.

lpvOutBuffer

A pointer to the output buffer. On successful output, this parameter contains a pointer to a TCP_INFO_v0 structure that contains the TCP statistics for the specified socket.

cbOutBuffer

The size, in bytes, of the output buffer. This parameter must be at least the size of the TCP_INFO_v0 structure.

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 operations, 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

Type: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

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 code	Meaning
WSAEMSGSIZE	The pointer to the input buffer was NULL, or the specified size of the input buffer was not correct.
WSAEINVAL	An invalid argument was supplied. This error is returned if 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.

Remarks

Unlike retrieving TCP statistics with the GetPerTcpConnectionEStats function, retrieving TCP statistics with this control code does not require the user code to load, store, and filter the TCP connection table, and does not require elevated privileges to use.