CBFS Connect 2020 Python Edition

Questions / Feedback?

on_offload_write_file Event

Fires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) write operation.

Syntax

class CBFSOffloadWriteFileEventParams(object):
  @property
  def file_name() -> str: ...
  @property
  def position() -> int: ...
  @property
  def copy_length() -> int: ...
  @property
  def transfer_offset() -> int: ...
  @property
  def transfer_length() -> int: ...
  @transfer_length.setter
  def transfer_length(value) -> None: ...
  @property
  def token_type() -> int: ...
  @property
  def token() -> c_void_p: ...
  @property
  def token_length() -> int: ...
  @property
  def result_flags() -> int: ...
  @result_flags.setter
  def result_flags(value) -> None: ...
  @property
  def handle_info() -> int: ...
  @property
  def file_context() -> int: ...
  @file_context.setter
  def file_context(value) -> None: ...
  @property
  def handle_context() -> int: ...
  @handle_context.setter
  def handle_context(value) -> None: ...
  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBFS:
@property
def on_offload_write_file() -> Callable[[CBFSOffloadWriteFileEventParams], None]: ...
@on_offload_write_file.setter
def on_offload_write_file(event_hook: Callable[[CBFSOffloadWriteFileEventParams], None]) -> None: ...

Remarks

This event fires when the OS wants the virtual filesystem to perform an offload write for the file specified by FileName as part of an offloaded data transfer.

To handle this event properly, applications should perform any actions needed to handle the offloaded write based on the specified parameters, and then return the result information. Please refer to the parameter descriptions below for more information.

The Position and CopyLength parameters specify the byte offset and length (respectively) of the data chunk that should be written in the specified file. The CopyLength parameter's value may be smaller than the total amount of data represented by the token (in which case TransferOffset may be greater than 0).

The TransferOffset parameters specifies the byte offset, in the chunk of data represented by the token, from which to begin writing.

The TransferLength parameter must be set to the number of bytes actually written as a result of this request. It may be less than CopyLength.

The TokenType parameter indicates the type of token stored in the Token buffer. A value of STORAGE_OFFLOAD_TOKEN_TYPE_ZERO_DATA (0xFFFF0001) indicates that the token represents data which is all zeros; while any other value (outside of the reserved range 0xFFFF0002 to 0xFFFFFFFF) indicates an application-defined token format.

The Token parameter points to a memory buffer that contains the token returned in response to an earlier offload read request. The token identifies the chunk of data that has been read/prepared for transfer; refer to the on_offload_read_file event for more information. The TokenLength parameter specifies the length, in bytes, of the data in Token.

Please refer to the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultFlags parameter must be set to a combination of zero or more of the flags described in the FSCTL_OFFLOAD_WRITE_OUTPUT structure's documentation.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token. (This parameter may be absent, in which case it will be 0.)

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. (HandleContext may be absent, in which case it will be None.)

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.

 
 
Copyright (c) 2021 Callback Technologies, Inc. - All rights reserved.
CBFS Connect 2020 Python Edition - Version 20.0 [Build 7880]