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:

## 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

## ◆ 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.

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

## ◆ querySize()

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

Queries the current file size.

Parameters

  size | Queried file size.

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

## ◆ read()

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

Reads data from this file.

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.

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

## ◆ 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.

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.

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

## ◆ 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.

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

## ◆ write()

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

Writes bytes to this file.

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

Parameters

  offset | Offset in bytes to start writing.
  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 much bytes were written.

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

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

## ◆ 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.