Función ZwEnumerateTransactionObject (wdm.h)
La rutina ZwEnumerateTransactionObject enumera los objetos KTM de un equipo.
Sintaxis
NTSYSCALLAPI NTSTATUS ZwEnumerateTransactionObject(
[in, optional] HANDLE RootObjectHandle,
[in] KTMOBJECT_TYPE QueryType,
[in, out] PKTMOBJECT_CURSOR ObjectCursor,
[in] ULONG ObjectCursorLength,
[out] PULONG ReturnLength
);
Parámetros
[in, optional] RootObjectHandle
Identificador de un objeto KTM. La rutina enumera los objetos secundarios del objeto especificado. Este parámetro es opcional y puede ser NULL. Para obtener más información sobre los valores válidos para este parámetro, consulte la tabla de la sección Comentarios siguiente.
[in] QueryType
Valor de tipo KTMOBJECT_TYPE que identifica el tipo de objeto que se va a enumerar. Para obtener más información sobre los valores válidos para este parámetro, consulte la tabla de la sección Comentarios siguiente.
[in, out] ObjectCursor
Puntero a un búfer asignado por el autor de la llamada que comienza con una estructura KTMOBJECT_CURSOR . ZwEnumerateTransactionObject usa el búfer para almacenar los GUID de los objetos que encuentra.
[in] ObjectCursorLength
Longitud, en bytes, del búfer al que apunta ObjectCursor .
[out] ReturnLength
Puntero a una ubicación asignada por el autor de la llamada que recibe el número de bytes que ZwEnumerateTransactionObject devuelve en el búfer objectCursor , incluida la longitud de la estructura KTMOBJECT_CURSOR y la longitud de todos los GUID devueltos.
Valor devuelto
ZwEnumerateTransactionObject devuelve STATUS_SUCCESS si la operación se realiza correctamente, pero la rutina no ha enumerado todos los objetos. Si no hay más objetos que enumerar, la rutina devuelve STATUS_NO_MORE_ENTRIES. De lo contrario, esta rutina podría devolver uno de los siguientes valores:
| Código devuelto | Descripción |
|---|---|
| STATUS_INVALID_PARAMETER | El valor del parámetro QueryType o ObjectCursorLength no es válido. |
| STATUS_OBJECT_TYPE_MISMATCH | El identificador que especifica el parámetro RootObjectHandle no es un identificador para un objeto KTM válido. |
| STATUS_INVALID_HANDLE | Un identificador de objeto no es válido. |
| STATUS_ACCESS_DENIED | El autor de la llamada no tiene el acceso adecuado a los objetos que se están enumerando. |
La rutina podría devolver otros valores NTSTATUS.
Comentarios
La tabla siguiente contiene los valores válidos para los parámetros RootObjectHandle y QueryType .
| Parámetro QueryType | Parámetro RootObjectHandle | Objetos enumerados |
|---|---|---|
| KTMOBJECT_TRANSACTION_MANAGER | NULL | Todos los objetos del administrador de transacciones |
| KTMOBJECT_RESOURCE_MANAGER | Identificador de un objeto de administrador de transacciones. El identificador debe tener TRANSACTIONMANAGER_QUERY_INFORMATION acceso al objeto . | Todos los objetos de Resource Manager que pertenecen al objeto de administrador de transacciones especificado |
| KTMOBJECT_ENLISTMENT | Identificador de un objeto de Resource Manager. El identificador debe tener RESOURCEMANAGER_QUERY_INFORMATION acceso al objeto . | Todos los objetos de inscripción que pertenecen al objeto de Resource Manager especificado |
| KTMOBJECT_TRANSACTION | Identificador de un objeto de administrador de transacciones. El identificador debe tener TRANSACTIONMANAGER_QUERY_INFORMATION acceso al objeto . | Todos los objetos de transacción que pertenecen al objeto de administrador de transacciones especificado |
| KTMOBJECT_TRANSACTION | NULL | Todos los objetos de transacción que pertenecen a todos los objetos del administrador de transacciones |
La mayoría de los componentes de TPS no tienen que llamar a ZwEnumerateTransactionObject, pero la rutina podría ser útil si tiene que escribir una utilidad de depuración.
Antes de que el componente llame a ZwEnumerateTransactionObject, debe asignar y cero el búfer al que apunta ObjectCursor . La matriz GUID del búfer puede ser lo suficientemente grande como para recibir uno o varios elementos.
Para enumerar todos los objetos KTM del tipo especificado, el componente debe llamar a ZwEnumerateTransactionObject repetidamente hasta que devuelva STATUS_NO_MORE_ENTRIES.
Cada vez que se llama a la rutina, rellena la matriz GUID del búfer con tantos GUID de objeto que caben. Después de cada llamada, el componente puede usar el miembro ObjectIdCount de la estructura KTMOBJECT_CURSOR para determinar el número de GUID de objeto que la rutina almacenada en la matriz.
NtEnumerateTransactionObject y ZwEnumerateTransactionObject son dos versiones de la misma rutina de Windows Native System Services.
En el caso de las llamadas desde controladores en modo kernel, las versiones NtXxx y ZwXxx de una rutina de Windows Native System Services pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.
Ejemplos
En el ejemplo de código siguiente se muestra cómo enumerar todos los objetos de transacción de un equipo. En este ejemplo, la matriz GUID de la estructura KTMOBJECT_CURSOR contiene solo un elemento, por lo que cada llamada a ZwEnumerateTransactionObject devuelve un GUID. La rutina crea una cadena Unicode a partir del GUID y muestra la cadena.
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;
}
Requisitos
| Requisito | Value |
|---|---|
| Plataforma de destino | Universal |
| Encabezado | wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| Archivo DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Reglas de cumplimiento de DDI | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |
Consulte también
Uso de las versiones Nt y Zw de las rutinas nativas de System Services