Name

Description

VixHandle
VixVM_WriteVariable(VixHandle vmHandle,
                    int variableType,
                    const char *valueName,
                    const char *value,
                    int options,
                    VixEventProc *callbackProc,
                    void *clientData);

This function writes variables to the virtual machine state. This includes the virtual machine configuration, environment variables in the guest, and VMware "Guest Variables".

Parameters

vmHandle

Identifies a virtual machine. Call VixVM_Open() to create a virtual machine handle.

variableType

The type of variable to write. The currently supported values are:

• VIX_VM_GUEST_VARIABLE - A "Guest Variable". This is a runtime-only value; it is never stored persistently. This is the same guest variable that is exposed through the VMControl APIs, and is a simple way to pass runtime values in and out of the guest.
• VIX_VM_CONFIG_RUNTIME_ONLY - The configuration state of the virtual machine. This is the .vmx file that is stored on the host. You can read this and it will return the persistent data. If you write to this, it will only be a runtime change, so changes will be lost when the VM powers off. Not supported on ESX hosts.
• VIX_GUEST_ENVIRONMENT_VARIABLE - An environment variable in the guest of the VM. On a Windows NT series guest, writing these values is saved persistently so they are immediately visible to every process. On a Linux or Windows 9X guest, writing these values is not persistent so they are only visible to the VMware tools process. Requires root or Administrator privilege.

valueName

The name of the variable.

value

The value to be written.

options

Must be 0.

callbackProc

A callback function that will be invoked when the operation is complete.

clientData

A parameter that will be passed to the callbackProc function.

Return Value

Remarks

• The VIX_VM_CONFIG_RUNTIME_ONLY variable type is not supported on ESX hosts.
• You must call VixVM_LoginInGuest() before calling this function to write a VIX_GUEST_ENVIRONMENT_VARIABLE value. You do not have to call VixVM_LoginInGuest() to use this function to write a VIX_VM_GUEST_VARIABLE or a VIX_VM_CONFIG_RUNTIME_ONLY value.
• Do not use the slash '/' character in a VIX_VM_GUEST_VARIABLE variable name; doing so produces a VIX_E_INVALID_ARG error.
• Do not use the equal '=' character in the valueName parameter; doing so produces a VIX_E_INVALID_ARG error.
• On Linux guests, you must login as root to change environment variables (when variable type is VIX_GUEST_ENVIRONMENT_VARIABLE) otherwise it produces a VIX_E_GUEST_USER_PERMISSIONS error.
• On Windows Vista guests, when variable type is VIX_GUEST_ENVIRONMENT_VARIABLE, you must turn off User Account Control (UAC) in Control Panel > User Accounts > User Accounts > Turn User Account on or off, in order for this function to work.

Side Effects

Requirements

Example