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
for VMware Server 1.x,
VIX_SERVICEPROVIDER_VMWARE_WORKSTATION
for Workstation 6.x, or
VIX_SERVICEPROVIDER_VMWARE_VI_SERVER
for VMware Server 2.x.
- hostName
-
DNS name, IP address, or URL of the remote host.
For VMware Server 1.x, use a DNS name or IP address.
For VMware Server 2.x, use a URL of the form
"https://<hostName>:<port>/sdk" where <hostName>
could be DNS name or IP address. Use
NULL
to connect to
local host.
- hostPort
-
TCP/IP port of remote host. Use zero for local host.
On VMware Server 2.x you must specify port number within
the hostName parameter, so this parameter is ignored.
- 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.
- For VMware Server 2.x, the URL for the hostName argument should specify the port.
Otherwise an HTTPS connection is attempted on port 443.
HTTPS is strongly recommended.
Port numbers are set during installation of Server 2.x.
The installer's default HTTP and HTTPS values
are 8222 and 8333 for Server on Windows,
or (if not already in use) 80 and 443 for Server on Linux,
and 902 for the automation socket, authd.
If connecting to a virtual machine though a firewall,
port 902 and the communicating port must be opened to allow guest operations.
- 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_VI_SERVER,
https://viserver/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);
}