SHCreateProcessAsUserW function (shellapi.h)

Article
02/22/2024

[SHCreateProcessAsUserW is not implemented under Windows XP or later systems.]

Creates a new user-mode process and its primary thread to run a specified executable file.

Syntax

BOOL SHCreateProcessAsUserW(
  [in, out] PSHCREATEPROCESSINFOW pscpi
);

Parameters

[in, out] pscpi

Type: PSHCREATEPROCESSINFOW

A pointer to an SHCREATEPROCESSINFOW structure with information on how to create the process.

Return value

Type: BOOL

Returns TRUE if successful, or FALSE if not. To retrieve extended error information, call GetLastError.

Remarks

This function is similar to ShellExecuteEx with runas as the verb. However, SHCreateProcessAsUserW creates a process that runs in the security context of the user represented by the hUserToken member of the structure pointed to by pscpi. The lpProcessInformation member can be used to return a PROCESS_INFORMATION structure with information on the new process.

The runas verb must be supported by the executable file's file type. The .exe file type supports runas. Use the AssocQueryString function to check whether runas is supported by other file types. The following code fragment illustrates the syntax.

AssocQueryString(0, ASSOCSTR_COMMAND, pszFile, TEXT("runas"), NULL, &cchVerb)

For a discussion of how to use the Shell to launch applications, see Launching Applications.

SHCreateProcessAsUserW is not supported under Windows XP. Users requiring similar functionality should examine CreateProcess, CreateProcessAsUser, CreateProcessWithLogonW and ShellExecuteEx, carefully evaluating each based on required functionality and security. IQueryAssociations can be used to extract information used with CreateProcess, if necessary.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	shellapi.h
Library	Shell32.lib
DLL	Shell32.dll (version 5.0 or later)