<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-5E861D2B-CEAA-55F4-90D8-206CB8EF835B"><title>UTrace API</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This topic lists the various functionality changes in the UTrace API for UTF 2.0. It covers the following sub-topics: </p> <ul><li id="GUID-38742C23-EC0F-5FC9-95CF-954C0F2F614D"><p><xref href="GUID-5E861D2B-CEAA-55F4-90D8-206CB8EF835B.dita#GUID-5E861D2B-CEAA-55F4-90D8-206CB8EF835B/GUID-297E0D08-6176-532F-A93F-4ADDBEF26A92">API Changes</xref>  </p> </li> <li id="GUID-EE95523E-5E88-5000-95B2-3697284383A2"><p><xref href="GUID-5E861D2B-CEAA-55F4-90D8-206CB8EF835B.dita#GUID-5E861D2B-CEAA-55F4-90D8-206CB8EF835B/GUID-DB940B76-3F25-5F0C-821E-DE5E01E1F176">Trace Calls</xref>  </p> </li> <li id="GUID-B42F67DB-F1ED-5B3B-B597-CDEAE7FCF6C3"><p><xref href="GUID-5E861D2B-CEAA-55F4-90D8-206CB8EF835B.dita#GUID-5E861D2B-CEAA-55F4-90D8-206CB8EF835B/GUID-99E80B35-1A2A-550B-9139-9907DBBF926C">Exported Traces</xref>  </p> </li> <li id="GUID-665B50EC-1977-50FF-9960-2DD832030562"><p><xref href="GUID-5E861D2B-CEAA-55F4-90D8-206CB8EF835B.dita#GUID-5E861D2B-CEAA-55F4-90D8-206CB8EF835B/GUID-5F73A0BA-21F7-5B02-A745-A9311E068358">Trace Points</xref>  </p> </li> <li id="GUID-02058018-A828-53BE-B2B9-5C9974DF3E0A"><p><xref href="GUID-5E861D2B-CEAA-55F4-90D8-206CB8EF835B.dita#GUID-5E861D2B-CEAA-55F4-90D8-206CB8EF835B/GUID-EC57C2D4-6858-551E-8FE6-275FADECE488">Identifiers</xref>  </p> </li> </ul> <section id="GUID-297E0D08-6176-532F-A93F-4ADDBEF26A92"><title>API Changes</title> <p>The following table lists the various changes in the UTrace API for UTF 2.0: </p> <table id="GUID-030D2333-CDEA-56A9-B451-523814C8763C"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry>Item</entry> <entry>UTF 1.0</entry> <entry>UTF 2.0</entry> </row> </thead> <tbody><row><entry><p>Namespace </p> </entry> <entry><p>Not supported </p> </entry> <entry><p>UTF </p> </entry> </row> <row><entry><p>Class containing trace methods </p> </entry> <entry><p> <xref href="GUID-817BCF1D-8E11-3D81-AB0F-1AF1221CCA57.dita"><apiname>TUTrace</apiname></xref>  </p> </entry> <entry><p> <xref href="GUID-424ABDB3-9BBF-3273-A5BD-E21E068CEBAB.dita"><apiname>TTraceContext</apiname></xref>  </p> </entry> </row> <row><entry><p>8-bit filter and identifier </p> </entry> <entry><p> <codeph>TUint8 TPrimaryFilter </codeph>  </p> </entry> <entry><p> <codeph> TUint8 TClassification </codeph>  </p> </entry> </row> <row><entry><p>32-bit filter and identifier </p> </entry> <entry><p> <codeph>TUint32 TSecondaryFilter</codeph>  </p> </entry> <entry><p> <codeph>TUint32 TModuleUid </codeph>  </p> </entry> </row> <row><entry><p>8-bit identifier </p> </entry> <entry><p> <codeph>TUint8 TTraceSchema</codeph>  </p> </entry> <entry><p>Not supported </p> </entry> </row> <row><entry><p>16-bit identifier </p> </entry> <entry><p>Not supported </p> </entry> <entry><p> <codeph>TUint16 TFormatId </codeph>  </p> </entry> </row> <row><entry><p>Context ID </p> </entry> <entry><p> <codeph>TBool aIncludeContextId</codeph>  </p> </entry> <entry><codeblock id="GUID-2DA9F383-6816-5316-8DC5-619343EE932C" xml:space="preserve">enum THasThreadIdentification

{

   EAddThreadIdentification = ETrue,

   ENoThreadIdentification = EFalse

};

</codeblock> </entry> </row> <row><entry><p>Program Counter </p> </entry> <entry><p> <codeph>TBool aIncludePc</codeph>  </p> </entry> <entry><codeblock id="GUID-4ABAB653-992B-5BE5-A70D-458DE04A3A03" xml:space="preserve">enum THasProgramCounter

{

   EAddProgramCounter = ETrue,

   ENoProgramCounter = EFalse

};

