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.