Funzione NtEnumerateTransactionObject (wdm.h)

Articolo
03/08/2023

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:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Il valore del parametro QueryType o ObjectCursorLength non è valido.
STATUS_OBJECT_TYPE_MISMATCH	L'handle specificato dal parametro RootObjectHandle non è un handle per un oggetto KTM valido.
STATUS_INVALID_HANDLE	Un handle di oggetto non è valido.
STATUS_ACCESS_DENIED	Il chiamante non dispone dell'accesso appropriato agli oggetti da enumerare.

La routine potrebbe restituire altri valori NTSTATUS.

Commenti

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

Parametro QueryType	RootObjectHandle - parametro	Oggetti enumerati
KTMOBJECT_TRANSACTION_MANAGER	NULL	Tutti gli oggetti di gestione transazioni
KTMOBJECT_RESOURCE_MANAGER	Handle per un oggetto di gestione transazioni. L'handle deve avere TRANSACTIONMANAGER_QUERY_INFORMATION accesso all'oggetto .	Tutti gli oggetti resource manager che appartengono all'oggetto di gestione transazioni specificato
KTMOBJECT_ENLISTMENT	Handle per un oggetto resource manager. L'handle deve avere RESOURCEMANAGER_QUERY_INFORMATION accesso all'oggetto .	Tutti gli oggetti di integrazione che appartengono all'oggetto resource manager specificato
KTMOBJECT_TRANSACTION	Handle per un oggetto di gestione transazioni. L'handle deve avere TRANSACTIONMANAGER_QUERY_INFORMATION accesso all'oggetto .	Tutti gli oggetti transazione che appartengono all'oggetto di gestione transazioni specificato
KTMOBJECT_TRANSACTION	NULL	Tutti gli oggetti transazione che appartengono a tutti gli oggetti di gestione transazioni

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

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDIs, PowerIrpDDis

Vedi anche

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

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

Condividi tramite