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.