Managed Object - FileManager

Property of
ServiceContent
See also
Datacenter
Since
VI API 2.5


Managed Object Description

NOTE: This managed object type and all of its methods are experimental and subject to change in future releases.

This managed object type provides a way to manage and manipulate files and folders on datastores. The source and the destination names are in the form of a URL or a datastore path.

A URL has the form

scheme://authority/folder/path?dcPath=dcPath&dsName=dsName
where
  • scheme is http or https.
  • authority specifies the hostname or IP address of the VirtualCenter or ESX server and optionally the port.
  • dcPath is the inventory path to the Datacenter containing the Datastore.
  • dsName is the name of the Datastore.
  • path is a slash-delimited path from the root of the datastore.
  • A datastore path has the form

    [datastore] path
    where
  • datastore is the datastore name.
  • path is a slash-delimited path from the root of the datastore.
  • An example datastore path is "[storage] path/to/file.extension". A listing of all the files, disks and folders on a datastore can be obtained from the datastore browser.
    See HostDatastoreBrowser

    Properties

    Name Type Description
    None

    Methods

    Methods defined in this Managed Object
    CopyDatastoreFile_Task, DeleteDatastoreFile_Task, MakeDirectory, MoveDatastoreFile_Task

    CopyDatastoreFile_Task

    Copies the source file to the destination.

    If the destination file does not exist, it is created. If the destination file exists, the force parameter determines whether to overwrite it with the source or not. Copying folders is not supported. If any intermediate level folder specified by the source and destination does not exist, a FileNotFound fault is thrown.

    If a file of a virtual machine is overwritten on the destination datastore as a result of the force parameter, it may corrupt that virtual machine. Recursive copy is not supported.

    If the source is an extent of a virtual disk, this operation treats the extent as a file.

    It is important to note that this operation will provide transactional guarantees only for a filek. If the intent is to clone a virtual machine registered in the inventory, with transactional guarantees, please refer to CloneVM_Task.

    Experimental. Subject to change

    Required Privileges
    None

    Parameters

    NameTypeDescription
    _thisManagedObjectReference A reference to the FileManager used to make the method call.
    sourceNamexsd:string

    The name of the source, either a URL or a datastore path referring to the file to be copied.
    sourceDatacenter* PManagedObjectReference
    to a Datacenter

    If sourceName is a datastore path, the datacenter for that datastore path. If not specified, sourceName must be a URL.
    destinationNamexsd:string

    The name of the destination, either a URL or a datastore path referring to the destination file.
    destinationDatacenter* PManagedObjectReference
    to a Datacenter

    If destinationName is a datastore path, the datacenter for that datastore path If not specified and sourceName is a datastore path, it is assumed that the destination path belongs to the source datacenter.
    force*xsd:boolean

    If true, overwrite any identically named filek at the destination. If not specified, it is assumed to be false.
    *Need not be set P Required privilege: Datastore.FileManagement

    Return Value

    Type Description
    ManagedObjectReference
    to a Task
    This method returns a Task object with which to monitor the operation.

    Faults

    Type Description
    CannotAccessFileThrown if the source cannot be accessed because of insufficient permissions.
    FileAlreadyExistsThrown if a file with the given name already exists at the destination, and the force flag is false.
    FileFault
    FileLockedThrown if the source file is currently locked or in use.
    FileNotFoundThrown if the file specified by sourceName is not found, or, any intermediate level folder specified by the destinationName is not found.
    InvalidDatastoreThrown if the operation cannot be performed on the source or destination datastores. Typically, a specific subclass of this exception is thrown.
    NoDiskSpaceThrown if there is not enough space available at the destination datastore.
    RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

    Show WSDL type definition



    DeleteDatastoreFile_Task

    Deletes the specified file or folder from the datastore. If a file of a virtual machine is deleted, it may corrupt that virtual machine. An empty folder may be specified as the source. Recursive delete is not supported.

    If the source is an extent of a virtual disk, this operation treats the extent as a file.

    It is important to note that this operation will provide transactional guarantees only for a file. If the intent is to delete a virtual machine registered in the inventory, please refer to Destroy_Task.

    Requires Datastore.FileManagement privilege on the datacenter.

    Experimental. Subject to change

    Required Privileges
    None

    Parameters

    NameTypeDescription
    _thisManagedObjectReference A reference to the FileManager used to make the method call.
    namexsd:string

    The name of the file or folder,e either a URL or a datastore path referring to the file or folder to be deleted.
    datacenter* PManagedObjectReference
    to a Datacenter

    If name is a datastore path, the datacenter for that datastore path. If not specified, name must be a URL.
    *Need not be set P Required privilege: Datastore.FileManagement

    Return Value

    Type Description
    ManagedObjectReference
    to a Task
    This method returns a Task object with which to monitor the operation.

    Faults

    Type Description
    CannotDeleteFileThrown if the delete operation on the file or folder fails.
    FileFault
    FileLockedThrown if the source file or folder is currently locked or in use.
    FileNotFoundThrown if the file or folder specified by name is not found.
    InvalidDatastoreThrown if the operation cannot be performed on the datastore. Typically, a specific subclass of this exception is thrown.
    RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

    Show WSDL type definition



    MakeDirectory

    Create a folder using the specified name. If the parent or intermediate level folders do not exist, and the parameter createParentDirectories is false, a FileNotFound fault is thrown. If the intermediate level folders do not exist, and the parameter createParentDirectories is true, all the non-existent folders are created.

    Requires Datastore.FileManagement privilege on the datacenter.

    Experimental. Subject to change

    Required Privileges
    None

    Parameters

    NameTypeDescription
    _thisManagedObjectReference A reference to the FileManager used to make the method call.
    namexsd:string

    The name of the folder, either a URL or a datastore path referring to the folder to be created.
    datacenter* PManagedObjectReference
    to a Datacenter

    If name is a datastore path, the datacenter for that datastore path. If not specified, name must be a URL.
    createParentDirectories*xsd:boolean

    If true, any non-existent intermediate level folders will be created. If not specified, it is assumed to be false.
    *Need not be set P Required privilege: Datastore.FileManagement

    Return Value

    Type Description
    None

    Faults

    Type Description
    CannotCreateFileThrown if the create operation on the folder fails.
    FileAlreadyExistsThrown if a file or folder with the given name already exists at the destination.
    FileFault
    FileNotFoundThrown if the createParentDirectories is false and a intermediate level folder specified by name is not found.
    InvalidDatastoreThrown if the operation cannot be performed on the datastore. Typically, a specific subclass of this exception is thrown.
    RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

    Show WSDL type definition



    MoveDatastoreFile_Task

    Moves the source file to the destination

    If the destination file does not exist, it is created. If the destination file exists, the force parameter determines whether to overwrite it with the source or not. Moving folders is not supported. If any intermediate level folder specified by the source and destination does not exist, a FileNotFound fault is thrown.

    If a file of a virtual machine is moved, it may corrupt that virtualmachine. If a file of a virtual machine is overwritten on the destination datastore as a result of the force parameter, it may corrupt that virtual machine. Recursive move is not supported.

    If the source is an extent of a virtual disk, this operation treats the extent as a file.

    It is important to note that this operation will provide transactional guarantees only for a file. If the intent is to move a virtual machine registered in the inventory, with transactional guarantees, please refer to RelocateVM_Task. If the intent is to rename a virtual machine registered in the inventory, please refer to Rename_Task.

    Experimental. Subject to change

    Required Privileges
    None

    Parameters

    NameTypeDescription
    _thisManagedObjectReference A reference to the FileManager used to make the method call.
    sourceNamexsd:string

    The name of the source, either a URL or a datastore path referring to the file to be moved.
    sourceDatacenter* PManagedObjectReference
    to a Datacenter

    If sourceName is a datastore path, the datacenter for that datastore path. If not specified, sourceName must be a URL.
    destinationNamexsd:string

    The name of the destination, either a URL or a datastore path referring to the destination file.
    destinationDatacenter* PManagedObjectReference
    to a Datacenter

    If destinationName is a datastore path, the datacenter for that datastore path If not specified and sourceName is a datastore path, it is assumed that the destination path belongs to the source datacenter.
    force*xsd:boolean

    If true, overwrite any identically named file at the destination. If not specified, it is assumed to be false.
    *Need not be set P Required privilege: Datastore.FileManagement

    Return Value

    Type Description
    ManagedObjectReference
    to a Task
    This method returns a Task object with which to monitor the operation.

    Faults

    Type Description
    CannotAccessFileThrown if the source file cannot be moved because of insufficient permissions.
    FileAlreadyExistsThrown if a file with the given name already exists at the destination, and the force flag is false.
    FileFault
    FileLockedThrown if the source file is currently locked or in use.
    FileNotFoundThrown if the file specified by sourceName is not found, or, any intermediate level folder specified by the destinationName is not found.
    InvalidDatastoreThrown if the operation cannot be performed on the source or destination datastores. Typically, a specific subclass of this exception is thrown.
    NoDiskSpaceThrown if there is not enough space available on the destination datastore.
    RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

    Show WSDL type definition