Introduction

The messaging system provides an application-wide available service for message exchange.

It is provided by a small generic API which attends a simple messaging concept. The basic idea is that the message broker maintains several named message channels, where each channel can be seen like a thread in a newsgroup or forum, where messages of a special topic are sent. Messages are sent in such channels and received by clients synchronously or asynchronously.

I will first describe the very general message broker interface and the classes of the public messaging API. After that, in the usage section, I will present patterns for defining, sending and receiving messages; those patterns should be used throughout the application.

General concepts and message broker API

Message channels

Message channels categorize messages sent in the MP2 system. Each message channel transfers messages of a special topic. For example, there are message channels for the WorkflowManager, the PlayerManager, the PlayerContextManager and so on. Via each channel, messages of several finer-grained types are sent, for example the player manager sends different messages for status updates via its player manager message channel, for example the change of a player slot controller.

Each message channel transmits all of its messages in order. They can be fetched by creating special message queue instances or, in exceptional cases, by directly registering at the message broker.

SystemMessage

Messages being sent through the system are of type SystemMessage, which has those public members:

public class SystemMessage
{
  // Protected fields

  public SystemMessage(object messageType)
  {
    ...
  }

  public object MessageType
  {
    get { ... }
  }

  public string ChannelName
  {
    get { ... }
    set { ... }
  }

  public IDictionary<string, object> MessageData
  {
    get { ... }
    set { ... }
  }
}

Each message stores the name of the channel where it is being sent in its ChannelName property. Messages have a message type of an arbitrary .net type, typically they will be typed by an enum which is channel specific and declared in the messaging class. Furthermore, each message instance can have additional MessageData, a simple dictionary which holds key/value pairs.

IMessageBroker

The message broker is a very simple interface which looks like this:

public interface IMessageBroker
{
  void RegisterMessageReceiver(string channel, IMessageReceiver receiver);
  void UnregisterMessageReceiver(string channel, IMessageReceiver receiver);
  void Send(string channelName, SystemMessage msg);
}

Message senders create message objects of type SystemMessage and put those messages into such a channel by calling the method IMessageBroker.Send, passing the channel name and the message instance which should be sent.

Message receivers will typically NOT register themselves via RegisterMessageReceiver, they will typically use an AsynchronousMessageQueue.

Message receivers

To receive messages, clients need to register a message queue at the message broker. The most common message queue is the AsynchronousMessageQueue which provides a secure, asynchronous communication.

There also exists an implementation of a synchronous message queue which can be used in exceptional cases, but with restrictions.

When you absolutely know what you do, it is even possible to register at the message broker interface itself, but be aware that a missuse of the messaging subsystem might significantly reduce the system quality.

Asynchronous message queue

The AsynchronousMessageQueue is the default way of receiving messages. Internally, this kind of message queue puts each received message into a private queue which is processed by an own asynchronous thread. That assures all requirements which are drawn by the contract of the IMessageBroker interface:

• It doens't block the system
• The message reception is fast

To receive messages via an asynchronous message queue, the client itself instantiates the queue, passes all interesting message channel names to it, registers a .net event handler for receiving the asynchronous messages and then it starts the queue. The asynchronous message queue also provides a .net event handler to "preview" events which are pushed into the queue; note that this message preview only may be done used with message handlers, which DON'T acquire locks. See the MP2 multithreading guideline for an explanation.

The code docs of the AsynchronousMessageQueue class provide more details.

Synchronous message queue

The SynchronousMessageQueue can be used in cases where a synchronous message reception is needed. It is strongly recommended that you use asynchronous message queues because they make much less trouble than synchronous message queues. When using synchronous message queues, make sure to follow all requirements which are stated by the contract of the SynchronousMessageQueue (formulated in the class docs). At the current development time, there is not a single user of a synchronous message queue and we'll try to avoid every such usage.

Usage of the messaging system

There is a quite strict pattern how to use the messaging system.

Message senders

To be continued. Until this section is written, see the class PlayerManagerMessaging and its clients in the MediaPortal.UI project.

Message receivers

To be continued. Until this section is written, see the class PlayerManagerMessaging and its clients in the MediaPortal.UI project.