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》