<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-B0D76734-1DB7-5465-91AE-BB3521599A75" xml:lang="en"><title>Log

Engine Tutorial Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This overview provides the information to perform various tasks that clients

perform with Log Engine. </p>

<section id="GUID-976D4359-6836-5501-8C53-1C2B0E577160"><title>Purpose</title> <p>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. </p> </section>

<section id="GUID-61FEA51A-D091-59D7-A645-8E008E3A7C3E"><title>Introduction</title> <p>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. </p> <p>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. </p> <p>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. </p> <p>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 <xref href="GUID-51C67545-12BA-326D-BD8F-662B24C68ED2.dita"><apiname>CLogClient</apiname></xref> and

its parent class <xref href="GUID-4A7D312F-A8C6-3663-8455-13FA73F1CFB5.dita"><apiname>CLogBase</apiname></xref> are often wrapped in a class <xref href="GUID-146D719E-BDD6-3F20-80B1-EDE09081A6EA.dita"><apiname>CLogWrapper</apiname></xref> which

handles cases where logging functionality is absent. </p> <p>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. </p> <p>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. </p> <p>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. </p> <p>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. </p> <p>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. </p> <p>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. </p> </section>

<section id="GUID-F0F5CEB4-7BFD-5C7E-AEAE-B9A5EAC306B3"><title>Log clients

and log views</title> <p>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 <xref href="GUID-51C67545-12BA-326D-BD8F-662B24C68ED2.dita"><apiname>CLogClient</apiname></xref>, <xref href="GUID-4A7D312F-A8C6-3663-8455-13FA73F1CFB5.dita"><apiname>CLogBase</apiname></xref> and <xref href="GUID-146D719E-BDD6-3F20-80B1-EDE09081A6EA.dita"><apiname>CLogWrapper</apiname></xref>.

It is <xref href="GUID-51C67545-12BA-326D-BD8F-662B24C68ED2.dita"><apiname>CLogClient</apiname></xref> which contains the actual functionality:

the purpose of <xref href="GUID-4A7D312F-A8C6-3663-8455-13FA73F1CFB5.dita"><apiname>CLogBase</apiname></xref> and <xref href="GUID-146D719E-BDD6-3F20-80B1-EDE09081A6EA.dita"><apiname>CLogWrapper</apiname></xref> 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 <xref href="GUID-3A3E6F09-0F78-38E1-95F5-00C743F41073.dita"><apiname>CLogViewEvent</apiname></xref> and <xref href="GUID-F40F9556-F223-36A5-9812-6EF6FF3F5156.dita"><apiname>CLogViewRecent</apiname></xref>,

which inherit from a class <xref href="GUID-F33ADAF2-FD57-3662-B3AC-1000B69289D6.dita"><apiname>CLogView</apiname></xref> which cannot be instantiated. </p> </section>

<section id="GUID-D511597A-013F-5ECA-97C5-A75770575EFF"><title>Events and

event types</title> <p>The log engine is designed to log events having to

do with communications: messaging, telephony, email and so on. The class <xref href="GUID-CDFB61A7-1C74-3F63-9FDF-5A3B8603A010.dita"><apiname>CLogEvent</apiname></xref> represents

events of this kind: its member objects mainly have to do with types of communication.

The class <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> contains information about the

event type which a particular event belongs to. </p> <p><b>Log

events</b> </p> <p>The <xref href="GUID-CDFB61A7-1C74-3F63-9FDF-5A3B8603A010.dita"><apiname>CLogEvent</apiname></xref> class encapsulates data

about communication events. </p> <ul>

<li id="GUID-0B904A94-48BE-5534-81C0-B3103B33EA06"><p>The ID is the unique

identifier of the event. </p> </li>

<li id="GUID-FC68C424-C8B8-51AC-96E0-498C59AEB905"><p>The remote party is

the device originating or receiving the communication. </p> </li>

<li id="GUID-E362093C-3618-5EF6-977C-9FA6FA9384EA"><p>The direction indicates

whether the communication is incoming or outgoing. </p> </li>

<li id="GUID-1007760C-A467-5697-8F5D-5EE586959B66"><p>The time of the event

is the time at which it began. </p> </li>

<li id="GUID-3D3A7537-1F54-5F36-AFD1-1B6D29B236E2"><p>The duration type is

