Pre-Conditions for CorDebug.idl Interfaces

Article
03/30/2009

Some methods in the debugging interfaces require the process that is being debugged (that is, the debuggee) to be in a certain state, as a pre-condition. The pre-condition applies only to the direct member methods of interfaces that are declared in the CorDebug.idl file. (That is, they apply only to methods that are not inherited from IUnknown.)

State of the Debuggee

The debuggee has six high-level states, which are described in the following sections. Only three of these states (live, synchronized, and operating-system frozen) are valid.

Live

A valid state in which the debuggee is running. This is the state between debug events.

Synchronized

A valid state in which the debuggee is stopped and all managed states are suspended. The debuggee gets into this state in one of two ways:

During the interval between the dispatch and continuation of a managed debug event. This is the period after a managed (or an in-band, native) debug event is dispatched, but before the event is continued.
After calling the ICorDebugController::Stop Method method.

Operating-System Frozen

A valid state in which the debuggee is stopped at an out-of-band, native debugging event. This state is relevant only for interop debugging.

Not Yet Initialized

An invalid state in which the debuggee has not been initialized. This state exists during the period after the debuggee is created and before the ICorDebugManagedCallback::CreateProcess Method callback is dispatched. If a method that was defined in CorDebug.idl is called during this state, it may return an HRESULT value of CORDBG_E_NOTREADY.

Dead or Deactivated

An invalid state in which the debuggee is no longer available for debugging. If a method that was defined in CorDebug.idl is called during this state, it may return one of several HRESULT values, including CORDBG_E_PROCESS_DETACHED and CORDBG_E_PROCESS_TERMINATED.

Unrecoverable Error

An invalid state that the debuggee enters when the ICorDebugManagedCallback::DebuggerError Method callback is dispatched. This means that the managed debugging services have become significantly corrupted and unusable. If a method that was defined in CorDebug.idl is called during this state, it may return an HRESULT value of CORDBG_E_UNRECOVERABLE_ERROR.

States Required Before Calling Methods

The member methods of the ICorDebug Interface interface have no state-specific restrictions beyond their declarations because they do not live directly on a process object. Member methods of all other interfaces have some process-specific affinity. Therefore, these methods require the debuggee process to be in one of three states when they are called: live, synchronized, or operating-system frozen.

The following methods can be called when the debuggee is in the live state:

The following methods can be called when the debuggee is either in the operating-system frozen or the synchronized state:

All other methods should be called only when the debuggee is in the synchronized state. Otherwise, they may return an HRESULT value of CORDBG_E_PROCESS_NOT_SYNCHRONIZED.