JwElevateProcess Function

Pascal

function JwElevateProcess(const FileName: TJwString; Parameters: TJwString; Directory: TJwString; hWindow: HWND; ElevationProcessFlags: TJwElevationProcessFlags; const OnElevationGetCredentials: TJwOnElevationGetCredentials): TJwProcessId;

File

JwsclElevation

Parameters

Parameters	Description
const FileName: TJwString	This parameter receives the application to be elevated.
Parameters: TJwString	This parameter receives the parameter to be applied to the new process.
Directory: TJwString	This parameter receives the target directory of the new process.
hWindow: HWND	If any UI is display this window handle is used as a parent. Can be 0 to use no parent at all (not recommended). This handle is used by UAC prompt Windows default credentials prompt SuRun
ElevationProcessFlags: TJwElevationProcessFlags	Receives a set of flags that controls the behavior of the function. See TJwElevationProcessFlags for more information.
const OnElevationGetCredentials: TJwOnElevationGetCredentials	This event is used only if SuRun is not available or ignored (due to missing epfAllowSuRun) UAC is not supported by OS epfNoUi is set in parameter ElevationProcessFlags See TJwOnElevationGetCredentials

Returns

The return value is a processID of the newly created process.

If the process is started by SuRun the returned value can be 0 although the process was elevated successfully. SuRun 1.2.0.5 and older don't support PIDs. In this case zero (0) is returned. If there was an error getting the PID the exception EJwsclPIDException will be raised.

Description

JwElevateProcess is much like JwShellExecute but also may work on Windows 2000 and XP without UAC. Instead of UAC it uses SuRun if installed. On Vista/2008 and newer it tries to use UAC. If UAC and SuRun is not available it falls back to ShellExecute with the RunAs verb. In this case a dialog pops up the receives a username and password to use (usually Administrator). If no UI is allowed the function can use another method that receives the username and password from a generated even method (OnElevationGetCredentials). In this case the process is started using Windows Secondary Logon Service.

The return value is a process handle, in case of SuRun zero, or zero if it closed automatically.

Remarks

In case of the EJwsclSuRunErrorException the LastError property contains more information. SuRun returns some status error code information that can be used.

Status value	Description
-1 (WAIT_FAILED)	Not a SuRun status code. It happens when a wait call for the SuRun process failed because the process handle is invalid.
258 (WAIT_TIMEOUT)	Not a SuRun status code. A time out occurred while waiting for the SuRun process to finish. This usually happens when SuRun stucks or Surun's credential prompt time out is greater than 60seconds. (constant timeout)
0 (RETVAL_OK)	SuRun returned successfully. The designated application is run elevated.
1 (RETVAL_ACCESSDENIED)	SuRun: TBD
3 (RETVAL_RESTRICT)	SuRun: The current user is not allowed to run applications elevated or this application cannot be run elevated by the current user.
4 (RETVAL_CANCELLED)	SuRun: The user canceled the elevation process.

Exceptions

Exceptions	Description
EJwsclAbortException	The elevation was aborted by the user.
EjwsclCryptApiException	This exception is raised if the encrypted password received through the OnElevationGetCredentials event could not be decrypted.
EJwsclElevateProcessException	Super class of EJwsclAbortException EJwsclElevationException EJwsclJwShellExecuteException EJwsclShellExecuteException EJwsclSuRunErrorException Actually this exception is not raised.
EJwsclElevationException	Currently not used.
EJwsclJwShellExecuteException	A call to JwShellExecute failed. This happens only on system with UAC available. See property LastError for more information.
EJwsclShellExecuteException	This exception is raised if SuRun is not setup properly.See property LastError for more information.
EJwsclSuRunErrorException	This exception will be raised if SuRun fails to elevate the new process. The property LastError of this exception contains more information about the error. See remarks section for more information.
EJwsclWinCallFailedException	This error only happens when a call to the Secondary Logon Process failed.See property LastError for more information.
EJwsclPIDException	This error occurs when the PID could not be returned. You can ignore this error if you don't use the return value. The exception won't be thrown if SuRun does not support PIDs.

Conditions

The function acts the following way:

If it detects SuRun and parameter ElevationProcessFlags contains epfAllowSuRun it uses SuRun to elevate the application.
If Windows Vista, 2008, 7 is detected
1. and UAC is available, it uses UAC to elevate the process.
2. and UAC is not available, it uses Secondary Logon Process and thus event parameter OnElevationGetCredentials is called
In all other cases it uses Secondary Logon Process and thus event parameter OnElevationGetCredentials is called

JwElevateProcess does not fall back to Secondary Logon Process if UAC is enabled but fails.

Group

Functions

Links

JwsclElevation, Functions

Contents | Index | Home

What do you think about this topic? Send feedback!