Descriptors for function interfaces

下面的内容摘自Symbian S60 3rd Edition SDK，先把英文原版贴在这里，等时间充足的时候我再把它翻译出来。How to Use Descriptors之Descriptors for function interfaces《函数接口中描述符的使用》

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.