Funzione CreateLogFile (clfsw32.h)

Articolo
02/23/2024

Crea o apre un log. Il log può essere dedicato o multiplexed e che 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 quando si crea il log usando CreateLogFile. Nell'esempio seguente viene identificato il formato da usare.

Registro:<LogName[::<LogStreamName>>]

Ad esempio, il percorso "LOG:c:\MyDirectory\MyLog" crea il file "c:\MyDirectory\MyLog.blf". 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 al quale 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ù flag consente combinazioni di lettura, scrittura ed eliminazione dell'accesso all'oggetto.

Nota È necessario specificare l'accesso DELETE 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 nuovamente aperto 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 eliminato. 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 viene 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 membro lpSecurityDescriptor 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ò avere 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 non riesce 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 coda 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 di flag vengono ignorati. Specificando FILE_FLAG_OVERLAPPED significa che un file viene aperto per l'I/O sovrapposto, 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 sincronizzare 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 coda 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 di flag vengono ignorati.

Specificando FILE_FLAG_OVERLAPPED significa che un file viene aperto per l'I/O sovrapposto, 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 sincronizzare 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 informazioni dettagliate sull'errore, chiamare GetLastError.

L'elenco seguente identifica i possibili codici di errore:

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2003 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	clfsw32.h
Libreria	Clfsw32.lib
DLL	Clfsw32.dll