小弟穇的sdk

[hanming]

小弟边看SDK，边穇的东西，有些地方不是很准确，还请高手指点一下，小弟会立即修改。谢谢先。

四．内存管理
1． 内存管理总览
(1) 目的
讨论程序运行时分配的内存与程序运行所要的内存。内存，做为EPOC程序的基石，做为一块有限的资源，必须被小心使用，尤其是在出现异常的情况下，因此，在CleanUp Support API中，异常处理与内存管理紧密的连系在一起。
(2) 体系结构
UiKon Core framework用这些API为每个GUI程序提供良好的内存管理的基本体系结构。每个GUI程序都在异常出现的时候都支持Clean up Memory,且在调试时能够检测内存泄漏。
2． Cleanup 支持概述
(1) 目的
提供处理程序异常和当异常发生时清除内存的方法
(3) 体系结构
EPOC的Cleanup策略与普通类(尤其是CBase的派生类)紧密联系在一起，
(4) Description
这些API分为三个重点部分：异常处理(Exception handling)，清除栈(cleanup satck)和(general cleanup item)
l 异常处理(Exception Handling)
a． EPOC并不使用标准C++的异常处理，(try, catch, throw),而是使用自己惯用的方法，一个异常被称为Leave
b． 捕获器(trap harness)在程序中定义了一个当异常发生时会立即跳转去的点。程序员可以用TRAP 或TRAPD这两个宏来设置捕获器。
c． 通过调用系统静态功能API的User类的函数(User：：Leave())时会触发Leave.许多系统函数与用户代码都有可能触发Leave.
l 清除栈(Cleanup Stack)
a． 异常发生时，任何在堆上分配的内存，如通过New()创建的对象，其指针就会被遗弃在内存中，造成内存泄漏。要防止这种内存泄漏，就需要程序能记录这些对象，一旦发生泄漏，系统就能自动找到这些对象并清除它们。即所谓的清除栈。
b． GUI程序的Application Frameword提供了清除栈，而其它的应用程序就要显示的用CTrapCleanup去显示的建立清除栈。
l General Cleanup Item
a． 通常Cleanup Stack 只处理CBase的派生类和无类型的对象(TANY*) ，General Cleanup Item允许将其它类对象压入Cleanup Stack，然后让调用者调用指定的函数去完成清除工作。其接口定义在TCleanupItme;
3． 内存分配总览
其分为两个重要的部分：Chunk,Heap
Chunk:
(1) Chunk是被映射到线性连续地址上的RAM区域，当一个进程运行时，地址空间被分成1至3个Chunk.
(2) Stack/Heap Chunk：被进程的主线程使用的堆和栈。其綺常存在
(3) Code Chunk：只有进程被装入到RAM中，才存在。
(4) Data Chunk： 只有里程拥有静态数据时才存在。
(5) 程序允许附加其它的Chunk，Global Chunk能被其它的进程访问，所以允许大量的内存共享。 其接口定义在RChunk
(6) TFindChunk 用于查找其它进程建立的Chunk.
Heap:
(1) 堆用于显示的动态分配内存，EPOC定义C++的new操作符在当前的线程堆栈中创建对象。
(2) 堆可以监控内存泄漏，在一个进程中的各个线程之间共享，在CELL LEVEL下存取与操作。


