PrlVmGuest_RunProgram Function

Executes a program in a virtual machine.

Syntax

PRL_HANDLE PrlVmGuest_RunProgram(
    PRL_HANDLE hVmGuest, 
    PRL_CONST_STR sAppName, 
    PRL_HANDLE hArgsList, 
    PRL_HANDLE hEnvsList, 
    PRL_UINT32 nFlags
);

File

PrlApi.h

Parameters

hVmGuest

A handle of type PHT_VM_GUEST_SESSION identifying the user session in a virtual machine. The handle is obtained using the PrlVm_LoginInGuest function.

sAppName

An absolute path to the program that you would like to execute.

hArgsList

A handle of type PHT_STRINGS_LIST specifying the list of arguments to pass to the program. Each token must be a separate list item.

hEnvsList

A handle of type PHT_STRINGS_LIST specifying the list of environment variables to add to the program execution environment. Each variable must be a separate list item in the var_name=var_value format.

nFlags

Modificators of the program execution. Acceptable values:

PFD_STDOUT - return stdout.

PFD_STDERR - return stderr.

PFD_ALL - return both stdout and stderr (a blank nFlags parameter yields the same result).

PRPM_RUN_PROGRAM_AND_RETURN_IMMEDIATELY - run the program and return immediately without waiting for the program execution results.

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

Prior to calling this function, a handle to a user session in a virtual machine must be obtained using the PrlVm_LoginInGuest function. Once you obtain a session handle, you can use this function to run programs in the virtual machine. Depending on the options that were used during login, you will be able to run GUI applications and/or console programs. See the PrlVm_LoginInGuest function for more info.

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

PRL_ERR_INVALID_ARG - invalid handle was passed.

PRL_ERR_VM_EXEC_PROGRAM_NOT_FOUND - the specified program at the specified path was not found.

PRL_ERR_SUCCESS - program executed successfully.

Links

PrlApi.h , PHT_VM_GUEST_SESSION