Funzione NtCreateTransactionManager (wdm.h)

Articolo
02/07/2025

La routine ZwCreateTransactionManager crea un nuovo oggetto di gestione transazioni.

Sintassi

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              CommitStrength
);

Parametri

[out] TmHandle

Puntatore a una variabile allocata dal chiamante che riceve un handle per il nuovo oggetto di gestione transazioni .

[in] DesiredAccess

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

flag ACCESS_MASK	Consente al chiamante di
TRANSACTIONMANAGER_CREATE_RM	Creare un gestore di risorse (vedere ZwCreateResourceManager).
TRANSACTIONMANAGER_QUERY_INFORMATION	Ottenere informazioni sul gestore delle transazioni (vedere ZwQueryInformationTransactionManager e ZwEnumerateTransactionObject). Necessario anche per ZwOpenResourceManager, ZwCreateTransactione ZwOpenTransaction.)
TRANSACTIONMANAGER_RECOVER	Ripristinare il gestore delle transazioni (vedere ZwRecoverTransactionManager e ZwRollforwardTransactionManager).
TRANSACTIONMANAGER_RENAME	Non utilizzato.
TRANSACTIONMANAGER_SET_INFORMATION	Non utilizzato.

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
TRANSACTIONMANAGER_GENERIC_READ	STANDARD_RIGHTS_READ e TRANSACTIONMANAGER_QUERY_INFORMATION
TRANSACTIONMANAGER_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTIONMANAGER_SET_INFORMATION, TRANSACTIONMANAGER_RECOVER, TRANSACTIONMANAGER_RENAME e TRANSACTIONMANAGER_CREATE_RM
TRANSACTIONMANAGER_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE
TRANSACTIONMANAGER_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTIONMANAGER_GENERIC_READ, TRANSACTIONMANAGER_GENERIC_WRITE e TRANSACTIONMANAGER_GENERIC_EXECUTE

[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] LogFileName

Puntatore a una struttura UNICODE_STRING che contiene il percorso e il nome file di un flusso di file di log CLFS da associare all'oggetto di gestione transazioni. Questo parametro deve essere NULL se il parametro createOptions è TRANSACTION_MANAGER_VOLATILE. In caso contrario, questo parametro deve essere diverso daNULL. Per altre informazioni, vedere la sezione Osservazioni seguente.

[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_MANAGER_VOLATILE	L'oggetto di gestione transazioni sarà volatile. Pertanto, non userà un file di log.
TRANSACTION_MANAGER_COMMIT_DEFAULT	Solo per uso interno.
TRANSACTION_MANAGER_COMMIT_SYSTEM_VOLUME	Solo per uso interno.
TRANSACTION_MANAGER_COMMIT_SYSTEM_HIVES	Solo per uso interno.
TRANSACTION_MANAGER_COMMIT_LOWEST	Solo per uso interno.
TRANSACTION_MANAGER_CORRUPT_FOR_RECOVERY	Solo per uso interno.
TRANSACTION_MANAGER_CORRUPT_FOR_PROGRESS	Solo per uso interno.

[in, optional] CommitStrength

Riservato per uso futuro. Questo parametro deve essere zero.

Valore restituito

ZwCreateTransactionManager 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 valore di un parametro di input non è valido.
STATUS_INSUFFICIENT_RESOURCES	KTM non è riuscito ad allocare risorse di sistema (in genere memoria).
STATUS_LOG_CORRUPTION_DETECTED	KTM ha rilevato un errore durante la creazione o l'apertura del file di log.
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_COLLISION	Il sistema operativo ha rilevato un nome di oggetto duplicato. L'errore potrebbe indicare che il flusso di log è già in uso.
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

Se il flusso del file di log specificato dal parametro LogFileName non esiste, KTM chiama CLFS per creare il flusso. Se il flusso esiste già, KTM chiama CLFS per aprire il flusso.

Il componente TPS deve chiamare ZwRecoverTransactionManager dopo aver chiamato ZwCreateTransactionManager

Se il componente TPS specifica il flag TRANSACTION_MANAGER_VOLATILE nel parametro CreateOptions , tutti i gestori risorse associati all'oggetto di gestione transazioni devono specificare il flag RESOURCE_MANAGER_VOLATILE quando chiamano ZwCreateResourceManager.

Un componente TPS che chiama ZwCreateTransactionManager deve infine chiamare ZwClose per chiudere l'handle dell'oggetto.

Per altre informazioni sull'uso di ZwCreateTransactionManager, vedere Creating a Resource Manager.

NtCreateTransactionManager e ZwCreateTransactionManager sono due versioni della stessa routine di Servizi di sistema nativi di Windows.

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, Ntifs.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
regole di conformità DDI	HwStorPortProhibitedDDIs, PowerIrpDDis