PrlVm_LoginInGuest Function

Creates a new console session or binds to an existing GUI session in a virtual machine.

Syntax

PRL_HANDLE PrlVm_LoginInGuest(
    PRL_HANDLE hVm, 
    PRL_CONST_STR sUserName, 
    PRL_CONST_STR sUserPassword, 
    PRL_UINT32 nFlags
);

File

PrlApiVm.h

Parameters

hVm

A handle of type PHT_VIRTUAL_MACHINE identifying the virtual machine.

sUserName

User name. This parameter must contain a valid guest OS user name or one of the following constants:

PRL_CURRENT_GUEST_OS_SESSION -- binds to an existing GUI session in a virtual machine.

PRL_PRIVILEGED_GUEST_OS_SESSION -- binds to an existing session under which Parallels Service is running. This session belongs to a privileged user (e.g. root on Linux or LocalSystem on Windows), so it can be used to perform administrative tasks.

Note that in order to use the constants above, the current user must be an administrator of the host OS or be the owner of the target virtual machine.

sUserPassword

User password. If the sUserName parameter contains one of the constants (see above) then this parameter can contain an empty string.

nFlags

A bitset of flags. Must be 0 in the current API implementation.

Returns

A handle of type PHT_JOB containing the results of this asynchronous operation or PRL_INVALID_HANDLE if there's not enough memory to instantiate the job object.

Remarks

Note: To use this function, Parallels Tools must be installed in the target virtual machine.

This function is used when you want to run a program in a virtual machine or perform an administrative task that require native guest operating system login. Depending on the type of the program that you would like to run, the login must be performed using one of the following methods:

To run a GUI application, call this function passing the PRL_CURRENT_GUEST_OS_SESSION constant in the sUserName parameter. The reason is the function can only bind to an existing GUI session and cannot create a new one. Prior to calling this function, a GUI session must already be open in a virtual machine (the machine must be running and a user must be logged in to it). The user password parameter can be blank.
To run a console program, the sUserName parameter can contain the PRL_PRIVILEGED_GUEST_OS_SESSION constant or a valid user name and password. When using PRL_PRIVILEGED_GUEST_OS_SESSION, the function will bind to an existing session under which Parallels Service is running. This session belongs to a privileged user (e.g. root on Linux or LocalSystem on Windows), so it can be used to perform administrative tasks. When specifying a user name and password, a new session will be created in the virtual machine.

On successful login, the function obtains a handle of type PHT_VM_GUEST_SESSION (see below for the instructions on how to get the handle from the PHT_JOB object). You can use the handle functions to run programs in a virtual machine and to perform other supported operations. See the PHT_VM_GUEST_SESSION handle description for a complete list of functions.

When the session is no longer needed, it should be closed using the PrlVmGuest_Logout function.

To get the return code from the PHT_JOB object, use the PrlJob_GetRetCode function. Possible values are:

PRL_ERR_INVALID_ARG - invalid handle or null pointer was passed.

PRL_ERR_SUCCESS - function completed successfully.

To get the PHT_VM_GUEST_SESSION handle from the returned PHT_JOB object:

Use the PrlJob_GetResult function to obtain the PHT_RESULT handle.
Use the PrlResult_GetParam to obtain the PHT_VM_GUEST_SESSION handle.