Funzione NtCreateTransaction (wdm.h)

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.

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.

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.

[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:

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

Vedi anche

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

UNICODE_STRING

Uso di nt e zw versioni delle routine di Servizi di sistema nativo

ZwClose

ZwCommitTransaction

ZwCreateEnlistment

ZwCreateTransactionManager

ZwOpenTransaction

ZwOpenTransactionManager

ZwQueryInformationTransaction

ZwRollbackTransaction

ZwSetInformationTransaction