Help! Descriptors!!

Probably the number one question on the mind of any new Symbian OS developer (and some seasoned ones too!) is descriptors, why, how, where, which one… the list continues. So here’s list of definitive resources on descriptors on the way, which IMO should answer all your questions. Finally, there’s my rules of thumb on using descriptors, which you can find at the end of the article.

  • Descriptors: Excellent presentation from Symbian on descriptors, with detailed discussion on the internal structure of descriptors, their place in C++ code and most importantly, which ones to use in which circumstances.
  • Descriptors FAQ: Excellent FAQ on descriptors maintained by Jo Stichbury that complements the presentation above really well.

And now for the impatient! Basic rules of thumb on descriptor usage. Remember these are just rules of thumb and not a definitive guide.

  • I need a temporary (stack based) string and I know the possible max length, like printing out a message. What should I use? Use a TBuf.
  • I need to have a class member, e.g. contact name, whose max size is known before hand. Use a TBuf.
  • Same situation as before, but I have many string member variables.
    Use a TBufC in that case. TBufC is a bit more (4 bytes) RAM efficient than TBuf. However, remember, you can’t directly manipulate a TBufC and need to call Des (expensive?) on it to get a modifiable pointer, or simply use the assignment operator to replace the whole content of the TBufC.
  • I need a dynamically allocated string on the fly or as a member variable (max length not anticipated). Use RBuf.

That’s it, not much to it, is there? The keen reader will notice that I have failed to mention a particular class whose name begins with H. Well, I say its time to bury it behind RBuf, once and for all.

Happy coding!

6 thoughts on “Help! Descriptors!!

  1. Why are HBufC and TBufC called C for constant and referred to as unmodifiable descriptors if you can change both of them via Des()?

  2. The reason being, you can’t directly modify them. Calling Des is an indirect method. I guess the naming convention is a bit confusing. Hence, its always a safer bet to explicitly use the C++ language constructs to guard against such things, e.g. *if* you really want a const TBufC (in which case you are better off using _LIT…), mark it as a const TBufC.

  3. Hi,
    Really nice example and tutorial as well about buffers . Is there is a tutorial by you on symbian programming using c++?

    – how to convert string to number and vice versa.
    – how to manupulate strings, (compare, find, substring etc)
    – how to deal graphics,(data types avaibale and their coutner part in c++ , compartively)
    -and of course, general introduction by you on Symbian OS.


  4. So if you declare a TBufC or a HBufC and you try to modify it you will get a compiler warning, so you may be attempting to use it in a way you originally didn’t intend (because you declared it const)?

    However, how many people use HBufCs as a genuine ‘const’ string often?

  5. Hi Albert,

    The only time you’d use a HBufC is when you need a dynamically allocated string. This means, either you don’t know beforehand the length of the string you require, or you need a large string that may not be safe to declare on the stack. Hence the use case of a HBufC being used as a proper “const” type is missing. Its always better to use language constructs, e.g. const to guard against programming errors 🙂

  6. I’ve read the document on the Symbian website about using RBufs, however all the examples in it don’t involve any interaction with functions.

    There’s an example of where an RBuf is being assigned into by a function that returns a HBufC*, however if RBufs are supposed to be preferable to HBufCs now then how would/should you write a function that previously would have returned a HBufC* but not would be preferrable to return an RBuf?

    Are there any instances when an RBuf should be used as an out parameter to a function?

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 )

Google photo

You are commenting using your Google 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 )

Connecting to %s