Abstract parent interface for files handled by VirtualBox. More...

Inheritance diagram for IFile:

Public Member Functions
void	close ()
	Closes this file.

void	queryInfo ([retval] out IFsObjInfo objInfo)
	Queries information about this file.

void	querySize ([retval] out long long size)
	Queries the current file size.

void	read (in unsigned long toRead, in unsigned long timeoutMS, [retval] out octet[] data)
	Reads data from this file.

void	readAt (in long long offset, in unsigned long toRead, in unsigned long timeoutMS, [retval] out octet[] data)
	Reads data from an offset of this file.

void	seek (in long long offset, in FileSeekOrigin whence, [retval] out long long newOffset)
	Changes the current file position of this file.

void	setACL (in wstring acl, in unsigned long mode)
	Sets the ACL of this file.

void	setSize (in long long size)
	Changes the file size.

void	write (in octet[] data, in unsigned long timeoutMS, [retval] out unsigned long written)
	Writes bytes to this file.

void	writeAt (in long long offset, in octet[] data, in unsigned long timeoutMS, [retval] out unsigned long written)
	Writes bytes at a certain offset to this file.

Public Attributes
readonly attribute IEventSource	eventSource
	Event source for file events.

readonly attribute unsigned long	id
	The ID VirtualBox internally assigned to the open file.

readonly attribute long long	initialSize
	The initial size in bytes when opened.

readonly attribute long long	offset
	The current file position.

readonly attribute FileStatus	status
	Current file status.

readonly attribute wstring	filename
	Full path of the actual file name of this file.

readonly attribute unsigned long	creationMode
	The UNIX-style creation mode specified when opening the file.

readonly attribute FileOpenAction	openAction
	The opening action specified when opening the file.

readonly attribute FileAccessMode	accessMode
	The file access mode.

Detailed Description

Abstract parent interface for files handled by VirtualBox.

Interface ID:: {59A235AC-2F1A-4D6C-81FC-E3FA843F49AE}

Member Function Documentation

◆ close()

void IFile::close ( )

Closes this file.

After closing operations like reading data, writing data or querying information will not be possible anymore.

◆ queryInfo()

void IFile::queryInfo ( [retval] out IFsObjInfo objInfo )

Queries information about this file.

Parameters

objInfo Object information of this file. Also see IFsObjInfo.

◆ querySize()

void IFile::querySize ( [retval] out long long size )

Queries the current file size.

Parameters

size	Queried file size.

◆ read()

void IFile::read	(	in unsigned long	toRead,
		in unsigned long	timeoutMS,
		[retval] out octet[]	data
	)

Reads data from this file.

The file current position (IFile::offset) is updated on success.

Parameters

toRead	Number of bytes to read.
timeoutMS	Timeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
data	Array of data read.

◆ readAt()

void IFile::readAt	(	in long long	offset,
		in unsigned long	toRead,
		in unsigned long	timeoutMS,
		[retval] out octet[]	data
	)

Reads data from an offset of this file.

The file current position (IFile::offset) is updated on success.

Parameters

offset	Offset in bytes to start reading.
toRead	Number of bytes to read.
timeoutMS	Timeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
data	Array of data read.

◆ seek()

void IFile::seek	(	in long long	offset,
		in FileSeekOrigin	whence,
		[retval] out long long	newOffset
	)

Changes the current file position of this file.

The file current position always applies to the IFile::read method. Same for the IFile::write method it except when the IFile::accessMode is FileAccessMode_AppendOnly or FileAccessMode_AppendRead.

Parameters

offset	Offset to seek relative to the position specified by whence.
whence	One of the FileSeekOrigin seek starting points.
newOffset	The new file offset after the seek operation.

◆ setACL()

void IFile::setACL	(	in wstring	acl,
		in unsigned long	mode
	)

Sets the ACL of this file.

Parameters

acl	The ACL specification string. To-be-defined.
mode	UNIX-style mode mask to use if acl is empty. As mention in IGuestSession::directoryCreate this is realized on a best effort basis and the exact behavior depends on the Guest OS.

Expected result codes:

E_NOTIMPL

The method is not implemented yet.

◆ setSize()

void IFile::setSize ( in long long size )

Changes the file size.

Parameters

size	The new file size.

◆ write()

void IFile::write	(	in octet[]	data,
		in unsigned long	timeoutMS,
		[retval] out unsigned long	written
	)

Writes bytes to this file.

The file current position (IFile::offset) is updated on success.

Parameters

data	Array of bytes to write. The size of the array also specifies how much to write.
timeoutMS	Timeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
written	How many bytes were written.

◆ writeAt()

void IFile::writeAt	(	in long long	offset,
		in octet[]	data,
		in unsigned long	timeoutMS,
		[retval] out unsigned long	written
	)

Writes bytes at a certain offset to this file.

The file current position (IFile::offset) is updated on success.

Parameters

offset	Offset in bytes to start writing. If the file was opened with the IFile::accessMode set to FileAccessMode_AppendOnly or FileAccessMode_AppendRead, the offset is ignored and the write always goes to the end of the file.
data	Array of bytes to write. The size of the array also specifies how much to write.
timeoutMS	Timeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
written	How many bytes were written.

Member Data Documentation

◆ eventSource

readonly attribute IEventSource IFile::eventSource

Event source for file events.

◆ id

readonly attribute unsigned long IFile::id

The ID VirtualBox internally assigned to the open file.

◆ initialSize

readonly attribute long long IFile::initialSize

The initial size in bytes when opened.

◆ offset

readonly attribute long long IFile::offset

The current file position.

The file current position always applies to the IFile::read method, which updates it upon return. Same goes for the IFile::write method except when IFile::accessMode is FileAccessMode_AppendOnly or FileAccessMode_AppendRead, where it will always write to the end of the file and will leave this attribute unchanged.

The IFile::seek is used to change this attribute without transfering any file data like read and write does.

Note: This will not always be correct with older Guest Additions (version 5.2.30 and earlier, as well as versions 6.0.0 thru 6.0.8) after a calling IFile::readAt or IFile::writeAt, or after calling IFile::write on a file in append mode. The correct file offset can be obtained using IFile::seek.

◆ status

readonly attribute FileStatus IFile::status

Current file status.

◆ filename

readonly attribute wstring IFile::filename

Full path of the actual file name of this file.

◆ creationMode

readonly attribute unsigned long IFile::creationMode

The UNIX-style creation mode specified when opening the file.

◆ openAction

readonly attribute FileOpenAction IFile::openAction

The opening action specified when opening the file.

◆ accessMode

readonly attribute FileAccessMode IFile::accessMode

The file access mode.

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ close()

◆ queryInfo()

◆ querySize()

◆ read()

◆ readAt()

◆ seek()

◆ setACL()

◆ setSize()

◆ write()

◆ writeAt()

Member Data Documentation

◆ eventSource

◆ id

◆ initialSize

◆ offset

◆ status

◆ filename

◆ creationMode

◆ openAction

◆ accessMode