Assert Macros and Functions

The Microsoft® DirectShow® SDK has three assertion macros: ASSERT, EXECUTE_ASSERT, and KASSERT. The most commonly used assertion macro is ASSERT. If ASSERT fails, DirectShow displays a message box that lists the file and line number of the macro call. The EXECUTE_ASSERT macro is similar to ASSERT except that the condition will still be evaluated in a build of any kind. The third assertion macro is KASSERT, which is more suitable for pure filters, such as those in the kernel, where the condition is printed onto the debugger rather than to a message box.

There are also two assertion functions: DbgAssert and DbgKernelAssert. You should call the assertion functions from assertion macros, rather than from normal code.

ASSERT Checks an assertion in a debug build.
DbgAssert Handles an assertion failure in a debug build.
DbgKernelAssert Handles a kernel assertion failure in a debug build.
EXECUTE_ASSERT Always evaluates a condition; if it is not TRUE in a debug build, treat this as an assertion failure.
KASSERT Checks a kernel assertion in a debug build.

ASSERT

Evaluates the given condition in a debug build. If the resulting evaluation is false, then ASSERT calls DbgAssert to handle the assertion failure. DbgAssert can return to its caller later, if the user so desires.

Syntax

ASSERT(
  cond
  );

Parameters

cond
Boolean expression that defines the condition to evaluate.

Remarks

If you use the ASSERT macro, DbgAssert might display a message box. If this is not acceptable in your environment, you can use KASSERT (kernel assert) instead.
Here are two examples of ASSERT calls:
ASSERT( First != NULL);
ASSERT( StartTime <= EndTime);

DbgAssert

Assert Macros and Functions

Handles an assertion failure in a debug build. DbgAssert will display a message box that includes the condition text, source file name, and source line number. The user will be given the choice to ignore the assertion failure, debug the assertion, or force the application to exit. Thus DbgAssert might return to the caller, depending on the user's actions.

Syntax

void WINAPI DbgAssert(
  const TCHAR *pCondition,
  const TCHAR *pFileName,
  INT iLine
  );

Parameters

pCondition
Pointer to a string version of a Boolean expression.
pFileName
Pointer to a source file name.
iLine
Line number within the source file.

Remarks

This function is available only in a debug build. Usually, DbgAssert will be called by macros such as ASSERT, not directly from other code.
If you use the ASSERT macro, DbgAssert might display a message box. If this is not acceptable in your environment, you can use DbgKernelAssert instead.

DbgKernelAssert

Assert Macros and Functions

Called in a debug build to print the condition onto the kernel debugger, including the condition text, source file name, and source line number.

Syntax

void WINAPI DbgKernelAssert(
  const TCHAR *pCondition,
  const TCHAR *pFileName,
  INT iLine
  );

Parameters

pCondition
Pointer to a string version of a Boolean expression.
pFileName
Pointer to a source file name.
iLine
Line number within the source file.

Remarks

This function is available only in a debug build. Usually, DbgKernelAssert is called by macros such as KASSERT, not directly from other code.
Unlike DbgAssert, when macros call DbgKernelAssert in a debug build, no message box appears.

EXECUTE_ASSERT

Assert Macros and Functions

Evaluates the condition. In a debug build, if the resulting value is not TRUE, then the EXECUTE_ASSERT macro will invoke DbgAssert to handle the assertion failure. DbgAssert might return to the caller, depending on the user's actions.

Syntax

EXECUTE_ASSERT(
  cond
  );

Parameters

cond
Condition (a Boolean expression), which is always evaluated. This contrasts with ASSERT and many other traditional assertion macros, which do not evaluate the condition in nondebug builds.

Remarks

If you use the EXECUTE_ASSERT macro in a debug build, DbgAssert might display a message box. If this is not acceptable in your environment, you can use KASSERT (kernel assert) instead.

KASSERT

Assert Macros and Functions

In a debug build, if the condition evaluates to FALSE, the KASSERT macro prints the condition on the kernel debugger, including the file name and line number.

Syntax

KASSERT(
  cond
  );

Parameters

cond
Condition (a Boolean expression).

Remarks

This macro is ignored unless DEBUG is defined when the DirectShow headers are included.
Unlike ASSERT and EXECUTE_ASSERT, if you use this macro in a debug build no message box will appear.

ASSERT	Checks an assertion in a debug build.
DbgAssert	Handles an assertion failure in a debug build.
DbgKernelAssert	Handles a kernel assertion failure in a debug build.
EXECUTE_ASSERT	Always evaluates a condition; if it is not TRUE in a debug build, treat this as an assertion failure.
KASSERT	Checks a kernel assertion in a debug build.