Fonction AuxKlibQueryModuleInformation (aux_klib.h)

Article
08/07/2023

La routine AuxKlibQueryModuleInformation récupère des informations sur les modules d’image que le système d’exploitation a chargés.

Syntaxe

NTSTATUS AuxKlibQueryModuleInformation(
  [in, out]       PULONG BufferSize,
  [in]            ULONG  ElementSize,
  [out, optional] PVOID  QueryInfo
);

Paramètres

[in, out] BufferSize

Pointeur vers un emplacement qui contient ou reçoit une taille de mémoire tampon, en octets. Si QueryInfo a la valeur NULL, l’emplacement reçoit le nombre d’octets que le pilote doit allouer pour le tableau qui reçoit les informations récupérées. Si QueryInfo n’a pas la valeur NULL, l’emplacement doit contenir le nombre d’octets spécifié.

[in] ElementSize

Taille, en octets, de chaque élément du tableau vers lequel QueryInfo pointe. Cette valeur doit être sizeof(AUX_MODULE_BASIC_INFO) ou sizeof(AUX_MODULE_EXTENDED_INFO).

[out, optional] QueryInfo

Pointeur vers un tableau de structures AUX_MODULE_BASIC_INFO ou AUX_MODULE_EXTENDED_INFO qui reçoit des informations sur les modules d’image chargés. Si ce pointeur a la valeur NULL, AuxKlibQueryModuleInformation écrit la taille de mémoire tampon requise à l’emplacement vers lequel bufferSize pointe.

Valeur retournée

AuxKlibQueryModuleInformation retourne STATUS_SUCCESS si l’opération réussit. AuxKlibQueryModuleInformation retourne STATUS_BUFFER_TOO_SMALL si le pointeur QueryInfo n’est pas NULL et que la valeur BufferSize fournie par le pilote est trop petite.

La routine peut retourner d’autres valeurs NTSTATUS.

Remarques

Pour obtenir des informations sur les modules d’image chargés du système d’exploitation, un pilote doit :

Appelez AuxKlibQueryModuleInformation avec un pointeur QueryInfoNULL. Après le retour de AuxKlibQueryModuleInformation , l’emplacement vers lequel pointe le paramètre BufferSize contient le nombre d’octets que le pilote devra allouer au tableau.
Appelez une routine d’allocation de mémoire, telle que ExAllocatePoolWithTag, pour allouer une mémoire tampon pour le tableau.
Appelez à nouveau AuxKlibQueryModuleInformation . Cette fois, le pointeur QueryInfo doit contenir l’adresse de la mémoire tampon allouée. Après le retour de AuxKlibQueryModuleInformation , la mémoire tampon contient un tableau d’informations de module.

Le nombre de modules chargés peut changer entre le premier et le deuxième appel à AuxKlibQueryModuleInformation. Par conséquent, le deuxième appel à AuxKlibQueryModuleInformation peut retourner STATUS_BUFFER_TOO_SMALL même si le pilote alloue une mémoire tampon basée sur la taille obtenue à partir du premier appel.

Si un appel à AuxKlibQueryModuleInformation réussit, la routine écrit une valeur ImageBase dans chaque élément du tableau QueryInfo . Chaque valeur ImageBase est un pointeur vers la base d’une image de pilote chargée. Ce pointeur reste valide uniquement pendant que le pilote reste chargé. L’appelant doit supposer que le pilote peut être déchargé à tout moment, sauf si l’appelant peut garantir le contraire. Par exemple, un pilote peut être déchargé entre un appel à AuxKlibQueryModuleInformation qui obtient un pointeur vers l’image du pilote et un appel à AuxKlibGetImageExportDirectory qui utilise ce pointeur.

Les pilotes doivent appeler AuxKlibInitialize avant d’appeler AuxKlibQueryModuleInformation.

Exemples

L’exemple de code suivant illustre les étapes répertoriées dans la section Notes précédente.

NTSTATUS  status;
ULONG  modulesSize;
AUX_MODULE_EXTENDED_INFO*  modules;
ULONG  numberOfModules;
//
// Get the required array size.
//
status = AuxKlibQueryModuleInformation(
                                       &modulesSize,
                                       sizeof(AUX_MODULE_EXTENDED_INFO),
                                       NULL
                                       );

if (!NT_SUCCESS(status) || modulesSize == 0) {
    break;
    }

//
// Calculate the number of modules.
//
numberOfModules = modulesSize / sizeof(AUX_MODULE_EXTENDED_INFO);

//
// Allocate memory to receive data.
//
modules = 
    (AUX_MODULE_EXTENDED_INFO*) ExAllocatePoolWithTag(
                                      PagedPool,
                                      modulesSize,
                                      '3LxF'
                                      );
if (modules == NULL) {
    status = STATUS_INSUFFICIENT_RESOURCES;
    break;
    }

RtlZeroMemory(
              modules,
              modulesSize
              );

//
// Obtain the module information.
//
status = AuxKlibQueryModuleInformation(
                                       &modulesSize,
                                       sizeof(AUX_MODULE_EXTENDED_INFO),
                                       modules
                                       );
if (!NT_SUCCESS(status)) {
    break;
    }

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge à partir de Windows 2000.
Plateforme cible	Universal
En-tête	aux_klib.h (include Aux_klib.h)
Bibliothèque	Aux_Klib.lib
IRQL	PASSIVE_LEVEL