</codeblock> </entry> </row> </tbody> </tgroup> </table> </section> <section id="GUID-DB940B76-3F25-5F0C-821E-DE5E01E1F176"><title>Trace Calls</title> <p>In UTF 1.0, all trace calls are contained in the <codeph>TUTrace</codeph> class and you can instantiate a <codeph>TUTrace</codeph> object. The <codeph>TUTrace</codeph> object sets some values, which are used when the trace functions are called. Alternatively, you can pass these values as parameters into each trace call. </p> <p>In UTF 2.0, all trace calls are defined as global static functions which do not belong to a class. Instead of using values stored in a <codeph>TUTrace</codeph> object each trace function takes a <codeph>TTraceContext</codeph> as a parameter. The <codeph>TTraceContext</codeph> class has constructors that set default values for the following parameters: </p> <table id="GUID-C31EF6D1-0278-5EB0-9405-67575462DFE3"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Parameter</entry> <entry>Default Value</entry> </row> </thead> <tbody><row><entry><p>ModuleUid </p> </entry> <entry><p> <codeph>TTraceContext::DefaultModuleUid();</codeph>  </p> <p>Normally, it is <codeph>UID3</codeph> of an application. </p> <p> <b>Note</b>: To override the default ModuleUid, you can use <codeph>EXECUTABLE_DEFAULT_MODULEUID</codeph>, which is defined in <filepath>e32utrace_basic_types.h</filepath>. </p> </entry> </row> <row><entry><p>Thread Identification </p> </entry> <entry><p> <codeph>EAddThreadIdentification</codeph>  </p> <p> <b>Note</b>: To override the default setting for adding or not adding the thread identification in a trace packet, you can use <codeph>EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION</codeph>. </p> </entry> </row> <row><entry><p>Program Counter </p> </entry> <entry><p> <codeph>ENoProgramCounter</codeph>  </p> <p> <b>Note</b>: To override the default setting for adding or not adding the program counter in a trace packet, you can use <codeph>EXECUTABLE_DEFAULT_HAS_PC</codeph>. </p> </entry> </row> </tbody> </tgroup> </table> <p>The following code snippets explain how to override the default values: </p> <p> <b>MMP file</b>  </p> <codeblock id="GUID-61E51EEC-71B4-5128-BCA3-DF4A17584FCD" xml:space="preserve">

#define SYMBIAN_INCLUDE_EXECUTABLE_TRACE

//override the default values

MACRO EXECUTABLE_DEFAULT_MODULEUID=0x00210D3B

MACRO EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION=ENoThreadIdentification

MACRO EXECUTABLE_DEFAULT_HAS_PC=EAddProgramCounter 

#include <e32utrace.mmh>

</codeblock> <p> <b>CPP file</b>  </p> <codeblock id="GUID-E4A1F04B-A55F-5A00-9D8D-7A0362466D93" xml:space="preserve">#include &lt;e32utrace.h&gt;

using namespace UTF;

void e32main()

{

     // print the trace using default ModuleUid, ThreadIdentification and ProgramCounter settings

     Printf(TTraceContext(EBorder), “File handle is %s.”, iMyData);

     // do a binary trace

                    FormatId myDataFormat = KInitialClientFormat; //KInitialClientFormat as defined in e32utrace_basic_types.h

     Trace(TTraceContext(EBorder), myDataFormat, iMyData, sizeof(iMyData)); // data to be included in the trace output

     // override the default context values

     TModuleUid useCaseA = 0x00210D3C;

     Trace(TTraceContext(useCaseA, EBorder, ENoThreadIdentification, ENoProgramCounter), myDataFormat, iMyData, sizeof(iMyData));

}</codeblock> <p> <b>Note</b>: In UTF 1.0, you must specify whether to send a trace using only a primary filter or a combination of primary and secondary filters. You must also set up Context ID and Program counter for each trace. </p> </section> <section id="GUID-99E80B35-1A2A-550B-9139-9907DBBF926C"><title>Exported Traces</title> <p>In UTF 1.0, the <filepath>e32btrace.h</filepath> header file needs to be included in source for the trace calls. </p> <p>In UTF 2.0, trace calls can be exported. To export the trace calls, you must include the <filepath>e32utrace.h</filepath> header file in the source and the <filepath>e32utrace.mmh</filepath> file in an <filepath>MMP</filepath> file. If you want to include trace data in ROM, then use the implemented version of the <filepath>utraceuser.dll</filepath>. To disable all traces in the entire ROM, replace the implemented DLL with the stubbed DLL called <filepath>utraceuserstubbed.dll</filepath>. This allows you to choose a stubbed version over an implemented version without recompiling all components at ROM build time. </p> </section> <section id="GUID-5F73A0BA-21F7-5B02-A745-A9311E068358"><title>Trace Points</title> <p>In UTF 1.0, the <codeph>#define SYMBIAN_TRACE_ENABLE</codeph> must be defined in an <filepath>MMP</filepath> file if traces are to be compiled into source code. In UTF 2.0, the following <codeph>define</codeph> statement is added instead of <codeph>#define SYMBIAN_TRACE_ENABLE</codeph>: </p> <p> <codeph>#define SYMBIAN_INCLUDE_EXECUTABLE_TRACE</codeph>  </p> <p>This must be defined in your <filepath>MMP</filepath> file to implement the traces in source. </p> </section> <section id="GUID-EC57C2D4-6858-551E-8FE6-275FADECE488"><title>Identifiers</title> <p>In UTF 2.0, the <codeph>TTraceSchema</codeph> (8-bit identifier) is removed and <codeph>TFormatId</codeph> (16-bit identifier) added in its place. The <codeph>TFormatId</codeph> identifier is used in conjunction with the Classification and the ModuleUid. It describes how the trace records are to be parsed on the host side. </p> <p>There are two pre-defined FormatIds, <codeph>KFormatIdPrintf</codeph> and <codeph>KFormatIdPrintfUnicode</codeph>, which differentiate between normal and unicode <codeph>printf</codeph> calls. These two pre-defined ids are sent as part of a trace packet generated by a call to any of the printf calls. </p> </section> </conbody></concept>