CBFS Connect 2020 Python Edition

Questions / Feedback?

on_ioctl Event

Fires when the disk behind the virtual filesystem receives a non-standard request (I/O control code).


class CBFSIoctlEventParams(object):
  def file_name() -> str: ...
  def code() -> int: ...
  def input_buffer() -> c_void_p: ...
  def input_buffer_length() -> int: ...
  def output_buffer() -> c_void_p: ...
  def output_buffer_length() -> int: ...
  def bytes_returned() -> int: ...
  def bytes_returned(value) -> None: ...
  def result_code() -> int: ...
  def result_code(value) -> None: ...

# In class CBFS:
def on_ioctl() -> Callable[[CBFSIoctlEventParams], None]: ...
def on_ioctl(event_hook: Callable[[CBFSIoctlEventParams], None]) -> None: ...


An IOCTL is a system call for device-specific I/O operations, as well as other operations that cannot be expressed through regular API calls. Such calls carry a control code, and the effects of the call depend entirely on how a device driver handles that control code. A control code is composed of, among other things, a function code and flags that describe how data is passed.

This event is optional. Applications that choose to implement it are free to do so in any manner they desire based on the control code received.

The FileName parameter identifies the file or directory targeted by the request. It may be empty if the request is targeting the virtual drive itself.

The Code parameter reflects the control code received. If the specified control code is unrecognized or unsupported, return the ERROR_INVALID_FUNCTION error code via ResultCode.

The InputBuffer parameter points to the memory buffer containing the data required to perform the operation. The format of this data depends on the specified Code; it may be empty. The InputBufferLength parameter specifies the length, in bytes, of InputBuffer.

The OutputBuffer parameter points to the memory buffer that receives the data returned by the operation. The format of this data depends on the specified Code; it may be empty. The OutputBufferLength parameter specifies the capacity, in bytes, of OutputBuffer; applications should set the BytesReturned parameter to the number of bytes written to OutputBuffer.

If the application needs to return more than OutputBufferLength bytes of data, it should do one of the following things:

  1. If OutputBuffer is too small to hold all of the data, but can hold some entries, then the application should write as much data to it as possible, set BytesReturned appropriately, and return the ERROR_MORE_DATA error code via ResultCode.
  2. If OutputBuffer is too small to hold any data, then the application should set BytesReturned to 0, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

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

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]