NPI_PROVIDER_ATTACH_CLIENT_FN回呼函式 (netioddk.h)

發行項
02/26/2024

提供者模組的 ProviderAttachClient 回呼函式會將提供者模組連結至客戶端模組。

語法

NPI_PROVIDER_ATTACH_CLIENT_FN NpiProviderAttachClientFn;

NTSTATUS NpiProviderAttachClientFn(
  [in]  HANDLE NmrBindingHandle,
  [in]  PVOID ProviderContext,
  [in]  PNPI_REGISTRATION_INSTANCE ClientRegistrationInstance,
  [in]  PVOID ClientBindingContext,
  [in]  const VOID *ClientDispatch,
  [out] PVOID *ProviderBindingContext,
  [out] const VOID **ProviderDispatch
)
{...}

參數

[in] NmrBindingHandle

NMR 用來表示用戶端模組與提供者模組之間的系結的句柄。

[in] ProviderContext

提供者模組註冊內容的指標。提供者模組會在呼叫 NmrRegisterProvider 函式以向NMR註冊本身時，將此指標傳遞至NMR。

[in] ClientRegistrationInstance

的指標 NPI_REGISTRATION_INSTANCE 結構。這個結構包含用戶端模組的註冊數據。

[in] ClientBindingContext

用戶端模組與提供者模組之間系結之用戶端模組內容的指標。用戶端模組會使用此內容來追蹤系結的狀態。用戶端模組系結內容的內容與提供者模組不透明。每當提供者模組呼叫任何需要用戶端模組系結內容的用戶端模組 NPI 回呼函式時，提供者模組就會將此指標傳遞至用戶端模組。

[in] ClientDispatch

常數結構的指標，其中包含用戶端模組之 NPI 回呼函式的分派數據表。結構的內容是 NPI 特定的。如果 NPI 未定義用戶端分派數據表結構，則此指標為 NULL。

[out] ProviderBindingContext

變數的指標，提供者模組會儲存其內容指標，以供用戶端模組與提供者模組之間的系結之系結。提供者模組會使用此內容來追蹤系結的狀態。提供者模組系結內容的內容與用戶端模組不透明。每當用戶端模組呼叫其中一個需要提供者模組系結內容的提供者模組 NPI 函式時，客戶端模組就會將此指標傳遞至提供者模組。提供者模組必須確定只要用戶端模組附加至提供者模組，此內容就會保持有效且保留在記憶體中。

[out] ProviderDispatch

提供者模組將儲存常數結構的指標，其中包含提供者模組之 NPI 函式的分派數據表。只要客戶端模組附加至提供者模組，提供者模組就必須確保此結構保持有效且保留在記憶體中。結構的內容是 NPI 特定的。

傳回值

提供者模組的 ProviderAttachClient 回呼函式會傳回下列其中一個 NTSTATUS 代碼：

傳回碼	Description
STATUS_SUCCESS	提供者模組已成功附加至客戶端模組。
STATUS_NOINTERFACE	提供者模組未附加至客戶端模組。
其他狀態代碼	發生錯誤。

備註

每當用戶端模組呼叫NmrClientAttachProvider函式時，NMR會呼叫提供者模組的 ProviderAttachClient 回呼函式，其句柄代表用戶端模組與提供者模組之間的系結。

提供者模組可以檢查用戶端模組的註冊數據。此數據位於 ClientRegistrationInstance 參數所指向的結構中。提供者模組會使用此資料來判斷它是否會附加至用戶端模組：

如果提供者模組判斷它會附加至用戶端模組， 則 ProviderAttachClient 回呼函式必須執行下列動作：
1. 儲存在 ClientBindingContext 和 ClientDispatch 參數中傳遞的指標，讓提供者模組可以呼叫用戶端模組的 NPI 函式。
2. 儲存在 NmrBindingHandle 參數中傳遞的句柄。提供者模組會將此句柄當做參數傳遞至 NmrProviderDetachClientComplete 函式從用戶端模組中斷連結時。
3. 將 ProviderBindingContext 參數設定為指向用戶端模組與提供者模組之間系結之提供者模組的系結內容結構。
4. 將 ProviderDispatch 參數設定為指向包含提供者模組之 NPI 函式分派表的結構。
5. 傳回STATUS_SUCCESS。
如果提供者模塊判斷它不會附加至用戶端模組， 則 ProviderAttachClient 回呼函式必須傳回STATUS_NOINTERFACE。

如果提供者模組連結至用戶端模組，且其動態配置記憶體以供系結內容使用，則當NMR呼叫提供者模組時，應該釋出配置記憶體的記憶體Client 模組和提供者模組彼此中斷鏈接之後的 ProviderCleanupBindingContext 回呼函式。

NMR 會在 IRQL = PASSIVE_LEVEL呼叫提供者模組的 ProviderAttachClient 回呼函式。

規格需求

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