1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Debug print definitions

    15  *

    16 */

    17 

    18 

    19 

    20 /*

    21 *

    22 *  Description:

    23 *

    24 *     Logging tools. Uniforms style to write debug data to

    25 *     screen using RDebug or to a file with RFileLogger.

    26 *

    27 *     Usage:

    28 *     1.Configuring:

    29 *

    30 *       Logging and debug printing is configured with following macros

    31 *           CHAT_ENABLE_DEBUG_PRINT         (defining this enables debug printing)

    32 *           CHAT_DEBUG_OUTPUT_TO_FILE       (now debug printing goes to file)

    33 *           CHAT_DEBUG_FILENAME "Some.log"  (file to store debug log)

    34 *

    35 *       Debug printing can be configured on project level by defining desired

    36 *       macros in .mmp file like this

    37 *           //enable file logging

    38 *           MACRO CHAT_ENABLE_DEBUG_PRINT

    39 *           MACRO CHAT_DEBUG_OUTPUT_TO_FILE

    40 *

    41 *       You may also automate the debug printing to follow current build

    42 *       variant like this:

    43 *           #ifdef _DEBUG

    44 *           MACRO CHAT_ENABLE_DEBUG_PRINT

    45 *           #endif // _DEBUG

    46 *

    47 *       The file to write debug log needs to be defined in file level.

    48 *       (Defining it in mmp file causes errors to build procedure..)

    49 *           #define CHAT_DEBUG_FILENAME "Example.log"

    50 *

    51 *       When using debug printing to file, flogger.lib needs to be added in

    52 *       mmp file

    53 *           LIBRARY  flogger.lib

    54 *       and following directory must be manually done before loggin

    55 *       (no directory, not logs) Epoc32\Wins\c\logs\CHAT\

    56 *

    57 *

    58 *     2.Printing:

    59 *

    60 *       // normal string                                  output:

    61 *       CHAT_DP( D_CHAT_LIT( "Some text." ) );                >> CHAT: Some text.

    62 *       CHAT_DP( D_PLAIN_LIT( "Some text." ) );               >> Some text.

    63 *       CHAT_DP_TXT( "Some text." );                          >> CHAT: Some text.

    64 *

    65 *       // string with variables

    66 *       TInt index( 99 );

    67 *       _LIT( KExample, "Example" );

    68 *       CHAT_DP( D_CHAT_LIT( "Some text: %d" ), 100 );        >> CHAT: Some text: 100

    69 *       CHAT_DP( D_CHAT_LIT( "Some text: %d" ), index );      >> CHAT: Some text: 99

    70 *       CHAT_DP( D_CHAT_LIT( "Some text: %S" ), &KExample );  >> CHAT: Some text: Example

    71 *

    72 *       CHAT_DP( D_PLAIN_LIT( "Some text: %d" ), 100 );       >> Some text: 100

    73 *       CHAT_DP( D_PLAIN_LIT( "Some text: %d" ), index );     >> Some text: 99

    74 *       CHAT_DP( D_PLAIN_LIT( "Some text: %S" ), &KExample ); >> Some text: Example

    75 *

    76 *

    77 *     3.Known issues:

    78 *

    79 *       - If you use macros from .mmp file remember to abld makefile <target> to

    80 *         change flags from project.

    81 *       - In statements like CHAT_DP( D_CHAT_LIT("Some text: %S"), &KExample );

    82 *         parameters causes still some code to generated in release builds.

    83 *         Propably it is best to #ifdef all debugprint blocks

    84 *         with CHAT_ENABLE_DEBUG_PRINT statement.

    85 *

    86 * ============================================================================

    87 */

    88 

    89 

    90 #ifndef __CHATDEBUGPRINT_H__

    91 #define __CHATDEBUGPRINT_H__

    92 

    93 // Debug logging is enabled, you may enable debug printing in release builds also

    94 #ifdef CHAT_ENABLE_DEBUG_PRINT

    95 

    96 // no include files if no debug printing --> faster compile time

    97 // INCLUDES

    98 #include <e32std.h>

    99 #include <e32svr.h>

   100 #include <flogger.h>

   101 

   102 #ifndef _DEBUG

   103 // warn in release build

   104 #if defined( __VC32__ )

   105 #pragma message( "Warning: CHAT debug printing is on in release build!" ) // CSI: 68 # Warning for rel builds

   106 #else // __GCC32__

   107 #warning "CHAT debug printing is on in release build!"

   108 #endif // __VC32__

   109 #endif

   110 

   111 /**

   112  * Depending if the build is UNICODE or not, define the

   113  * helper macros that insert CHAT prefix.

   114  */

   115 #ifdef _UNICODE

   116 #define CHAT_TOKEN_PASTING( s ) L##s

   117 #define CHAT_TO_UNICODE( s ) CHAT_TOKEN_PASTING( s )

   118 #define CHAT_DEBUG_STR( m ) CHAT_TO_UNICODE( "CHAT: " ) L##m

   119 #else

   120 #define CHAT_DEBUG_STR "CHAT: "

   121 #endif // _UNICODE

   122 

   123 

   124 /**

   125  * Helper macro for defining debug strings with plain debug text.

   126  */

   127 #define D_PLAIN_LIT( s ) _L( s )    // CSI: 78 # Debug print

   128 

   129 

   130 /**

   131  * Helper macro for defining debug strings with "CHAT:" prefix.

   132  */

   133 #define D_CHAT_LIT( s ) TPtrC( ( const TText * ) CHAT_DEBUG_STR( s ) )

   134 

   135 

   136 

   137 #ifdef CHAT_DEBUG_OUTPUT_TO_FILE

   138 

   139 /**

   140  * Method to handle file writing

   141  */

   142 inline void CHATDebugWriteFormat( TRefByValue<const TDesC> aFmt, ... )

   143     {

   144     _LIT( KDir, "Chat" );

   145 #ifdef CHAT_DEBUG_FILENAME

   146     const static TLitC < sizeof( CHAT_DEBUG_FILENAME ) > KName = {

   147         sizeof( CHAT_DEBUG_FILENAME ) - 1,

   148         CHAT_TO_UNICODE( CHAT_DEBUG_FILENAME )

   149         };

   150 #else

   151     _LIT( KName, "ChatDebug.log" );

   152 #endif // CHAT_DEBUG_FILENAME

   153 

   154     // take the ellipsis parameters

   155     VA_LIST args;

   156     VA_START( args, aFmt );

   157     RFileLogger::WriteFormat( KDir, KName, EFileLoggingModeAppend,

   158                               aFmt, args );

   159     VA_END( args );

   160     }

   161 

   162 /**

   163  * Actual debug printters.

   164  * Output to log file.

   165  */

   166 #define CHAT_DP CHATDebugWriteFormat

   167 #define CHAT_DP_TXT( s ) CHATDebugWriteFormat( D_CHAT_LIT( s ) )

   168 

   169 

   170 

   171 #else

   172 /**

   173  * Actual debug printters.

   174  * Output to debugger output.

   175  */

   176 #define CHAT_DP RDebug::Print

   177 #define CHAT_DP_TXT( s ) RDebug::Print( D_CHAT_LIT( s ) )

   178 #endif

   179 

   180 

   181 #else   //CHAT_ENABLE_DEBUG_PRINT

   182 

   183 /**

   184  *

   185  * Empty implementations for non-debug printing build versions.

   186  *

   187  */

   188 

   189 /**

   190  * Dummy struct for checking that all CHAT_DP's define string

   191  * literals using space-saving D_PLAIN_LIT or D_CHAT_LIT.

   192  */

   193 struct TCHATEmptyDebugString { };

   194 

   195 /**

   196  * Macro for defining debug-only literal strings (empty release version)

   197  */

   198 #define D_PLAIN_LIT( s ) TCHATEmptyDebugString()

   199 

   200 /**

   201  * Macro for defining debug-only literal strings (empty release version)

   202  */

   203 #define D_CHAT_LIT( s ) TCHATEmptyDebugString()

   204 

   205 /**

   206  * Macro for empty debug print function

   207  */

   208 #define CHAT_DP_TXT( s ) CHAT_DP( D_CHAT_LIT( s ) )

   209 

   210 

   211 /// Empty debug print function for release builds.

   212 inline void CHAT_DP( TCHATEmptyDebugString )

   213     {

   214     }

   215 

   216 template< class T1 >

   217 inline void CHAT_DP( TCHATEmptyDebugString, T1 )

   218     {

   219     }

   220 

   221 template< class T1, class T2 >

   222 inline void CHAT_DP( TCHATEmptyDebugString, T1, T2 )

   223     {

   224     }

   225 

   226 template< class T1, class T2, class T3 >

   227 inline void CHAT_DP( TCHATEmptyDebugString, T1, T2, T3 )

   228     {

   229     }

   230 

   231 template< class T1, class T2, class T3, class T4 >

   232 inline void CHAT_DP( TCHATEmptyDebugString, T1, T2, T3, T4 )

   233     {

   234     }

   235 

   236 template< class T1, class T2, class T3, class T4, class T5 >

   237 inline void CHAT_DP( TCHATEmptyDebugString, T1, T2, T3, T4, T5 )

   238     {

   239     }

   240 

   241 template< class T1, class T2, class T3, class T4, class T5, class T6 >

   242 inline void CHAT_DP( TCHATEmptyDebugString, T1, T2, T3, T4, T5, T6 )

   243     {

   244     }

   245 

   246 template < class T1, class T2, class T3, class T4, class T5, class T6,

   247 class T7 >

   248 inline void CHAT_DP( TCHATEmptyDebugString, T1, T2, T3, T4, T5, T6, T7 )

   249     {

   250     }

   251 

   252 template < class T1, class T2, class T3, class T4, class T5, class T6,

   253 class T7, class T8 >

   254 inline void CHAT_DP( TCHATEmptyDebugString, T1, T2, T3, T4, T5, T6, T7, T8 )

   255     {

   256     }

   257 

   258 template < class T1, class T2, class T3, class T4, class T5, class T6,

   259 class T7, class T8, class T9 >

   260 inline void CHAT_DP( TCHATEmptyDebugString, T1, T2, T3, T4, T5, T6, T7, T8,

   261                      T9 )

   262     {

   263     }

   264 

   265 template < class T1, class T2, class T3, class T4, class T5, class T6,

   266 class T7, class T8, class T9, class T10 >

   267 inline void CHAT_DP( TCHATEmptyDebugString, T1, T2, T3, T4, T5, T6, T7, T8,

   268                      T9, T10 )

   269     {

   270     }

   271 

   272 template < class T1, class T2, class T3, class T4, class T5, class T6,

   273 class T7, class T8, class T9, class T10, class T11 >

   274 inline void CHAT_DP( TCHATEmptyDebugString, T1, T2, T3, T4, T5, T6, T7, T8,

   275                      T9, T10, T11 )

   276     {

   277     }

   278 

   279 #endif  // CHAT_ENABLE_DEBUG_PRINT

   280 

   281 /* Some general wrappers to CHAT_DP for convenience.

   282  *

   283  * Since these just wrap CHAT_DP, they work transparently: the macros write

   284  * stuff to debug output or to a file, whichever you are using,

   285  * you don't have to care.

   286  *

   287  * Since CHAT_DP is either defined or empty inline, these won't

   288  * matter in either build (no, there is no noticeable penalty in compile time)

   289  *

   290  * There are three types of wrappers, output format is

   291  *

   292  * "filename:linenumber method - enter" when entering function

   293  * "filename:linenumber method - message" when inside function

   294  * "filename:linenumber method - done" when exiting function

   295  *

   296  * Example:

   297  * TInt CSomeClass::SomeMethod()

   298  * {

   299  *      CHAT_DP_FUNC_ENTER( "SomeMethod" );

   300  *

   301  *      TInt i = 41;

   302  *

   303  *      CHAT_DP_FUNC_DP( "SomeMethod", "Doing intensive calculations" );

   304  *

   305  *      i++;

   306  *

   307  *      CHAT_DP_FUNC_DONE( "SomeMethod" );

   308  *  }

   309  *

   310  * You have to provide the method name yourself since the __FUNCTION__

   311  * preprocessor macro is not understood.

   312  */

   313 

   314 #include "ChatDebugMacros.h" 	// WFILE etc.

   315 

   316 // when entering a function

   317 #define CHAT_DP_FUNC_ENTER( method ) \

   318     CHAT_DP( D_CHAT_LIT("%s:%d %s - enter" ), __WFILE__, __LINE__, L ## method );

   319 

   320 // debug print

   321 #define CHAT_DP_FUNC_DP( method,msg ) \

   322     CHAT_DP( D_CHAT_LIT( "%s:%d %s - %s" ), __WFILE__, __LINE__, L ## method, L ## msg );

   323 

   324 // when exiting a function

   325 #define CHAT_DP_FUNC_DONE(method) \

   326     CHAT_DP( D_CHAT_LIT( "%s:%d %s - done" ), __WFILE__, __LINE__, L ## method );

   327 

   328 #endif  // __CHATDEBUGPRINT_H__

   329 

   330 

   331 //  End of File