--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-B0D76734-1DB7-5465-91AE-BB3521599A75.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,192 @@
+<?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>
+</conbody></concept>
\ No newline at end of file