Inicializace a registrace modulu zprostředkovatele

Modul poskytovatele musí inicializovat řadu datových struktur, aby se mohl zaregistrovat u registrátora síťového modulu (NMR). Tyto struktury zahrnují strukturu NPI_MODULEID , strukturu NPI_PROVIDER_CHARACTERISTICS , strukturu NPI_REGISTRATION_INSTANCE (obsaženou v NPI_PROVIDER_CHARACTERISTICS struktuře) a strukturu definovanou modulem zprostředkovatele, který se používá pro kontext registrace modulu poskytovatele.

Pokud se modul poskytovatele zaregistruje u NMR jako poskytovatel síťového programovacího rozhraní (NPI), který definuje vlastnosti poskytovatele specifické pro NPI, musí modul zprostředkovatele také inicializovat instanci struktury charakteristik zprostředkovatele, která je definována npI.

Všechny tyto datové struktury musí zůstat platné a rezidentní v paměti, pokud je modul poskytovatele zaregistrovaný v NMR.

Předpokládejme například, že NPI "EXNPI" definuje následující v hlavičce souboru 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;

Následující ukazuje, jak modul poskytovatele, který se zaregistruje jako poskytovatel EXNPI NPI, může inicializovat všechny tyto datové struktury:

// 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
  .
};

Modul zprostředkovatele se obvykle inicializuje v rámci své funkce DriverEntry . Hlavní úlohy inicializace modulu zprostředkovatele jsou:

• Zadejte funkci Unload. Operační systém tuto funkci volá, když je modul zprostředkovatele uvolněn ze systému. Pokud modul zprostředkovatele neposkytuje funkci uvolnění, modul zprostředkovatele nelze ze systému uvolnit.

• Voláním funkce NmrRegisterProvider zaregistrujte modul poskytovatele v NMR.

Například:

// 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;
}

Pokud je modul zprostředkovatele poskytovatelem více než jednoho NPI, musí inicializovat nezávislou sadu datových struktur a volat NmrRegisterProvider pro každý NPI, který podporuje. Pokud je síťový modul modul poskytovatele i klientský modul (to znamená poskytovatel jednoho NPI a klienta jiného NPI), musí inicializovat dvě nezávislé sady datových struktur, jednu pro rozhraní zprostředkovatele a jeden pro klientské rozhraní a volat NmrRegisterProvider i NmrRegisterClient.

Modul poskytovatele není nutný k volání NmrRegisterProvider z jeho funkce DriverEntry . Například v situaci, kdy je modul zprostředkovatele dílčí součástí komplexního ovladače, může dojít k registraci modulu poskytovatele pouze v případě, že je aktivována dílčí součást modulu zprostředkovatele.

Další informace o implementaci funkce Unload modulu zprostředkovatele naleznete v tématu Uvolnění modulu zprostředkovatele.