RFileLogger Class Reference

class RFileLogger : public RSessionBase

Provides access methods to file logging.

The file logger API contains both static and non-static versions of access functions to the file logging system. Migrate to Open System Trace Instrumentation API instead

Inherits from

Public Member Functions
RFileLogger ()
~RFileLogger ()
IMPORT_C void CloseLog ()
IMPORT_C TInt Connect ()
IMPORT_C void CreateLog (const TDesC &, const TDesC &, TFileLoggingMode )
IMPORT_C void HexDump (const TText *, const TText *, const TUint8 *, TInt )
IMPORT_C void HexDump (const TDesC &, const TDesC &, TFileLoggingMode , const TText *, const TText *, const TUint8 *, TInt )
IMPORT_C TInt LastError ()
IMPORT_C TBool LogSTI ()
IMPORT_C TBool LogValid ()
IMPORT_C void SetDateAndTime ( TBool , TBool )
IMPORT_C TVersion Version ()
IMPORT_C void Write (const TDesC16 &)
IMPORT_C void Write (const TDesC8 &)
IMPORT_C void Write (const TDesC &, const TDesC &, TFileLoggingMode , const TDesC16 &)
IMPORT_C void Write (const TDesC &, const TDesC &, TFileLoggingMode , const TDesC8 &)
IMPORT_C void WriteFormat ( TRefByValue < const TDesC16 >, ...)
IMPORT_C void WriteFormat ( TRefByValue < const TDesC16 >, VA_LIST &)
IMPORT_C void WriteFormat ( TRefByValue < const TDesC8 >, ...)
IMPORT_C void WriteFormat ( TRefByValue < const TDesC8 >, VA_LIST &)
IMPORT_C void WriteFormat (const TDesC &, const TDesC &, TFileLoggingMode , TRefByValue < const TDesC16 >, ...)
IMPORT_C void WriteFormat (const TDesC &, const TDesC &, TFileLoggingMode , TRefByValue < const TDesC16 >, VA_LIST &)
IMPORT_C void WriteFormat (const TDesC &, const TDesC &, TFileLoggingMode , TRefByValue < const TDesC8 >, ...)
IMPORT_C void WriteFormat (const TDesC &, const TDesC &, TFileLoggingMode , TRefByValue < const TDesC8 >, VA_LIST &)
Private Member Functions
TInt DoConnect ()
void DoHexDump (const TText *, const TText *, const TUint8 *, TInt )
void DoStaticWrite (const TDesC8 &)
void DoStaticWriteFormat (const TDesC &, const TDesC &, TFileLoggingMode , TRefByValue < const TDesC16 >, VA_LIST &)
void DoStaticWriteFormat (const TDesC &, const TDesC &, TFileLoggingMode , TRefByValue < const TDesC8 >, VA_LIST &)
void DoWrite (const TDesC8 &)
void DoWriteFormat ( TRefByValue < const TDesC16 >, VA_LIST &)
void DoWriteFormat ( TRefByValue < const TDesC8 >, VA_LIST &)
Inherited Functions
RHandleBase::Attributes()const
RHandleBase::BTraceId()const
RHandleBase::Close()
RHandleBase::DoExtendedClose()
RHandleBase::Duplicate(const RThread &,TOwnerType)
RHandleBase::FullName()const
RHandleBase::FullName(TDes &)const
RHandleBase::Handle()const
RHandleBase::HandleInfo(THandleInfo *)
RHandleBase::Name()const
RHandleBase::NotifyDestruction(TRequestStatus &)
RHandleBase::Open(const TFindHandleBase &,TOwnerType)
RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
RHandleBase::RHandleBase()
RHandleBase::RHandleBase(TInt)
RHandleBase::SetHandle(TInt)
RHandleBase::SetHandleNC(TInt)
RSessionBase::CreateSession(RServer2,const TVersion &)
RSessionBase::CreateSession(RServer2,const TVersion &,TInt)
RSessionBase::CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)
RSessionBase::CreateSession(const TDesC &,const TVersion &)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)
RSessionBase::Open(RMessagePtr2,TInt,TOwnerType)
RSessionBase::Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)
RSessionBase::Open(TInt,TOwnerType)
RSessionBase::Open(TInt,const TSecurityPolicy &,TOwnerType)
RSessionBase::Send(TInt)const
RSessionBase::Send(TInt,const TIpcArgs &)const
RSessionBase::SendReceive(TInt)const
RSessionBase::SendReceive(TInt,TRequestStatus &)const
RSessionBase::SendReceive(TInt,const TIpcArgs &)const
RSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
RSessionBase::SetReturnedHandle(TInt)
RSessionBase::SetReturnedHandle(TInt,RHandleBase &)
RSessionBase::SetReturnedHandle(TInt,const TSecurityPolicy &)
RSessionBase::ShareAuto()
RSessionBase::ShareProtected()
Inherited Enumerations
RHandleBase:TAttributes
RSessionBase:TAttachMode
Private Attributes
TLogFormatter iFormatter
TInt iLastError
TLogFile iLogFile
TBool iLogSTI
Inherited Attributes
RHandleBase::iHandle

