Live Communications Server API 详解（1）

Live Communications Server Application API
发布时间：2005 年 6 月

摘要：LCS API套件中包括：Microsoft SIP Processing Language(MSPL)、Microsoft.Rtc.Sip命名空间、application manifests 和为LCS构建SIP应用程序的资料。本文档将针对以上部分进行详细介绍。

LCS API套件中包括：
Microsoft SIP Processing Language(MSPL)、Microsoft.Rtc.Sip命名空间、application manifests 和为LCS构建SIP应用程序的资料。
Note The Live Communications Server Application API currently does not support SIP dialogs and UAC server behaviors. Future versions of the API will add support for these features.
1. Application manifests
The application manifest is an XML document that describes a Live Communications Server application to the server on which it is running. This document is presented to the server when the application registers with Live Communications Server through the Microsoft.Rtc.Sip.ServerAgent managed class.

1.1 Application manifests构成：
Application manifests由以下三部分组成：
1.1.1 <alias:applicationManifest>标签。
在这个标签内装入应用程序属性（Application attributes）和消息过滤脚本（MSPL），可以为"alias"定义一个别名，微软建议使用默认别名"ls"。
1.1.2 A set of application attributes that defines key properties of the application, such as the SIP message types to filter and whether it is script-only.
1.1.3 用MSPL语言写的消息过滤脚本。
在CDATA element里被附加上<alias:splScript>标签。
1.2 Application manifests部属：
这个Application manifests文件，一次建立后，可以和装配件（assembly）里的resource一样，植入应用程序内部，或者像一个外部文件一样存在。
1.2.1 植入assembly内部：
用Microsoft.Rtc.Sip命名空间的ApplicationManifest类，在新生成的 ApplicationManifest对象里用Compile方法对它进行编译。样里代码如下:

ResourceManager myResourceManager = new ResourceManager(MyApplicationType);

string appManifestXml = myResourceManager.GetString("appManifest");

ApplicationManifest myAppManifest = ApplicationManifest.CreateFromString(appManifestXml);

try

{

myAppManifest.Compile();

}

catch (CompilerErrorException cee)

{

Console.WriteLine("Failed to compile.");

foreach (string message in cee.ErrorMessages)

{

Console.WriteLine(message);

}

return;

}

编译成功后，这个编译过的Application manifests部属到代理服务器上，
1.2.2 外部文件格式：
下面是一个仅有SIP INVITE and MESSAGE请求的基本的application manifest：

<?xml version="1.0" ?>

<lc:applicationManifest

appUri="http://www.adatum.com/myApplicationLocation"

xmlns:lc="http://schemas.microsoft.com/lc/2003/05">

<lc:requestFilter methodNames="INVITE,MESSAGE"

strictRoute="false"

registrarGenerated="true"

domainSupported="true"/ >

<lc:responseFilter reasonCodes="NONE" />

<lc:proxyByDefault action="true" />

<lc:scriptOnly />

