Funzione ClfsCreateLogFile (wdm.h)
La routine ClfsCreateLogFile crea o apre un flusso CLFS. Se necessario, ClfsCreateLogFile crea anche il log fisico sottostante che contiene i record del flusso.
Sintassi
CLFSUSER_API NTSTATUS ClfsCreateLogFile(
[out] PPLOG_FILE_OBJECT pplfoLog,
[in] PUNICODE_STRING puszLogFileName,
[in] ACCESS_MASK fDesiredAccess,
[in] ULONG dwShareMode,
[in, optional] PSECURITY_DESCRIPTOR psdLogFile,
[in] ULONG fCreateDisposition,
[in] ULONG fCreateOptions,
[in] ULONG fFlagsAndAttributes,
[in] ULONG fLogOptionFlag,
[in, optional] PVOID pvContext,
[in] ULONG cbContext
);
Parametri
[out] pplfoLog
Puntatore a una variabile che riceve un puntatore a una struttura LOG_FILE_OBJECT che rappresenta un'istanza aperta del flusso.
[in] puszLogFileName
Puntatore a una struttura UNICODE_STRING che specifica il nome del flusso o del log fisico sottostante.
Se il flusso esiste già ed è l'unico flusso di un log dedicato, il nome ha il nome del log fisico:fisico, dove il nome del log fisico è il nome del percorso, nel file system sottostante, del log fisico esistente che contiene i record del flusso.
Se il flusso non esiste già e deve diventare l'unico flusso di un log dedicato (che non esiste ancora), il nome ha il nome del log fisico: il nome del log fisico, dove il nome del log fisico è il nome del percorso, nel file system sottostante, del log fisico che verrà creato per contenere i record del flusso.
Se il flusso è (o diventa) uno dei flussi di un log multiplexed, il nome ha il nome del log del modulo:nome log fisico::nome del log fisico, dove il nome del log fisico è il nome del percorso, nel file system sottostante, del log fisico che contiene i record del flusso e il nome del flusso è il nome di un flusso che condivide (o condividerà) tale log fisico.
Se si vuole creare un log multiplexed senza flussi per il momento, usare un nome del nome del log fisico::, dove il nome del log fisico è il nome del percorso, nel file system sottostante, del log fisico da creare.
L'elenco seguente fornisce alcuni esempi di nomi validi.
- "Log:c:\myLog" crea o apre un log dedicato e il relativo flusso.
- "Log:c:\myCommonLog::" crea un log multiplexed che non dispone ancora di flussi.
- "Log:c:\myCommonLog::Stream1" crea o apre uno dei flussi (Stream1) di un log multiplexed.
[in] fDesiredAccess
Un ACCESS_MASK che fornisce il tipo di accesso al client avrà (usando il puntatore restituito in pplfoLog) al flusso. Se questo parametro è zero, i client possono eseguire query sul flusso per i relativi attributi, ma non possono leggere o scrivere nel flusso. Questo parametro può essere zero o qualsiasi combinazione dei flag seguenti:
| Contrassegno | Significato |
|---|---|
| GENERIC_READ | Il client ha accesso in lettura al flusso. |
| GENERIC_WRITE | Il client ha accesso in scrittura al flusso. |
| DELETE | Il client può contrassegnare il flusso per l'eliminazione. |
[in] dwShareMode
La modalità di condivisione del flusso, che può essere zero (non condivisa) o qualsiasi combinazione dei flag seguenti:
| Contrassegno | Significato |
|---|---|
| FILE_SHARE_DELETE | Le richieste successive per aprire il flusso con l'accesso eliminato avranno esito positivo. |
| FILE_SHARE_READ | Le richieste successive per aprire il flusso con accesso in lettura avranno esito positivo. |
| FILE_SHARE_WRITE | Le richieste successive per aprire il flusso con l'accesso in scrittura avranno esito positivo. |
[in, optional] psdLogFile
Puntatore a una struttura SECURITY_DESCRIPTOR che fornisce attributi di sicurezza per il flusso. Questo parametro può essere NULL.
[in] fCreateDisposition
L'azione da eseguire dipende dal fatto che il flusso esista già. Questo parametro deve essere impostato su uno dei valori seguenti:
| Valore | Significato |
|---|---|
| CREATE_NEW | Creare un nuovo flusso se il flusso non viene già chiuso. Errore se il flusso esiste già. |
| OPEN_EXISTING | Aprire un flusso esistente. Errore se il flusso non esiste già. |
| OPEN_ALWAYS | Aprire un flusso esistente. Creare il flusso se non esiste già. |
[in] fCreateOptions
Set di flag che specificano le opzioni da applicare durante la creazione o l'apertura del flusso. Questo parametro può essere zero o una combinazione compatibile dei flag seguenti:
| Contrassegno | Significato |
|---|---|
| FILE_NO_INTERMEDIATE_BUFFERING | I record del flusso non possono essere memorizzati nella cache nei buffer interni di un driver. |
| FILE_SYNCHRONOUS_IO_ALERT | Tutte le operazioni sul flusso vengono eseguite in modo sincrono. Qualsiasi attesa per conto del chiamante è soggetta alla terminazione prematura dagli avvisi. Se questo flag è impostato, è necessario cancellare il flag FILE_SYNCHRONOUS_IO_NONALERT. |
| FILE_SYNCHRONOUS_IO_NONALERT | Tutte le operazioni sul flusso vengono eseguite in modo sincrono. Le attese nel sistema che sincronizzano l'accodamento e il completamento di I/O non sono soggetti agli avvisi. Se questo flag è impostato, è necessario cancellare il flag FILE_SYNCHRONOUS_IO_ALERT. |
[in] fFlagsAndAttributes
Valore che specifica se il flusso viene aperto per l'accesso normale o di sola lettura. Questo parametro deve essere impostato su entrambi
FILE_ATTRIBUTE_NORMAL o FILE_ATTRIBUTE_READONLY.
[in] fLogOptionFlag
Hint sulla relazione tra CLFS e il componente che crea o apre il flusso. Questo parametro deve essere impostato su uno dei valori seguenti:
| Valore | Significato |
|---|---|
| CLFS_FLAG_NO_FLAGS | CLFS e il componente di creazione hanno la relazione standard e normale. I componenti in modalità kernel usano questo valore a meno che non rientrano in una delle tre altre categorie elencate in questa tabella. Se pvContext non è NULL, CLFS verifica che cbContext sia maggiore di zero. In caso contrario, pvContext e cbContext vengono ignorati. |
| CLFS_FLAG_REENTRANT_FILE_SYSTEM | Il componente di creazione è il file system che fornisce l'archiviazione sottostante per CLFS. CLFS usa il file system per l'allocazione di contenitori e il file system usa flussi CLFS. In questo caso, è possibile che il file system chiami CLFS e che CLFS effettua le chiamate al file system nello stesso thread o in thread diversi. Se pvContext non è NULL, CLFS verifica che cbContext sia maggiore di zero. In caso contrario, pvContext e cbContext vengono ignorati. |
| CLFS_FLAG_NON_REENTRANT_FILTER | Il componente di creazione è un driver di filtro del file system che invia tutti i relativi I/O CLFS a un livello specificato sotto se stesso nello stack di filtri. Questa opzione consente a un driver di filtro di creare un log CLFS senza visualizzarne la registrazione. Il chiamante passa l'oggetto dispositivo di destinazione non NULL nel parametro pvContext con cbContext impostato sulle dimensioni appropriate. CLFS usa la routine IoCreateFileSpecifyDeviceObjectHint per creare contenitori a livello di destinazione nello stack di filtri I/O specificato dall'oggetto dispositivo. |
| CLFS_FLAG_REENTRANT_FILTER | Il componente di creazione è un driver di filtro del file system che invia tutti i relativi I/O CLFS all'inizio dello stack di filtri. Il filtro ha una relazione ricorsiva con CLFS perché filtra la propria registrazione di I/O quando CLFS esegue qualsiasi operazione di file system nei contenitori. Il parametro pvContext fornisce un mezzo per i filtri per associare un contesto riconoscibile ai contenitori CLFS come log I/O scende lo stack di filtri. Il parametro cbContext specifica le dimensioni del contesto opaco in byte. |
| CLFS_FLAG_MINIFILTER_LEVEL | Il componente di creazione è un driver minifilter del file system che invia tutti i relativi I/O CLFS a un livello specificato sotto se stesso nello stack di filtri. Questa opzione consente a un minifilter di creare un log CLFS senza visualizzare la propria registrazione di I/O. Il chiamante passa l'oggetto contesto minifilter non NULL nel parametro pvContext con cbContext impostato sulle dimensioni appropriate. CLFS usa la routine IoCreateFileSpecifyDeviceObjectHint per creare contenitori a un'altitudine (specificata all'interno del contesto del minifiltro) nello stack minifilter del gestore filtri. |
[in, optional] pvContext
Puntatore a un contesto. La modalità di interpretazione del contesto dipende dal valore passato a fLogOptionsFlag.
[in] cbContext
Dimensione, in byte, del contesto a cui punta pvContext. Se pvContext non è NULL, questo parametro deve essere maggiore di zero.
Valore restituito
ClfsCreateLogFile restituisce STATUS_SUCCESS se ha esito positivo; in caso contrario, restituisce uno dei codici di errore definiti in Ntstatus.h.
Commenti
Quando si crea un flusso CLFS, viene supportato da un log CLFS fisico sottostante. Il log sottostante può essere dedicato (esegue il backup di un solo flusso) o multiplexed (esegue il backup di più flussi). Non è possibile convertire un log dedicato in un log multiplexed e non è possibile convertire un log multiplexed in un log dedicato.
Un nome di log CLFS fisico non include l'estensione blf.
Per una spiegazione dei concetti e della terminologia di CLFS, vedere Common Log File System.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile in Windows Server 2003 R2, Windows Vista e versioni successive di Windows. |
| Piattaforma di destinazione | Desktop |
| Intestazione | wdm.h (include Wdm.h) |
| Libreria | Clfs.lib |
| DLL | Clfs.sys |
| IRQL | <= APC_LEVEL |