Name

VixHost_Connect

Description

VixHandle
VixHost_Connect(int apiVersion,
                VixServiceProvider hostType,
                const char *hostName,
                int hostPort,
                const char *userName,
                const char *password,
                VixHostOptions options,
                VixHandle propertyListHandle,
                VixEventProc *callbackProc,
                void *clientData);

Creates a host handle.

Parameters

apiVersion: Must be VIX_API_VERSION.
hostType: VIX_SERVICEPROVIDER_VMWARE_SERVER or VIX_SERVICEPROVIDER_VMWARE_WORKSTATION.
hostName: DNS name or IP address of remote host. Use NULL to connect to local host.
hostPort: TCP/IP port of remote host, typically 902. Use zero for local host.
userName: Username to authenticate with on remote machine. Use NULL to authenticate as current user on local host.
password: Password to authenticate with on remote machine. Use NULL to authenticate as current user on local host.
options: Optionally VIX_HOSTOPTION_USE_EVENT_PUMP (See Remarks section), otherwise zero.
propertyListHandle: Must be VIX_INVALID_HANDLE.
callbackProc: Optional callback of type VixEventProc.
clientData: Optional user supplied opaque data to be passed to optional callback.

Return Value

A job handle. When the job completes, retrieve the Host handle from the job handle using the VIX_PROPERTY_JOB_RESULT_HANDLE property.

Remarks

To specify the local host (where the API client runs), pass null values for the hostName, hostPort, userName, and password parameters. This is shown in the example below.
If you are already connected to the host, a subsequent call to VixHost_Connect() succeeds if you connect as the same user and use the same host name. Subsequent calls return the same handle value.
When you initialize the host object, you can also control some Vix operations with the options parameter. The following option is supported:
- VIX_HOSTOPTION_USE_EVENT_PUMP . All asynchronous event processing happens when the client calls Vix_PumpEvents(). The client is responsible for regularly calling Vix_PumpEvents(), such as in an event loop.

Side Effects

None.

Requirements

vix.h, since VMware Server 1.0

Example

#include "vix.h"
int main(int argc, char * argv[])
{
   VixHandle hostHandle = VIX_INVALID_HANDLE;
   VixHandle jobHandle = VIX_INVALID_HANDLE;
   VixError err;
   // Connect as current user on local host.
   jobHandle = VixHost_Connect(VIX_API_VERSION,
                               VIX_SERVICEPROVIDER_VMWARE_SERVER,
                               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;
   }
   Vix_ReleaseHandle(jobHandle);
   // Other code goes here...
   abort:
   Vix_ReleaseHandle(jobHandle);
   VixHost_Disconnect(hostHandle);
}