CreateLogFile, fonction (clfsw32.h)

Article
08/22/2023

Crée ou ouvre un journal. Le journal peut être dédié ou multiplexé, ce qui dépend du nom du journal. Utilisez la fonction CloseHandle pour fermer le journal.

Syntaxe

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
);

Paramètres

[in] pszLogFileName

Nom du journal.

Ce nom est spécifié lors de la création du journal à l’aide de CreateLogFile. L’exemple suivant identifie le format à utiliser.

rapport:<LogName>[ ::<LogStreamName>]

Par exemple : le chemin « LOG :c :\MyDirectory\MyLog » crée le fichier « c :\MyDirectory\MyLog.blf ». Le chemin « ?? \LOG :\HarddiskVolume1\MyDirectory\MyLog » crée le fichier « \.\HarddiskVolume1\MyDirectory\MyLog.blf », tout comme le chemin d’accès « \clfs\Device\HarddiskVolume1\MyDirectory\MyLog ».

<Logname> correspond à un chemin de fichier valide dans le système de fichiers, et <LogStreamName> est le nom unique d’un flux de journal dans le journal. Pour plus d’informations, consultez Types de journaux.

[in] fDesiredAccess

Type d’accès que le handle retourné a à l’objet journal.

Valeur	Signification
GENERIC_READ	Spécifie l’accès en lecture à l’objet.
GENERIC_WRITE	Spécifie l’accès en écriture à l’objet.
DELETE	Spécifier l’accès à la suppression des journaux

Un OR au niveau du bit de deux ou plusieurs de ces indicateurs autorise des combinaisons d’accès en lecture, écriture et suppression à l’objet.

Note Vous devez spécifier l’accès DELETE pour pouvoir supprimer le journal.

Windows Server 2003 R2 : Ce paramètre doit être défini sur GENERIC_WRITE.

[in] dwShareMode

Mode de partage d’un fichier.

Un client ne peut pas demander un mode de partage qui entre en conflit avec un mode spécifié dans une demande ouverte précédente qui a un handle ouvert.

Si ce paramètre est égal à zéro et que la fonction réussit, l’objet ne peut pas être partagé et ne peut pas être rouvert tant que le handle n’est pas fermé.

Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.

Valeur	Signification
FILE_SHARE_DELETE	Active les opérations d’ouverture sur l’objet pour demander l’accès à la suppression. Sans cette valeur, d’autres processus ne peuvent pas ouvrir l’objet si l’accès de suppression est demandé.
FILE_SHARE_READ	Active les opérations d’ouverture sur l’objet pour demander l’accès en lecture. Sans cette valeur, d’autres processus ne peuvent pas ouvrir l’objet si l’accès en lecture est demandé.
FILE_SHARE_WRITE	Active les opérations d’ouverture sur l’objet pour demander l’accès en écriture. Sans cette valeur, d’autres processus ne peuvent pas ouvrir l’objet si l’accès en écriture est demandé.

[in, optional] psaLogFile

Pointeur vers une structure SECURITY_ATTRIBUTES qui spécifie les attributs de sécurité d’un journal.

Il détermine si le handle retourné peut être hérité par des processus enfants. Si ce paramètre a la valeur NULL, le handle ne peut pas être hérité.

Le membre lpSecurityDescriptor de SECURITY_ATTRIBUTES spécifie un descripteur de sécurité pour le nouveau handle de journal. Si psaLogFile a la valeur NULL, l’objet obtient un descripteur de sécurité par défaut. Les listes de contrôle d’accès (ACL) dans le descripteur de sécurité par défaut d’un journal proviennent du jeton principal ou d’emprunt d’identité du créateur.

[in] fCreateDisposition

Action à entreprendre.

Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
CREATE_NEW	Crée un fichier et échoue si le fichier existe déjà.
OPEN_EXISTING	Ouvre un fichier existant et échoue si le fichier n’existe pas.
OPEN_ALWAYS	Ouvre un fichier existant ou crée le fichier s’il n’existe pas.

[in] fFlagsAndAttributes

Attributs et indicateurs de fichier pour le fichier.

Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
FILE_ATTRIBUTE_ARCHIVE	Ce journal non éphémère doit être archivé. Si cet indicateur n’est pas fourni, le journal n’a pas besoin d’être archivé et une queue d’archivage n’est pas conservée pour recycler les conteneurs de journaux.
FILE_FLAG_OVERLAPPED	Si l’indicateur FILE_FLAG_OVERLAPPED est défini, toutes les autres valeurs d’indicateur sont ignorées. La spécification de FILE_FLAG_OVERLAPPED signifie qu’un fichier est ouvert pour les E/S qui se chevauchent, ce qui permet d’effectuer plusieurs opérations d’E/S sur le handle du journal. Si cet indicateur est défini lors de la création d’un journal, tous les appels d’E/S asynchrones à ce journal doivent spécifier une structure qui se chevauche et se synchroniser avec la fin différée de l’appel.

Valeur

Signification

FILE_ATTRIBUTE_ARCHIVE

Ce journal non éphémère doit être archivé.

Si cet indicateur n’est pas fourni, le journal n’a pas besoin d’être archivé et une queue d’archivage n’est pas conservée pour recycler les conteneurs de journaux.

FILE_FLAG_OVERLAPPED

Si l’indicateur FILE_FLAG_OVERLAPPED est défini, toutes les autres valeurs d’indicateur sont ignorées.

La spécification de FILE_FLAG_OVERLAPPED signifie qu’un fichier est ouvert pour les E/S qui se chevauchent, ce qui permet d’effectuer plusieurs opérations d’E/S sur le handle du journal. Si cet indicateur est défini lors de la création d’un journal, tous les appels d’E/S asynchrones à ce journal doivent spécifier une structure qui se chevauche et se synchroniser avec la fin différée de l’appel.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle dans le journal.

Si la fonction échoue, la valeur de retour est INVALID_HANDLE_VALUE. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

La liste suivante identifie les codes d’erreur possibles :

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	clfsw32.h
Bibliothèque	Clfsw32.lib
DLL	Clfsw32.dll