Symbian programming Summary-basics-Descriptor (1)-Descriptor Introduction

This article was originally prepared by Yang. If you need to reselect the article, please indicate the source. Thank you!

I. Enhancing impressions
Before learning the descriptor, you must first understand the role of the descriptor in Symbian. In Symbian, classes specifically used to process strings are not provided. It treats strings and binary buffers as the same type of data and has a set of specialized classes for management, the hierarchical structure of the class relationship diagram of this set of classes is shown in:

Figure 1. Hierarchy of Descriptor classes

The classes shown are collectively referred to as "Descriptors". Symbian uses "Descriptors" to manage strings. Specifically, TDesC, TDes, and TBufCBase are abstract classes.
First, let's give a simple example to enhance our understanding of the descriptor. If we want to store variables by a string "NewLC", we can use the following code in C:

1 2	char[] c = “NewLC”; const char* c = “NewLC”;

In Symbian C ++, which of the above descriptors should be used for storage?
The answer is: you can store any descriptor! Without code, we will first show you how to store strings in memory using different descriptors:

Figure 2. Location of Descriptor object and data in memory

2. Understanding concepts

1. Classification Based on the storage location of Descriptor data (2 ):

• Stack descriptor TBuf and TBufC: data exists as part of the descriptor object, and the descriptor object is stored in the stack of the program, just like the character array (char []) in C language.
• Heap descriptor HBufC: data exists as part of the descriptor object, and the descriptor object is stored in the heap, just as in the C language (char *) malloc (length + 1) the same is usually used when the length cannot be determined in advance. Because it is allocated on the stack, it is always used through HBufC * instead of directly defining HBufC objects.
• Pointer descriptor TPtr and TPtrC: the descriptor object is stored separately from the actual data it represents, and the descriptor object is stored in the stack, just as the meaning of "pointer, the data pointed to by the pointer descriptor can be the data in the stack or in the heap. TPtrC and TPtr are a bit similar to char * in C, but because the descriptor itself contains length information, you do not need to scan the ending null character ('\ 0') or allocate space for it.

2. modifiable descriptors and unmodifiable descriptors:
As you can see, in the descriptor class, some classes end with "C". These classes represent "Read-Only Descriptors", that is, the data or data pointed to when the descriptor is defined, the descriptor does not provide modification methods. Therefore, the following methods are recommended to declare modifiable descriptors and unmodifiable descriptors:

1 2	const TDesC& str; TDesC& str;

As shown in figure 1, the base class TDesC does not provide a function for content modification, while the class TDes inherited from TDesC provides a function for content modification.

3. descriptor width
All these descriptors can specify data scales: TDes8, TDes16, TDesC8, TDesC16, TBuf8, and TBuf16.
Here, 8 indicates that the descriptor processes 8 bits, and 16 indicates 16 bits. Generally, you only need to use the general form (TDes, TDesC ,...) To Represent Text data, and use 8bit (TDesC8, etc.) to represent binary content.

Iii. Use of descriptors
1. Use macro _ extract (_ LIT16, _ LIT8) and _ L to define string constants.
_ L () can generate an address (TPtrC) pointing to the character value, which is often used to pass the string to the function:

1	NEikonEnvironment::MessageBox(_L(“Error: init file not found!”));

_ Constant () can generate a constant name for future reuse:

1	_LIT(KMyFile, “c:\System\Apps\MyApp\MyFile.jpg”);

The result of the _ separator () macro (that is, the above KMyFile) is actually a literal descriptor TLitC, which can be used in any place where TDesC & is used.

2. system defined Descriptor
KNullDesC (KNullDesC16, KNullDesC8)

1	_LIT16(KNullDesC, "");

It indicates a 16-bit (8-bit) format descriptor with null or no text.

3. Construct Descriptor

• TBufC (unmodifiable stack descriptor)

  1 2 3 4 5 6 7

  _LIT(KHelloWorld, "Hello World"); const TInt maxBuf = 32; TBufC<maxbuf> buf; TInt currentLen = buf.Length(); // == 0 buf = KHelloWorld; currentLen = buf.Length(); // == 11 TText ch = buf[2]; // == ''l''

• TBuf (modifiable stack descriptor)

  1 2 3 4 5 6 7 8 9 10 11

  Const TInt bufLen = 6; TUInt8 objType = 1; TUInt8 objId = 1; TUInt8 xCoord = 128; TUInt8 yCoord = 192; .... TBuf8 <bufLen> buf; Buf. Append (objType ); Buf. Append (objId ); ... // We can use buf to do some things, such as writing the buf into a file or sending it through a Socket.

• TPtrC (unmodifiable pointer descriptor)

  1 2 3

  const unsigned char KBuffer[] = {0x00, 0x33, 0x66, 0x99, 0xbb, 0xff}; TPtrC8 bufferPtr( KBuffer, sizeof(KBuffer)); iSocket.Write(bufferPtr, iStatus);

• TPtr (modifiable pointer descriptor)

  1 2 3 4 5 6 7

  _LIT(KHelloWorld, "Hello World"); const TInt maxBuf = 32; TBufC<maxBuf> buf; buf = KHelloWorld; TPtr ptr = buf.Des(); ptr[7] = ''a''; ptr[8] = ''l''; ptr[9] = ''e''; ptr[10] = ''s''; CEikonEnv::Static()->InfoMsg(ptr); // "Hello Wales"

• HBufC (heap descriptor)

  1 2 3

  HBufC* heapBuf = HBufC::NewL(KHelloWorld().Length()); *heapBuf = KHelloWorld(); delete heapBuf;

4. Use Descriptor

• Ptr () is used to obtain the pointer in the descriptor data.
• Length () is used to obtain the number of characters in the descriptor data.
• Size () is used to obtain the number of bytes in the descriptor data.
• Cpmpare () or operator = ,! =, <= And> = are used to compare descriptor data.
• OPERATOR [], which can be used to obtain a single character in the descriptor string, just like in c/c ++.
• Append () and Num () have many reloads. For more information, see the SDK.
• Compare () has two variants: CompareC () and CompareF (), and Copy (), Find (), Locate () and Match (), these functions all have extensions of C/F, C stands for Collated, and F stands for Folded. Folding is a simple method for comparing and formatting text. It is mainly used when comparison is not too accurate. Collation is a better and more effective way to compare strings. It can generate a sequence similar to a dictionary.

Iv. References:
1. String and Descriptors in Symbian, source: http://blog.csdn.net/sworder_001/archive/2006/09/27/1297069.aspx
2. descriptor analysis, source: http://blog.csdn.net/btooth/archive/2006/07/05/879584.aspx
3. Symbian Basic specification: descriptor, source: http://gardenlee.blogchina.com/gardenlee/3285302.html
4. Nokia official training (Symbian4300) Notes (6)-Descriptors, source: http://embed.e800.com.cn/articles/2007/427/1177655438529691221_1.html