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 代码之一：

返回代码	说明
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 操作系统中可用。
目标平台	Windows
标头	netioddk.h (包括 Wsk.h)
IRQL	PASSIVE_LEVEL