Funzione CreateLogFile (clfsw32.h)

Articolo
11/20/2024

Crea o apre un log. Il log può essere dedicato o multiplexed e dipende dal nome del log. Usare la funzione closehandle per chiudere il log.

Sintassi

CLFSUSER_API HANDLE CreateLogFile(
  [in]           LPCWSTR               pszLogFileName,
  [in]           ACCESS_MASK           fDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES psaLogFile,
  [in]           ULONG                 fCreateDisposition,
  [in]           ULONG                 fFlagsAndAttributes
);

Parametri

[in] pszLogFileName

Nome del log.

Questo nome viene specificato durante la creazione del log usando CreateLogFile. Nell'esempio seguente viene identificato il formato da utilizzare.

log :<LogName>[::<LogStreamName>]

Ad esempio: il percorso "LOG:c:\MyDirectory\MyLog" crea il file "c:\MyDirectory\MyLog.blf". Il percorso "?? \LOG:\HarddiskVolume1\MyDirectory\MyLog" crea il file "\.\HarddiskVolume1\MyDirectory\MyLog.blf", come fa il percorso "\clfs\Device\HarddiskVolume1\MyDirectory\MyLog".

< > LogName corrisponde a un percorso di file valido nel file system e <LogStreamName> è il nome univoco di un flusso di log nel log. Per altre informazioni, vedere tipi di log.

[in] fDesiredAccess

Tipo di accesso a cui l'handle restituito deve accedere all'oggetto log.

Valore	Significato
GENERIC_READ	Specifica l'accesso in lettura all'oggetto .
GENERIC_WRITE	Specifica l'accesso in scrittura all'oggetto .
DELETE	Specificare l'accesso all'eliminazione dei log

Un OR bit per bit di due o più di questi flag consente combinazioni di accesso in lettura, scrittura ed eliminazione all'oggetto.

Nota È necessario specificare DELETE l'accesso per poter eliminare il log.

Windows Server 2003 R2: Questo parametro deve essere impostato su GENERIC_WRITE.

[in] dwShareMode

Modalità di condivisione di un file.

Un client non può richiedere una modalità di condivisione in conflitto con qualsiasi modalità specificata in qualsiasi richiesta aperta precedente con un handle aperto.

Se questo parametro è zero e la funzione ha esito positivo, l'oggetto non può essere condiviso e non può essere aperto di nuovo finché l'handle non viene chiuso.

Questo parametro può essere uno o più dei valori seguenti.

Valore	Significato
FILE_SHARE_DELETE	Abilita le operazioni aperte sull'oggetto per richiedere l'accesso di eliminazione. Senza questo valore, altri processi non possono aprire l'oggetto se viene richiesto l'accesso all'eliminazione.
FILE_SHARE_READ	Abilita le operazioni aperte sull'oggetto per richiedere l'accesso in lettura. Senza questo valore, altri processi non possono aprire l'oggetto se è richiesto l'accesso in lettura.
FILE_SHARE_WRITE	Abilita le operazioni aperte sull'oggetto per richiedere l'accesso in scrittura. Senza questo valore, altri processi non possono aprire l'oggetto se viene richiesto l'accesso in scrittura.

[in, optional] psaLogFile

Puntatore a una struttura SECURITY_ATTRIBUTES che specifica gli attributi di sicurezza di un log.

Determina se l'handle restituito può essere ereditato dai processi figlio. Se questo parametro è NULL, l'handle non può essere ereditato.

Il lpSecurityDescriptor membro di SECURITY_ATTRIBUTES specifica un descrittore di sicurezza per il nuovo handle di log. Se psaLogFile è NULL, l'oggetto ottiene un descrittore di sicurezza predefinito. Gli elenchi di controllo di accesso (ACL) nel descrittore di sicurezza predefinito per un log provengono dal token primario o di rappresentazione dell'autore.

[in] fCreateDisposition

Un'azione da intraprendere.

Questo parametro può essere uno dei valori seguenti.

Valore	Significato
CREATE_NEW	Crea un nuovo file e ha esito negativo se il file esiste già.
OPEN_EXISTING	Apre un file esistente e ha esito negativo se il file non esiste.
OPEN_ALWAYS	Apre un file esistente o crea il file, se non esiste.

[in] fFlagsAndAttributes

Attributi e flag di file per il file.

Questo parametro può accettare i valori seguenti.

Valore	Significato
FILE_ATTRIBUTE_ARCHIVE	Questo log non temporaneo deve essere archiviato. Se questo flag non viene fornito, il log non deve essere archiviato e una parte finale di archiviazione non viene mantenuta per i contenitori di log di riciclo.
FILE_FLAG_OVERLAPPED	Se il flag FILE_FLAG_OVERLAPPED è impostato, tutti gli altri valori flag vengono ignorati. Specificando FILE_FLAG_OVERLAPPED si intende che un file viene aperto per operazioni di I/O sovrapposte, che consente l'esecuzione di più operazioni di I/O nell'handle di log. Se questo flag viene impostato durante la creazione di un log, tutte le chiamate di I/O asincrone a tale log devono specificare una struttura sovrapposta e sincronizzarsi con il completamento posticipato della chiamata.

Valore

Significato

FILE_ATTRIBUTE_ARCHIVE

Questo log non temporaneo deve essere archiviato.

Se questo flag non viene fornito, il log non deve essere archiviato e una parte finale di archiviazione non viene mantenuta per i contenitori di log di riciclo.

FILE_FLAG_OVERLAPPED

Se il flag FILE_FLAG_OVERLAPPED è impostato, tutti gli altri valori flag vengono ignorati.

Specificando FILE_FLAG_OVERLAPPED si intende che un file viene aperto per operazioni di I/O sovrapposte, che consente l'esecuzione di più operazioni di I/O nell'handle di log. Se questo flag viene impostato durante la creazione di un log, tutte le chiamate di I/O asincrone a tale log devono specificare una struttura sovrapposta e sincronizzarsi con il completamento posticipato della chiamata.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per il log.

Se la funzione ha esito negativo, il valore restituito è INVALID_HANDLE_VALUE. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

L'elenco seguente identifica i possibili codici di errore:

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [solo app desktop]
server minimo supportato	Windows Server 2003 R2 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	clfsw32.h
libreria	Clfsw32.lib
dll	Clfsw32.dll