BeforeWriteFile Event

Fires before data is written to a file.

Syntax

public class DefaultCbfilterEventListener implements CbfilterEventListener {
  ...
  public void beforeWriteFile(CbfilterBeforeWriteFileEvent e) {}
  ...
}

public class CbfilterBeforeWriteFileEvent {
  public String fileName;
  public long position;
  public ByteBuffer buffer;
  public int bufferLength;
  public int bytesToWrite;
  public int direction;
  public long fileContext;
  public long handleContext;
  public boolean processRequest;
  public int resultCode;
}

Remarks

This event fires before data is written to the file specified by FileName.

Applications may use this event to modify the request's parameters and/or data. Applications that choose to modify the request's data 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 BytesToWrite parameter's value afterwards so that it correctly reflects the amount of data in Buffer.

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. Write the data pointed to by Buffer to the desired location (after preprocessing it, if necessary).
2. Update the BytesToWrite parameter's value afterwards so that it correctly reflects the amount of data that was written.
3. 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_WRITE flag.

The Position parameter specifies the byte offset in the file at which writing should start. A value of -1 means "append to the end of the file".

The Buffer parameter points to a memory buffer that contains the data to write to 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 BytesToWrite parameter's initial value reflects how many bytes should be written to the file (i.e., how many bytes the requestor expects will be written). This parameter's value may be changed (for either of the reasons discussed above), but it must not exceed BufferLength.

However, please note that writing more or less data than requested is not expected behavior, and will likely cause the requestor to misbehave. Applications that change BytesToWrite, for any reason, should use the AfterWriteFile 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 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.