BeforeReadFile Event

Fires before data is read from a file.

Syntax

• C#
• VB.NET

public event OnBeforeReadFileHandler OnBeforeReadFile;

public delegate void OnBeforeReadFileHandler(object sender, CbfilterBeforeReadFileEventArgs e);

public class CbfilterBeforeReadFileEventArgs : EventArgs {
  public string FileName { get; }
  public long Position { get; set; }
  public IntPtr Buffer { get; }
  public int BufferLength { get; }
  public int BytesToRead { get; set; }
  public int Direction { get; }
  public IntPtr FileContext { get; set; }
  public IntPtr HandleContext { get; set; }
  public bool ProcessRequest { get; set; }
  public int ResultCode { get; set; }
}

Public Event OnBeforeReadFile As OnBeforeReadFileHandler

Public Delegate Sub OnBeforeReadFileHandler(sender As Object, e As CbfilterBeforeReadFileEventArgs)

Public Class CbfilterBeforeReadFileEventArgs Inherits EventArgs
  Public ReadOnly Property FileName As String
  Public Property Position As Long
  Public ReadOnly Property Buffer As IntPtr
  Public ReadOnly Property BufferLength As Integer
  Public Property BytesToRead As Integer
  Public ReadOnly Property Direction As Integer
  Public Property FileContext As IntPtr
  Public Property HandleContext As IntPtr
  Public Property ProcessRequest As Boolean
  Public Property ResultCode As Integer
End Class

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:

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 IntPtr.Zero.)

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.