Descriptors to specify interfaces which use or manipulate text strings or general binary data use
In conventional ‘C’ programming, interfaces are specified using a combination
of char*, void* and length values. In Symbian
platform, descriptors are always used.
There are four main cases:
Passing a constant string
In
‘C’: StringRead(const char* aString);
The length of the string is implied by the zero terminator; therefore, the function does not require the length to be explicitly specified.
In Symbian
platform: StringRead(const TDesC& aString);
The descriptor can access the string and contains its length.
Passing a string which can be changed.
In ‘C’: StringWrite(char* aString, int
aMaxLength);
The length of the passed string is
implied by the zero terminator. aMaxLength indicates the
maximum length to which the string may be extended.
In Symbian platform: StringWrite(TDes&
aString);
The descriptor can access the string and contains its length and the maximum length to which the string may be extended.
Passing a buffer containing general binary data
In ‘C’: BufferRead(const void* aBuffer,
int aLength);
Both the address and length of the buffer must be specified.
In Symbian platform: BufferRead(const
TDes8& aBuffer);
The descriptor has access to the address of the buffer and contains the length of the data. The 8 bit variant is explicitly specified; the buffer is treated as byte data, regardless of the build variant.
Passing a buffer containing general binary data which can be changed.
In ‘C’:BufferWrite(void*
aBuffer, int& aLength, int aMaxLength);
The
address of the buffer, the current length of the data and the maximum length
of the buffer are specified. The aLength parameter is specified
as a reference to allow the function to indicate the length of the data on
return.
In Symbian platform: BufferRead(TDes8& aBuffer);
The descriptor has access to the adddress of the buffer and contains the length of the data and the maximum length. The 8 bit variant is explicitly specified; the buffer is treated as byte data, regardless of the build variant.
Defining interfaces using the base descriptor classes allows callers to pass all appropriate derived descriptor types.