共用方式為


PFN_WSK_CONTROL_SOCKET回呼函式 (wsk.h)

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 參數設定為 WskSetOptionWskGetOption,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 參數中指定 WskSetOptionWskGetOption,請參閱 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 參數設定為 WskIoctlControlCode 參數設定為 SIO_ADDRESS_LIST_QUERYSIO_ADDRESS_LIST_CHANGESIO_ADDRESS_LIST_SORT。 在此情況下,呼叫端必須在 IRQL = PASSIVE_LEVEL上執行。

規格需求

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

另請參閱

WSK 套接字 IOCTL 作業

WSK 套接字選項

WSK_PROVIDER_BASIC_DISPATCH

WSK_PROVIDER_CONNECTION_DISPATCH WSK_PROVIDER_DATAGRAM_DISPATCH

WSK_PROVIDER_LISTEN_DISPATCH

WskCloseSocket

WskSocket