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