Constructor & Destructor Documentation

RFileLogger()

IMPORT_C RFileLogger ( )

Creates a default RFileLogger object.

~RFileLogger()

IMPORT_C ~RFileLogger ( )

Empty destructor. Clients with open sessions must end the session by calling Close() beforehand. Note that it does not delete the log file.

Member Functions Documentation

CloseLog()

IMPORT_C void CloseLog ( )

Closes the log file, iLogFile.

This function closes the log file previously created or opened by CreateLog() .

Connect()

IMPORT_C TInt Connect ( )

Connects to the file logger server with the default number of message slots, which is 8.

This function does not need to be called if you are using the static versions of Write() , WriteFormat() or HexDump() .

CreateLog(const TDesC &, const TDesC &, TFileLoggingMode)

IMPORT_C void CreateLog ( const TDesC & aDir,
const TDesC & aName,
TFileLoggingMode aMode
)

Creates or opens a file for logging.

When specifying a directory for logging only specify the relative path to 'C:\Logs\' and do not append a '\' to the end of the path either. CreateLog() only creates the specified log file if the directory exists. This means that switching logging on and off can be achieved without having to re-compile, by just removing or renaming the log directory.

aLogFile.iValid is set according to whether logging will actually occur or not.

Parameters

const TDesC & aDir The directory relative to 'C:\Logs\' where the log file resides or is to be created.
const TDesC & aName The name of the log file.
TFileLoggingMode aMode The mode in which the log file should be opened, either EAppend or EOverwrite.

DoConnect()

TInt DoConnect ( ) [private]

Connects to the flogger server - default number of message slots = 8

DoHexDump(const TText *, const TText *, const TUint8 *, TInt)

void DoHexDump ( const TText * aHeader,
const TText * aMargin,
const TUint8 * aPtr,
TInt aLen
) [private]

Static Write. Dumps arbitrary data to the log file as a standard hex dump.

Pre-condition
session is already open.
Post-condition
The text is only written if the original connection was successful. No text is ever written if the directory specified in the original connection request does not exist. Each line is preceded in the date and time.
Note:

This function has poor performance since it performs a full connection and disconnection to the flogger server. Example of aHeader/aMargin. If "aHeader" is set to "Fn Output:" and "aMargin" is set to " ", then output would look like (for a print of the alphabet): 14/11/2002 12:32:24 Fn Output:0000 : 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f 70 abcdefghijklmnop 14/11/2002 12:32:24 0010 : 71 72 73 74 75 76 77 78 79 7a qrstuvwxyz

Parameters

const TText * aHeader Specify a string to be printed before the first hex line. Leave as null or an empty string for no header.
const TText * aMargin Specify a string to be printed before each subsequent line. Leave as null or an empty string for no Margin.
const TUint8 * aPtr pointer to the data being dumped.
TInt aLen the number of bytes to dump

DoStaticWrite(const TDesC8 &)

void DoStaticWrite ( const TDesC8 & aBuf ) [private]

