<?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-E8F8A9BE-4DCE-5CB9-BFC7-9BC00A7845F7" xml:lang="en"><title>Descriptors

for function interfaces</title><shortdesc>Descriptors to specify interfaces which use or manipulate text

strings or general binary data use </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>In conventional ‘C’ programming, interfaces are specified using a combination

of <codeph>char*</codeph>, <codeph>void*</codeph> and length values. In Symbian

platform, descriptors are always used.</p>

<p>There are four main cases:</p>

<ul>

<li id="GUID-2939B94A-C71E-5270-A385-EBC04471A5A9"><p>Passing a constant string</p> <p>In

‘C’: <codeph>StringRead(const char*              aString);</codeph> </p> <p>The

length of the string is implied by the zero terminator; therefore, the function

does not require the length to be explicitly specified.</p> <p>In Symbian

platform: <codeph>StringRead(const TDesC&amp;              aString)</codeph>;</p> <p>The

descriptor can access the string and contains its length.</p> </li>

<li id="GUID-C66E1B0E-55C9-5EDD-A5F5-208B8C0EA96E"><p>Passing a string which

can be changed.</p> <p>In ‘C’: <codeph>StringWrite(char* aString, int    

         aMaxLength);</codeph> </p> <p>The length of the passed string is

implied by the zero terminator. <codeph>aMaxLength</codeph> indicates the

maximum length to which the string may be extended.</p> <p>In Symbian platform: <codeph>StringWrite(TDes&amp;

aString);</codeph> </p> <p>The descriptor can access the string and contains

its length and the maximum length to which the string may be extended.</p> </li>

<li id="GUID-27FD5409-AD86-5CE6-8427-8DF4E977FB7E"><p>Passing a buffer containing

general binary data</p> <p>In ‘C’: <codeph>BufferRead(const void* aBuffer,

int              aLength);</codeph> </p> <p>Both the address and length of

the buffer must be specified.</p> <p>In Symbian platform: <codeph>BufferRead(const

TDes8&amp;              aBuffer);</codeph> </p> <p>The descriptor has access

to the address of the buffer and contains the length of the data. The 8 bit

variant is explicitly specified; the buffer is treated as byte data, regardless

of the build variant.</p> </li>

<li id="GUID-46B5ED44-A841-56C4-BCB1-90995C8B79B6"><p>Passing a buffer containing

general binary data which can be changed.</p> <p>In ‘C’:<codeph>BufferWrite(void*

aBuffer, int&amp;              aLength, int aMaxLength);</codeph> </p> <p>The

address of the buffer, the current length of the data and the maximum length

of the buffer are specified. The <codeph>aLength</codeph> parameter is specified

as a reference to allow the function to indicate the length of the data on

return.</p> <p>In Symbian platform: <codeph>BufferRead(TDes8&amp; aBuffer);</codeph> </p> <p>The

descriptor has access to the adddress of the buffer and contains the length

of the data and the maximum length. The 8 bit variant is explicitly specified;

the buffer is treated as byte data, regardless of the build variant.</p> </li>

</ul>

<p>Defining interfaces using the base descriptor classes allows callers to

pass all appropriate derived descriptor types.</p>

</conbody></concept>