Funzione NtCreateTransaction (wdm.h)

Articolo
02/27/2024

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 al 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 transazioni.

Maschera di accesso	Consente al chiamante di
TRANSACTION_COMMIT	Eseguire il commit della transazione (vedere ZwCommitTransaction).
TRANSACTION_ENLIST	Creare un elenco 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 seguenti ACCESS_MASK. Queste bitmap combinano i flag della tabella precedente con i flag STANDARD_RIGHTS_XXX descritti nella pagina di riferimento ACCESS_MASK. È anche possibile combinare queste bitmap con flag aggiuntivi dalla 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 SYNC
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT e SYNC
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK e SYNC
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 SYNC

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. Usare 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 dell'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 transazioni. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, optional] TmHandle

Handle a 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 elenco 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 usi futuri.

[in, optional] IsolationLevel

Riservato per usi futuri. I chiamanti devono impostare questo parametro su zero.

[in, optional] IsolationFlags

Riservato per utilizzi futuri. I chiamanti devono impostare questo parametro su zero.

[in, optional] Timeout

Puntatore a un valore di timeout. Se la transazione non è stata eseguito il commit entro l'ora specificata da questo parametro, KTM esegue il rollback della transazione. Il valore di timeout viene espresso in unità temporali di sistema (intervalli a 100 nanosecondi) e può specificare un tempo assoluto o un tempo relativo. Se il valore puntato da 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 vuole che la transazione abbia un valore di timeout. Se TimeoutNULL o *Timeout = = 0, la transazione non viene mai interrotta. È anche possibile usare ZwSetInformationTransaction per impostare un valore di timeout.

[in, optional] Description

Puntatore a una struttura di UNICODE_STRING fornita dal chiamante che contiene una stringa con terminazione NULL. La stringa fornisce una descrizione della transazione. KTM archivia una copia della stringa e include la stringa nei messaggi che scrive 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 è zero o la stringa del parametro Description è troppo lunga.
STATUS_INSUFFICIENT_RESOURCES	KTM non ha potuto allocare le risorse di sistema (in genere memoria).
STATUS_INVALID_ACL	Un descrittore di sicurezza contiene un elenco di controllo di accesso non valido .
STATUS_INVALID_SID	Un descrittore di sicurezza contiene un identificatore di sicurezza non valido (SID).
STATUS_OBJECT_NAME_EXISTS	Nome dell'oggetto che il parametro ObjectAttributes specifica già esistente.
STATUS_OBJECT_NAME_INVALID	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.

Commenti

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 delle transazioni, il componente denominato 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 sul modo in cui i client delle transazioni devono usare ZwCreateTransaction, vedere Creazione di un client transazionale.

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.

Requisiti

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