五．使用Cleanup
1．异常处理
a) 错误类型与恢复
错误条件可以分为以下三类
(1) 程序错误，如数组访问超界，可以用_ASSERT_DEBUG宏来检查，一般解决的方法是重写代码。
(2) 环境错误，如内存不足，磁盘空间不足，检查方法有两种，一是如错误出现在一个操作之后，就可以检查返回码是不是KErrNone,另外一种是使用异常处理和清除技术。
(3) 用户错误，如源代码中的语法错误，在对话框中输入错误的数据。
b) C++异常处理
EPOC有其自己的异常处理机制，注意在使用C++异常处理的同时，Cleanup与两段构造同样需要。
c) 基本异常处理支持
操作系统支持如下基本的异常处理
TRAP宏与其变量，允许代码运行在捕获器下的TRAPD宏。
User::Leave()调用，其将会终止当前的函数，并指定一个错误码，返回到捕获器中。
d) User::Leave()的使用
User::Leave()用以在发生异常的时候立即中止功能模块的处理。
void doExampleL()
{
CExample* myExample = new CExample;
if (!myExample) User::Leave(KErrNoMemory);
// leave used in place of return to indicate an error
// do something
myExample->iInt = 5;
testConsole.Printf(_LIT("Value of iInt is %d.\n"),myExample->iInt);
// delete
delete myExample;
}
如果NEW失败的话便会调用User::Leave()；
e) TRAP使用
在捕获器下执行将要发生异常的程序
可能发生异常的函数或是调用其它可能发生异常函数的函数都必须在捕获器下执行。如果在一个函数调用了User::Leave(),那么控制权将立即返回到最近的TRAP中去。通常会定义一个变量用以了取得错误码。当没有异常发生时，函数调用完后执行TRAP，但其错误码不会改变。
TInt E32Main()
{
testConsole.Title(); // write out title
testConsole.Start(_LIT("Example")); // start a new "test"

// The leave variable
TInt r=0;
// Perform example function. If it leaves,
// the leave code is put in r
TRAP(r,doExampleL());
// Test the leave variable
if (r)
testConsole.Printf(_LIT("Failed: leave code=%d"), r);

testConsole.End(); // finish
testConsole.Close(); // close it
return KErrNone; // and return
}
TRAPD的使用
用法与TRAP相同，只是不用定义变量。
TRAPD(leaveCode,SomeFunctionL()); // call a function
if (leaveCode!=KErrNone) // check for error leave code
{
// some cleanup
}
TRAPD(leaveCode,value=GetSomethingL()); // get a value
if (leaveCode!=KErrNone) // check for error leave code
{
// some cleanup
}
else { // didn’t leave: value valid
}
f) new with automatic leave on failure的使用
如果NEW失败的话，则意味着必须离开这段程式，也就没有检查NEW返回的结果的必要了。

void doExampleL()
{
// attempt to allocate, leave if could not
CExample* myExample = new (ELeave) CExample;
// new (ELeave) replaces new followed by check
// do something
myExample->iInt = 5;
testConsole.Printf(_LIT("Value of iInt is %d.\n"),myExample->iInt);
// delete
delete myExample;
}
g) 捕获器(trap harness)放在哪里最好？？？
捕获器可以嵌套使用，如果一个程序引起异常，控制权将返回到最近的捕获器去，这就让嵌套子程序有其自己的捕获器。良好的捕获器必须能够准确的知道错误类型并能做出恢复。
所有的GUI程序都提供了一个顶级(嵌套级别)的捕获器，如果异常发生，而用户没有去处理他，那么GUI程序所提供的捕获器就会响应这个错误，并做出相应的处理。
大多数的程序的捕获器都会处理用户的命令，但对于一些特别的情况，捕获器还会处理一些特殊命令，a much finer_grain approach.
对于大型的应用程序，最好有一个单一的恢复单元，最好在一些特殊地方放置捕获器。

[hanming]

