Introduction to MIP Message communication

The MIP Message communication service offers a simple method for transmitting and receiving messages across MIP applications and plugins executing on different machines.

The communication is controlled by the Event Server, as all messages are forwarded to the Event Server and used directly by the Event Server or by plug-ins in the Event Server, or is distributed to other MIP Environments requesting the messages.

A MIP application or plug-in must register a set of filters to define what messages to receive and from which source. Only messages that are requested by at least one MIP Environment will be transmitted from a given MIP Environment.

It is also possible to directly send a message to another MIP Environment, even if the other MIP Environment did not register a filter, provided that the sender knows the destination FQID of the receiving MIP Environment.

The Event Server acts as a MIP message router. MIP based applications may send/receive messages by establishing sessions to the Event Server (Gray arrows).

MIP Messages sent by an application (red arrows) will be filtered and forwarded by the Event Server.

Method of operation

Port used for MIP Message communication

The MIP Environment in the Event Server offers a web service located on default port 22333 (2 numbers higher than the Event Server port number). An application initiates the message communication in another MIP Environment by calling MessageCommunicationManager.Start(EnvironmentManager.Instance.MasterSite.ServerId).

The underlying MIP Environment will go through these steps to build the URL:

The MIP Environment will now establish a slow polling thread to maintain a 2-way communication with a hanging call for receiving messages from the Event Server (and indirectly from other Environments) – and another specific web client for transmitting messages immediately to the Event Server.

Delayed Event Server communication

This section is not relevant anymore, earlier text removed - event server plugin can now initialize MessageCommunication in their Init() method as for all other environments.

Message filtering

Message filters are registered and un-registered by a given MIP plug-in. The registration can be performed immediately after startup, and will be cached in the MessageCommunicationManager class. When the Environment has established the message exchange session with the Event Server it will forward all filters to the event server. The event server will then forward the filters to the relevant other MIP Environments. If, for example, you create a chat application you can listen to your own message id MyApp.ChatLine sent from any one of the other MIP applications. To send a text line, simply issue a TransmitMessage with the above message id and the text line in the content. The Event Server will then forward the same message to all MIP Environments listening to this message, for example a Smart Client having the chat plug-in loaded.

Error handling

Registered filter definitions are cached in the original MIP Environment as well as in the Event Server. This is to assist in re-establishing correct filters in case the MessageCommunication web services are unavailable for a short while.

If the web service session is lost between a MIP Environment client and a given Event Server, an event is fired to notify the application or plug-ins. The following code will setup to get the event from the master site:

_messageCommunication = MessageCommunicationManager.Get(
        EnvironmentManager.Instance.MasterSite.ServerId );
_messageCommunication.ConnectionStateChangedEvent += new
        EventHandler(_messageCommunication_ConnectionStateChangedEvent);

You can now display the state or notify the user, when the event handler is called.

When the session is re-established after a failure, the filters are automatically sent again from the executing MIP Environment to the Event Server, and the Event Server will in turn also re-send all filters it has cached to the executing MIP Environment (when other Environments have registered filters relevant for your application).

Messages being send when the communication web service is down will throw a MIPException for you to handle.

When a message has been sent correctly from one MIP Environment to the Event Server, but the Event Server does not currently have contact to the receiving MIP Environment, the message will be queue up for 60 seconds and transmitted to the receiving end if it comes online within this period.

For making guaranteed delivery communication, another layer of messages should be developed, so all senders will get a sort of “ACK” back from the receiving application.

Multiple Event Servers

When multiple Event Servers are involved, you call the MessageCommunicationManager.Start( serverId ) for each of the servers owning an Event Servers.

Afterwards, there is a MessageCommunication instance handling the communication flow to and from each Event Server. It is accessed through:

_messageCommunication = MessageCommunicationManager.Get( 
        EnvironmentManager.Instance.MasterSite.ServerId );

This class is used for transmitting messages relevant for the applications connected to that Event Server.

The MessageCommunication class also contains an FQID for the Event Server itself, used for sending the built-in messages.

When multiple Event Servers are active at one time, it is possible to receive messages from all Event Servers.

Built-in messages

