/CBR/CBR.Core/Helpers/MVVM/Events/IMessenger.cs

// **************************************************************************

// <copyright file="IMessenger.cs" company="GalaSoft Laurent Bugnion">

// Copyright © GalaSoft Laurent Bugnion 2009-2011

// </copyright>

// ****************************************************************************

// <author>Laurent Bugnion</author>

// <email>laurent@galasoft.ch</email>

// <date>23.9.2009</date>

// <project>GalaSoft.MvvmLight.Messaging</project>

// <web>http://www.galasoft.ch</web>

// <license>

// See license.txt in this project or http://www.galasoft.ch/license_MIT.txt

// </license>

// ****************************************************************************



using System;

using System.Diagnostics.CodeAnalysis;



////using GalaSoft.Utilities.Attributes;



namespace CBR.Core.Helpers

{

    /// <summary>

    /// The Messenger is a class allowing objects to exchange messages.

    /// </summary>

    ////[ClassInfo(typeof(Messenger))]

    public interface IMessenger

    {

        /// <summary>

        /// Registers a recipient for a type of message TMessage. The action

        /// parameter will be executed when a corresponding message is sent.

        /// <para>Registering a recipient does not create a hard reference to it,

        /// so if this recipient is deleted, no memory leak is caused.</para>

        /// </summary>

        /// <typeparam name="TMessage">The type of message that the recipient registers

        /// for.</typeparam>

        /// <param name="recipient">The recipient that will receive the messages.</param>

        /// <param name="action">The action that will be executed when a message

        /// of type TMessage is sent.</param>

        void Register<TMessage>(object recipient, Action<TMessage> action);



        /// <summary>

        /// Registers a recipient for a type of message TMessage.

        /// The action parameter will be executed when a corresponding 

        /// message is sent. See the receiveDerivedMessagesToo parameter

        /// for details on how messages deriving from TMessage (or, if TMessage is an interface,

        /// messages implementing TMessage) can be received too.

        /// <para>Registering a recipient does not create a hard reference to it,

        /// so if this recipient is deleted, no memory leak is caused.</para>

        /// </summary>

        /// <typeparam name="TMessage">The type of message that the recipient registers

        /// for.</typeparam>

        /// <param name="recipient">The recipient that will receive the messages.</param>

        /// <param name="token">A token for a messaging channel. If a recipient registers

        /// using a token, and a sender sends a message using the same token, then this

        /// message will be delivered to the recipient. Other recipients who did not

        /// use a token when registering (or who used a different token) will not

        /// get the message. Similarly, messages sent without any token, or with a different

        /// token, will not be delivered to that recipient.</param>

        /// <param name="action">The action that will be executed when a message

        /// of type TMessage is sent.</param>

        void Register<TMessage>(object recipient, object token, Action<TMessage> action);



        /// <summary>

        /// Registers a recipient for a type of message TMessage.

        /// The action parameter will be executed when a corresponding 

        /// message is sent. See the receiveDerivedMessagesToo parameter

        /// for details on how messages deriving from TMessage (or, if TMessage is an interface,

        /// messages implementing TMessage) can be received too.

        /// <para>Registering a recipient does not create a hard reference to it,

        /// so if this recipient is deleted, no memory leak is caused.</para>

        /// </summary>

        /// <typeparam name="TMessage">The type of message that the recipient registers

        /// for.</typeparam>

        /// <param name="recipient">The recipient that will receive the messages.</param>

        /// <param name="token">A token for a messaging channel. If a recipient registers

        /// using a token, and a sender sends a message using the same token, then this

        /// message will be delivered to the recipient. Other recipients who did not

        /// use a token when registering (or who used a different token) will not

        /// get the message. Similarly, messages sent without any token, or with a different

        /// token, will not be delivered to that recipient.</param>

        /// <param name="receiveDerivedMessagesToo">If true, message types deriving from

        /// TMessage will also be transmitted to the recipient. For example, if a SendOrderMessage

        /// and an ExecuteOrderMessage derive from OrderMessage, registering for OrderMessage

        /// and setting receiveDerivedMessagesToo to true will send SendOrderMessage

        /// and ExecuteOrderMessage to the recipient that registered.

        /// <para>Also, if TMessage is an interface, message types implementing TMessage will also be

        /// transmitted to the recipient. For example, if a SendOrderMessage

        /// and an ExecuteOrderMessage implement IOrderMessage, registering for IOrderMessage

        /// and setting receiveDerivedMessagesToo to true will send SendOrderMessage

        /// and ExecuteOrderMessage to the recipient that registered.</para>

        /// </param>

        /// <param name="action">The action that will be executed when a message

        /// of type TMessage is sent.</param>

        void Register<TMessage>(object recipient, object token, bool receiveDerivedMessagesToo, Action<TMessage> action);



        /// <summary>

        /// Registers a recipient for a type of message TMessage.

        /// The action parameter will be executed when a corresponding 

        /// message is sent. See the receiveDerivedMessagesToo parameter

        /// for details on how messages deriving from TMessage (or, if TMessage is an interface,

        /// messages implementing TMessage) can be received too.

        /// <para>Registering a recipient does not create a hard reference to it,

        /// so if this recipient is deleted, no memory leak is caused.</para>

        /// </summary>

        /// <typeparam name="TMessage">The type of message that the recipient registers

        /// for.</typeparam>

        /// <param name="recipient">The recipient that will receive the messages.</param>

        /// <param name="receiveDerivedMessagesToo">If true, message types deriving from

        /// TMessage will also be transmitted to the recipient. For example, if a SendOrderMessage

        /// and an ExecuteOrderMessage derive from OrderMessage, registering for OrderMessage

