--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Adaptation/GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita Fri Oct 15 14:32:18 2010 +0100
@@ -0,0 +1,809 @@
+<?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-8EB25927-D49E-578F-BD93-294C4EECB7E7" xml:lang="en"><title>Basic
+APIs</title><shortdesc>Accessing APIs and basic functions in kernel-side programs.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>Device drivers, like user-side programs, need to use APIs for basic tasks
+such as managing buffers and arrays. However, the EKA2 architecture does not
+allow kernel-side programs such as drivers to link and use the User Library
+(<filepath>euser.dll</filepath>) that provides these APIs to user-side programs.
+This means kernel side code <i>cannot use the majority</i> of classes and
+functions that are available to user side code. </p>
+<p>However, some classes are available for use on both the user side and the
+kernel side. The first section of this document, <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-2CE47F55-D160-50A3-B05E-318569FDEF1F">Available EUSER functionality</xref>, explains what these are. In other cases,
+there are alternative Kernel-specific APIs or techniques that you can use.
+The second section, <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-6AE21206-A29D-5CB6-83E9-69C2E7DA566A">Coding
+techniques to replace EUSER functionality</xref>, describes these. </p>
+<p>The detailed contents are given below: </p>
+<p><b>Contents </b> </p>
+<ul>
+<li id="GUID-F2669D60-00E3-520C-BACA-E363BFEDD487"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-2CE47F55-D160-50A3-B05E-318569FDEF1F">Available EUSER functionality</xref> </p> <ul>
+<li id="GUID-AB9D2617-556C-556B-81F2-A9E0E3CA2A60"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-1A26C8D7-E915-5280-BA1E-0B837E296EE4">8-bit descriptors</xref> </p> </li>
+<li id="GUID-2D0B05B0-BEBB-5A71-A6CA-1FFC5848D80B"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-F8164DF1-8875-5C83-9165-9902EB51A97C">Arrays</xref> </p> </li>
+<li id="GUID-962C0A1C-5A7B-5201-956D-F38BDF59C836"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-0BC2B8B1-F797-5B65-9EE7-36A2EC5C9BC5">Character representation</xref> </p> </li>
+<li id="GUID-36D2B096-181D-51E5-B502-E385565E7693"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-682EF1C2-4756-5E5A-B4E9-00AABD5D4CE2">Basic utility functions and classes</xref> </p> </li>
+<li id="GUID-F9264F5E-2D3D-551D-B9DD-DCECC027021D"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-331E0310-69A3-58A6-B932-F2B44201530D">The Package Buffers API</xref> </p> </li>
+<li id="GUID-293A58CA-F57E-5323-9B1B-A8F51D351AA2"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-5707529F-6145-58C3-A0A9-8789FF8F1C93">The UID manipulation APIs</xref> </p> </li>
+<li id="GUID-022766DC-6F40-55BE-B02A-6544A213141B"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-E9F32C01-5C4F-5706-B992-A4F8B01171FD">Version handling API</xref> </p> </li>
+<li id="GUID-5CA1160C-8EEC-5795-853D-C568D519534F"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-E67B4238-3CFF-5448-B711-FCD14D8D3C10">TRequestStatus</xref> </p> </li>
+<li id="GUID-AE09C566-0664-5341-9D8D-386D9CE3DFBA"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-0CA35DBF-C10D-5C35-90CD-24C53AEA41BF">TIpcArgs</xref> </p> </li>
+<li id="GUID-EE77EAFA-50E6-58E4-B64E-4E7AB5FCAEF2"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-111081C5-5BDA-516B-9B3D-9D24FAD31E5D">Basic graphic classes</xref> </p> </li>
+</ul> </li>
+<li id="GUID-7772333C-EB62-58E1-B1FD-64B500567C9D"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-6AE21206-A29D-5CB6-83E9-69C2E7DA566A">Coding techniques to replace EUSER functionality</xref> </p> <ul>
+<li id="GUID-EF0FA499-7F16-54D6-B1BA-A0AB3071CFB5"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-CA520DD3-3601-5774-87F2-D5BA4DA2BF8E">Buffers: replacing HBufC8 with HBuf</xref> </p> </li>
+<li id="GUID-6CAA6B7F-7F07-5047-82CE-CCAF960880AF"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-310ADB7F-A03C-5994-A918-634B7BAB7DD8">Buffers: replacing HBufC8 with C style pointers</xref> </p> </li>
+<li id="GUID-8858CFAA-EF27-54B0-8083-74A990C5E614"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-586DD3B4-69DB-564B-AB8D-B3A02607CE02">Handling 16-bit data items</xref> </p> </li>
+<li id="GUID-AA63211F-E5AD-554A-AAFC-3FB1336553D5"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-77C88D19-50C3-5D69-8084-BE750F100BA0">Replacing CBase with DBase</xref> </p> </li>
+<li id="GUID-E264271B-64F3-59A3-AD65-56C9ACEB5ABF"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-585EE1D8-6080-5B37-A3BD-278B8731B7F9">Replacing User::QueryVersionSupported() with Kern::QueryVersionSupported()</xref> </p> </li>
+</ul> </li>
+</ul>
+<section id="GUID-2CE47F55-D160-50A3-B05E-318569FDEF1F"><title>Available EUSER
+functionality</title> <p>This is a list of USER side classes, types and APIs
+that can still be used on the kernel side. However, a subset of the class
+member functions may not be available. </p> <ul>
+<li id="GUID-81D6F170-FAB0-5DE6-93BC-0027CF8E382F"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-1A26C8D7-E915-5280-BA1E-0B837E296EE4">8-bit descriptors</xref> </p> </li>
+<li id="GUID-BF477CD1-6079-5C60-A658-0DD64111081F"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-F8164DF1-8875-5C83-9165-9902EB51A97C">Arrays</xref> </p> </li>
+<li id="GUID-63E56F9D-B261-58E7-B9F9-ED9726C7F16F"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-0BC2B8B1-F797-5B65-9EE7-36A2EC5C9BC5">Character representation (TChar)</xref> </p> </li>
+<li id="GUID-6F9BC926-0367-57DC-8356-29A2D29D60B8"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-682EF1C2-4756-5E5A-B4E9-00AABD5D4CE2">Basic utility functions and classes</xref> </p> </li>
+<li id="GUID-17051C1E-21DE-567C-ADB4-11D18314B0FC"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-331E0310-69A3-58A6-B932-F2B44201530D">The Package Buffers API</xref> </p> </li>
+<li id="GUID-3BCFE3A4-9B93-5D2D-BA1E-71F2544028AC"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-5707529F-6145-58C3-A0A9-8789FF8F1C93">The UID manipulation APIs</xref> </p> </li>
+<li id="GUID-4C2730C0-D22F-5855-9D11-8049B1BDEF5E"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-E9F32C01-5C4F-5706-B992-A4F8B01171FD">Version handling API</xref> </p> </li>
+<li id="GUID-44CEA8AD-36B9-59DF-9469-9A905A600ED4"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-E67B4238-3CFF-5448-B711-FCD14D8D3C10">TRequestStatus</xref> </p> </li>
+<li id="GUID-A867EDC0-DD2E-5E6D-ABC8-E57CECDA6158"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-0CA35DBF-C10D-5C35-90CD-24C53AEA41BF">TIpcArgs</xref> </p> </li>
+<li id="GUID-D0E83441-2258-5660-99F1-5BCBB799DEA8"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-111081C5-5BDA-516B-9B3D-9D24FAD31E5D">Basic graphic classes</xref> </p> </li>
+</ul> <p id="GUID-1A26C8D7-E915-5280-BA1E-0B837E296EE4"><b>8-bit descriptors</b> </p> <p>The
+following classes, defined in <filepath>e32des8.h</filepath>, <i>can</i> be
+used on the kernel side. </p> <p>For some classes, the kernel side can use
+the same member functions that are available to the user side. However, for
+other classes, the kernel side is restricted to using a subset of functions;
+where this is the case, the functions are listed </p> <table id="GUID-CCC5A82F-8A1B-52F2-8B0A-036801F68C68">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><p> <b>Classes available </b> </p> </entry>
+<entry><p> <b>Public member functions that are available to kernel side code</b> </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> </p> </entry>
+<entry><p> <codeph>TInt operator<(const TDesC8 &aDes) const;</codeph> </p> <p> <codeph>TInt
+operator<=(const TDesC8 &aDes) const;</codeph> </p> <p> <codeph>TInt
+operator>(const TDesC8 &aDes) const;</codeph> </p> <p> <codeph>TInt operator>=(const
+TDesC8 &aDes) const;</codeph> </p> <p> <codeph>TInt operator==(const
+TDesC8 &aDes) const;</codeph> </p> <p> <codeph>TInt operator!=(const
+TDesC8 &aDes) const;</codeph> </p> <p> <codeph> const TUint8 &operator[](TInt
+anIndex) const;</codeph> </p> <p> <codeph>TInt Length() const;</codeph> </p> <p> <codeph>TInt
+Size() const;</codeph> </p> <p> <codeph>const TUint8 *Ptr() const;</codeph> </p> <p> <codeph>TInt
+Compare(const TDesC8 &aDes) const;</codeph> </p> <p> <codeph>TInt Match(const
+TDesC8 &aDes) const;</codeph> </p> <p> <codeph>TInt MatchF(const TDesC8
+&aDes) const;</codeph> </p> <p> <codeph>TInt MatchC(const TDesC8 &aDes)
+const;</codeph> </p> <p> <codeph>TInt Locate(TChar aChar) const;</codeph> </p> <p> <codeph>TInt
+LocateReverse(TChar aChar) const;</codeph> </p> <p> <codeph>TInt Find(const
+TDesC8 &aDes) const;</codeph> </p> <p> <codeph>TInt Find(const TUint8
+*pS,TInt aLenS) const;</codeph> </p> <p> <codeph>TPtrC8 Left(TInt aLength)
+const;</codeph> </p> <p> <codeph>TPtrC8 Right(TInt aLength) const;</codeph> </p> <p> <codeph>TPtrC8
+Mid(TInt aPos) const;</codeph> </p> <p> <codeph>TPtrC8 Mid(TInt aPos,TInt
+aLength) const;</codeph> </p> <p> <codeph>TInt CompareF(const TDesC8 &aDes)
+const;</codeph> </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes8</apiname></xref> </p> </entry>
+<entry><p> <codeph>TDes8& operator=(const TUint8 *aString);</codeph> </p> <p> <codeph>TDes8&
+operator=(const TDesC8 &aDes);</codeph> </p> <p> <codeph>TDes8& operator=(const
+TDes8 &aDes);</codeph> </p> <p> <codeph>TInt MaxLength() const;</codeph> </p> <p> <codeph>TInt
+MaxSize() const;</codeph> </p> <p> <codeph>const TUint8 &operator[](TInt
+anIndex) const;</codeph> </p> <p> <codeph>TUint8 &operator[](TInt anIndex);</codeph> </p> <p> <codeph>TDes8
+&operator+=(const TDesC8 &aDes);</codeph> </p> <p> <codeph>void Zero();</codeph> </p> <p> <codeph>void
+SetLength(TInt aLength);</codeph> </p> <p> <codeph>void SetMax();</codeph> </p> <p> <codeph>void
+Copy(const TDesC8 &aDes);</codeph> </p> <p> <codeph>void Copy(const TUint8
+*aBuf,TInt aLength);</codeph> </p> <p> <codeph>void Copy(const TUint8 *aString);</codeph> </p> <p> <codeph>void
+Copy(const TDesC16 &aDes);</codeph> </p> <p> <codeph>void Append(TChar
+aChar);</codeph> </p> <p> <codeph>void Append(const TDesC8 &aDes);</codeph> </p> <p> <codeph>void
+Append(const TDesC16 &aDes);</codeph> </p> <p> <codeph>void Append(const
+TUint8 *aBuf,TInt aLength);</codeph> </p> <p> <codeph>void Fill(TChar aChar);</codeph> </p> <p> <codeph>void
+Fill(TChar aChar,TInt aLength);</codeph> </p> <p> <codeph>void FillZ();</codeph> </p> <p> <codeph>void
+FillZ(TInt aLength);</codeph> </p> <p> <codeph>void Num(TInt64 aVal);</codeph> </p> <p> <codeph> void
+Num(TUint64 aVal, TRadix aRadix);</codeph> </p> <p> <codeph>void NumFixedWidth(TUint
+aVal,TRadix aRadix,TInt aWidth);</codeph> </p> <p> <codeph>void
+AppendNum(TInt64 aVal);</codeph> </p> <p> <codeph>void AppendNum(TUint64
+aVal, TRadix aRadix);</codeph> </p> <p> <codeph>void AppendNumFixedWidth(TUint
+aVal,TRadix aRadix,TInt aWidth);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-6DF731E4-5691-31C4-BEE0-03A3873F15EC.dita"><apiname>TPtrC8</apiname></xref> </p> </entry>
+<entry><p>Same as for user side code. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-C0D29B11-1535-3D11-B318-B18D30A6120B.dita"><apiname>TPtr8</apiname></xref> </p> </entry>
+<entry><p>Same as for user side code. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-5B1CA2E7-E3A7-3AF8-9EB0-662E130C45DA.dita"><apiname>TBufC8</apiname></xref> </p> </entry>
+<entry><p>Same as for user side code. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-78E993D5-A845-32B4-B41A-947ABEF16AA0.dita"><apiname>TBuf8</apiname></xref> </p> </entry>
+<entry><p>Same as for user side code. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-6A13E649-D15A-3BD7-B5C2-4DC23211F276.dita"><apiname>TDes8Overflow</apiname></xref> </p> </entry>
+<entry><p>Same as for user side code. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-A188447C-9DAA-3963-B6F2-893910450FC7.dita"><apiname>TLitC8</apiname></xref> </p> </entry>
+<entry><p>Same as for user side code. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p id="GUID-F8164DF1-8875-5C83-9165-9902EB51A97C"><b>Arrays</b> </p> <p>The
+following classes, defined in <filepath>e32cmn.h</filepath>, <i>can</i> be
+used on the kernel side. </p> <p>For some classes, the kernel side can use
+the same member functions that are available to the user side. However, for
+other classes, the kernel side is restricted to using a subset of functions;
+where this is the case, the functions are listed </p> <table id="GUID-858768C2-7159-5AF9-9704-C95F6FB14204">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><p> <b>Classes available </b> </p> </entry>
+<entry><p> <b>Public member functions that are available to kernel side code</b> </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-FAEBF321-6B08-3041-A01F-B1E7282D0707.dita"><apiname> RArray</apiname></xref> <class T> </p> </entry>
+<entry><p> <codeph>RArray();</codeph> </p> <p> <codeph>RArray(TInt aGranularity);</codeph> </p> <p> <codeph>RArray(TInt
+aGranularity, TInt aKeyOffset);</codeph> </p> <p> <codeph>RArray(TInt aMinGrowBy,
+TInt aKeyOffset, TInt aFactor);</codeph> </p> <p> <codeph>void
+Close(); inline TInt Count() const;</codeph> </p> <p> <codeph>const T&
+operator[](TInt anIndex) const;</codeph> </p> <p> <codeph>T& operator[](TInt
+anIndex);</codeph> </p> <p> <codeph>TInt Append(const T& anEntry);</codeph> </p> <p> <codeph>TInt
+Insert(const T& anEntry, TInt aPos);</codeph> </p> <p> <codeph>void Remove(TInt
+anIndex);</codeph> </p> <p> <codeph>void Compress();</codeph> </p> <p> <codeph>void
+Reset();</codeph> </p> <p> <codeph>TInt Find(const T& anEntry) const;</codeph> </p> <p> <codeph>TInt
+Find(const T& anEntry, TIdentityRelation<T> anIdentity)
+const;</codeph> </p> <p> <codeph>TInt FindInSignedKeyOrder(const T& anEntry)
+ const;</codeph> </p> <p> <codeph> TInt FindInUnsignedKeyOrder(const
+T& anEntry) const;</codeph> </p> <p> <codeph>TInt
+FindInOrder(const T& anEntry, TLinearOrder<T>
+anOrder) const;</codeph> </p> <p> <codeph>TInt FindInSignedKeyOrder(const
+T& anEntry, TInt& anIndex) const;</codeph> </p> <p> <codeph>TInt
+FindInUnsignedKeyOrder(const T& anEntry, TInt&
+anIndex) const;</codeph> </p> <p> <codeph>TInt FindInOrder(const T& anEntry,
+TInt& anIndex, TLinearOrder<T> anOrder) const;</codeph> </p> <p> <codeph>TInt
+SpecificFindInSignedKeyOrder(const T& anEntry, TInt
+aMode) const;</codeph> </p> <p> <codeph>TInt SpecificFindInUnsignedKeyOrder(const
+T& anEntry, TInt aMode) const;</codeph> </p> <p> <codeph>TInt
+SpecificFindInOrder(const T& anEntry, TLinearOrder<T>
+anOrder, TInt aMode) const;</codeph> </p> <p> <codeph>TInt SpecificFindInSignedKeyOrder(const
+T& anEntry, TInt& anIndex, TInt aMode) const;</codeph> </p> <p> <codeph>TInt
+SpecificFindInUnsignedKeyOrder(const T& anEntry,
+TInt& anIndex, TInt aMode) const;</codeph> </p> <p> <codeph>TInt SpecificFindInOrder(const
+T& anEntry, TInt& anIndex, TLinearOrder<T>
+anOrder, TInt aMode) const;</codeph> </p> <p> <codeph>TInt InsertInSignedKeyOrder(const
+T& anEntry);</codeph> </p> <p> <codeph>TInt InsertInUnsignedKeyOrder(const
+T& anEntry);</codeph> </p> <p> <codeph>TInt InsertInOrder(const
+T& anEntry, TLinearOrder<T> anOrder);</codeph> </p> <p> <codeph>TInt
+InsertInSignedKeyOrderAllowRepeats(const T& anEntry);</codeph> </p> <p> <codeph>TInt
+InsertInUnsignedKeyOrderAllowRepeats(const T& anEntry);</codeph> </p> <p> <codeph>TInt
+InsertInOrderAllowRepeats(const T& anEntry, TLinearOrder<T>
+anOrder);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-FAEBF321-6B08-3041-A01F-B1E7282D0707.dita"><apiname>RArray</apiname></xref> <TInt> </p> </entry>
+<entry><p> <codeph>RArray();</codeph> </p> <p> <codeph>RArray(TInt aGranularity);</codeph> </p> <p> <codeph>RArray(TInt
+aMinGrowBy, TInt aFactor);</codeph> </p> <p> <codeph>void Close();</codeph> </p> <p> <codeph>TInt
+Count() const;</codeph> </p> <p> <codeph>const TInt& operator[](TInt
+anIndex) const;</codeph> </p> <p> <codeph>TInt& operator[](TInt anIndex);</codeph> </p> <p> <codeph>TInt
+Append(TInt anEntry);</codeph> </p> <p> <codeph>TInt Insert(TInt anEntry,
+TInt aPos);</codeph> </p> <p> <codeph>void Remove(TInt anIndex);</codeph> </p> <p> <codeph>void
+Compress();</codeph> </p> <p> <codeph>void Reset();</codeph> </p> <p> <codeph>TInt
+Find(TInt anEntry) const;</codeph> </p> <p> <codeph>TInt FindInOrder(TInt
+anEntry) const;</codeph> </p> <p> <codeph>TInt FindInOrder(TInt anEntry,
+TInt& anIndex) const; </codeph> </p> <p> <codeph>TInt
+SpecificFindInOrder(TInt anEntry, TInt aMode) const;</codeph> </p> <p> <codeph>TInt
+SpecificFindInOrder(TInt anEntry, TInt& anIndex,
+TInt aMode) const;</codeph> </p> <p> <codeph>TInt InsertInOrder(TInt anEntry);</codeph> </p> <p> <codeph>TInt
+InsertInOrderAllowRepeats(TInt anEntry);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-FAEBF321-6B08-3041-A01F-B1E7282D0707.dita"><apiname>RArray</apiname></xref> <TUint> </p> </entry>
+<entry><p> <codeph>RArray();</codeph> </p> <p> <codeph>RArray(TInt aGranularity);</codeph> </p> <p> <codeph>RArray(TInt
+aMinGrowBy, TInt aFactor);</codeph> </p> <p> <codeph>void Close();</codeph> </p> <p> <codeph>TInt
+Count() const;</codeph> </p> <p> <codeph>const TUint& operator[](TInt
+anIndex) const;</codeph> </p> <p> <codeph>TUint& operator[](TInt anIndex);</codeph> </p> <p> <codeph>TInt
+Append(TUint anEntry);</codeph> </p> <p> <codeph>TInt Insert(TUint anEntry,
+TInt aPos);</codeph> </p> <p> <codeph>void Remove(TInt anIndex);</codeph> </p> <p> <codeph>void
+Compress();</codeph> </p> <p> <codeph>void Reset();</codeph> </p> <p> <codeph>TInt
+Find(TUint anEntry) const;</codeph> </p> <p> <codeph>TInt FindInOrder(TUint
+anEntry) const;</codeph> </p> <p> <codeph>TInt FindInOrder(TUint anEntry,
+TInt& anIndex) const; </codeph> </p> <p> <codeph>TInt
+SpecificFindInOrder(TUint anEntry, TInt aMode) const;</codeph> </p> <p> <codeph>TInt
+SpecificFindInOrder(TUint anEntry, TInt& anIndex,
+TInt aMode) const;</codeph> </p> <p> <codeph>TInt InsertInOrder(TUint anEntry);</codeph> </p> <p> <codeph>TInt
+InsertInOrderAllowRepeats(TUint anEntry);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-AAA13D1F-1BD7-3331-BB8C-11FA2795B53F.dita"><apiname>RPointerArray</apiname></xref> <class T> </p> </entry>
+<entry><p> <codeph>RPointerArray();</codeph> </p> <p> <codeph>RPointerArray(TInt
+aGranularity);</codeph> </p> <p> <codeph>RPointerArray(TInt aMinGrowBy, TInt
+aFactor);</codeph> </p> <p> <codeph>void Close();</codeph> </p> <p> <codeph>TInt
+Count() const;</codeph> </p> <p> <codeph>T* const& operator[](TInt anIndex)
+const;</codeph> </p> <p> <codeph>T*& operator[](TInt anIndex);</codeph> </p> <p> <codeph>TInt
+Append(const T* anEntry);</codeph> </p> <p> <codeph>TInt Insert(const T*
+anEntry, TInt aPos);</codeph> </p> <p> <codeph>void Remove(TInt anIndex);</codeph> </p> <p> <codeph>void
+Compress();</codeph> </p> <p> <codeph>void Reset();</codeph> </p> <p> <codeph>void
+ResetAndDestroy();</codeph> </p> <p> <codeph>TInt Find(const T* anEntry)
+const;</codeph> </p> <p> <codeph>TInt Find(const T* anEntry, TIdentityRelation<T>
+ anIdentity) const;</codeph> </p> <p> <codeph>TInt FindInAddressOrder(const
+T* anEntry) const;</codeph> </p> <p> <codeph>TInt FindInOrder(const T* anEntry,
+TLinearOrder<T> anOrder) const;</codeph> </p> <p> <codeph>TInt
+FindInAddressOrder(const T* anEntry, TInt& anIndex)
+const;</codeph> </p> <p> <codeph>TInt FindInOrder(const T* anEntry, TInt&
+anIndex, TLinearOrder<T> anOrder) const;</codeph> </p> <p> <codeph>TInt
+SpecificFindInAddressOrder(const T* anEntry, TInt aMode)
+const;);</codeph> </p> <p> <codeph>TInt SpecificFindInOrder(const T* anEntry,
+ TLinearOrder<T> anOrder, TInt aMode) const;</codeph> </p> <p> <codeph>TInt
+SpecificFindInAddressOrder(const T* anEntry, TInt&
+anIndex, TInt aMode) const;</codeph> </p> <p> <codeph>TInt SpecificFindInOrder(const
+T* anEntry, TInt& anIndex, TLinearOrder<T> anOrder,
+TInt aMode) const;</codeph> </p> <p> <codeph>TInt InsertInAddressOrder(const
+T* anEntry);</codeph> </p> <p> <codeph>TInt InsertInOrder(const T* anEntry,
+ TLinearOrder<T> anOrder);</codeph> </p> <p> <codeph>TInt
+InsertInAddressOrderAllowRepeats(const T* anEntry);</codeph> </p> <p> <codeph>TInt
+InsertInOrderAllowRepeats(const T* anEntry, TLinearOrder<T>
+anOrder);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-E75F040A-CEC6-3751-8F96-F16AEDC209A3.dita"><apiname>TIdentityRelation </apiname></xref> <class T> </p> </entry>
+<entry><p>Same as for user side code. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-C028C373-CE25-3832-855E-17FB738721CF.dita"><apiname>TLinearOrder</apiname></xref> <class T> </p> </entry>
+<entry><p>Same as for user side code. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p id="GUID-0BC2B8B1-F797-5B65-9EE7-36A2EC5C9BC5"><b>Character representation</b> </p> <p>The
+following class, defined in <filepath>e32cmn.h</filepath>, <i>can</i> be used
+on the kernel side. </p> <p>For some classes, the kernel side can use the
+same member functions that are available to the user side. However, for other
+classes, the kernel side is restricted to using a subset of functions; where
+this is the case, the functions are listed </p> <table id="GUID-F24ABED3-1122-5FE2-8E00-87B610F7E2A6">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><p> <b>Classes available </b> </p> </entry>
+<entry><p> <b>Public member functions that are available to kernel side code</b> </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-CDCFA2A5-EA8A-3B39-B90F-77AC41571E2D.dita"><apiname>TChar</apiname></xref> </p> </entry>
+<entry><p> <codeph>TChar();</codeph> </p> <p> <codeph>TChar(TUint aChar);</codeph> </p> <p> <codeph>TChar&
+operator-=(TUint aChar);</codeph> </p> <p> <codeph>TChar& operator+=(TUint
+aChar);</codeph> </p> <p> <codeph>TChar operator-(TUint aChar);</codeph> </p> <p> <codeph>TChar
+operator+(TUint aChar);</codeph> </p> <p> <codeph>operator TUint() const;</codeph> </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p id="GUID-682EF1C2-4756-5E5A-B4E9-00AABD5D4CE2"><b>Basic utility
+functions and classes</b> </p> <p>The following global utility functions and
+classes, defined in <filepath>e32cmn.h</filepath>, <i>can</i> be used on the
+kernel side. </p> <table id="GUID-1754BDC5-BFB7-5E32-A956-2289FDB1C172">
+<tgroup cols="1"><colspec colname="col0"/>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-5391E485-A019-358F-85D2-3B55BA439BD1.dita"><apiname>TRefByValue</apiname></xref> </p> </entry>
+</row>
+<row>
+<entry><p> <codeph>TInt Lim(TInt aVal,TUint aLimit);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p> <codeph>TInt LimX(TInt aVal,TUint aLimit);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>template <class T> <codeph>T Min(T aLeft,T aRight);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>template <class T> <codeph>T Min(T aLeft,TUint
+ aRight);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>template <class T> <codeph>T Max(T aLeft,T aRight);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>template <class T> <codeph>T Max(T aLeft,TUint
+ aRight);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>template <class T> <codeph>T Abs(T aVal);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>template <class T> <codeph>TBool Rng(T aMin,T aVal,T
+ aMax);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>template <class T,class S> <codeph>T* PtrAdd(T* aPtr,S
+ aVal);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>template <class T,class S> <codeph>T* PtrSub(T* aPtr,S
+ aVal);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>template <class T> <codeph>T Align2(T aValue);</codeph> </p> </entry>
+</row>
+<row>
+<entry><p>template <class T> <codeph>T Align4(T aValue);</codeph> </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p id="GUID-331E0310-69A3-58A6-B932-F2B44201530D"><b>The Package
+Buffers API</b> </p> <p>The package buffers API, represented by classes defined
+in <filepath>e32cmn.h</filepath>, <i>can</i> be used on the kernel side. </p> <table id="GUID-CE1782C9-E59A-567C-8F6F-DA5AE7C50476">
+<tgroup cols="1"><colspec colname="col0"/>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-C7A094BD-846F-3ED2-8CCE-C0743DB3712A.dita"><apiname>TPckgBuf</apiname></xref> </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-36B29964-420D-38D0-AF08-4DA70BED8B6E.dita"><apiname>TPckgC</apiname></xref> </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-4DFB8E64-81FF-3D3B-9694-CE51B11DA69A.dita"><apiname>TPckg</apiname></xref> </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p id="GUID-5707529F-6145-58C3-A0A9-8789FF8F1C93"><b>The UID manipulation
+APIs</b> </p> <p>The UID manipulation APIs, represented by classes defined
+in <filepath>e32cmn.h</filepath> can be used on the kernel side. However,
+only a <i>subset</i> of functions are available. See the detailed notes in
+the following table. </p> <table id="GUID-4E17CB02-80F9-5D3A-A3F0-0C6208D759F5">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><p> <xref href="GUID-530281E6-29FC-33F2-BC9B-610FBA389444.dita"><apiname>TUid</apiname></xref> </p> </entry>
+<entry><p>Only the two inline functions can be used: </p> <ul>
+<li id="GUID-1FA84853-4983-500F-B38E-AA82BB5456D6"><p> <xref href="GUID-530281E6-29FC-33F2-BC9B-610FBA389444.dita#GUID-530281E6-29FC-33F2-BC9B-610FBA389444/GUID-65B526E7-8629-3DEC-970B-1D48263D7AFD"><apiname>TUid::Uid</apiname></xref> </p> </li>
+<li id="GUID-B588EEC3-4DB9-51D3-9DCA-DAF822006C4B"><p> <xref href="GUID-530281E6-29FC-33F2-BC9B-610FBA389444.dita#GUID-530281E6-29FC-33F2-BC9B-610FBA389444/GUID-B7F5CA42-157B-3D74-BA2E-00B290F71345"><apiname>TUid::Null()</apiname></xref> </p> </li>
+</ul> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-B6D6B0AD-B15C-339A-8540-40540885089A.dita"><apiname>TUidType</apiname></xref> </p> </entry>
+<entry><p>None of the member functions can be used; however, the <codeph>iUid</codeph> data
+member is declared as public on the kernel side. </p> </entry>
+</row>
+<row>
+<entry><p> <xref href="GUID-1FB6F0D5-96F9-3D31-8508-9CE731A2E8E4.dita"><apiname>TUidName</apiname></xref> </p> </entry>
+<entry><p>This will only ever be an 8-bit type descriptor. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p id="GUID-E9F32C01-5C4F-5706-B992-A4F8B01171FD"><b>Version handling
+API</b> </p> <p>The version handling API, represented by the <xref href="GUID-D82DEC7A-71C2-3004-BFC2-C82C009A2715.dita"><apiname>TVersion</apiname></xref> class
+defined in <filepath>e32cmn.h</filepath> can be used on the kernel side. </p> <p id="GUID-E67B4238-3CFF-5448-B711-FCD14D8D3C10"><b>TRequestStatus</b> </p> <p>The <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> class
+representing the completion status of an asynchronous request, and defined
+in <filepath>e32cmn.h</filepath> can be used on the kernel side. </p> <p id="GUID-0CA35DBF-C10D-5C35-90CD-24C53AEA41BF"><b>TIpcArgs</b> </p> <p>The <xref href="GUID-4AD02F14-1142-372F-9D11-224595932034.dita"><apiname>TIpcArgs</apiname></xref> class, which is part of the Version2 client/server APIs,
+and defined in <filepath>e32cmn.h</filepath>, can be used on the kernel side.
+However, the <codeph>Set()</codeph> and <codeph>Type()</codeph> member functions
+that take 16-bit descriptors are not available. </p> <p id="GUID-111081C5-5BDA-516B-9B3D-9D24FAD31E5D"><b>Basic
+graphic classes</b> </p> <p>The basic graphic classes <xref href="GUID-339EC4C5-89DC-3972-9579-6DD38D418317.dita"><apiname>TPoint</apiname></xref> and <xref href="GUID-938244B2-5E1A-39F7-8ACA-E6DE4C44A313.dita"><apiname>TSize</apiname></xref> are
+defined on the kernel side. However, only the public data members are defined
+- the member functions are not defined, and are not available for use. </p> </section>
+<section id="GUID-6AE21206-A29D-5CB6-83E9-69C2E7DA566A"><title>Coding techniques
+to replace EUSER functionality</title> <ul>
+<li id="GUID-19997154-7682-5FA8-85EA-2E24683398D5"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-CA520DD3-3601-5774-87F2-D5BA4DA2BF8E">Buffers: replacing HBufC8 with HBuf</xref> </p> </li>
+<li id="GUID-DBAA1CE6-9A00-5A97-8954-C2B3E4DC8B3C"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-310ADB7F-A03C-5994-A918-634B7BAB7DD8">Buffers: replacing HBufC8 with C style pointers</xref> </p> </li>
+<li id="GUID-44A25AD2-1970-5D1E-8B51-B92232F14E6F"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-586DD3B4-69DB-564B-AB8D-B3A02607CE02">Handling 16-bit data items</xref> </p> </li>
+<li id="GUID-E9549A58-6921-5521-ACCA-E74DD962FFBC"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-77C88D19-50C3-5D69-8084-BE750F100BA0">Replacing CBase with DBase</xref> </p> </li>
+<li id="GUID-BC1219A8-4F8F-5E91-ABE9-E8D89F904D58"><p> <xref href="GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita#GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7/GUID-585EE1D8-6080-5B37-A3BD-278B8731B7F9">Replacing User::QueryVersionSupported() with Kern::QueryVersionSupported()</xref> </p> </li>
+</ul> <p id="GUID-CA520DD3-3601-5774-87F2-D5BA4DA2BF8E"><b>Buffers: replacing
+HBufC8 with HBuf</b> </p> <p>In EKA2, the heap descriptor buffer, <xref href="GUID-2A528453-0279-3E47-838C-F8A8D29B88F1.dita"><apiname>HBufC8</apiname></xref> is
+not available. However, the kernel side defines and implements an equivalent
+(kernel) heap descriptor buffer: <xref href="GUID-1E0F353F-2532-3FF2-9992-06EC687C3998.dita"><apiname>HBuf8</apiname></xref>. <xref href="GUID-1E0F353F-2532-3FF2-9992-06EC687C3998.dita"><apiname>HBuf8</apiname></xref> is
+behaves in a similar way to <xref href="GUID-2A528453-0279-3E47-838C-F8A8D29B88F1.dita"><apiname>HBufC8</apiname></xref>, so nearly all of your
+code can be reused, but note the following points: </p> <ul>
+<li id="GUID-409FC5CB-F502-54ED-972E-D00AF311180C"><p>If your code uses the
+typedef <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref>, then you need to change it to <xref href="GUID-5BEA9976-B969-3949-B855-E657FFF38EE2.dita"><apiname>HBuf</apiname></xref>. </p> </li>
+<li id="GUID-889793AE-1F58-5FAE-9C58-04E3549526F9"><p>On the kernel side,
+there is no explicit support for 16-bit buffers, which means that there is
+no class called HBuf16. In practice, this means that, <xref href="GUID-5BEA9976-B969-3949-B855-E657FFF38EE2.dita"><apiname>HBuf</apiname></xref> is
+always the same as <xref href="GUID-1E0F353F-2532-3FF2-9992-06EC687C3998.dita"><apiname>HBuf8</apiname></xref>. </p> </li>
+<li id="GUID-58F6F261-69EA-5D2E-BAF1-9EF844F13B5A"><p>Unlike <xref href="GUID-2A528453-0279-3E47-838C-F8A8D29B88F1.dita"><apiname>HBufC8</apiname></xref>, <xref href="GUID-1E0F353F-2532-3FF2-9992-06EC687C3998.dita"><apiname>HBuf8</apiname></xref> is
+a modifiable type descriptor. It has <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes8</apiname></xref> in its derivation
+hierarchy, and this means that you can manipulate the descriptor's data (using
+the <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes8</apiname></xref> member functions). </p> </li>
+<li id="GUID-3D649264-94C6-598A-9F90-5ED6988A3B66"><p>The number of functions
+available to create an <xref href="GUID-1E0F353F-2532-3FF2-9992-06EC687C3998.dita"><apiname>HBuf8</apiname></xref> object is more limited than
+for <xref href="GUID-2A528453-0279-3E47-838C-F8A8D29B88F1.dita"><apiname>HBufC8</apiname></xref> - there are only three variants - although in
+practice this is not a problem: </p> <ul>
+<li id="GUID-3B3B2A9D-13E0-57D4-A9F9-F308580B8F28"><p> <codeph>HBuf8::New(TInt
+aMaxLength)</codeph> to allocate a heap descriptor buffer (on the kernel heap)
+and set its length to zero; this behaves the same as the user side <codeph>HBufC8::New(TInt
+aMaxLength)</codeph> </p> </li>
+<li id="GUID-213F8721-16E5-5E64-9D0A-E84E75831FB5"><p> <codeph>HBuf8::New(const
+TDesC8& aDes)</codeph> to allocate a heap descriptor buffer (on the kernel
+heap) and initialise it by copying an existing descriptor's data into it. </p> </li>
+<li id="GUID-EBC5B863-9671-52C8-B22A-D303AA963697"><p> <codeph>HBuf8::ReAlloc(TInt
+aNewMax)</codeph> to re-allocate (i.e. to resize) a heap descriptor buffer
+(on the kernel heap); this behaves the same as the user side <codeph>HBufC8::New(TInt
+aMaxLength)</codeph> </p> </li>
+</ul> </li>
+<li id="GUID-67068834-2B86-5901-9BB7-C8E0158BBDA5"><p>There are no "leaving"
+variants of these functions - if you have NewL(), NewLC(), and other "leaving"
+variants, then you will need to change your code to explicitly check the return
+code to make sure that the creation, or the reallocation of the heap descriptor
+buffer has worked. </p> </li>
+<li id="GUID-D6FE65EF-A142-5B19-9F6E-718C9844B04B"><p>As the descriptor is
+modifiable, there is no need for, and there is no equivalent of the function <xref href="GUID-2A528453-0279-3E47-838C-F8A8D29B88F1.dita#GUID-2A528453-0279-3E47-838C-F8A8D29B88F1/GUID-155C7682-B1C4-38D0-9542-3829DF383050"><apiname>HBufC8::Des()</apiname></xref>;
+you just use the base class <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes8</apiname></xref> functions. </p> </li>
+<li id="GUID-28F7E8E5-4E78-5175-93B2-CA8365978A10"><p>If your code uses the
+assignment operators (i.e. the <codeph>=</codeph> operator), you don't need
+to change your code; the compiler will use the operators implemented in the <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes8</apiname></xref> base
+class, which will do the right thing. </p> </li>
+<li id="GUID-2909D8CE-D267-5EB7-9870-5253438F7E98"><p>The descriptor function <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita#GUID-FB97E0A3-352A-316F-97C6-69E4741A8120/GUID-FF9F5F8C-A240-354E-BBD3-44772AE5C4A4"><apiname>TDesC8::Alloc()</apiname></xref> is
+no longer available on the kernel side, so you cannot create a heap descriptor
+buffer from a general descriptor. </p> </li>
+</ul> <p>The following code fragments show code that is approximately equivalent
+between EKA1 and EKA2. The fragments are a little artificial, and make assumptions
+that would not necessarily be made in real code, but nevertheless still show
+the essential differences. </p> <table id="GUID-C5338045-8A9C-5605-AB94-04D2770183E0">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><p> <b>EKA1</b> </p> </entry>
+<entry><p> <b>EKA2</b> </p> </entry>
+</row>
+<row>
+<entry><p>This is a function that allocates a heap descriptor buffer (<xref href="GUID-2A528453-0279-3E47-838C-F8A8D29B88F1.dita"><apiname>HBufC8</apiname></xref>),
+puts data into it, changes its size, replaces the data, deletes a part of
+the data, and then deletes it. </p> <codeblock id="GUID-DEA8F91F-DE46-5DCF-BF06-9F4E89C5F366" xml:space="preserve">_LIT8(KTxSmall,"abcdef");
+_LIT8(KTxBig,"ghijklmnopqrstuvwxyz");
+
+void X::FunctionL()
+ {
+ // Create a buffer big enough to contain
+ // the text "abcdef".
+ // This uses the "leaving" variant, and leaves
+ // if there is insufficient memory.
+ HBufC8* pBuf = HBufC8::NewL(KTxSmall().Length());
+
+ // Copy the text "abcdedf" into it
+ *pBUf = KTxSmall;
+
+ // Make the buffer bigger...
+ // ... and check that it worked OK
+ // Note that we are using the non-leaving version.
+ // We could use the leaving version, but we would
+ // need to handle the cleanup of pBuf
+ HBuf8* pNewBuf = pBuf->ReAlloc(KTxBig().Length());;
+
+ if (pNewBuf)
+ {
+ pBuf = pNewBuf;
+ }
+ else
+ {
+ delete pBuf;
+ User::Leave(KErrNoMemory);
+ }
+
+ // Replace content of the descriptor with
+ // the text "ghijkl......"
+ *pBuf = KTxBig;
+
+ // Need to use the Des() function to create
+ // a modifiable descriptor before we can make
+ // changes to the text in the descriptor.
+ TPtr8 pDesPtr;
+ pDesPtr = pBuf->Des();
+
+ // Delete the 1st two characters.
+ PDesPtr.Delete(0,2)
+
+ delete pBUf;
+
+ return;
+ }</codeblock> </entry>
+<entry><p>A similar function, but it uses <xref href="GUID-1E0F353F-2532-3FF2-9992-06EC687C3998.dita"><apiname>HBuf8</apiname></xref> instead. </p> <codeblock id="GUID-927B0A0C-D65B-5E5C-811D-285437C473BE" xml:space="preserve">_LIT8(KTxSmall,"abcdef");
+_LIT8(KTxBig,"ghijklmnopqrstuvwxyz");
+
+TInt X::Function()
+ {
+ // Create a buffer big enough to contain
+ // the text "abcdef", and copy the text
+ // from its source into the buffer.
+ //
+ // You need to check explicitly that this
+ // has worked.
+ HBuf8* pBuf = HBuf8::New(KTxSmall);
+ if (!pBuf)
+ {
+ return KErrNoMemory;
+ }
+
+ // Make the buffer bigger...
+ // .. and check that it worked OK
+ HBuf8* pNewBuf = pBuf->ReAlloc(KTxBig().Length());
+
+ if (pNewBuf)
+ {
+ pBuf = pNewBuf;
+ }
+ else
+ {
+ delete pBuf;
+ return KErrNoMemory;
+ }
+
+ // You can still use the =operator to replace
+ // the content of the heap descriptor !
+ // Replace content with
+ // the text "ghijkl......"
+ *pBuf = KTxBig;
+
+
+ // Can now use use the TDes8 functions
+ // directly.
+ // This deletes the 1st two characters.
+ pBuf->Delete(0,2);
+
+ // delete the heap descriptor
+ delete pBUf;
+
+ return KErrNone;
+ }</codeblock> </entry>
+</row>
+<row>
+<entry><p>A small code fragment that uses <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita#GUID-FB97E0A3-352A-316F-97C6-69E4741A8120/GUID-FF9F5F8C-A240-354E-BBD3-44772AE5C4A4"><apiname>TDesC8::Alloc()</apiname></xref> to
+create an <xref href="GUID-2A528453-0279-3E47-838C-F8A8D29B88F1.dita"><apiname>HBufC8</apiname></xref> heap descriptor buffer from an existing
+descriptor. </p> <codeblock id="GUID-7545CD6E-8849-5CE0-88A8-975F141A7877" xml:space="preserve">HBufC8* X::Function(const TDesC8& aDes)
+ {
+ // Returns NULL if creation
+ // of the heap descriptor buffer fails.
+
+ return aDes.Alloc();
+ }</codeblock> <p>or possibly: </p> <codeblock id="GUID-0E01D617-B83F-558A-8C6B-BF9BD8B2E449" xml:space="preserve">HBufC8* X::FunctionL(const TDesC8& aDes)
+ {
+ // Leaves if creation of the heap
+ // descriptor buffer fails, otherwise it
+ // returns a valid pointer.
+
+ return(aDes.AllocL());
+ }</codeblock> </entry>
+<entry><p>An equivalent code fragment that creates an <xref href="GUID-1E0F353F-2532-3FF2-9992-06EC687C3998.dita"><apiname>HBuf8</apiname></xref> heap
+descriptor buffer. </p> <codeblock id="GUID-EA7187B6-8365-5F77-941A-CCCC359BF5D0" xml:space="preserve">HBuf8* X::Function(const TDesC8& aDes)
+ {
+ // Returns NULL if creation
+ // of the heap descriptor buffer fails.
+
+ return (HBuf8::New(aDes));
+ }</codeblock> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p id="GUID-310ADB7F-A03C-5994-A918-634B7BAB7DD8"><b>Buffers: replacing
+HBufC8 with C style pointers</b> </p> <p>Instead of replacing <xref href="GUID-2A528453-0279-3E47-838C-F8A8D29B88F1.dita"><apiname>HBufC8</apiname></xref> with <xref href="GUID-5BEA9976-B969-3949-B855-E657FFF38EE2.dita"><apiname>HBuf</apiname></xref>,
+it may be more suitable to replace your heap descriptor buffers with C style
+pointers - effectively managing your buffers in open code or as part of the
+implementation of your own purpose written classes. </p> <p>You allocate memory
+from the kernel heap using <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-DCB1C323-54D4-3C43-849A-503C19075C18"><apiname>Kern::Alloc()</apiname></xref> or <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-25A2BC43-08AB-34E8-93B4-AD4B82A98666"><apiname>Kern::AllocZ()</apiname></xref> and
+track the pointers to that memory. The following code fragments show how the
+use of HBufC8 translates to the direct use of these functions. </p> <p>Although
+the EKA2 code here uses <xref href="GUID-E2C25A1E-46B4-3697-A939-613CA366D87A.dita"><apiname>memcpy()</apiname></xref>, and <xref href="GUID-AC5005AE-EDC0-36EE-B877-2F91B09B0068.dita"><apiname>memmove()</apiname></xref>,
+you will also find the functions <xref href="GUID-5F6B1E3D-4F68-3870-96E2-8EA88D70C888.dita"><apiname>memclr()</apiname></xref>, <xref href="GUID-5A95E126-A82F-3F29-9810-FA1CD35E8B19.dita"><apiname>memset()</apiname></xref>, <xref href="GUID-9A49DF44-1742-32CF-8C13-AF732C3971A6.dita"><apiname>wordmove()</apiname></xref> and <xref href="GUID-57B71C3A-3F1E-3304-AA6C-EF53CD6682AD.dita"><apiname>memcompare()</apiname></xref> useful in your code. </p> <table id="GUID-A6F83848-EEE6-5656-BBD9-6CA8CC986AAD">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><p> <b>EKA1</b> </p> </entry>
+<entry><p> <b>EKA2</b> </p> </entry>
+</row>
+<row>
+<entry><p>This is a function that allocates a heap descriptor buffer (<xref href="GUID-2A528453-0279-3E47-838C-F8A8D29B88F1.dita"><apiname>HBufC8</apiname></xref>),
+puts data into it, changes its size, replaces the data, deletes a part of
+the data, and then deletes the whole buffer. </p> <codeblock id="GUID-7541F426-A84A-5496-A75D-A5235DD0B45E" xml:space="preserve">_LIT8(KTxSmall,"abcdef");
+_LIT8(KTxBig,"ghijklmnopqrstuvwxyz");
+
+void X::FunctionL()
+ {
+ // Create a buffer big enough to contain
+ // the text "abcdef".
+ // This uses the "leaving" variant, and leaves
+ // if there is insufficient memory.
+ HBufC8* pBuf = HBufC8::NewL(KTxSmall().Length());
+
+ // Copy the text "abcdedf" into it
+ *pBUf = KTxSmall;
+
+ // Make the buffer bigger...
+ // ... and check that it worked OK
+ // Note that we are using the non-leaving version.
+ // We could use the leaving version, but we would
+ // need to handle the cleanup of pBuf
+ HBuf8* pNewBuf = pBuf->ReAlloc(KTxBig().Length());;
+
+ if (pNewBuf)
+ {
+ pBuf = pNewBuf;
+ }
+ else
+ {
+ delete pBuf;
+ User::Leave(KErrNoMemory);
+ }
+
+ // Replace content of the descriptor with
+ // the text "ghijkl......"
+ *pBuf = KTxBig;
+
+ // Need to use the Des() function to create
+ // a modifiable descriptor before we can make
+ // changes to the text in the descriptor.
+ TPtr8 pDesPtr;
+ pDesPtr = pBuf->Des();
+
+ // Delete the 1st two characters.
+ PDesPtr.Delete(0,2)
+
+ delete pBUf;
+
+ return;
+ }</codeblock> </entry>
+<entry><p>A similar function, but allocates memory on the kernel heap explicitly,
+and manages its own pointers instead. Note the use of the nanokernel utility
+function: <xref href="GUID-E2C25A1E-46B4-3697-A939-613CA366D87A.dita"><apiname>memcpy()</apiname></xref>, and <xref href="GUID-AC5005AE-EDC0-36EE-B877-2F91B09B0068.dita"><apiname>memmove()</apiname></xref> </p> <codeblock id="GUID-DB644074-0F80-58CE-9FE9-D5C5AF521849" xml:space="preserve">_LIT8(KTxSmall,"abcdef");
+_LIT8(KTxBig,"ghijklmnopqrstuvwxyz");
+
+TInt X::Function()
+ {
+ // Create a buffer big enough to contain
+ // the text "abcdef", and copy the text
+ // from its source into the buffer.
+ //
+ // Steps.
+ // 1. work out the size of buffer needed
+ // 2. Get the buffer.
+ // 3. Copy the source.
+
+ TInt lengthInBuffer = 0;
+
+ // 1.
+ TInt Smallsize;
+ SmallSize = KTxSmall().Length();
+ lengthInBuffer = SmallSize;
+
+ // 2.
+ TUint8* pBuf;
+ pBuf = Kern::Alloc(SmallSize);
+ if (!pBuf)
+ {
+ return KErrNoMemory;
+ }
+
+ // 3.
+ memcpy(pBuf,KTxSmall().Ptr(),SmallSize));
+
+
+ // Make the buffer bigger.
+ // If it works ok, then copy the data
+ // to the new buffer, delete the old buffer
+ TInt BiggerSize;
+ TUint8* pNewBuf;
+
+ BiggerSize = KTxBig().Length();
+ pNewBuf = Kern::Alloc(BiggerSize);
+ if (pNewBuf)
+ {
+ memcpy(pNewBuf, pBuf, SmallSize);
+ Kern::Free(pBuf);
+ pBuf = pNewBuf;
+ }
+ else
+ {
+ Kern::Free(pBuf);
+ return KErrNoMemory;
+ }
+ lengthInBuffer = BiggerSize;
+
+ // Replace content with
+ // the text "ghijkl......"
+ memcpy(pNewBuf, KTxBig().Ptr(), BiggerSize);
+
+
+ // Delete 1st two characters
+ memmove(pNewBuf, pNewBuf+2, lengthInBuffer;
+ lengthInBuffer -= 2;
+
+ Kern::Free(pBuf);
+
+ return KErrNone;
+ }</codeblock> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p id="GUID-586DD3B4-69DB-564B-AB8D-B3A02607CE02"><b>Handling 16-bit
+data items</b> </p> <p>If you need to handle 16-bit items on the kernel side,
+then you can still use 8-bit heap descriptor buffers. You just need to be
+aware that the data is 16 bit and cast accordingly. The following code fragments
+are simplistic, but show you the basic idea. </p> <table id="GUID-65BA6847-9FC7-53B2-B9F6-2D649D4B75AE">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><p> <b>EKA1</b> </p> </entry>
+<entry><p> <b>EKA2</b> </p> </entry>
+</row>
+<row>
+<entry><p>This is a function which is passed a 16-bit descriptor containing
+16-bit wide characters. </p> <codeblock id="GUID-52B25979-B624-5D89-8D38-ADEDF3F27BED" xml:space="preserve">void X::FunctionL(const TDes16& aDes)
+ {
+ HBuf16* pBuf = aDes.AllocL();
+
+ TInt noOfCharacters;
+ TUint16* pointerToData;
+
+ noOfCharacters = pBuf->Length();
+ pointerToData = pBuf->Ptr();
+
+ ...
+ }</codeblock> </entry>
+<entry><p>This is a similar function which is also passed 16-bit wide characters.
+The function needs slight changes as it can only receive data through an 8-bit
+descriptor. </p> <codeblock id="GUID-DD5720C2-1132-5991-B2E1-71B1BECAC15C" xml:space="preserve">TInt X::Function(const TDes8& aDes)
+ {
+ HBuf8* pBuf = HBuf8::New(aDes);
+ if (!pBuf)
+ {
+ return KErrNoMemory;
+ }
+
+ TInt noOfCharacters;
+ TUint16* pointerToData;
+
+ noOfCharacters = ((pBuf->Length()) >> 1);
+ pointerToData = (TUint16*)(pBuf->Ptr());
+
+ ...
+
+ return KErrNone;
+ }</codeblock> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p id="GUID-77C88D19-50C3-5D69-8084-BE750F100BA0"><b>Replacing CBase
+with DBase</b> </p> <p>The <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita"><apiname>DBase</apiname></xref> class is the kernel-side
+equivalent of the user-side <xref href="GUID-8F6FE089-E2A8-30F4-B67E-10F286347681.dita"><apiname>CBase</apiname></xref> class. It provides zero-filling
+of memory prior to object construction and a virtual destructor in a similar
+way to <xref href="GUID-8F6FE089-E2A8-30F4-B67E-10F286347681.dita"><apiname>CBase</apiname></xref>. </p> <p>If you have a class derived from <xref href="GUID-8F6FE089-E2A8-30F4-B67E-10F286347681.dita"><apiname>CBase</apiname></xref>,
+then all you need to do is: </p> <ul>
+<li id="GUID-B5ABF979-A6E0-5733-AFB2-DAC8FC132BA0"><p>change your class definition
+so that it is derived from <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita"><apiname>DBase</apiname></xref>. </p> </li>
+<li id="GUID-03B04EF1-32FE-5B37-A67C-AE57F8902F8E"><p>Remember to include
+the <filepath>klib.h</filepath> header file. </p> </li>
+</ul> <p>you should not need to do anything else. </p> <p>One additional feature
+provided by <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita"><apiname>DBase</apiname></xref> that is not available in <xref href="GUID-8F6FE089-E2A8-30F4-B67E-10F286347681.dita"><apiname>CBase</apiname></xref> is
+the function <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita#GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3/GUID-40C0DEE0-7E6F-3D28-9B33-77A3CCC4E66E"><apiname>DBase::AsyncDelete()</apiname></xref>. This allows you to delete
+an instance of a <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita"><apiname>DBase</apiname></xref> derived class asynchronously, and
+is useful if you need to delete a <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita"><apiname>DBase</apiname></xref> derived object
+in time-critical code. </p> <p>Internally, asynchronous deletion works by
+placing the object to be deleted onto a queue, and then triggering a DFC,
+which runs in the context of the supervisor thread. This means that only a
+small amount of code is executed by your (the calling) thread, and the actual
+deletion is done by the supervisor thread. </p> <p>Its use is straightforward. </p> <codeblock id="GUID-1C283AE2-391A-5687-BA56-D8C1DD4E7745" xml:space="preserve">class DMyObject : public DBase
+ {
+ ...
+ }</codeblock> <codeblock id="GUID-20E2CA1A-06EE-5ADE-8B5B-14A3CE47ABDB" xml:space="preserve">DMyObject pPtr;
+ ...
+ pPtr = new DMyObject;
+ ...
+ pPtr->AsyncDelete();
+ ...</codeblock> <p id="GUID-585EE1D8-6080-5B37-A3BD-278B8731B7F9"><b>Replacing
+User::QueryVersionSupported() with Kern::QueryVersionSupported()</b> </p> <p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-B68B3E85-D58E-31FD-8BD2-A4F346BF416F"><apiname>User::QueryVersionSupported()</apiname></xref> is
+replaced by <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-A28757CC-B89B-3F63-AD39-9955FBE7533B"><apiname>Kern::QueryVersionSupported()</apiname></xref> on the kernel
+side. </p> <p>The parameters passed to these functions are the same, both
+in type and meaning. The behaviour of both functions is also the same. This
+means that all you need to do is replace <codeph>User::</codeph> with <codeph>Kern::</codeph> in
+your code. </p> </section>
+</conbody></concept>
\ No newline at end of file