ClfsReserveAndAppendLog, fonction (wdm.h)

La routine ClfsReserveAndAppendLog réserve de l’espace dans une zone de marshaling ou ajoute un enregistrement à une zone de marshaling ou effectue les deux atomiquement.

Syntaxe

CLFSUSER_API NTSTATUS ClfsReserveAndAppendLog(
  [in]            PVOID             pvMarshalContext,
  [in, optional]  PCLFS_WRITE_ENTRY rgWriteEntries,
  [in]            ULONG             cWriteEntries,
  [in, optional]  PCLFS_LSN         plsnUndoNext,
  [in, optional]  PCLFS_LSN         plsnPrevious,
  [in]            ULONG             cReserveRecords,
  [in, out]       PLONGLONG         rgcbReservation,
  [in]            ULONG             fFlags,
  [out, optional] PCLFS_LSN         plsn
);

Paramètres

[in] pvMarshalContext

Pointeur vers un contexte opaque qui représente une zone de marshaling associée à un flux CLFS. L’appelant a précédemment obtenu ce pointeur en appelant ClfsCreateMarshallingArea.

[in, optional] rgWriteEntries

Pointeur vers un tableau de structures CLFS_WRITE_ENTRY , chacune contenant un pointeur vers une mémoire tampon de données qui fera partie de l’enregistrement ajouté au journal. Ce paramètre peut être NULL si cWriteEntries est égal à zéro.

[in] cWriteEntries

Nombre d’éléments dans le tableau pointé par rgWriteEntries. Ce paramètre doit être égal à zéro si rgWriteEntries a la valeur NULL.

[in, optional] plsnUndoNext

Pointeur vers une structure de CLFS_LSN qui fournit le numéro LSN undo-next de l’enregistrement à ajouter.

[in, optional] plsnPrevious

Pointeur vers une structure CLFS_LSN qui fournit le LSN précédent de l’enregistrement à ajouter.

[in] cReserveRecords

Nombre d’éléments dans le tableau vers rgcbReservation. Ce paramètre doit être égal à zéro si rgcbReservation a la valeur NULL ou si l’indicateur CLFS_FLAG_USE_RESERVATION de fFlags est défini.

[in, out] rgcbReservation

Pointeur vers un tableau de variables de type LONGLONG. L’appelant définit chaque élément du tableau sur la taille, en octets, d’un enregistrement qui doit avoir un espace réservé. Au retour, chaque élément de tableau reçoit cette taille réelle de l’espace réservé à l’enregistrement. Cela inclut l’espace requis pour les en-têtes et l’alignement. Si la valeur de réservation est négative, un enregistrement réservé qui correspond le plus à la valeur absolue de la valeur négative fournie est libéré. Ce paramètre peut être NULL si cReserveRecords est égal à zéro et doit être NULL si l’indicateur CLFS_FLAG_USE_RESERVATION de fFlags est défini.

[in] fFlags

Ce paramètre peut être égal à zéro ou à n’importe quelle combinaison des indicateurs suivants.

Indicateur	Signification
CLFS_FLAG_FORCE_APPEND	Une fois l’enregistrement actif ajouté à un bloc d’E/S du journal, le bloc est mis en file d’attente, dans la séquence LSN, vers un stockage stable. Cet indicateur ne fournit aucune garantie que l’enregistrement est forcé à un stockage stable (voir CLFS_FLAG_FORCE_FLUSH).
CLFS_FLAG_FORCE_FLUSH	Une fois l’enregistrement actif ajouté à un bloc d’E/S du journal, le bloc est forcé à un stockage stable.
CLFS_FLAG_USE_RESERVATION	L’enregistrement actif est placé dans un espace réservé dans un bloc d’E/S de journal dans la zone de marshaling. Le nombre d’enregistrements réservés dans la zone de marshaling est réduit d’un. Si cet indicateur est défini, cReserveRecords doit être égal à zéro et rgcbReservation doit avoir la valeur NULL.

[out, optional] plsn

Pointeur vers une structure de CLFS_LSN qui reçoit le numéro LSN de l’enregistrement ajouté. Ce paramètre peut être NULL si cWriteEntries est égal à zéro.

Valeur retournée

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

Remarques

La routine ClfsReserveAndAppendLog modifie son comportement fondamental en fonction de la présence de paramètres facultatifs et de l’état de l’indicateur CLFS_USE_RESERVATION. Le tableau suivant récapitule les scénarios courants.

Valeurs de paramètre et d’indicateur	Actions effectuées
cWriteEntries = 0. rgWriteEntries = NULL. plsn = NULL.	Réserve de l’espace pour un ensemble d’enregistrements, mais n’ajoute pas les enregistrements à la zone de marshaling. Le paramètre rgcbReservation donne la taille de la partie de données de chaque enregistrement qui a besoin d’espace réservé.
cWriteEntries > 0. rgWriteEntries n’est pas NULL. plsn n’est pas NULL. cReserveRecords = 0. rgcbReservation a la valeur NULL. CLFS_USE_RESERVATION est défini.	Ajoute un enregistrement à la zone de marshaling à l’aide de l’espace qui a déjà été réservé. Réduit d’un seul le nombre d’espaces d’enregistrement réservés.
cWriteEntries > 0. rgWriteEntries n’est pas NULL. plsn n’est pas NULL. cReserveRecords = 0. rgcbReservation a la valeur NULL. CLFS_USE_RESERVATION est effacé.	Ajoute un enregistrement à la zone de marshaling en réservant un nouvel espace. Laisse le nombre d’espaces d’enregistrement réservés inchangé.
cWriteEntries > 0. rgWriteEntries n’est pas NULL. plsn n’est pas NULL. cReserveRecords> 0. rgcbReservation n’est pas NULL. CLFS_USE_RESERVATION’indicateur est effacé.	Ajoute un enregistrement à la zone de marshaling en réservant un nouvel espace. Réserve également de l’espace pour un ensemble d’enregistrements qui ne sont pas ajoutés pour le moment. Le paramètre rgcbReservation donne la taille de chaque enregistrement qui a besoin d’espace réservé. Augmente le nombre d’espaces d’enregistrement réservés par la valeur de cReserveRecords.

 

Appeler ClfsReserveAndAppendLog équivaut à appeler ClfsReserveAndAppendLogA aligné avec le paramètre cbEntryAlignment défini sur un.

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

CLFS_LSN

CLFS_WRITE_ENTRY

ClfsCreateMarshallingArea

ClfsReserveAndAppendLogAligned