Funzione ClfsReserveAndAppendLog (wdm.h)
Il ClfsReserveAndAppendLog routine riserva spazio in un'area di marshalling o aggiunge un record a un'area di marshalling o esegue entrambe le operazioni in modo atomico.
Sintassi
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
);
Parametri
[in] pvMarshalContext
Puntatore a un contesto opaco che rappresenta un'area di marshalling associata a un flusso CLFS. Il chiamante ottenuto in precedenza questo puntatore chiamando ClfsCreateMarshallingArea.
[in, optional] rgWriteEntries
Puntatore a una matrice di strutture CLFS_WRITE_ENTRY, ognuna delle quali contiene un puntatore a un buffer di dati che diventerà parte del record aggiunto al log. Questo parametro può essere null se cWriteEntries è zero.
[in] cWriteEntries
Numero di elementi nella matrice a cui punta rgWriteEntries. Questo parametro deve essere zero se rgWriteEntries è NULL.
[in, optional] plsnUndoNext
Puntatore a una struttura CLFS_LSN che fornisce l'LSN di annullamento successivo del record da accodare.
[in, optional] plsnPrevious
Puntatore a una struttura CLFS_LSN che fornisce l'LSN precedente del record da aggiungere.
[in] cReserveRecords
Numero di elementi nella matrice a cui punta rgcbReservation. Questo parametro deve essere zero se rgcbReservation è NULL o è impostato il flag CLFS_FLAG_USE_RESERVATION di fFlags.
[in, out] rgcbReservation
Puntatore a una matrice di variabili tipate LONGLONG. Il chiamante imposta ogni elemento della matrice sulle dimensioni, in byte, di un record che deve disporre di spazio riservato. In caso di restituzione, ogni elemento della matrice riceve tale dimensione effettiva dello spazio riservato per il record. Questo include lo spazio necessario per le intestazioni e l'allineamento. Se il valore della prenotazione è negativo, verrà liberato un record riservato che corrisponde quasi al valore assoluto del valore negativo specificato. Questo parametro può essere NULL se cReserveRecords è zero e deve essere NULL se è impostato il flag CLFS_FLAG_USE_RESERVATION di fFlags.
[in] fFlags
Questo parametro può essere zero o qualsiasi combinazione dei flag seguenti.
| Bandiera | Significato |
|---|---|
| CLFS_FLAG_FORCE_APPEND | Dopo l'aggiunta del record corrente a un blocco di I/O del log, il blocco viene accodato, nella sequenza LSN, all'archiviazione stabile. Questo flag non garantisce che il record venga forzato a una risorsa di archiviazione stabile (vedere CLFS_FLAG_FORCE_FLUSH). |
| CLFS_FLAG_FORCE_FLUSH | Dopo l'aggiunta del record corrente a un blocco di I/O del log, il blocco viene forzato a una risorsa di archiviazione stabile. |
| CLFS_FLAG_USE_RESERVATION | Il record corrente viene inserito nello spazio riservato in un blocco di I/O del log all'interno dell'area di marshalling. Il numero di record riservati nell'area di marshalling viene ridotto di uno. Se questo flag è impostato, cReserveRecords deve essere zero e rgcbReservation deve essere NULL. |
[out, optional] plsn
Puntatore a una struttura CLFS_LSN che riceve l'LSN del record aggiunto. Questo parametro può essere null se cWriteEntries è zero.
Valore restituito
clfsReserveAndAppendLog restituisce STATUS_SUCCESS se ha esito positivo; in caso contrario, restituisce uno dei codici di errore definiti in Ntstatus.h.
Osservazioni
La routine ClfsReserveAndAppendLog modifica il comportamento fondamentale in base alla presenza di parametri facoltativi e allo stato del flag CLFS_USE_RESERVATION. La tabella seguente riepiloga gli scenari comuni.
| Valori dei parametri e dei flag | Azioni eseguite |
|---|---|
|
cWriteEntries = 0.
rgWriteEntries = NULL. plsn = NULL. |
Riserva spazio per un set di record, ma non accoda i record all'area di marshalling. Il parametro rgcbReservation fornisce le dimensioni della parte di dati di ogni record che richiede spazio riservato. |
|
cWriteEntries > 0.
rgWriteEntries non è NULL. plsn non è NULL. cReserveRecords = 0. rgcbReservation è NULL. CLFS_USE_RESERVATION è impostato. |
Aggiunge un record all'area di marshalling utilizzando lo spazio già riservato. Riduce il numero di spazi di record riservati di uno. |
|
cWriteEntries > 0.
rgWriteEntries non è NULL. plsn non è NULL. cReserveRecords = 0. rgcbReservation è NULL. CLFS_USE_RESERVATION è deselezionata. |
Aggiunge un record all'area di marshalling riservando nuovo spazio. Lascia invariato il numero di spazi di record riservati. |
|
cWriteEntries > 0.
rgWriteEntries non è NULL. plsn non è NULL. cReserveRecords> 0. rgcbReservation non è NULL. CLFS_USE_RESERVATION flag è deselezionato. |
Aggiunge un record all'area di marshalling riservando nuovo spazio. Riserva inoltre spazio per un set di record che non vengono accodati in questo momento. Il parametro rgcbReservation fornisce le dimensioni di ogni record che richiede spazio riservato. Aumenta il numero di spazi di record riservati in base al valore di cReserveRecords. |
La chiamata a ClfsReserveAndAppendLog equivale a chiamare clfsReserveAndAppendLogAligned con il parametro cbEntryAlignment impostato su uno.
Per una spiegazione dei concetti e della terminologia di CLFS, vedere Common Log File System.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Disponibile in Windows Server 2003 R2, Windows Vista e versioni successive di Windows. |
| piattaforma di destinazione | Desktop |
| intestazione | wdm.h (include Wdm.h) |
| libreria | Clfs.lib |
| dll | Clfs.sys |
| IRQL | <= APC_LEVEL |