one of three constants: <xref href="GUID-8ADA7A0F-0A96-3B80-B09F-F01ACA7CB51C.dita"><apiname>KLogDurationNone</apiname></xref>, <xref href="GUID-F9F30026-EBA8-334C-B926-95886F9D0B82.dita"><apiname>KLogDurationData</apiname></xref> or <xref href="GUID-8F476C11-5DEA-3690-84D2-F3C56A5ECDEE.dita"><apiname>KLogDurationValid</apiname></xref>.

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). </p> </li>

<li id="GUID-6184A320-07E4-5968-B92E-79619C4593ED"><p>The duration is the

duration in seconds from the start of the event to the end. </p> </li>

<li id="GUID-79D55852-1670-540D-901C-54EF22DC0A80"><p>The delivery status

is one of a set of flags indicating whether the communication was successfully

delivered. </p> </li>

<li id="GUID-FF64F139-E294-5D35-97D5-FCDB41FF56AC"><p>The subject is a string

to be displayed in the subject line of the viewer application. </p> </li>

<li id="GUID-2F387309-992C-5E97-9C11-D579E2786E00"><p>The log link is the

ID of the event in the calling application, as distinct from its ID in the

log. </p> </li>

<li id="GUID-D14F2BB8-EE85-57AE-B8C1-F5CEB0E039CF"><p>The description is a

human readable description of the event type. </p> </li>

<li id="GUID-485D6CB5-1433-5A4A-B9F6-2292F05BD878"><p>There is only one flag, <xref href="GUID-D593DD54-B0A6-38A2-BC17-5D4542343A67.dita"><apiname>KLogEventRead</apiname></xref>,

which is set to true if the event has been read by a client. It can be cleared

either by passing the constant <xref href="GUID-1FB349A5-F3D2-3D75-BB6A-9BA3AD1F30B6.dita"><apiname>KLogFlagsMask</apiname></xref> to the function <xref href="GUID-E6477727-53AA-3092-AB4E-54E2EC50C891.dita"><apiname>SetFlags()</apiname></xref> or

by calling the function <xref href="GUID-AD7C319E-5ACA-3D1C-B000-AD45B388FA4E.dita"><apiname>ClearFlags()</apiname></xref>. </p> </li>

</ul> <p><b>Log

event types</b> </p> <p>The log engine API defines constants of type <xref href="GUID-530281E6-29FC-33F2-BC9B-610FBA389444.dita"><apiname>TUid</apiname></xref> representing

the standard types of communication event which can be logged. </p> <ul>

<li id="GUID-DCCB5455-5251-5394-8E36-BB0493D230A2"><p> <xref href="GUID-5A0DEBDD-EE90-336A-8990-0C8E65D87B8D.dita"><apiname>KLogCallEventType</apiname></xref>:

voice call </p> </li>

<li id="GUID-345EF3F1-9FAA-530F-B13E-086333EB16B2"><p> <xref href="GUID-95C9EA37-216C-3012-8579-D27EDE985F37.dita"><apiname>KLogDataEventType</apiname></xref>:

data call </p> </li>

<li id="GUID-95B204BD-D1CD-528D-BCE4-2202C8B6C70A"><p> <xref href="GUID-1F4D6F37-7095-37D1-9CFD-4C612854F1D9.dita"><apiname>KLogFaxEventType</apiname></xref>:

fax call </p> </li>

<li id="GUID-D7A6070F-96ED-57B0-B4AC-16BD30182EEB"><p> <xref href="GUID-9939CC72-09CF-3AAE-A7B7-BCA1FC036BB7.dita"><apiname>KLogShortMessageEventType</apiname></xref>:

SMS call </p> </li>

<li id="GUID-355B1AF2-403D-5EF7-9656-E526E5C9FFAA"><p> <xref href="GUID-95E66461-EBD7-3843-AD05-D632AB113F2A.dita"><apiname>KLogMailEventType</apiname></xref>:

email </p> </li>

<li id="GUID-95FC2F4A-0D7F-5378-AF50-38F40440347F"><p> <xref href="GUID-EA11EA32-F6A1-3C57-8C20-98E9D98F5ED8.dita"><apiname>KLogTaskSchedulerEventType</apiname></xref>:

task scheduler event </p> </li>

</ul> <p>The log engine API provides the class <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> which

acts on all events of a specified type. Its functions are: </p> <ul>

