<?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 task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="GUID-504EB40B-AC98-5AB2-9263-185887C29A7E" xml:lang="en"><title>Searching

for an IAP Record by Name and Loading the Associated Service and the Bearer

Table: Tutorial</title><shortdesc>This tutorial shows you how to search for a Symbian platform defined

Internet Access Points Configuration (IAP) record by name. The tutorial, then

shows you how load the connected service and the bearer table. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<prereq id="GUID-8F09964A-B8AC-5601-817C-B1C243B1CB92"><p>Before you start,

you must understand: </p> <ul>

<li id="GUID-95E91894-42A9-569A-BCBD-D9CAE502B289"><p>the general concept

of the Comms Database </p> </li>

<li id="GUID-127FB886-98D0-5F17-997F-CD1134BA7F57"><p>the specific concept

of fields, records, links and tables </p> </li>

<li id="GUID-8AF15E7D-44F0-5F28-94A1-C4A6E6DE3B93"><p>how to write and build

application code to run on Symbian platform </p> </li>

</ul> </prereq>

<context id="GUID-37F9160E-EAE2-5975-B064-255EA353CB72"><p>This tutorial shows

you: </p> <ul>

<li id="GUID-84E5F473-8F05-5FDD-B1BB-ED301420CD89"><p>how to search the <i>Internet

Access Points Configuration</i> table for a record defined by name. This table

is also called the IAP table </p> </li>

<li id="GUID-08BA5682-4AF9-526B-9CD2-48BFDEE7E162"><p>how to load the connected

service. </p> </li>

<li id="GUID-545EC3CC-F771-50AF-8388-CA0AC4B84B10"><p>how to load the connected

bearer table. </p> </li>

</ul> <p>The principles that apply here also apply to the other Symbian platform

defined tables. </p> </context>

<steps id="GUID-6A94C40E-59E3-5F22-A778-0734773900C4">

<step id="GUID-FFA9D8F4-6683-52EC-B9F7-7D1AAB904D48"><cmd>Make sure that you

have created a session. </cmd>

</step>

<step id="GUID-D00E9CCC-8046-5E43-9D8E-CCA971C79ED2"><cmd>Create an empty

IAP record in the tool or application process. </cmd>

<info>You create a <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBRecordSet</apiname></xref> <codeph>&lt;T&gt;</codeph> object

and specify <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CCDIAPRecord</apiname></xref> as the template

parameter. </info>

<info>Symbian platform defines the <codeph>CCDIAPRecord</codeph> class to

represent a IAP record. The class is a schema for the record. The class defines

the fields and links that make a IAP record. </info>

<info>Symbian platform defines <xref href="GUID-32E556BC-55C3-5FBD-9A60-9708139C20D6.dita">unique

numeric Id</xref> s for Symbian platform defined tables. The symbol <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>KCDTIdIAPRecord</apiname></xref> also defines the value of this

Id for records in the IAP table. The Id allows the CommsDat API to get the

record from the Comms Database. </info>

<info>To work with other Symbian platform defined tables, use the correct

class name and the correct unique numeric Id values. The <xref href="GUID-58089281-9DD0-502D-8DFD-831E7BAA931E.dita">Reference</xref> section

contains a list of all Symbian platform defined tables. </info>

<stepxmp><codeblock id="GUID-629FD205-82F8-5383-AEC8-1645309B994B" xml:space="preserve">...

// This code fragment assumes that a session with the Comms Database has been created.

// iDb is a pointer to a CMDBSession object

...

// When we search by Name or Id, there can be only one record to be returned

// Create an empty IAP record.

//

// Note:

// 1. the template parameter CCDIAPRecord defines 

//    the "IAP" record type.

// 2. to create a record, you use a factory function and pass the unique

//    numeric Id KCDTIdIAPRecord as a parameter to the constructor.

//

CCDIAPRecord* ptrIAPRecord = 

              static_cast<CCDIAPRecord *>(CCDRecordBase::RecordFactoryL(KCDTIdIAPRecord));

...</codeblock> </stepxmp>

</step>

<step id="GUID-82296CE1-8682-56E6-8847-FB6A2348479A"><cmd>Define the name

of the IAP record to be found and set the name in IAP record. Do the search

for the record in the Comms Database. </cmd>

<info>In this tutorial, the name of the IAP record is NTRas with Null Modem. </info>

<info>Use the assignment operator to add the data to a field. A field that

has type <codeph>T</codeph> accepts a type T item as the right-hand argument

of an assignment call. </info>

<info>A descriptor field needs an additional call to set the size of the descriptor.

Call <codeph>SetMaxLengthL()</codeph> to set the size of the descriptor. This

function is a member of the field class <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBField</apiname></xref> <codeph>&lt;TDesC&gt;</codeph>.

Internally, the function causes the allocation of a descriptor. You must set

the size of the descriptor before you assign the data. You can also use the <codeph>SetL()</codeph> function.

This function sets the length and assigns the data. The function is a member

of the field class <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>CMDBField</apiname></xref> <codeph>&lt;TDesC&gt;</codeph>. </info>

<stepxmp><codeblock id="GUID-8427EB95-2BE7-59C7-9A21-DF9DDB3607AF" xml:space="preserve">...

// Define the name of the IAP record.

_LIT(KMyIap, "NTRas with Null Modem");

// Either 

ptrIAPRecord->iRecordName.SetMaxLengthL(KMyIap().Length());

ptrIAPRecord->iRecordName = KMyIap;

// Or 

ptrIAPRecord->iRecordName.SetL(KMyIap);

// Search the Comms Database

if(ptrIAPRecord->FindL(*iDb))

    {

    // Found a matching record

    ...

    }

...</codeblock> </stepxmp>

</step>

<step id="GUID-119EC7CA-0E0E-5062-BC7D-FC023205FA1A"><cmd>Load the NTRas with

Null Modem service and the associated bearer table. </cmd>

<stepxmp><codeblock id="GUID-C3994C1F-61BD-5BCC-9E29-FACAEE5C198C" xml:space="preserve">...

// Search the Comms Database

if(ptrIAPRecord->FindL(*iDb))

    {

    // Found a matching record

    // Now load the the associated service and bearer tables, 

    // The variables iService,iBearer, etc

    // are links that point to other records. These links have a "Value" and 

    // "iLinkedRecord".

    // 

    // The "Value" represent the id of the target field,and gets initialized along with the

    // parent record(ptrIAPRecord). When we explictly call load on these LinkedFields,

    // the "iLinkedRecord" pointer points to the appropriate object.

    //

    // The "iLinkedRecord" pointer is  owned by the parent record and gets

    // deleted along with it.THis means that it must be set to NULL

    // if the user wants to take ownership.

    ptrIAPRecord->iService.LoadL(*iDb);

    ptrIAPRecord->iBearer.LoadL(*iDb);

    // Take ownership of the loaded service record cache

    CCDServiceRecordBase* ptrService = 

        static_cast< CCDServiceRecordBase *> (ptrIAPRecord->iService.iLinkedRecord);

    (ptrIAPRecord->iService).iLinkedRecord = NULL;

    // Deleting ptrIAPRecord also deletes all the loaded iLinkedRecord

    // pointers it owns unless set to null.

    delete ptrIAPRecord;         

   //delete the service view.

    delete ptrService;

    }         

...</codeblock> </stepxmp>

</step>

</steps>

</taskbody><related-links>

<link href="GUID-1AFDDD6F-CB99-587D-A0B5-D3F5B27F7135.dita"><linktext>Comms Database

                concepts</linktext></link>

</related-links></task>