PFN_WSK_RECEIVE_FROM回呼函式 (wsk.h)

發行項
03/01/2024

WskReceiveFrom 函式會從遠端傳輸位址接收數據報和任何相關聯的控制資訊。

語法

PFN_WSK_RECEIVE_FROM PfnWskReceiveFrom;

NTSTATUS PfnWskReceiveFrom(
  [in]            PWSK_SOCKET Socket,
  [in]            PWSK_BUF Buffer,
                  ULONG Flags,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PULONG ControlLength,
  [out, optional] PCMSGHDR ControlInfo,
  [out, optional] PULONG ControlFlags,
  [in, out]       PIRP Irp
)
{...}

參數

[in] Socket

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

[in] Buffer

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

Flags

此參數保留給系統使用。 WSK 應用程式必須將此參數設定為零。

[out, optional] RemoteAddress

呼叫端配置緩衝區的指標，接收接收所接收數據報的來源遠端傳輸位址。緩衝區必須位於非分頁記憶體中。緩衝區也必須夠大，才能包含對應至 WSK 應用程式在建立數據報套接字時所指定的位址系列的特定 SOCKADDR 結構類型。此指標是選擇性的，而且可以是 NULL。

[in, out] ControlLength

ULONG 的指標，指定 ControlInfo 參數指向的緩衝區大小。當接收作業完成時，變數會收到與所接收數據報相關聯的控件資訊大小。如果傳回的值是零，則數據報沒有任何控件資訊存在。此指標是選擇性的，而且可以是 NULL。如果此參數為 NULL，則會忽略 ControlInfo 參數。

[out, optional] ControlInfo

呼叫端配置的緩衝區指標，接收與所接收數據報相關聯的控件資訊。與數據報相關聯的控件信息數據是由一或多個控件數據物件所組成，每個物件都是以 CMSGHDR 結構開頭。如果接收的數據報沒有控件資訊存在，則緩衝區的內容是未定義的。此指標是選擇性的，而且可以是 NULL。如果 ControlInfoLength 參數為 NULL，ControlInfo 參數應該是 NULL。

[out, optional] ControlFlags

ULONG 型別變數的指標，可接收下列旗標組合的位 OR：

MSG_BCAST

數據報是以連結層廣播或目的地傳輸位址接收，而目的地傳輸地址是廣播位址。

MSG_MCAST

數據報是以多播位址的目的地傳輸位址接收。

MSG_TRUNC

數據報已截斷，因為數據報的大小大於 Buffer 參數所指定的緩衝區大小。

MSG_CTRUNC

控件信息數據遭到截斷，因為控制資訊的位元元組數目大於 ControlInfo 參數所指定的緩衝區大小。

這個參數是選擇性的，而且可以是 NULL。

[in, out] Irp

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

傳回值

WskReceiveFrom 會傳回下列其中一個 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 函式，才能儘快關閉套接字。
其他狀態代碼	發生錯誤。 IRP 將會以失敗狀態完成。

備註

如果 WSK 應用程式已設定資料報套接字的固定遠端傳輸位址，WSK 子系統將會捨棄從任何其他遠端傳輸位址接收的數據報。如需設定數據報套接字遠端傳輸位址的詳細資訊，請參閱 SIO_WSK_SET_REMOTE_ADDRESS。

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

如果 WskReceiveFrom 函式傳回STATUS_PENDING，則 Buffer 參數所指向WSK_BUF結構中所述的 MDL 鏈結必須維持在記憶體中鎖定，直到 IRP 完成為止。此外， ControlInfoLength 參數所指向的變數、 ControlInfo 參數所指向的緩衝區，以及 ControlFlags 參數所指向的變數也必須維持有效狀態，直到 IRP 完成為止。如果 WSK 應用程式使用其中一個 ExAllocateXxx 函式配置這些緩衝區或變數，它就無法在 IRP 完成之後釋放具有對應 ExFreeXxx 函式的記憶體。如果 WSK 應用程式在堆疊上配置這些緩衝區或變數，它就無法從呼叫 WskReceiveFrom 函式的函式傳回，直到 IRP 完成之後。

規格需求

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