Sends the pre-formatted write string to the flogger server.

Pre-condition
session is already open. aText is not longer than KLogBufferSize
Post-condition
The text is only written if the original connection was successful. No text is ever written if the directory specified in the original connection request does not exist. Each line is preceded in the date and time.

Parameters

const TDesC8 & aBuf text to write

DoStaticWriteFormat(const TDesC &, const TDesC &, TFileLoggingMode, TRefByValue< const TDesC16 >, VA_LIST &)

void DoStaticWriteFormat ( const TDesC & aDir,
const TDesC & aName,
TFileLoggingMode aMode,
TRefByValue < const TDesC16 > aFmt,
VA_LIST & aList
) [private, static]

Sends a format write string to the flogger server to write to the specified file.

Post-condition
The text is only written if the original connection was successful. No text is ever written if the directory specified in the original connection request does not exist. Each line is preceded in the date and time.
void RFileLogger::DoStaticWriteFormat(const TDesC& aDir, const TDesC& aName, TFileLoggingMode aMode, TRefByValue<const TDesC8> aFmt, VA_LIST& aList)

Parameters

const TDesC & aDir Path of the log file.
const TDesC & aName Name of the log file.
TFileLoggingMode aMode
TRefByValue < const TDesC16 > aFmt c-style formatted text to be written.
VA_LIST & aList any variables required by the format.

DoStaticWriteFormat(const TDesC &, const TDesC &, TFileLoggingMode, TRefByValue< const TDesC8 >, VA_LIST &)

void DoStaticWriteFormat ( const TDesC & aDir,
const TDesC & aName,
TFileLoggingMode aMode,
TRefByValue < const TDesC8 > aFmt,
VA_LIST & aList
) [private, static]

Sends a format write string to the flogger server to write to the specified file. There is no pre-condition.

Post-condition
The text is only written if the original connection was successful. No text is ever written if the directory specified in the original connection request does not exist. Each line is preceded in the date and time.

Parameters

const TDesC & aDir Path of the log file.
const TDesC & aName Name of the log file.
TFileLoggingMode aMode
TRefByValue < const TDesC8 > aFmt c-style formatted text to be written.
VA_LIST & aList any variables required by the format.

DoWrite(const TDesC8 &)

void DoWrite ( const TDesC8 & aBuf ) [private]

Sends the pre-formatted write string to the flogger server.

Pre-condition
session is already open.

Parameters

const TDesC8 & aBuf 8-bit text to be written.

DoWriteFormat(TRefByValue< const TDesC16 >, VA_LIST &)

void DoWriteFormat ( TRefByValue < const TDesC16 > aFmt,
VA_LIST & aList
) [private]

Trim format string before sending to the flogger server.

Pre-condition
session is already open.
Post-condition
The final string is truncated to KLogBufferSize.
void RFileLogger::DoWriteFormat(TRefByValue<const TDesC8> aFmt, VA_LIST& aList)

Parameters

TRefByValue < const TDesC16 > aFmt c-style formatted text to be written.
VA_LIST & aList any variables required by the format.

DoWriteFormat(TRefByValue< const TDesC8 >, VA_LIST &)

void DoWriteFormat ( TRefByValue < const TDesC8 > aFmt,
VA_LIST & aList
) [private]

Trim format string before sending to the flogger server.

Pre-condition
session is already open.
Post-condition
The final string is truncated to KLogBufferSize.

Parameters

TRefByValue < const TDesC8 > aFmt c-style formatted text to be written.
VA_LIST & aList any variables required by the format.

HexDump(const TText *, const TText *, const TUint8 *, TInt)

IMPORT_C void HexDump ( const TText * aHeader,
const TText * aMargin,
const TUint8 * aPtr,
TInt aLen
)

Writes a hex dump of the specified data to the log.

The format of the hex dump entry is a header followed by the hex string of the data followed by any printable characters (non printable characters are substituted with '.'). For example,

         RLog_Ex0000 : 41 42 6C 6B 0A 0A 45 46 20 20 78 7A                       ABlk..EF 
 xz
