# Name

VixHost_UnregisterVM

# Description

    VixHandle
    VixHost_UnregisterVM(VixHandle hostHandle,
                         const char *vmxFilePath,
                         VixEventProc *callbackProc,
                         void *clientData);

This function removes a virtual machine from the host's inventory.

# Parameters

hostHandle
  The host handle returned by VixHost_Connect().
vmxFilePath
  The storage path of the .vmx file on the host.
callbackProc
  A function to be invoked when VixHost_UnregisterVM() completes.
clientData
  A user-supplied parameter to be passed to the callback function.

# Return Value

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

# Remarks

- This function unregisters the virtual machine identified by vmxFilePathName, which is a storage path to the configuration file (.vmx) for that virtual machine. A virtual machine must be powered off to unregister it.
- The format of the storage path depends on the host operating system. If the storage path includes backslash characters, you need to precede each one with an escape character. Path to storage [standard] or [storage1] may vary.
- For VMware Server 1.x, supply the full path name instead of storage path, and specify VIX_SERVICEPROVIDER_VMWARE_SERVER to connect.
- This function returns VIX_OK but has no effect on Workstation or Player, which lack a virtual machine inventory.
- This function is asynchronous. Completion is reported by a job handle.
- It is not a Vix error to unregister an already-unregistered virtual machine, nor is it a Vix error to unregister a non-existent virtual machine.
- 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 unregistered.

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

    // Connect to the Server 2.x host:
    jobHandle = VixHost_Connect(VIX_API_VERSION,
                                VIX_SERVICEPROVIDER_VMWARE_VI_SERVER,
                                "https://viserver/sdk", // hostName
                                0, // hostPort
                                "root", // userName
                                "rootpasswd", // 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);

    // Unregister the virtual machine:
    jobHandle = VixHost_UnregisterVM(hostHandle,
                                // "[storage1] RedHatLinux/RedHatLinux.vmx"
                                   "[standard] Windows XP\\Windows XP.vmx",
                                   NULL, // callbackProc
                                   NULL); // clientData
    err = VixJob_Wait(jobHandle,
                      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.