The Descriptor Classes
In this section, we look closely at all of the descriptor classes.
There are 12 descriptor classes available for the programmer to use. These are divided into three types: buffer, pointer, and heap. Buffer descriptors contain their data buffers in the descriptor classes themselves; their class names begin with TBuf. Pointer descriptors contain a pointer to a data buffer located outside the descriptor; their names begin with TPtr. Heap descriptors are used for managing descriptors on the heap. Heap descriptor names begin with HBuf or RBuf.
A descriptor can be modifiable or non-modifiable. A C (for constant) is appended to the class names mentioned above to indicate that the descriptor is non-modifiable.
Furthermore, a descriptor buffer can contain 8-bit or 16-bit data. Adding 8 or 16 at the end of the class name indicates this. So, for example, TBufC16 is a 16-bit non-modifiable buffer descriptor.
Listed here are all the descriptor classes that can be instantiated. These classes are directly instantiated without inheritance, and they are defined in e32des8.h and e32des16.h in the <SDK Installation Directory>\epoc\include directory.
• TBuf8<n>: modifiable, 8-bit buffer, n is the buffer size.
• TBuf16<n>: modifiable, 16-bit buffer, n is the buffer size.
• TBufC8<n>: non-modifiable, 8-bit buffer, n is the buffer size.
• TBufC16<n>: non-modifiable, 16-bit buffer, n is the buffer size.
• TPtr8: modifiable, 8-bit pointer descriptor.
• TPtr16: modifiable, 16-bit pointer descriptor.
• TPtrC8: non-modifiable, 8-bit pointer descriptor.
• TPtrC16: non-modifiable, 16-bit pointer descriptor.
• HBufC8: non-modifiable, 8-bit heap descriptor.
• HBufC16: non-modifiable, 16-bit heap descriptor.
• RBuf8: modifiable, 8-bit heap descriptor.
• RBuf16: modifiable, 16-bit heap descriptor.
16-Bit default for Unicode
Most times you will see strings represented with descriptor classes with no data width appended to the class name (e.g., just TBuf). If you leave the data width off the class name, it defaults to a 16-bit descriptor. Actually, the default depends on whether the build is using a 16-bit Unicode character set or not (remember descriptors are used mainly for strings). But since all current Symbian OS platforms use Unicode, then the default is always 16-bit. Examine the include file e32std.h if you are interested in how this default mapping to the descriptor classes is accomplished.
Since 8- and 16-bit descriptors behave identically in almost all respects, I will use the default 16-bit descriptors (by leaving the number off) for simplicity for most of this chapter. Unless stated otherwise, you can assume that the code for 16-bit descriptors applies also to 8-bit descriptors.
Descriptor class hierarchy
Figure 6.2 shows a class diagram of the descriptor classes. As indicated above, the diagram shows 16-bit classes only-there is a separate, but equivalent hierarchy for 8-bit descriptors that start with TDesC8 (just tack an 8 on every class name, and you'll have it).
Post a comment