Descriptors – a nightmare?

As far as  I had the chance to google and to browse through some Symbian developer communities and forums, the answer to this question is likely to be positive for a Symbian junior programmer.

Well … what is in my mind when writing about descriptors? Am I a masochist?
I’m trying not to be and also I’m trying to improve  my Symbian expertise. Why? Does it worth spending the time learning about one of the most complicated operating system ever built? It’s quite difficult to answer but for sure this will not make the subject of this post.

What about descriptors … ?

I think one must regards those descriptors like some predefined data types somehow replacing char type from C, due to its inconsistencies we’ve just discussed.

Descriptors can be classified in six categories: whether they are modifiable or not, whether they are pointers or buffers, whether they are heap or stack based.

How can you differentiate them when writing Symbian C++ code?

Basically you can use just the following types: TPtr (pointers), TBuf (stack based), HBuf (heap based), if one of those type has a trailing C, TPtrC, TBufC or HBuf, this is meaning that they are constant. Below is presented the descriptors’ class hierarchy:

In my opinion a very big leap ahead in understanding descriptors is to have an in-depth knowledge of this scheme above.

I will just outline some basic characteristics of TDesC, TDes, TPtr and TPtrC in this post, leaving the discussion about rest of classes for other posts.

TDesC class is the root node of the entire inheritance tree. All constant descriptors, those that I’ve just pointed, TPtrC, TBufC, HBufC, are inherited from it. There are two important methods in this class: the one serving for calculating the size of descriptor – Length() – and for accessing them – Ptr(). One important thing to add here: do not confuse Size() with Length(). Former returns the number of bytes the descriptor occupies, the latter returns the number of characters the descriptor contains. For 8-bit descriptors, where each character occupies a byte, this is the same thing. However, on all releases of Symbian OS since v5u, the native character width has been 16 bits; that is, each character occupies two bytes.

Modifiable descriptors which derive from TDes class, a child class for TDesC, has an additional member called MaxLength, which specifies how big the non-constant descriptor may be, and also multiple methods handling data manipulation (like Append(), Capitalize()..).

It is also important to mention that basically any instance of a non-constant descriptor (TPtr, TBuf) is 4 bytes bigger than its constant counterpart, because of this space overhead introduced by MaxLength, but we’ll talk about descriptors memory layout soon.

Both classes, TDes and TDesC can be found in the following installation path of S60 SDK C:\Symbian\9.2\S60_3rd_FP1\Epoc32\include\e32des16.h (in my case, I am using S60 3’rd edition Feature Pack 1) but also a very documented reference is

Attention! TDes and TDesC classes cannot be instantiated, you cannot create a descriptor of TDesC type (there are some exceptions, in the way that you can pass a reference to those classes as parameters, but generally you define the descriptors as I already mentioned – TBuf, TPtr …).

Those two generic classes although have implemented the methods for manipulating the strings (… or descriptors, or what ever you would like to call them). It is not the case as you are familiar with C++ style where abstract generic classes contain only pure virtual functions which are implemented deeper in the hierarchy tree, in the derived classes.

If you remember every C++ object whose class has at least a virtual method has associated an additional vptr pointer indicating somewhere in a virtual table called vtable.
This thing introduces a size overhead to each object of that type.

This is not desired in Symbian C++. If looking at the memory layout of a Symbian descriptor, first 32 bits hold descriptor’s length (actually only 28, rest of 4 are used to differentiate between different descriptor types)

Those provide just some interface methods which are overwritten in the derived classes, if you scroll downwards you’ll find the descriptors inheritance class tree, accordingly to their needs.

What about TPtrC and TPtr? Somehow an object of type TPtrC has const char * as a C-equivalent type and TPtr is can be associated to char *.  As you probably remarked from the inheritance tree, all non-modifiable operations defined in TDesC are accessible  to objects of type TPtrC and the same is valid for TPtr which can access methods defined in TDes.

As you may encountered in many Symbian books that descriptors contain the information that they point to, you may wondered what is this meaning?
On one side the big advantage they have over the character type from C, is that they are aware of the size of objects that they indicate. Every C programmer having a minimum knowledge about this language, knows that characters are in some sense – pointers. This is somehow valid for descriptors but with one difference, there are two types of descriptors: those that own the data they indicate (HBufC, TBufC and TBuf ) and those that do not own the data they point (TPtr and TPtrC).

Maybe the picture below better summarizes the words above:

You can remark the space overhead introduced by MaxLength member inherited from TDes and the fact that TPtr and TPtrC are completely agnostic about data that they point. Every rectangle within the descriptor fields is 4 bytes big.

I will stop for the moment here but I owe you some examples with TPtr, TPtrC implementation. I will manage to do this in the next Symbian-related post.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: