Function name: CreateProcessWithLogon

Defined in : advapi32

Requirements : Windows 2000 or later; Win9x/ME: Not supported

Declaration:

Declare Function CreateProcessWithLogon Lib "Advapi32" Alias "CreateProcessWithLogonW" (ByVal lpUsername As Long, ByVal lpDomain As Long, ByVal lpPassword As Long, ByVal dwLogonFlags As Long, ByVal lpApplicationName As Long, ByVal lpCommandLine As Long, ByVal dwCreationFlags As Long, ByVal lpEnvironment As Long, ByVal lpCurrentDirectory As Long, lpStartupInfo As STARTUPINFO, lpProcessInfo As PROCESS_INFORMATION) As Long

Parameters:

* lpUsername [in] Pointer to a null-terminated string that specifies the name of the user. This is the name of the user account to log on to. If you use the UPN format, user@DNS_domain_name, the lpDomain parameter must be NULL. 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. * lpDomain [in] Pointer to a null-terminated string that specifies the name of the domain or server whose account database contains the lpUsername account. If this parameter is NULL, the user name must be specified in UPN format. Windows XP: If this parameter is ".", the function validates the account using only the local account database. * lpPassword [in] Pointer to a null-terminated string that specifies the clear-text password for the lpUsername account. * dwLogonFlags [in] Specifies the logon option. This parameter can be one of the following values. Value Meaning LOGON_WITH_PROFILE Log on, then load the user's profile. Loading the profile can be time-consuming, so it is best to use this value only if you must access the user's profile information. LOGON_NETCREDENTIALS_ONLY Log on, but use the specified credentials on the network only. The new process uses the same token as the caller, but the system creates a new logon session within LSA, and the process uses the specified credentials as the default credentials. This value can be used to create a process that uses a different set of credentials locally than it does remotely. This is useful in inter-domain scenarios where there is no trust relationship. * lpApplicationName [in] Pointer to a null-terminated string that specifies the module to execute. The specified module can be a Windows-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. 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. If the file name does not contain an extension, .exe is assumed. Therefore, if the file name extension is .com, this parameter must include the .com extension. The lpApplicationName 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 filessub dirprogram 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 filessub dirprogram name c:program filessub.exe dirprogram name c:program filessub dirprogram.exe name c:program filessub dirprogram name.exe 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. * lpCommandLine [in] Pointer to a null-terminated string that specifies the command line to execute. This function will fail if this parameter is a const string. 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. Therefore, if the file name extension is .com, this parameter must include the .com extension. 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: The directory from which the application loaded. The current directory for the parent process. The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is System32. The 16-bit Windows system directory. There is no function that obtains the path of this directory, but it is searched. The name of this directory is System. The Windows directory. Use the GetWindowsDirectory function to get the path of this directory. The directories that are listed in the PATH environment variable. The system adds a null character to the command line string to separate the file name from the arguments. This divides the original string into two strings for internal processing. * dwCreationFlags [in] Specifies how the process is created. The CREATE_DEFAULT_ERROR_MODE, CREATE_NEW_CONSOLE, and CREATE_NEW_PROCESS_GROUP flags are enabled by default. You can specifiy additional flags as noted. 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. 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. You can specify one of the following values. ABOVE_NORMAL_PRIORITY_CLASS Indicates a process that has priority higher than NORMAL_PRIORITY_CLASS but lower than HIGH_PRIORITY_CLASS. BELOW_NORMAL_PRIORITY_CLASS 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. * lpEnvironment [in] Pointer to an environment block for the new process. If this parameter is NULL, the new process uses the environment of the calling process. 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. An environment block can contain Unicode or ANSI characters. If the environment block pointed to by lpEnvironment contains Unicode characters, be sure that dwCreationFlags includes CREATE_UNICODE_ENVIRONMENT. 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. * lpCurrentDirectory [in] Pointer to a null-terminated string that specifies the current drive and directory for the new process. The string must be a full path that includes a drive letter. If this parameter is NULL, the new process has the same current drive as the system service that creates the process. (This feature is provided primarily for shells that need to start an application and specify its initial drive and working directory.) * lpStartupInfo [in] Pointer to a STARTUPINFO structure that specifies how the main window for the new process should appear. * lpProcessInfo [out] Pointer to a PROCESS_INFORMATION structure that receives identification information for the new process, including a handle to the process. Handles in PROCESS_INFORMATION must be closed with the CloseHandle function when they are no longer needed.

Returns:

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.

Related functions:

Examples:

Sorry, this function has no examples yet.