初始化和注册提供程序模块
提供程序模块必须先初始化多个数据结构,然后才能将自身注册到网络模块注册器 (NMR) 。 这些结构包括 NPI_MODULEID 结构、 NPI_PROVIDER_CHARACTERISTICS 结构、 包含在NPI_PROVIDER_CHARACTERISTICS 结构) 中的NPI_REGISTRATION_INSTANCE结构 (,以及提供程序模块定义的用于提供程序模块注册上下文的结构。
如果提供程序模块将自身注册到 NMR 作为 网络编程接口 (NPI) (用于定义 NPI 特定提供程序特征)的提供程序,则提供程序模块还必须初始化由 NPI 定义的提供程序特征结构的实例。
只要提供程序模块已注册到 NMR,所有这些数据结构都必须保持有效并驻留在内存中。
例如,假设“EXNPI”NPI 在头文件 Exnpi.h 中定义以下内容:
// EXNPI NPI identifier
const NPIID EXNPI_NPIID = { ... };
// EXNPI provider characteristics structure
typedef struct EXNPI_PROVIDER_CHARACTERISTICS_
{
.
. // NPI-specific members
.
} EXNPI_PROVIDER_CHARACTERISTICS, *PEXNPI_PROVIDER_CHARACTERISTICS;
下面显示了将自身注册为 EXNPI NPI 的提供程序模块如何初始化所有这些数据结构:
// Include the NPI specific header file
#include "exnpi.h"
// Structure for the provider module's NPI-specific characteristics
const EXNPI_PROVIDER_CHARACTERISTICS NpiSpecificCharacteristics =
{
.
. // The NPI-specific characteristics of the provider module
.
};
// Structure for the provider module's identification
const NPI_MODULEID ProviderModuleId =
{
sizeof(NPI_MODULEID),
MIT_GUID,
{ ... } // A GUID that uniquely identifies the provider module
};
// Prototypes for the provider module's callback functions
NTSTATUS
ProviderAttachClient(
IN HANDLE NmrBindingHandle,
IN PVOID ProviderContext,
IN PNPI_REGISTRATION_INSTANCE ClientRegistrationInstance,
IN PVOID ClientBindingContext,
IN CONST VOID *ClientDispatch,
OUT PVOID *ProviderBindingContext,
OUT PVOID *ProviderDispatch
);
NTSTATUS
ProviderDetachClient(
IN PVOID ProviderBindingContext
);
VOID
ProviderCleanupBindingContext(
IN PVOID ProviderBindingContext
);
// Structure for the provider module's characteristics
const NPI_PROVIDER_CHARACTERISTICS ProviderCharacteristics =
{
0,
sizeof(NPI_PROVIDER_CHARACTERISTICS),
ProviderAttachClient,
ProviderDetachClient,
ProviderCleanupBindingContext,
{
0,
sizeof(NPI_REGISTRATION_INSTANCE),
&EXNPI_NPIID,
&ProviderModuleId,
0,
&NpiSpecificCharacteristics
}
};
// Context structure for the provider module's registration
typedef struct PROVIDER_REGISTRATION_CONTEXT_ {
.
. // Provider-specific members
.
} PROVIDER_REGISTRATION_CONTEXT, *PPROVIDER_REGISTRATION_CONTEXT;
// Structure for the provider's registration context
PROVIDER_REGISTRATION_CONTEXT ProviderRegistrationContext =
{
.
. // Initial values for the registration context
.
};
提供程序模块通常在其 DriverEntry 函数中初始化自身。 提供程序模块main初始化任务包括:
指定 Unload 函数。 从系统卸载提供程序模块时,操作系统会调用此函数。 如果提供程序模块不提供 unload 函数,则无法从系统卸载该提供程序模块。
调用 NmrRegisterProvider 函数以向 NMR 注册提供程序模块。
例如:
// Prototype for the provider module's unload function
VOID
Unload(
PDRIVER_OBJECT DriverObject
);
// Variable to contain the handle for the registration
HANDLE ProviderHandle;
// DriverEntry function
NTSTATUS
DriverEntry(
PDRIVER_OBJECT DriverObject,
PUNICODE_STRING RegistryPath
)
{
NTSTATUS Status;
// Specify the unload function
DriverObject->DriverUnload = Unload;
.
. // Other initialization tasks
.
// Register the provider module with the NMR
Status = NmrRegisterProvider(
&ProviderCharacteristics,
&ProviderRegistrationContext,
&ProviderHandle
);
// Return the result of the registration
return Status;
}
如果提供程序模块是多个 NPI 的提供程序,则必须初始化一组独立的数据结构,并为它支持的每个 NPI 调用 NmrRegisterProvider 。 如果网络模块既是提供程序模块,又是客户端模块 (也就是说,它是一个 NPI 的提供程序,另一个 NPI) 的客户端,则它必须初始化两个独立的数据结构集,一个用于提供程序接口,另一个用于客户端接口,并同时调用 NmrRegisterProvider 和 NmrRegisterClient。
提供程序模块不需要从其 DriverEntry 函数中调用 NmrRegisterProvider。 例如,在提供程序模块是复杂驱动程序的子组件的情况下,仅当激活提供程序模块子组件时,才会注册提供程序模块。