Condividi tramite


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

Vedi anche

ClfsCloseAndResetLogFile

ClfsCloseLogFileObject

ClfsDeleteLogByPointer

ClfsDeleteLogFile