PFN_WSK_CONTROL_SOCKET回呼函式 (wsk.h)

發行項
03/01/2024

WskControlSocket 函式會在套接字上執行控制作業。

語法

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
)
{...}

參數

[in] Socket

WSK_SOCKET 結構的指標，指定執行控件作業所在套接字的套接字物件。

[in] RequestType

值，指定正在執行的控制項作業類型。 WSK 應用程式會將此參數設定為下列其中一個值：

WskSetOption

設定套接字選項的狀態或值。

WskGetOption

取得套接字選項的狀態或值。

WskIoctl

執行 I/O 控制作業。

[in] ControlCode

如果 RequestType 參數設定為 WskSetOption 或 WskGetOption，ControlCode 參數會指定要設定或擷取其值的特定套接字選項。如需 WSK 子系統所支援套接字選項的詳細資訊，請參閱 WSK 套接字選項。基礎網路協定可能支援其他套接字選項。

如果 RequestType 參數設定為 WskIoctl，ControlCode 參數會指定正在執行的特定 I/O 控制作業。如需 WSK 子系統所支援之 I/O 控制作業的詳細資訊，請參閱 WSK 套接字 IOCTL 作業。基礎網路協定可能支持額外的套接字 I/O 控制作業。

[in] Level

網路堆疊中的層級，其中套接字選項的值正在設定或擷取。針對 WSK 子系統層級套接字選項，WSK 應用程式應該將此參數設定為 SOL_SOCKET。針對傳輸通訊協定或網路協定層級套接字選項，WSK 應用程式應該將此參數設定為基礎傳輸的適當層級。

如果 RequestType 參數設定為 WskIoctl， 則會忽略 Level 參數。

[in] InputSize

InputBuffer 參數所指向之緩衝區中的數據位元組數目。

[in, optional] InputBuffer

呼叫端配置的緩衝區，提供執行指定之控制作業所需的任何輸入數據。如果指定的控制作業不需要輸入數據，WSK 應用程式應該將此參數設定為 NULL ，並將 InputSize 參數設定為零。

[in] OutputSize

OutputBuffer 參數所指向的緩衝區大小。

[out, optional] OutputBuffer

呼叫端配置的緩衝區，接收指定之控制作業所傳回的任何輸出數據。如果指定的控制作業未傳回任何輸出數據，WSK 應用程式應該將此參數設定為 NULL ，並將 OutputSize 參數設定為零。

[out, optional] OutputSizeReturned

ULONG 型別變數的指標，接收 OutputBuffer 參數所指向之緩衝區中傳回的數據位元組數目。 WSK 應用程式應該將 OutputSizeReturned 參數設定為 NULL ，除非下列所有專案都成立：

Irp 參數設定為 NULL。
正在執行的作業會傳回 OutputBuffer 參數所指向之緩衝區中的輸出數據。
正在執行的作業所傳回的輸出數據位元組數目未知。

[in, out] Irp

WSK 子系統用來以異步方式完成控制作業的呼叫端配置 IRP 指標。如需搭配 WSK 函式使用 IRP 的詳細資訊，請參閱搭配 Winsock 核心函式使用 IRP。

如果 RequestType 參數設定為 WskSetOption 或 WskGetOption，則 Irp 參數是必要參數、是選擇性的，或必須是 NULL，視要設定或擷取的特定套接字選項而定。如需每個支援套接字選項之 Irp 參數需求的詳細資訊，請參閱 WSK 套接字選項。

如果 RequestType 參數設定為 WskIoctl， 則 Irp 參數是必要的、是選擇性的，或必須根據所執行的特定 I/O 控制作業為 NULL 。如需每個支援 I/O 控制作業之 Irp 參數需求的詳細資訊，請參閱 WSK 套接字 IOCTL 作業。

傳回值

WskControlSocket 會傳回下列其中一個 NTSTATUS 代碼：

傳回碼	Description
STATUS_SUCCESS	控制作業已順利完成。如果 WSK 應用程式在 Irp 參數中指定了 IRP 的指標，則 IRP 將會以成功狀態完成，而 OutputBuffer 參數所指向的緩衝區中傳回的位元組數目將會在 IRP 的 IoStatus.Information 字段中傳回。
STATUS_PENDING	WSK 子系統無法立即完成控制作業。 WSK 子系統會在完成控制作業之後完成 IRP。控制作業的狀態將會在 IRP 的 [IoStatus.Status ] 字段中傳回。如果作業成功，輸出Buffer 參數所指向之緩衝區中傳回的位元組數目將會在 IRP 的 IoStatus.Information 欄位中傳回。
STATUS_EVENT_PENDING	WSK 子系統無法立即完成控制作業。只有在 WSK 應用程式在套接字上停用事件回呼函式時，才會傳回此值，當目前對該事件回呼函式進行中呼叫，以及 Irp 參數為 NULL 時。如需停用事件回呼函式的詳細資訊，請參閱 SO_WSK_EVENT_CALLBACK。
STATUS_FILE_FORCED_CLOSED	套接字已不再運作。 IRP 將會以失敗狀態完成。 WSK 應用程式必須呼叫 WskCloseSocket 函式，才能儘快關閉套接字。
其他狀態代碼	發生錯誤。 IRP 將會以失敗狀態完成。

備註

如果 WSK 應用程式在 RequestType 參數中指定 WskSetOption 或 WskGetOption，請參閱 WSK 套接字選項，以取得每個套接字選項如何使用輸入和輸出緩衝區的詳細資訊。

如果 WSK 應用程式在 RequestType 參數中指定 WskIoctl，請參閱 WSK 套接字 IOCTL 作業，以取得輸入和輸出緩衝區如何用於每個 I/O 控制作業的詳細資訊。

如果 WskControlSocket 函式傳回STATUS_PENDING，則 InputBuffer 參數或 OutputBuffer 參數所指向的任何緩衝區都必須維持有效狀態，直到 IRP 完成為止。如果 WSK 應用程式已使用其中一個 ExAllocateXxx 函式配置緩衝區，則在 IRP 完成之後，才能釋放具有對應 ExFreeXxx 函式的記憶體。如果 WSK 應用程式配置堆疊上的緩衝區，它就無法從呼叫 WskControlSocket 函式的函式傳回，直到 IRP 完成之後為止。

WskControlSocket 函式的呼叫端必須在 IRQL <= DISPATCH_LEVEL執行，除非 RequestType 參數設定為 WskIoctl 且 ControlCode 參數設定為 SIO_ADDRESS_LIST_QUERY、SIO_ADDRESS_LIST_CHANGE 或 SIO_ADDRESS_LIST_SORT。在此情況下，呼叫端必須在 IRQL = PASSIVE_LEVEL上執行。

規格需求

需求	值
最低支援的用戶端	可在 Windows Vista 和更新版本的 Windows 作業系統中使用。
目標平台	Universal
標頭	wsk.h (包含 Wsk.h)
IRQL	<= DISPATCH_LEVEL (请参阅一节)