Index: /trunk/doc/manual/en_US/SDKRef.xml
===================================================================
--- /trunk/doc/manual/en_US/SDKRef.xml (revision 80710)
+++ /trunk/doc/manual/en_US/SDKRef.xml (revision 80711)
@@ -2549,4 +2549,201 @@
+
+
+ Working with the Cloud
+
+ VirtualBox supports and goes towards the Oracle tendencies like "move to the Cloud".
+
+
+ OCI features
+ VirtualBox supports the Oracle Cloud Infrastructure (OCI). See the interfaces:
+ ICloudClient,
+ ICloudProvider,
+ ICloudProfile,
+ ICloudProviderManager.
+
+ Each cloud interface has own implementation to support OCI features. There are everal functions in the implementation
+ which should be explained in details because OCI requires some special data or settings.
+
+
+ Also see the enumeration VirtualSystemDescriptionType for the possible values.
+
+
+
+
+ Function ICloudClient::exportVM
+
+ See the ICloudClient::exportVM.
+ The function exports an existing virtual machine into OCI. The final result of this operation is creation a custom image
+ from the bootable image of VM. The Id of created image is returned in the parameter "description" (which is
+ IVirtualSystemDescription) as an entry with the type
+ VirtualSystemDescriptionType::CloudImageId. The standard steps here are:
+
+
+ Upload VBox image to OCI Object Storage.
+
+
+ Create OCI custom image from the uploaded object.
+
+
+ Parameter "description" must contain all information and settings needed for creation a custom image in OCI.
+ At least next entries must be presented there before the call:
+
+
+ VirtualSystemDescriptionType::Name - Name of new instance in OCI.
+
+
+ VirtualSystemDescriptionType::HardDiskImage - The local path or id of bootable VM image.
+
+
+ VirtualSystemDescriptionType::CloudBucket - A cloud bucket name where the exported image is uploaded.
+
+
+ VirtualSystemDescriptionType::CloudImageDisplayName - A name which is assigned to a new custom image in the OCI.
+
+
+ VirtualSystemDescriptionType::CloudKeepObject - Whether keep or delete an uploaded object after its usage.
+
+
+ VirtualSystemDescriptionType::CloudLaunchInstance - Whether launch or not a new instance.
+
+
+
+
+
+
+ Function ICloudClient::launchVM
+
+ See the ICloudClient::launchVM.
+ The function launches a new instance in OCI with a previously created custom image as a bootable image in OCI.
+ The final result of this operation is a running instance. The id of created instance is returned
+ in the parameter "description" (which is IVirtualSystemDescription)
+ as an entry with the type VirtualSystemDescriptionType::CloudInstanceId. Parameter "description" must contain all information
+ and settings needed for creation a new instance in OCI. At least next entries must be presented there before the call:
+
+
+ VirtualSystemDescriptionType::Name - Name of new instance in OCI.
+
+
+ VirtualSystemDescriptionType::CloudOCISubnet - OCID of existing subnet in OCI which will be used by the instance.
+
+
+ VirtualSystemDescriptionType::CloudImageId - OCID of custom image used as a bootable image for the instance.
+
+
+ VirtualSystemDescriptionType::CloudBootDiskSize - The size of instance bootable image in GB.
+
+
+ VirtualSystemDescriptionType::CloudInstanceShape - The shape of instance according to OCI documentation,
+ defines the number of CPUs and RAM memory.
+
+
+ VirtualSystemDescriptionType::CloudLaunchInstance - Whether launch or not a new instance.
+
+
+ VirtualSystemDescriptionType::CloudDomain - Availability domain in OCI where new instance is created.
+
+
+ VirtualSystemDescriptionType::CloudPublicIP - Whether the instance will have a public IP or not.
+
+
+
+
+
+
+ Function ICloudClient::getInstanceInfo
+
+ See the ICloudClient::getInstanceInfo.
+ The function takes an instance id (parameter "uid"), finds the requested instance in OCI and gets back information
+ about the found instance in the parameter "description" (which is IVirtualSystemDescription)
+ The entries with next types will be presented in the object:
+
+
+ VirtualSystemDescriptionType::Name - Displayed name of the instance.
+
+
+ VirtualSystemDescriptionType::CloudDomain - Availability domain in OCI.
+
+
+ VirtualSystemDescriptionType::CloudImageId - Name of custom image used for creation this instance.
+
+
+ VirtualSystemDescriptionType::CloudInstanceId - The OCID of the instance.
+
+
+ VirtualSystemDescriptionType::OS - Guest OS type of the instance.
+
+
+ VirtualSystemDescriptionType::CloudBootDiskSize - Size of instance bootable image.
+
+
+ VirtualSystemDescriptionType::CloudInstanceState - The instance state according to OCI documentation.
+
+
+ VirtualSystemDescriptionType::CloudInstanceShape - The instance shape according to OCI documentation
+
+
+ VirtualSystemDescriptionType::Memory - RAM memory in GB allocated for the instance.
+
+
+ VirtualSystemDescriptionType::CPU - Number of virtual CPUs allocated for the instance.
+
+
+
+
+
+
+ Function ICloudClient::importInstance
+
+ See the ICloudClient::importInstance.
+ The API function imports an existing instance from the OCI to the local host.
+ The standard steps here are:
+
+
+ Create a custom image from an existing OCI instance.
+
+
+ Export the custom image to OCI object (the object is created in the OCI Object Storage).
+
+
+ Download the OCI object to the local host.
+
+
+ As the result of operation user will have a file with the suffix ".oci" on the local host. This file is a TAR archive which
+ contains a bootable instance image converted into the VMDK format and a JSON file with some metadata related to
+ the imported instance. The function takes the parameter "description"
+ (which is IVirtualSystemDescription)
+ Parameter "description" must contain all information and settings needed for successful operation result.
+ At least next entries must be presented there before the call:
+
+
+ VirtualSystemDescriptionType::Name is used for the several purposes:
+
+
+ As a custom image name. A custom image is created from an instance.
+
+
+ As OCI object name. An object is a file in OCI Object Storage. The object is created from the custom image.
+
+
+ Name of imported instance on the local host. Because the result of import is a file, the file will have this
+ name and extension ".oci".
+
+
+
+
+
+ VirtualSystemDescriptionType::CloudInstanceId - The OCID of the existing instance.
+
+
+ VirtualSystemDescriptionType::CloudBucket - a cloud bucket name in OCI Object Storage where created an OCI object
+ from a custom image.
+
+
+
+
+
+
+