Symbian3/SDK/Source/GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita
author Dominic Pinkman <Dominic.Pinkman@Nokia.com>
Wed, 31 Mar 2010 11:11:55 +0100
changeset 7 51a74ef9ed63
child 8 ae94777fff8f
permissions -rw-r--r--
Week 12 contribution of API Specs and fix SDK submission

<?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-6DAF85AD-E412-5823-81C2-FC1755A90A84" xml:lang="en"><title>What
are elements</title><shortdesc>This topic describes elements. All items that can be stored in
the Comms Database are elements. The topic also discusses the structure of
the unique numeric Id and the attributes that control access to elements. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>An element is represented by the <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBElement</apiname></xref> class.
The class is a base class for all items that can be stored in the Comms Database.
The class contains the data that is common to all items that can be stored
in the Comms database. </p>
<p>Elements contain three pieces of information: </p>
<ul>
<li id="GUID-42CDC895-ADD7-53E1-86C8-BDCA97874D80"><p>a unique numeric Id
that defines the location of the element in the database. The Id defines the
meaning of the element in the database schema as a specific Table, Column,
Record or Field. A numeric Id also allows for fast access and retrieval of
an element. </p> </li>
<li id="GUID-370BB127-A262-561F-BB53-CFD71D7EF61E"><p>a set of attributes
that controls access to the data. </p> </li>
<li id="GUID-F533113D-25EF-5CAE-8AA4-FF05CA8894B6"><p>a value that can be
a single numeric type, a Boolean type, a descriptor, or a composite of one
or more nested elements. </p> </li>
</ul>
<p> <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBElement</apiname></xref> derives from <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>MMetaDatabase</apiname></xref>. <codeph>MMetaDatabase</codeph> provides
the behaviour that allows an element to operate with the Comms Database. [See
accessing the database or words to that effect.] </p>
<fig id="GUID-3FE9490C-8766-5F31-9147-7F20A03BBF2D">
<image href="GUID-4B7FA629-BFC9-594B-B253-AC920EAD6E67_d0e85908_href.png" placement="inline"/>
</fig>
<section id="GUID-4DDD4947-D379-5B68-8DC0-B67B074FA852"><title>The Element
Id</title> <p>The <codeph>iElementId</codeph> data member of <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBElement</apiname></xref> is
a 32 bit number that contains: </p> <ul>
<li id="GUID-4F41A6A2-79FC-5CA7-AC9C-B242D7DC925E"><p>the unique numeric Id
that shows the location of the element in the database. This numeric Id is
known as the Element Id. </p> </li>
<li id="GUID-D8EFDBE9-A897-56F8-939A-E3942FCC34F2"><p>the set of attributes
that controls access to the data. The bits define the access levels. </p> </li>
</ul> <p>Both pieces of information are encoded in the 32 bit number. The
32 bit number is a <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>TMDBElementId</apiname></xref> type. </p> <p>The <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBElement</apiname></xref> class provides member functions to
access and to change the information in the Element Id. </p></section>
<section> <p id="GUID-32E556BC-55C3-5FBD-9A60-9708139C20D6"><b>The unique
numeric Id</b> </p> <p>The unique numeric Id has two parts: the Type Id and
the Record Id. </p> <p>The Type Id defines the type of element; the Record
Id identifies an instance of this type of element. </p> <p>The class <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBElement</apiname></xref> provides the member functions <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CommsDat::CMDBElement::TypeId()</apiname></xref> and <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CommsDat::CMDBElement::RecordId()</apiname></xref> to
extract this information. </p> <p>Internally, the Type Id includes a 8 bit
number and a 7 bit number. The 8 bit number is the Table Id and the 7 bit
number is the Column Id. The Type Id and the Record Id are in defined locations
in the 32 bit number <codeph>iElementId</codeph>. </p> <fig id="GUID-B3A732DF-8D24-532C-A4AB-D5B42408D832">
<image href="GUID-0B151FE8-21E1-58A1-BEB3-5502EDF052C0_d0e85988_href.png" placement="inline"/>
</fig> <p>The header file <filepath>comsdat.h</filepath> contains the constants
that define the location of these Ids in the 32 bit number: </p> <table id="GUID-1369F999-F42E-5268-AF6F-0D5C9A362878">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p>Table Id </p> </entry>
<entry><p> <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>KCDMaskShowRecordType</apiname></xref>  </p> </entry>
</row>
<row>
<entry><p>Column Id </p> </entry>
<entry><p> <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>KCDMaskShowFieldType</apiname></xref>  </p> </entry>
</row>
<row>
<entry><p>Type Id </p> </entry>
<entry><p> <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>KCDMaskShowType</apiname></xref>  </p> </entry>
</row>
<row>
<entry><p>Record Id </p> </entry>
<entry><p> <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>KCDMaskShowRecordId</apiname></xref>  </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
<section><p id="GUID-EE8E5985-4159-5780-8001-E51EB4821D05"><b> The set of
attributes that controls access to the data</b> </p><p>The access levels of
an element are defined by the bits in the element. The <xref href="GUID-2AF9DED8-0AAE-370B-8FA2-B2910939A7B8.dita"><apiname>TCDAttributeFlags</apiname></xref> enum
defines the access levels of an element. These bits are stored in the fourth
byte of the <codeph>iElementId</codeph> member of <xref href="GUID-C36F41FE-1776-3735-89F3-DAAAFA7FDC91.dita"><apiname>CMDBElement</apiname></xref>. </p><fig id="GUID-A1C2FF44-AA19-42B8-8F10-E927170A317A">
<image href="GUID-46673FC4-ADA9-59D1-A743-B4784425D240_d0e86097_href.png" placement="inline"/>
</fig><p> <xref href="GUID-DC185E84-1DC0-36F7-9B3D-19B4B3E641D7.dita"><apiname>KCDMaskShowAttributes</apiname></xref> in the header file <filepath>comsdat.h</filepath> defines
the location of these access control bits in the 32 bit number.</p>  </section>
</conbody></concept>