        /// and setting receiveDerivedMessagesToo to true will send SendOrderMessage

        /// and ExecuteOrderMessage to the recipient that registered.

        /// <para>Also, if TMessage is an interface, message types implementing TMessage will also be

        /// transmitted to the recipient. For example, if a SendOrderMessage

        /// and an ExecuteOrderMessage implement IOrderMessage, registering for IOrderMessage

        /// and setting receiveDerivedMessagesToo to true will send SendOrderMessage

        /// and ExecuteOrderMessage to the recipient that registered.</para>

        /// </param>

        /// <param name="action">The action that will be executed when a message

        /// of type TMessage is sent.</param>

        void Register<TMessage>(object recipient, bool receiveDerivedMessagesToo, Action<TMessage> action);



        /// <summary>

        /// Sends a message to registered recipients. The message will

        /// reach all recipients that registered for this message type

        /// using one of the Register methods.

        /// </summary>

        /// <typeparam name="TMessage">The type of message that will be sent.</typeparam>

        /// <param name="message">The message to send to registered recipients.</param>

        void Send<TMessage>(TMessage message);



        /// <summary>

        /// Sends a message to registered recipients. The message will

        /// reach only recipients that registered for this message type

        /// using one of the Register methods, and that are

        /// of the targetType.

        /// </summary>

        /// <typeparam name="TMessage">The type of message that will be sent.</typeparam>

        /// <typeparam name="TTarget">The type of recipients that will receive

        /// the message. The message won't be sent to recipients of another type.</typeparam>

        /// <param name="message">The message to send to registered recipients.</param>

        [SuppressMessage(

            "Microsoft.Design",

            "CA1004:GenericMethodsShouldProvideTypeParameter",

            Justification = "This syntax is more convenient than other alternatives.")]

        void Send<TMessage, TTarget>(TMessage message);



        /// <summary>

        /// Sends a message to registered recipients. The message will

        /// reach only recipients that registered for this message type

        /// using one of the Register methods, and that are

        /// of the targetType.

        /// </summary>

        /// <typeparam name="TMessage">The type of message that will be sent.</typeparam>

        /// <param name="message">The message to send to registered recipients.</param>

        /// <param name="token">A token for a messaging channel. If a recipient registers

        /// using a token, and a sender sends a message using the same token, then this

        /// message will be delivered to the recipient. Other recipients who did not

        /// use a token when registering (or who used a different token) will not

        /// get the message. Similarly, messages sent without any token, or with a different

        /// token, will not be delivered to that recipient.</param>

        void Send<TMessage>(TMessage message, object token);



        /// <summary>

        /// Unregisters a messager recipient completely. After this method

        /// is executed, the recipient will not receive any messages anymore.

        /// </summary>

        /// <param name="recipient">The recipient that must be unregistered.</param>

        void Unregister(object recipient);



        /// <summary>

        /// Unregisters a message recipient for a given type of messages only. 

        /// After this method is executed, the recipient will not receive messages

        /// of type TMessage anymore, but will still receive other message types (if it

        /// registered for them previously).

        /// </summary>

        /// <typeparam name="TMessage">The type of messages that the recipient wants

        /// to unregister from.</typeparam>

        /// <param name="recipient">The recipient that must be unregistered.</param>

        [SuppressMessage(

            "Microsoft.Design",

            "CA1004:GenericMethodsShouldProvideTypeParameter",

            Justification = "This syntax is more convenient than other alternatives.")]

        void Unregister<TMessage>(object recipient);



        /// <summary>

        /// Unregisters a message recipient for a given type of messages only and for a given token. 

        /// After this method is executed, the recipient will not receive messages

        /// of type TMessage anymore with the given token, but will still receive other message types

        /// or messages with other tokens (if it registered for them previously).

        /// </summary>

        /// <param name="recipient">The recipient that must be unregistered.</param>

        /// <param name="token">The token for which the recipient must be unregistered.</param>

        /// <typeparam name="TMessage">The type of messages that the recipient wants

        /// to unregister from.</typeparam>

        [SuppressMessage(

            "Microsoft.Design",

            "CA1004:GenericMethodsShouldProvideTypeParameter",

            Justification = "This syntax is more convenient than other alternatives.")]

        void Unregister<TMessage>(object recipient, object token);



        /// <summary>

        /// Unregisters a message recipient for a given type of messages and for

        /// a given action. Other message types will still be transmitted to the

        /// recipient (if it registered for them previously). Other actions that have

        /// been registered for the message type TMessage and for the given recipient (if

        /// available) will also remain available.

        /// </summary>

        /// <typeparam name="TMessage">The type of messages that the recipient wants

        /// to unregister from.</typeparam>

        /// <param name="recipient">The recipient that must be unregistered.</param>

        /// <param name="action">The action that must be unregistered for

        /// the recipient and for the message type TMessage.</param>

        void Unregister<TMessage>(object recipient, Action<TMessage> action);



        /// <summary>

        /// Unregisters a message recipient for a given type of messages, for

        /// a given action and a given token. Other message types will still be transmitted to the

        /// recipient (if it registered for them previously). Other actions that have

        /// been registered for the message type TMessage, for the given recipient and other tokens (if

        /// available) will also remain available.

        /// </summary>

        /// <typeparam name="TMessage">The type of messages that the recipient wants

        /// to unregister from.</typeparam>

        /// <param name="recipient">The recipient that must be unregistered.</param>

        /// <param name="token">The token for which the recipient must be unregistered.</param>

        /// <param name="action">The action that must be unregistered for

        /// the recipient and for the message type TMessage.</param>

        void Unregister<TMessage>(object recipient, object token, Action<TMessage> action);

    }

}