CreateProcess (Windows CE 5.0)
This function is used to run a new program. It creates a new process and its primary thread. The new process executes the specified executable file.
Note The remote application interface (RAPI) version of this function is named CeCreateProcess (RAPI).
BOOL CreateProcess( LPCWSTR pszImageName, LPCWSTR pszCmdLine, LPSECURITY_ATTRIBUTES psaProcess, LPSECURITY_ATTRIBUTES psaThread, BOOL fInheritHandles, DWORD fdwCreate, LPVOID pvEnvironment, LPWSTR pszCurDir, LPSTARTUPINFOW psiStartInfo, LPPROCESS_INFORMATION pProcInfo);
Parameters
pszImageName
[in] Pointer to a null-terminated string that specifies the module to execute.The string can specify the full path and filename of the module to execute or it can specify a partial path and filename.
The lpszImageName parameter must be non-NULL and must include the module name.
pszCmdLine
[in, out] Pointer to a null-terminated string that specifies the command line to execute.The system adds a null character to the command line, trimming the string if necessary, to indicate which file was used.
The lpszCmdLine parameter can be NULL. In that case, the function uses the string pointed to by lpszImageName as the command line.
If lpszImageName and lpszCmdLine are non-NULL, * lpszImageName specifies the module to execute, and * lpszCmdLine specifies the command line.
C runtime processes can use the argc and argv arguments.
If the filename does not contain an extension, .EXE is assumed.
If the filename ends in a period (.) with no extension, or if the filename contains a path, .EXE is not appended.
psaProcess
[in] Not supported; set to NULL.psaThread
[in] Not supported; set to NULL.fInheritHandles
[in] Not supported; set to FALSE.fdwCreate
[in] Specifies additional flags that control the priority and the creation of the process.The following creation flags can be specified in any combination, except as noted.
Value Description CREATE_DEFAULT_ERROR_MODE Not supported. CREATE_NEW_CONSOLE The new process has a new console, instead of inheriting the parent's console. CREATE_NEW_PROCESS_GROUP Not supported. CREATE_SEPARATE_WOW_VDM Not supported. CREATE_SHARED_WOW_VDM Not supported. 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 Not supported. DEBUG_PROCESS If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. Child processes of the new process are also debugged. The system notifies the debugger of all debug events that occur in the process being debugged.
If you create a process with this flag set, only the calling thread (the thread that called CreateProcess) can call the WaitForDebugEvent function.
DEBUG_ONLY_THIS_PROCESS If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. No child processes of the new process are debugged. The system notifies the debugger of all debug events that occur in the process being debugged.
DETACHED_PROCESS Not supported. INHERIT_CALLER_PRIORITY If this flag is set, the new process inherits the priority of the creator process. Windows CE does not support the concept of a priority class. The priority of a thread is the only parameter that determines a thread's scheduling priority.
pvEnvironment
[in] Not supported; set to NULL.pszCurDir
[in] Not supported; set to NULL.psiStartInfo
[in] Not supported; set to NULL.pProcInfo
[out] Pointer to a PROCESS_INFORMATION structure that receives identification information about the new process.
Return Values
Nonzero indicates success.
Zero indicates failure.
To get extended error information, call GetLastError.
Remarks
In addition to creating a process, it also creates a thread object.
The size of the initial stack for the thread is described in the image header of the specified program's executable file.
The thread begins execution at the image's entry point.
The new process and the new thread handles are created with full access rights. For either handle, the handle can be used in any function that requires an object handle to that type.
The process is assigned a 32-bit 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 32-bit thread identifier. 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.
The following list shows the directories indicated by the pszImageName parameter in the order that Windows CE searches them:
- The windows (\windows) directory
- The root (\) directory of the device
- An OEM-specified directory
The following list shows the directories indicated by the pszImageName parameter in the order that Windows CE 2.10 and later search them:
- The windows (\windows) directory
- The root (\) directory of the device
- An OEM-dependent directory
- The OEM-defined shell (\ceshell) directory (Platform Builder users only)
The following list shows the directories indicated by the pszImageName parameter in the order Windows CE 1.0 through 2.01 search them:
- The root of the PC Card, if it exists
- The windows (\windows) directory
- The root (\ ) directory of the device
When specifying an application name in the pszImageName string, it does not matter whether the application name includes the filename extension.
Do not call CreateProcess from a DllMain function. This causes the application to stop responding.
The following registry subkey specifies a search path to use with the LoadLibrary function and CreateProcess:
HKEY_LOCAL_MACHINE\Loader
"SystemPath" = multi_sz:"\\path1\\"
"\\path2\\"
The path is only searched if the path of the file being looked for is not explicitly specified.
If the length of the SystemPath value exceeds 260 characters, the path is ignored. A change to the SystemPath key does not take effect until a Windows CE-based device is reset.
ExitThread, CreateThread, and a process that is starting (as the result of a call by CreateProcess) are serialized between each other within a process. Only one of these events can happen in an address space at a time. The following list shows the restrictions during the process:
- During process startup and DLL initialization routines, new threads can be created but they do not begin execution until DLL initialization is completed.
- In a process, only one thread at a time can be in a DLL initialization or detach routine.
The created process remains in the system until all threads within the process are terminated and all handles to the process and its threads are closed through calls to CloseHandle.
The handles for the process and the main thread must be closed through calls to CloseHandle. If these handles are not needed, close them immediately after the process is created.
The following events occur when the last thread in a process terminates:
- All objects opened by the process are implicitly closed.
- The process's termination status, which is returned by GetExitCodeProcess, changes from its initial value of STILL_ACTIVE to the termination status of the last thread to terminate.
- The thread object of the main thread is set to the signaled state, satisfying threads that were waiting on the object.
- The process object is set to the signaled state, satisfying threads that were waiting on the object.
The handle returned by the CreateProcess function has PROCESS_ALL_ACCESS access to the process object.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Winbase.h.
Link Library: Coredll.lib.
See Also
CeCreateProcess (RAPI) | CloseHandle | CreateThread | DllMain | ExitThread | GetExitCodeProcess | LoadLibrary | OpenProcess | ResumeThread | TerminateProcess | WaitForDebugEvent | PROCESS_INFORMATION
Send Feedback on this topic to the authors