ATLTRACE2( DWORD category, UINT level, LPCSTR lpszFormat, ... )
Parameters
category
[in] The atlTraceFlags to indicate the type of event or method on which to report. See Remarks for a list of categories.
level
[in] The level of tracing to report. Must be less than or equal to the value you set for ATL_TRACE_LEVEL to appear. For example, if you set level to 4 and ATL_TRACE_LEVEL to 0, you will see no warnings. See Remarks for more information about ATL_TRACE_LEVEL.
lpszFormat
[in] The formatted string to send to the dump device.
Remarks
Use ATLTRACE2 for debugging purposes. ATLTRACE2 provides messages about how events and methods happen. ATLTRACE2 reports warnings and errors that occur as you debug the program. ATLTRACE2 sends a formatted string, lpszFormat, to a dump device, usually the debugger output window or a file.
The first parameter for ATLTRACE2, category, lists the trace flags to set. These flags correspond to the types of methods for which you want to report. The table below lists the valid trace flags you can use for the category parameter.
| Category | Description |
| atlTraceUser | Application-defined. The value indicates the level of warnings to report. |
| atlTraceGeneral | Reports on all ATL applications. The default. |
| atlTraceCOM | Reports on COM methods. |
| atlTraceQI | Reports on QueryInterface calls. |
| atlTraceRegistrar | Reports on the registration of objects. |
| atlTraceRefcount | Reports on changing reference count. |
| atlTraceWindowing | Reports on windows methods, for example reports an invalid message map ID. |
| atlTraceControls | Reports on controls, for example reports when a control or its window is destroyed. |
| atlTraceHosting | Reports hosting messages, for example, when a client in a container is activated. |
| atlTraceDBClient | Reports on OLE DB Consumer Template; for example when a call to GetData fails, the output can contain the HRESULT. |
| atlTraceDBProvider | Reports on OLE DB Provider Template, for example reports if the creation of a column failed. |
| atlTraceSnapin | Reports for MMC SnapIn application. |
| atlTraceNotImpl | Reports that the indicated function is not implemented. |
Example
// example for ATLTRACE2
int i = 1;
ATLTRACE2( atlTraceGeneral, 4, "Integer = %d\n", i );
// Output: 'Integer = 1'
You can filter for specific categories and levels at the project level by setting the two global functions described below. To specify such filtering in the preprocessor definitions, insert the global functions into Stdafx.h before the #include <atlbase.h> statement.
Alternately, you can set the filter in the preprocessor directives in the Project Settings dialog box. Click the C/C++ tab, and then insert the global into the Preprocessor definitions edit box.
To set the categories and levels, use the following global functions:
ATL_TRACE_CATEGORY 0xFFFFFFFF
Sets the trace category for which to filter. The default, 0xFFFFFFFF reports all categories. To filter for a specific category or set of categories, replace 0xFFFFFFFF with the category names you want to trace. You can use the bitwise OR (|) operator to filter for more than one category. For example, by setting ATL_TRACE_CATEGORY (atlTraceControls | atlTraceWindowing), you will see only ATLTRACE2 warnings for controls and windowing.
ATL_TRACE_LEVEL 0
Sets the trace level for which to filter. Can be 0, 1, 2, 3, or 4. The default, 0, reports only the most serious problems. Replace 0 with the level of reporting you want to see. For example, by specifying 4, you will see all levels of warnings and informational messages.
ATL Macros and Global Functions
See Also