|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-E8F8A9BE-4DCE-5CB9-BFC7-9BC00A7845F7" xml:lang="en"><title>Descriptors |
|
13 for function interfaces</title><shortdesc>Descriptors to specify interfaces which use or manipulate text |
|
14 strings or general binary data use </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>In conventional ‘C’ programming, interfaces are specified using a combination |
|
16 of <codeph>char*</codeph>, <codeph>void*</codeph> and length values. In Symbian |
|
17 platform, descriptors are always used.</p> |
|
18 <p>There are four main cases:</p> |
|
19 <ul> |
|
20 <li id="GUID-2939B94A-C71E-5270-A385-EBC04471A5A9"><p>Passing a constant string</p> <p>In |
|
21 ‘C’: <codeph>StringRead(const char* aString);</codeph> </p> <p>The |
|
22 length of the string is implied by the zero terminator; therefore, the function |
|
23 does not require the length to be explicitly specified.</p> <p>In Symbian |
|
24 platform: <codeph>StringRead(const TDesC& aString)</codeph>;</p> <p>The |
|
25 descriptor can access the string and contains its length.</p> </li> |
|
26 <li id="GUID-C66E1B0E-55C9-5EDD-A5F5-208B8C0EA96E"><p>Passing a string which |
|
27 can be changed.</p> <p>In ‘C’: <codeph>StringWrite(char* aString, int |
|
28 aMaxLength);</codeph> </p> <p>The length of the passed string is |
|
29 implied by the zero terminator. <codeph>aMaxLength</codeph> indicates the |
|
30 maximum length to which the string may be extended.</p> <p>In Symbian platform: <codeph>StringWrite(TDes& |
|
31 aString);</codeph> </p> <p>The descriptor can access the string and contains |
|
32 its length and the maximum length to which the string may be extended.</p> </li> |
|
33 <li id="GUID-27FD5409-AD86-5CE6-8427-8DF4E977FB7E"><p>Passing a buffer containing |
|
34 general binary data</p> <p>In ‘C’: <codeph>BufferRead(const void* aBuffer, |
|
35 int aLength);</codeph> </p> <p>Both the address and length of |
|
36 the buffer must be specified.</p> <p>In Symbian platform: <codeph>BufferRead(const |
|
37 TDes8& aBuffer);</codeph> </p> <p>The descriptor has access |
|
38 to the address of the buffer and contains the length of the data. The 8 bit |
|
39 variant is explicitly specified; the buffer is treated as byte data, regardless |
|
40 of the build variant.</p> </li> |
|
41 <li id="GUID-46B5ED44-A841-56C4-BCB1-90995C8B79B6"><p>Passing a buffer containing |
|
42 general binary data which can be changed.</p> <p>In ‘C’:<codeph>BufferWrite(void* |
|
43 aBuffer, int& aLength, int aMaxLength);</codeph> </p> <p>The |
|
44 address of the buffer, the current length of the data and the maximum length |
|
45 of the buffer are specified. The <codeph>aLength</codeph> parameter is specified |
|
46 as a reference to allow the function to indicate the length of the data on |
|
47 return.</p> <p>In Symbian platform: <codeph>BufferRead(TDes8& aBuffer);</codeph> </p> <p>The |
|
48 descriptor has access to the adddress of the buffer and contains the length |
|
49 of the data and the maximum length. The 8 bit variant is explicitly specified; |
|
50 the buffer is treated as byte data, regardless of the build variant.</p> </li> |
|
51 </ul> |
|
52 <p>Defining interfaces using the base descriptor classes allows callers to |
|
53 pass all appropriate derived descriptor types.</p> |
|
54 </conbody></concept> |