Fonction NtEnumerateTransactionObject (wdm.h)

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

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtEnumerateTransactionObject(
  [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 :

La routine peut retourner d’autres valeurs NTSTATUS.

Remarques

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

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 membre ObjectIdCount 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

Voir aussi

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

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