sl@0: // Copyright (c) 1997-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 "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: // Comms Debug Utility (File and Serial logger) Client side header
sl@0: // 
sl@0: //
sl@0: 
sl@0: /**
sl@0: @file
sl@0: @publishedAll
sl@0: @deprecated Migrate to Open System Trace Instrumentation API instead
sl@0: */
sl@0: 
sl@0: #ifndef __COMMSDEBUGUTILITY_H__
sl@0: #define __COMMSDEBUGUTILITY_H__
sl@0: 
sl@0: #ifndef __FLOG_NO_UDEB
sl@0: 	#ifdef _DEBUG
sl@0: 		#ifndef __FLOG_ACTIVE
sl@0: 			#define __FLOG_ACTIVE
sl@0: 		#endif
sl@0: 	#endif // _DEBUG
sl@0: #endif //__FLOG_NO_UDEB
sl@0: 
sl@0: #ifdef __FLOG_UREL
sl@0: 	#ifndef _DEBUG
sl@0: 		#ifndef __FLOG_ACTIVE
sl@0: 			#define __FLOG_ACTIVE
sl@0: 		#endif //__FLOG_ACTIVE
sl@0: 	#endif //_DEBUG
sl@0: #endif //__FLOG_UREL
sl@0: 
sl@0: 
sl@0: #define __FLOG_DECLARATION_MEMBER_SIZE   TInt32
sl@0: 
sl@0: 
sl@0: // constants available to clients in either build so they can be used in classes
sl@0: #include <e32base.h>
sl@0: 
sl@0: const TInt KLogBufferSize=200;		///< Any attempt to write logs longer than KLogBufferSize and the client string will be truncated.
sl@0: const TInt KMaxHexDumpWidth = 150;	///< If the client asks to hexdump a string longer than this, the string will be truncated
sl@0: const TInt KMaxTagLength = 16;		///< Maximum length of the client tag strings. Exceeding this causes the tag to be truncated.
sl@0: 
sl@0: 
sl@0: #if defined __FLOG_ACTIVE
sl@0: 
sl@0: // make sure clients using this in release mode get a warning.
sl@0: #if (!defined __FLOG_SUPPRESS_REL_WARNING) && (!defined _DEBUG)
sl@0: #pragma message ("WARNING: Use of comms-infras/CommsDebugUtility.h in active mode in a release build")
sl@0: #endif
sl@0: 
sl@0: 
sl@0: const TInt KMaxMediaSettingLength = 0x20; ///< Maximum expected length for media setting tag
sl@0: 
sl@0: 
sl@0: _LIT(KFloggerPanic, "Comsdbgutil.dll");		///< The text which defines any flogger panic. Sent to User::Panic.
sl@0: 
sl@0: /**
sl@0:  * Panic codes
sl@0:  *
sl@0:  * @publishedAll
sl@0:  * @deprecated Migrate to Open System Trace Instrumentation API instead
sl@0:  * @note The order of the panic numbers should not be changed.
sl@0:  *       New panic codes must be added at the end of this enum.
sl@0:  *       All panic codes are assigned to values to ease debugging.
sl@0:  */
sl@0: enum TFloggerPanics
sl@0: 	{
sl@0: 	ESetLogTagsNotCalled = 0,   ///< Attempt by client to write without first setting the ID tags
sl@0: 	EInternalConsistencyFault = 1   ///< A situation has arisen which indicates a programming fault in flogger since the situation should not be caused by any external inputs
sl@0: 	};
sl@0: 
sl@0: /**
sl@0:  * Logging Mode codes
sl@0:  *
sl@0:  * @publishedAll
sl@0:  * @deprecated As of version 8.0 the logging modes are deprecated due to the introduction
sl@0:  *             of a single log file. Appent mode is the default for all write operations,
sl@0:  *             while Overwrite can be achieved using new __FLOG_CLEAR macro, or ClearLog API.
sl@0:  */
sl@0: enum TFileLoggingMode 
sl@0: 	{
sl@0: 	EFileLoggingModeUnknown =0,  ///< Deprecated - has no effect
sl@0: 	EFileLoggingModeAppend,      ///< Deprecated - has no effect
sl@0: 	EFileLoggingModeOverwrite,    ///< Deprecated - has no effect
sl@0: 	EFileLoggingModeAppendRaw,	 ///< Deprecated - has no effect
sl@0: 	EFileLoggingModeOverwriteRaw ///< Deprecated - has no effect	
sl@0: 	};
sl@0: 
sl@0: class RFileLoggerBody;
sl@0: 
sl@0: 
sl@0: /**
sl@0:  * Flogger - File and Serial Logger client interface 
sl@0:  *
sl@0:  * @publishedAll
sl@0:  * @deprecated Migrate to Open System Trace Instrumentation API instead
sl@0:  * 
sl@0:  * This class is responsible for providing all functions
sl@0:  * clients require of the flogger system. It is preferred, though,
sl@0:  * that clients use the provided macros which refer to these API's
sl@0:  * so that all logging code is governed by the global __FLOG_ACTIVE
sl@0:  * macro setting. The macro's are not currently documented using
sl@0:  * doxygen - you will need to consult the flogger user guide instead.
sl@0:  * RFileLogger is the only exported interface for the flogger component.
sl@0:  */
sl@0: class RFileLogger
sl@0: 	{
sl@0: public:
sl@0: 	IMPORT_C RFileLogger();
sl@0: 	IMPORT_C ~RFileLogger();
sl@0: 	IMPORT_C TVersion Version() const;
sl@0: 	IMPORT_C TInt Connect();
sl@0: 	IMPORT_C void SetDateAndTime(TBool aUseDate,TBool aUseTime);	//Deprecated. Does nothing.
sl@0: 	IMPORT_C void CreateLog(const TDesC& aSubsystem, const TDesC& aComponent, TFileLoggingMode /*aMode*/);	//Deprecated. Use SetLogTags instead.
sl@0: 	IMPORT_C void CloseLog();	//Deprecated.
sl@0: 	
sl@0: 	IMPORT_C static void Write(const TDesC& aSubsystem, const TDesC& aComponent, TFileLoggingMode /*aMode*/, const TDesC16& aText);   // Removed
sl@0: 	IMPORT_C static void WriteFormat(const TDesC& aSubsystem, const TDesC& aComponent, TFileLoggingMode aMode, TRefByValue<const TDesC16> aFmt,...); // Removed
sl@0: 	IMPORT_C static void WriteFormat(const TDesC& aSubsystem, const TDesC& aComponent, TFileLoggingMode /*aMode*/, TRefByValue<const TDesC16> aFmt, VA_LIST& aList);  // Removed
sl@0: 	IMPORT_C static void Write(const TDesC& aSubsystem, const TDesC& aComponent, TFileLoggingMode /*aMode*/, const TDesC8& aText);  // Removed
sl@0: 	IMPORT_C static void WriteFormat(const TDesC& aSubsystem, const TDesC& aComponent, TFileLoggingMode aMode, TRefByValue<const TDesC8> aFmt,...);  // Removed
sl@0: 	IMPORT_C static void WriteFormat(const TDesC& aSubsystem, const TDesC& aComponent, TFileLoggingMode /*aMode*/, TRefByValue<const TDesC8> aFmt, VA_LIST& aList);  // Removed
sl@0: 	IMPORT_C static void HexDump(const TDesC& aSubsystem, const TDesC& aComponent, TFileLoggingMode /*aMode*/, const TText* aHeader, const TText* aMargin, const TUint8* aPtr, TInt aLen);  // Removed
sl@0: 
sl@0: 	IMPORT_C static void Write(const TDesC8& aSubsystem, const TDesC8& aComponent, const TDesC16& aText);
sl@0: 	IMPORT_C static void WriteFormat(const TDesC8& aSubsystem, const TDesC8& aComponent, const TRefByValue<const TDesC16> aFmt,...);
sl@0: 	IMPORT_C static void WriteFormat(const TDesC8& aSubsystem, const TDesC8& aComponent, const TRefByValue<const TDesC16> aFmt, VA_LIST& aList);
sl@0: 	IMPORT_C static void Write(const TDesC8& aSubsystem, const TDesC8& aComponent, const TDesC8& aText);
sl@0: 	IMPORT_C static void WriteFormat(const TDesC8& aSubsystem, const TDesC8& aComponent, const TRefByValue<const TDesC8> aFmt,...);
sl@0: 	IMPORT_C static void WriteFormat(const TDesC8& aSubsystem, const TDesC8& aComponent, const TRefByValue<const TDesC8> aFmt, VA_LIST& aList);
sl@0: 	IMPORT_C static void HexDump(const TDesC8& aSubsystem, const TDesC8& aComponent, const TDesC8& aData, const TDesC8& aHeader = TPtrC8(NULL,0));
sl@0: 	
sl@0: 	IMPORT_C void Write(const TDesC16& aText);
sl@0: 	IMPORT_C void WriteFormat(TRefByValue<const TDesC16> aFmt,...);
sl@0: 	IMPORT_C void WriteFormat(TRefByValue<const TDesC16> aFmt, VA_LIST& aList);
sl@0: 	IMPORT_C void Write(const TDesC8& aText);
sl@0: 	IMPORT_C void WriteFormat(TRefByValue<const TDesC8> aFmt,...);
sl@0: 	IMPORT_C void WriteFormat(TRefByValue<const TDesC8> aFmt, VA_LIST& aList);
sl@0: 	IMPORT_C void WriteBinary(const TDesC8& aData);
sl@0: 	IMPORT_C void HexDump(const TText* aHeader, const TText* aMargin, const TUint8* aPtr, TInt aLen);
sl@0: 	IMPORT_C void HexDump(const TDesC8& aData, const TDesC8& aHeader = TPtrC8(NULL,0));
sl@0: 	
sl@0: 	IMPORT_C TInt LastError() const;	//Deprecated.
sl@0: 	IMPORT_C TBool LogValid() const;	//Deprecated.
sl@0: 	IMPORT_C void Close();
sl@0: 	IMPORT_C TInt ClearLog();
sl@0: 	IMPORT_C TInt SetLogTags(const TDesC8& aSubsystem, const TDesC8& aComponent);
sl@0: 	IMPORT_C TInt Handle() const;
sl@0: 	IMPORT_C TInt Share();
sl@0: 	IMPORT_C void __DbgShutDownServer();	//For testing purposes only
sl@0: 	IMPORT_C void __DbgSetHeapFailure(TInt aFailAfter);
sl@0: private:
sl@0: 	TInt DoConnect();
sl@0: 	TInt DoSetLogTags(const TDesC8& aSubsystem, const TDesC8& aComponent);
sl@0: 	void DoWrite(const TDesC8& aBuf);
sl@0: 	void DoWriteFormat(TRefByValue<const TDesC16> aFmt, VA_LIST& aList);
sl@0: 	void DoWriteFormat(TRefByValue<const TDesC8> aFmt, VA_LIST& aList);
sl@0: 	void DoSendStaticWrite(const TDesC8& aDir, const TDesC8& aName, const TDesC8& aBuf);
sl@0: 	static void DoStaticWrite(const TDesC8& aDir, const TDesC8& aName, const TDesC8& aBuf);
sl@0: 	static void DoStaticWriteFormat(const TDesC8& aDir, const TDesC8& aName, const TRefByValue<const TDesC16> aFmt, VA_LIST& aList);
sl@0: 	static void DoStaticWriteFormat(const TDesC8& aDir, const TDesC8& aName, const TRefByValue<const TDesC8> aFmt, VA_LIST& aList);
sl@0: 	void DoHexDump(const TText* aHeader, const TText* aMargin, const TUint8* aPtr, TInt aLen);
sl@0: 	void DoHexDump(const TDesC8& aData, const TDesC8& aHeader, const TDesC8& aMargin);
sl@0: 	TBool IsLogging();
sl@0: 	RFileLogger& operator=(const RFileLogger& aLogger);	//Outlaw copying RFileLogger objects.
sl@0: 	RFileLogger(const RFileLogger& aLogger); //Outlaw copy constructor
sl@0: private:
sl@0: 	RFileLoggerBody* iLoggerBody;   ///< Reference to all the data the client interface requires. This keeps the class size small and less likely to change in size.
sl@0: 	};
sl@0: 
sl@0: 
sl@0: // Consult the How-to/User Guide for how to use these macros
sl@0: 
sl@0: // Sundry Logging Macros
sl@0: 
sl@0: #define __FLOG_DECLARATION_MEMBER_MUTABLE  mutable RFileLogger __logger__
sl@0: 
sl@0: #define __FLOG_DECLARATION_MEMBER		   RFileLogger __logger__
sl@0: 
sl@0: #define __FLOG_DECLARATION_VARIABLE		   RFileLogger __logger__
sl@0: 
sl@0: #define __FLOG_OPEN(subsys,compnt)		__logger__.Connect();\
sl@0: 										__logger__.SetLogTags(subsys,compnt)
sl@0: 
sl@0: #define __FLOG_OPENC(subsys,compnt)		__logger__.Connect();\
sl@0: 										__logger__.SetLogTags(subsys,compnt);\
sl@0: 										CleanupClosePushL(__logger__)
sl@0: 
sl@0: #define __FLOG_CLOSE					__logger__.Close()
sl@0: 
sl@0: #define __FLOG_CLOSE_CLEANUP			CleanupStack::PopAndDestroy(&__logger__)
sl@0: 
sl@0: #define __FLOG_CLEAR					__logger__.ClearLog()
sl@0: 
sl@0: #define __FLOG_SET_TAGS(subsys,compnt)	__logger__.SetLogTags(subsys,compnt)
sl@0: 
sl@0: #define __FLOG_STMT(text) text
sl@0: 
sl@0: // Connected Output Logging Macros
sl@0: 
sl@0: #define __FLOG_0(text)					__logger__.Write(text)
sl@0: 
sl@0: #define __FLOG_1(text,a)				__logger__.WriteFormat(text,a)
sl@0: 
sl@0: #define __FLOG_2(text,a,b)				__logger__.WriteFormat(text,a,b)
sl@0: 
sl@0: #define __FLOG_3(text,a,b,c)			__logger__.WriteFormat(text,a,b,c)
sl@0: 
sl@0: #define __FLOG_4(text,a,b,c,d)			__logger__.WriteFormat(text,a,b,c,d)
sl@0: 
sl@0: #define __FLOG_5(text,a,b,c,d,e)		__logger__.WriteFormat(text,a,b,c,d,e)
sl@0: 
sl@0: #define __FLOG_6(text,a,b,c,d,e,f)		__logger__.WriteFormat(text,a,b,c,d,e,f)
sl@0: 
sl@0: #define __FLOG_7(text,a,b,c,d,e,f,g)	__logger__.WriteFormat(text,a,b,c,d,e,f,g)
sl@0: 
sl@0: #define __FLOG_8(text,a,b,c,d,e,f,g,h)	__logger__.WriteFormat(text,a,b,c,d,e,f,g,h)
sl@0: 
sl@0: #define __FLOG_9(text,a,b,c,d,e,f,g,h,i)	__logger__.WriteFormat(text,a,b,c,d,e,f,g,h,i)
sl@0: 
sl@0: #define __FLOG(text)						__logger__.Write(text)
sl@0: 
sl@0: #define __FLOG_VA(args)						__logger__.WriteFormat args
sl@0: 
sl@0: #define __FLOG_HEXDUMP(args)				__logger__.HexDump args
sl@0: 
sl@0: #define __FLOG_BINARY(data)					__logger__.WriteBinary(data)
sl@0: 
sl@0: // Static Output Logging Macros
sl@0: #define __FLOG_STATIC0(subsys,compnt,text)						RFileLogger::Write(subsys,compnt, text)
sl@0: 
sl@0: #define __FLOG_STATIC1(subsys,compnt,text,a)					RFileLogger::WriteFormat(subsys,compnt, text,a)
sl@0: 
sl@0: #define __FLOG_STATIC2(subsys,compnt,text,a,b)					RFileLogger::WriteFormat(subsys,compnt, text,a,b)
sl@0: 
sl@0: #define __FLOG_STATIC3(subsys,compnt,text,a,b,c)				RFileLogger::WriteFormat(subsys,compnt, text,a,b,c)
sl@0: 
sl@0: #define __FLOG_STATIC4(subsys,compnt,text,a,b,c,d)				RFileLogger::WriteFormat(subsys,compnt, text,a,b,c,d)
sl@0: 
sl@0: #define __FLOG_STATIC5(subsys,compnt,text,a,b,c,d,e)			RFileLogger::WriteFormat(subsys,compnt, text,a,b,c,d,e)
sl@0: 
sl@0: #define __FLOG_STATIC6(subsys,compnt,text,a,b,c,d,e,f)			RFileLogger::WriteFormat(subsys,compnt, text,a,b,c,d,e,f)
sl@0: 
sl@0: #define __FLOG_STATIC7(subsys,compnt,text,a,b,c,d,e,f,g)		RFileLogger::WriteFormat(subsys,compnt, text,a,b,c,d,e,f,g)
sl@0: 
sl@0: #define __FLOG_STATIC8(subsys,compnt,text,a,b,c,d,e,f,g,h)		RFileLogger::WriteFormat(subsys,compnt, text,a,b,c,d,e,f,g,h)
sl@0: 
sl@0: #define __FLOG_STATIC9(subsys,compnt,text,a,b,c,d,e,f,g,h,i)	RFileLogger::WriteFormat(subsys,compnt, text,a,b,c,d,e,f,g,h,i)
sl@0: 
sl@0: #define __FLOG_STATIC(subsys,compnt,text)						RFileLogger::WriteFormat(subsys,compnt, text)
sl@0: 
sl@0: #define __FLOG_STATIC_VA(args)									RFileLogger::WriteFormat args
sl@0: 
sl@0: #define __FLOG_STATIC_HEXDUMP(args)								RFileLogger::HexDump args
sl@0: 
sl@0: 
sl@0: 
sl@0: // Line below is used to check that RFileLogger stays the same size as
sl@0: // __FLOG_DECLARATION_MEMBER_SIZE. If the RFileLogger object ever changes size,
sl@0: // the line below will cause the compiler to throw an error. __FLOG_DECLARATION_MEMBER_SIZE
sl@0: // should then be changed accordingly.
sl@0: const TInt KCheckRFileLoggerIsCorrectSize = 1/(sizeof(RFileLogger)==sizeof(__FLOG_DECLARATION_MEMBER_SIZE));
sl@0: 
sl@0: 
sl@0: 
sl@0: #else
sl@0: // Begin declarations for when Flogger is NOT to be used.
sl@0: // This declares all macros to be void and the class to be replaced with a stub.
sl@0: // This will result in Flogger only requiring 32 bits for each component which uses it.
sl@0: 
sl@0: // Consult the How-to/User Guide for how to use these macros
sl@0: 
sl@0: // Sundry Logging Macros
sl@0: 
sl@0: #define __FLOG_DECLARATION_MEMBER_MUTABLE	__FLOG_DECLARATION_MEMBER_SIZE __noLogger__; \
sl@0: 											inline void useNoLogger() { __noLogger__ = 0; }
sl@0: 
sl@0: #define __FLOG_DECLARATION_MEMBER			__FLOG_DECLARATION_MEMBER_SIZE __noLogger__; \
sl@0: 											inline void useNoLogger() { __noLogger__ = 0; }
sl@0: 
sl@0: #define __FLOG_DECLARATION_VARIABLE
sl@0: 
sl@0: #define __FLOG_OPEN(subsys,compnt)
sl@0: 
sl@0: #define __FLOG_OPENC(subsys,compnt)
sl@0: 
sl@0: #define __FLOG_CLOSE
sl@0: 
sl@0: #define __FLOG_CLOSE_CLEANUP
sl@0: 
sl@0: #define __FLOG_HEXDUMP(args)
sl@0: 
sl@0: #define __FLOG_CLEAR					
sl@0: 
sl@0: #define __FLOG_SET_TAGS(subsys,compnt)		
sl@0: 
sl@0: 
sl@0: #define __FLOG_STMT(text)
sl@0: 
sl@0: 
sl@0: // Connected Output Logging Macros
sl@0: 
sl@0: #define __FLOG_0(text)
sl@0: 
sl@0: #define __FLOG_1(text,a)
sl@0: 
sl@0: #define __FLOG_2(text,a,b)
sl@0: 
sl@0: #define __FLOG_3(text,a,b,c)
sl@0: 
sl@0: #define __FLOG_4(text,a,b,c,d)
sl@0: 
sl@0: #define __FLOG_5(text,a,b,c,d,e)
sl@0: 
sl@0: #define __FLOG_6(text,a,b,c,d,e,f)
sl@0: 
sl@0: #define __FLOG_7(text,a,b,c,d,e,f,g)
sl@0: 
sl@0: #define __FLOG_8(text,a,b,c,d,e,f,g,h)
sl@0: 
sl@0: #define __FLOG_9(text,a,b,c,d,e,f,g,h,i)
sl@0: 
sl@0: #define __FLOG(text)
sl@0: 
sl@0: #define __FLOG_VA(args)
sl@0: 
sl@0: #define __FLOG_BINARY(data)	
sl@0: 
sl@0: // Static Output Logging Macros
sl@0: #define __FLOG_STATIC0(subsys,compnt,text)		
sl@0: 
sl@0: #define __FLOG_STATIC1(subsys,compnt,text,a)		
sl@0: 
sl@0: #define __FLOG_STATIC2(subsys,compnt,text,a,b)		
sl@0: 
sl@0: #define __FLOG_STATIC3(subsys,compnt,text,a,b,c)	
sl@0: 
sl@0: #define __FLOG_STATIC4(subsys,compnt,text,a,b,c,d)		
sl@0: 
sl@0: #define __FLOG_STATIC5(subsys,compnt,text,a,b,c,d,e)	
sl@0: 
sl@0: #define __FLOG_STATIC6(subsys,compnt,text,a,b,c,d,e,f)		
sl@0: 
sl@0: #define __FLOG_STATIC7(subsys,compnt,text,a,b,c,d,e,f,g)	
sl@0: 
sl@0: #define __FLOG_STATIC8(subsys,compnt,text,a,b,c,d,e,f,g,h)	
sl@0: 
sl@0: #define __FLOG_STATIC9(subsys,compnt,text,a,b,c,d,e,f,g,h,i)	
sl@0: 
sl@0: #define __FLOG_STATIC(subsys,compnt,text)
sl@0: 
sl@0: #define __FLOG_STATIC_VA(args)
sl@0: 
sl@0: #define __FLOG_STATIC_HEXDUMP(args)		
sl@0: 
sl@0: 
sl@0: #endif
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: #endif // __COMMSDEBUGUTILITY_H__