2. ClearStack基础
a) 当程序发生异常，它将跳到TRAP(TRAPD)宏下的语句，然后将堆栈指针指向最初的TRAP宏，然后跳到期望的程序。因此：(1)任何自动创建的对象，以值做为参数传递的对象和做为其它对象参数而被建立的对象都会被遗弃，即其析构函数不被调用，除堆栈上的存储空间以外，申明的所有的资源将不会被释放。(2)在能被安全的遗弃的对象与不能被安全遗弃的对象之间，将存在明显的差异。T类型数据能被安全的遗弃，如：TInt, TPoint, TPtr和其他的一些数据，C类对象不允许被遗弃，最好不要在堆栈里分配它们。R类对象可包含其他外部资源，所以，R对象可以进行拷贝操作，而不用拷贝其资源。因此R类拷贝对象可以分配在栈上。而栈上分配的拷贝对象可以被安全的遗弃。(3) 如分配的对象内部有捕获器，那它将不能被遗弃，而是无论如何都要清除掉。
Clear Stach 是EPOC处理最后出现的问题的机制。
例子：
void doExampleL()
{
// An T-type object: can be declared on the stack
TBuf<10> buf;

// A C-type object: must be allocated on the heap
// Allocate and leave if can not
CExample* myExample = new (ELeave) CExample;

// do something that cannot leave: no protection needed
myExample->iInt = 5;

// PROBLEM: do something that can leave
myExample->DoSomethingL();
// delete
delete myExample;
}
如DoSomethingL引起异常的话， CExample的对象将被遗留在堆中。这块内存在程序中止之前就收不回来。
b) CleanStack 的使用
(1) 在可能引起异常的操作之前，用CleanupStack::PushL()将对象指针压入Cleanup栈中。
(2) 在所有可能引起异常的操作完成之后用CleanupStack::PopL()将对象指针从栈中弹出。
(3) void doExampleL()
{
// allocate with checking
CExample* myExample = new (ELeave) CExample;

// do something that cannot leave
myExample->iInt = 5; // cannot leave: no protection needed

// do something that can leave: use cleanup stack
CleanupStack::PushL(myExample); // pointer on cleanup stack
myExample->DoSomethingL(); // something that might leave
CleanupStack::Pop(); // it didn't leave: pop the pointer

// delete
delete myExample;
}
注意：因为CExample 有可能在异常发生时被遗留在内存中，所以Cleanup Stack 在这里是必须的。由于myExample是一个指向CExample的指针，其自身在栈中就可以被遗弃。CleanupStack::PushL()由于需要更多的内存，所以自身就有可能引起异常。CleanupStack::PushL()的失败将正确的将对象清除。
c) 怎样弹出与销毁？？
(1) 通常，任何通过自动变量访问的对象在使用之前直接压入栈中，而在这个对象销毁之前将其弹出。
(2) 可以用CleanupStack::PopAndDestroy()去完成这弹出与销毁。
void doExampleL()
{
// allocate and leave if could not
CExample* myExample = new (ELeave) CExample;

// this cannot leave - no protection needed
myExample->iInt = 5;
// do something that might leave, protected by cleanup stack
CleanupStack::PushL(myExample); // push pointer to stack

myExample->DoSomethingL()}; // something that might leave

// pop from cleanup stack, and destroy, in one operation
CleanupStack::PopAndDestroy();
}
注意： Pop()仍然有用，在任何有可能引起异常的操作完成之前，将对象弹出栈销毁或是存储都是很安全的。因此，对象也就不会引起异常，
d) the trailing-C naming convention的使用
分配函数綺常是用来将分配对象和将对象压入栈中进行封装的一个操作，如User::AllocLC()分配内存，如果失败了就Leave，否则就将对象压入栈中。
函数后面加C就表示，如函数不会引起异常，就将其压入栈中。
函数调用一个-C函数，必须在使用这后将其弹出(如函数分配了一个对象，则必须销毁)。
e) Destructor requirements
C类型的类，清除时会调用析构函数。析构函数用来释放所有C类型的资源。
清除(Cleanup)是在创建部分对象时发生，而析构函数却不会。《By definition, cleanup may occur on partially constructed objects: the destructor may not, therefore, assume that all conditions for a fully-constructed object hold in these circumstances. A typical situation to watch for is calling a member function on a pointer that is initialised in the ConstructL(), as the pointer could be NULL in failure cases.》
资源通常以指针或是句柄指定。如没有资源分配的话，指针或是句柄将为空(NULL)，析构器在释放他们时将判断是否为空。CBase派生类沿用了这个行为，因为他们在初次分配时初始化为0。
程序员必须小心对象指针的重复分配与释放，当一个对象被释放时，必须将其
指针清为空。
f) 怎么样分配与释放Cleanup Stack？
GUI和Servers程序的框架都已内建了Cleanup Stack，而Console程序就需要显示的调用相关函数来分配与释放Cleanup Stack。
TheTrapCleanup=CTrapCleanup::New();
delete TheTrapCleanup;
注意：
(1) 需要的Cleanup处理的线程需要显示的调用函数，反之则不必。
(2) Cleanup Stack的名称可以为任意合法的名称。支持多个Cleanup Stack,系统有一个Cleanup Stack的栈，也是是当前的栈，当一个新的Cleanup Stack建立，就将其压入系统的Cleanup Stack中。并使当前CleanupStack为新建立的CleanupStack.当前栈被销毁时，前一个栈就成了当前栈。
g) Cleanup 使用总结
(1) 如异常发生，分配的对象和一个结构里的对象指针务必是能被访问的，且能够被弹出并清除。
(2) 对象中的另一个对象的指针必须是可以访问的，在异常发生之前，则能从CleanupStack中弹出，然后存储
(3) 在异常发生时，不能多次清除一个对象。
(4) an object is accessible if a leave occurs, if either it is pushed to the cleanup stack, or there is a reference to it from another object which would be accessible if a leave occurred, or there is a reference to it from a stack frame which would not be affected when a leave occurs (because of an appropriately-placed TRAP), or there is a reference to it from a global variable

