sl@0: // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // Trace API
sl@0: //
sl@0: 
sl@0: #ifndef E32UTRACE_H
sl@0: #define E32UTRACE_H
sl@0: 
sl@0: #include <e32utrace_basic_types.h>
sl@0: 
sl@0: 
sl@0: /**
sl@0: Methods for tracing from user and kernel side.
sl@0: 
sl@0: These methods are used to output trace packets.
sl@0: Each trace packet consist of attributes and the user defined payload.
sl@0: The attributes in @see TTraceContext is used to identify and filter the trace packet.
sl@0: 
sl@0: In order to output trace packets tracing needs to be
sl@0: included and enabled at compile time in the executable,
sl@0: as well as be filtered at run-time.
sl@0: @see e32utrace.mmh
sl@0: @see RUlogger for information on how to filter at run-time
sl@0: 
sl@0: Trace example:
sl@0: 
sl@0: To include tracing you need to include the e32utrace.mmh
sl@0: in your executables mmp file. You also need to enable tracing at
sl@0: build time, which you do by defining the
sl@0: SYMBIAN_INCLUDE_EXECUTABLE_TRACE before the mmh is included.
sl@0: 
sl@0: @code
sl@0: #define SYMBIAN_INCLUDE_EXECUTABLE_TRACE
sl@0: #include <e32utrace.mmh>
sl@0: @endcode
sl@0: 
sl@0: Example usage of UTrace:
sl@0: 
sl@0: @code
sl@0: #include <e32utf.h>
sl@0: using namespace UTF;
sl@0: 
sl@0: TInt E32Main()
sl@0: 	{
sl@0: 	TFormatId formatId = TMyAppFormatExample::KFilePrintfStringLookupId;
sl@0: 	TUint32 myData = SomeData();
sl@0: 
sl@0: 	//One line trace examples
sl@0: 	Printf(TTraceContext(EError), "My data %d.", myData);
sl@0: 	Printf(TTraceContext(KMyModuleUid, EError), "My data %d.", myData);
sl@0: 	Printf(TTraceContext(EError, ENoThreadIdentification, ENoProgramCounter), "My data %d.", myData);
sl@0: 	
sl@0: 	//In case Printf is overloaded
sl@0: 	UTF::Printf(TTraceContext(EError), "My data %d.", myData);
sl@0: 	
sl@0: 	//Using default ModuleUid, i.e. UID3
sl@0: 	TTraceContext context(EError);
sl@0: 	if(WouldBeTracedNow(context))
sl@0: 		{
sl@0: 		Printf(context, "My data %d.", myData);
sl@0: 		Trace(context, formatId, myData);	
sl@0: 		}
sl@0: 		
sl@0: 	//Setting the default ModuleUid to something other than UID3
sl@0: 	#define EXECUTABLE_DEFAULT_MODULEUID 0x00210D3B
sl@0: 	TTraceContext otherDefault(EError);
sl@0: 	if(WouldBeTracedNow(otherDefault))
sl@0: 		{
sl@0: 		Printf(otherDefault, "My data %i.", myData);
sl@0: 		Trace(otherDefault, formatId, myData);	
sl@0: 		}
sl@0: 	
sl@0: 	//Setting different ModuleUid for each trace point
sl@0: 	static const TModuleUid KTelephony = 0x00210D3B;
sl@0: 	static const TModuleUid KConnectivity = 0x0039399A;
sl@0: 	TTraceContext telephony(KTelephony, ECallControl);
sl@0: 	TTraceContext connectivity(KConnectivity, EBluetooth);
sl@0: 	if(WouldBeTracedNow(telephony))
sl@0: 		{
sl@0: 		Printf(telephony, "My data %i.", myData);
sl@0: 		}
sl@0: 	if(WouldBeTracedNow(connectivity))
sl@0: 		{
sl@0: 		Printf(connectivity, "My data %i.", myData);
sl@0: 		}
sl@0: 		
sl@0: 	//Don't add the thread identification into the trace packet
sl@0: 	TTraceContext noThreadIdentifier(EError, ENoThreadIdentification, ENoProgramCounter);
sl@0: 	if(WouldBeTracedNow(noThreadIdentifier))
sl@0: 		{
sl@0: 		Printf(noThreadIdentifier, "My data %i.", myData);
sl@0: 		Trace(noThreadIdentifier, formatId, myData);	
sl@0: 		}
sl@0: 	
sl@0: 	return KErrNone;
sl@0: 	}
sl@0: 	
sl@0: @endcode
sl@0: 
sl@0: 
sl@0: Note:
sl@0: UTrace does not enforce any security. It is the developer's responsibility
sl@0: to ensure that trace packets do not contain any sensitive information that
sl@0: may undermine platform security.
sl@0: 
sl@0: @file
sl@0: @publishedPartner
sl@0: @prototype
sl@0: */
sl@0: namespace UTF
sl@0: {
sl@0: /**
sl@0: Class used to encapsulate the context of a trace point.
sl@0: For more information about the attributes please @see e32utrace_basic_types.h.
sl@0: */
sl@0: NONSHARABLE_CLASS(TTraceContext)
sl@0: 	{
sl@0: public:
sl@0: 	inline TTraceContext(const TClassification aClassification);	
sl@0: 	inline TTraceContext(const TClassification aClassification, const THasThreadIdentification aHasThreadIdentification, const THasProgramCounter aHasProgramCounter);
sl@0: 	
sl@0: 	inline TTraceContext(const TModuleUid aModuleUid, const TClassification aClassification);
sl@0: 	inline TTraceContext(const TModuleUid aModuleUid, const TClassification aClassification, const THasThreadIdentification aHasThreadIdentification, const THasProgramCounter aHasProgramCounter);
sl@0: 
sl@0: 	IMPORT_C TModuleUid					ModuleUid() const;
sl@0: 	IMPORT_C TClassification 			Classification() const;
sl@0: 	IMPORT_C THasThreadIdentification	HasThreadIdentification()  const;
sl@0: 	IMPORT_C THasProgramCounter 		HasProgramCounter()  const;
sl@0: 	IMPORT_C static TModuleUid			DefaultModuleUid();
sl@0: private:
sl@0: 	inline TTraceContext(){};
sl@0: private:
sl@0: 	TModuleUid					iModuleUid;			//@see TModuleUid
sl@0: 	TClassification 			iClassification;	//@see TClassification
sl@0: 	THasThreadIdentification	iHasThreadIdentification;	//@see THasThreadIdentification
sl@0: 	THasProgramCounter			iHasProgramCounter;			//@see THasProgramCounter
sl@0: 	TUint32			 			iReserved1;			//Reserved for future use
sl@0: 	TUint32			 			iReserved2;			//Reserved for future use
sl@0: 	};
sl@0: 
sl@0: 	IMPORT_C TBool Printf(const TTraceContext& aContext, const char* aFmt, ...);
sl@0: 	IMPORT_C TBool Print(const TTraceContext& aContext, const TDesC8& aDes);
sl@0: 	IMPORT_C TBool Printf(const TTraceContext& aContext, TRefByValue<const TDesC8> aFmt,...);
sl@0: 	#ifndef  __KERNEL_MODE__
sl@0: 	IMPORT_C TBool Print(const TTraceContext& aContext, const TDesC16& aDes);
sl@0: 	IMPORT_C TBool Printf(const TTraceContext& aContext, TRefByValue<const TDesC16> aFmt,...);
sl@0: 	#endif //__KERNEL_MODE__
sl@0: 	
sl@0: 	IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId);
sl@0: 	IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TUint8 aData);
sl@0: 	IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TUint16 aData);
sl@0: 	IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TUint32 aData);
sl@0: 	IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TUint32 aData1, const TUint32 aData2);
sl@0: 	IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TDesC8& aData);
sl@0: 	#ifndef __KERNEL_MODE__
sl@0: 	IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TDesC16& aData);
sl@0: 	#endif
sl@0: 	template<typename T>
sl@0: 	static inline TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const T& aData);
sl@0: 	IMPORT_C TBool Trace(const TTraceContext& aContext, const TFormatId aFormatId, const TAny* aData, const TInt aDataSize);
sl@0: 	
sl@0: 	IMPORT_C TBool WouldBeTracedNow(const TTraceContext& aContext);
sl@0: 
sl@0: 	
sl@0: #include <e32utrace.inl>
sl@0: }//end of UTF namespace
sl@0: 
sl@0: 
sl@0: #endif //E32UTRACE_H