CeCreateProcess (RAPI) (Windows Embedded CE 6.0)

1/6/2010

This function is used to run a program on a remote Windows Embedded CE–based device. It creates a new process and its primary thread. The new process executes the specified executable file.

Syntax

BOOL CeCreateProcess(
  LPCWSTR lpApplicationName, 
  LPCWSTR lpCommandLine, 
  LPSECURITY_ATTRIBUTES lpProcessAttributes, 
  LPSECURITY_ATTRIBUTES lpThreadAttributes, 
  BOOL bInheritHandles, 
  DWORD dwCreationFlags, 
  LPVOID lpEnvironment, 
  LPWSTR lpCurrentDirectory, 
  LPSTARTUPINFO lpStartupInfo, 
  LPPROCESS_INFORMATION lpProcessInformation 
); 

Parameters

  • lpApplicationName
    [in] Long pointer to a null-terminated string that specifies the module to execute.

    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 lpApplicationName parameter must be non-NULL and must include the module name.

  • lpCommandLine
    [in] Long pointer to a null-terminated string that specifies the command line arguments with which the application will be executed.

    The lpCommandLine parameter can be NULL. In that case, the function uses the string pointed to by lpApplicationName as the command line.

    If lpCommandLine is non-NULL, lpApplicationName specifies the module to execute, and lpCommandLine specifies the command line arguments. C runtime processes can use the argc and argv arguments to access the command line values.

  • lpProcessAttributes
    [in] Not supported; set to NULL.
  • lpThreadAttributes
    [in] Not supported; set to NULL.
  • bInheritHandles
    [in] Not supported; set to FALSE.
  • dwCreationFlags
    [in] Specifies additional flags that control the priority and the creation of the process. For Windows Embedded CE versions 1.0 and later, specify either zero or the following flag.

    Value Description

    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.

    For Windows Embedded CE versions 2.0 and later, you can specify one of the following flags in addition to those in previous editions.

    Value Description

    DEBUG_PROCESS

    If this flag is set, then 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_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.

    For Windows Embedded CE versions 3.0 and later, you can specify one of the following flags in addition to those in previous editions.

    Value Description

    CREATE_NEW_CONSOLE

    If this flag is set, then the new process has a new console, instead of inheriting the parent's console.

  • lpEnvironment
    [in] Not supported; set to NULL.
  • lpCurrentDirectory
    [in] Not supported; set to NULL.
  • lpStartupInfo
    [in] Not supported; set to NULL.
  • lpProcessInformation
    [out] Long pointer to a PROCESS_INFORMATION structure that receives identification information about the new process.

Return Value

Nonzero indicates success. Zero indicates failure. To get extended error information, call CeGetLastError and CeRapiGetError.

Remarks

If lpApplicationName does not contain an extension, .EXE is assumed. If the file name ends in a period (.) with no extension, or the file name contains a path, .EXE is not appended.

If the filename does not contain a directory path, Windows Embedded CE searches for the executable file in the following sequence:

Windows CE .NET 4.2 and later

  1. The windows (\windows) directory.
  2. The root (\) directory of the device .
  3. An OEM-dependent directory, which include the Windows Embedded CE Debug shell directory for Platform Builder users only.

Windows CE 2.10 to Windows CE .NET 4.2

  1. The windows (\windows) directory.
  2. The root (\) directory of the device .
  3. An OEM-dependent directory.
  4. The OEM-defined shell (\ceshell) directory (Platform Builder users only).

Windows CE 1.0 and Windows CE 2.10

  1. The root of the PC Card, if it exists.
  2. The windows (\windows) directory.
  3. The root (\ ) directory of the device.

Requirements

Header rapi.h
Library rapi.lib
Windows Embedded CE Windows CE 3.0 and later

See Also

Reference

RAPI Functions