Funzione ZwCreateTransactionManager (wdm.h)

Articolo
08/08/2023

La routine ZwCreateTransactionManager crea un nuovo oggetto di gestione transazioni.

Sintassi

NTSYSCALLAPI NTSTATUS ZwCreateTransactionManager(
  [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 al nuovo oggetto di gestione transazioni.

[in] DesiredAccess

Valore ACCESS_MASK che specifica l'accesso richiesto dal chiamante all'oggetto 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 resource manager (vedere ZwCreateResourceManager).
TRANSACTIONMANAGER_QUERY_INFORMATION	Ottenere informazioni sulla gestione delle transazioni (vedere ZwQueryInformationTransactionManager e ZwEnumerateTransactionObject). Obbligatorio anche per ZwOpenResourceManager, ZwCreateTransaction e ZwOpenTransaction.
TRANSACTIONMANAGER_RECOVER	Ripristinare il gestore delle transazioni (vedere ZwRecoverTransactionManager e ZwRollforwardTransactionManager).
TRANSACTIONMANAGER_RENAME	Non usato.
TRANSACTIONMANAGER_SET_INFORMATION	Non usato.

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
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. 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] 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 gestione transazioni. Questo parametro deve essere NULL se il parametro CreateOptions è TRANSACTION_MANAGER_VOLATILE. In caso contrario, questo parametro deve essere diverso da NULL. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[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 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 utilizzi futuri. 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 ha potuto allocare le 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 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_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	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

Se il flusso di 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 di risorse associati all'oggetto gestione transazioni devono specificare il flag di 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 Creazione di un Resource Manager.

NtCreateTransactionManager e ZwCreateTransactionManager sono due versioni della stessa routine di Windows Native System Services.

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, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)