Name

VixHost_OpenVM

Description

VixHandle
VixHost_OpenVM(VixHandle hostHandle,
               const char *vmxFilePathName,
               VixVMOpenOptions options,
               VixHandle propertyListHandle,
               VixEventProc *callbackProc,
               void *clientData);

This function opens a virtual machine on the host that is identified by the hostHandle parameter and returns a context to that machine as a virtual machine handle. This function supercedes VixVM_Open().

Parameters

hostHandle
The handle of a host object, typically returned from VixHost_Connect().

vmxFilePathName
The path name of the virtual machine configuration file on the local host.
options
Must be VIX_VMOPEN_NORMAL.
propertyListHandle
A handle to a property list containing extra information that might be needed to open the VM. This parameter is optional; you can pass VIX_INVALID_HANDLE if no extra information is needed.
callbackProc
A callback function that will be invoked when the operation is complete.
clientData
A parameter that will be passed to the callbackProc procedure.

Return Value

VixHandle. A job handle that describes the state of this asynchronous call.

Remarks

Requirements

vix.h, since VMware Workstation 7.0

Example

The following sample illustrates how to open a regular virtual machine on a VMware Workstation host:
VixError err;
VixHandle hostHandle = VIX_INVALID_HANDLE;
VixHandle jobHandle = VIX_INVALID_HANDLE;
VixHandle vmHandle = VIX_INVALID_HANDLE;

// Connect to the local host:
jobHandle = VixHost_Connect(VIX_API_VERSION,
                            VIX_SERVICEPROVIDER_VMWARE_WORKSTATION,
                            NULL, // hostName
                            0, // hostPort
                            NULL, // userName
                            NULL, // password
                            0, // options
                            VIX_INVALID_HANDLE, // propertyListHandle
                            NULL, // callbackProc
                            NULL); // clientData

err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &hostHandle,
                  VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}
// Release handle when done:
Vix_ReleaseHandle(jobHandle);

// Open the virtual machine:
jobHandle = VixHost_OpenVM(hostHandle,
                           "c:\\Virtual Machines\\vm1\\win2000.vmx",
                           VIX_VMOPEN_NORMAL,
                           VIX_INVALID_HANDLE,
                           NULL, // callbackProc
                           NULL); // clientData
err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &vmHandle,
                  VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}
// Release handle when done:
Vix_ReleaseHandle(jobHandle);
The following sample illustrates how to open a regular virtual machine on a VMware ESX host:
VixError err;
VixHandle hostHandle = VIX_INVALID_HANDLE;
VixHandle jobHandle = VIX_INVALID_HANDLE;
VixHandle vmHandle = VIX_INVALID_HANDLE;

// Connect to the local host:
jobHandle = VixHost_Connect(VIX_API_VERSION,
                            VIX_SERVICEPROVIDER_VMWARE_VI_SERVER,
                            "https://10.20.30.40/sdk", // hostName
                            0, // hostPort
                            "username", // userName
                            "password", // password
                            0, // options
                            VIX_INVALID_HANDLE, // propertyListHandle
                            NULL, // callbackProc
                            NULL); // clientData

err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &hostHandle,
                  VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}
// Release handle when done:
Vix_ReleaseHandle(jobHandle);

// Open the virtual machine:
jobHandle = VixHost_OpenVM(hostHandle,
                           "[datastore] vm1/vm1.vmx",
                           VIX_VMOPEN_NORMAL,
                           VIX_INVALID_HANDLE,
                           NULL, // callbackProc
                           NULL); // clientData
err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &vmHandle,
                  VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}
// Release handle when done:
Vix_ReleaseHandle(jobHandle);
The following sample illustrates how to open an encrypted virtual machine on a VMware Workstation host:
VixError err;
VixHandle hostHandle = VIX_INVALID_HANDLE;
VixHandle jobHandle = VIX_INVALID_HANDLE;
VixHandle vmHandle = VIX_INVALID_HANDLE;
VixHandle propertyHandle = VIX_INVALID_HANDLE;

// Connect to the local host:
jobHandle = VixHost_Connect(VIX_API_VERSION,
                            VIX_SERVICEPROVIDER_VMWARE_WORKSTATION,
                            NULL, // hostName
                            0, // hostPort
                            NULL, // userName
                            NULL, // password
                            0, // options
                            VIX_INVALID_HANDLE, // propertyListHandle
                            NULL, // callbackProc
                            NULL); // clientData

err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &hostHandle,
                  VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}
// Release handle when done:
Vix_ReleaseHandle(jobHandle);

err = VixPropertyList_AllocPropertyList(hostHandle,
                                        &propertyHandle,
                                        VIX_PROPERTY_VM_ENCRYPTION_PASSWORD,
                                        "vmPassword",
                                        VIX_PROPERTY_NONE);
if (err != VIX_OK) {
   // Handle the error...
   goto abort;
}

// Open the virtual machine:
jobHandle = VixHost_OpenVM(hostHandle,
                           "c:\\Virtual Machines\\vm1\\win2000.vmx",
                           VIX_VMOPEN_NORMAL,
                           propertyHandle,
                           NULL, // callbackProc
                           NULL); // clientData
err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &vmHandle,
                  VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}
// Release handle when done:
Vix_ReleaseHandle(jobHandle);
Vix_ReleaseHandle(propertyHandle);

Copyright (C) 2007-2010 VMware, Inc. All rights reserved.