# Name

VixVM_Open

# Description

    VixHandle
    VixVM_Open(VixHandle hostHandle,
               const char *vmxFilePathName,
               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.

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

- This function opens a virtual machine on the host that is identified by the hostHandle parameter. The virtual machine is identified by vmxFilePathName, which is a path name to the configuration file (.VMX file) for that virtual machine.
- The format of the path name depends on the host operating system. For example, a path name for a Windows host requires backslash as a directory separator, whereas a Linux host requires a forward slash. If the path name includes backslash characters, you need to precede each one with an escape character. For VMware vSphere (ESX or vCenter Server) or VMware Server 2.x, the path contains a preceding data store, for example [storage1] vm/vm.vmx.
- This function is asynchronous, and uses a job object to report when the operation is complete. The function returns a handle to the job object immediately. When the job is signaled, the virtual machine handle is stored as the VIX_PROPERTY_JOB_RESULT_HANDLE property of the job object.
- For ESX/ESXi hosts and VMware Server, a virtual machine must be registered before you can open it. You can register a virtual machine by opening it with the VMware Server Console, through the vmware-cmd command with the register parameter, or with VixHost_RegisterVM.
- For vSphere, the Virtual Machine opened may not be the one desired if more than one Datacenter contains vmxFilePathName.
- For ESX/ESXi hosts and vSphere, the user account specified in the call to VixHost_Connect must have "System.View" privilege at the level of the Datacenter containing the ESX server that hosts the VM to be opened.
- For ESX/ESXi hosts and vSphere, the user account specified in the call to VixHost_Connect must have sufficient privileges to access guest operations in the virtual machine. For vSphere 4.1 and later, the privilege is "Virtual Machine.Interaction.Acquire Guest Control Ticket". For 4.0, the privilege is "Virtual Machine.Interaction.Console Interaction".

# Side Effects

None.

# Requirements

vix.h, since VMware Server 1.0

# Example

    VixError err = VIX_OK;
    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 = VixVM_Open(hostHandle,
                           "c:\\Virtual Machines\\vm1\\win2000.vmx",
                           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);

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