parameters: (self, lpCmdLine, **kwargs)
return_statement: return aProcess
docstring: Starts a new process for instrumenting (or debugging).
  
          @type  lpCmdLine: str
          @param lpCmdLine: Command line to execute. Can't be an empty string.
  
          @type    bConsole: bool
          @keyword bConsole: True to inherit the console of the debugger.
              Defaults to C{False}.
  
          @type    bDebug: bool
          @keyword bDebug: C{True} to attach to the new process.
              To debug a process it's best to use the L{Debug} class instead.
              Defaults to C{False}.
  
          @type    bFollow: bool
          @keyword bFollow: C{True} to automatically attach to the child
              processes of the newly created process. Ignored unless C{bDebug} is
              C{True}. Defaults to C{False}.
  
          @type    bInheritHandles: bool
          @keyword bInheritHandles: C{True} if the new process should inherit
              it's parent process' handles. Defaults to C{False}.
  
          @type    bSuspended: bool
          @keyword bSuspended: C{True} to suspend the main thread before any code
              is executed in the debugee. Defaults to C{False}.
  
          @type    dwParentProcessId: int or None
          @keyword dwParentProcessId: C{None} if the debugger process should be
              the parent process (default), or a process ID to forcefully set as
              the debugee's parent (only available for Windows Vista and above).
  
          @type    iTrustLevel: int
          @keyword iTrustLevel: Trust level.
              Must be one of the following values:
               - 0: B{No trust}. May not access certain resources, such as
                    cryptographic keys and credentials. Only available since
                    Windows XP and 2003, desktop editions.
               - 1: B{Normal trust}. Run with the same privileges as a normal
                    user, that is, one that doesn't have the I{Administrator} or
                    I{Power User} user rights. Only available since Windows XP
                    and 2003, desktop editions.
               - 2: B{Full trust}. Run with the exact same privileges as the
                    current user. This is the default value.
  
          @type    bAllowElevation: bool
          @keyword bAllowElevation: C{True} to allow the child process to keep
              UAC elevation, if the debugger itself is running elevated. C{False}
              to ensure the child process doesn't run with elevation. Defaults to
              C{True}.
  
              This flag is only meaningful on Windows Vista and above, and if the
              debugger itself is running with elevation. It can be used to make
              sure the child processes don't run elevated as well.
  
              This flag DOES NOT force an elevation prompt when the debugger is
              not running with elevation.
  
              Note that running the debugger with elevation (or the Python
              interpreter at all for that matter) is not normally required.
              You should only need to if the target program requires elevation
              to work properly (for example if you try to debug an installer).
  
          @rtype:  L{Process}
          @return: Process object.
