Partager via


Fonction ClfsCreateLogFile (wdm.h)

La routine ClfsCreateLogFile crée ou ouvre un flux CLFS. Si nécessaire, ClfsCreateLogFile crée également le journal physique sous-jacent qui contient les enregistrements du flux.

Syntaxe

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

Paramètres

[out] pplfoLog

Pointeur vers une variable qui reçoit un pointeur vers une structure LOG_FILE_OBJECT qui représente une instance ouverte du flux.

[in] puszLogFileName

Pointeur vers une structure UNICODE_STRING qui fournit le nom du flux ou le journal physique sous-jacent.

Si le flux existe déjà et qu’il s’agit du seul flux d’un journal dédié, le nom a la forme log :nom du journal physique, où nom du journal physique est le nom du chemin d’accès, sur le système de fichiers sous-jacent, du journal physique existant qui contient les enregistrements du flux.

Si le flux n’existe pas déjà et doit devenir le seul flux d’un journal dédié (qui n’existe pas encore), le nom a la forme log :nom du journal physique, où nom du journal physique est le nom du chemin d’accès, sur le système de fichiers sous-jacent, du journal physique qui sera créé pour contenir les enregistrements du flux.

Si le flux est (ou doit devenir) l’un des flux d’un journal multiplexé, le nom a la forme log :physical log name ::stream, où nom du journal physique est le nom du chemin d’accès, sur le système de fichiers sous-jacent, du journal physique qui contient les enregistrements du flux, et le nom du flux est le nom d’un flux qui partage (ou partagera) ce journal physique.

Si vous souhaitez créer un journal multiplexé qui n’a pas de flux pour le moment, utilisez un nom au format log :physical log name ::, où nom du journal physique est le nom du chemin d’accès, sur le système de fichiers sous-jacent, du journal physique à créer.

La liste suivante fournit quelques exemples de noms valides.

  • « Log :c :\myLog » crée ou ouvre un journal dédié et son flux unique.
  • « Log :c :\myCommonLog :: » crée un journal multiplexé qui n’a pas encore de flux.
  • « Log :c :\myCommonLog ::Stream1 » crée ou ouvre l’un des flux (Stream1) d’un journal multiplexé.

[in] fDesiredAccess

Une ACCESS_MASK qui fournit le type d’accès du client (à l’aide du pointeur retourné dans pplfoLog) au flux. Si ce paramètre est égal à zéro, les clients peuvent interroger le flux pour ses attributs, mais ne peuvent pas lire ou écrire dans le flux. Ce paramètre peut être zéro ou n’importe quelle combinaison des indicateurs suivants :

Indicateur Signification
GENERIC_READ Le client dispose d’un accès en lecture au flux.
GENERIC_WRITE Le client dispose d’un accès en écriture au flux.
Suppression Le client peut marquer le flux pour suppression.

[in] dwShareMode

Mode de partage du flux, qui peut être zéro (non partagé) ou toute combinaison des indicateurs suivants :

Indicateur Signification
FILE_SHARE_DELETE Les demandes suivantes d’ouverture du flux avec accès de suppression réussissent.
FILE_SHARE_READ Les demandes suivantes d’ouverture du flux avec accès en lecture réussissent.
FILE_SHARE_WRITE Les demandes suivantes d’ouverture du flux avec accès en écriture réussissent.

[in, optional] psdLogFile

Pointeur vers une structure SECURITY_DESCRIPTOR qui fournit des attributs de sécurité pour le flux. Ce paramètre peut être NULL.

[in] fCreateDisposition

L’action à effectuer dépend de l’existence ou non du flux. Ce paramètre doit être défini sur l’une des valeurs suivantes :

Valeur Signification
CREATE_NEW Créez un flux si le flux ne se ferme pas déjà. Échec si le flux existe déjà.
OPEN_EXISTING Ouvrez un flux existant. Échec si le flux n’existe pas déjà.
OPEN_ALWAYS Ouvrez un flux existant. Créez le flux s’il n’existe pas déjà.

[in] fCreateOptions

Ensemble d’indicateurs qui spécifient des options à appliquer lors de la création ou de l’ouverture du flux. Ce paramètre peut être égal à zéro ou à une combinaison compatible des indicateurs suivants :

Indicateur Signification
FILE_NO_INTERMEDIATE_BUFFERING Les enregistrements du flux ne peuvent pas être mis en cache dans les mémoires tampons internes d’un pilote.
FILE_SYNCHRONOUS_IO_ALERT Toutes les opérations sur le flux sont effectuées de manière synchrone. Toute attente de la part de l’appelant est sujette à l’arrêt prématuré des alertes. Si cet indicateur est défini, l’indicateur FILE_SYNCHRONOUS_IO_NONALERT doit être effacé.
FILE_SYNCHRONOUS_IO_NONALERT Toutes les opérations sur le flux sont effectuées de manière synchrone. Les attentes dans le système qui synchronisent la file d’attente d’E/S et l’achèvement ne font pas l’objet d’alertes. Si cet indicateur est défini, l’indicateur FILE_SYNCHRONOUS_IO_ALERT doit être effacé.

