Funzione NtCreateTransaction (wdm.h)

Articolo
02/07/2025

La routine ZwCreateTransaction crea un oggetto transazione .

Sintassi

__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
);

Parametri

[out] TransactionHandle

Puntatore a una variabile allocata dal chiamante che riceve un handle per il nuovo oggetto transazione, se la chiamata a ZwCreateTransaction ha esito positivo.

[in] DesiredAccess

Valore ACCESS_MASK che specifica l'accesso richiesto dal chiamante all'oggetto transazione. Oltre ai diritti di accesso definiti per tutti i tipi di oggetti (vedere ACCESS_MASK), il chiamante può specificare uno dei flag seguenti per gli oggetti transazione.

Maschera di accesso	Consente al chiamante di
TRANSACTION_COMMIT	Eseguire il commit della transazione (vedere ZwCommitTransaction).
TRANSACTION_ENLIST	Creare un'integrazione per la transazione (vedere ZwCreateEnlistment).
TRANSACTION_PROPAGATE	Non usare.
TRANSACTION_QUERY_INFORMATION	Ottenere informazioni sulla transazione (vedere ZwQueryInformationTransaction).
TRANSACTION_ROLLBACK	Eseguire il rollback della transazione (vedere ZwRollbackTransaction).
TRANSACTION_SET_INFORMATION	Impostare le informazioni per la transazione (vedere ZwSetInformationTransaction).

In alternativa, è possibile specificare una o più delle bitmap di ACCESS_MASK seguenti. Queste bitmap combinano i flag della tabella precedente con i flagXXX STANDARD_RIGHTS_ XXX descritti nella pagina di riferimento ACCESS_MASK. È anche possibile combinare queste bitmap con flag aggiuntivi della tabella precedente. Nella tabella seguente viene illustrato come le bitmap corrispondono a diritti di accesso specifici.

Bitmap diritti	Set di diritti di accesso specifici
TRANSACTION_GENERIC_READ	STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION e SYNCHRONIZE
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT e SYNCHRONIZE
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK e SYNCHRONIZE
TRANSACTION_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE e TRANSACTION_GENERIC_EXECUTE
TRANSACTION_RESOURCE_MANAGER_RIGHTS	STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE e SYNCHRONIZE

In genere, un gestore risorse specifica TRANSACTION_RESOURCE_MANAGER_RIGHTS.

Il valore desiredAccess non può essere zero.

[in, optional] ObjectAttributes

Puntatore a una struttura OBJECT_ATTRIBUTES che specifica il nome dell'oggetto e altri attributi. Utilizzare la routine InitializeObjectAttributes per inizializzare questa struttura. Se il chiamante non è in esecuzione in un contesto di thread di sistema, deve impostare l'attributo OBJ_KERNEL_HANDLE quando chiama InitializeObjectAttributes. Questo parametro è facoltativo e può essere NULL.

[in, optional] Uow

Puntatore a un GUID usato da KTM come identificatore 'unità di lavoro (UOW) del nuovo oggetto transazione. Questo parametro è facoltativo e può essere NULL. Se questo parametro è NULL, KTM genera un GUID e lo assegna all'oggetto transazione. Per altre informazioni, vedere la sezione Osservazioni seguente.

[in, optional] TmHandle

Handle per un oggetto di gestione transazioni ottenuto da una chiamata precedente a ZwCreateTransactionManager o ZwOpenTransactionManager. KTM assegna il nuovo oggetto transazione all'oggetto di gestione transazioni specificato. Se questo parametro è NULL, KTM assegna il nuovo oggetto transazione a un gestore transazioni in un secondo momento, quando un gestore risorse crea un'integrazione per la transazione.

[in, optional] CreateOptions

Flag di creazione di oggetti facoltativi. La tabella seguente contiene i flag disponibili, definiti in Ktmtypes.h.

Flag di opzione	Significato
TRANSACTION_DO_NOT_PROMOTE	Riservato per uso futuro.

[in, optional] IsolationLevel

Riservato per uso futuro. I chiamanti devono impostare questo parametro su zero.

[in, optional] IsolationFlags

Riservato per uso futuro. I chiamanti devono impostare questo parametro su zero.

[in, optional] Timeout

Puntatore a un valore di timeout. Se il commit della transazione non è stato eseguito dal tempo specificato da questo parametro, KTM esegue il rollback della transazione. Il valore di timeout viene espresso in unità di tempo di sistema (intervalli di 100 nanosecondi) e può specificare un tempo assoluto o un tempo relativo. Se il valore a cui punta Timeout è negativo, l'ora di scadenza è relativa all'ora di sistema corrente. In caso contrario, l'ora di scadenza è assoluta. Questo puntatore è facoltativo e può essere NULL se non si desidera che la transazione abbia un valore di timeout. Se timeout = null o *timeout = 0, la transazione non raggiunge mai il timeout. Puoi anche usare ZwSetInformationTransaction per impostare un valore di timeout.

[in, optional] Description

Puntatore a una struttura di UNICODE_STRING fornita dal chiamante contenente una stringa con terminazione NULL. La stringa fornisce una descrizione della transazione. KTM archivia una copia della stringa e include la stringa nei messaggi scritti nel flusso di log. La lunghezza massima della stringa è MAX_TRANSACTION_DESCRIPTION_LENGTH. Questo parametro è facoltativo e può essere NULL.

Valore restituito

ZwCreateTransaction restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questa routine potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Il parametro CreateOptions contiene un flag non valido, il parametro DesiredAccess è pari a zero oppure la stringa Description parametro è troppo lunga.
STATUS_INSUFFICIENT_RESOURCES	KTM non è riuscito ad allocare risorse di sistema (in genere memoria).
STATUS_INVALID_ACL	Un descrittore di sicurezza contiene un elenco di controllo di accesso (ACL) non valido.
STATUS_INVALID_SID	Un descrittore di sicurezza contiene un SID (Security Identifier) non valido.
STATUS_OBJECT_NAME_EXISTS	Nome dell'oggetto specificato dal parametro objectAttributes esiste già.
STATUS_OBJECT_NAME_INVALID	Il nome dell'oggetto specificato dal parametro objectAttributes non è valido.
STATUS_ACCESS_DENIED	Il valore del parametro desiredAccess non è valido.

La routine potrebbe restituire altri valori NTSTATUS .

Osservazioni

Il chiamante può usare il parametro Uow per specificare un identificatore UOW per l'oggetto transazione. Se il chiamante non specifica un identificatore UOW, KTM genera un GUID e lo assegna all'oggetto transazione. Il chiamante può in seguito ottenere questo GUID chiamando ZwQueryInformationTransaction.

In genere, è consigliabile consentire a KTM di generare un GUID per l'oggetto transazione, a meno che il componente non comunichi con un altro componente TPS che ha già generato un identificatore UOW per la transazione.

Per chiudere l'handle di transazione, il componente che ha chiamato ZwCreateTransaction deve chiamare ZwClose. Se l'ultimo handle di transazione viene chiuso prima che qualsiasi componente chiami ZwCommitTransaction per la transazione, KTM esegue il rollback della transazione.

Per altre informazioni su come i client delle transazioni devono usare ZwCreateTransaction, vedere Creazione di un client transazionale.

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.

Fabbisogno

Requisito	Valore
client minimo supportato	Disponibile in Windows Vista e versioni successive del sistema operativo.
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