Descriptors for function interfaces

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.