--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-E8F8A9BE-4DCE-5CB9-BFC7-9BC00A7845F7.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,54 @@
+<?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>
\ No newline at end of file