LCS API
一、常用知识点：
1、[MSPL]Dispatch函数：
Dispatch函数向应用程序内部的提供事件句柄分配一个事件。
bool Dispatch(
string methodName,
);
参数：methodName,...
这个methodName在托管代码里，他将收到这个分配的消息，并处理它。
返回值：如果成功的转发指定的方法将返回true.否则返回false.
备注：如果你的应用程序用script-only标记，那么你用Dispatch的话编译将失败。
示例：下面的代码显示了Dispatch函数在application manifest内部的具体用法。和它自身的事件句柄方法
（event handler methods）的样例。
<?xml version="1.0" ?>
<lc:applicationManifest
appUri="http://www.adatum.com/myApplicationLocation"
xmlns:lc="http://schemas.microsoft.com/lc/2003/05">
<lc:splScript><![CDATA[
if (sipRequest) {
if (sipRequest.Method == StandardMethod.Invite) {
Dispatch("OnInvite");
}
else if (sipRequest.Method == StandardMethod.Message) {
Dispatch("OnMessage");
}
}
]]></lc:splScript>
</lc:applicationManifest>
public void OnInvite (object sender, RequestReceivedEventArgs requestArgs) {
// INVITE request processing goes here.
}public void OnMessage (object sender, RequestReceivedEventArgs requestArgs) {
// MESSAGE request processing goes here.
}
2、事务（Transaction）
当两个用户代理交换SIP消息的时候，发送请求的用户代理（UA）就是用户代理客户端
（UAC，User Agent Client）而返回应答的用户代理则是用户代理服务器（UAS，User Agent Server）。
SIP请求连同一个它所触发的应答被叫做一个SIP事务。
二、Microsoft.Rtc.Sip Namespace
1、ApplicationManifest
The ApplicationManifest class defines the application manifest for a SIP application.
2、BranchCollection
The BranchCollection class represents an unordered collection of client transactions (branches)
associated with a server transaction. Each client transaction is represented as a
ClientTransaction object, and can be obtained through the IEnumerator interface returned by
the GetEnumerator() method.
注：关于GetEnumerator()方法，BranchCollection.GetEnumerator；关于IEnumerator接口，是所有枚举的基接口。
BranchCollection对象是通过ServerTransaction.Branches获得的。它包含这个服务器端事务的全部客户端事务。
这个类实现IEnumerable接口。
3、ClientTransaction
The ClientTransaction class defines a SIP client transaction object located on a SIP proxy.
A ClientTransaction object is created by calling CreateBranch on a ServerTransaction object.
For forking proxy behaviors, ServerTransaction.CreateBranch can be called multiple times;
however, a ClientTransaction object itself can service only one request. To send the request,
call ClientTransaction.SendRequest.
To handle the responses for the request sent by a specific client transaction, you must
register for the ClientTransaction.ResponseReceived event. This event will return
a ResponseReceivedEventArgs object whenever it is raised, and contains the response as a
Response object.
Currently, the UAC client transaction case is not supported, where the server originates a
client transaction. Only proxy behaviors are available for this class.
The ClientTransaction class is derived from the Microsoft.Rtc.Sip.Transaction class.
4、 Response
The Response class defines a SIP response sent from a server transaction to a client
transaction.
To generate a response message for a request, call CreateResponse on the associated
Request object. P5opulate the Response message with the proper status class and reason
phrase, and then pass it to ServerTransaction.SendResponse, using the ServerTransaction
object for the initial request.
There are two methods for receiving a response:
- The response is filtered by the MSPL message filter and dispatched to a specific
- method defined in your application. (See the Dispatch built-in MSPL function for
- more information.) The method handling the response must have a signature that
- matches the ResponseReceivedEventHandler delegate.
- The originating request that incurred the response was sent from a specific
- ClientTransaction object instance running on your application. In this case,
- the response is obtained by registering an event handler for the
- ClientTransaction.ResponseReceived event.
In both cases, the response is returned as the
ResponseReceivedEventArgs.Response property, which contains a Response object. In the case where a ClientTransaction
object on the application incurred the response,
the ResponseReceivedEventArgs.ClientTransaction property will contain
a reference to the specific client transaction.
The Response class is derived from the Microsoft.Rtc.Sip.Message class.
5、 Request
The Request class defines a SIP request sent from a client transaction to a server transaction.
Client transactions are represented as a ClientTransaction object, and server transactions are represented as a ServerTransaction object. A request is sent by calling the ClientTransaction.SendRequest method. Any transaction may have only one associated request.
Requests are proxied by calling ServerTransaction.CreateBranch and creating an associated ClientTransaction object for the proxied request. To fork a request, call ServerTransaction.CreateBranch once for each fork, and then call ClientTransaction.SendRequest on each element in the BranchCollection found at ServerTransaction.Branches.
To generate a response message for a request, call CreateResponse on the associated Request object. Populate the Response message with the proper status class and reason phrase, and then pass it to ServerTransaction.SendResponse, using the ServerTransaction object for the initial request.
When a response is returned for a specific request, a ResponseReceived event is raised on the ClientTransaction object that sent the request, and a ResponseReceivedEventArgs object is supplied to the method provided to the ResponseReceivedEventHandler delegate.
The Request class is derived from the Microsoft.Rtc.Sip.Message class.
6、ServerAgent
The ServerAgent class implements a Live Communications server agent.
Applications use ServerAgent objects to interact with the Live Communications Server. Each object of this class represents a logical SIP application to the server. Most applications will create only one such object, but in special cases, it may be necessary to create multiple server agent objects (such as for logging all incoming and all outgoing messages).
Before a ServerAgent object is instantiated, an application manifest should be created to describe the application to the server and provide the message filtering service.
This class implemented the IDisposable interface.
The ServerAgent class is derived from the System.Object class.
7、Transaction
The Transaction class provides the abstract base class for the ServerTransaction and ClientTransaction classes, and represents a generic SIP transaction.
This class implements the IDisposable interface.
The Transaction class is derived from the System.Object class.
8、ServerTransaction
The ServerTransaction class defines a SIP server transaction object located on a SIP proxy or user agent server (UAS).
A ServerTransaction instance is generated as the RequestReceivedEventArgs.ServerTransaction property, available on the RequestReceivedEventArgs object dispatched to a specific method by the MSPL script filter. (See the Dispatch MSPL built-in function for more information.) There are no public constructors for this class.
The request being serviced by this server transaction can be forwarded by calling ServerTransaction.CreateBranch, which will create an associated ClientTransaction. To fork a message, CreateBranch can be called for each fork. The collection of branches for this server transaction can be obtained as a BranchCollection object by referencing the ServerTransaction.Branches property. Requests are sent by calling ClientTransaction.SendRequest on each branch.
To send a response for the request the server transaction was created to service, call ServerTransaction.SendResponse with the Response object created by calling Request.CreateResponse on the Request object available in the RequestReceivedEventArgs.Request property.
The ServerTransaction class is derived from the Microsoft.Rtc.Sip.Transaction class.
9、Header
The Header class defines a SIP header.
The Header class is derived from the System.Object class.
Example Code
The following code sample sends a redirection response with the new endpoint address in the "Contact" header. Requests are dispatched to this method from the MSPL script in the application manifest using the Dispatch MSPL function.
public void OnRequest(object sender, RequestReceivedEventArgs rreArgs)
{
// Send a generic response to the sender indicating redirection (302). Response response = rreArgs.Request.CreateResponse(302);
response.ReasonPhrase = "Redirected by Live Communications Server";
// Add the "Contact" header indicating the new redirection address of the SIP user.
// In this example, the localhost is supplied; in a real application, the second
// parameter of the Header constructor would be the redirection address of the user.
Header h = new Header("Contact", "sip:127.0.0.1:5060;transport=tcp");
response.AllHeaders.Add(h);
// Send the response.
rreArgs.ServerTransaction.SendResponse(response);
}
10、HeaderCollection
The HeaderCollection class defines the collection of header fields in any given SIP message.
This class implements the IEnumerable and ICollection interfaces.
The HeaderCollection class is derived from the System.Object class.
Example Code
The following code sample iterates through a HeaderCollection and writes the header type along with its associated value. In this case, the HeaderCollection is the AllHeaders property set on an incoming Request.
public void OnRequest(object sender, RequestReceivedEventArgs rreArgs)
{
Request r = rreArgs.Request;
HeaderCollection headers = r.AllHeaders;
foreach (Header header in headers)
{
Console.WriteLine("{0}: {1}", header.Type, header.Value);
}
}
11、Message
The Message class defines the abstract base class for SIP message classes. It contains a parsed SIP message, separated into its component headers and content.
The Request and Response classes inherit from this class. Objects of these types are generated by transactions (represented as a Transaction type or derived type, such as ClientTransaction and ServerTransaction) between two proxies.
Message headers are represented as Header objects. The collection of all headers on a message is found in the Message.AllHeaders property, which contains a HeaderCollection object. This HeaderCollection object contains all of the headers defined on the message. The content of a message is accessible through the Message.Content property.
This class implements the ICloneable interface.
The Message class is derived from the System.Object class.
12、CompilerErrorException
The CompilerErrorException class defines the exception that is thrown when an application manifest compiler encounters an error.
The CompilerErrorException class is derived from the System.ApplicationException class.
ApplicationManifest myAppManifest = ApplicationManifest.CreateFromFile("C:\\xmldocs\\my_app_manifest_xml_file.xml");
try {
myAppManifest.Compile();
}
catch (CompilerErrorException compilerErrorException) {
Console.WriteLine("The following MSPL compiler errors occurred:");
foreach (object errMsg in compilerErrorException.ErrorMessages)
{
Console.Write("\t{0}", errMsg.ToString());
}
Console.WriteLine();
}
13、ConnectionDroppedEventArgs
The ConnectionDroppedEventArgs class defines the object returned by the ServerAgent.ConnectionDropped event.
The ConnectionDroppedEventArgs class is derived from the System.EventArgs class.
//
ServerAgent mySA = new ServerAgent(this, myAppManifest);
mySA.ConnectionDropped += new ConnectionDroppedEventHandler(OnConnectionDropped);
//
// Event handler for ConnectionDropped events.
public void OnConnectionDropped(object sender, ConnectionDroppedEventArgs cdeArgs)
{
//
switch (cdeArgs.Reason)
{
case ConnectionDroppedReason.ApplicationDisabled:
Console.Writeline("The application has been disabled on the Live Communications Server.");
break;
case ConnectionDroppedReason.ApplicationDisconnected:
Console.WriteLine("The application has been disconnected from the Live Communications Server.");
break;
case ConnectionDroppedReason.ApplicationReconnectTimeout:
Console.WriteLine("The application timed out while attempting to reconnect to the Live Communications Server.");
break;
case ConnectionDroppedReason.ServerAgentDisposed:
Console.WriteLine("The ServerAgent instance for this application had Dispose called on it.");
break;
, case ConnectionDroppedReason.ServerShutdown:
Console.WriteLine("The Live Communications Server was shut down unexpectedly.");
break;
default:
Console.WriteLine("The connection to the Live Communications Server was dropped for unknown reason.");
break;
}
}
14、RequestReceivedEventArgs
The RequestReceivedEventArgs class defines information to an application regarding the arrival of a SIP request.
When a request has been successfully dispatched by the MSPL message filter (see the Dispatch built-in function), an event containing a RequestReceivedEventArgs object will be dispatched to the specified method (whose signature must match the RequestReceivedEventHandler delegate). RequestReceivedEventArgs contains the request as the RequestReceivedEventArgs.Request property.
An instance of ServerTransaction is created as a property of RequestReceivedEventArgs. This property represents the new server transaction for the request. To forward this request, call ServerTransaction.CreateBranch to create a ClientTransaction and call ClientTransaction.SendRequest, passing the Request object in the RequestReceivedEventArgs.Request property.
The RequestReceivedEventArgs class is derived from the System.EventArgs class.
参考文档《Microsoft Office Live Communications Server 2005》