Fonction ReadLogRecord (clfsw32.h)

Article
02/26/2024

Lance une séquence de lectures à partir d’un numéro de séquence de journal (LSN) spécifié dans l’un des trois modes et retourne le premier des enregistrements de journal spécifiés et un contexte de lecture. Un client peut lire les enregistrements suivants en mode désigné en passant le contexte de lecture à ReadNextLogRecord.

Syntaxe

CLFSUSER_API BOOL ReadLogRecord(
  [in]                PVOID             pvMarshal,
  [in]                PCLFS_LSN         plsnFirst,
  [in]                CLFS_CONTEXT_MODE eContextMode,
  [out]               PVOID             *ppvReadBuffer,
  [out]               PULONG            pcbReadBuffer,
  [out]               PCLFS_RECORD_TYPE peRecordType,
  [out]               PCLFS_LSN         plsnUndoNext,
  [out]               PCLFS_LSN         plsnPrevious,
  [out]               PVOID             *ppvReadContext,
  [in, out, optional] LPOVERLAPPED      pOverlapped
);

Paramètres

[in] pvMarshal

Pointeur vers un contexte de marshaling alloué à l’aide de la fonction CreateLogMarshallingArea .

[in] plsnFirst

Pointeur vers une structure de CLFS_LSN qui spécifie le numéro de séquence de journal (LSN) de l’enregistrement où l’opération de lecture doit démarrer.

Cette valeur doit être un LSN d’un enregistrement valide dans la plage active du journal.

[in] eContextMode

Mode du contexte de lecture retourné dans *ppvReadContext.

Le tableau suivant identifie les trois modes de lecture mutuellement exclusifs.

Valeur	Signification
ClfsContextPrevious	Lit l’enregistrement lié à par plsnPrevious.
ClfsContextUndoNext	Lit la chaîne d’enregistrements liée à par plsnUndoNext.
ClfsContextForward	Lit l’enregistrement avec le LSN qui suit immédiatement le LSN actuel dans le contexte de lecture.

[out] ppvReadBuffer

Pointeur vers une variable qui reçoit un pointeur vers l’enregistrement cible dans le bloc d’E/S du journal.

[out] pcbReadBuffer

Pointeur vers une variable qui reçoit la taille des données retournées dans *ppvReadBuffer, en octets.

[out] peRecordType

Pointeur vers une variable qui reçoit le type de lecture d’enregistrement.

Ce paramètre est l’une des constantes CLFS_RECORD_TYPE.

[out] plsnUndoNext

Pointeur vers une structure de CLFS_LSN qui reçoit le LSN de l’enregistrement suivant dans la chaîne d’annulation des enregistrements.

[out] plsnPrevious

Pointeur vers une structure CLFS_LSN qui reçoit le LSN de l’enregistrement suivant dans la chaîne d’enregistrements précédente.

[out] ppvReadContext

Pointeur vers une variable qui reçoit un pointeur vers un contexte de lecture alloué par le système lorsqu’une lecture réussit.

Si la fonction reporte la fin d’une opération, elle retourne un pointeur de contexte de lecture valide et une erreur status de ERROR_IO_PENDING. Pour toutes les autres erreurs, le pointeur de contexte de lecture est NULL. Pour plus d’informations sur la gestion de l’achèvement différé de la fonction, consultez la section Remarques de cette rubrique.

Après avoir obtenu tous les enregistrements de journal demandés, le client doit passer le contexte de lecture à TerminateReadLog pour libérer la mémoire associée. Si vous ne le faites pas, cela entraîne une fuite de mémoire.

Note Les contextes de lecture CLFS (Common Log File System) ne sont pas thread-safe. Elles ne doivent pas être utilisées par plusieurs threads à la fois, ni passées dans plusieurs lectures asynchrones à la fois.

[in, out, optional] pOverlapped

Pointeur vers une structure CHEVAUCHEMENT, qui est nécessaire pour l’opération asynchrone.

Ce paramètre peut avoir la valeur NULL si l’opération asynchrone n’est pas utilisée.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

La liste suivante identifie les codes d’erreur possibles.

Remarques

Le message d’erreur ERROR_LOG_BLOCK_INCOMPLETE est retourné si la taille du bloc de journal spécifiée par CreateLogMarshallingArea n’est pas suffisamment grande pour contenir un bloc de journal complet.

Si ReadLogRecord est appelé avec une structure pOverlapped valide et que le handle de journal est créé avec l’option qui se chevauche, si un appel à cette fonction échoue avec un code d’erreur de ERROR_IO_PENDING, un pointeur vers un contexte de lecture valide est placé dans la variable vers laquelle pointe le paramètre ppvReadContext .

Si vous tentez d’ouvrir plus de contextes de lecture que les mémoires tampons de nombre spécifiées dans un appel précédent à CreateLogMarshallingArea, ERROR_LOG_BLOCK_EXHAUSTED est retourné.

Pour effectuer une copie d’enregistrement de journal, le client doit d’abord synchroniser son exécution avec l’achèvement différé de l’opération d’E/S qui se chevauche à l’aide de GetOverlappedResult ou de l’une des fonctions d’attente de synchronisation. Pour plus d’informations, consultez Synchronisation et entrées et sorties qui se chevauchent.

Une fois ReadLogRecord terminé de manière asynchrone, l’enregistrement demandé est lu à partir du disque, mais n’est pas résolu en pointeur dans *ppvReadBuffer.

Pour terminer la lecture demandée et obtenir un pointeur valide vers l’enregistrement de journal, le client doit appeler ReadNextLogRecord, qui passe dans le pointeur de contexte de lecture retourné par ReadLogRecord .

Note Les contextes de lecture CLFS (Common Log File System) ne sont pas thread-safe. Ils ne doivent pas être utilisés par plusieurs threads à la fois.

Les contextes de lecture CLFS ne doivent pas être passés dans plusieurs lectures asynchrones à la fois, sinon la fonction échoue avec ERROR_BUSY.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	clfsw32.h
Bibliothèque	Clfsw32.lib
DLL	Clfsw32.dll