RL_cont0001 : 43 44 6C 6B 0A 0A 45 46 20 20 78 7A                       CDlk..EF 
 xz
RL_cont0002 : 45 46 6C 6B 0A 0A 47 48 20 20 78 7A                       EFlk..GH 
 xz
.
.
.
        

Parameters

const TText * aHeader A label for the hex dump entry. The label has a sequence number appended to it automatically.
const TText * aMargin A continuation label if the hex dump exceeds one line. This label is displayed on all subsequent lines after line one and also has a sequence number appended to it.
const TUint8 * aPtr The data that is to be converted to a hex string.
TInt aLen How many of the characters in aPtr are to be converted. Conversion always starts from position 0 within aPtr.

HexDump(const TDesC &, const TDesC &, TFileLoggingMode, const TText *, const TText *, const TUint8 *, TInt)

IMPORT_C void HexDump ( const TDesC & aDir,
const TDesC & aName,
TFileLoggingMode aMode,
const TText * aHeader,
const TText * aMargin,
const TUint8 * aPtr,
TInt aLen
) [static]

Writes a hex dump of the specified data to the log.

The format of the hex dump entry is a header followed by the hex string of the data followed by any printable characters (non printable characters are substituted with '.'). For example,

         RLog_Ex0000 : 41 42 6C 6B 0A 0A 45 46 20 20 78 7A                       ABlk..EF 
 xz
RL_cont0001 : 43 44 6C 6B 0A 0A 45 46 20 20 78 7A                       CDlk..EF 
 xz
RL_cont0002 : 45 46 6C 6B 0A 0A 47 48 20 20 78 7A                       EFlk..GH 
 xz
.
.
.
        

Parameters

const TDesC & aDir The directory relative to 'C:\Logs\' where the log file resides.
const TDesC & aName The name of the log file.
TFileLoggingMode aMode The mode in which the log file should be opened: either EAppend or EOverwrite.
const TText * aHeader A label for the hex dump entry. The label has a sequence number appended to it automatically.
const TText * aMargin A continuation label if the hex dump exceeds one line. This label is displayed on all subsequent lines after line one and also has a sequence number appended to it.
const TUint8 * aPtr The data that is to be converted to a hex string.
TInt aLen How many of the characters in aPtr are to be converted. Conversion always starts from position 0 within aPtr.

LastError()

IMPORT_C TInt LastError ( ) const

Returns the last error status that has been set.

LogSTI()

IMPORT_C TBool LogSTI ( ) const

Returns patchable constant value.

LogValid()

IMPORT_C TBool LogValid ( ) const

Returns the status of the log.

SetDateAndTime(TBool, TBool)

IMPORT_C void SetDateAndTime ( TBool aUseDate,
TBool aUseTime
)

Specifies whether time and/or date should be appended to log data.

Appending of the time and date to log entries can be switched on and off at anytime between creation and destruction of RFileLogger .

This function does not need to be called if you are using the static versions of Write() , WriteFormat() or HexDump() .

Parameters

TBool aUseDate Use ETrue to log the date, otherwise EFalse.
TBool aUseTime Use ETrue to log the time, otherwise EFalse.

Version()

IMPORT_C TVersion Version ( ) const

Returns the version number.

Write(const TDesC16 &)

IMPORT_C void Write ( const TDesC16 & aText )

Writes a string of Unicode characters to an open log, iLogFile, if it is a valid file.

Note that the text will be converted to an 8 bit format for the log file.

Parameters

const TDesC16 & aText The Unicode string to write to the open log.

Write(const TDesC8 &)

IMPORT_C void Write ( const TDesC8 & aText )

Writes a string of 8-bit characters to an open log, iLogFile, if it is a valid file.

Parameters

const TDesC8 & aText The 8-bit character string to write to the open log.

Write(const TDesC &, const TDesC &, TFileLoggingMode, const TDesC16 &)

IMPORT_C void Write ( const TDesC & aDir,
const TDesC & aName,
TFileLoggingMode aMode,
const TDesC16 & aText
) [static]

Writes a string of 16-bit characters to an open log.

