Share via


IDebugStackFrame3::InterceptCurrentException

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

Called by the debugger on the current stack frame when it wants to intercept the current exception.

Syntax

HRESULT InterceptCurrentException(
   INTERCEPT_EXCEPTION_ACTION dwFlags,
   UINT64*                    pqwCookie
);
int InterceptCurrentException(
   uint dwFlags,
   out  ulong pqwCookie
);

Parameters

dwFlags
[in] Specifies different actions. Currently, only the INTERCEPT_EXCEPTION_ACTION value IEA_INTERCEPT is supported and must be specified.

pqwCookie
[out] Unique value identifying a particular exception.

Return Value

If successful, returns S_OK; otherwise, returns an error code.

The following are the most common error returns.

Error Description
E_EXCEPTION_CANNOT_BE_INTERCEPTED The current exception cannot be intercepted.
E_EXCEPTION_CANNOT_UNWIND_ABOVE_CALLBACK The current execution frame hasn't been searched for a handler yet.
E_INTERCEPT_CURRENT_EXCEPTION_NOT_SUPPORTED This method is not supported for this frame.

Remarks

When an exception is thrown, the debugger gains control from the run time at key points during the exception handling process. During these key moments, the debugger can ask the current stack frame if the frame wants to intercept the exception. In this way, an intercepted exception is essentially an on-the-fly exception handler for a stack frame, even if that stack frame doesn't have an exception handler (for example, a try/catch block in the program code).

When the debugger wants to know if the exception should be intercepted, it calls this method on the current stack frame object. This method is responsible for handling all details of the exception. If the IDebugStackFrame3 interface is not implemented or the InterceptStackException method returns any error, then the debugger continues processing the exception normally.

Note

Exceptions can be intercepted only in managed code, that is, when the program being debugged is running under the .NET run time. Of course, third-party language implementers can implement InterceptStackException in their own debug engines if they so choose.

After the interception is complete, an IDebugInterceptExceptionCompleteEvent2 is signaled.

See also