CBFS Filter 2020 Node.js Edition

Questions / Feedback?

BeforeReadFile Event

Fires before data is read from a file.

Syntax

cbfilter.on('BeforeReadFile', [callback])

Callback

The 'callback' is called when the 'BeforeReadFile' event is emited.

function(e){ }

The argument 'e' has the following properties:

e.fileName
e.position
e.buffer
e.bufferLength
e.bytesToRead
e.direction
e.fileContext
e.handleContext
e.processRequest
e.resultCode

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 0.)

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 Node.js Edition - Version 20.0 [Build 8164]