Fonction ClfsReserveAndAppendLogAligned (wdm.h)
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 |