4. 客户端API函数和过程

  4.1实体迭代程序

迭代程序目的是提供顺序地访问一个集合对象单元的方法，无需暴露它的底层的表现。对于设计资源管理器的设计数据库，通过使用迭代程序提供了一个紧密的访问设计数据库实体的方法，无需跨越API来创建一个镜像数据库。迭代程序主要功能是通过数据库遍历来读取每一个实体对象，实体对象可以为文档、文档集合、项目和抽象实体。

  4.1.1 ClientApi_CreateIterator函数

声明(来自ClientProcs单元)：

Function ClientApi_CreateIterator(ADesignEntity : TObjectHandle; AFilter　: SetOfEntityId; AnIterationMethod : TClientIterationMethod) : TObjectHandle;

描述：

ClientApi_CreateIterator函数返回一个迭代程序对象的句柄。三个参数描述在下面的列表中。如果迭代程序不能被创建，函数返回值是空(nul)。如果设计实体的句柄是0，即ADesignEntity参数值是0，那么迭代程序将遍历在设计资源管理器中加载的所有设计数据库，您能从容器层或从一个文件夹层向下迭代，所以ADesignEntity句柄代表您希望来从哪里进行来迭代程序的处理。

参见其它：

  4.1.2 ClientApi_DestroyIterator过程

声明(来自ClientProcs单元)：

Procedure ClientApi_DestroyIterator(AnIterator : TObjectHandle);

描述：

ClientApi_DestroyIterator过程销毁一个迭代对象。

参见其它：

  4.1.3 ClientApi_GetFirstEntity函数

声明(来自ClientProcs单元)：

Function ClientApi_GetFirstEntity(AnIterator : TObjectHandle) : TObjectHandle;

描述：

ClientApi_GetFirstEntity函数用给定的迭代程序句柄返回第一个查找到的实体，此函数将被在ClientApi_CreateIterator函数后和在ClientApi_GetNextObject函数前调用。

例子：

Var

DocumentName: String;//抽象地址字符串。

DocumentAddress: TDDBAddress;

Iterator: ClientTypes.TObjectHandle;

DocHandle: ClientTypes.TObjectHandle;

Begin

DocumentAddress := TDDBAddress.Create('');//建立一个地址对象。

Iterator:= ClientApi_CreateIterator(0, [eDocument], eAll);//建立对当前在设计资源管理器中打开的DDB进行迭代的迭代对象。

DocHandle := ClientApi_GetFirstEntity(Iterator);//查找第一个文档。

While DocHandle <> 0 Do

Begin

ClientApi_GetDocumentEntityAbsoluteAddress(DocHandle, DocumentName);

//ClientApi_GetDocumentEntityAbsoluteAddress在关联的设计数据文档内获得一个文档实体的绝对地址，绝对地址字符串赋值到DocumentName字符串变量。

DocumentAddress.Import_FromParameters(DocumentName);//把绝对地址字符串输入到DocumentAddress中，即表示DocumentAddress对象现成为迭代程序查找到的文档对象。

If StringsEqual(DocumentAddress.EditorKind, 'Sch') Then //如果文档对象的是原理图，DocumentAddress的EditorKind属性中存放文档的类型。

ShowInfo(DocumentAddress.Root.Name + ' 有一个原理图文档');

//DocumentAddress.Root.Name表示当前原理图所在的DDB包的名称。

DocHandle := ClientApi_GetNextEntity(Iterator);//查找下一个文档对象。

End;

ClientApi_DestroyIterator(Iterator);//销毁迭代程序对象。

DocumentAddress.Free;//释放DocumentAddress对象。

End;

此代码片段在设计资源管理器中所有打开的设计数据库中查找原理图文档。DocumentAddress对象是一个定义在DDB_Address单元中的TDDBAddress类，DDB_Address单元来自Protel 99运行时间库，TDDBAddress类提供了关于一个设计数据库中一个特定文档的信息，例如一个作为外部文档的OLE文档，并提供了此文档在它所属的设计数据库的有关位置信息，在此代码例子中，ClientApi_GetDocumentEntityAbsoluteAddress函数提取了文档的抽象地址并赋抽象地址字符串变量DocumentName，Import_FromParameters函数为TDDBAddress对象填充明细，然后再根据TDDBAddress对象的EditorKind属性来判断文档的类型。

参见其它：