PFN_WSK_CONTROL_SOCKET callback function (wsk.h)

Article
10/21/2021

The WskControlSocket function performs control operations on a socket.

Syntax

PFN_WSK_CONTROL_SOCKET PfnWskControlSocket;

NTSTATUS PfnWskControlSocket(
  [in]            PWSK_SOCKET Socket,
  [in]            WSK_CONTROL_SOCKET_TYPE RequestType,
  [in]            ULONG ControlCode,
  [in]            ULONG Level,
  [in]            SIZE_T InputSize,
  [in, optional]  PVOID InputBuffer,
  [in]            SIZE_T OutputSize,
  [out, optional] PVOID OutputBuffer,
  [out, optional] SIZE_T *OutputSizeReturned,
  [in, out]       PIRP Irp
)
{...}

Parameters

[in] Socket

A pointer to a WSK_SOCKET structure that specifies the socket object for the socket on which the control operation is being performed.

[in] RequestType

A value that specifies the type of control operation that is being performed. A WSK application sets this parameter to one of the following values:

WskSetOption

Set the state or value for a socket option.

WskGetOption

Get the state or value of a socket option.

WskIoctl

Perform an I/O control operation.

[in] ControlCode

If the RequestType parameter is set to WskSetOption or WskGetOption, the ControlCode parameter specifies the particular socket option whose value is being set or retrieved. For more information about socket options that are supported by the WSK subsystem, see WSK Socket Options. The underlying network protocol might support additional socket options.

If the RequestType parameter is set to WskIoctl, the ControlCode parameter specifies the particular I/O control operation that is being performed. For more information about I/O control operations that are supported by the WSK subsystem, see WSK Socket IOCTL Operations. The underlying network protocol might support additional socket I/O control operations.

[in] Level

The level in the network stack at which the value for a socket option is being either set or retrieved. For WSK subsystem level socket options, the WSK application should set this parameter to SOL_SOCKET. For transport protocol or network protocol level socket options, the WSK application should set this parameter to the appropriate level for the underlying transport.

If the RequestType parameter is set to WskIoctl, the Level parameter is ignored.

[in] InputSize

The number of bytes of data in the buffer that is pointed to by the InputBuffer parameter.

[in, optional] InputBuffer

A caller-allocated buffer that supplies any input data that is required to perform the specified control operation. If no input data is required for the specified control operation, the WSK application should set this parameter to NULL and set the InputSize parameter to zero.

[in] OutputSize

The size of the buffer that is pointed to by the OutputBuffer parameter.

[out, optional] OutputBuffer

A caller-allocated buffer that receives any output data that is returned by the specified control operation. If no output data is returned by the specified control operation, the WSK application should set this parameter to NULL and set the OutputSize parameter to zero.

[out, optional] OutputSizeReturned

A pointer to a ULONG-typed variable that receives the number of bytes of data that is returned in the buffer that is pointed to by the OutputBuffer parameter. A WSK application should set the OutputSizeReturned parameter to NULL except when all of the following are true:

The Irp parameter is set to NULL.
The operation that is being performed returns output data in the buffer that is pointed to by the OutputBuffer parameter.
The number of bytes of output data that is returned by the operation that is being performed is unknown.

[in, out] Irp

A pointer to a caller-allocated IRP that the WSK subsystem uses to complete the control operation asynchronously. For more information about using IRPs with WSK functions, see Using IRPs with Winsock Kernel Functions.

If the RequestType parameter is set to either WskSetOption or WskGetOption, the Irp parameter is required, is optional, or must be NULL depending on the particular socket option that is being set or retrieved. For more information about the requirements for the Irp parameter for each of the supported socket options, see WSK Socket Options.

If the RequestType parameter is set to WskIoctl, the Irp parameter is required, is optional, or must be NULL depending on the particular I/O control operation that is being performed. For more information about the requirements for the Irp parameter for each of the supported I/O control operations, see WSK Socket IOCTL Operations.

Return value

WskControlSocket returns one of the following NTSTATUS codes:

Return code	Description
STATUS_SUCCESS	The control operation completed successfully. If the WSK application specified a pointer to an IRP in the Irp parameter, the IRP will be completed with success status, and the number of bytes that is returned in the buffer that is pointed to by the OutputBuffer parameter will be returned in the IoStatus.Information field of the IRP.
STATUS_PENDING	The WSK subsystem could not complete the control operation immediately. The WSK subsystem will complete the IRP after it has completed the control operation. The status of the control operation will be returned in the IoStatus.Status field of the IRP. If the operation succeeds, the number of bytes that is returned in the buffer that is pointed to by the OutputBuffer parameter will be returned in the IoStatus.Information field of the IRP.
STATUS_EVENT_PENDING	The WSK subsystem could not complete the control operation immediately. This value is returned only when a WSK application is disabling an event callback function on a socket when there are currently in-progress calls to that event callback function and when the Irp parameter is NULL. For more information about disabling event callback functions, see SO_WSK_EVENT_CALLBACK.
STATUS_FILE_FORCED_CLOSED	The socket is no longer functional. The IRP will be completed with failure status. The WSK application must call the WskCloseSocket function to close the socket as soon as possible.
Other status codes	An error occurred. The IRP will be completed with failure status.

Remarks

If a WSK application specifies WskSetOption or WskGetOption in the RequestType parameter, see WSK Socket Options for more information about how the input and output buffers are used for each socket option.

If a WSK application specifies WskIoctl in the RequestType parameter, see WSK Socket IOCTL Operations for more information about how the input and output buffers are used for each I/O control operation.

If the WskControlSocket function returns STATUS_PENDING, any buffers that are pointed to by the InputBuffer parameter or the OutputBuffer parameter must remain valid until the IRP is completed. If the WSK application allocated the buffers with one of the ExAllocateXxx functions, it cannot free the memory with the corresponding ExFreeXxx function until after the IRP is completed. If the WSK application allocated the buffers on the stack, it cannot return from the function that calls the WskControlSocket function until after the IRP is completed.

Callers of the WskControlSocket function must be running at IRQL <= DISPATCH_LEVEL except when the RequestType parameter is set to WskIoctl and the ControlCode parameter is set to SIO_ADDRESS_LIST_QUERY, SIO_ADDRESS_LIST_CHANGE, or SIO_ADDRESS_LIST_SORT. In this situation, callers must be running at IRQL = PASSIVE_LEVEL.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of the Windows operating systems.
Target Platform	Universal
Header	wsk.h (include Wsk.h)
IRQL	<= DISPATCH_LEVEL (see Remarks section)