Name
VixDiskLib_ConnectEx
Description
VixError
VixDiskLib_ConnectEx(const VixDiskLibConnectParams *connectParams,
Bool readOnly,
const char *snapshotRef,
const char *transportModes,
VixDiskLibConnection *connection);
Create a transport context to access disks belonging to a
particular snapshot of a particular virtual machine. Using this
transport context enables callers to open virtual disks using
the most efficient data access protocol available for managed
virtual machines, for improved I/O performance.
If you use this call instead of VixDiskLib_Connect(), the additional
information passed in helps optimize the I/O access path to maximize I/O throughput.
This function opens a connection to VixDiskLib. You can use this connection to
later request various services from VixDiskLib.
Parameters
- connectParams
-
A structure containing the parameters to establish a connection:
- vmxSpec - a managed object ID string specifying the VM, in the form "moref=<moid>"
- serverName - host name or IP address of ESX/ESXi or vCenter Server
- credType - VIXDISKLIB_CRED_UID, VIXDISKLIB_CRED_SESSIONID, VIXDISKLIB_CRED_TICKETID,
or VIXDISKLIB_CRED_SSPI
- creds - union to hold credentials: userName/password for UID, cookie/userName/key for others
- port - port number to connect through
- readOnly
-
Should be set to TRUE if no write access is needed
for the disks to be accessed through this connection. In
some cases, a more efficient I/O path can be used for read-only access.
- snapshotRef
-
A managed object reference to the snapshot of the virtual
machine whose disks will be accessed with this connection.
Specifying this property is only meaningful if the vmxSpec
property in connectParams is set as well.
- transportModes
-
An optional list of transport modes that can be
used for this connection, separated by colons. If you specify NULL
specified (recommended), VixDiskLib's default setting is used.
The default setting corresponds to the string
returned by VixDiskLib_ListTransportModes().
If a disk is opened through this connection, VixDiskLib
starts with the first entry of the list and attempts to
use this transport mode to gain access to the virtual
disk. If this does not work, the next item in the list
is tried until either the disk is successfully opened
or the end of the list is reached.
- connection
-
A handle for the connection. This is an output parameter.
Return Value
VIX_OK if the function succeeded, otherwise an appropriate VIX error code.
Remarks
- To create a connection to open a managed disk, provide valid credentials for
the ESX server that currently hosts the virtual machine owning the virtual disk,
or the managing vCenter Server.
- To create a connection that can open hosted type disks, use null values for
vmname, hostname, username, password and port.
This is sufficient to establish a connection to the localhost.
For hosted type disks, this call is equivalent to using VixDiskLib_Connect().
- This function blocks until the connection completes.
- Every call to VixDiskLib_ConnectEx() should have a matching
VixDiskLib_Disconnect().
- When using VixDiskLib_ConnectEx(), some state might have not been cleaned
up if the resulting connection was not shut down cleanly. Use
VixDiskLib_Cleanup() to remove this extra state.
Example
VixDiskLibConnectParams cnxParams = {0};
if (appGlobals.isRemote) {
cnxParams.vmxSpec = moid-str;
cnxParams.serverName = hostName;
cnxParams.credType = VIXDISKLIB_CRED_UID;
cnxParams.creds.uid.userName = userName;
cnxParams.creds.uid.password = password;
cnxParams.port = port;
}
VixError vixError = VixDiskLib_ConnectEx(&cnxParams,
TRUE,
"snapshot-47",
"san:nbd:file",
&connection);