Wednesday, May 04, 2005
1. The Basics
What are descriptors?
Descriptors are Symbian OS strings.
So why are they called 'descriptors' rather than strings?
They're known as 'descriptors', because they are self describing. Each descriptor object holds the length of the string of data it represents as well as its 'type', which identifies the underlying memory layout of the data it holds.
So they can be used to store text?
They can. They can also be used to store binary data.
Do they store text data as ASCII or Unicode?
Either. There are two types, 8-bit and 16-bit descriptors. The 8-bit variant is used to store ASCII characters and raw binary data. The smallest data unit in these is a “narrow” 8 bit (1 byte) character. The 16-bit type is used to store Unicode characters; for these, the data unit is a “wide” 16-bit (2 byte) character.
How do I know which I have got?
Each type ends in 8 or 16, for example TDesC8 or TDesC16.
What about descriptors without 8 or 16 at the end, such as TDesC?
These are said to be of ‘neutral’ width because they are built with the platform default character size. In the old days, Symbian OS (or EPOC32 as it was known then) used 8-bit ASCII text, so a neutral descriptor defaulted to the 8-bit variety. Since Symbian OS v5U (also known as ER5U) Symbian OS has used wide strings.
Thus, unless you're working with a pre-v5U SDK, the neutral descriptors (TBufC, TPtr, HBufC etc) are implicitly 16-bit and are actually TBufC16, TPtr16, HBufC16 etc.
How do I find out the character width of my platform?
As described above - unless you’re working with a version of the OS which pre-dates Symbian OS v5U (used in the Ericsson R380 mobile phone in the year 2000) you’ll be working with the wide, 16-bit platform.
So which width should I use?
If you need to use 8-bit data, for example, to call a particular API method (such as the Read() or Write() functions of RFile), for Internet email, or to manipulate ASCII data, you should use the explicitly 8-bit descriptors.
If you want to store a chunk of binary data, use the 8 bit variety too.
If you need to work with 16-bit text, for example, Java strings, and want to indicate this explicitly, use the 16-bit descriptors.
But, in general, unless you need to make the data width explicit, use the neutral descriptors. If nothing else, your code is more readable and it may even be portable if the default character width changes on a later platform.
Are they NULL-terminated like C strings?
No.
How come?
Because they're self-describing, descriptors know the length of their internal data. This means there’s no need for the data to be NULL-terminated to mark where the data ends. It also means that binary data can be stored in the same descriptor classes as store text data. This isn’t possible with C strings because there’s no way of distinguishing the NULL terminating character from valid binary data.
Are they hard to use?
Not really. They’re easy to use badly but in fact there are only a few rules, and a few gotchas. They just haven’t been fully explained: until now...
You can find an overview of descriptors in the Symbian Developer Library which accompanies each Software Development Kit (e.g. for UIQ or S60 phones). It is also available online as described in the references section (References to other descriptors resources).
The descriptors overview can be found in [reference 1].
Descriptors are Symbian OS strings.
So why are they called 'descriptors' rather than strings?
They're known as 'descriptors', because they are self describing. Each descriptor object holds the length of the string of data it represents as well as its 'type', which identifies the underlying memory layout of the data it holds.
So they can be used to store text?
They can. They can also be used to store binary data.
Do they store text data as ASCII or Unicode?
Either. There are two types, 8-bit and 16-bit descriptors. The 8-bit variant is used to store ASCII characters and raw binary data. The smallest data unit in these is a “narrow” 8 bit (1 byte) character. The 16-bit type is used to store Unicode characters; for these, the data unit is a “wide” 16-bit (2 byte) character.
How do I know which I have got?
Each type ends in 8 or 16, for example TDesC8 or TDesC16.
What about descriptors without 8 or 16 at the end, such as TDesC?
These are said to be of ‘neutral’ width because they are built with the platform default character size. In the old days, Symbian OS (or EPOC32 as it was known then) used 8-bit ASCII text, so a neutral descriptor defaulted to the 8-bit variety. Since Symbian OS v5U (also known as ER5U) Symbian OS has used wide strings.
Thus, unless you're working with a pre-v5U SDK, the neutral descriptors (TBufC, TPtr, HBufC etc) are implicitly 16-bit and are actually TBufC16, TPtr16, HBufC16 etc.
How do I find out the character width of my platform?
As described above - unless you’re working with a version of the OS which pre-dates Symbian OS v5U (used in the Ericsson R380 mobile phone in the year 2000) you’ll be working with the wide, 16-bit platform.
So which width should I use?
If you need to use 8-bit data, for example, to call a particular API method (such as the Read() or Write() functions of RFile), for Internet email, or to manipulate ASCII data, you should use the explicitly 8-bit descriptors.
If you want to store a chunk of binary data, use the 8 bit variety too.
If you need to work with 16-bit text, for example, Java strings, and want to indicate this explicitly, use the 16-bit descriptors.
But, in general, unless you need to make the data width explicit, use the neutral descriptors. If nothing else, your code is more readable and it may even be portable if the default character width changes on a later platform.
Are they NULL-terminated like C strings?
No.
How come?
Because they're self-describing, descriptors know the length of their internal data. This means there’s no need for the data to be NULL-terminated to mark where the data ends. It also means that binary data can be stored in the same descriptor classes as store text data. This isn’t possible with C strings because there’s no way of distinguishing the NULL terminating character from valid binary data.
Are they hard to use?
Not really. They’re easy to use badly but in fact there are only a few rules, and a few gotchas. They just haven’t been fully explained: until now...
You can find an overview of descriptors in the Symbian Developer Library which accompanies each Software Development Kit (e.g. for UIQ or S60 phones). It is also available online as described in the references section (References to other descriptors resources).
The descriptors overview can be found in [reference 1].
Comments:
<< Home
Apart from the underlying character size, the behavior of the 8- and 16-bit descriptor classes is identical, except for Copy() and Size(). These differ, necessarily, because of the size of the characters being manipulated.
I could not find a relevant post to piggyback on so here goes my question:
Are formatting operations on descriptors thread-safe? Consider sample like this:
void do_log(const TDes8 & format,...)
{
VA_LIST aList;
VA_START(aList, format);
TBuf8<100> msg;
msg.AppendFormatList(format aList);
VA_END(aList);
}
If the above code is being executed by multiple threads simultaneously. Does symbian implementation guarantee correct behavior or the formatting op must be synchonized?
Post a Comment
Are formatting operations on descriptors thread-safe? Consider sample like this:
void do_log(const TDes8 & format,...)
{
VA_LIST aList;
VA_START(aList, format);
TBuf8<100> msg;
msg.AppendFormatList(format aList);
VA_END(aList);
}
If the above code is being executed by multiple threads simultaneously. Does symbian implementation guarantee correct behavior or the formatting op must be synchonized?
<< Home
