1 /*

     2 * Copyright (c) 2004 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:  Logging tools. Uniforms style to write debug data.

    15 *

    16 */

    17 

    18 

    19 /**

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

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

    22 *

    23 *     Usage:

    24 *     1.Configuring:

    25 *

    26 *       Logging and debug printing is configured with following macros

    27 *           IMPSCUI_ENABLE_DEBUG_PRINT         (defining this enables debug printing)

    28 *           IMPSCUI_DEBUG_OUTPUT_TO_FILE       (debug printing goes to file)

    29 *

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

    31 *       macros in .mmp file like this

    32 *           //enable file logging

    33 *           MACRO IMPSCUI_ENABLE_DEBUG_PRINT

    34 *           MACRO IMPSCUI_DEBUG_OUTPUT_TO_FILE

    35 *

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

    37 *       variant like this:

    38 *           #ifdef _DEBUG

    39 *           MACRO IMPSCUI_ENABLE_DEBUG_PRINT

    40 *           #endif // _DEBUG

    41 *

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

    43 *       mmp file

    44 *           LIBRARY  flogger.lib

    45 *       and following directory must be manually done before loggin

    46 *       (no directory, no logs)  Epoc32\Wins\c\logs\IMPSCUI\

    47 *

    48 *

    49 *     2.Printing:

    50 *       // normal string                                    output:

    51 *       IMPSCUI_DP( D_IMPSCUI_LIT( "Some text." ) );        >> IMPSCUI: Some text.

    52 *       IMPSCUI_DP_TXT( "Some text.");                      >> IMPSCUI: Some text.

    53 *

    54 *       // string with variables

    55 *       TInt index( 99 );

    56 *       _LIT( KExample, "Example" );

    57 *       IMPSCUI_DP( D_IMPSCUI_LIT( "Some text: %d" ), 100 );         >> IMPSCUI: Some text: 100

    58 *       IMPSCUI_DP( D_IMPSCUI_LIT( "Some text: %d" ), index );       >> IMPSCUI: Some text: 99

    59 *       IMPSCUI_DP( D_IMPSCUI_LIT( "Some text: %S" ), &KExample );   >> IMPSCUI: Some text: Example

    60 *

    61 */

    62 #ifndef __IMPSCUIDEBUGPRINT_H__

    63 #define __IMPSCUIDEBUGPRINT_H__

    64 #include "IMPSCommonUiProjectDefinitionMacros.h"

    65 

    66 

    67 // Define macro below to enable the thread name in debug prints

    68 #define IMPSCUI_DEBUG_STR_USE_THREAD_NAME

    69 

    70 

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

    72 #ifdef IMPSCUI_ENABLE_DEBUG_PRINT

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

    74 // INCLUDES

    75 #include <e32std.h>

    76 #include <e32svr.h>

    77 #include <flogger.h>

    78 

    79 #ifndef _DEBUG

    80 // warn in release build!!

    81 #if defined(__VC32__)

    82 // Code scanner warning use of #pragma message (Id: 68) ignored

    83 // because we want this message if debug printing is on in release build

    84 #pragma message( "Warning: IMPSCommonUi Debug Printing is _ON_ in release build!" ) // CSI: 68 # See above

    85 #else // __GCC32__

    86 #warning "IMPSCommonUi Debug Printing is _ON_ in release build!"

    87 #endif // __VC32__

    88 #endif

    89 

    90 /**

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

    92  * helper macros that insert IMPSCUI prefix.

    93  */

    94 #ifdef _UNICODE

    95 #define IMPSCUI_TOKEN_PASTING(s) L##s

    96 #define IMPSCUI_TO_UNICODE(s) IMPSCUI_TOKEN_PASTING(s)

    97 #define IMPSCUI_DEBUG_STR(m) IMPSCUI_TO_UNICODE("IMPSCUI: ") L##m

    98 #else

    99 #define IMPSCUI_DEBUG_STR "IMPSCUI: "

   100 #endif // _UNICODE

   101 

   102 

   103 #ifdef IMPSCUI_DEBUG_STR_USE_THREAD_NAME

   104 /**

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

   106  * When we use thread name, we don't need "IMPSCUI:" prefix

   107  */

   108 #define D_IMPSCUI_LIT(s) _L(s) // CSI: 78 # We need to use _L here

   109 #else

   110 /**

   111  * Helper macro for defining debug strings with "IMPSCUI:" prefix.

   112  */

   113 #define D_IMPSCUI_LIT(s) TPtrC((const TText *) IMPSCUI_DEBUG_STR(s))

   114 #endif // IMPSCUI_DEBUG_STR_USE_THREAD_NAME

   115 

   116 

   117 

   118 /***************************************************************************

   119  * Debug prints to file

   120  ***************************************************************************/

   121 #ifdef IMPSCUI_DEBUG_OUTPUT_TO_FILE

   122 /**

   123  * Method to handle file writing

   124  */

   125 _LIT( KIMPSCUIDebugOutputDir, "IMPSCUI" );

   126 _LIT( KIMPSCUIDebugOutputFileName, "IMPSCUI.log" );

   127 inline void IMPSCUIDebugWriteFormat( TRefByValue<const TDesC> aFmt, ... )

   128     {

   129     //Use RFileLogger to write log - no time and date

   130     RFileLogger logger;

   131     logger.Connect();

   132     //use date, use time

   133     logger.SetDateAndTime( EFalse, ETrue );

   134     logger.CreateLog( KIMPSCUIDebugOutputDir,

   135                       KIMPSCUIDebugOutputFileName,

   136                       EFileLoggingModeAppend );

   137 

   138     TBuf< 256 > buffer;

   139 #ifdef IMPSCUI_DEBUG_STR_USE_THREAD_NAME

   140         {

   141         buffer.Append( _L( "[" ) ); // CSI: 78 # We need to use _L here

   142         buffer.Append( RThread().Name() );

   143         buffer.Append( _L( "] " ) ); // CSI: 78 # We need to use _L here

   144         }

   145 #endif // IMPSCUI_DEBUG_STR_USE_THREAD_NAME

   146 

   147         {

   148         VA_LIST list;

   149         VA_START ( list, aFmt );

   150         TBuf< 300 > formatted;

   151         formatted.FormatList( aFmt, list );

   152         buffer.Append( formatted.Left( buffer.MaxLength() - buffer.Length() ) );

   153         }

   154 

   155     logger.Write( buffer );

   156     logger.CloseLog();

   157     logger.Close();

   158     }

   159 

   160 /**

   161  * Actual debug printters.

   162  * Output to log file.

   163  */

   164 #define IMPSCUI_DP IMPSCUIDebugWriteFormat

   165 #define IMPSCUI_DP_TXT(s) IMPSCUIDebugWriteFormat( D_IMPSCUI_LIT(s) )

   166 

   167 

   168 

   169 

   170 /***************************************************************************

   171  * Debug prints to debug output

   172  ***************************************************************************/

   173 #else

   174 inline void IMPSCUIDebugWriteFormat( TRefByValue<const TDesC> aFmt, ... )

   175     {

   176     TBuf< 256 > buffer;

   177 #ifdef IMPSCUI_DEBUG_STR_USE_THREAD_NAME

   178         {

   179         buffer.Append( _L( "[" ) ); // CSI: 78 # We need to use _L here

   180         buffer.Append( RThread().Name() );

   181         buffer.Append( _L( "] " ) ); // CSI: 78 # We need to use _L here

   182         }

   183 #endif // IMPSCUI_DEBUG_STR_USE_THREAD_NAME

   184 

   185         {

   186         VA_LIST list;

   187         VA_START ( list, aFmt );

   188         TBuf< 300 > formatted;

   189         formatted.FormatList( aFmt, list );

   190         buffer.Append( formatted.Left( buffer.MaxLength() - buffer.Length() ) );

   191         }

   192     //prevent crashing if buffer has format directives

   193     RDebug::Print( _L( "%S" ), &buffer );

   194     }

   195 

   196 /**

   197  * Actual debug printters.

   198  * Output to debugger output.

   199  */

   200 #define IMPSCUI_DP IMPSCUIDebugWriteFormat

   201 #define IMPSCUI_DP_TXT(s) IMPSCUIDebugWriteFormat( D_IMPSCUI_LIT(s) )

   202 #endif

   203 

   204 

   205 

   206 #else   //IMPSCUI_ENABLE_DEBUG_PRINT

   207 

   208 /**

   209  *

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

   211  *

   212  */

   213 

   214 /**

   215  * Dummy struct for checking that all IMPSCUI_DP's define string

   216  * literals using space-saving D_IMPSCUI_LIT.

   217  */

   218 struct TIMPSCUIEmptyDebugString { };

   219 

   220 /**

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

   222  */

   223 #define D_IMPSCUI_LIT(s) TIMPSCUIEmptyDebugString()

   224 

   225 /**

   226  * Macro for empty debug print function

   227  */

   228 #define IMPSCUI_DP_TXT(s) IMPSCUI_DP( D_IMPSCUI_LIT(s) )

   229 

   230 

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

   232 inline void IMPSCUI_DP( TIMPSCUIEmptyDebugString )

   233     {

   234     }

   235 

   236 template<class T1>

   237 inline void IMPSCUI_DP( TIMPSCUIEmptyDebugString, T1 )

   238     {

   239     }

   240 

   241 template<class T1, class T2>

   242 inline void IMPSCUI_DP( TIMPSCUIEmptyDebugString, T1, T2 )

   243     {

   244     }

   245 

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

   247 inline void IMPSCUI_DP( TIMPSCUIEmptyDebugString, T1, T2, T3 )

   248     {

   249     }

   250 

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

   252 inline void IMPSCUI_DP( TIMPSCUIEmptyDebugString, T1, T2, T3, T4 )

   253     {

   254     }

   255 

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

   257 inline void IMPSCUI_DP( TIMPSCUIEmptyDebugString, T1, T2, T3, T4, T5 )

   258     {

   259     }

   260 

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

   262 inline void IMPSCUI_DP( TIMPSCUIEmptyDebugString, T1, T2, T3, T4, T5, T6 )

   263     {

   264     }

   265 

   266 template<class T1, class T2, class T3, class T4, class T5, class T6, class T7>

   267 inline void IMPSCUI_DP( TIMPSCUIEmptyDebugString, T1, T2, T3, T4, T5, T6, T7 )

   268     {

   269     }

   270 

   271 template<class T1, class T2, class T3, class T4, class T5, class T6, class T7, class T8>

   272 inline void IMPSCUI_DP( TIMPSCUIEmptyDebugString, T1, T2, T3, T4, T5, T6, T7, T8 )

   273     {

   274     }

   275 

   276 

   277 #endif  // IMPSCUI_ENABLE_DEBUG_PRINT

   278 

   279 /* Some general wrappers to IMPSCUI_DP for convenience.

   280  *

   281  * Since these just wrap IMPSCUI_DP, they work transparently: the macros write

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

   283  * you don't have to care.

   284  *

   285  * Since IMPSCUI_DP is either defined or empty inline, these won't

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

   287  *

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

   289  *

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

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

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

   293  *

   294  * Example:

   295  * TInt CSomeClass::SomeMethod()

   296  * {

   297  *      IMPSCUI_DP_FUNC_ENTER("SomeMethod");

   298  *

   299  *      TInt i = 41;

   300  *

   301  *      IMPSCUI_DP_FUNC_DP("SomeMethod", "Doing intensive calculations");

   302  *

   303  *      i++;

   304  *

   305  *      IMPSCUI_DP_FUNC_DONE("SomeMethod");

   306  *  }

   307  *

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

   309  * preprocessor macro is not understood.

   310  */

   311 

   312 // workaround 8-bit string to 16-bit unicode

   313 #define WIDEN2(x) L ## x

   314 #define WIDEN(x) WIDEN2(x)

   315 #define __WFILE__ WIDEN(__FILE__)

   316 

   317 // when entering a function

   318 #define IMPSCUI_DP_FUNC_ENTER(method) \

   319     IMPSCUI_DP( D_IMPSCUI_LIT("%s:%d %s - enter"), __WFILE__, __LINE__, L ## method );

   320 

   321 // debug print

   322 #define IMPSCUI_DP_FUNC_DP(method,msg) \

   323     IMPSCUI_DP( D_IMPSCUI_LIT("%s:%d %s - %s"), __WFILE__, __LINE__, L ## method, L ## msg );

   324 

   325 // when exiting a function

   326 #define IMPSCUI_DP_FUNC_DONE(method) \

   327     IMPSCUI_DP( D_IMPSCUI_LIT("%s:%d %s - done"), __WFILE__, __LINE__, L ## method );

   328 

   329 #endif  // __IMPSCUIDEBUGPRINT_H__

   330 

   331 //  End of File