Descriptors for function interfaces

Many interfaces which use or manipulate text strings or general binary data use descriptors to specify the interface. In conventional ‘C’ programming, interfaces are specified using a combination of char*, void* and length values. In Symbian OS, 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 OS: 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 OS: 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 OS: 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 OS: 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.