docstring_summary: Starts a new process for instrumenting (or debugging).
docstring_tokens: Starts a new process for instrumenting ( or debugging ) .
function: def start_process(self, lpCmdLine, **kwargs):
          """
          Starts a new process for instrumenting (or debugging).
  
          @type  lpCmdLine: str
          @param lpCmdLine: Command line to execute. Can't be an empty string.
  
          @type    bConsole: bool
          @keyword bConsole: True to inherit the console of the debugger.
              Defaults to C{False}.
  
          @type    bDebug: bool
          @keyword bDebug: C{True} to attach to the new process.
              To debug a process it's best to use the L{Debug} class instead.
              Defaults to C{False}.
  
          @type    bFollow: bool
          @keyword bFollow: C{True} to automatically attach to the child
              processes of the newly created process. Ignored unless C{bDebug} is
              C{True}. Defaults to C{False}.
  
          @type    bInheritHandles: bool
          @keyword bInheritHandles: C{True} if the new process should inherit
              it's parent process' handles. Defaults to C{False}.
  
          @type    bSuspended: bool
          @keyword bSuspended: C{True} to suspend the main thread before any code
              is executed in the debugee. Defaults to C{False}.
  
          @type    dwParentProcessId: int or None
          @keyword dwParentProcessId: C{None} if the debugger process should be
              the parent process (default), or a process ID to forcefully set as
              the debugee's parent (only available for Windows Vista and above).
  
          @type    iTrustLevel: int
          @keyword iTrustLevel: Trust level.
              Must be one of the following values:
               - 0: B{No trust}. May not access certain resources, such as
                    cryptographic keys and credentials. Only available since
                    Windows XP and 2003, desktop editions.
               - 1: B{Normal trust}. Run with the same privileges as a normal
                    user, that is, one that doesn't have the I{Administrator} or
                    I{Power User} user rights. Only available since Windows XP
                    and 2003, desktop editions.
               - 2: B{Full trust}. Run with the exact same privileges as the
                    current user. This is the default value.
  
          @type    bAllowElevation: bool
          @keyword bAllowElevation: C{True} to allow the child process to keep
              UAC elevation, if the debugger itself is running elevated. C{False}
              to ensure the child process doesn't run with elevation. Defaults to
              C{True}.
  
              This flag is only meaningful on Windows Vista and above, and if the
              debugger itself is running with elevation. It can be used to make
              sure the child processes don't run elevated as well.
  
              This flag DOES NOT force an elevation prompt when the debugger is
              not running with elevation.
  
              Note that running the debugger with elevation (or the Python
              interpreter at all for that matter) is not normally required.
              You should only need to if the target program requires elevation
              to work properly (for example if you try to debug an installer).
  
          @rtype:  L{Process}
          @return: Process object.
          """
  
          # Get the flags.
          bConsole            = kwargs.pop('bConsole', False)
          bDebug              = kwargs.pop('bDebug', False)
          bFollow             = kwargs.pop('bFollow', False)
          bSuspended          = kwargs.pop('bSuspended', False)
          bInheritHandles     = kwargs.pop('bInheritHandles', False)
          dwParentProcessId   = kwargs.pop('dwParentProcessId', None)
          iTrustLevel         = kwargs.pop('iTrustLevel', 2)
          bAllowElevation     = kwargs.pop('bAllowElevation', True)
          if kwargs:
              raise TypeError("Unknown keyword arguments: %s" % compat.keys(kwargs))
          if not lpCmdLine:
              raise ValueError("Missing command line to execute!")
  
          # Sanitize the trust level flag.
          if iTrustLevel is None:
              iTrustLevel = 2
  
          # The UAC elevation flag is only meaningful if we're running elevated.
          try:
              bAllowElevation = bAllowElevation or not self.is_admin()
          except AttributeError:
              bAllowElevation = True
              warnings.warn(
                  "UAC elevation is only available in Windows Vista and above",
                  RuntimeWarning)
  
          # Calculate the process creation flags.
          dwCreationFlags  = 0
          dwCreationFlags |= win32.CREATE_DEFAULT_ERROR_MODE
          dwCreationFlags |= win32.CREATE_BREAKAWAY_FROM_JOB
          ##dwCreationFlags |= win32.CREATE_UNICODE_ENVIRONMENT
          if not bConsole:
              dwCreationFlags |= win32.DETACHED_PROCESS
              #dwCreationFlags |= win32.CREATE_NO_WINDOW   # weird stuff happens
          if bSuspended:
              dwCreationFlags |= win32.CREATE_SUSPENDED
          if bDebug:
              dwCreationFlags |= win32.DEBUG_PROCESS
              if not bFollow:
                  dwCreationFlags |= win32.DEBUG_ONLY_THIS_PROCESS
  
          # Change the parent process if requested.
          # May fail on old versions of Windows.
          lpStartupInfo = None
          if dwParentProcessId is not None:
              myPID = win32.GetCurrentProcessId()
              if dwParentProcessId != myPID:
                  if self.has_process(dwParentProcessId):
                      ParentProcess = self.get_process(dwParentProcessId)
                  else:
                      ParentProcess = Process(dwParentProcessId)
                  ParentProcessHandle = ParentProcess.get_handle(
                                          win32.PROCESS_CREATE_PROCESS)
                  AttributeListData = (
                      (
                          win32.PROC_THREAD_ATTRIBUTE_PARENT_PROCESS,
                          ParentProcessHandle._as_parameter_
                      ),
                  )
                  AttributeList = win32.ProcThreadAttributeList(AttributeListData)
                  StartupInfoEx           = win32.STARTUPINFOEX()
                  StartupInfo             = StartupInfoEx.StartupInfo
                  StartupInfo.cb          = win32.sizeof(win32.STARTUPINFOEX)
                  StartupInfo.lpReserved  = 0
                  StartupInfo.lpDesktop   = 0
                  StartupInfo.lpTitle     = 0
                  StartupInfo.dwFlags     = 0
                  StartupInfo.cbReserved2 = 0
                  StartupInfo.lpReserved2 = 0
                  StartupInfoEx.lpAttributeList = AttributeList.value
                  lpStartupInfo = StartupInfoEx
                  dwCreationFlags |= win32.EXTENDED_STARTUPINFO_PRESENT
  
          pi = None
          try:
  
              # Create the process the easy way.
              if iTrustLevel >= 2 and bAllowElevation:
                  pi = win32.CreateProcess(None, lpCmdLine,
                                              bInheritHandles = bInheritHandles,
                                              dwCreationFlags = dwCreationFlags,
                                              lpStartupInfo   = lpStartupInfo)
  
              # Create the process the hard way...
              else:
  
                  # If we allow elevation, use the current process token.
                  # If not, get the token from the current shell process.
                  hToken = None
                  try:
                      if not bAllowElevation:
                          if bFollow:
                              msg = (
                                  "Child processes can't be autofollowed"
                                  " when dropping UAC elevation.")
                              raise NotImplementedError(msg)
                          if bConsole:
                              msg = (
                                  "Child processes can't inherit the debugger's"
                                  " console when dropping UAC elevation.")
                              raise NotImplementedError(msg)
                          if bInheritHandles:
                              msg = (
                                  "Child processes can't inherit the debugger's"
                                  " handles when dropping UAC elevation.")
                              raise NotImplementedError(msg)
                          try:
                              hWnd = self.get_shell_window()
                          except WindowsError:
                              hWnd = self.get_desktop_window()
                          shell = hWnd.get_process()
                          try:
                              hShell = shell.get_handle(
                                              win32.PROCESS_QUERY_INFORMATION)
                              with win32.OpenProcessToken(hShell) as hShellToken:
                                  hToken = win32.DuplicateTokenEx(hShellToken)
                          finally:
                              shell.close_handle()
  
                      # Lower trust level if requested.
                      if iTrustLevel < 2:
                          if iTrustLevel > 0:
                              dwLevelId = win32.SAFER_LEVELID_NORMALUSER
                          else:
                              dwLevelId = win32.SAFER_LEVELID_UNTRUSTED
                          with win32.SaferCreateLevel(dwLevelId = dwLevelId) as hSafer:
                              hSaferToken = win32.SaferComputeTokenFromLevel(
                                                              hSafer, hToken)[0]
                              try:
                                  if hToken is not None:
                                      hToken.close()
                              except:
                                  hSaferToken.close()
                                  raise
                              hToken = hSaferToken
  
                      # If we have a computed token, call CreateProcessAsUser().
                      if bAllowElevation:
                          pi = win32.CreateProcessAsUser(
                                      hToken          = hToken,
                                      lpCommandLine   = lpCmdLine,
                                      bInheritHandles = bInheritHandles,
                                      dwCreationFlags = dwCreationFlags,
                                      lpStartupInfo   = lpStartupInfo)
  
                      # If we have a primary token call CreateProcessWithToken().
                      # The problem is, there are many flags CreateProcess() and
                      # CreateProcessAsUser() accept but CreateProcessWithToken()
                      # and CreateProcessWithLogonW() don't, so we need to work
                      # around them.
                      else:
  
                          # Remove the debug flags.
                          dwCreationFlags &= ~win32.DEBUG_PROCESS
                          dwCreationFlags &= ~win32.DEBUG_ONLY_THIS_PROCESS
  
                          # Remove the console flags.
                          dwCreationFlags &= ~win32.DETACHED_PROCESS
  
                          # The process will be created suspended.
                          dwCreationFlags |= win32.CREATE_SUSPENDED
  
                          # Create the process using the new primary token.
                          pi = win32.CreateProcessWithToken(
                                      hToken          = hToken,
                                      dwLogonFlags    = win32.LOGON_WITH_PROFILE,
                                      lpCommandLine   = lpCmdLine,
                                      dwCreationFlags = dwCreationFlags,
                                      lpStartupInfo   = lpStartupInfo)
  
                          # Attach as a debugger, if requested.
                          if bDebug:
                              win32.DebugActiveProcess(pi.dwProcessId)
  
                          # Resume execution, if requested.
                          if not bSuspended:
                              win32.ResumeThread(pi.hThread)
  
                  # Close the token when we're done with it.
                  finally:
                      if hToken is not None:
                          hToken.close()
  
              # Wrap the new process and thread in Process and Thread objects,
              # and add them to the corresponding snapshots.
              aProcess = Process(pi.dwProcessId, pi.hProcess)
              aThread  = Thread (pi.dwThreadId,  pi.hThread)
              aProcess._add_thread(aThread)
              self._add_process(aProcess)
  
          # Clean up on error.
          except:
              if pi is not None:
                  try:
                      win32.TerminateProcess(pi.hProcess)
                  except WindowsError:
                      pass
                  pi.hThread.close()
                  pi.hProcess.close()
              raise
  
          # Return the new Process object.
          return aProcess
