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 KTMOBJECT_TYPEtipizzato 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 ObjectCursor punta.

[out] ReturnLength

Puntatore a una posizione allocata dal chiamante che riceve il numero di byte restituiti 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 enumerati.

La routine potrebbe restituire altri valori NTSTATUS .

Osservazioni

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

parametro QueryType	parametro RootObjectHandle	Oggetti enumerati
KTMOBJECT_TRANSACTION_MANAGER	NULL	Tutti gli oggetti di gestione transazioni
KTMOBJECT_RESOURCE_MANAGER	Handle di 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 di 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 ObjectCursor punta. La matrice GUID del buffer può essere sufficientemente grande da ricevere uno o più elementi.

Per enumerare tutti gli oggetti KTM del tipo specificato, il componente deve chiamare ZwEnumerateTransactionObject ripetutamente 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 ObjectId Count 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 NtXxx e ZwXxx versioni di una routine di Windows Native System Services 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.

Esempi

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

Fabbisogno

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

Vedere anche

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

uso di versioni Nt e Zw delle routine di Servizi di sistema nativi