|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-B0D76734-1DB7-5465-91AE-BB3521599A75" xml:lang="en"><title>Log |
|
13 Engine Tutorial Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This overview provides the information to perform various tasks that clients |
|
15 perform with Log Engine. </p> |
|
16 <section id="GUID-976D4359-6836-5501-8C53-1C2B0E577160"><title>Purpose</title> <p>The |
|
17 log engine stores events generated by operating system components, particularly |
|
18 telephony and messaging. This document explains how to use the log engine |
|
19 to create a record of events and how to create views of the events for display. </p> </section> |
|
20 <section id="GUID-61FEA51A-D091-59D7-A645-8E008E3A7C3E"><title>Introduction</title> <p>The |
|
21 log engine uses a client-server architecture. The log server is a permanent |
|
22 process maintaining event data and the log clients attach to it to add and |
|
23 retrieve data. When writing an application which uses the log engine you create |
|
24 a log client wrapped in a customized component. This component has two purposes. |
|
25 Firstly it causes the server to log events of a specified kind. Secondly it |
|
26 uses log filter and log view classes to extract and present the data appropriately. </p> <p>The |
|
27 log engine is designed to abstract from the details of how events are notified, |
|
28 stored and displayed. You do not need to know exactly how this functionality |
|
29 is implemented. </p> <p>The log engine is an interface to a database holding |
|
30 records of communication events. You do not need to know the implementation |
|
31 of the database, merely that the log engine has functionality to add, read, |
|
32 modify and delete records. </p> <p>Not all devices are equipped with logging |
|
33 functionality. You need to determine whether your application will only run |
|
34 on platforms with logging functionality guaranteed or else write the application |
|
35 so as to fail gracefully. For this reason the class <xref href="GUID-51C67545-12BA-326D-BD8F-662B24C68ED2.dita"><apiname>CLogClient</apiname></xref> and |
|
36 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 |
|
37 handles cases where logging functionality is absent. </p> <p>Logging calls |
|
38 are asynchronous. The application developer is responsible for maintaining |
|
39 the integrity of the log client session. A typical way of doing this is to |
|
40 maintain a queue of log events. </p> <p>The log engine provides limited configuration |
|
41 functionality. If you are involved in device creation and want to tune performance |
|
42 you need to know how to manage memory and configure the logging component |
|
43 explicitly: the topic is not covered in this document. </p> <p>The log engine |
|
44 models standard types of communication event by default. If your application |
|
45 involves non-standard functionality you need to know how to create user defined |
|
46 data types to represent non-standard events. </p> <p>The log engine uses the |
|
47 Symbian platform capabilities model of security. This means that your application |
|
48 must police its own security and you must therefore know the security capabilities |
|
49 required by each item of functionality. </p> <p>The purpose of the log engine |
|
50 is to provide data for a viewer application which displays information such |
|
51 as missed calls to the end user of the device. You do not need to know anything |
|
52 about the viewer, merely that it requires data views to be provided in certain |
|
53 data structures. </p> <p>The log engine gets updated by an observer component |
|
54 which notifies it of new communication events affecting either the data tables |
|
55 or the views created from them. You do not need to know the details of the |
|
56 interprocess communication, merely that an observer component exists and performs |
|
57 notifications. </p> </section> |
|
58 <section id="GUID-F0F5CEB4-7BFD-5C7E-AEAE-B9A5EAC306B3"><title>Log clients |
|
59 and log views</title> <p>The log engine API consists of two types of classes, |
|
60 the client classes and the view classes. The client classes exist to create |
|
61 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>. |
|
62 It is <xref href="GUID-51C67545-12BA-326D-BD8F-662B24C68ED2.dita"><apiname>CLogClient</apiname></xref> which contains the actual functionality: |
|
63 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 |
|
64 to provide default functionality when logging functionality is not available. |
|
65 The view classes exist to filter the log data and prepare it for presentation |
|
66 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>, |
|
67 which inherit from a class <xref href="GUID-F33ADAF2-FD57-3662-B3AC-1000B69289D6.dita"><apiname>CLogView</apiname></xref> which cannot be instantiated. </p> </section> |
|
68 <section id="GUID-D511597A-013F-5ECA-97C5-A75770575EFF"><title>Events and |
|
69 event types</title> <p>The log engine is designed to log events having to |
|
70 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 |
|
71 events of this kind: its member objects mainly have to do with types of communication. |
|
72 The class <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> contains information about the |
|
73 event type which a particular event belongs to. </p> <p><b>Log |
|
74 events</b> </p> <p>The <xref href="GUID-CDFB61A7-1C74-3F63-9FDF-5A3B8603A010.dita"><apiname>CLogEvent</apiname></xref> class encapsulates data |
|
75 about communication events. </p> <ul> |
|
76 <li id="GUID-0B904A94-48BE-5534-81C0-B3103B33EA06"><p>The ID is the unique |
|
77 identifier of the event. </p> </li> |
|
78 <li id="GUID-FC68C424-C8B8-51AC-96E0-498C59AEB905"><p>The remote party is |
|
79 the device originating or receiving the communication. </p> </li> |
|
80 <li id="GUID-E362093C-3618-5EF6-977C-9FA6FA9384EA"><p>The direction indicates |
|
81 whether the communication is incoming or outgoing. </p> </li> |
|
82 <li id="GUID-1007760C-A467-5697-8F5D-5EE586959B66"><p>The time of the event |
|
83 is the time at which it began. </p> </li> |
|
84 <li id="GUID-3D3A7537-1F54-5F36-AFD1-1B6D29B236E2"><p>The duration type is |
|
85 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>. |
|
86 You typically use them where the event being represented either has no duration, |
|
87 or has a duration of no relevance (such as a data transfer), or has a valid |
|
88 duration (such as a voice call). </p> </li> |
|
89 <li id="GUID-6184A320-07E4-5968-B92E-79619C4593ED"><p>The duration is the |
|
90 duration in seconds from the start of the event to the end. </p> </li> |
|
91 <li id="GUID-79D55852-1670-540D-901C-54EF22DC0A80"><p>The delivery status |
|
92 is one of a set of flags indicating whether the communication was successfully |
|
93 delivered. </p> </li> |
|
94 <li id="GUID-FF64F139-E294-5D35-97D5-FCDB41FF56AC"><p>The subject is a string |
|
95 to be displayed in the subject line of the viewer application. </p> </li> |
|
96 <li id="GUID-2F387309-992C-5E97-9C11-D579E2786E00"><p>The log link is the |
|
97 ID of the event in the calling application, as distinct from its ID in the |
|
98 log. </p> </li> |
|
99 <li id="GUID-D14F2BB8-EE85-57AE-B8C1-F5CEB0E039CF"><p>The description is a |
|
100 human readable description of the event type. </p> </li> |
|
101 <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>, |
|
102 which is set to true if the event has been read by a client. It can be cleared |
|
103 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 |
|
104 by calling the function <xref href="GUID-AD7C319E-5ACA-3D1C-B000-AD45B388FA4E.dita"><apiname>ClearFlags()</apiname></xref>. </p> </li> |
|
105 </ul> <p><b>Log |
|
106 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 |
|
107 the standard types of communication event which can be logged. </p> <ul> |
|
108 <li id="GUID-DCCB5455-5251-5394-8E36-BB0493D230A2"><p> <xref href="GUID-5A0DEBDD-EE90-336A-8990-0C8E65D87B8D.dita"><apiname>KLogCallEventType</apiname></xref>: |
|
109 voice call </p> </li> |
|
110 <li id="GUID-345EF3F1-9FAA-530F-B13E-086333EB16B2"><p> <xref href="GUID-95C9EA37-216C-3012-8579-D27EDE985F37.dita"><apiname>KLogDataEventType</apiname></xref>: |
|
111 data call </p> </li> |
|
112 <li id="GUID-95B204BD-D1CD-528D-BCE4-2202C8B6C70A"><p> <xref href="GUID-1F4D6F37-7095-37D1-9CFD-4C612854F1D9.dita"><apiname>KLogFaxEventType</apiname></xref>: |
|
113 fax call </p> </li> |
|
114 <li id="GUID-D7A6070F-96ED-57B0-B4AC-16BD30182EEB"><p> <xref href="GUID-9939CC72-09CF-3AAE-A7B7-BCA1FC036BB7.dita"><apiname>KLogShortMessageEventType</apiname></xref>: |
|
115 SMS call </p> </li> |
|
116 <li id="GUID-355B1AF2-403D-5EF7-9656-E526E5C9FFAA"><p> <xref href="GUID-95E66461-EBD7-3843-AD05-D632AB113F2A.dita"><apiname>KLogMailEventType</apiname></xref>: |
|
117 email </p> </li> |
|
118 <li id="GUID-95FC2F4A-0D7F-5378-AF50-38F40440347F"><p> <xref href="GUID-EA11EA32-F6A1-3C57-8C20-98E9D98F5ED8.dita"><apiname>KLogTaskSchedulerEventType</apiname></xref>: |
|
119 task scheduler event </p> </li> |
|
120 </ul> <p>The log engine API provides the class <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> which |
|
121 acts on all events of a specified type. Its functions are: </p> <ul> |
|
122 <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 |
|
123 and set the UID identifying the event type. </p> </li> |
|
124 <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 |
|
125 and set the description in words of the event type. </p> </li> |
|
126 <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 |
|
127 and set a flag which enables events of this type to be logged. </p> </li> |
|
128 <li id="GUID-F2C2D7A2-A0DE-59D3-BD25-0D794D7566F1"><p> <xref href="GUID-CD3C9BD5-1386-3CF5-A8F6-9BE1AE40689F.dita"><apiname>Copy()</apiname></xref> copies |
|
129 an existing event type. </p> </li> |
|
130 <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 |
|
131 streaming input and output of an event type object. </p> </li> |
|
132 </ul> <p>You may need an event type not supplied with the log engine API, |
|
133 for instance if you are developing a new kind of messaging application. A |
|
134 new event type requires a new unique Id which must be allocated by Symbian |
|
135 Signed. Once you have that Id you can create a <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> and |
|
136 pass the Id to <xref href="GUID-05D6F7AA-878A-32D6-BD81-C8D30838FB71.dita"><apiname>SetUid()</apiname></xref> just like the standard event type |
|
137 constants. </p> <p>The main use of <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> is to |
|
138 enable or disable logging for all events of a particular type. You do this |
|
139 by creating a <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> object with its UID set to |
|
140 the relevant event type and calling its <xref href="GUID-E366A706-736E-3530-88B3-26727B8D9C17.dita"><apiname>SetLoggingEnabled()</apiname></xref> function |
|
141 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 |
|
142 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 |
|
143 of a <xref href="GUID-E7CCB043-770E-3722-B735-92B65CC7A0D8.dita"><apiname>CLogEventType</apiname></xref> object will cause logging to take place. |
|
144 For instance if you create a new event type <xref href="GUID-C2D1CC20-9AF0-3B02-B42B-BE96534F44DE.dita"><apiname>myEventType</apiname></xref> and |
|
145 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 |
|
146 before logging will occur. </p> <codeblock id="GUID-F3C05730-5CB0-51A0-8975-311D64C21213" xml:space="preserve"> CLogEventType* myEventType = CLogEventType::NewL();myEventType->SetLoggingEnabled(ETrue);</codeblock> </section> |
|
147 <section id="GUID-5CE676D6-7F07-5C37-99F7-A17C2FC9185C"><title>Log engine |
|
148 and platform security</title> <p>The Symbian platform uses a capabilities |
|
149 model of security in which an application being called verifies that the calling |
|
150 application has the required security policies before returning data. This |
|
151 is important in connection with message logging which involves the end user's |
|
152 confidential information. When writing an application which incorporates logging |
|
153 functionality you must ensure that it has the capabilities to call the log |
|
154 engine APIs. </p> <p>To call a log client, a calling application must have |
|
155 the capabilities required by the event type of the event being accessed. This |
|
156 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 |
|
157 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. |
|
158 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. |
|
159 No capability is required to call <xref href="GUID-BF3481A7-85D0-3431-81C8-905FF0D40887.dita"><apiname>GetEventType()</apiname></xref>. </p> <p>No |
|
160 security capability is required to access the view classes. </p> </section> |
|
161 <section id="GUID-4B5E20B7-5689-5AB1-B265-9C9956B32635"><title>Using filters |
|
162 when displaying a log</title> <p>An event view typically contains only a selection |
|
163 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 |
|
164 members representing the same information as a <xref href="GUID-CDFB61A7-1C74-3F63-9FDF-5A3B8603A010.dita"><apiname>CLogEvent</apiname></xref> object |
|
165 but is used to select on data not modify it. (In the database implementation, |
|
166 a filter corresponds to the WHERE clause of a SELECT query.) An event view |
|
167 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 |
|
168 and then pass this as a parameter of the <xref href="GUID-409E06DF-141C-3352-8E31-87646F9C2DCA.dita"><apiname>SetFilterL()</apiname></xref> function |
|
169 of the event view. You may also want to initialize a view to satisfy any one |
|
170 of several filters, in which case you pass in a <xref href="GUID-84D55725-6357-3596-B1DE-3F3388884504.dita"><apiname>CLogFilterList</apiname></xref>: |
|
171 this is an array of several <xref href="GUID-99144BA6-F79A-3D3C-B1D3-272B3723C42C.dita"><apiname>CLogFilter</apiname></xref> objects. You would |
|
172 do this, for instance, if you wanted to create a view to display events of |
|
173 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 |
|
174 has one event type. </p> </section> |
|
175 <section id="GUID-695967C7-72D9-4026-B719-A756CB89060B"><ol id="GUID-DB02C018-8542-5E49-AB88-44708F78AF3F"> |
|
176 <li id="GUID-0A180E8B-8D5F-5C74-BCF3-24F5387B3F73"><p><xref href="GUID-BCB0E50F-B22E-5964-BB68-BEE1870D9C79.dita">Configuring |
|
177 Log Engine </xref> </p> <p>The clients must configure the Log Engine before |
|
178 using it. </p> </li> |
|
179 <li id="GUID-5920F750-32FE-537B-90E1-AA9A5814FF01"><p><xref href="GUID-2022F702-9899-5798-8932-D70119C7177D.dita">Setting |
|
180 Up A Log Engine Client</xref> </p> <p>After configuring the log engine, a |
|
181 log engine client must be developed. </p> </li> |
|
182 <li id="GUID-2449AFDC-998A-51CF-A81C-B9209445895C"><p><xref href="GUID-E4A950EA-5671-5755-B3EF-5D6B90E19AE6.dita">Maintaining |
|
183 Log Events</xref> </p> <p>The client applications can then add event, event |
|
184 types and delete if necessary. </p> </li> |
|
185 <li id="GUID-B87FA355-BD1B-5595-8FD5-008D281A5D6A"><p><xref href="GUID-BE65B3A7-04E8-5406-B46A-09E2608E0F1F.dita">Requesting |
|
186 Log Engine Notifications</xref> </p> <p>Client applications can receive notification |
|
187 from log engine to get events recorded by other applications. </p> </li> |
|
188 <li id="GUID-5E27A02E-D120-5410-A1F6-54909E9F8324"><p><xref href="GUID-55ECBCF5-FC29-5A4A-A3C6-1CB1C0D562CE.dita">Displaying |
|
189 Log Events</xref> </p> <p>Finally the client applications can then display |
|
190 the log events to the user. </p> </li> |
|
191 </ol> </section> |
|
192 </conbody></concept> |