VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
IMediumIO Interface Reference

The IMediumIO interface is used to access and modify the content of a medium. More...

Inheritance diagram for IMediumIO:

## Public Member Functions
void | read (in long long offset, in unsigned long size, [retval] out octet[] data)
| Read data from the medium.
void | write (in long long offset, in octet[] data, [retval] out unsigned long written)
| Write data to the medium.
void | formatFAT (in boolean quick)
| Formats the medium as FAT.
void | initializePartitionTable (in PartitionTableType format, in boolean wholeDiskInOneEntry)
| Writes an empty partition table to the disk.
void | convertToStream (in wstring format, in MediumVariant[] variant, in unsigned long bufferSize, out IDataStream stream, [retval] out IProgress progress)
| Converts the currently opened image into a stream of the specified image type/variant.
void | close ()
| Explicitly close the medium I/O rather than waiting for garbage collection and the destructor.

## Public Attributes
readonly attribute IMedium | medium
| The open medium.
readonly attribute boolean | writable
| Whether the medium can be written to.
readonly attribute IVFSExplorer | explorer
| Returns the virtual file system explorer for the medium.

## Detailed Description

The IMediumIO interface is used to access and modify the content of a medium.

It is returned by IMedium::openForIO.

Interface ID:
  `{E4B301A9-5F86-4D65-AD1B-87CA284FB1C8}`

## Member Function Documentation

## ◆ read()

void IMediumIO::read | ( | in long long | offset,
|  | in unsigned long | size,
|  | [retval] out octet[] | data
| ) |  |

Read data from the medium.

Parameters

  offset | The byte offset into the medium to start reading at.
  size | How many bytes to try read.
  data | Array of data read. This may be shorter than the specified size.

## ◆ write()

void IMediumIO::write | ( | in long long | offset,
|  | in octet[] | data,
|  | [retval] out unsigned long | written
| ) |  |

Write data to the medium.

Parameters

  offset | The byte offset into the medium to start reading at.
  data | Array of data to write.
  written | How many bytes were actually written.

## ◆ formatFAT()

void IMediumIO::formatFAT | ( | in boolean | quick | ) |

Formats the medium as FAT.

Generally only useful for floppy images as no partition table will be created.

Parameters

  quick | Quick format it when set.

## ◆ initializePartitionTable()

void IMediumIO::initializePartitionTable | ( | in PartitionTableType | format,
|  | in boolean | wholeDiskInOneEntry
| ) |  |

Writes an empty partition table to the disk.

Parameters

  format | The partition table format.
  wholeDiskInOneEntry | When `true` a partition table entry for the whole disk is created. Otherwise the partition table is empty.

## ◆ convertToStream()

void IMediumIO::convertToStream | ( | in wstring | format,
|  | in MediumVariant[] | variant,
|  | in unsigned long | bufferSize,
|  | out IDataStream | stream,
|  | [retval] out IProgress | progress
| ) |  |

Converts the currently opened image into a stream of the specified image type/variant.

It is sufficient to open the image in read-only mode. Only few types and variants are supported due to the inherent restrictions of the output style.

Parameters

  format | Identifier of the storage format to use for output.
  variant | The partition table format.
  bufferSize | Requested buffer size (in bytes) for efficient conversion. Sizes which are too small or too large are silently truncated to suitable values. Tens to hundreds of Megabytes are a good choice.
  stream | Data stream object for reading the target image.
  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_NOT_SUPPORTED | The requested format/variant combination cannot handle stream output.
  VBOX_E_FILE_ERROR | An error occurred during the conversion.

## ◆ close()

void IMediumIO::close | ( |  | ) |

Explicitly close the medium I/O rather than waiting for garbage collection and the destructor.

This will wait for any pending reads and writes to complete and then close down the I/O access without regard for open explorer instances or anything like that.

## Member Data Documentation

## ◆ medium

readonly attribute IMedium IMediumIO::medium

The open medium.

## ◆ writable

readonly attribute boolean IMediumIO::writable

Whether the medium can be written to.

(It can always be read from.)

## ◆ explorer

readonly attribute IVFSExplorer IMediumIO::explorer

Returns the virtual file system explorer for the medium.

This will attempt to recognize the format of the medium content and present it as a virtual directory structure to the API user.

A FAT floppy image will be represented will a single root subdir 'fat12' that gives access to the file system content.

A ISO-9660 image will have one subdir in the root for each format present in the image, so the API user can select which data view to access (iso9660, rockridge, joliet, udf, hfs, ...).

A partitioned harddisk image will have subdirs for each partition. The filesystem content of each partition can be accessed thru the subdirs if we have a file system interpreter for it. There will also be raw files for each subdirectory, to provide a simple way of accessing raw partition data from an API client.

Please note that the explorer may show inconsistent information if the API user modifies the raw image content after it was opened.