Fonction ClfsReserveAndAppendLogAligned (wdm.h)

Article
02/27/2024

La routine ClfsReserveAndAppendLogAligned réserve de l’espace dans une zone de marshaling ou ajoute un enregistrement à une zone de marshaling ou effectue les deux de manière atomique. Les données de l’enregistrement sont alignées sur les limites spécifiées.

Syntaxe

CLFSUSER_API NTSTATUS ClfsReserveAndAppendLogAligned(
  [in]            PVOID             pvMarshalContext,
  [in, optional]  PCLFS_WRITE_ENTRY rgWriteEntries,
  [in]            ULONG             cWriteEntries,
  [in]            ULONG             cbEntryAlignment,
  [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 avoir la valeur NULL si cWriteEntries est égal à zéro.

[in] cWriteEntries

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

[in] cbEntryAlignment

Alignement d’octets des entrées de données pointées par rgWriteEntries , car elles sont marshalées dans un enregistrement unique. Une valeur de un spécifie la concaténation simple (voir ClfsReserveAndAppendLog). Une valeur supérieure à une peut entraîner la place de zéros entre les entrées de l’enregistrement. La valeur de ce paramètre doit être supérieure à zéro.

[in, optional] plsnUndoNext

Pointeur vers une structure CLFS_LSN qui fournit le 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 pointé 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 à la taille, en octets, d’un enregistrement qui doit disposer d’une réserve d’espace. Au retour, chaque élément de tableau reçoit la 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 avoir la valeur NULL si cReserveRecords est égal à zéro et doit avoir la valeur NULL si l’indicateur de CLFS_FLAG_USE_RESERVATION de fFlags est défini.

[in] fFlags

Ce paramètre peut être 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 garantit pas 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. Le nombre d’enregistrements réservés dans la zone de marshaling est réduit d’un seul. 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 CLFS_LSN qui reçoit le LSN de l’enregistrement ajouté. Ce paramètre peut avoir la valeur NULL si cWriteEntries est égal à zéro.

Valeur retournée

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

Remarques

La routine ClfsReserveAndAppendLogAligned 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’a pas la valeur NULL. plsn n’a pas la valeur 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’a pas la valeur NULL. plsn n’a pas la valeur 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’a pas la valeur NULL. plsn n’a pas la valeur 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.

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 (inclure Wdm.h)
Bibliothèque	Clfs.lib
DLL	Clfs.sys
IRQL	<= APC_LEVEL

Voir aussi

CLFS_LSN

CLFS_WRITE_ENTRY

ClfsCreateMarshallingArea

ClfsReserveAndAppendLog