WPUCreateSocketHandle 函式 (ws2spi.h)

發行項
08/28/2023

WPUCreateSocketHandle函式會建立新的通訊端控制碼。

語法

SOCKET WPUCreateSocketHandle(
  [in]  DWORD     dwCatalogEntryId,
  [in]  DWORD_PTR dwContext,
  [out] LPINT     lpErrno
);

參數

[in] dwCatalogEntryId

識別呼叫服務提供者的描述項。

[in] dwContext

要與新通訊端控制碼建立關聯的內容值。

[out] lpErrno

錯誤碼的指標。

傳回值

如果沒有發生錯誤， WPUCreateSocketHandle 會傳回新的通訊端控制碼。否則，它會傳回INVALID_SOCKET，而且 lpErrno中提供特定的錯誤碼。

錯誤碼	意義
WSAENOBUFS	沒有足夠的緩衝區可用來建立新的通訊端控制碼。

備註

WPUCreateSocketHandle函式會為指定的提供者建立新的通訊端控制碼。 WPUCreateSocketHandle所建立的控制碼與真正的檔案系統控制碼不相同。這在兩方面很重要。首先，Windows Socket 2 架構負責將檔案系統函式 ReadFile 和 WriteFile 分別重新導向至此服務提供者的 LPWSPRecv 和 LPWSPSend 函式。其次，在支援完成埠的作業系統中，Windows Sockets 2 架構支援將完成埠與通訊端控制碼建立關聯，並用它來報告重迭的 I/O 完成。

**注意** 重新導向 ReadFile 和 WriteFile 的機制一定牽涉到使用者對核心轉換以取得重新導向器，後面接著核心對使用者轉換，以取得 [LPWSPRecv] (nc-ws2spi-lpwsprecv.md) 或 [LPWSPSend] (nc-ws2spi-lpwspsend.md) 。傳回時，這些轉換會反向撤銷。這可能會造成顯著的效能負面影響。任何使用 **WPUCreateSocketHandle** 來建立其通訊端控制碼的服務提供者，不應該在其 WSAProtocol_Info 結構中設定XP1_IFS_HANDLES。用戶端應採用XP1_IFS_HANDLES，以避免使用 **ReadFile** 和 **WriteFile**。

**注意** 使用完成埠機制搭配使用使用 **WPUCreateSocketHandle** 建立的通訊端控制碼時，不會有例外的效能負面影響。服務提供者應該使用 WPUCompleteOverlappedRequest 來宣告可能涉及完成埠的重迭 I/O 作業完成。用戶端可以自由使用作業系統函式來建立、建立、關聯及使用完成埠，以取得完成通知 (例如 CreateIoCompletionPort、 GetQueuedCompletionStatus，請參閱相關的作業系統檔以取得詳細資料) 。請注意，完成埠不會與 Windows Sockets 2 所提供的其他非同步通知機制整合。也就是說，用戶端可以執行包含多個事件和完成回呼的多重等候，但是沒有預先定義的方式來讓多等候包含完成埠。

**分層服務提供者考慮**

此程式對分層服務提供者特別感興趣。分層服務提供者可能會使用此程式，而不是 WPUModifyIFSHandle 來建立它向其用戶端公開的通訊端控制碼。使用此程式的優點是，可以保證所有涉及通訊端的 I/O 要求都能通過此服務提供者。即使用戶端假設通訊端是檔案系統控制碼，並呼叫檔案系統函式 ReadFile 和 WriteFile (，但此假設會支付效能損失) 。

保證所有 I/O 都會通過此層，這是在實際 I/O 作業之前或之後處理 I/O 資料流程所需的層需求。使用 WPUCreateSocketHandle 建立通訊端控制碼，並在 WSPStartup 時指定適當的服務提供者介面過程分派資料表，可確保圖層有機會開始每個 I/O 作業。當用戶端要求重迭的 I/O 作業時，此服務提供者層通常必須安排以進入 I/O 完成通知的路徑。

若要查看原因，請考慮如果用戶端將完成埠與通訊端控制碼產生關聯，以達到重迭 I/O 完成通知的目的，會發生什麼事。埠與這個層公開的通訊端控制碼相關聯，而不是下一層的通訊端控制碼。此層無法判斷完成埠是否已相關聯或埠是什麼。當此層呼叫下一層的 I/O 作業時，它會使用下一層的通訊端控制碼。下一層的通訊端控制碼不會有相同的完成埠關聯。用戶端的預期完成埠通知不會發生，而不會有一些額外的協助。

分層服務提供者處理此作業的一般方式，是在下一層叫用 I/O 作業時，替代不同的重迭 I/O 結構和不同的重迭 I/O 參數。替代的重迭 I/O 結構會參考用戶端儲存的重迭結構和參數。下一層的調用會設定回呼通知。發生回呼通知時，此層會執行任何所需的後續處理、擷取代表用戶端儲存的重迭 I/O 資訊、捨棄替代結構，並將適當的完成通知轉送給用戶端。

規格需求


最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	ws2spi.h