Log -Engine Tutorial Overview

This overview provides the information to perform various tasks that clients -perform with Log Engine.

Purpose

The -log engine stores events generated by operating system components, particularly -telephony and messaging. This document explains how to use the log engine -to create a record of events and how to create views of the events for display.

Introduction

The -log engine uses a client-server architecture. The log server is a permanent -process maintaining event data and the log clients attach to it to add and -retrieve data. When writing an application which uses the log engine you create -a log client wrapped in a customized component. This component has two purposes. -Firstly it causes the server to log events of a specified kind. Secondly it -uses log filter and log view classes to extract and present the data appropriately.

The -log engine is designed to abstract from the details of how events are notified, -stored and displayed. You do not need to know exactly how this functionality -is implemented.

The log engine is an interface to a database holding -records of communication events. You do not need to know the implementation -of the database, merely that the log engine has functionality to add, read, -modify and delete records.

Not all devices are equipped with logging -functionality. You need to determine whether your application will only run -on platforms with logging functionality guaranteed or else write the application -so as to fail gracefully. For this reason the class CLogClient and -its parent class CLogBase are often wrapped in a class CLogWrapper which -handles cases where logging functionality is absent.

Logging calls -are asynchronous. The application developer is responsible for maintaining -the integrity of the log client session. A typical way of doing this is to -maintain a queue of log events.

The log engine provides limited configuration -functionality. If you are involved in device creation and want to tune performance -you need to know how to manage memory and configure the logging component -explicitly: the topic is not covered in this document.

The log engine -models standard types of communication event by default. If your application -involves non-standard functionality you need to know how to create user defined -data types to represent non-standard events.

The log engine uses the -Symbian platform capabilities model of security. This means that your application -must police its own security and you must therefore know the security capabilities -required by each item of functionality.

The purpose of the log engine -is to provide data for a viewer application which displays information such -as missed calls to the end user of the device. You do not need to know anything -about the viewer, merely that it requires data views to be provided in certain -data structures.

The log engine gets updated by an observer component -which notifies it of new communication events affecting either the data tables -or the views created from them. You do not need to know the details of the -interprocess communication, merely that an observer component exists and performs -notifications.

Log clients -and log views

The log engine API consists of two types of classes, -the client classes and the view classes. The client classes exist to create -logs and maintain and modify them. They are CLogClient, CLogBase and CLogWrapper. -It is CLogClient which contains the actual functionality: -the purpose of CLogBase and CLogWrapper is -to provide default functionality when logging functionality is not available. -The view classes exist to filter the log data and prepare it for presentation -in a viewer application. They are CLogViewEvent and CLogViewRecent, -which inherit from a class CLogView which cannot be instantiated.

Events and -event types

The log engine is designed to log events having to -do with communications: messaging, telephony, email and so on. The class CLogEvent represents -events of this kind: its member objects mainly have to do with types of communication. -The class CLogEventType contains information about the -event type which a particular event belongs to.

Log -events

The CLogEvent class encapsulates data -about communication events.

The ID is the unique -identifier of the event.
The remote party is -the device originating or receiving the communication.
The direction indicates -whether the communication is incoming or outgoing.
The time of the event -is the time at which it began.
The duration type is -one of three constants: KLogDurationNone, KLogDurationData or KLogDurationValid. -You typically use them where the event being represented either has no duration, -or has a duration of no relevance (such as a data transfer), or has a valid -duration (such as a voice call).
The duration is the -duration in seconds from the start of the event to the end.
The delivery status -is one of a set of flags indicating whether the communication was successfully -delivered.
The subject is a string -to be displayed in the subject line of the viewer application.
The log link is the -ID of the event in the calling application, as distinct from its ID in the -log.
The description is a -human readable description of the event type.
There is only one flag, KLogEventRead, -which is set to true if the event has been read by a client. It can be cleared -either by passing the constant KLogFlagsMask to the function SetFlags() or -by calling the function ClearFlags().

Log -event types

The log engine API defines constants of type TUid representing -the standard types of communication event which can be logged.

KLogCallEventType: -voice call
KLogDataEventType: -data call
KLogFaxEventType: -fax call
KLogShortMessageEventType: -SMS call
KLogMailEventType: -email
KLogTaskSchedulerEventType: -task scheduler event

The log engine API provides the class CLogEventType which -acts on all events of a specified type. Its functions are:

Uid() and SetUid() get -and set the UID identifying the event type.
Description() and SetDescription() get -and set the description in words of the event type.
LoggingEnabled() and SetLoggingEnabled() get -and set a flag which enables events of this type to be logged.
Copy() copies -an existing event type.
InternaliseL() and ExternaliseL() implement -streaming input and output of an event type object.

You may need an event type not supplied with the log engine API, -for instance if you are developing a new kind of messaging application. A -new event type requires a new unique Id which must be allocated by Symbian -Signed. Once you have that Id you can create a CLogEventType and -pass the Id to SetUid() just like the standard event type -constants.

