第二章 Notes Object Services

本章将描述Notes Object Serivces（NOS）,它是Notes client和server中的核心功能。

Notes Object Services

NOS是大量函数的一个集合，程序员可以通过Notes应用程序接口来访问这些函数集。NOS函数集提供了被client和server所使用的基本的，可移植的，线程安全的服务。

NOS函数集按照相关性非为许多不同的组。同一组内的函数都以相同的组名作为函数名的前缀--例如，Extension Manager相关函数以“EM”开头。函数组之间也有层次关系--例如一组函数可以使用另一组函数提供的服务，提供服务的这组函数也许又依赖于其他组函数提供的功能。

Portabliity (可移植性）

可移植性是Notes最主要的一个优势。大型组织通常将各种不同的操作系统联合起来使用已构成他们的企业环境。例如，人力资源使用运行在Windows系统的一个福利软件，工程部门需要UNIX上运行的一套CAD/CAM软件。由于Notes可以运行在多个不同的系统，这些部门就能在使用其各自不同软件的同时，也方便的使用Notes。

为了实现可移植性，Notes在NOS的源码中实现了一个可移植层，此层可以运行在任何Notes运行的系统上。从架构的角度来看，这种可移植性是通过在NOS的可移植层大量的使用的条件编译来实现，换句话说，Notes通过这个可移植来与操作系统交互。可移植层直接与操作系统进行交互，可以使得基于可移植层的通用模块充分利用各种操作系统所提供的额外的内存和I/O功能。

将NOS实现在一个类似于虚拟操作系统之上，可以有效的使得大部分Notes相关的功能函数与底层平台无关。

NOS线程安全

一个多进程的操作系统可以同时的执行多个进程。多进程系统一般通过如下几种方式来实现。一种是使用多处理器的硬件--也就是说，一个计算机有多个处理器，每个处理器执行一个或者多个进程。另一种是单一处理器通过进程调度软件来同时运行多个进程，处理器迅速的在进程之间切换，造成了多个程序同时运行的假象。

在多进程的系统中，多个Notes应用也许会同时的调用某个NOS函数，或者用NOS函数同时的访问相同的数据---例如，他们也许同时试着打开Notes数据库中的同一个document。如果Notes允许这样这样的操作，数据在多个应用混杂的读写后可能会被损坏。为了避免这种情况，Notes程序会串行的执行对共享数据的访问。

串行化可以避免多个进程或者线程同时读写，造成数据的损坏。利用串行化逻辑实现的代码也就是线程安全的。

NOS函数采用的这种串行化的方法，因此它是线程安全的，可以避免共享数据的损坏。NOS服务以最有效的方法保证了平台上的线程安全，因此，使用这些服务的应用就无需自己实现这种串行逻辑。

NOS架构图

下图阐明了NOS各功能组之间的关系。

NOS service groups

大多数的服务都属于下属服务组的一部分：

- 可移植层是负责Notes和底层平台交互的接口。其中你可以找到所有与系统交互的Notes组件。

- 网络服务允许应用程序使用自己的协议来与其他系统进行连接和通信。

- 数据库服务提供了防伪Notes数据库文件内容的接口。底层的数据库服务提供了诸如穿件，备份，删除任务的功能。高层的数据库服务提供了像全文索引，邮件以及调度的功能。

NOS service groups表

下表描述了NOS中的各服务组。

Service Group          |　　　　Description

---------------------------------------------------------

ACL                        |   管理加载在内存中ACL的内容，这些服务通常与NSFDbReadACL/NSFDbWriteACL联合使用

AdminReq              |   像Administration进程提交请求

Addin                     |    Facilitates logging within Domino add-in applications.

Agent                    |    加载并运行数据库中的“agent”notes

Alarm                    |    管理Notes alarm

CompoundText，   |  

ConvertItem,          |   管理内存中的rich text对象，以及将rich text 对象转换成 text对象

EnumComposite     |

DN                        |   进程的名字是由 distinguished-name 构成 -- 例如， “CN=...."

EM                        |   通过hook一些定义好的Notes活动来定制Notes的功能--例如，当打开或者关闭数据时调用用户自定义的功能。

Event                     |   管理event和event 队列

FT                         |    创建本地数据库的全文索引，搜索满足条件的document

ID                         |    管理统一数据库中压缩的note ID列表

List                       |    管理内存中text list， text list是note database中个通用的类型

Log                      |     管理日志

MQ                      |     使得Notes应用可以响应其他Notse应用发送来的服务请求

Mail                     |      处理邮件中诸如邮件头，附件等条目

Name                  |      定位Domino目录和地址簿，并从中捞取数据

Net，NTI             |      为应用程序访问网络和网络传输驱动提供一组可移植的接口

NIF                     |       为Notes数据库中一个或者多个documents创建和管理索引

NLS                    |       负责字符集的转换

NSF，Folder，Subform|  f访问Notes数据的内容

ODS                   |      将数据在NSF文件中和内存中相互转换

OS，                  |      分配内存，读取环境变量等等

REG                   |      注册client，server和IDs

Time                  |      使用Date/Time信息

Sch                    |      用Notes API管理用户调度

SECKFM            |       管理用户，公钥和证书

Miscellaneous    |       包括：Abstract, Billing, Convert, IntlTextCompare, Map, Soundex, and Stat.

                        |        参考最新的 Lotus C API 以获得帮助。

NOS 可移植层服务

可移植层包括了和底层操作系统交互的Nots组建。和主机操作系统进行交互，也就是软件必须能够正确的使用操作系统提供的服务和资源。具体来说，包括如下三个交互：

- 在内存和磁盘之间传递数据

- 在网络之间传递数据

- 使用主机的操作系统的服务

可移植层提供的函数屏蔽了高层应用和操作系统之间的这些差异。系统的底层也许需要针对不同的操作系统管理和处理的数据，但是高层的组件将不会搜到这些差异的影响。

下表描述了可移植层所提供的服务。

Portability layer 　　　　　　          |　　service Description

Notes language services(NLS)        |      处理 text 字符串

On-disk structure(ODS)                  |     在内存和nsf文件中传递数据

Operating System service（OS）     |    分配内存，获取环境变量等

NOS中Notes 语言服务

Notes语言相关的函数都以NLS开头，可以用来处理字符串。这些函数包括：

- 在自定字符串中查找子串

- 在字符串中找某个字符第一次出现的位置

- 通过指针获取一个字符，将指针向后移动

- 判断字符的类型，大小写，数字，文件，符号等

- 加载一个指定字符集

- 在缓存之间拷贝字符

- 返回字符串中字节数目

- 翻书字符串中字符数目

On-disk structure service in NOS

On-disk structure services, 以前缀ODS开头，将数据在nsf文件和内存之间转换。

- 获取数据结构的大小

- 将一个标准的结构格式化为machine-specific 格式

- 将machine-specific格式转换成标准格式

NOS中操作系统服务

操作系统服务是以OS前缀打头的一组函数，可以获得本地操作系统的环境变量。

- 获取系统信息 -- 例如时间日期

- 创建以及使用动态数组

- 获取和设置环境变量中的值

- 加载和运行外部程序

- 分配和释放Notes/Domino系统中的一块内存

NOS 网络服务

一些网络服务支持Notes远程过程调用机制（NRPC）。这些服务允许客户端和服务器端访问不同服务器以及网络上共享的服务器数据库，包括拨号网络以及局域网。这些特殊的网络服务无法通过调用Lotus C API来访问，只间接的通过远程 Note API函数。

其他的一些网络服务则可以通过Louts C API 来访问，这些服务提供网络发送和接收机制，使得你可以通过串口来连接到远程系统，并且以字符的方式与系统进行交互。通过使用NOS网络服务，不同系统上的应用程序可以进行连接和通信。

网络服务包括：

- 为应用程序提供一个可移植的方式访问网络和网络传输驱动

- 为不同的网络协议提供单一的网络接口

- 可以发起和接收电话，或者在端口（Domino目录中Connection documents定义的）上创建LAN协议会话

这些服务可以比起直接操作系统的串口驱动有如下两个好处。第一，允许应用程序共享Notes/Domino使用的串口设备。第二，允许应用程序使用Notes/Domino系统中内建的modern模块。

应用程序应该按照如下的顺序使用上述服务：

1. 调用NetLink进行拨号连接到远程系统，并建立会话

2. 调用NetSetSessionMode来设置会话的操作参数

3. 在会话上调用NetSend和NetRecieve来按照应用程序规定的协议进行通信。

4. 调用NetCloseSession来挂断电话，释放串口设备，关闭会话。

以上这些都是很重要的步骤，一旦NetLink调用返回成功后，其后的步骤都应该顺序被调用，即使其中某个调用失败了。

NOS 数据库服务

Notes数据库服务提供接口来访问Notes数据库文件。一个Notes数据库是一系列documents的集合，docouments则是field的集合。Document和field各自通常也被称作notes和items。Notes数据库包含头文件信息，例如，数据库创建的时间，最后修改的时间以及universal ID（UNID）。

Notes数据库服务氛围两大类：

- Notes Storage Facility(NSF) services,提供底层的数据服务--例如，创建，备份，删除

- High-level database services， 包含搜做，邮件，定时调度

Notes Sotrage Facility services in NOS

Notes storage facility services都以NSF打头，提供了递呈的数据库服务，这些服务可以都可以通过Extension Manager进行扩展，包括

- 创建，打开，关闭数据库

- 数据库维护功能，例如campating和replicating

- 拷贝全部或者部分数据库内容

- 处理访问控制列表 ACL

- 备份本地数据库

- 有选择的访问数据头

- 拷贝或者删掉某一类的note

- 读，写，修改notes和他的fields

- 读，写，修改form和view notes

- 执行 Notse @function

High-level database services in NOS

高层数据库服务包括搜索，邮件，定时调度。其中一些服务可以通过Extension Manager进行扩展，其他的则不行。不可扩展的数据库服务包括：

- AdminReq

- Agent

- Calendar and scheduling
- Composite text, including ConvertItem and Enum Composite
- Folder
- Full text
- Log
- Mail
= Name
- Notes Index Facility
- Registration
- Subform

AdminReq services in NOS
AdminReq 服务向Administration Process 发送如下请求：

-  Check Access for Move Replica Creation
- Check Access for New Replica Creation
- Delete in Access Control List
- Delete in Address Book
- Initiate Rename in Address Book
- Move Person in Hierarchy
- Recertify Person in Address Book

- Rename Person in Address Book

Agent services in NOS
Agent services允许加载和运行数据库中的"agent" notes。与 form 和 view notes类似, agent notes 属于 design notes，它的类别是NOTE_CLASS_FILTER，存储在数据库中。Domino应用程序员通过设计agent来对数据库中的documents执行一些自动化得操作。Agent notes由一系列的document-selection formula， trigger（触发器），以及一个或者多个的action。action可以是Domino action， @function formula，LotusScript程序或者java 程序。某个预订的时间或者是特殊的事件（event）可以出发这些操作。每个操作都应用在指定一个documents集上。

通过使用 agent 服务，你可以创建，测试，执行以及查看agent工作的结果。这些服务引入了几个C API 管理note时需要用的结构体，结构体代表了notes在磁盘上的存储。当你查看这些头文件的时候，请注意assistant和agent两个是同义词。Notes和Domino同时也提供了一些函数来支持运行agent note.
这些服务包括:
- 打开一个含有agent的note
- 运行agent
- 设置agent执行的时间限制
- 判断agent是不是启用
- 停止agent

Calendar 和 scheduling 服务
Calendar 和 scheduling 相关的函数以前缀Sch开头，可以使用Notes API来管理用户的时间表。这些函数都可以通过Extension Manager来扩展。函数包括：

- 发送一个约定或者会议邀请给某个用户

- 从用户时间表中删除某个事件

- 查找一个用户空闲和占用的时间段

- 从schedule数据库（本地或者指定服务器上）查找某一组用户都空闲的时间

Composite-text
使用 composite-text 服务，你可以操作内存中的rich text对象，并将它们转成plain text对象。这些函数包括：
- CompoundText
- ConvertItem
- EnumComposite

Folder

访问folder和访问view中document的方法一样。事实上，folder就是view note的一种。你可以创建私有和共享的数据库folder。但是，你无法创建“Personal on first”的folder。同样你也无法创建用来存储桌面文件的私有folder。在Notes用户界面中，新创建的私有folder通常存储在一个指定的数据库中。然而，如果用户没有数据库访问权限，folder将会在用户的桌面文件中创建。在使用C API程序中，你无法在没有权限的数据库中创建私有folder。同样，你的C程序也无法存储在桌面文件中的私有folder。

为了访问数据库中的私有folder，可以将NIFFindPrivateDesignNote 的参数设置为NOTE_CLASS_VIEW。访问共享folder人，需要使用NIFFindView。然后再联合使用NIFOpenCollection和NIFReadEntries来获取folder中的document。可以参考Lotus C API 来获取更多信息。
函数包括:

- 创建一个folder

- 添加或者删除folder中的document
- 在同一父folder下移动folder

- 重命名folder

- 判断指定目录索引下条目的数量

- 删除folder

Full-text services in NOS 全文索引
全文索引相关的函数以FT开头，用来给本地数据库创建索引，以及在document中执行指定指定查询。这些函数同样也可以通过Extension Manager来扩展。函数包括：

- 为本地数据库创建全文索引

注意 C API不支持为远程数据创建索引

- 取得上一次对数据库进行全文索引的时间

- 查看全文索引结果

- 删除数据库的全文索引

To be continued...