Location: Symbol Reference > Functions > JwElevateProcess Function
JWSCL Documentation
ContentsIndexHome
PreviousUpNext
JwElevateProcess Function
Pascal
function JwElevateProcess(const FileName: TJwString; Parameters: TJwString; Directory: TJwString; hWindow: HWND; ElevationProcessFlags: TJwElevationProcessFlags; const OnElevationGetCredentials: TJwOnElevationGetCredentials): TJwProcessId;
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 

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.

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.

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 
Description 
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. 
Currently not used. 
A call to JwShellExecute failed. This happens only on system with UAC available. See property LastError for more information. 
This exception is raised if SuRun is not setup properly.See property LastError for more information. 
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. 
This error only happens when a call to the Secondary Logon Process failed.See property LastError for more information. 
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. 

The function acts the following way:

  1. If it detects SuRun and parameter ElevationProcessFlags contains epfAllowSuRun it uses SuRun to elevate the application.
  2. 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
  3. 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.

Copyright (c) 2010. All rights reserved.
This help was created by Doc-O-Matic sponsored by toolsfactory software inc.
What do you think about this topic? Send feedback!