Fonction ZwEnumerateTransactionObject (wdm.h)

Article
03/08/2023

La routine ZwEnumerateTransactionObject énumère les objets KTM sur un ordinateur.

Syntaxe

NTSYSCALLAPI NTSTATUS ZwEnumerateTransactionObject(
  [in, optional] HANDLE            RootObjectHandle,
  [in]           KTMOBJECT_TYPE    QueryType,
  [in, out]      PKTMOBJECT_CURSOR ObjectCursor,
  [in]           ULONG             ObjectCursorLength,
  [out]          PULONG            ReturnLength
);

Paramètres

[in, optional] RootObjectHandle

Handle d’un objet KTM. La routine énumère les objets enfants de l’objet spécifié. Ce paramètre est facultatif et peut être NULL. Pour plus d’informations sur les valeurs valides pour ce paramètre, consultez le tableau de la section Remarques suivante.

[in] QueryType

Valeur de type KTMOBJECT_TYPE qui identifie le type d’objet à énumérer. Pour plus d’informations sur les valeurs valides pour ce paramètre, consultez le tableau de la section Remarques suivante.

[in, out] ObjectCursor

Pointeur vers une mémoire tampon allouée par l’appelant qui commence par une structure KTMOBJECT_CURSOR . ZwEnumerateTransactionObject utilise la mémoire tampon pour stocker les GUID des objets qu’il trouve.

[in] ObjectCursorLength

Longueur, en octets, de la mémoire tampon vers laquelle ObjectCursor pointe.

[out] ReturnLength

Pointeur vers un emplacement alloué à l’appelant qui reçoit le nombre d’octets que ZwEnumerateTransactionObject retourne dans la mémoire tampon ObjectCursor , y compris la longueur de la structure KTMOBJECT_CURSOR et la longueur de tous les GUID retournés.

Valeur retournée

ZwEnumerateTransactionObject retourne STATUS_SUCCESS si l’opération réussit, mais que la routine n’a pas énuméré tous les objets. S’il n’y a plus d’objets à énumérer, la routine retourne STATUS_NO_MORE_ENTRIES. Sinon, cette routine peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	La valeur du paramètre QueryType ou ObjectCursorLength n’est pas valide.
STATUS_OBJECT_TYPE_MISMATCH	Le handle spécifié par le paramètre RootObjectHandle n’est pas un handle pour un objet KTM valide.
STATUS_INVALID_HANDLE	Un handle d’objet n’est pas valide.
STATUS_ACCESS_DENIED	L’appelant n’a pas l’accès approprié aux objets énumérés.

La routine peut retourner d’autres valeurs NTSTATUS.

Remarques

Le tableau suivant contient les valeurs valides pour les paramètres RootObjectHandle et QueryType .

Paramètre QueryType	Paramètre RootObjectHandle	Objets énumérés
KTMOBJECT_TRANSACTION_MANAGER	NULL	Tous les objets du gestionnaire de transactions
KTMOBJECT_RESOURCE_MANAGER	Handle d’un objet de gestionnaire de transactions. Le handle doit avoir TRANSACTIONMANAGER_QUERY_INFORMATION accès à l’objet.	Tous les objets Resource Manager qui appartiennent à l’objet gestionnaire de transactions spécifié
KTMOBJECT_ENLISTMENT	Handle d’un objet Resource Manager. Le handle doit avoir RESOURCEMANAGER_QUERY_INFORMATION accès à l’objet.	Tous les objets d’inscription qui appartiennent à l’objet Resource Manager spécifié
KTMOBJECT_TRANSACTION	Handle d’un objet de gestionnaire de transactions. Le handle doit avoir TRANSACTIONMANAGER_QUERY_INFORMATION accès à l’objet.	Tous les objets de transaction qui appartiennent à l’objet gestionnaire de transactions spécifié
KTMOBJECT_TRANSACTION	NULL	Tous les objets de transaction qui appartiennent à tous les objets du gestionnaire de transactions

La plupart des composants TPS n’ont pas besoin d’appeler ZwEnumerateTransactionObject, mais la routine peut être utile si vous devez écrire un utilitaire de débogage.

Avant que votre composant appelle ZwEnumerateTransactionObject, il doit allouer et zéro la mémoire tampon vers laquelle ObjectCursor pointe. Le tableau GUID de la mémoire tampon peut être suffisamment grand pour recevoir un ou plusieurs éléments.

Pour énumérer tous les objets KTM du type spécifié, votre composant doit appeler ZwEnumerateTransactionObject à plusieurs reprises jusqu’à ce qu’il retourne STATUS_NO_MORE_ENTRIES.

Chaque fois que la routine est appelée, elle remplit le tableau GUID de la mémoire tampon avec autant de GUID d’objets qui seront adaptés. Après chaque appel, votre composant peut utiliser le membreObjectIdCount de la structure KTMOBJECT_CURSOR pour déterminer le nombre d’GUID d’objet stockés par la routine dans le tableau.

NtEnumerateTransactionObject et ZwEnumerateTransactionObject sont deux versions de la même routine Windows Native System Services.

Pour les appels à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Utilisation des versions Nt et Zw des routines des services système natifs.

Exemples

L’exemple de code suivant montre comment énumérer tous les objets transactionnels sur un ordinateur. Dans cet exemple, le tableau GUID de la structure KTMOBJECT_CURSOR ne contient qu’un seul élément. Chaque appel à ZwEnumerateTransactionObject renvoie donc un GUID. La routine crée une chaîne Unicode à partir du GUID et affiche la chaîne.

NTSTATUS Status;
UNICODE_STRING GuidString;
KTMOBJECT_CURSOR Cursor;
ULONG ReturnedBytes;

RtlZeroMemory(&Cursor, sizeof(Cursor));

do {
    Status = ZwEnumerateTransactionObject(
                                          NULL,
                                          KTMOBJECT_TRANSACTION,
                                          &Cursor,
                                          sizeof(Cursor),
                                          &ReturnedBytes
                                          );

    if (Status != STATUS_NO_MORE_ENTRIES) {
        RtlStringFromGUID(
                          &Cursor.ObjectIds[0],
                          &GuidString
                          );
        OutputMessage(GuidString.Buffer);
        OutputMessage(L"\r\n");
        RtlFreeUnicodeString(&GuidString);
    }
} while (Status == STATUS_SUCCESS);
if (Status == STATUS_NO_MORE_ENTRIES) {
    Status = STATUS_SUCCESS;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),PowerIrpDDis(wdm)

Voir aussi

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

Utilisation des versions Nt et Zw des routines natives des services système natifs

Partager via