Connects to the logging server, creates/opens the log file and write aText to it.

This is a "static write".

Note that the text will be converted to an 8 bit format for the log file.

Parameters

const TDesC & aDir The directory relative to 'C:\Logs\' where the log file resides.
const TDesC & aName The name of the log file.
TFileLoggingMode aMode The mode in which the log file should be opened: either EAppend or EOverwrite.
const TDesC16 & aText The Unicode string to write to the log.

Write(const TDesC &, const TDesC &, TFileLoggingMode, const TDesC8 &)

IMPORT_C void Write ( const TDesC & aDir,
const TDesC & aName,
TFileLoggingMode aMode,
const TDesC8 & aText
) [static]

Writes a string of 8-bit characters to an open log.

Connects to the logging server, creates/opens the log file and writes aText to it.

This is a "static write".

Parameters

const TDesC & aDir The directory relative to 'C:\Logs\' where the log file resides.
const TDesC & aName The name of the log file.
TFileLoggingMode aMode The mode in which the log file should be opened: either EAppend or EOverwrite.
const TDesC8 & aText The 8-bit string to write to the log.

WriteFormat(TRefByValue< const TDesC16 >, ...)

IMPORT_C void WriteFormat ( TRefByValue < const TDesC16 > aFmt,
...
)

Formats the remaining arguments of the function according to aFmt, and writes the result to the log, iLogFile, if it is a valid file.

The format string aFmt contains literal text, embedded with directives, for converting the trailing list of arguments into text. The number and type of arguments is dictated by the structure of the directives in aFmt.

Note that the text will be converted to an 8 bit format for the log file.

Parameters

TRefByValue < const TDesC16 > aFmt The 16-bit non modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC16 type.
...

WriteFormat(TRefByValue< const TDesC16 >, VA_LIST &)

IMPORT_C void WriteFormat ( TRefByValue < const TDesC16 > aFmt,
VA_LIST & aList
)

Formats the arguments pointed to by aList according to aFmt, and writes the result to the log, iLogFile, if it is a valid file.

The format string aFmt contains literal text, embedded with directives, for converting the trailing list of arguments into text. The number and type of arguments pointed to by aList is dictated by the structure of the directives in aFmt.

Note that the text will be converted to an 8 bit format for the log file.

Parameters

TRefByValue < const TDesC16 > aFmt The 16-bit non modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC16 type.
VA_LIST & aList A pointer to an argument list.

WriteFormat(TRefByValue< const TDesC8 >, ...)

IMPORT_C void WriteFormat ( TRefByValue < const TDesC8 > aFmt,
...
)

Formats the remaining arguments of the function according to aFmt, and writes the result to the log, iLogFile, if it is a valid file.

The format string aFmt contains literal text, embedded with directives, for converting the trailing list of arguments into text. The number and type of arguments is dictated by the structure of the directives in aFmt.

Parameters

TRefByValue < const TDesC8 > aFmt The 8 bit non modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC8 type.
...

WriteFormat(TRefByValue< const TDesC8 >, VA_LIST &)

IMPORT_C void WriteFormat ( TRefByValue < const TDesC8 > aFmt,
VA_LIST & aList
)

Formats the arguments pointed to by aList according to aFmt, and writes the result to the log, iLogFile, if it is a valid file.

The format string aFmt contains literal text, embedded with directives, for converting the trailing list of arguments into text. The number and type of arguments pointed to by aList is dictated by the structure of the directives in aFmt.

Parameters

TRefByValue < const TDesC8 > aFmt The 8 bit non modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC8 type.
VA_LIST & aList A pointer to an argument list.

WriteFormat(const TDesC &, const TDesC &, TFileLoggingMode, TRefByValue< const TDesC16 >, ...)

IMPORT_C void WriteFormat ( const TDesC & aDir,
const TDesC & aName,
TFileLoggingMode aMode,
TRefByValue < const TDesC16 > aFmt,
...
) [static]

Formats the remaining arguments of the function according to aFmt and writes the result to the log.

