Función ZwEnumerateTransactionObject (wdm.h)

  • Artículo

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

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

Uso de las versiones Nt y Zw de las rutinas nativas de System Services