Funzione ReadLogRecord (clfsw32.h)

Articolo
05/03/2025

Avvia una sequenza di letture da un numero di sequenza di log specificato (LSN) in una delle tre modalità e restituisce il primo dei record di log specificati e un contesto di lettura. Un client può leggere i record successivi nella modalità designata passando il contesto di lettura a ReadNextLogRecord.

Sintassi

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
);

Parametri

[in] pvMarshal

Puntatore a un contesto di marshalling allocato tramite la funzione CreateLogMarshallingArea.

[in] plsnFirst

Puntatore a una struttura CLFS_LSN che specifica il numero di sequenza del log (LSN) del record in cui deve essere avviata l'operazione di lettura.

Questo valore deve essere un LSN di un record valido nell'intervallo attivo del log.

[in] eContextMode

Modalità per il contesto di lettura restituito in *ppvReadContext.

La tabella seguente identifica le tre modalità di lettura che si escludono a vicenda.

Valore	Significato
clfsContextPrevious	Legge il record collegato da plsnPrevious.
ClfsContextUndoNext	Legge la catena di record collegata a da plsnUndoNext.
ClfsContextForward	Legge il record con l'LSN che segue immediatamente l'LSN corrente nel contesto di lettura.

[out] ppvReadBuffer

Puntatore a una variabile che riceve un puntatore al record di destinazione nel blocco di I/O del log.

[out] pcbReadBuffer

Puntatore a una variabile che riceve le dimensioni dei dati restituiti in *ppvReadBuffer, in byte.

[out] peRecordType

Puntatore a una variabile che riceve il tipo di lettura del record.

Questo parametro è una delle costanti CLFS_RECORD_TYPE.

[out] plsnUndoNext

Puntatore a una struttura CLFS_LSN che riceve l'LSN del record successivo nella catena di record di annullamento.

[out] plsnPrevious

Puntatore a una struttura CLFS_LSN che riceve l'LSN del record successivo nella catena di record precedente.

[out] ppvReadContext

Puntatore a una variabile che riceve un puntatore a un contesto di lettura allocato dal sistema quando una lettura ha esito positivo.

Se la funzione rinvia il completamento di un'operazione, restituisce un puntatore di contesto di lettura valido e uno stato di errore di ERROR_IO_PENDING. In tutti gli altri errori, il puntatore al contesto di lettura viene NULL. Per altre informazioni sulla gestione del completamento posticipato della funzione, vedere la sezione Osservazioni di questo argomento.

Dopo aver ottenuto tutti i record di log richiesti, il client deve passare il contesto di lettura a TerminateReadLog per liberare la memoria associata. In caso contrario, si verifica una perdita di memoria.

Nota contesti di lettura CLFS (Common Log File System) non sono thread-safe. Non devono essere usati da più thread alla volta o passati a più letture asincrone alla volta.

[in, out, optional] pOverlapped

Puntatore a una struttura OVERLAPPED, necessaria per l'operazione asincrona.

Questo parametro può essere NULL se non viene utilizzata l'operazione asincrona.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

L'elenco seguente identifica i possibili codici di errore.

Osservazioni

Il messaggio di errore ERROR_LOG_BLOCK_INCOMPLETE viene restituito se le dimensioni del blocco di log specificate da CreateLogMarshallingArea non sono sufficienti per contenere un blocco di log completo.

Se readLogRecord viene chiamato con una struttura di valida e l'handle di log viene creato con l'opzione sovrapposta, se una chiamata a questa funzione non riesce con un codice di errore di ERROR_IO_PENDING, viene inserito un puntatore a un contesto di lettura valido nella variabile a cui punta il parametro ppvReadContext.

Se si tenta di aprire più contesti di lettura rispetto ai buffer numerici specificati in una chiamata precedente a CreateLogMarshallingArea, viene restituito ERROR_LOG_BLOCK_EXHAUSTED.

Per completare una copia di record di log, il client deve prima sincronizzarne l'esecuzione con il completamento posticipato dell'operazione di I/O sovrapposta usando GetOverlappedResult o una delle funzioni di attesa sincronizzazione. Per altre informazioni, vedere sincronizzazione e input sovrapposto e output.

Dopo che ReadLogRecord viene completato in modo asincrono, il record richiesto viene letto dal disco, ma non viene risolto in un puntatore in *ppvReadBuffer.

Per completare la lettura richiesta e ottenere un puntatore valido al record di log, il client deve chiamare ReadNextLogRecord, che passa il puntatore al contesto di lettura restituito ReadLogRecord.

Nota contesti di lettura CLFS (Common Log File System) non sono thread-safe. Non devono essere usati da più thread alla volta.

I contesti di lettura CLFS non devono essere passati in più letture asincrone alla volta oppure la funzione ha esito negativo con ERROR_BUSY.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [solo app desktop]
server minimo supportato	Windows Server 2003 R2 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	clfsw32.h
libreria	Clfsw32.lib
dll	Clfsw32.dll