[hanming]

3. 两段构造
a) CBase派生类与两段构造
如果一个对象的构造不会引起异常(除内存不足)，那么它就可以用C++构造器，通过new来自动创建。
如对象的构造会引起异常，则对象必须被压入CleanupStack中去，或是这个对象的指针必须存放在另一个能在异常发生时能清除的对象中。在构造函数中任何部分都可能引起异常。故构造就不能在C++的构造函数中完成，而是在另一个初始化函数中去完成，即第二段构造函数。
两段构造的步骤：
(1) 使用new 为对象分配内存
(2) 定义一个不会引起异常的C++构造函数(可选)
(3) 将对象指针压入CleanupStack中，或是存放到另一个支持Cleanup的对象中。
(4) 使用第二段构造函数完成可能引起异常的构造工作。
注意：
(1) 整个步骤綺常封装在静态成员函数NewL()和NewLC()中。
(2) 抽象类不被实例化，但还是有第二段构造器,NewL()和NewLC()。
(3) 上面第2步是可选的。因为第二段构造能完成其功能。只有一个类是直接从基类派生而来，而其基类缺省的C++构造函数不能被使用的时候，C++构造函数才需要。在这种情况下，派生类必须以适当的参数调用基类的构造函数。
(4) 第二段构造器被叫做ConstructL();
b) 两段构造的实现
l Example Classes
class CSimple : public Cbase//没有外部资源的类
{
public:
CSimple(TInt);
void Display();
private:
TInt iVal;
};
class CCompound : public Cbase//拥有其它对象的复合类
{
public:
void Display();
~CCompound();
static CCompound* NewL(TInt aVal);
static CCompound* NewLC(TInt aVal);
protected:
CCompound(TInt aVal);
ConstructL();
private:
TInt iVal;
CSimple* iChild;
};
由于其构造函数是protected的，所以CCompound对象只能通过public的NewL()和NewLC()来创建。
l 不正确的构造函数引起内存泄漏
CCompound::CCompound(TInt aVal)
{
iVal=aVal;
iChild = new (ELeave) CSimple(aVal);
}
想想如是按上面的构造，会有什么后果？？
如 new引起异常，便会(a)CCompound类的内存已綺分配(b)由于异常，
便没有部分构造的CCompound类的合法指针。(c)没有合法的指针，也便没有清除CCompound的方法了。
l 两段构造
解决的方法就是分配CCompund类对象，将其指针压入CleanupStack中去，然后完成其构造。任何可能引起异常的构造必须在部分构造对象的地址被压入CleanupStack栈之后完成。
(a) 在对象被分配后将对象指针压入CleanupStack栈中。
(b) 调用ConstructL()函数去完成构造。
NewLC() example
// NewLC with two stage construction
CCompound* CCompound::NewLC(TInt aVal)
{
// get new, leave if can't
CCompound* self=new (ELeave) CCompound(aVal);
// push onto cleanup stack in case self->ConstructL leaves
CleanupStack::PushL(self);
// complete construction with second phase constructor
self->ConstructL();
return self;
}
现在ConstructL()函数用来替换C++的构造函数。从本质来说，在单一的构造情况下，它完成和C++构造函数一样的功能。
ConstructL() example
void CCompound::ConstructL()
{
// NB. function may leave, as CSimple::NewL may leave
iChild = new (ELeave) CSimple (iVal);
}
NewL()的实现是用来调用NewLC(),然后弹出压入CleanupStack栈的指针。
NewL() example


CCompound* CCompound::NewL(TInt aVal)
{
CCompound* self=NewLC(aVal);
CleanupStack::Pop();
return self;
}
l 注意：
两步构造应避免在类的C++构造函数的开始去包括CleanupStack::PushL(this)。它将带来与ConstructL()函数同样的效果。如果一个类被做为基类使用，那么它的任何派生类的构造函数都会招致在每一层的调用都会有一个PUSH和POP，而不是它自己的NewLC()中的一个POP和PUSH。《Two-stage construction for a class could be avoided by including a CleanupStack::PushL(this) at the start of the class’s C++ constructor. This would achieve the same effect as using ConstructL(). However if the class is to be used as a base class, the constructor of any classes derived from it will incur the overhead of one push and pop in the constructor called at each level in the inheritance hierarchy, rather than one pop and push in its own NewLC().》

