クライアント モジュールの初期化と登録

  • [アーティクル]

クライアント モジュールは、ネットワーク モジュール レジストラー (NMR) に登録する前に、多数のデータ構造を初期化する必要があります。 これらの構造体には、NPI_MODULEID 構造体、NPI_CLIENT_CHARACTERISTICS 構造体、NPI_REGISTRATION_INSTANCE 構造体 (NPI_CLIENT_CHARACTERISTICS 構造体内に含まれます)、クライアント モジュールの登録コンテキストに使用されるクライアント モジュールによって定義された構造体が含まれます。

クライアント モジュールが、NPI 固有のクライアント特性を定義するネットワーク プログラミング インターフェイス (NPI) のクライアントとして自身を NMR に登録する場合、クライアント モジュールは、NPI によって定義されたクライアント特性構造のインスタンスも初期化する必要があります。

クライアントモジュールが NMR に登録されている限り、これらのデータ構造は現在でもすべて有効でメモリ内に常駐している必要があります。

たとえば、"EXNPI" NPI がヘッダー ファイル Exnpi.h で次のように定義するとします。

// EXNPI NPI identifier
const NPIID EXNPI_NPIID = { ... };

// EXNPI client characteristics structure
typedef struct EXNPI_CLIENT_CHARACTERISTICS_
{
  .
  . // NPI-specific members
  .
} EXNPI_CLIENT_CHARACTERISTICS, *PEXNPI_CLIENT_CHARACTERISTICS;

次に示すのは、EXNPI NPI のクライアントとして自身を登録するクライアント モジュールが、これらのすべてのデータ構造を初期化する方法です。

// Include the NPI specific header file
#include "exnpi.h"

// Structure for the client module's NPI-specific characteristics
const EXNPI_CLIENT_CHARACTERISTICS NpiSpecificCharacteristics =
{
  .
  . // The NPI-specific characteristics of the client module
  .
};

// Structure for the client module's identification
const NPI_MODULEID ClientModuleId =
{
  sizeof(NPI_MODULEID),
  MIT_GUID,
  { ... }  // A GUID that uniquely identifies the client module
};

// Prototypes for the client module's callback functions
NTSTATUS
  ClientAttachProvider(
    IN HANDLE NmrBindingHandle,
    IN PVOID ClientContext,
    IN PNPI_REGISTRATION_INSTANCE ProviderRegistrationInstance
    );

NTSTATUS
  ClientDetachProvider(
    IN PVOID ClientBindingContext
    );

VOID
  ClientCleanupBindingContext(
    IN PVOID ClientBindingContext
    );

// Structure for the client module's characteristics
const NPI_CLIENT_CHARACTERISTICS ClientCharacteristics =
{
  0,
  sizeof(NPI_CLIENT_CHARACTERISTICS),
  ClientAttachProvider,
  ClientDetachProvider,
  ClientCleanupBindingContext,
  {
    0,
    sizeof(NPI_REGISTRATION_INSTANCE),
    &EXNPI_NPIID,
    &ClientModuleId,
    0,
    &NpiSpecificCharacteristics
  }
};

// Context structure for the client module's registration
typedef struct CLIENT_REGISTRATION_CONTEXT_ {
  .
  . // Client-specific members
  .
} CLIENT_REGISTRATION_CONTEXT, *PCLIENT_REGISTRATION_CONTEXT;

// Structure for the client's registration context
CLIENT_REGISTRATION_CONTEXT ClientRegistrationContext =
{
  .
  . // Initial values for the registration context
  .
};

通常、クライアント モジュールは DriverEntry 関数内で自身を初期化します。 クライアント モジュールの主な初期化タスクは次のとおりです。

  • Unload 関数を指定します。 オペレーティング システムは、クライアント モジュールがシステムからアンロードされるときに、この関数を呼び出します。 クライアント モジュールがアンロード関数を提供しない場合、クライアント モジュールをシステムからアンロードすることはできません。

  • クライアント モジュールを NMR に登録するには、NmrRegisterClient 関数を呼び出します。

次に例を示します。

// Prototype for the client module's unload function
VOID
  Unload(
    PDRIVER_OBJECT DriverObject
    );

// Variable to contain the handle for the registration
HANDLE ClientHandle;

// DriverEntry function
NTSTATUS
  DriverEntry(
    PDRIVER_OBJECT DriverObject,
    PUNICODE_STRING RegistryPath
    )
{
  NTSTATUS Status;

  // Specify the unload function
  DriverObject->DriverUnload = Unload;

  .
  . // Other initialization tasks
  .

  // Register the client module with the NMR
  Status = NmrRegisterClient(
    &ClientCharacteristics,
    &ClientRegistrationContext,
    &ClientHandle
    );

  // Return the result of the registration
  return Status;
}

クライアント モジュールが複数の NPI のクライアントである場合は、データ構造の独立したセットを初期化し、それをサポートする各 NPI に対して NmrRegisterClient を呼び出す必要があります。 ネットワーク モジュールがクライアント モジュールとプロバイダー モジュールの両方 (つまり、1 つの NPI のクライアントであり、別の NPI のプロバイダー) である場合は、クライアント インターフェイス用とプロバイダー インターフェイス用の 2 つの独立したデータ構造セットを初期化し、NmrRegisterClient とNmrRegisterProvider の両方を呼び出す必要があります。

クライアント モジュールは、DriverEntry 関数内から NmrRegisterClient を呼び出す必要はありません。 たとえば、クライアント モジュールが複雑なドライバーのサブコンポーネントである場合、クライアント モジュールの登録は、クライアント モジュールのサブコンポーネントがアクティブ化される際にのみ発生する可能性があります。

クライアント モジュールの Unload 関数の実装に関する詳細については、「クライアント モジュールのアンロード」を参照してください。