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:   Abstract Trace interface definition

    15 *

    16 */

    17 

    18  

    19 

    20 #ifndef M_ALFTRACEINTERFACE_H

    21 #define M_ALFTRACEINTERFACE_H

    22 

    23 #include <e32base.h>

    24 

    25 /**

    26  * Trace categories

    27  */

    28 enum TAlfTraceCategory

    29     {

    30 

    31     /*

    32     * Report categories those do not belong to any other category

    33     */

    34     EAlfTraceCategoryGeneral                = 0x00000001,

    35 

    36     /*

    37     * Report object life change time events

    38     */

    39     EAlfTraceCategoryObjectLifeTime         = 0x00000002,

    40 

    41     /*

    42     * Events

    43     */

    44     EAlfTraceCategoryKeyEvent               = 0x00000004,

    45     EAlfTraceCategoryAppEvent               = 0x00000008,

    46     EAlfTraceCategorySystemEvent            = 0x00000010,

    47     EAlfTraceCategoryGeneralEvent           = 0x00000020,

    48     EAlfTraceCategoryAllEvents              = EAlfTraceCategoryKeyEvent |

    49                                               EAlfTraceCategoryAppEvent |

    50                                               EAlfTraceCategorySystemEvent |

    51                                               EAlfTraceCategoryGeneralEvent,

    52 

    53     /*

    54     * Program flow points

    55     */

    56     EAlfTraceCategoryProgramFlowSrcRefresh  = 0x00000040,

    57     EAlfTraceCategoryProgramFlowTextureLoad = 0x00000080,

    58     EAlfTraceCategoryProgramFlowGeneral     = 0x00000100,

    59     EAlfTraceCategoryProgramFlowAll         = 

    60                                               EAlfTraceCategoryProgramFlowSrcRefresh |

    61                                               EAlfTraceCategoryProgramFlowTextureLoad |

    62                                               EAlfTraceCategoryProgramFlowGeneral,

    63 

    64     /*

    65     * Report ipc event handling events

    66     */

    67     EAlfTraceCategoryIpcMessages            = 0x00000400,

    68 

    69     /*

    70     * Report RAM changes

    71     */

    72     EAlfTraceCategoryRAM                    = 0x00000800,

    73 

    74     /*

    75     * Report framerate

    76     */

    77     EAlfTraceCategoryFramerate              = 0x00001000,

    78 

    79     /*

    80     * General informational trace

    81     */

    82     EAlfTraceCategoryInfo                   = 0x08000000,

    83 

    84     /*

    85     * Trace from warnings

    86     */

    87     EAlfTraceCategoryWarning                = 0x10000000,    

    88 

    89     /*

    90     * Trace from errors

    91     */

    92     EAlfTraceCategoryError                  = 0x20000000,

    93 

    94     /*

    95     * Trace from panic situations

    96     */

    97     EAlfTraceCategoryPanic                  = 0x40000000,

    98 

    99     /*

   100     * Trace from trace internal error situations

   101     */

   102     EAlfTraceCategoryInternalError          = 0x80000000,

   103 

   104     /*

   105     * All traces

   106     */

   107     EAlfTraceCategoryAll                    = 0xffffffff,

   108     

   109     /*

   110     * No traces

   111     */    

   112     EAlfTraceCategoryNone                   = 0x00000000,

   113     };

   114 

   115 

   116 /**

   117  *  Abstract trace interface

   118  *

   119  *  Interface for keeping track of test cases, and for receiving trace output requests.

   120  *

   121   *  @since S60 v3.2

   122  */

   123 class MAlfTraceInterface

   124     {

   125 public:

   126 

   127     /**

   128      * Starts a new test case. If existing test case is already started, new nested

   129      * test case will be created.

   130      *

   131      * @since S60 v3.2

   132      * @aTraceCategory Test case category

   133      * @param aTestCaseName Test case name

   134      *

   135      */

   136     virtual void StartTestCase(TInt32 aTraceCategory, const TDesC& aTestCaseName) = 0;

   137 

   138     /**

   139      * Closes the current (most-recently created) test case.

   140      *

   141      * @since S60 v3.2

   142      *

   143      */

   144     virtual void EndTestCase(void) = 0;

   145 

   146     /**

   147      * Sets an output filter.

   148      *

   149      * Output filter controls which trace output events are actually written to trace file or device.    

   150      * Parameter aCategories can be one or more flags from EAlfTraceCategory enumeration.

   151      * Join multiple flags with OR (|) operator.

   152      *

   153      * @since S60 v3.2

   154      * @param aCategories One or more flags from EAlfTraceCategory enumaration

   155      * @return Previous output filter

   156      *

   157      */

   158     virtual TInt32 SetOutputFilter(TInt32 aCategories) = 0;

   159 

   160     /*

   161      * Output single string to trace output device or file. Time stamp and current test case

   162      * information will be concatenated with the string. Trace is written only if its

   163      * category matches with current output filter. If the trace belongs to more than one

   164      * category, categories can be joined with OR (|) operator.

   165      *

   166      * @since S60 v3.2

   167      * @param aTraceCategory Flag in EAlfTraceCategory enumaration

   168      * @param aString Output string

   169      *

   170      */

   171     virtual void OutputString(TInt32 aTraceCategory, const TDesC& aString) = 0;

   172 

   173     /*

   174      * Output single unsigned integer number with description to trace output device or file.

   175      * Time stamp and current test case information will be concatenated with the string. 

   176      * Trace is written only if its category matches with current output filter. If the

   177      * trace belongs to more than one category, categories can be joined with OR (|) operator.

   178      *

   179      * @since S60 v3.2

   180      * @param aTraceCategory Flag in EAlfTraceCategory enumaration

   181      * @param aDescription Description for number

   182      * @param aNumber Number value

   183      *

   184      */

   185     virtual void OutputNumber(TInt32 aTraceCategory, const TDesC& aDescription, TUint aNumber) = 0;

   186 

   187     /*

   188      * Output single signed integer number with description to trace output device or file.

   189      * Time stamp and current test case information will be concatenated with the string. 

   190      * Trace is written only if its category matches with current output filter. If the

   191      * trace belongs to more than one category, categories can be joined with OR (|) operator.

   192      *

   193      * @since S60 v3.2

   194      * @param aTraceCategory Flag in EAlfTraceCategory enumaration

   195      * @param aDescription Description for number

   196      * @param aNumber Number value

   197      *

   198      */

   199     virtual void OutputNumber(TInt32 aTraceCategory, const TDesC& aDescription, TInt aNumber) = 0;

   200 

   201     /*

   202      * Output single floating point number with description to trace output device or file.

   203      * Time stamp and current test case information will be concatenated with the string. 

   204      * Trace is written only if its category matches with current output filter. If the

   205      * trace belongs to more than one category, categories can be joined with OR (|) operator.

   206      *

   207      * @since S60 v3.2

   208      * @param aTraceCategory Flag in EAlfTraceCategory enumaration

   209      * @param aDescription Description for number

   210      * @param aNumber Number value

   211      *

   212      */

   213     virtual void OutputNumber(TInt32 aTraceCategory, const TDesC& aDescription, TReal32 aNumber) __SOFTFP = 0;

   214 

   215     /*

   216      * Output arbitary string to trace output device or file, with no additional data nor filtering.

   217      *

   218      * @since S60 v3.2

   219      * @param aString Output string

   220      *

   221      */

   222     virtual void RawOutput(const TDesC& aString) = 0;

   223 

   224     /*

   225      * Flush buffered output data. This is effective only if the trace output device or file has

   226      * a output buffer.

   227      *

   228      * @since S60 v3.2

   229      *

   230      */

   231     virtual void Flush(void) = 0;

   232     };

   233 

   234 #endif // M_ALFTRACEINTERFACE_H

   235