XDMessaging 3.0 : Documentation

XDMessaging .Net Library 3.0

Project home

Project downloads

Project documentation

Getting started

The following API is all you need to start broadcasting and receiving messages across application, process and local network boundaries in your .Net application.

XDTransportMode

This defines the implementation to use for broadcasting and receiving messages. There are currently three modes as follows, each with advantages over the other.

IOStream: This uses file based IO to broadcast messages via a shared directory. A FileSystemWatcher is used within listener classes to monitor changes and trigger the MessageReceived event containing the broadcast message. This mode can be used in Windows Services, console applications, and Windows Forms based applications. Channels are created as separate directories on the file system for each channel. The temporary directories should be accessible by all processes, and there should be no need for manual configuration.
WindowsMessaging: This uses the WM_COPYDATA Windows message to copy data between applications. The broadcast implementation sends the Windows messages directly to a hidden window on the listener instance, which dispatches the MessageReceived event with the copied data. Channels are created by adding/removing Windows properties. This offers the most performant solution for Windows Forms based applications, but does not work for Windows Services, console apps, or other applications without a message pump.
MailSlot: This uses a MailSlot to broadcast messages over the local network and interprocess. A limitation of the MailSlot is that only one process may read the message within the scope of a single machine. The library uses a Mutex to synchronize access to the MailSlot across the system, and ensures that when one process terminates another listener can pick up further messages. This mode is used internally to send messages from other transport modes over the local network. Machines must be a member of the same Domain or Workgroup in order to send and receive MailSlot messages. MailSlot are not robust when used over the network and there may be a high drop rate using this implementation.

IXDBroadcast

Use these implementations to broadcast string messages on named channel to other processes. Messages will be received by listeners in the same mode which have registered with the same named channel.

Example: Creating an instance.

// Create an instance of IXDBroadcast using IOStream mode
IXDBroadcast broadcast = XDBroadcast.CreateBroadcast(XDTransportMode.IOStream);

// or create an instance of IXDBroadcast using WindowsMessaging mode
IXDBroadcast broadcast = XDBroadcast.CreateBroadcast(XDTransportMode.WindowsMessaging);

// or create an instance of IXDBroadcast using MailSlot mode
IXDBroadcast broadcast = XDBroadcast.CreateBroadcast(XDTransportMode.MailSlot);

Example: Sending a message.

// Send shutdown message to a channel named commands
broadcast.SendToChannel("commands", "shutdown");

// Send serializable object to a channel named binary1
broadcast.SendToChannel("binary1", new CustomData("Some text"));

Example: Network propagation

Set the optional propagateNetwork parameter to true in order to send messages to listeners on other machines. Network messages are received by all listener instances which are in the same mode and channel as the broadcast instance. For network communication the machines must be on the same Domain or Workgroup.


// create an instance of IXDBroadcast and allow network propagation
IXDBroadcast broadcast = XDBroadcast.CreateBroadcast(XDTransportMode.WindowsMessaging, true);

// Send a message on the commands channel to all listeners on the local network
// which are in WindowsMessaging mode
broadcast.SendToChannel("commands", "doWork");

Example: Multi-broadcast

This example shows how to send messages using multiple modes at the same time.

// create an instance of IXDBroadcast which uses multiple modes
IXDBroadcast broadcast = XDBroadcast.CreateBroadcast(
                               XDTransportMode.WindowsMessaging,
                               XDTransportMode.IOStream);

// Dispatch to all listeners in either modes
broadcast.SendToChannel("commands", "doWork");

IXDListener

Use these implementations to receive events when messages are broadcast from other processes. Events will only occur if the listener is in the same mode as the broadcasting instance, and if it's listening on the same channel.

By default each listener is capable of acting as a system-wide listener for network messages propagated over the network in order that they may be re-distributed to all processes on the same machine. By setting the optional excludeNetworkMessages flag to true the listener will not take part in listening for network messages. With this setting however the instance may still receive network messages that have been re-broadcast by other listeners in the same mode.

Example: Creating an instance.

// Create our listener instance using IOStream mode
IXDListener listener = XDListener.CreateListener(XDTransportMode.IOStream);

// or create our listener using WindowsMessaging mode
IXDListener listener = XDListener.CreateListener(XDTransportMode.WindowsMessaging);

Example: Registering an unregistering channels.

// Register channels to listen on
listener.RegisterChannel("events");
listener.RegisterChannel("status");
listener.RegisterChannel("commands");

// Stop listening on a specific channel
listener.UnRegisterChannel("status");

Example: Handling the MessageReceived event.

// Attach an event handler to a listener instance
listener.MessageReceived+=XDMessageHandler(this.listener_MessageReceived);

// process the message
private void listener_MessageReceived(object sender, XDMessageEventArgs e)
{
    // e.DataGram.Message is the message
    // e.DataGram.Channel is the channel name
    if (e.DataGram.Channel == "commands")
    {
       switch(e.DataGram.Message)
       {
           case "shutdown":
             this.Close();
             break;
       }
    }
}

Example: Handling a serialized messages:

// Attach an event handler to a listener instance
listener.MessageReceived+=XDMessageHandler(this.listener_MessageReceived);
 
// process the message
private void listener_MessageReceived(object sender, XDMessageEventArgs e)
{
 switch(e.DataGram.Channel)
 {
  case "binary1":
      TypedDataGram<CustomData> typedMsg = e.DataGram;
      UserMessage customData = typedMsg.Message;
      // do something with customData
      break;
 }
}

Example: Dispose IXDListener to release resources.

// Create our listener instance using IOStream mode
IXDListener listener = XDListener.CreateListener(XDTransportMode.IOStream);

// when no longer needed ensure it's disposed
// without this the IOStream listener will continue using resources to listen for messages
listener.Dispose();

// create a new instance
listener = XDListener.CreateListener(XDTransportMode.WindowsMessaging);

The Code King