VirtualBox Main API

Public Attributes | List of all members
ISharedFolder Interface Reference

The ISharedFolder interface represents a folder in the host computer's file system accessible from the guest OS running inside a virtual machine using an associated logical name. More...

Inheritance diagram for ISharedFolder:

## Public Attributes
readonly attribute wstring | name
| Logical name of the shared folder.
readonly attribute wstring | hostPath
| Full path to the shared folder in the host file system.
readonly attribute boolean | accessible
| Whether the folder defined by the host path is currently accessible or not.
attribute boolean | writable
| Whether the folder defined by the host path is writable or not.
attribute boolean | autoMount
| Whether the folder gets automatically mounted by the guest or not.
attribute wstring | autoMountPoint
| Desired mount point in the guest for automatically mounting the folder when ISharedFolder::autoMount is set.
readonly attribute wstring | lastAccessError
| Text message that represents the result of the last accessibility check.
attribute SymlinkPolicy | symlinkPolicy
| The security policy for allowing guest VMs to create symbolic links within a Shared Folder.

## Detailed Description

The ISharedFolder interface represents a folder in the host computer's file system accessible from the guest OS running inside a virtual machine using an associated logical name.

There are three types of shared folders:

- Global (IVirtualBox::sharedFolders), shared folders available to all virtual machines.
- Permanent (IMachine::sharedFolders), VM-specific shared folders available to the given virtual machine at startup.
- Transient (IConsole::sharedFolders), VM-specific shared folders created in the session context (for example, when the virtual machine is running) and automatically discarded when the session is closed (the VM is powered off).

Logical names of shared folders must be unique within the given scope (global, permanent or transient). However, they do not need to be unique across scopes. In this case, the definition of the shared folder in a more specific scope takes precedence over definitions in all other scopes. The order of precedence is (more specific to more general):

1. Transient definitions
2. Permanent definitions
3. Global definitions

For example, if MyMachine has a shared folder named `C_DRIVE` (that points to `C:\`), then creating a transient shared folder named `C_DRIVE` (that points to `C:\\WINDOWS`) will change the definition of `C_DRIVE` in the guest OS so that `\\VBOXSVR\C_DRIVE` will give access to `C:\WINDOWS` instead of `C:\` on the host PC. Removing the transient shared folder `C_DRIVE` will restore the previous (permanent) definition of `C_DRIVE` that points to `C:\` if it still exists.

Note that permanent and transient shared folders of different machines are in different name spaces, so they don't overlap and don't need to have unique logical names.

Interface ID:
  `{0B108B8C-62E0-4E06-9DFA-2F1A2AD70774}`

## Member Data Documentation

## ◆ name

readonly attribute wstring ISharedFolder::name

Logical name of the shared folder.

## ◆ hostPath

readonly attribute wstring ISharedFolder::hostPath

Full path to the shared folder in the host file system.

## ◆ accessible

readonly attribute boolean ISharedFolder::accessible

Whether the folder defined by the host path is currently accessible or not.

For example, the folder can be inaccessible if it is placed on the network share that is not available by the time this property is read.

## ◆ writable

attribute boolean ISharedFolder::writable

Whether the folder defined by the host path is writable or not.

## ◆ autoMount

attribute boolean ISharedFolder::autoMount

Whether the folder gets automatically mounted by the guest or not.

## ◆ autoMountPoint

attribute wstring ISharedFolder::autoMountPoint

Desired mount point in the guest for automatically mounting the folder when ISharedFolder::autoMount is set.

For Windows and OS/2 guests this should be a drive letter, while other guests it should be a absolute directory. It is possible to combine the two, e.g. "T:/mnt/testrsrc" will be attached to "T:" by windows and OS/2 while the unixy guests will mount it at "/mnt/testrsrc".

When empty the guest will choose a mount point. The guest may do so too should the specified mount point be in use or otherwise unusable.

## ◆ lastAccessError

readonly attribute wstring ISharedFolder::lastAccessError

Text message that represents the result of the last accessibility check.

Accessibility checks are performed each time the accessible attribute is read. An empty string is returned if the last accessibility check was successful. A non-empty string indicates a failure and should normally describe a reason of the failure (for example, a file read error).

## ◆ symlinkPolicy

attribute SymlinkPolicy ISharedFolder::symlinkPolicy

The security policy for allowing guest VMs to create symbolic links within a Shared Folder.