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 ()
	Explictly 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

(

)

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.