Chapter 1

There is another version of Write() here, which takes a length that is used to override the
length in the descriptor. This is a simple convenience function. If it had not been provided in
the API, and you wanted it, then instead of using file.Write(buffer,length), you
could use file.Write(buffer.Left(length)). Left() returns a TPtrC with the
same address as its argument, but with its length shortened to the number of characters (or
bytes) required.
Likewise, the Read() functions take a descriptor in which the data to be read will be put.
These parameters are specified as TDes& types. Read()-like functions coded like this use
one of three conventions:
� They fill the destination buffer to its MaxLength().
� They fill the destination buffer with a fixed amount of data, but truncate if that would
exceed MaxLength().
� They fill the destination buffer with a fixed amount of data, but panic if the buffer isn't
big enough.
RFile usually fills the entire buffer – except when reading has reached the end of the file.
Many servers and device drivers follow the third convention and expect the buffer to be big
enough.
Communications protocols at the stream level behave like an RFile. Communications
protocols at the packet level behave like a server or an I/O device.
In Chapter 16 and those that follow, we'll learn a lot more about binary descriptors, as we get
to grips with packet-based communications and servers for the Battleships game.
5.7 Summary
In this chapter, I've introduced you to the way Symbian OS handles strings and other data,
using descriptors. The main advantages of descriptors are
� descriptors can handle both string and binary data
� they provide a uniform API for dealing with data, whether it is part of a program binary,
on the stack, or on the default heap
� they prevent buffer overflow errors, but otherwise don't hide memory management
issues – preserving the balance between safety and efficiency that underlies Symbian
OS
� descriptors encapsulate the address and length of data
� 8-bit versions of descriptor classes allow binary data to be handled.
In terms of the classes we've seen
� for immutable strings and data, classes ending with C provide constfunctions, derived
from TDesC
� when modifying strings or data, use classes derived from TDes, with its nonconst
functions
� the _LIT and _L macros, the difference between them and why _LIT is preferred.