The format string aFmt contains literal text, embedded with directives, for converting the trailing list of arguments into text. The number and type of arguments is dictated by the structure of the directives in aFmt.

Connects to the logging server, creates/opens the log file and writes the text arguments to it.

This is a "static write".

Note that the text will be converted to an 8 bit format for the log file.

Parameters

const TDesC & aDir The directory relative to 'C:\Logs\' where the log file resides.
const TDesC & aName The name of the log file.
TFileLoggingMode aMode The mode in which the log file should be opened: either EAppend or EOverwrite.
TRefByValue < const TDesC16 > aFmt The 16 bit non modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC16 type.
...

WriteFormat(const TDesC &, const TDesC &, TFileLoggingMode, TRefByValue< const TDesC16 >, VA_LIST &)

IMPORT_C void WriteFormat ( const TDesC & aDir,
const TDesC & aName,
TFileLoggingMode aMode,
TRefByValue < const TDesC16 > aFmt,
VA_LIST & aList
) [static]

Formats the arguments pointed to by aList according to aFmt, and writes the result to the log.

The format string aFmt contains literal text, embedded with directives, for converting the trailing list of arguments into text. The number and type of arguments pointed to by aList is dictated by the structure of the directives in aFmt.

Connects to the logging server, creates/opens the log file and writes the text arguments to it.

This is a "static write".

Note that the text will be converted to an 8 bit format for the log file.

Parameters

const TDesC & aDir The directory relative to 'C:\Logs\' where the log file resides.
const TDesC & aName The name of the log file.
TFileLoggingMode aMode The mode in which the log file should be opened: either EAppend or EOverwrite.
TRefByValue < const TDesC16 > aFmt The 16 bit non modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC16 type.
VA_LIST & aList A pointer to an argument list.

WriteFormat(const TDesC &, const TDesC &, TFileLoggingMode, TRefByValue< const TDesC8 >, ...)

IMPORT_C void WriteFormat ( const TDesC & aDir,
const TDesC & aName,
TFileLoggingMode aMode,
TRefByValue < const TDesC8 > aFmt,
...
) [static]

Formats the remaining arguments of the function according to aFmt and writes the result to the log.

The format string aFmt contains literal text, embedded with directives, for converting the trailing list of arguments into text. The number and type of arguments is dictated by the structure of the directives in aFmt.

Connects to the logging server, creates/opens the log file and writes the text arguments to it.

This is a "static write".

Parameters

const TDesC & aDir The directory relative to 'C:\Logs\' where the log file resides.
const TDesC & aName The name of the log file.
TFileLoggingMode aMode The mode in which the log file should be opened: either EAppend or EOverwrite.
TRefByValue < const TDesC8 > aFmt The 8 bit non modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC8 type.
...

WriteFormat(const TDesC &, const TDesC &, TFileLoggingMode, TRefByValue< const TDesC8 >, VA_LIST &)

IMPORT_C void WriteFormat ( const TDesC & aDir,
const TDesC & aName,
TFileLoggingMode aMode,
TRefByValue < const TDesC8 > aFmt,
VA_LIST & aList
) [static]

Formats the arguments pointed to by aList according to aFmt, and writes the result to the log.

The format string aFmt contains literal text, embedded with directives, for converting the trailing list of arguments into text. The number and type of arguments pointed to by aList is dictated by the structure of the directives in aFmt.

Connects to the logging server, creates/opens the log file and writes the text arguments to it.

This is a "static write".

Parameters

const TDesC & aDir The directory relative to 'C:\Logs\' where the log file resides.
const TDesC & aName The name of the log file.
TFileLoggingMode aMode The mode in which the log file should be opened: either EAppend or EOverwrite.
TRefByValue < const TDesC8 > aFmt The 8 bit non modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC8 type.
VA_LIST & aList A pointer to an argument list.

Member Data Documentation

TLogFormatter iFormatter

TLogFormatter iFormatter [private]

TInt iLastError

TInt iLastError [private]

TLogFile iLogFile

TLogFile iLogFile [private]

TBool iLogSTI

TBool iLogSTI [private]