VirtualBox Main API
Public Member Functions | Public Attributes | List of all members
IFile Interface Reference

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

Inheritance diagram for IFile:
IGuestFile

Public Member Functions

void close ()
 Closes this file. More...
 
void queryInfo ([retval] out IFsObjInfo objInfo)
 Queries information about this file. More...
 
void querySize ([retval] out long long size)
 Queries the current file size. More...
 
void read (in unsigned long toRead, in unsigned long timeoutMS, [retval] out octet[] data)
 Reads data from this file. More...
 
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. More...
 
void seek (in long long offset, in FileSeekOrigin whence, [retval] out long long newOffset)
 Changes the current file position of this file. More...
 
void setACL (in wstring acl, in unsigned long mode)
 Sets the ACL of this file. More...
 
void setSize (in long long size)
 Changes the file size. More...
 
void write (in octet[] data, in unsigned long timeoutMS, [retval] out unsigned long written)
 Writes bytes to this file. More...
 
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. More...
 

Public Attributes

readonly attribute IEventSource eventSource
 Event source for file events. More...
 
readonly attribute unsigned long id
 The ID VirtualBox internally assigned to the open file. More...
 
readonly attribute long long initialSize
 The initial size in bytes when opened. More...
 
readonly attribute long long offset
 The current file position. More...
 
readonly attribute FileStatus status
 Current file status. More...
 
readonly attribute wstring fileName
 Full path of the actual file name of this file. More...
 
readonly attribute unsigned long creationMode
 The UNIX-style creation mode specified when opening the file. More...
 
readonly attribute FileOpenAction openAction
 The opening action specified when opening the file. More...
 
readonly attribute FileAccessMode accessMode
 The file access mode. More...
 

Detailed Description

Abstract parent interface for files handled by VirtualBox.

Interface ID:
{14C66B23-404C-F24A-3CC1-EE9501D44F2A}

Member Function Documentation

void IFile::close ( )

Closes this file.

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

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

Queries information about this file.

Parameters
objInfoObject information of this file. Also see IFsObjInfo.
Expected result codes:
E_NOTIMPL The method is not implemented yet.
void IFile::querySize ( [retval] out long long  size)

Queries the current file size.

Parameters
sizeQueried file size.
Expected result codes:
E_NOTIMPL The method is not implemented yet.
void IFile::read ( in unsigned long  toRead,
in unsigned long  timeoutMS,
[retval] out octet[]  data 
)

Reads data from this file.

Parameters
toReadNumber of bytes to read.
timeoutMSTimeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
dataArray of data read.
Expected result codes:
E_NOTIMPL The method is not implemented yet.
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.

Parameters
offsetOffset in bytes to start reading.
toReadNumber of bytes to read.
timeoutMSTimeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
dataArray of data read.
Expected result codes:
E_NOTIMPL The method is not implemented yet.
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
offsetOffset to seek relative to the position specified by whence.
whenceOne of the FileSeekOrigin seek starting points.
newOffsetThe new file offset after the seek operation.
void IFile::setACL ( in wstring  acl,
in unsigned long  mode 
)

Sets the ACL of this file.

Parameters
aclThe ACL specification string. To-be-defined.
modeUNIX-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.
void IFile::setSize ( in long long  size)

Changes the file size.

Parameters
sizeThe new file size.
Expected result codes:
E_NOTIMPL The method is not implemented yet.
void IFile::write ( in octet[]  data,
in unsigned long  timeoutMS,
[retval] out unsigned long  written 
)

Writes bytes to this file.

Parameters
dataArray of bytes to write. The size of the array also specifies how much to write.
timeoutMSTimeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
writtenHow much bytes were written.
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.

Parameters
offsetOffset in bytes to start writing.
dataArray of bytes to write. The size of the array also specifies how much to write.
timeoutMSTimeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
writtenHow much bytes were written.
Expected result codes:
E_NOTIMPL The method is not implemented yet.

Member Data Documentation

readonly attribute IEventSource IFile::eventSource

Event source for file events.

readonly attribute unsigned long IFile::id

The ID VirtualBox internally assigned to the open file.

readonly attribute long long IFile::initialSize

The initial size in bytes when opened.

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.

readonly attribute FileStatus IFile::status

Current file status.

readonly attribute wstring IFile::fileName

Full path of the actual file name of this file.

readonly attribute unsigned long IFile::creationMode

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

readonly attribute FileOpenAction IFile::openAction

The opening action specified when opening the file.

readonly attribute FileAccessMode IFile::accessMode

The file access mode.