<li id="GUID-06AFACB8-A994-5A60-BD35-35D1054118FD"><p> <xref href="GUID-260722ED-60D9-37EB-A95C-6F0BF4692D97.dita"><apiname>Uid()</apiname></xref> and <xref href="GUID-05D6F7AA-878A-32D6-BD81-C8D30838FB71.dita"><apiname>SetUid()</apiname></xref> get

and set the UID identifying the event type. </p> </li>

<li id="GUID-480DAE38-65A8-52A1-ADCF-6B70ED1D08F4"><p> <xref href="GUID-E7339978-FFE8-3C38-818A-FEE7CBDAE34A.dita"><apiname>Description()</apiname></xref> and <xref href="GUID-37D64FF2-A036-3511-B7B3-54BC33DF0805.dita"><apiname>SetDescription()</apiname></xref> get

and set the description in words of the event type. </p> </li>

<li id="GUID-B6C7ACBC-080D-5295-8E1B-E0DCA546F3E2"><p> <xref href="GUID-D498B4D9-7106-396F-B750-CB7BFAB26851.dita"><apiname>LoggingEnabled()</apiname></xref> and <xref href="GUID-E366A706-736E-3530-88B3-26727B8D9C17.dita"><apiname>SetLoggingEnabled()</apiname></xref> get

and set a flag which enables events of this type to be logged. </p> </li>

<li id="GUID-F2C2D7A2-A0DE-59D3-BD25-0D794D7566F1"><p> <xref href="GUID-CD3C9BD5-1386-3CF5-A8F6-9BE1AE40689F.dita"><apiname>Copy()</apiname></xref> copies

an existing event type. </p> </li>

<li id="GUID-EB4393F4-02E7-5422-85C0-7B3FEC0D2D6A"><p> <xref href="GUID-B677E528-7C32-3483-8B30-F1CDC6875B03.dita"><apiname>InternaliseL()</apiname></xref> and <xref href="GUID-0304F040-A7C1-3911-ACA3-6A75FBDB8ACF.dita"><apiname>ExternaliseL()</apiname></xref> implement

streaming input and output of an event type object. </p> </li>

</ul> <p>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 <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> and

pass the Id to <xref href="GUID-05D6F7AA-878A-32D6-BD81-C8D30838FB71.dita"><apiname>SetUid()</apiname></xref> just like the standard event type

constants. </p> <p>The main use of <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> is to

enable or disable logging for all events of a particular type. You do this

by creating a <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> object with its UID set to

the relevant event type and calling its <xref href="GUID-E366A706-736E-3530-88B3-26727B8D9C17.dita"><apiname>SetLoggingEnabled()</apiname></xref> function

with <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref> or <xref href="GUID-A759CA2D-8327-348F-9337-4886E619D920.dita"><apiname>EFalse</apiname></xref> as argument. </p> <p>It

is important to know that only an explicit call to the <xref href="GUID-E366A706-736E-3530-88B3-26727B8D9C17.dita"><apiname>SetLoggingEnabled()</apiname></xref> function

of a <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> object will cause logging to take place.

For instance if you create a new event type <xref href="GUID-C2D1CC20-9AF0-3B02-B42B-BE96534F44DE.dita"><apiname>myEventType</apiname></xref> and

want such events to be logged, you have to call its <xref href="GUID-E366A706-736E-3530-88B3-26727B8D9C17.dita"><apiname>SetLoggingEnabled()</apiname></xref> function

before logging will occur. </p> <codeblock id="GUID-F3C05730-5CB0-51A0-8975-311D64C21213" xml:space="preserve">    CLogEventType* myEventType = CLogEventType::NewL();myEventType-&gt;SetLoggingEnabled(ETrue);</codeblock> </section>

<section id="GUID-5CE676D6-7F07-5C37-99F7-A17C2FC9185C"><title>Log engine

and platform security</title> <p>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. </p> <p>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 <xref href="GUID-51C67545-12BA-326D-BD8F-662B24C68ED2.dita#GUID-51C67545-12BA-326D-BD8F-662B24C68ED2/GUID-034027BA-BD4B-331B-8F1D-1B5750FD2BCD"><apiname>CLogClient::GetEvent()</apiname></xref> must have the

