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 |