[in] fFlagsAndAttributes

Valeur qui spécifie si le flux est ouvert pour un accès normal ou en lecture seule. Ce paramètre doit être défini sur

FILE_ATTRIBUTE_NORMAL ou FILE_ATTRIBUTE_READONLY.

[in] fLogOptionFlag

Indicateur de la relation entre CLFS et le composant qui crée ou ouvre le flux. Ce paramètre doit être défini sur l’une des valeurs suivantes :

Valeur Signification
CLFS_FLAG_NO_FLAGS CLFS et le composant de création ont la relation standard et normale. Les composants en mode noyau utilisent cette valeur, sauf s’ils appartiennent à l’une des trois autres catégories répertoriées dans ce tableau. Si pvContext n’a pas la valeur NULL, CLFS vérifie que cbContext est supérieur à zéro. Sinon, pvContext et cbContext sont ignorés.
CLFS_FLAG_REENTRANT_FILE_SYSTEM Le composant de création est le système de fichiers qui fournit le stockage sous-jacent pour CLFS. CLFS utilise le système de fichiers pour l’allocation des conteneurs, et le système de fichiers utilise des flux CLFS. Dans ce cas, il est possible pour le système de fichiers d’appeler CLFS et pour CLFS d’effectuer des appels dans le système de fichiers sur le même thread ou des threads différents. Si pvContext n’a pas la valeur NULL, CLFS vérifie que cbContext est supérieur à zéro. Sinon, pvContext et cbContext sont ignorés.
CLFS_FLAG_NON_REENTRANT_FILTER Le composant de création est un pilote de filtre de système de fichiers qui envoie toutes ses E/S CLFS à un niveau spécifié sous lui-même sur la pile de filtres. Cette option permet à un pilote de filtre de créer un journal CLFS sans voir ses propres E/S de journalisation. L’appelant transmet l’objet d’appareil cible non NULL dans le paramètre pvContext avec cbContext défini sur la taille appropriée. CLFS utilise la routine IoCreateFileSpecifyDeviceObjectHint pour créer des conteneurs à un niveau ciblé dans la pile de filtres d’E/S spécifiée par l’objet d’appareil.
CLFS_FLAG_REENTRANT_FILTER Le composant de création est un pilote de filtre de système de fichiers qui envoie toutes ses E/S CLFS en haut de la pile de filtres. Le filtre a une relation récursive avec CLFS, car il filtre ses propres E/S de journalisation lorsque CLFS effectue une opération de système de fichiers sur ses conteneurs. Le paramètre pvContext permet aux filtres d’associer un contexte reconnaissable à ses conteneurs CLFS à mesure que les E/S du journal descendent de la pile de filtres. Le paramètre cbContext spécifie la taille du contexte opaque en octets.
CLFS_FLAG_MINIFILTER_LEVEL Le composant de création est un pilote de minifiltre de système de fichiers qui envoie toutes ses E/S CLFS à un niveau spécifié sous lui-même sur la pile de filtres. Cette option permet à un minifiltre de créer un journal CLFS sans voir ses propres E/S de journalisation. L’appelant transmet l’objet de contexte minifilter non NULL dans le paramètre pvContext avec cbContext défini sur la taille appropriée. CLFS utilise la routine IoCreateFileSpecifyDeviceObjectHint pour créer des conteneurs à une altitude (spécifiée dans le contexte de minifiltre) dans la pile de minifiltres du gestionnaire de filtres.

[in, optional] pvContext

Pointeur vers un contexte. La façon dont le contexte est interprété dépend de la valeur passée à fLogOptionsFlag.

[in] cbContext

Taille, en octets, du contexte pointé par pvContext. Si pvContext n’a pas la valeur NULL, ce paramètre doit être supérieur à zéro.

Valeur retournée

ClfsCreateLogFile retourne STATUS_SUCCESS si elle réussit ; sinon, elle retourne l’un des codes d’erreur définis dans Ntstatus.h.

Remarques

Lorsque vous créez un flux CLFS, il est soutenu par un journal CLFS physique sous-jacent. Le journal sous-jacent peut être dédié (ne sauvegarde qu’un seul flux) ou multiplexé (sauvegarde de plusieurs flux). Un journal dédié ne peut pas être converti en journal multiplexé et un journal multiplexé ne peut pas être converti en journal dédié.

Un nom de journal CLFS physique n’inclut pas l’extension .blf.

Pour obtenir une explication des concepts et de la terminologie CLFS, consultez Common Log File System.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Disponible dans Windows Server 2003 R2, Windows Vista et versions ultérieures de Windows.
Plateforme cible Desktop (Expérience utilisateur)
En-tête wdm.h (include Wdm.h)
Bibliothèque Clfs.lib
DLL Clfs.sys
IRQL <= APC_LEVEL

Voir aussi

ClfsCloseAndResetLogFile

ClfsCloseLogFileObject

ClfsDeleteLogByPointer

ClfsDeleteLogFile