function_tokens: def start_process ( self , lpCmdLine , * * kwargs ) : # Get the flags. bConsole = kwargs . pop ( 'bConsole' , False ) bDebug = kwargs . pop ( 'bDebug' , False ) bFollow = kwargs . pop ( 'bFollow' , False ) bSuspended = kwargs . pop ( 'bSuspended' , False ) bInheritHandles = kwargs . pop ( 'bInheritHandles' , False ) dwParentProcessId = kwargs . pop ( 'dwParentProcessId' , None ) iTrustLevel = kwargs . pop ( 'iTrustLevel' , 2 ) bAllowElevation = kwargs . pop ( 'bAllowElevation' , True ) if kwargs : raise TypeError ( "Unknown keyword arguments: %s" % compat . keys ( kwargs ) ) if not lpCmdLine : raise ValueError ( "Missing command line to execute!" ) # Sanitize the trust level flag. if iTrustLevel is None : iTrustLevel = 2 # The UAC elevation flag is only meaningful if we're running elevated. try : bAllowElevation = bAllowElevation or not self . is_admin ( ) except AttributeError : bAllowElevation = True warnings . warn ( "UAC elevation is only available in Windows Vista and above" , RuntimeWarning ) # Calculate the process creation flags. dwCreationFlags = 0 dwCreationFlags |= win32 . CREATE_DEFAULT_ERROR_MODE dwCreationFlags |= win32 . CREATE_BREAKAWAY_FROM_JOB ##dwCreationFlags |= win32.CREATE_UNICODE_ENVIRONMENT if not bConsole : dwCreationFlags |= win32 . DETACHED_PROCESS #dwCreationFlags |= win32.CREATE_NO_WINDOW   # weird stuff happens if bSuspended : dwCreationFlags |= win32 . CREATE_SUSPENDED if bDebug : dwCreationFlags |= win32 . DEBUG_PROCESS if not bFollow : dwCreationFlags |= win32 . DEBUG_ONLY_THIS_PROCESS # Change the parent process if requested. # May fail on old versions of Windows. lpStartupInfo = None if dwParentProcessId is not None : myPID = win32 . GetCurrentProcessId ( ) if dwParentProcessId != myPID : if self . has_process ( dwParentProcessId ) : ParentProcess = self . get_process ( dwParentProcessId ) else : ParentProcess = Process ( dwParentProcessId ) ParentProcessHandle = ParentProcess . get_handle ( win32 . PROCESS_CREATE_PROCESS ) AttributeListData = ( ( win32 . PROC_THREAD_ATTRIBUTE_PARENT_PROCESS , ParentProcessHandle . _as_parameter_ ) , ) AttributeList = win32 . ProcThreadAttributeList ( AttributeListData ) StartupInfoEx = win32 . STARTUPINFOEX ( ) StartupInfo = StartupInfoEx . StartupInfo StartupInfo . cb = win32 . sizeof ( win32 . STARTUPINFOEX ) StartupInfo . lpReserved = 0 StartupInfo . lpDesktop = 0 StartupInfo . lpTitle = 0 StartupInfo . dwFlags = 0 StartupInfo . cbReserved2 = 0 StartupInfo . lpReserved2 = 0 StartupInfoEx . lpAttributeList = AttributeList . value lpStartupInfo = StartupInfoEx dwCreationFlags |= win32 . EXTENDED_STARTUPINFO_PRESENT pi = None try : # Create the process the easy way. if iTrustLevel >= 2 and bAllowElevation : pi = win32 . CreateProcess ( None , lpCmdLine , bInheritHandles = bInheritHandles , dwCreationFlags = dwCreationFlags , lpStartupInfo = lpStartupInfo ) # Create the process the hard way... else : # If we allow elevation, use the current process token. # If not, get the token from the current shell process. hToken = None try : if not bAllowElevation : if bFollow : msg = ( "Child processes can't be autofollowed" " when dropping UAC elevation." ) raise NotImplementedError ( msg ) if bConsole : msg = ( "Child processes can't inherit the debugger's" " console when dropping UAC elevation." ) raise NotImplementedError ( msg ) if bInheritHandles : msg = ( "Child processes can't inherit the debugger's" " handles when dropping UAC elevation." ) raise NotImplementedError ( msg ) try : hWnd = self . get_shell_window ( ) except WindowsError : hWnd = self . get_desktop_window ( ) shell = hWnd . get_process ( ) try : hShell = shell . get_handle ( win32 . PROCESS_QUERY_INFORMATION ) with win32 . OpenProcessToken ( hShell ) as hShellToken : hToken = win32 . DuplicateTokenEx ( hShellToken ) finally : shell . close_handle ( ) # Lower trust level if requested. if iTrustLevel < 2 : if iTrustLevel > 0 : dwLevelId = win32 . SAFER_LEVELID_NORMALUSER else : dwLevelId = win32 . SAFER_LEVELID_UNTRUSTED with win32 . SaferCreateLevel ( dwLevelId = dwLevelId ) as hSafer : hSaferToken = win32 . SaferComputeTokenFromLevel ( hSafer , hToken ) [ 0 ] try : if hToken is not None : hToken . close ( ) except : hSaferToken . close ( ) raise hToken = hSaferToken # If we have a computed token, call CreateProcessAsUser(). if bAllowElevation : pi = win32 . CreateProcessAsUser ( hToken = hToken , lpCommandLine = lpCmdLine , bInheritHandles = bInheritHandles , dwCreationFlags = dwCreationFlags , lpStartupInfo = lpStartupInfo ) # If we have a primary token call CreateProcessWithToken(). # The problem is, there are many flags CreateProcess() and # CreateProcessAsUser() accept but CreateProcessWithToken() # and CreateProcessWithLogonW() don't, so we need to work # around them. else : # Remove the debug flags. dwCreationFlags &= ~ win32 . DEBUG_PROCESS dwCreationFlags &= ~ win32 . DEBUG_ONLY_THIS_PROCESS # Remove the console flags. dwCreationFlags &= ~ win32 . DETACHED_PROCESS # The process will be created suspended. dwCreationFlags |= win32 . CREATE_SUSPENDED # Create the process using the new primary token. pi = win32 . CreateProcessWithToken ( hToken = hToken , dwLogonFlags = win32 . LOGON_WITH_PROFILE , lpCommandLine = lpCmdLine , dwCreationFlags = dwCreationFlags , lpStartupInfo = lpStartupInfo ) # Attach as a debugger, if requested. if bDebug : win32 . DebugActiveProcess ( pi . dwProcessId ) # Resume execution, if requested. if not bSuspended : win32 . ResumeThread ( pi . hThread ) # Close the token when we're done with it. finally : if hToken is not None : hToken . close ( ) # Wrap the new process and thread in Process and Thread objects, # and add them to the corresponding snapshots. aProcess = Process ( pi . dwProcessId , pi . hProcess ) aThread = Thread ( pi . dwThreadId , pi . hThread ) aProcess . _add_thread ( aThread ) self . _add_process ( aProcess ) # Clean up on error. except : if pi is not None : try : win32 . TerminateProcess ( pi . hProcess ) except WindowsError : pass pi . hThread . close ( ) pi . hProcess . close ( ) raise # Return the new Process object. return aProcess