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, 
    PRL_FILE_DESC nStdin, 
    PRL_FILE_DESC nStdout, 
    PRL_FILE_DESC nStderr
);

File

PrlApiVm.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.

nStdin

file descriptor on standard input (PRL_INVALID_FILE_DESCRIPTOR should be passed if you don't want to use file descriptors. Please note that IO channel between client and VM should be established before using file descriptors. Please call PrlDevDisplay_ConnectToVm in order to do it).

nStdout

file descriptor on standard output (PRL_INVALID_FILE_DESCRIPTOR should be passed if you don't want to use file descriptors. Please note that IO channel between client and VM should be established before using file descriptors. Please call PrlDevDisplay_ConnectToVm in order to do it).

nStderr

file descriptor on standard errors output (PRL_INVALID_FILE_DESCRIPTOR should be passed if you don't want to use file descriptors. Please note that IO channel between client and VM should be established before using file descriptors. Please call PrlDevDisplay_ConnectToVm in order to do it).

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_UNINITIALIZED - file descriptors interface tried to use but PrlDevDisplay_ConnectToVm wasn't call.

PRL_ERR_SUCCESS - program executed successfully.

Links

PHT_VM_GUEST_SESSION