NPI_PROVIDER_ATTACH_CLIENT_FN回调函数（netioddk.h）

项目
02/07/2025

提供程序模块的 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 代码之一：

返回代码	描述
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 调用提供程序模块时，应释放分配的内存在客户端模块和提供程序模块彼此分离后， ProviderCleanupBindingContext 回调函数。

NMR 在 IRQL = PASSIVE_LEVEL 调用提供程序模块的 ProviderAttachClient 回调函数。

要求

要求	价值
最低支持的客户端	在 Windows Vista 和更高版本的 Windows作系统中可用。
目标平台	窗户
标头	netioddk.h （包括 Wsk.h）
IRQL	PASSIVE_LEVEL