Funzione ZwEnumerateTransactionObject (wdm.h)
La routine ZwEnumerateTransactionObject enumera gli oggetti KTM in un computer.
Sintassi
NTSYSCALLAPI NTSTATUS ZwEnumerateTransactionObject(
[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 seguenti.
[in] QueryType
Valore KTMOBJECT_TYPE tipizzato che identifica il tipo di oggetto da enumerare. Per altre informazioni sui valori validi per questo parametro, vedere la tabella nella sezione Osservazioni seguenti.
[in, out] ObjectCursor
Puntatore a un buffer allocato del 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 del 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 più 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 oggetto non è valido. |
| STATUS_ACCESS_DENIED | Il chiamante non dispone dell'accesso appropriato agli oggetti che vengono enumerati. |
La routine potrebbe restituire altri valori NTSTATUS.
Commenti
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 a un oggetto di gestione transazioni. L'handle deve avere TRANSACTIONMANAGER_QUERY_INFORMATION accesso all'oggetto. | Tutti gli oggetti di Resource Manager appartenenti all'oggetto di gestione transazioni specificato |
| KTMOBJECT_ENLISTMENT | Handle a un oggetto resource manager. L'handle deve avere RESOURCEMANAGER_QUERY_INFORMATION accesso all'oggetto. | Tutti gli oggetti di inserimento appartenenti all'oggetto resource manager specificato |
| KTMOBJECT_TRANSACTION | Handle a un oggetto di gestione transazioni. L'handle deve avere TRANSACTIONMANAGER_QUERY_INFORMATION accesso all'oggetto. | Tutti gli oggetti transazioni appartenenti all'oggetto di gestione transazioni specificato |
| KTMOBJECT_TRANSACTION | NULL | Tutti gli oggetti transazioni 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 abbastanza grande per ricevere uno o più elementi.
Per enumerare tutti gli oggetti KTM del tipo specificato, il componente deve chiamare ripetutamente 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 Windows Native System Services.
Per le chiamate dai driver in modalità kernel, le versioni NtXxx e ZwXxx 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 Uso di nt e zw versioni delle routine di Servizi di sistema nativo.
Esempio
Nell'esempio di codice seguente viene illustrato come enumerare tutti gli oggetti transazioni in un computer. In questo esempio la matrice GUID della struttura di 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(storport), PowerIrpDDis(wdm) |
Vedi anche
Uso di nt e zw versioni delle routine di Servizi di sistema nativo