| Platform SDK: DLLs, Processes, and Threads |
The CreateProcessWithLogonW function creates a new process and its primary thread. The new process then runs the specified executable file in the security context of the specified credentials (user, domain, and password). It can optionally load the user profile of the specified user.
The CreateProcessWithLogonW function is similar to the CreateProcessAsUser function, except that the caller does not need to call the LogonUser function to authenticate the user and get a token.
BOOL CreateProcessWithLogonW( LPCWSTR lpUsername, // user's name LPCWSTR lpDomain, // user's domain LPCWSTR lpPassword, // user's password DWORD dwLogonFlags, // logon option LPCWSTR lpApplicationName, // executable module name LPWSTR lpCommandLine, // command-line string DWORD dwCreationFlags, // creation flags LPVOID lpEnvironment, // new environment block LPCWSTR lpCurrentDirectory, // current directory name LPSTARTUPINFOW lpStartupInfo, // startup information LPPROCESS_INFORMATION lpProcessInfo // process information );
The user account must have Log On Locally permission on the local computer. This permission is granted to all users on workstations and servers, but only to administrators on domain controllers.
If this parameter is NULL, CreateProcessWithLogonW attempts to validate the account using the local account database. If CreateProcessWithLogonW cannot find the account in the local account database, its trusted domains search their account databases until a match is found. Note that this parameter cannot be NULL unless you specify the user name in UPN format.
| Value | Meaning |
|---|---|
| LOGON_WITH_PROFILE | Log on with profile. |
| LOGON_NETCREDENTIALS_ONLY | Log on with only network credentials. |
The string can specify the full path and file name of the module to execute or it can specify a partial name. In the case of a partial name, the function uses the current drive and current directory to complete the specification. The function will not use the search path.
This parameter can be NULL. In that case, the module name must be the first white space-delimited token in the lpCommandLine string. If you are using a long file name that contains a space, use quoted strings to indicate where the file name ends and the arguments begin; otherwise, the file name is ambiguous. For example, consider the string "c:\program files\sub dir\program name". This string can be interpreted in a number of ways. The system tries to interpret the possibilities in the following order:
c:\program.exe files\sub dir\program name
c:\program files\sub.exe dir\program name
c:\program files\sub dir\program.exe name
c:\program files\sub dir\program name.exe
The specified module can be a Win32-based application. It can be some other type of module (for example, MS-DOS or OS/2) if the appropriate subsystem is available on the local computer. If the executable module is a 16-bit application, lpApplicationName should be NULL, and the string pointed to by lpCommandLine should specify the executable module as well as its arguments. A 16-bit application is one that executes as a VDM or WOW process.
The lpCommandLine parameter can be NULL. In that case, the function uses the string pointed to by lpApplicationName as the command line.
If both lpApplicationName and lpCommandLine are non-NULL, *lpApplicationName specifies the module to execute, and *lpCommandLine specifies the command line. The new process can use GetCommandLine to retrieve the entire command line. C runtime processes can use the argc and argv arguments. Note that it is a common practice to repeat the module name as the first token in the command line.
If lpApplicationName is NULL, the first white-space – delimited token of the command line specifies the module name. If you are using a long file name that contains a space, use quoted strings to indicate where the file name ends and the arguments begin (see the explanation for the lpApplicationName parameter). If the file name does not contain an extension, .exe is appended. If the file name ends in a period (.) with no extension, or if the file name contains a path, .exe is not appended. If the file name does not contain a directory path, the system searches for the executable file in the following sequence:
| Value | Meaning |
|---|---|
| CREATE_DEFAULT_ERROR_MODE | The new process does not inherit the error mode of the calling process. Instead, CreateProcessWithLogonW gives the new process the current default error mode. An application sets the current default error mode by calling SetErrorMode.
This flag is enabled by default. |
| CREATE_NEW_CONSOLE | The new process has a new console, instead of inheriting the parent's console. This flag cannot be used with the DETACHED_PROCESS flag.
This flag is enabled by default. |
| CREATE_NEW_PROCESS_GROUP | The new process is the root process of a new process group. The process group includes all processes that are descendants of this root process. The process identifier of the new process group is the same as the process identifier, which is returned in the lpProcessInfo parameter. Process groups are used by the GenerateConsoleCtrlEvent function to enable sending a CTRL+C or CTRL+BREAK signal to a group of console processes.
This flag is enabled by default. |
| CREATE_SEPARATE_WOW_VDM | This flag is only valid starting a 16-bit Windows-based application. If set, the new process runs in a private Virtual DOS Machine (VDM). By default, all 16-bit Windows-based applications run in a single, shared VDM. The advantage of running separately is that a crash only terminates the single VDM; any other programs running in distinct VDMs continue to function normally. Also, 16-bit Windows-based applications that run in separate VDMs have separate input queues. That means that if one application stops responding momentarily, applications in separate VDMs continue to receive input. |
| CREATE_SUSPENDED | The primary thread of the new process is created in a suspended state, and does not run until the ResumeThread function is called. |
| CREATE_UNICODE_ENVIRONMENT | Indicates the format of the lpEnvironment parameter. If this flag is set, the environment block pointed to by lpEnvironment uses Unicode characters. Otherwise, the environment block uses ANSI characters. |
| CREATE_WITH_USERPROFILE | If this flag is set, the system loads the user's profile after the logon succeeds. Loading the profile can be time-consuming, so it is best to use this flag only if you must access the user's profile information. |
The dwCreationFlags parameter also controls the new process's priority class, which is used to determine the scheduling priorities of the process's threads. If none of the following priority class flags is specified, the priority class is NORMAL_PRIORITY_CLASS by default unless the priority class of the creating process is IDLE_PRIORITY_CLASS or BELOW_NORMAL_PRIORITY_CLASS. In this case, the child process receives the default priority class of the calling process. One of the following flags can be specified.
| Priority | Meaning |
|---|---|
| ABOVE_NORMAL_PRIORITY_CLASS | Windows 2000: Indicates a process that has priority higher than NORMAL_PRIORITY_CLASS but lower than HIGH_PRIORITY_CLASS. |
| BELOW_NORMAL_PRIORITY_CLASS | Windows 2000: Indicates a process that has priority higher than IDLE_PRIORITY_CLASS but lower than NORMAL_PRIORITY_CLASS. |
| HIGH_PRIORITY_CLASS | Indicates a process that performs time-critical tasks. The threads of a high-priority class process preempt the threads of normal-priority or idle-priority class processes. An example is the Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a CPU-bound application with a high-priority class can use nearly all available cycles. |
| IDLE_PRIORITY_CLASS | Indicates a process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes. |
| NORMAL_PRIORITY_CLASS | Indicates a normal process with no special scheduling needs. |
| REALTIME_PRIORITY_CLASS | Indicates a process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive. |
An environment block consists of a null-terminated block of null-terminated strings. Each string is in the form:
name=value
Because the equal sign is used as a separator, it must not be used in the name of an environment variable.
If an application provides an environment block, rather than passing NULL for this parameter, the current directory information of the system drives is not automatically propagated to the new process. For a discussion of this situation and how to handle it, see the following Remarks section.
An environment block can contain Unicode or ANSI characters. If the environment block pointed to by lpEnvironment contains Unicode characters, set the dwCreationFlags parameter's CREATE_UNICODE_ENVIRONMENT flag. Otherwise, do not set this flag.
Note that an ANSI environment block is terminated by two zero bytes: one for the last string, one more to terminate the block. A Unicode environment block is terminated by four zero bytes: two for the last string, two more to terminate the block.
To retrieve a copy of the environment block for a given user, use the CreateEnvironmentBlock function.
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
By default, CreateProcessWithLogonW creates the new process on a noninteractive window station with a desktop that is not visible and cannot receive user input. To enable user interaction with the new process, you must specify the name of the default interactive window station and desktop, "winsta0\default", in the lpDesktop member of the STARTUPINFO structure. In addition, before calling CreateProcessWithLogonW, you must change the discretionary access control list (DACL) of both the default interactive window station and the default desktop. The DACLs for the window station and desktop must grant access to the user represented by the lpUsername parameter.
CreateProcessWithLogonW does not load the specified user's profile into the HKEY_USERS registry key. This means that access to information in the HKEY_CURRENT_USER registry key may not produce results consistent with a normal interactive logon. It is your responsibility to load the user's registry hive into HKEY_USERS, using the LoadUserProfile function, before calling CreateProcessWithLogonW.
If the lpEnvironment parameter is NULL, the new process inherits the environment of the calling process. CreateProcessWithLogonW does not automatically modify the environment block to include environment variables specific to the user. For example, the USERNAME and USERDOMAIN variables are inherited from the calling process if lpEnvironment is NULL. It is your responsibility to prepare the environment block for the new process and specify it in lpEnvironment.
When created, the new process and the new thread handles receive full access rights (PROCESS_ALL_ACCESS and THREAD_ALL_ACCESS). For either handle, if a security descriptor is not provided, the handle can be used in any function that requires an object handle of that type. When a security descriptor is provided, an access check is performed on all subsequent uses of the handle before access is granted. If access is denied, the requesting process cannot use the handle to gain access to the process or thread.
If the lpProcessAttributes parameter is NULL, the function uses the default security descriptor for the user. This security descriptor may not allow access for the caller, in which case the process may not be opened again after it is run. The handle returned in the PROCESS_INFORMATION structure is valid and will continue to have complete access. This is also true for thread attributes.
Handles in PROCESS_INFORMATION must be closed with CloseHandle when they are no longer needed.
The process is assigned a process identifier. The identifier is valid until the process terminates. It can be used to identify the process, or specified in the OpenProcess function to open a handle to the process. The initial thread in the process is also assigned a thread identifier. It can be specified in the OpenThread function to open a handle to the thread. The identifier is valid until the thread terminates and can be used to uniquely identify the thread within the system. These identifiers are returned in the PROCESS_INFORMATION structure.
When specifying an application name in the lpApplicationName or lpCommandLine strings, it doesn't matter whether the application name includes the file name extension, with one exception: an MS-DOS – based or Windows-based application whose file name extension is .com must include the .com extension.
The calling thread can use the WaitForInputIdle function to wait until the new process has finished its initialization and is waiting for user input with no input pending. This can be useful for synchronization between parent and child processes, because CreateProcessWithLogonW returns without waiting for the new process to finish its initialization. For example, the creating process would use WaitForInputIdle before trying to find a window associated with the new process.
The preferred way to shut down a process is by using the ExitProcess function, because this function sends notification of approaching termination to all DLLs attached to the process. Other means of shutting down a process do not notify the attached DLLs. Note that when a thread calls ExitProcess, other threads of the process are terminated without an opportunity to execute any additional code (including the thread termination code of attached DLLs).
The ExitProcess, ExitThread, CreateThread, and CreateRemoteThread functions, and processes that are starting (as the result of a call by CreateProcessWithLogonW) are serialized within a process. Only one of these events can happen at a time, and the following restrictions apply:
Windows NT/2000: Requires Windows 2000.
Windows 95/98: Unsupported.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Advapi32.lib.
Unicode: Implemented only as Unicode.
Processes and Threads Overview, Process and Thread Functions, CloseHandle, CreateEnvironmentBlock, CreateProcessAsUser, CreateRemoteThread, CreateThread, ExitProcess, ExitThread, GetExitCodeProcess, OpenProcess, OpenThread, PROCESS_INFORMATION, SetErrorMode, STARTUPINFO, WaitForInputIdle