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.

Name	Description
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

Assert Macros and Functions

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.

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.

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.

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.

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.

KASSERT(
  cond
  );

Parameters

cond

Condition (a Boolean expression).

Remarks

This macro is ignored unless DEBUG is defined when the Microsoft DirectShow headers are included.

Unlike ASSERT and EXECUTE_ASSERT, if you use this macro in a debug build no message box will appear.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page