c) NewLC()的实现与使用
当一个对象通过NewLC()来创建，在使用完这个对象时，用CleanupStack::PopAndDestroy()去销毁这个对象。
static CExample* CExample::NewLC()
{
CExample* self = new (ELeave) CExample();
CleanupStack::PushL(self);
self->ConstructL();
return self;
}
void doExampleL()
{
// allocate and push to cleanup stack - leave if failed
CExample* myExample = CExample::NewLC();
// do something that might leave
myExample->DoSomethingL();
// pop from cleanup stack and destroy
CleanupStack::PopAndDestroy();
}
d) 怎样写一个带有两段构造的派生类
当前一个派生类时，必须使用派生类的ConstructL()去正确调用基类的ConstructL().
在做派生类构造之前调用基类的ConstructL()



class CCompoundDerived::ConstructL()
{
CCompound::ConstructL();
// own construction
}

[kcomex]

haming兄！你的精神实在可嘉！我看到你的穇译真是有些感到国内Symbian力量真是不乏热情的革命者~~
不过?_?_?_?_
然而?_?_?_?_
可是?_?_?_?_
但是?_?_?_?_
以下观点仅为个人意见，于其他任何事情没有关系。kcome对下列文字保留任何权利，并且不做出任何保证和明示或暗示；包括但不限于?_?_?_?_[此处略去法律免责声明3000字，跟NOKIA学的，haha :)]

我2-3年前，自己对于三维动籣和视频处理很有兴趣，并且热情极高！国内的fans绝对比现在的Symbian力量强大的多，而且不乏高手和专业人士。不过那个时候搞高端的三维动籣，去看英文资料和文档，是用英文软件是很多国内热情高涨的fans的严重障癬。于是，就有人穇译资料。我就是一个，穇译了大量的英文文档和独立文章。但是，时间的推移，我明白了很多。
要想真正学到东西，靠别人穇译文档是绝对不够，不是解决办法的！真正尖端的技术，你必须自己学英文去看，去理解。我给别人穇译的三维动籣资料，我后来看看，觉得挺幼稚，别人一定看不懂得。因为尖端的技术，就没有穇译标准而言，大量的专业词汇是我第一个把它起一个中文名字，可是我的水平，或者说第一个给那些专业词汇命中文名的人，可以很容易被大家接受么？我想答案是否定的。
那么看看Symbian，关于Symbian的纸张印刷书籍，我想全世界迄今为止出版的不到10种。那么，这门技术可想而知了。
英文并不是什么困难的东西啊~~，我看到Nokia新发行Document的时候，肾上腺素的分泌程度一点也不必看到36E的程度小~~
把对Symbian的热情转化为学英文的热情吧，这是我自己的一点点看法。

我没有细看你的穇译，我没有对你的穇译质量，做任何评价，因为我会去看訽版的英文文档。哪怕是Nokia穇译成中文的Document，我也很少看的。

Regards
kcome

[hanming]

受教了，kcome师兄，你说的很有道理，小弟是刚入这行的新手，以前和现在是做NUCLEUS的，也是全英文文档，现在刚开始准备做这方面的项目，穇译SDK也是訽因的，但看了你的个人意见，我觉得如你所说，要想专入这个门坎，这个关是必须得过的，其实在穇译的同时，我也有这方面的考虑，但不是很多：)，也许看文档这一关就能够把不同水平的人区分开来，真正的成功是属于那些坚持不懈，从不放弃的人。对吗？？
很愿意和你做朋友，也很愿意多听一些像你一样的程序老手的箴言，毕竟我是一个刚入行的新兵(毕业还不到一年)，谢谢。
我的邮箱是hanm@gwtelecom.com,QQ:3923399,MSN:hanm827@hotmail.com,很乐意与你交谈。：)

[kcomex]

hanming兄！受用不起啊~~
大家互相交流就好了，相互学习，共同进步么~~
我现在要去lunch了，呵呵~~
在学校上网不方便，我可能22:00后才能联系你哦~~

Regards
kcome