capability specified in the read policy of the event type, while calls to <xref href="GUID-91804418-6DCC-3ACF-BA1E-399B112285A3.dita"><apiname>AddEvent()</apiname></xref>, <xref href="GUID-C8F2B567-6B68-3460-9799-6658DF3771A8.dita"><apiname>ChangeEvent()</apiname></xref> and <xref href="GUID-EC15284E-B1CF-3DB6-87C1-E639F270E434.dita"><apiname>DeleteEvent()</apiname></xref> must have the capability specified in the write policy.

To modify the event type by calling <xref href="GUID-1AC902E9-EAE0-329A-A69E-6823A317DEE8.dita"><apiname>AddEventType()</apiname></xref>, <xref href="GUID-966DB6EC-CE70-3F08-A4D1-30F76AF5A54F.dita"><apiname>ChangeEventType()</apiname></xref> and <xref href="GUID-FA3CA920-0F43-3B7C-8171-905BC8C8C2A4.dita"><apiname>DeleteEventType()</apiname></xref> a calling application requires the <xref href="GUID-7BA52F1C-159D-3F72-91A3-1A2B5870C48B.dita"><apiname>WriteDeviceData</apiname></xref> capability.

No capability is required to call <xref href="GUID-BF3481A7-85D0-3431-81C8-905FF0D40887.dita"><apiname>GetEventType()</apiname></xref>. </p> <p>No

security capability is required to access the view classes. </p> </section>

<section id="GUID-4B5E20B7-5689-5AB1-B265-9C9956B32635"><title>Using filters

when displaying a log</title> <p>An event view typically contains only a selection

of items from the main log which satisfy the constraints of a filter. A <xref href="GUID-99144BA6-F79A-3D3C-B1D3-272B3723C42C.dita"><apiname>CLogFilter</apiname></xref> has

members representing the same information as a <xref href="GUID-CDFB61A7-1C74-3F63-9FDF-5A3B8603A010.dita"><apiname>CLogEvent</apiname></xref> 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 <xref href="GUID-99144BA6-F79A-3D3C-B1D3-272B3723C42C.dita"><apiname>CLogFilter</apiname></xref> object

and then pass this as a parameter of the <xref href="GUID-409E06DF-141C-3352-8E31-87646F9C2DCA.dita"><apiname>SetFilterL()</apiname></xref> 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 <xref href="GUID-84D55725-6357-3596-B1DE-3F3388884504.dita"><apiname>CLogFilterList</apiname></xref>:

this is an array of several <xref href="GUID-99144BA6-F79A-3D3C-B1D3-272B3723C42C.dita"><apiname>CLogFilter</apiname></xref> 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 <xref href="GUID-99144BA6-F79A-3D3C-B1D3-272B3723C42C.dita"><apiname>CLogFilter</apiname></xref> only

has one event type. </p> </section>

<section id="GUID-695967C7-72D9-4026-B719-A756CB89060B"><ol id="GUID-DB02C018-8542-5E49-AB88-44708F78AF3F">

<li id="GUID-0A180E8B-8D5F-5C74-BCF3-24F5387B3F73"><p><xref href="GUID-BCB0E50F-B22E-5964-BB68-BEE1870D9C79.dita">Configuring

Log Engine </xref>  </p> <p>The clients must configure the Log Engine before

using it. </p> </li>

<li id="GUID-5920F750-32FE-537B-90E1-AA9A5814FF01"><p><xref href="GUID-2022F702-9899-5798-8932-D70119C7177D.dita">Setting

Up A Log Engine Client</xref>  </p> <p>After configuring the log engine, a

log engine client must be developed. </p> </li>

<li id="GUID-2449AFDC-998A-51CF-A81C-B9209445895C"><p><xref href="GUID-E4A950EA-5671-5755-B3EF-5D6B90E19AE6.dita">Maintaining

Log Events</xref>  </p> <p>The client applications can then add event, event

types and delete if necessary. </p> </li>

<li id="GUID-B87FA355-BD1B-5595-8FD5-008D281A5D6A"><p><xref href="GUID-BE65B3A7-04E8-5406-B46A-09E2608E0F1F.dita">Requesting

Log Engine Notifications</xref> </p> <p>Client applications can receive notification

from log engine to get events recorded by other applications. </p> </li>

<li id="GUID-5E27A02E-D120-5410-A1F6-54909E9F8324"><p><xref href="GUID-55ECBCF5-FC29-5A4A-A3C6-1CB1C0D562CE.dita">Displaying

Log Events</xref>  </p> <p>Finally the client applications can then display

the log events to the user. </p> </li>

</ol> </section>