PFN_WSK_RECEIVE回呼函式 (wsk.h)

發行項
02/27/2024

WskReceive 函式會從遠端傳輸位址透過連接導向或數據流套接字接收數據。

語法

PFN_WSK_RECEIVE PfnWskReceive;

NTSTATUS PfnWskReceive(
  [in]      PWSK_SOCKET Socket,
  [in]      PWSK_BUF Buffer,
  [in]      ULONG Flags,
  [in, out] PIRP Irp
)
{...}

參數

[in] Socket

WSK_SOCKET 結構的指標，指定要從中接收數據的套接字物件。

[in] Buffer

初始化 WSK_BUF 結構的指標，描述從套接字接收數據的數據緩衝區。

[in] Flags

ULONG 值，包含下列旗標組合的位 OR：

WSK_FLAG_WAITALL

等候數據緩衝區完全填滿。如果指定此旗標，在發生下列其中一個事件之前，將不會完成 Irp 參數中指定的 IRP ：

由 Buffer 參數所指向之WSK_BUF結構所描述的數據緩衝區已完全填滿。
遠端發件者會正常中斷連線。
線上已中止，由 WSK 應用程式或遠端發件者中斷連線。
指定的 IRP 已取消。

Microsoft TCP/IP 傳輸通訊協定支援此旗標。其他傳輸通訊協定可能不支援此旗標。

WSK_FLAG_DRAIN

等候套接字中斷連線，捨棄套接字上收到的任何數據。如果指定此旗標，在發生下列其中一個事件之前，將不會完成指定的 IRP：

遠端發件者會正常中斷連線。
線上已中止，由 WSK 應用程式或遠端發件者中斷連線。
指定的 IRP 已取消。

WSK 子系統會捨棄任何已接收的數據。不會將接收的數據複製到數據緩衝區。指定此旗標時仍需要 Buffer 參數，但WSK_BUF結構所描述的緩衝區長度必須為零。

Microsoft TCP/IP 傳輸通訊協定支援此旗標。其他傳輸通訊協定可能不支援此旗標。

WSK_FLAG_WAITALL和WSK_FLAG_DRAIN旗標互斥。 WSK 應用程式不應該同時指定這兩個旗標。

[in, out] Irp

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

傳回值

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

傳回碼	Description
STATUS_SUCCESS	已成功從套接字接收數據。 IRP 將會以成功狀態完成。 IRP 的 [IoStatus.Information] 字段包含收到的位元組數目。
STATUS_PENDING	WSK 子系統無法立即從套接字接收數據。 WSK 子系統會在從套接字收到數據之後完成 IRP。接收作業的狀態將會在 IRP 的 [IoStatus.Status ] 字段中傳回。如果作業成功，IRP 的 IoStatus.Information 欄位將會包含收到的位元組數目。
STATUS_FILE_FORCED_CLOSED	套接字已不再運作。 IRP 將會以失敗狀態完成。 WSK 應用程式必須呼叫 WskCloseSocket 函式，才能儘快關閉套接字。
STATUS_NOT_SUPPORTED	基礎網路傳輸不支援指定的旗標。
其他狀態代碼	發生錯誤。 IRP 將會以失敗狀態完成。

備註

WSK 應用程式只能在先前連線到遠端傳輸地址的連接導向或數據流套接字上呼叫 WskReceive 函式。線上導向套接字會透過下列其中一種方法連線到遠端傳輸位址：

WSK 應用程式會呼叫 WskConnect 函式來連接套接字。
WSK 應用程式會藉由呼叫 WskSocketConnect 函式來建立、系結及連接套接字。
當 WSK 應用程式接受接聽套接字上的連入連線要求時，WSK 子系統會連接套接字。

如果 WSK 應用程式的 WskReceiveEvent 事件回呼函式是在連線導向套接字上啟用，而且應用程式在相同的連接導向套接字上也對 WskReceive 函式具有暫止呼叫，則當數據送達時， WskReceive 函式的暫止呼叫會優先於 WskReceiveEvent 事件回呼函式。只有在沒有從擱置呼叫 WskReceive 函式排入佇列的 IRP 時，WSK 子系統才會呼叫應用程式的 WskReceiveEvent 事件回呼函式。不過，WSK 應用程式不應該假設 WSK 子系統不會針對對 WskReceive 函式進行擱置呼叫的連接導向套接字呼叫應用程式的 WskReceiveEvent 事件回呼函式。存在 WSK 子系統仍可呼叫 WSK 應用程式的 WskReceiveEvent 事件回呼函式的競爭條件。 WSK 應用程式確保 WSK 子系統不會針對連接導向套接字呼叫應用程式的 WskReceiveEvent 事件回呼函式的唯一方式是停用應用程式的 WskReceiveEvent 事件回呼函式。

WSK 應用程式可以呼叫 WskReceive 函式，並在 Buffer 參數所指向之WSK_BUF結構的 Length 成員中指定零長度。在此成員中指定零長度在下列情況下很有用：

在先前傳回 WskReceiveEvent 事件回呼函式之後，重新啟用套接字的 WskReceiveEvent 事件回呼函式 STATUS_DATA_NOT_ACCEPTED時
指定WSK_FLAG_DRAIN旗標以捨棄套接字上收到的任何其他數據時

如果 WskReceive 函式傳回STATUS_PENDING， 則 Buffer 參數所指向之WSK_BUF結構中所述的 MDL 鏈結必須維持在記憶體中鎖定，直到 IRP 完成為止。

規格需求

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