Funzione NtEnumerateTransactionObject (wdm.h)

La routine ZwEnumerateTransactionObject enumera gli oggetti KTM in un computer.

Sintassi

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

Parametri

[in, optional] RootObjectHandle

Handle per un oggetto KTM. La routine enumera gli oggetti figlio dell'oggetto specificato. Questo parametro è facoltativo e può essere NULL. Per altre informazioni sui valori validi per questo parametro, vedere la tabella nella sezione Osservazioni seguente.

[in] QueryType

Valore tipizzato KTMOBJECT_TYPE che identifica il tipo di oggetto da enumerare. Per altre informazioni sui valori validi per questo parametro, vedere la tabella nella sezione Osservazioni seguente.

[in, out] ObjectCursor

Puntatore a un buffer allocato dal chiamante che inizia con una struttura KTMOBJECT_CURSOR . ZwEnumerateTransactionObject usa il buffer per archiviare i GUID degli oggetti trovati.

[in] ObjectCursorLength

Lunghezza, in byte, del buffer a cui punta ObjectCursor .

[out] ReturnLength

Puntatore a una posizione allocata dal chiamante che riceve il numero di byte restituiti da ZwEnumerateTransactionObject nel buffer ObjectCursor , inclusa la lunghezza della struttura KTMOBJECT_CURSOR e la lunghezza di tutti i GUID restituiti.

Valore restituito

ZwEnumerateTransactionObject restituisce STATUS_SUCCESS se l'operazione ha esito positivo, ma la routine non ha enumerato tutti gli oggetti. Se non sono presenti altri oggetti da enumerare, la routine restituisce STATUS_NO_MORE_ENTRIES. In caso contrario, questa routine potrebbe restituire uno dei valori seguenti:

La routine potrebbe restituire altri valori NTSTATUS.

Commenti

La tabella seguente contiene i valori validi per i parametri RootObjectHandle e QueryType .

La maggior parte dei componenti TPS non deve chiamare ZwEnumerateTransactionObject, ma la routine potrebbe essere utile se è necessario scrivere un'utilità di debug.

Prima che il componente chiami ZwEnumerateTransactionObject, deve allocare e zero il buffer a cui punta ObjectCursor . La matrice GUID del buffer può essere sufficientemente grande da ricevere uno o più elementi.

Per enumerare ripetutamente tutti gli oggetti KTM del tipo specificato, il componente deve chiamare ZwEnumerateTransactionObject finché non restituisce STATUS_NO_MORE_ENTRIES.

Ogni volta che viene chiamata la routine, riempie la matrice GUID del buffer con il numero di GUID dell'oggetto che si adatta. Dopo ogni chiamata, il componente può usare il membro ObjectIdCount della struttura KTMOBJECT_CURSOR per determinare il numero di GUID oggetto archiviati nella matrice.

NtEnumerateTransactionObject e ZwEnumerateTransactionObject sono due versioni della stessa routine di Servizi di sistema nativi di Windows.

Per le chiamate da driver in modalità kernel, le versioni NtXxx e ZwXxx di una routine di Servizi di sistema nativi di Windows possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx e ZwXxx di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines .For more information about the Nt Xxx and Zw versions of the Native System Services Routines.

Esempio

Nell'esempio di codice seguente viene illustrato come enumerare tutti gli oggetti transazione in un computer. In questo esempio, la matrice GUID della struttura KTMOBJECT_CURSOR contiene un solo elemento, quindi ogni chiamata a ZwEnumerateTransactionObject restituisce un GUID. La routine crea una stringa Unicode dal GUID e visualizza la stringa.

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

Requisiti

Vedi anche

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

Uso delle versioni Nt e Zw delle routine native di Servizi di sistema