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 |