ArgxCreateProcessAsUser function

Creates a new process, running in the security context of the user represented by the given token

This is equivalent to the Windows CreateProcessAsUser API.

Syntax

BOOL ArgxCreateProcessAsUser(
        HANDLE                hToken,
        LPCTSTR               lpApplicationName,
        LPCTSTR*              lpArgv,
        DWORD                 dwArgc,
        LPSECURITY_ATTRIBUTES lpProcessAttributes,
        LPSECURITY_ATTRIBUTES lpThreadAttributes,
        BOOL                  bInheritHandles,
        DWORD                 dwCreationFlags,
        LPVOID                lpEnvironment,
        LPCTSTR               lpCurrentDirectory,
        LPSTARTUPINFO         lpStartupInfo,
        LPPROCESS_INFORMATION lpProcessInformation
     );

Parameters

hToken

A primary token representing the user in whose security context the new process should start. This handle must have TOKEN_QUERY, TOKEN_DUPLICATE and TOKEN_ASSIGN_PRIMARY access rights (see Access Rights for Access-Token Objects). The user identified by the token must have read and execute access to the application that is being started.

You can obtain such a token by calling the LogonUser or DuplicateTokenEx APIs.

lpApplicationName

The path to the executable to start. This string is not subject to any path searching, though it may be a relative path. There is no default extension for this parameter.

If this parameter is NULL, the executable path will be taken from the first argument, lpArgv[0].

lpArgv

The argument vector. If lpApplicationName is NULL, the first element of the argument vector will be used to locate the desired executable.

In that case:

  • If lpArgv[0] contains path delimiters, it will be treated as a literal path and used directly; otherwise,
  • If lpArgv[0] does not have an extension, the extension “.exe” will be appended automatically.
  • The function will then try to find the executable by looking in the following places:
    1. The directory from which the calling application loaded.
    2. The current directory.
    3. The Windows System32 directory (as returned by the GetSystemDirectory API).
    4. The 16-bit Windows System directory, if present.
    5. The Windows directory (as returned by the GetWindowsDirectory API).
    6. The directories listed in the PATH environment variable.

This function will not modify any of the strings in lpArgv. Also note that this function does not suffer from the security hole in the CreateProcessAsUser API caused by that function’s attempt to parse filenames and directory names containing spaces.

lpArgv must not be NULL.

dwArgc
The number of elements in lpArgv, which must be at least one.
lpProcessAttributes
Describes the desired SECURITY_ATTRIBUTES for the new process. May be NULL.
lpThreadAttributes
Describes the desired SECURITY_ATTRIBUTES for the primary thread of the new process. May be NULL.
bInheritHandles
If TRUE, inheritable handles will be inherited by the subprocess. Importantly, inherited handles have the same access rights that they have in the parent process, so this needs to be used with care.
dwCreationFlags
Flags that control priority class and creation behaviour. See Process Creation Flags for more information.
lpEnvironment
Points to the environment block for the new process, or NULL to inherit the environment of the parent.
lpCurrentDirectory
If NULL, the new process will start with the same current directory as the parent process. Otherwise, must contain the full path to the desired current directory.
lpStartupInfo
Points to a STARTUPINFO or STARTUPINFOEX structure. May be NULL.
lpProcessInformation
Points to a PROCESS_INFORMATION structure that will be filled in with handles to the process and its primary thread. Note that these handles must be closed when no longer needed.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, it will return zero (i.e. FALSE), with extended error information supplied via GetLastError.