Dispatch(string) function

Microsoft Office Live Communications Server 2005 with SP1

Dispatch

The Dispatch function dispatches an event to a supplied event handler within the application.

bool Dispatch(
  string methodName,...
);

Parameters

• methodName,...
  The name of a method in the managed code application that will receive the dispatched message and process it. Can take zero or more additional values whose type is one of null, bool, int, float, string, or any type that can be cast to a string. The additional arguments are passed only for dispatching requests. They are not passed for dispatching responses.

Return Values

Returns true if control was successfully transferred to the specified method; false if it was not. Failures can occur under heavy server loads.

Remarks

Within the application, there must be a method defined on the object supplied to the ServerAgent constructor that corresponds to the method name supplied in methodName. If the message type is a request, the event handler will receive a RequestReceivedEventArgs object containing the message as well as the associated client transaction. If it is a response, the event handler will likewise receive a ResponseReceivedEventArgs object containing the response as well as the associated server transaction.

If your application is declared as script-only (such that the managed code component serves only to create a server agent instance and register your script), and you call Dispatch, compilation will fail. This is because a declaration of script-only implicitly informs the server that Dispatch will never be called, assuming that you do not have any methods in the application to handle the messages.

A message is not dispatched if it has been previously dispatched, responded to, forked, or proxied. If an attempt is made to dispatch the message in one of these cases, a critical MSPL error is raised.

The Dispatch function has been extended to accept additional parameters that may specify references to any of the types defined above in the "parameters" section. These new parameters are passed to the managed method as a params array of objects, where each object is a boxed based type (int, float, bool) or a string, depending on the type of the argument passed to the Dispatch function. The additional parameters may not specify any references to either the sipRequest or sipResponse built-in variables because the built-in variable state is already marshaled across.

Example Code

Below is a code example showing the MSPL Dispatch calls within the application manifest, and the corresponding event handler methods within the application itself.

<?xml version="1.0" ?>
<lc:applicationManifest
   appUri="http://www.adatum.com/myApplicationLocation"
   xmlns:lc="https://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.
}

...

What did you think of this topic?

© 2008 Microsoft Corporation. All rights reserved.