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.

Descriptors – a milestone in the Symbian C++ learning curve?

I guess many C enthusiast programmers wanting to switch to Symbian code developing, faced some issues when learning about Symbian descriptors. Even if many useful and helpful resources can be found on the Internet, especially those written by Jo Stichbury (personally I would recommend this one a weblog completely dedicated to descriptors, but there are also other ones which can be found on Symbian developer communities or on Nokia forums), some misunderstandings still persist.

Personally I almost do not know anything about descriptors, I have just some scarce knowledge about Symbian in general, but I am struggling to improve.

Let me tell you how I see the things from a beginner perspective.

First of all two things are important to mention just from the beginning: descriptors (which are somehow equivalent of C arrays) are safer than ordinary C arrays and they are heavily used in transferring data, either on binary format or text.

Before going deeper into descriptors’ understanding I think it is required to clarify why is it so unsafe to use null terminated strings, like those implemented in C.

What is a nul (and it is rather more correct to call it NUL instead of NULL, which has more to do with dynamically allocated pointers – NULL could be something like ((void*)0)) terminated character array?

Let’s turn to Wikipedia and see what is there explained.

NewLC()– a new type of constructor in Symbian C++?

I am in the phase of learning Symbian C++ and Symbian OS, so this is the moment in time when I ask myself many questions about how the things are done.

Everywhere you will read a Symbian programming tutorial you will find a topic about the two phase construction. What exactly is this?

As I wrote in one of my previous posts the memory is a scarce resource when talking about mobile software development. You will have to be careful to code your application keeping in mind that memory needs to be handled very accurately. In general, in embedded programming you do not afford, like when doing PC desktop software development, to have any memory leak or a dangling pointer.

What is a memory leak? It is when you destroy a pointer to a memory location which was not freed correspondingly. The memory location is said to be left “orphaned”, there is no pointer to it so it cannot be handled inside the program.

What is a dangling pointer? Is a pointer that is used to indicate some data which was previously released. A common example is when you return a pointer from a function and that pointer indicates a local variable. A common workaround to avoid such dangling pointer bugs is to lock the pointer to NULL value after it released a resource.

Since in Symbian a lot of applications are relying on C classes (classes derived from CBase class), which are instantiating objects only on the heap, dynamically memory allocation will be intensively used.

One rule of thumb in Symbian is that the constructor is not allowed to leave. OK…

What are “leaves” in Symbian programming?

I’ve published several weeks ago an article highlighting the Symbian C++ coding conventions. One of the most important was the suffix: L. When a function is suffixed with L, actually this is informing the run-time machine that this function will generate an exception.

Actually leaves are Symbian equivalent of C++ exceptions. Suffixing a function with an L is like testing it into a try C++ clause.

Typically leaving functions  perform operations that are not guaranteed to succeed. A good example of this would be a memory allocation. Due to the fact that a Symbian equipped smartphone is relying on limited hardware resources, it may often happen that insufficient memory conditions occur. Just remember about the heap overflow discussion that I had in my dynamic memory allocation posts. On top of this you may add the notorious stack overflow issue.

It is very important to suffix a function that you “suspect” to leave because callers of this code may defend themselves against a potentially leak memory. An un-trapped leave may generate a panic, which is an error that results in blocking the entire system, in other words, is an untrapped error.

But how should you know whether or not a function will leave?

Brief guide to Symbian C++

… actually you can find this information on a dozen of other sources, but if you bothered (if this is so I will thank you) to click on my blog, it worth reading it.

Maybe the difference in between what is written here and on some other web resource, is that those things out here are  coming from a Symbian newbie, so …

Symbian developers from all over the world (I am addressing here to the beginners among you)  unissez vous !

Do you already have a C++ background and do you want to start learning about the worlds’ most deployed mobile operating system ? If you happily answer YES to both questions, you may need informations out here.

Many Symbian C++ books assume that you are already familiar with C++ but not that you have an in-depth knowledge of the operating system, actually many of them include some statements like this one:

If you are a developer targeting, or thinking of targeting, Symbian OS, this book will show you how to write the most effective C++. You will benefit from a greater understanding of the characteristic features and design of the operating system, and confidence in how to use them.

the author warns:

We encourage you to follow them too, in order for your own code to be understood most easily by other Symbian OS developers, and because the conventions have been chosen carefully to reflect object cleanup and ownership, and make code more comprehensible. An additional benefit to using the conventions is that your code can then be tested with automatic code analysis tools, which can flag potential bugs or areas to review.

… just taken from Symbian OS explained by Jo Stichbury, a Symbian OS and Symbian C++ golden reference

The general picture being drawn I will procede with Symbian C++ code conventions.

1. Capitalization – each class name must be capitalized, rest of the letters must be in lower-case.

CClass Instance1; //this is OK
CCLASS Instance2; //this is NOT OK