The main use of CLogEventType is to -enable or disable logging for all events of a particular type. You do this -by creating a CLogEventType object with its UID set to -the relevant event type and calling its SetLoggingEnabled() function -with ETrue or EFalse as argument.

It -is important to know that only an explicit call to the SetLoggingEnabled() function -of a CLogEventType object will cause logging to take place. -For instance if you create a new event type myEventType and -want such events to be logged, you have to call its SetLoggingEnabled() function -before logging will occur.

CLogEventType* myEventType = CLogEventType::NewL();myEventType->SetLoggingEnabled(ETrue);

Log engine -and platform security

The Symbian platform uses a capabilities -model of security in which an application being called verifies that the calling -application has the required security policies before returning data. This -is important in connection with message logging which involves the end user's -confidential information. When writing an application which incorporates logging -functionality you must ensure that it has the capabilities to call the log -engine APIs.

To call a log client, a calling application must have -the capabilities required by the event type of the event being accessed. This -means that a call to CLogClient::GetEvent() must have the -capability specified in the read policy of the event type, while calls to AddEvent(), ChangeEvent() and DeleteEvent() must have the capability specified in the write policy. -To modify the event type by calling AddEventType(), ChangeEventType() and DeleteEventType() a calling application requires the WriteDeviceData capability. -No capability is required to call GetEventType().

No -security capability is required to access the view classes.

Using filters -when displaying a log

An event view typically contains only a selection -of items from the main log which satisfy the constraints of a filter. A CLogFilter has -members representing the same information as a CLogEvent object -but is used to select on data not modify it. (In the database implementation, -a filter corresponds to the WHERE clause of a SELECT query.) An event view -is empty when created. To initialize it you first create and initialize a CLogFilter object -and then pass this as a parameter of the SetFilterL() function -of the event view. You may also want to initialize a view to satisfy any one -of several filters, in which case you pass in a CLogFilterList: -this is an array of several CLogFilter objects. You would -do this, for instance, if you wanted to create a view to display events of -several different event types such as voice mail, SMS and email, since a single CLogFilter only -has one event type.

Configuring -Log Engine

The clients must configure the Log Engine before -using it.
Setting -Up A Log Engine Client

After configuring the log engine, a -log engine client must be developed.
Maintaining -Log Events

The client applications can then add event, event -types and delete if necessary.
Requesting -Log Engine Notifications

Client applications can receive notification -from log engine to get events recorded by other applications.
Displaying -Log Events

Finally the client applications can then display -the log events to the user.

+ + + + + +Log +Engine Tutorial Overview +

This overview provides the information to perform various tasks that clients +perform with Log Engine.

Purpose

The +log engine stores events generated by operating system components, particularly +telephony and messaging. This document explains how to use the log engine +to create a record of events and how to create views of the events for display.

Introduction

The +log engine uses a client-server architecture. The log server is a permanent +process maintaining event data and the log clients attach to it to add and +retrieve data. When writing an application which uses the log engine you create +a log client wrapped in a customized component. This component has two purposes. +Firstly it causes the server to log events of a specified kind. Secondly it +uses log filter and log view classes to extract and present the data appropriately.

The +log engine is designed to abstract from the details of how events are notified, +stored and displayed. You do not need to know exactly how this functionality +is implemented.

The log engine is an interface to a database holding +records of communication events. You do not need to know the implementation +of the database, merely that the log engine has functionality to add, read, +modify and delete records.

Not all devices are equipped with logging +functionality. You need to determine whether your application will only run +on platforms with logging functionality guaranteed or else write the application +so as to fail gracefully. For this reason the class CLogClient and +its parent class CLogBase are often wrapped in a class CLogWrapper which +handles cases where logging functionality is absent.

Logging calls +are asynchronous. The application developer is responsible for maintaining +the integrity of the log client session. A typical way of doing this is to +maintain a queue of log events.

The log engine provides limited configuration +functionality. If you are involved in device creation and want to tune performance +you need to know how to manage memory and configure the logging component +explicitly: the topic is not covered in this document.

The log engine +models standard types of communication event by default. If your application +involves non-standard functionality you need to know how to create user defined +data types to represent non-standard events.

The log engine uses the +Symbian platform capabilities model of security. This means that your application +must police its own security and you must therefore know the security capabilities +required by each item of functionality.

The purpose of the log engine +is to provide data for a viewer application which displays information such +as missed calls to the end user of the device. You do not need to know anything +about the viewer, merely that it requires data views to be provided in certain +data structures.

The log engine gets updated by an observer component +which notifies it of new communication events affecting either the data tables +or the views created from them. You do not need to know the details of the +interprocess communication, merely that an observer component exists and performs +notifications.

Log clients +and log views

The log engine API consists of two types of classes, +the client classes and the view classes. The client classes exist to create +logs and maintain and modify them. They are CLogClient, CLogBase and CLogWrapper. +It is CLogClient which contains the actual functionality: +the purpose of CLogBase and CLogWrapper is +to provide default functionality when logging functionality is not available. +The view classes exist to filter the log data and prepare it for presentation +in a viewer application. They are CLogViewEvent and CLogViewRecent, +which inherit from a class CLogView which cannot be instantiated.

Events and +event types

The log engine is designed to log events having to +do with communications: messaging, telephony, email and so on. The class CLogEvent represents +events of this kind: its member objects mainly have to do with types of communication. +The class CLogEventType contains information about the +event type which a particular event belongs to.

Log +events

The CLogEvent class encapsulates data +about communication events.

The ID is the unique +identifier of the event.
The remote party is +the device originating or receiving the communication.
The direction indicates +whether the communication is incoming or outgoing.
The time of the event +is the time at which it began.
The duration type is +one of three constants: KLogDurationNone, KLogDurationData or KLogDurationValid. +You typically use them where the event being represented either has no duration, +or has a duration of no relevance (such as a data transfer), or has a valid +duration (such as a voice call).
The duration is the +duration in seconds from the start of the event to the end.
The delivery status +is one of a set of flags indicating whether the communication was successfully +delivered.
The subject is a string +to be displayed in the subject line of the viewer application.
The log link is the +ID of the event in the calling application, as distinct from its ID in the +log.
The description is a +human readable description of the event type.
There is only one flag, KLogEventRead, +which is set to true if the event has been read by a client. It can be cleared +either by passing the constant KLogFlagsMask to the function SetFlags() or +by calling the function ClearFlags().

Log +event types

The log engine API defines constants of type TUid representing +the standard types of communication event which can be logged.

KLogCallEventType: +voice call
KLogDataEventType: +data call
KLogFaxEventType: +fax call
KLogShortMessageEventType: +SMS call
KLogMailEventType: +email
KLogTaskSchedulerEventType: +task scheduler event

The log engine API provides the class CLogEventType which +acts on all events of a specified type. Its functions are:

Uid() and SetUid() get +and set the UID identifying the event type.
Description() and SetDescription() get +and set the description in words of the event type.
LoggingEnabled() and SetLoggingEnabled() get +and set a flag which enables events of this type to be logged.
Copy() copies +an existing event type.
InternaliseL() and ExternaliseL() implement +streaming input and output of an event type object.

You may need an event type not supplied with the log engine API, +for instance if you are developing a new kind of messaging application. A +new event type requires a new unique Id which must be allocated by Symbian +Signed. Once you have that Id you can create a CLogEventType and +pass the Id to SetUid() just like the standard event type +constants.

The main use of CLogEventType is to +enable or disable logging for all events of a particular type. You do this +by creating a CLogEventType object with its UID set to +the relevant event type and calling its SetLoggingEnabled() function +with ETrue or EFalse as argument.

It +is important to know that only an explicit call to the SetLoggingEnabled() function +of a CLogEventType object will cause logging to take place. +For instance if you create a new event type myEventType and +want such events to be logged, you have to call its SetLoggingEnabled() function +before logging will occur.

CLogEventType* myEventType = CLogEventType::NewL();myEventType->SetLoggingEnabled(ETrue);

Log engine +and platform security

The Symbian platform uses a capabilities +model of security in which an application being called verifies that the calling +application has the required security policies before returning data. This +is important in connection with message logging which involves the end user's +confidential information. When writing an application which incorporates logging +functionality you must ensure that it has the capabilities to call the log +engine APIs.

To call a log client, a calling application must have +the capabilities required by the event type of the event being accessed. This +means that a call to CLogClient::GetEvent() must have the +capability specified in the read policy of the event type, while calls to AddEvent(), ChangeEvent() and DeleteEvent() must have the capability specified in the write policy. +To modify the event type by calling AddEventType(), ChangeEventType() and DeleteEventType() a calling application requires the WriteDeviceData capability. +No capability is required to call GetEventType().

No +security capability is required to access the view classes.

Using filters +when displaying a log

An event view typically contains only a selection +of items from the main log which satisfy the constraints of a filter. A CLogFilter has +members representing the same information as a CLogEvent object +but is used to select on data not modify it. (In the database implementation, +a filter corresponds to the WHERE clause of a SELECT query.) An event view +is empty when created. To initialize it you first create and initialize a CLogFilter object +and then pass this as a parameter of the SetFilterL() function +of the event view. You may also want to initialize a view to satisfy any one +of several filters, in which case you pass in a CLogFilterList: +this is an array of several CLogFilter objects. You would +do this, for instance, if you wanted to create a view to display events of +several different event types such as voice mail, SMS and email, since a single CLogFilter only +has one event type.

Configuring +Log Engine

The clients must configure the Log Engine before +using it.
Setting +Up A Log Engine Client

After configuring the log engine, a +log engine client must be developed.
Maintaining +Log Events

The client applications can then add event, event +types and delete if necessary.
Requesting +Log Engine Notifications

Client applications can receive notification +from log engine to get events recorded by other applications.
Displaying +Log Events

Finally the client applications can then display +the log events to the user.

\ No newline at end of file