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. More...
 
void write (in long long offset, in octet[] data, [retval] out unsigned long written)
 Write data to the medium. More...
 
void formatFAT (in boolean quick)
 Formats the medium as FAT. More...
 
void initializePartitionTable (in PartitionTableType format, in boolean wholeDiskInOneEntry)
 Writes an empty partition table to the disk. More...
 
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. More...
 
void close ()
 Explictly close the medium I/O rather than waiting for garbage collection and the destructor. More...
 

Public Attributes

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

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
offsetThe byte offset into the medium to start reading at.
sizeHow many bytes to try read.
dataArray 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
offsetThe byte offset into the medium to start reading at.
dataArray of data to write.
writtenHow 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
quickQuick format it when set.

◆ initializePartitionTable()

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

Writes an empty partition table to the disk.

Parameters
formatThe partition table format.
wholeDiskInOneEntryWhen 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
formatIdentifier of the storage format to use for output.
variantThe partition table format.
bufferSizeRequested 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.
streamData stream object for reading the target image.
progressProgress 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 ( )

Explictly 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 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.