BeforeReadFile Event

Fires before data is read from a file.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeReadFile(CBFilterBeforeReadFileEventParams *e);
typedef struct {
const char *FileName;
int64 *pPosition;
void *Buffer;
int BufferLength;
int BytesToRead;
int Direction;
void *FileContext;
void *HandleContext;
int ProcessRequest;
int ResultCode; int reserved; } CBFilterBeforeReadFileEventParams; Unicode (Windows) virtual INT FireBeforeReadFile(CBFilterBeforeReadFileEventParams *e);
typedef struct {
LPCWSTR FileName;
LONG64 *pPosition;
LPVOID Buffer;
INT BufferLength;
INT BytesToRead;
INT Direction;
LPVOID FileContext;
LPVOID HandleContext;
BOOL ProcessRequest;
INT ResultCode; INT reserved; } CBFilterBeforeReadFileEventParams;
#define EID_CBFILTER_BEFOREREADFILE 42

virtual INT CBFSFILTER_CALL FireBeforeReadFile(LPWSTR &lpszFileName, LONG64 &lPosition, LPVOID &lpBuffer, INT &iBufferLength, INT &iBytesToRead, INT &iDirection, LPVOID &lpFileContext, LPVOID &lpHandleContext, BOOL &bProcessRequest, INT &iResultCode);

Remarks

This event fires before data is read from the file specified by FileName.

Applications that intend to modify a file's data after it is read may use this event to modify the request's parameters, if necessary (e.g., to ensure that the correct data is read from the file and made available for postprocessing during the AfterReadFile event). Applications may also use this event to block the request entirely by returning an appropriate error code (e.g., ACCESS_DENIED) via ResultCode.

Alternatively, applications may use this event to handle the underlying request, in which case they must:

  1. Enable the ModifiableReadWriteBuffers configuration setting (before this event fires, that is).
  2. Copy no more than BufferLength bytes into Buffer.
  3. Update the BytesToRead parameter's value afterwards so that it correctly reflects the amount of data in Buffer.
  4. Set ProcessRequest to false to indicate that the request has been handled and should not continue onwards.

Applications only need to handle this event if they've added a standard filter rule that includes the FS_CE_BEFORE_READ flag.

The Position parameter specifies the byte offset in the file at which reading should start.

The Buffer parameter points to a memory buffer that receives the data read from the file. The BufferLength parameter reflects the capacity of Buffer, in bytes. Please refer to the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The BytesToRead parameter's initial value reflects how many bytes should be read from the file (i.e., how many bytes the requestor expects will be read). This parameter's value may be changed (for either of the reasons discussed above), but it must not exceed BufferLength.

However, please note that reading more or less data than requested is not expected behavior, and will likely cause the requestor to misbehave. Applications that change BytesToRead, for any reason, should use the AfterReadFile event to "cover up" such behavior; please refer to its documentation for more information.

The Direction parameter indicates the request direction; please refer to the Cached and Non-Cached Requests topic for more information. Possible values are:

FS_REQUEST_DIR_USER_NONCACHED0Operations performed in the 'user mode application <--> filesystem' direction.
FS_REQUEST_DIR_USER_CACHED1Operations performed in the 'user mode application <--> system cache' direction.
FS_REQUEST_DIR_SYSTEM_NONCACHED2Operations performed in the 'system cache <--> filesystem' direction.
FS_REQUEST_DIR_SYSTEM_CACHED3Operations performed in the 'system component <--> system cache' direction.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be NULL.)

The ProcessRequest parameter controls whether the request is sent onwards for further processing by subsequent filter drivers and the filesystem; it is true by default.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

Copyright (c) 2022 Callback Technologies, Inc. - All rights reserved.
CBFS Filter 2020 C++ Edition - Version 20.0 [Build 8317]