--- a/Symbian3/PDK/Source/GUID-9D56FF77-A20B-5BFB-8DE6-19CC4535DFED.dita Tue Mar 30 11:42:04 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-9D56FF77-A20B-5BFB-8DE6-19CC4535DFED.dita Tue Mar 30 11:56:28 2010 +0100
@@ -1,89 +1,157 @@
-<?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 xml:lang="en" id="GUID-9D56FF77-A20B-5BFB-8DE6-19CC4535DFED"><title>Following a link to another table and finding a field by Id and by name: Tutorial</title><shortdesc>This tutorial shows you how to follow a link to a Symbian OS defined table. The tutorial also shows two methods to get the value of a field. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody> <prereq id="GUID-E4B235C3-CD22-57E0-BC48-DDDB0A6AFFFC"><p>Before you start, you must understand: </p> <ul><li id="GUID-6C352504-E6D4-5C17-88A3-1563F3AEE53E"><p>the general concept of the Comms Database </p> </li> <li id="GUID-AC4D044B-3B8E-522A-AB9D-5EBA1BCCE299"><p>the specific concept of fields, records, links and tables </p> </li> <li id="GUID-51754AAB-7EE7-5FB4-869C-7FADD29951D9"><p>how to write and build application code to run on Symbian OS </p> </li> </ul> </prereq> <context id="GUID-A7FE99ED-D5CC-5F71-8B64-E0CCB1F8222E"><p>The tutorial shows you how to follow a link from a record in the <xref href="GUID-387A8240-0765-52F2-98A4-8F9FC809E03E.dita#GUID-387A8240-0765-52F2-98A4-8F9FC809E03E/GUID-57197DDE-9DE0-5978-8F2F-D2E370489E3C">IAP</xref> table to a record in the service table. The tutorial then shows you how to find the "Bearer Speed" field by its Id and by its name in the linked record. </p> <p>The principles that apply here also apply to the other Symbian OS defined tables </p> </context> <steps id="GUID-02024A4A-F0D7-5EC0-BB5C-8BCC12D33BBB"><step id="GUID-FEB0F22C-F0F7-575F-9063-0D21D6708021"><cmd>Make sure that you have created a session. </cmd> </step> <step id="GUID-D7D8189E-EE40-5305-B993-26D9F28D3EC5"><cmd>Create the IAP record object in the tool or application process and prime it for the search for the service type "DialOutISP". </cmd> <info>Symbian OS defines the <codeph>CCDIAPRecord</codeph> class to represent a <xref href="GUID-387A8240-0765-52F2-98A4-8F9FC809E03E.dita#GUID-387A8240-0765-52F2-98A4-8F9FC809E03E/GUID-57197DDE-9DE0-5978-8F2F-D2E370489E3C">IAP</xref> record. The class is a schema for the record. The class defines the fields and links that make a IAP record. </info> <info>Symbian OS defines <xref href="GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-32E556BC-55C3-5FBD-9A60-9708139C20D6">unique numeric Id</xref> s for Symbian OS defined tables. The symbol <xref href="GUID-1CDD0B97-8B00-3373-9908-512C9BC1CF51.dita"><apiname>KCDTIdIAPRecord</apiname></xref> defines the value of this Id for the IAP table. The Id allows the CommsDat API to retrieve the table from the Comms Database efficiently. </info> <stepxmp><codeblock id="GUID-31732ADA-3BC7-5D6E-8579-6CE700C2A9B7" xml:space="preserve">...
-// Create a single IAP record in memory and prime it with the type of service
-// that you want to find. In this case, the type of service is "DialOutISP".
-// This code fragment assumes that a session with the Comms Database has been created.
-// "iDb" is a pointer to a CMDBSession object
-
-_LIT(KISPType, "DialOutISP");
-TUint32 bearerSpeed;
-
-
-// Use the factory function CCDRecordBase::RecordFactoryL() to create the IAP record obejct.
-//
-// Note:
-// 1. the template parameter CCDIAPRecord defines
-// the "IAP" record type.
-// 2. the unique numeric Id KCDTIdIAPRecord is passed as a parameter
-// to the constructor.
-
-CCDIAPRecord* ptrSingleIAPRecord = static_cast<CCDIAPRecord*>(CCDRecordBase::RecordFactoryL(KCDTIdIAPRecord));
-
-
-// The storage for string or binary fields must be allocated
-// explicitly if set or reset by the application. Storage required for
-// storing data retrieved from the database is handled by the implementation of the CommsDat API.
-//
-// Set the service type.
-ptrSingleIAPRecord->iServiceType.SetMaxLengthL(KISPType().Length());
-ptrSingleIAPRecord->iServiceType = KISPType;
-
-
-// Note that you can replace the above two function calls with the
-// single function call:
-//
-// ptrSingleIAPRecord->iServiceType.SetL(KISPType);
-...</codeblock> </stepxmp> </step> <step id="GUID-A661444B-A268-56C5-81FF-B3AB0063BA9C"><cmd>Search for the first IAP record that has "DialOutISP" as the service type. If the record is found, load the associated service table record. </cmd> <stepxmp><codeblock id="GUID-E197DCA4-4E3D-5963-A548-8FD84F797C6B" xml:space="preserve">...
-if(ptrSingleIAPRecord->FindL(*iDb))
- {
- // An IAP record with "DialOutISP" as the service type has
- // been found and loaded into memory.
-
- // Load the service table record associated with this IAP.
- ptrSingleIAPRecord->iService.LoadL(*iDb);
- ...</codeblock> </stepxmp> </step> <step id="GUID-5A28A3C4-BB43-52BF-8F98-00B125549A45"><cmd/><substeps id="GUID-B20735EC-2966-5C31-9591-8108A0A4BB5C"><substep id="GUID-76112AFB-54C4-55D8-AC6E-1B9D86CC35A7"><cmd>CASE 1 : Access the service record when you know the service type. This is the most effiecient method. </cmd> <stepxmp><codeblock id="GUID-316366CE-97B7-5093-8480-2AA021F764D5" xml:space="preserve">
- ...
- CCDDialOutISPRecord* ptrIspRecord = static_cast<CCDDialOutISPRecord*>(ptrSingleIAPRecord->iService.iLinkedRecord);
- bearerSpeed = ptrIspRecord->iBearerSpeed;
- ...</codeblock> </stepxmp> </substep> <substep id="GUID-2A8FE5F5-D7AD-5F95-A2D5-AD6DA1C4EDA0"><cmd>CASE 2: Access the service record when you do not know the service type. This is also the more general case and is slower than case 1. </cmd> <info>You can find a field by its Id, or you can find a field by its name. To find a field by its name is not recommended, because this operation is slow. </info> <stepxmp><codeblock id="GUID-0FDC8EF4-45FF-542B-87FD-042FC31F431C" xml:space="preserve">
- ...
- // Use the base class "CCDServiceRecordBase" instead of the more specific
- // class "CCDDialOutISPRecord" [or any other specific class derived from "CCDServiceRecordBase"].
- CCDServiceRecordBase* ptrServiceRecord = static_cast<CCDServiceRecordBase*>(ptrSingleIAPRecord->iService.iLinkedRecord);
- CMDBField<TUint32>* field;
- ...
-
- // Find a field by its Id
-
- field = (CMDBField<TUint32>*)ptrServiceRecord->GetFieldByIdL(KCDTIdBearerSpeed);
- bearerSpeed = *field;
- ...
-
- // Find a field by its name. Symbian OS defines KCDTypeNameBearerSpeed to represent
- // the name of the field.
-
- TPtrC16 BearerName(KCDTypeNameBearerSpeed);
- TInt valueType;
- field = (CMDBField<TUint32>*)ptrServiceRecord->GetFieldByNameL(BearerName,valueType);
- bearerSpeed = *field;
- ...
- </codeblock> </stepxmp> </substep> </substeps> </step> <step id="GUID-5B8443D8-DA79-57E6-9FC4-6A36C158090F"><cmd>Clean up. </cmd> <stepxmp><codeblock id="GUID-0E70C9AB-49B2-5ECB-9262-3A251135B5F9" xml:space="preserve">
- ...
- //
- // This also deletes "ptrSingleIAPRecord->iService.iLinkedRecord"
- //
- delete ptrSingleIAPRecord;
- ...
- }
-}</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>
\ No newline at end of file
+<?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-9D56FF77-A20B-5BFB-8DE6-19CC4535DFED" xml:lang="en"><title>Following
+a link to another table and finding a field by Id and by name: Tutorial</title><shortdesc>This tutorial shows you how to follow a link to a Symbian platform
+defined table. The tutorial also shows two methods to get the value of a field. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>
+
+
+<prereq id="GUID-E4B235C3-CD22-57E0-BC48-DDDB0A6AFFFC"><p>Before you start,
+you must understand: </p> <ul>
+<li id="GUID-6C352504-E6D4-5C17-88A3-1563F3AEE53E"><p>the general concept
+of the Comms Database </p> </li>
+<li id="GUID-AC4D044B-3B8E-522A-AB9D-5EBA1BCCE299"><p>the specific concept
+of fields, records, links and tables </p> </li>
+<li id="GUID-51754AAB-7EE7-5FB4-869C-7FADD29951D9"><p>how to write and build
+application code to run on Symbian platform </p> </li>
+</ul> </prereq>
+<context id="GUID-A7FE99ED-D5CC-5F71-8B64-E0CCB1F8222E"><p>The tutorial shows
+you how to follow a link from a record in the <xref href="GUID-387A8240-0765-52F2-98A4-8F9FC809E03E.dita#GUID-387A8240-0765-52F2-98A4-8F9FC809E03E/GUID-57197DDE-9DE0-5978-8F2F-D2E370489E3C">IAP</xref> table to a record in the service table. The tutorial then shows you how
+to find the "Bearer Speed" field by its Id and by its name in the linked record. </p> <p>The
+principles that apply here also apply to the other Symbian platform defined
+tables </p> </context>
+<steps id="GUID-02024A4A-F0D7-5EC0-BB5C-8BCC12D33BBB">
+<step id="GUID-FEB0F22C-F0F7-575F-9063-0D21D6708021"><cmd>Make sure that you
+have created a session. </cmd>
+</step>
+<step id="GUID-D7D8189E-EE40-5305-B993-26D9F28D3EC5"><cmd>Create the IAP record
+object in the tool or application process and prime it for the search for
+the service type "DialOutISP". </cmd>
+
+<info>Symbian platform defines the <codeph>CCDIAPRecord</codeph> class to
+represent a <xref href="GUID-387A8240-0765-52F2-98A4-8F9FC809E03E.dita#GUID-387A8240-0765-52F2-98A4-8F9FC809E03E/GUID-57197DDE-9DE0-5978-8F2F-D2E370489E3C">IAP</xref> 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-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita#GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84/GUID-32E556BC-55C3-5FBD-9A60-9708139C20D6">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> defines the value of this Id for
+the IAP table. The Id allows the CommsDat API to retrieve the table from the
+Comms Database efficiently. </info>
+<stepxmp><codeblock id="GUID-31732ADA-3BC7-5D6E-8579-6CE700C2A9B7" xml:space="preserve">...
+// Create a single IAP record in memory and prime it with the type of service
+// that you want to find. In this case, the type of service is "DialOutISP".
+// This code fragment assumes that a session with the Comms Database has been created.
+// "iDb" is a pointer to a CMDBSession object
+
+_LIT(KISPType, "DialOutISP");
+TUint32 bearerSpeed;
+
+
+// Use the factory function CCDRecordBase::RecordFactoryL() to create the IAP record obejct.
+//
+// Note:
+// 1. the template parameter CCDIAPRecord defines
+// the "IAP" record type.
+// 2. the unique numeric Id KCDTIdIAPRecord is passed as a parameter
+// to the constructor.
+
+CCDIAPRecord* ptrSingleIAPRecord = static_cast<CCDIAPRecord*>(CCDRecordBase::RecordFactoryL(KCDTIdIAPRecord));
+
+
+// The storage for string or binary fields must be allocated
+// explicitly if set or reset by the application. Storage required for
+// storing data retrieved from the database is handled by the implementation of the CommsDat API.
+//
+// Set the service type.
+ptrSingleIAPRecord->iServiceType.SetMaxLengthL(KISPType().Length());
+ptrSingleIAPRecord->iServiceType = KISPType;
+
+
+// Note that you can replace the above two function calls with the
+// single function call:
+//
+// ptrSingleIAPRecord->iServiceType.SetL(KISPType);
+...</codeblock> </stepxmp>
+</step>
+<step id="GUID-A661444B-A268-56C5-81FF-B3AB0063BA9C"><cmd>Search for the first
+IAP record that has "DialOutISP" as the service type. If the record is found,
+load the associated service table record. </cmd>
+<stepxmp><codeblock id="GUID-E197DCA4-4E3D-5963-A548-8FD84F797C6B" xml:space="preserve">...
+if(ptrSingleIAPRecord->FindL(*iDb))
+ {
+ // An IAP record with "DialOutISP" as the service type has
+ // been found and loaded into memory.
+
+ // Load the service table record associated with this IAP.
+ ptrSingleIAPRecord->iService.LoadL(*iDb);
+ ...</codeblock> </stepxmp>
+</step>
+<step id="GUID-5A28A3C4-BB43-52BF-8F98-00B125549A45"><cmd/>
+
+<substeps id="GUID-B20735EC-2966-5C31-9591-8108A0A4BB5C">
+<substep id="GUID-76112AFB-54C4-55D8-AC6E-1B9D86CC35A7"><cmd>CASE 1 : Access
+the service record when you know the service type. This is the most effiecient
+method. </cmd>
+<stepxmp><codeblock id="GUID-316366CE-97B7-5093-8480-2AA021F764D5" xml:space="preserve">
+ ...
+ CCDDialOutISPRecord* ptrIspRecord = static_cast<CCDDialOutISPRecord*>(ptrSingleIAPRecord->iService.iLinkedRecord);
+ bearerSpeed = ptrIspRecord->iBearerSpeed;
+ ...</codeblock> </stepxmp>
+</substep>
+<substep id="GUID-2A8FE5F5-D7AD-5F95-A2D5-AD6DA1C4EDA0"><cmd>CASE 2: Access
+the service record when you do not know the service type. This is also the
+more general case and is slower than case 1. </cmd>
+
+<info>You can find a field by its Id, or you can find a field by its name.
+To find a field by its name is not recommended, because this operation is
+slow. </info>
+<stepxmp><codeblock id="GUID-0FDC8EF4-45FF-542B-87FD-042FC31F431C" xml:space="preserve">
+ ...
+ // Use the base class "CCDServiceRecordBase" instead of the more specific
+ // class "CCDDialOutISPRecord" [or any other specific class derived from "CCDServiceRecordBase"].
+ CCDServiceRecordBase* ptrServiceRecord = static_cast<CCDServiceRecordBase*>(ptrSingleIAPRecord->iService.iLinkedRecord);
+ CMDBField<TUint32>* field;
+ ...
+
+ // Find a field by its Id
+
+ field = (CMDBField<TUint32>*)ptrServiceRecord->GetFieldByIdL(KCDTIdBearerSpeed);
+ bearerSpeed = *field;
+ ...
+
+ // Find a field by its name. Symbian platform defines KCDTypeNameBearerSpeed to represent
+ // the name of the field.
+
+ TPtrC16 BearerName(KCDTypeNameBearerSpeed);
+ TInt valueType;
+ field = (CMDBField<TUint32>*)ptrServiceRecord->GetFieldByNameL(BearerName,valueType);
+ bearerSpeed = *field;
+ ...
+ </codeblock> </stepxmp>
+</substep>
+</substeps>
+</step>
+<step id="GUID-5B8443D8-DA79-57E6-9FC4-6A36C158090F"><cmd>Clean up. </cmd>
+<stepxmp><codeblock id="GUID-0E70C9AB-49B2-5ECB-9262-3A251135B5F9" xml:space="preserve">
+ ...
+ //
+ // This also deletes "ptrSingleIAPRecord->iService.iLinkedRecord"
+ //
+ delete ptrSingleIAPRecord;
+ ...
+ }
+}</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>
\ No newline at end of file