The following messages assist in getting up and running:

Notice that when new application is logging on both the NewEndPointIndication and the EndPointTableChangedIndication messages will be send, but when an application is logging off, only the EndPointTableChangedIndication is sent.

A sample startup could be:

MessageCommunicationManager.Start(EnvironmentManager.Instance.MasterSite.ServerId);
_messageCommunication = MessageCommunicationManager.Get(EnvironmentManager.Instance.MasterSite.ServerId);
_messageCommunication.ConnectionStateChangedEvent += new
        EventHandler(_messageCommunication_ConnectionStateChangedEvent);
_obj1 = _messageCommunication.RegisterCommunicationFilter(WhoAreOnlineResponseHandler,
          new VideoOS.Platform.Messaging.CommunicationIdFilter(
            MessageCommunication.WhoAreOnlineResponse));
_obj2 = _messageCommunication.RegisterCommunicationFilter(NewEndPointHandler, 
          new VideoOS.Platform.Messaging.CommunicationIdFilter(
            MessageCommunication.NewEndPointIndication));
_obj3 = _messageCommunication.RegisterCommunicationFilter(EndPointTableChangedHandler,
          new VideoOS.Platform.Messaging.CommunicationIdFilter(
            MessageCommunication.EndPointTableChangedIndication));
_obj4 = _messageCommunication.RegisterCommunicationFilter(ChatLineHandler,
          new VideoOS.Platform.Messaging.CommunicationIdFilter(MessageIdChatLine));

EndPoint identification

To be able to send messages to specific applications or plug-ins, each MIP Environment has its own EndPoint FQID. The Event Server’s EndPoint is stored on the MessageCommunication class as ServerEndPointFQID, as it is the server side of the communication web service. While all other MIP Environments has one client FQID located in the MessageCommunicationManager class as EndPointFQID.

In a MIP .Net Library application accessing multiple Event Servers, such as in an MFA architecture, initialize the Message Communication client with the ServerId of the site you want to connect to; be aware that messages cannot flow between different sites.

A BroadcastEndPointFQID is located on the MessageCommunication that can be used for establishing contact.Please use this with care, as it will transmit the Message to all connected MessageCommunication clients.

The EndPointFQIDs are used when transmitting messages and for setting up filters by calling the RegisterCommunicationFilter method.

Security setting

The MessageCommunicationManager has a Security field containing the level of security the MIP Environment is in. The default setting is SecurityLevel.Normal.

The following security levels are defined:

Regardless of the SecurityLevel it is always possible to transmit messages.

Notice that for Smart Client MIP Environment, setting this to SecurityLevel.Low will allow remote applications to control the Smart Client.

MIP Message content

Messages are contained in the ExternalMessage class. It contains fields similar to the Message class used for Environment messaging and is extended with relevant information about EndPoints, e.g. the SourceEndPoint and the SourceEndPointType.

Messages are transmitted in a serialized format. You can define your own classes for containing information to be transmitted as long as all fields can be serialized; the Data field is assigned to a specific class.

Note:
Do not override the ExternalMessage class.

When doing a request/response kind of operation, define one MessageId for the request and another for the response. These need to be sent in two different operations.

Limitations on types allowed in the Message.Data field

No instances of types defined in the Microsoft namespace are allowed to be assigned to the Message.Data field and only the following from the System namespace are allowed:

If a message with a prohibited object is received by the Event Server, the message will be discarded and a log written to the Event Server MIP log.

If you have a plug-in or other integration that is using a prohibited class type, you can create a file named MessageCommunicationSettings.config in the Event Server installation folder, add content similar to the following to it, and restart the Event Server:

<?xml version="1.0" encoding="utf-8" ?>
<MessageCommunicationSettings>
  <AdditionalAllowedTransmitTypes>
    <AdditionalAllowedTransmitType message="MyMessageId" allowedTypes="System.Text.StringBuilder" />
  </AdditionalAllowedTransmitTypes>
</MessageCommunicationSettings>

If multiple types are used with same message id, add them all to allowedTypes separated by semicolon.

Types from plug-in defined namespace are allowed.

Relevant samples

Component integration

Plug-in integration