转自http://www.cppblog.com/franksunny/archive/2007/10/19/34622.html
接触 Symbian 已经一个半月多了,自从上个月熟悉了框架之后,一直都不敢再写什么东西了,因为没有经历过代码怎么可能写得出东西呢?起笔犹豫了很久,打算涉足 Symbian 与标准 C++ 的一个不同点——描述符。希望自己能够借这个机会搞清楚描述符这个东西。
一、总介
由于手机系统的资源区别于 PC ,为此为了更好的在内存受限设备上处理内存缓冲, Symbian 提供了独特的描述符,用以存储和操作字符串、以及管理二进制数据和其它串行化的复杂对象( serialized compound objects )。
Symbian OS 的很多 API 调用的参数都是描述符,同时 Symbian 也为描述符提供了很多的操作函数。但是描述符本身其实就是一个封装了数据及其长度的内存块类。作为字符串处理类,它与标准 C++ 的以 '/0' 结束符的字符串有区别,即它没有结束符;描述符在处理字符串和二进制数据时又有不同:首先 Symbian 使用 Unicode ,所以字符串通常存于 16 位描述符中,而二进制数据存储于 8 位描述符中(通常在底层通信中用的都是 8 位的描述符);其次如果描述符中包括二进制数据,则描述符的字符串操作方法不可用(我的理解是可以用,但是不能当字符串来用,所以也就没有意义了。至于处理串行化对象,本人没有接触所以暂时略过)。
二、描述符类型分类及其相互关系
描述符主要有四类,但是我们通常将文字常量也作为描述符的一类,所以就有了五类,以下就是常见分类:
· 抽象类(Abstract ):(TDes 、TDesC 、Tdes8 、TdesC8 ),其他描述符的基类,仅提供接口和基本功能,不能被实例化,一般只用作函数的参数。
· 文字常量(Literal ):(TlitC 、_LIT() ),用于存储文字字符串(literal string ),即C 中字符串常量,通常使用_LIT() 这种方式(当然还有_L() 和_L8() 的描述方式,但都不提倡用)。
· 栈类(Buffer ):(Tbuf 、TbufC 、 Tbuf8 、TbufC8 ),数据存储于栈上,最基本的描述符变量类型,大小在编译时确定,包含描述符本身数据,使用最为普遍。
· 堆类(Heap ):(HbufC 、HbufC8 ),数据存储于堆上,大小在运行时确定,也就是是用来处理动态申请的描述符类。在C/C++ 中用过动态内存的都知道,动态内存是啥回事,这里堆类描述符用的时候,也是差不多,由于堆描述符没有构造函数,所以只能声明为指针类型,通过堆描述符类内静态函数NewL 方法申请内存,具体方法如下
HBufC* errorTitleCode = HBufC::NewLC(50);
HbufC* unUseCode = NULL;
· 指针类(Pointer ):(TPtr 、TPtrC 、TPtr8 、TPtrC8 ),本身不包含描述符数据,但是包含长度数据,而且还包含一个指向位于描述符之外数据的指针。
从以上分类可知,描述符有 8 位和 16 位宽度的区别,还有可修改和不可修改的区别,具体的区别我从内存的角度出发列表如下:
具体类型 | 类型(4b ) | 当前长度(28b ) | 最大长度( 32b ) | Buffer |
TDesC8 |
| Yes | 无 | 无 |
TDesC |
| Yes | 无 | 无 |
TDes8 |
| Yes | Yes | 无 |
TDes |
| Yes | Yes | 无 |
TBufC8 | 0 | Yes | 无 | ByteBuffer |
TBufC | 0 | Yes | 无 | WordBuffer |
TBuf8 | 3 | Yes | Yes | ByteBuffer |
TBuf | 3 | Yes | Yes | WordBuffer |
TPtrC8 | 1 | Yes | 无 | 32 位指针 |
TPtrC | 1 | Yes | 无 | 32 位指针 |
TPtr8 | 2 | Yes | Yes | 32 位指针 |
TPtr | 2 | Yes | Yes | 32 位指针 |
HBufC8 | 0 | Yes | 无 | ByteBuffer |
HBufC | 0 | Yes | 无 | WordBuffer |
注:
1、 表中空出的内容,我暂时还不知道具体的值是多少。其中的 b 是 bit 的意思;
2、 在实际操作中,定义的描述符长度和内存实际使用长度会有不一致问题,原因是描述符也是按4字节进行边界对齐的 。
由如表所示的内存关系可能显得有点乱,如果能将每个类用 UML 类图(包括详尽的成员变量和成员函数,类的头文件在 e32des16.h 和 e32des8.h 中)来表示就更直观了,在 Symbian 官方网站有一张类简图,我先将此作为继承关系的简图在这里作为演示用
三、描述符的使用
介绍到这里应该具体讲每一个描述类的使用了,我发现有两篇中文文档整理的很好,在这里,我只做一些验证性的介绍,读者可以参阅我在文章后列出的两篇文档。由于要略过不能实例化的抽象类,且按照从简单到复杂的过程来叙述:
1、 文字描述符常量
a 、 _LIT() 可以生成个常量名,以便以后重复使用,例如
_LIT(KMyFile, "c:/System/Apps/MyApp/MyFile.jpg");
_LIT() 宏的结果(就是上面的 KMyFile )实际上是个文字描述符( literal descriptor ) TLitC ,它可以在任何使用 TDesC& 的地方使用。(但是 TlitC 已经不推荐使用了)。
b 、 _L() 可以生成一个指向字符值的地址( TPtrC ),它经常被用来传递字符串到函数中(包括描述符的构造函数和格式化函数);同理 _L8() 则可以生成一个指向二进制数据的地址( TPtrC8 )举例如下:
// 常用的通知函数
NEikonEnvironment::MessageBox(_L("Error: init file not found!"));
// 数字转字符串
TBuf16<20> buf;//
TInt iNum = 20;
buf.Format( _L( "%d" ) , iNum );
2、 栈描述符
栈类描述符声明时必须指定描述符的最大长度,否则无法声明和定义,下面举例
例 1 :构造
// 直接从字符串中构造
_LIT(Ktext, "TestText");
TBufC<10> Buf (Ktext);
// 或从字符串赋值
TBufC<10> Buf2;
Buf2 = Ktext;
// 从已有的对象中生成新的 TBufC
TBufC<10> Buf3(Buf2);
TBufC<n> 一般用来存储文本数据,而 TBufC8<n> 则用来存储二进制数据。尽管这里的对象表示数据是不能被修改的(因为有个后缀 C 代表了常量的意思),但仍然有两种方式可以用来修改数据内容:这里的数据可以用赋值的方式替换掉;使用 Des() 函数构造出一个 TPtr 对象,这样就可以用它来修改数据。
例 2 :修改数据
_LIT(Ktext , "Test Text");
_LIT(Ktext1 , "Test1 Text");
_LIT(KXtraText , "New:");
_LIT(NewText , "New1");
_LIT(NewText1 , "New2");
TBufC<10> Buf1 ( Ktext );//Buf1 长度为 9 内容 “ Test Text ”
TBufC<10> Buf2 ( Ktext1 );//Buf2 长度为 10 内容 “ Test1 Text ”
// 通过赋值的方式改变数据
Buf2 = Buf1; //Buf2 长度变为 9 内容 “ Test Text ”
// 通过使用 Des() 生成指针改变 TBufC 的数据
TPtr Pointer = Buf1.Des();
// 删除后四个字符
Pointer.Delete(Pointer.Length()-4, 4 ); //Buf1 长度变为 5 内容“ Test ”
// 但是内存应该没变
// 增加新的数据
Pointer.Append(KXtraText);//Buf1 长度为 9 内容为“ Test New :”
// 也可以使用下列方式改变数据
TBufC<10> Buf3(NewText);
Pointer.Copy(Buf3);//Buf1 长度为 4 ,内容为 New1
// 或直接从字符串里获得数据
Pointer.Copy(NewText1);//Buf1 长度为 4 ,内容为 New2
以上介绍的是不可修改的栈描述符,而可修改的描述符就不用通过那么复杂的方法来实现修改,它直接可以用 Copy 、 Delete 等 方法,但是无论可修改的还是不可修改的,一旦指定最大的数据长度后,最大长度就不能进行修改了。修改的只是数据内容,而数据内容修改的受限条件是不能超过 声明或定义时的最大长度。(个人以为从内存角度来说,不可修改类型的缺少最大长度,所以严格上来说为了减少错误,修改数据内容是不允许的)
3、 堆描述符
堆描述符虽然都是不可修改类型的,但是它仍然具有构造和修改,与栈描述符不同的是:首先对内存需要显示释放,其次是堆描述符没有最大长度的限制,任何时候都可以用 ReAlloc ()函数重新申请分配。具体见示例:
// 例 1 、构造
// 有两种方式来生成一个 Heap Descriptor
// 第一种方式用 New(),NewL(), 或 NewLC()
// 如下操作便可以构建一个存放数据的空间,空间为 15 ,不过目前大小为 0
HBufC * Buf = HBufC::NewL(15);
// 第二种方式是采用 Alloc() , AllocL() 或 AllcLC() 来处理,
// 不过这是已经存在的数据的管理方式。新的 Heap Descriptor
// 可以自动的根据这个内容来构造。
_LIT (KText , "Test Text");
TBufC<10> CBuf = KText;
HBufC * Buf1 = CBuf.AllocL();
CleanupStack::PushL(Buf1);
// 例 2 、修改
// 下面是通过赋值方式改变其数据的方法
_LIT ( KText1 , "Text1");
*Buf1 = KText1;
// 通过可修改指针来改变数据的方式
TPtr Pointer = Buf1->Des();
// 添加数据
Pointer.Delete(Pointer.Length() - 2, 2);
// 删除数据
_LIT ( KNew, "New:");
Pointer.Append(KNew);
// 例 3 、重新申请内存
Buf1 = Buf1->ReAllocL(KText().Length() + KNew().Length());
CleanupStack::PushL(Buf1);
// 例 4 、释放内存
// 直接用 delete
delete Buf;
Buf = NULL;
// 如果在使用 NewL 、 ReAllocL 等异常函数后我们使用清除栈压入的话
// 那么我们也可以用清除栈来释放内存
CleanupStack::PopAndDestroy();
Buf1 = NULL;
注:关于以上用清除栈的方式,个人只是猜测,因为对 Symbian 的异常处理三部曲,至今仍没有很好的掌握,所以如果有什么误用还望指点。
4、 指针描述符
其实关于指针描述符,我们在上面已经用过可修改的指针 TPtr 了,下面返璞归真,从 TPtrC 的构造开始介绍使用
// 例 1 、用 TBuf 和 TBufC 构造出 TPtrC 对象
_LIT(KText , "Test Code");
TBufC<10> Buf ( KText );
// 或者为 TBuf<10> Buf ( KText );
// Creation of TPtrC using Constructor
TPtrC Ptr (Buf);
// Creation of TPtrC using Member Function
TPtrC Ptr1;
Ptr1.Set(Buf);
// 例 2 、用 TText* 构造 TPtrC
const TText* text = _S("Hello World/n");
TPtrC ptr(text);
// 或者
TPtrC Ptr2;
Ptr2.Set(text);
// 如果要存储 TText 的一部分数据,我们使用下列方法
TPtrC ptr4(text, 5);
// 例 3 、从另一个 TPtrC 中构造 TPtrC
const TText * text1 = _S("Hello World/n");
TPtrC Ptr3(text1);
// 从一个 TPtrC 中获得另一个 TPtrC
TPtrC p1(Ptr3);
// 或
TPtrC p2;
p2.Set(Ptr3);
以上是不可修改的 TPtrC 的构造,相对应的也有可修改的 TPtr 的构造,不过我们下面省略了用 Set() 函数的构造方法
// 例 1 、通过 TBufC,HBufC 的 Des() 方法获取
_LIT(KText, "Test Data");
TBufC<10> NBuf ( KText );
TPtr Pointer = NBuf.Des();
// 例 2 、通过指定内存区域和大小来生成
const TText * Text = _S("Test Second");
TPtr Pointer1((TText*)Text, 11, 12);
// 例 3 、 通过另一个 TPtr 对象来生成
TPtr Pointer2 ( Pointer );
对于可修改的 TPtr 虽然前面用过,但是我们在这里在简单的添加两个例子加深下印象,并且说明指针修改的始终是它指向的描述符:
// 例 1 、改变已有 TPtr 数据的方式:赋值和 Copy() 方法
_LIT(KText, "Test Data");
_LIT(K1, "Text1");
_LIT(K2, "Text2");
TBufC<10> NBuf ( KText );//NBuf 内容为“ Test Data ”
TPtr Pointer = NBuf.Des(); //Pointer 指向 NBuf 的内容
Pointer = K1; // NBuf 内容为“ Text1”
Pointer.Copy(K2); // NBuf 内容为“ Text2”
// 例 2 、直接通过修改长度改变数据内容
Pointer.SetLength(2); // NBuf 内容为 "Te" 注:实际内存的内容应该没变
5、 抽象描述符
抽象描述符,没有什么好说的,正如前面所说,只用在函数的形参中,通常要强调参数是不可修改的,就用 const TDesC& 表示,可修改的参数用 TDesC& 表示。
四、常用 API 函数罗列
下面再对描述符的几个常用修改和不可修改 API 函数加以罗列
不可修改型:
// 获取属性类
Length() ,Size()
// 查找、比较类
Compare() ,Locate() ,LocateReverse () ,Find() ,Match()
// 取描述符子串指针类
Left() ,Right() ,Mid()
可修改型:
// 增加、插入、删除类
Insert() ,Delete() ,Append() ,Replace() , Trim()
// 赋值类
Zero() ,Copy() ,Num() ,Format()
本文涉及的两篇文档
Nokia 官方培训(Symbian4300) 笔记( 六)—Descriptors (该文链接google 里面找)
中文 Descriptors 的使用
http://wiki.forum.nokia.com/index.php/%E4%B8%AD%E6%96%87_Descriptors%E7%9A%84%E4%BD%BF%E7%94%A8#TPtr.E7.9A.84.E4.BD.BF.E7.94.A8
后 记:本想把涉及描述符的转换也整理在一篇文章中的,但是后来发现整理完概念和使用已经消耗了我一天多时间了,晚上部门要去喝茶,为此暂时到这里,明天周末 在整理转换问题。由衷感谢单位给我那么多时间在工作中学习,想想以前第一份工作时,在单位看书都要被老板说的历史,发觉自己现在真的蛮幸运的。