Función NtCreateTransaction (wdm.h)
La rutina ZwCreateTransaction crea un objeto de transacción .
Sintaxis
__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransaction(
[out] PHANDLE TransactionHandle,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] LPGUID Uow,
[in, optional] HANDLE TmHandle,
[in, optional] ULONG CreateOptions,
[in, optional] ULONG IsolationLevel,
[in, optional] ULONG IsolationFlags,
[in, optional] PLARGE_INTEGER Timeout,
[in, optional] PUNICODE_STRING Description
);
Parámetros
[out] TransactionHandle
Puntero a una variable asignada por el autor de la llamada que recibe un identificador para el nuevo objeto de transacción, si la llamada a ZwCreateTransaction se realiza correctamente.
[in] DesiredAccess
Valor ACCESS_MASK que especifica el acceso solicitado del autor de la llamada al objeto de transacción. Además de los derechos de acceso definidos para todos los tipos de objetos (vea ACCESS_MASK), el autor de la llamada puede especificar cualquiera de las marcas siguientes para los objetos de transacción.
Máscara de acceso | Permite al autor de la llamada |
---|---|
TRANSACTION_COMMIT | Confirme la transacción (consulte ZwCommitTransaction). |
TRANSACTION_ENLIST | Cree una inscripción para la transacción (consulte ZwCreateEnlistment). |
TRANSACTION_PROPAGATE | No use. |
TRANSACTION_QUERY_INFORMATION | Obtenga información sobre la transacción (consulte ZwQueryInformationTransaction). |
TRANSACTION_ROLLBACK | Revierte la transacción (consulte ZwRollbackTransaction). |
TRANSACTION_SET_INFORMATION | Establezca información para la transacción (vea ZwSetInformationTransaction). |
Como alternativa, puede especificar uno o varios de los siguientes ACCESS_MASK mapas de bits. Estos mapas de bits combinan las marcas de la tabla anterior con las marcas deXXX STANDARD_RIGHTS_ que se describen en la página de referencia de ACCESS_MASK. También puede combinar estos mapas de bits con marcas adicionales de la tabla anterior. En la tabla siguiente se muestra cómo se corresponden los mapas de bits con derechos de acceso específicos.
Mapa de bits de derechos | Conjunto de derechos de acceso específicos |
---|---|
TRANSACTION_GENERIC_READ | STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION y SYNCHRONIZE |
TRANSACTION_GENERIC_WRITE | STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT y SYNCHRONIZE |
TRANSACTION_GENERIC_EXECUTE | STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK y SYNCHRONIZE |
TRANSACTION_ALL_ACCESS | STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE y TRANSACTION_GENERIC_EXECUTE |
TRANSACTION_RESOURCE_MANAGER_RIGHTS | STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE y SYNCHRONIZE |
Normalmente, un administrador de recursos especifica TRANSACTION_RESOURCE_MANAGER_RIGHTS.
El valor de DesiredAccess no puede ser cero.
[in, optional] ObjectAttributes
Puntero a una estructura OBJECT_ATTRIBUTES que especifica el nombre del objeto y otros atributos. Use la rutina de InitializeObjectAttributes para inicializar esta estructura. Si el autor de la llamada no se ejecuta en un contexto de subproceso del sistema, debe establecer el atributo OBJ_KERNEL_HANDLE cuando llama a InitializeObjectAttributes. Este parámetro es opcional y se puede NULL.
[in, optional] Uow
Puntero a un GUID que KTM usa como identificador de unidad de trabajo (UOW) del nuevo objeto de transacción. Este parámetro es opcional y se puede NULL. Si este parámetro es null, KTM genera un GUID y lo asigna al objeto de transacción. Para obtener más información, vea la siguiente sección Comentarios.
[in, optional] TmHandle
Identificador de un objeto de administrador de transacciones obtenido por una llamada anterior a ZwCreateTransactionManager o ZwOpenTransactionManager. KTM asigna el nuevo objeto de transacción al objeto de administrador de transacciones especificado. Si este parámetro es NULL, KTM asigna el nuevo objeto de transacción a un administrador de transacciones más adelante, cuando un administrador de recursos crea una inscripción para la transacción.
[in, optional] CreateOptions
Marcas de creación de objetos opcionales. La tabla siguiente contiene las marcas disponibles, que se definen en Ktmtypes.h.
Marca de opción | Significado |
---|---|
TRANSACTION_DO_NOT_PROMOTE | Reservado para uso futuro. |
[in, optional] IsolationLevel
Reservado para uso futuro. Los autores de llamadas deben establecer este parámetro en cero.
[in, optional] IsolationFlags
Reservado para uso futuro. Los autores de llamadas deben establecer este parámetro en cero.
[in, optional] Timeout
Puntero a un valor de tiempo de espera. Si el tiempo especificado por este parámetro no ha confirmado la transacción, KTM revierte la transacción. El valor de tiempo de espera se expresa en unidades de tiempo del sistema (intervalos de 100 nanosegundos) y puede especificar una hora absoluta o una hora relativa. Si el valor al que apunta de tiempo de espera es negativo, la hora de expiración es relativa a la hora actual del sistema. De lo contrario, la hora de expiración es absoluta. Este puntero es opcional y puede ser NULL si no desea que la transacción tenga un valor de tiempo de espera. Si tiempo de espera = NULL o *tiempo de espera = 0, la transacción nunca agota el tiempo de espera. (También puede usar ZwSetInformationTransaction para establecer un valor de tiempo de espera).
[in, optional] Description
Puntero a una estructura de UNICODE_STRING proporcionada por el autor de la llamada que contiene una cadena terminada en NULL. La cadena proporciona una descripción de la transacción. KTM almacena una copia de la cadena e incluye la cadena en los mensajes que escribe en el flujo de registro. La longitud máxima de la cadena es MAX_TRANSACTION_DESCRIPTION_LENGTH. Este parámetro es opcional y se puede NULL.
Valor devuelto
ZwCreateTransaction devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, esta rutina podría devolver uno de los siguientes valores:
Código devuelto | Descripción |
---|---|
|
El parámetro CreateOptions contiene una marca no válida, el parámetro DesiredAccess es cero o la cadena del parámetro Description es demasiado larga. |
|
KTM no pudo asignar recursos del sistema (normalmente memoria). |
|
Un descriptor de seguridad contiene una lista de control de acceso (ACL) no válida. |
|
Un descriptor de seguridad contiene un identificador de seguridad (SID) no válido. |
|
El nombre de objeto que el parámetro ObjectAttributes especifica que ya existe. |
|
El nombre de objeto que especifica el parámetro objectAttributes no es válido. |
|
El valor del parámetro DesiredAccess no es válido. |
La rutina puede devolver otros valores NTSTATUS de .
Observaciones
El autor de la llamada puede usar el parámetro Uow para especificar un identificador UOW para el objeto de transacción. Si el autor de la llamada no especifica un identificador UOW, KTM genera un GUID y lo asigna al objeto de transacción. El autor de la llamada puede obtener más adelante este GUID llamando a ZwQueryInformationTransaction.
Normalmente, debe permitir que KTM genere un GUID para el objeto de transacción, a menos que el componente se comunique con otro componente tpS que ya haya generado un identificador UOW para la transacción.
Para cerrar el identificador de transacción, el componente que llamó a ZwCreateTransaction debe llamar a ZwClose. Si el último identificador de transacción se cierra antes de que cualquier componente llame a ZwCommitTransaction para la transacción, KTM revierte la transacción.
Para obtener más información sobre cómo deben usar los clientes de transacciones ZwCreateTransaction, vea Creación de un cliente transaccional.
En el caso de las llamadas desde controladores en modo kernel, las NtXxx y Zwversiones de Xxx de una rutina de Servicios del sistema nativo de Windows 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 de NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.
Requisitos
Requisito | Valor |
---|---|
cliente mínimo admitido | Disponible en Windows Vista y versiones posteriores del sistema operativo. |
de la plataforma de destino de | Universal |
encabezado de | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
biblioteca de | NtosKrnl.lib |
DLL de | NtosKrnl.exe |
irQL | PASSIVE_LEVEL |
reglas de cumplimiento de DDI | HwStorPortProhibitedDIs, PowerIrpDDis |
Consulte también
usar versiones Nt y Zw de las rutinas de servicios del sistema nativo