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