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. This handle cannot be shared or reused after disconnect.

Parameters

apiVersion
Must be VIX_API_VERSION.
hostType
With vCenter Server, ESX/ESXi hosts, and VMware Server 2.0, use VIX_SERVICEPROVIDER_VMWARE_VI_SERVER. With VMware Workstation, use VIX_SERVICEPROVIDER_VMWARE_WORKSTATION. With VMware Workstation (shared mode), use VIX_SERVICEPROVIDER_VMWARE_WORKSTATION_SHARED. With VMware Player, use VIX_SERVICEPROVIDER_VMWARE_PLAYER. With VMware Server 1.0.x, use VIX_SERVICEPROVIDER_VMWARE_SERVER.
hostName
Varies by product platform. With vCenter Server, ESX/ESXi hosts, VMware Workstation (shared mode) and VMware Server 2.0, use a URL of the form "https://<hostName>:<port>/sdk" where <hostName> is either the DNS name or IP address. If missing, <port> may default to 443 (see Remarks below). In VIX API 1.10 and later, you can omit "https://" and "/sdk" specifying just the DNS name or IP address. Credentials are required even for connections made locally. With Workstation, use NULL to connect to the local host. With VMware Server 1.0.x, use the DNS name or IP address for remote connections, or the same as Workstation for local connections.
hostPort
TCP/IP port on the remote host. With VMware Workstation and VMware Player, use zero for the local host. With ESX/ESXi hosts, VMware Workstation (shared mode) and VMware Server 2.0 you specify port number within the hostName parameter, so this parameter is ignored (see Remarks below).
login
Username for authentication on the remote machine. With VMware Workstation, VMware Player, and VMware Server 1.0.x, use NULL to authenticate as the current user on local host. With vCenter Server, ESX/ESXi hosts, VMware Workstation (shared mode) and VMware Server 2.0, you must use a valid login.
password
Password for authentication on the remote machine. With VMware Workstation, VMware Player, and VMware Server 1.0.x, use NULL to authenticate as the current user on local host. With ESX/ESXi, VMware Workstation (shared mode) and VMware Server 2.0, you must use a valid login.
options
Should be zero. The option VIX_HOSTOPTION_USE_EVENT_PUMP has been deprecated and may be removed from future versions of the VIX API.
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

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_VI_SERVER,
                               "https://viserver.example.com/sdk", // hostName
                               0, // hostPort
                               "Administrator", // userName
                               "adminpass", // 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);
}

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