<lc:splScript><![CDATA[

if (sipRequest) {

if (sipRequest.Method == StandardMethod.Invite) {

Dispatch("NameOfInviteHandlerMethodInApplicationHere");

}

else if (sipRequest.Method == StandardMethod.Message) {

Dispatch("NameofMessageHandlerMethodInApplicationHere");

}

]]></lc:splScript>

</lc:applicationManifest>

1.3 Application Attributes
Application Attibutes在消息过滤脚本的前面，在<lc:applicationManifest>标签的后面，包含详细的描述LCS应用程序的数据。例如下面所示：

<?xml version="1.0" ?>

<lc:applicationManifest

lc:appUri="http://www.adatum.com/applicationName"

xmlns:lc=http://schemas.microsoft.com/lcs/2004/05>

application attributes

<lc:splScript><![CDATA[

message filter script

]]></lc:splScript>

</lc:applicationManifest>

       其中，xmlns属性指定了用那个版本的LCS来运行应用程序，如果是LCS2003就采用下面的方式：
       xmlns:lc=http://schemas.microsoft.com/rtc/2003/05

共有下列应用程序属性标签可供Application manifests使用：
1.3.1

<lc:proxyByDefault action="true|false" />

说明：为应用程序指定默认代理行为。
如果是true，服务器自动代理任意消息，应用程序不依据句柄执行。如果是false，消息被抛出，应用程序结束，同时，一方将不会收到它。
1.3.2

<lc:scriptOnly />

说明：当部署时，指定应用程序不含托管代码的成分。
1.3.3

说明：指定应用程序通过服务器的那些请求。
有下列methodNames
REGISTER
SUBSCRIBE
NOTIFY
BENOTIFY
ACK
BYE
INVITE
OPTIONS
MESSAGE
SERVICE
INFO
REFER
OTHER
1.3.4

<lc:responseFilter reasonCodes="RESPONSE_CLASSES|ALL|NONE" />

说明：定义应用程序通过服务器响应那个类别。
类别如下：
1XX
2XX
3XX
4XX
5XX
6XX
1.3.5

<lc:file path="filePath" keyColumnName=[columName] delimitedBy="comma/tab/whitespace"

<lc:column name="ColumnName"/>

</lc:file>

说明：Name属性指引用的text文件名称，必须是有效的MSPL。Path属性是这个文件的决对路径，如果是相对的，它必须是相对于运行RTCSRV.exe的路径。
1.3.6

<lc:column name="columnName"

用这个标签可以指定一个或多个列节点。

2. Microsoft SIP Processing Language
MSPL是用来过滤或路由SIP消息的脚本语言，像大家知道的"message filters"，这个脚本是植入到application manifests里的LCS应用程序中。
MSPL不支持：
Explicit (declarative) data types
Type casting
Pointers
Declarations (other than basic function declarations, as detailed below)
Arithmetic operations
Iteration statements
Preprocessor statements
Attributes
Static or global variables (state is not maintained across script invocations)

2.1 MSPL Script Syntax
2.1.1 Function Invocation
一个函数在MSPL里是唯一的，在MSPL里函数用如下语法格式来定义：

function ParseDisplayName (displayName)

{

}

所有的函数定义必须在消息过滤脚本的开始处，在过滤脚本之前。一个函数能有零个或更多的参数。为了防止无意中的循环，递归函数的调用是不允许的。互相的递归调用calls-calls模式也是不允许的。例如，如果函数1调用函数2，然后调用函数3，函数3不能调用1或2的任意一个。返回值类型是implicitly defined的，更确切的说，这个类型是传递的返回声明的值决定的。参数也是implicitly defined的。函数不能返回collections，它支持的的返回类型有strings,bools,integers和floats.
下面的函数示例过滤了一个特殊的string，如果这个string被找到返回true,否则，返回false.

function FilterString (content)

{

filterWord ="confidential";

return ContainsString(content, filterWord, true);

}

2.1.2 The foreach Statement
在SIP消息处理过程中foreach允许脚本编写者比较句柄collections，例如contact header collections和 endpoint collections。下面示例演示了foreach loop的语法构成。

foreach (element in expression) statement

For example:

foreach (dbEndpoint in

QueryEndpoints("someone@example.com"))

{

}

这段代码将求出collections里的值，Strings和其他unary types 像single-item collections一样的处理。

2.1.3 The break Statement
Break 的用法和C#中switch/case里的用法相同

2.1.4 The null Keyword
Null关键字，脚本语法能添加一个null关键字，与empty string ("")不同，empty string是不能建立的。有下列函数将返回一个null来表明值没有找到或者错误。
" GetDisplayName
" GetHostName
" GetParameterValue
" GetScheme
" GetUri
" GetUriParameter
" GetUserName
" GetUserAtHost
" GetXMLAttr
" QueryHomeServer
另外，Message.Stamp 和 Message.StampPool也返回null.