Funzione NtCreateResourceManager (wdm.h)

Articolo
08/08/2023

La routine ZwCreateResourceManager crea un oggetto resource manager.

Sintassi

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateResourceManager(
  [out]          PHANDLE            ResourceManagerHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           HANDLE             TmHandle,
  [in]           LPGUID             RmGuid,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] ULONG              CreateOptions,
  [in, optional] PUNICODE_STRING    Description
);

Parametri

[out] ResourceManagerHandle

Puntatore a una variabile allocata dal chiamante che riceve un handle al nuovo oggetto resource manager se la chiamata a ZwCreateResourceManager ha esito positivo.

[in] DesiredAccess

Valore ACCESS_MASK che specifica l'accesso richiesto dal chiamante all'oggetto Resource Manager. 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 resource manager:

flag ACCESS_MASK	Consente al chiamante di
RESOURCEMANAGER_ENLIST	Inserimento nelle transazioni (vedere ZwCreateEnlistment).
RESOURCEMANAGER_GET_NOTIFICATION	Ricevere notifiche sulle transazioni associate a questo resource manager (vedere ZwGetNotificationResourceManager).
RESOURCEMANAGER_REGISTER_PROTOCOL	Non usato.
RESOURCEMANAGER_QUERY_INFORMATION	Eseguire query sulle informazioni su Resource Manager (vedere ZwQueryInformationResourceManager).
RESOURCEMANAGER_SET_INFORMATION	Non usato.
RESOURCEMANAGER_RECOVER	Ripristinare resource manager (vedere ZwRecoverResourceManager).
RESOURCEMANAGER_COMPLETE_PROPAGATION	Non usato.

In alternativa, è possibile specificare uno o più flag generici ACCESS_MASK seguenti. I flag STANDARD_RIGHTS_Xxx sono valori di sistema predefiniti usati per applicare la sicurezza agli oggetti di sistema. È anche possibile combinare questi flag generici con flag aggiuntivi dalla tabella precedente. Nella tabella seguente viene illustrato il modo in cui i diritti di accesso generico corrispondono a diritti di accesso specifici.

Diritto di accesso generico	Set di diritti di accesso specifici
RESOURCEMANAGER_GENERIC_READ	STANDARD_RIGHTS_READ, RESOURCEMANAGER_QUERY_INFORMATION e SYNC
RESOURCEMANAGER_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, RESOURCEMANAGER_SET_INFORMATION, RESOURCEMANAGER_RECOVER, RESOURCEMANAGER_ENLIST, RESOURCEMANAGER_GET_NOTIFICATION, RESOURCEMANAGER_REGISTER_PROTOCOL, RESOURCEMANAGER_COMPLETE_PROPAGATION e SYNC
RESOURCEMANAGER_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, RESOURCEMANAGER_RECOVER, RESOURCEMANAGER_ENLIST, RESOURCEMANAGER_GET_NOTIFICATION, RESOURCEMANAGER_COMPLETE_PROPAGATION e SYNC
RESOURCEMANAGER_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, RESOURCEMANAGER_GENERIC_READ, RESOURCEMANAGER_GENERIC_WRITE e RESOURCEMANAGER_GENERIC_EXECUTE

[in] TmHandle

Handle a un oggetto di gestione transazioni ottenuto da un elemento precedente a ZwCreateTransactionManager o ZwOpenTransactionManager.

[in] RmGuid

Puntatore a un GUID che KTM userà per identificare il resource manager. Se questo puntatore è NULL, KTM genera un GUID.

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

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

Flag CreateOptions	Significato
RESOURCE_MANAGER_COMMUNICATION	Solo per uso interno.
RESOURCE_MANAGER_VOLATILE	Il chiamante gestirà le risorse volatili. Sarà non persistente e non eseguirà il ripristino.

Questo parametro è facoltativo e può essere zero.

[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 di Resource Manager. KTM archivia una copia della stringa e include la stringa nei messaggi che scrive nel flusso di log. La lunghezza massima della stringa è MAX_RESOURCEMANAGER_DESCRIPTION_LENGTH. Questo parametro è facoltativo e può essere NULL.

Valore restituito

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

Codice restituito	Descrizione
STATUS_OBJECT_TYPE_MISMATCH	L'handle specificato da TmHandle non è un handle per un oggetto transazione.
STATUS_INVALID_HANDLE	L'handle specificato da TmHandle non è valido.
STATUS_ACCESS_DENIED	Il chiamante non dispone dell'accesso appropriato all'oggetto di gestione transazioni specificato.
STATUS_TRANSACTION_OBJECT_EXPIRED	L'handle specificato da TmHandle viene chiuso.
STATUS_INVALID_PARAMETER	Il valore del parametro CreateOptions non è valido o la stringa del parametro Description è troppo lunga.
STATUS_TM_VOLATILE	Il parametro CreateOptions non specifica RESOURCE_MANAGER_VOLATILE ma il gestore delle transazioni specificato da TmHandle è volatile.
STATUS_OBJECT_NAME_COLLISION	IL GUID specificato da ResourceManagerGuid esiste già.
STATUS_ACCESS_DENIED	Il valore del parametro DesiredAccess non è valido.

La routine potrebbe restituire altri valori NTSTATUS.

Commenti

Un resource manager che chiama ZwCreateResourceManager deve chiamare eventualmente ZwClose per chiudere l'handle dell'oggetto.

Per altre informazioni su ZwCreateResourceManager, vedere Creazione di un Resource Manager.

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