Live Communications Server API 详解 （3）

         
bool Dispatch(
               string 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

7、Transaction

8、ServerTransaction

9、Header

         
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

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

12、CompilerErrorException

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

// 
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