PageRenderTime 24ms CodeModel.GetById 12ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 0ms

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

#
C# | 232 lines | 32 code | 14 blank | 186 comment | 0 complexity | 1f7d65d21637d95115a100ec889dfeed MD5 | raw file
  1// **************************************************************************
  2// <copyright file="IMessenger.cs" company="GalaSoft Laurent Bugnion">
  3// Copyright © GalaSoft Laurent Bugnion 2009-2011
  4// </copyright>
  5// ****************************************************************************
  6// <author>Laurent Bugnion</author>
  7// <email>laurent@galasoft.ch</email>
  8// <date>23.9.2009</date>
  9// <project>GalaSoft.MvvmLight.Messaging</project>
 10// <web>http://www.galasoft.ch</web>
 11// <license>
 12// See license.txt in this project or http://www.galasoft.ch/license_MIT.txt
 13// </license>
 14// ****************************************************************************
 15
 16using System;
 17using System.Diagnostics.CodeAnalysis;
 18
 19////using GalaSoft.Utilities.Attributes;
 20
 21namespace CBR.Core.Helpers
 22{
 23    /// <summary>
 24    /// The Messenger is a class allowing objects to exchange messages.
 25    /// </summary>
 26    ////[ClassInfo(typeof(Messenger))]
 27    public interface IMessenger
 28    {
 29        /// <summary>
 30        /// Registers a recipient for a type of message TMessage. The action
 31        /// parameter will be executed when a corresponding message is sent.
 32        /// <para>Registering a recipient does not create a hard reference to it,
 33        /// so if this recipient is deleted, no memory leak is caused.</para>
 34        /// </summary>
 35        /// <typeparam name="TMessage">The type of message that the recipient registers
 36        /// for.</typeparam>
 37        /// <param name="recipient">The recipient that will receive the messages.</param>
 38        /// <param name="action">The action that will be executed when a message
 39        /// of type TMessage is sent.</param>
 40        void Register<TMessage>(object recipient, Action<TMessage> action);
 41
 42        /// <summary>
 43        /// Registers a recipient for a type of message TMessage.
 44        /// The action parameter will be executed when a corresponding 
 45        /// message is sent. See the receiveDerivedMessagesToo parameter
 46        /// for details on how messages deriving from TMessage (or, if TMessage is an interface,
 47        /// messages implementing TMessage) can be received too.
 48        /// <para>Registering a recipient does not create a hard reference to it,
 49        /// so if this recipient is deleted, no memory leak is caused.</para>
 50        /// </summary>
 51        /// <typeparam name="TMessage">The type of message that the recipient registers
 52        /// for.</typeparam>
 53        /// <param name="recipient">The recipient that will receive the messages.</param>
 54        /// <param name="token">A token for a messaging channel. If a recipient registers
 55        /// using a token, and a sender sends a message using the same token, then this
 56        /// message will be delivered to the recipient. Other recipients who did not
 57        /// use a token when registering (or who used a different token) will not
 58        /// get the message. Similarly, messages sent without any token, or with a different
 59        /// token, will not be delivered to that recipient.</param>
 60        /// <param name="action">The action that will be executed when a message
 61        /// of type TMessage is sent.</param>
 62        void Register<TMessage>(object recipient, object token, Action<TMessage> action);
 63
 64        /// <summary>
 65        /// Registers a recipient for a type of message TMessage.
 66        /// The action parameter will be executed when a corresponding 
 67        /// message is sent. See the receiveDerivedMessagesToo parameter
 68        /// for details on how messages deriving from TMessage (or, if TMessage is an interface,
 69        /// messages implementing TMessage) can be received too.
 70        /// <para>Registering a recipient does not create a hard reference to it,
 71        /// so if this recipient is deleted, no memory leak is caused.</para>
 72        /// </summary>
 73        /// <typeparam name="TMessage">The type of message that the recipient registers
 74        /// for.</typeparam>
 75        /// <param name="recipient">The recipient that will receive the messages.</param>
 76        /// <param name="token">A token for a messaging channel. If a recipient registers
 77        /// using a token, and a sender sends a message using the same token, then this
 78        /// message will be delivered to the recipient. Other recipients who did not
 79        /// use a token when registering (or who used a different token) will not
 80        /// get the message. Similarly, messages sent without any token, or with a different
 81        /// token, will not be delivered to that recipient.</param>
 82        /// <param name="receiveDerivedMessagesToo">If true, message types deriving from
 83        /// TMessage will also be transmitted to the recipient. For example, if a SendOrderMessage
 84        /// and an ExecuteOrderMessage derive from OrderMessage, registering for OrderMessage
 85        /// and setting receiveDerivedMessagesToo to true will send SendOrderMessage
 86        /// and ExecuteOrderMessage to the recipient that registered.
 87        /// <para>Also, if TMessage is an interface, message types implementing TMessage will also be
 88        /// transmitted to the recipient. For example, if a SendOrderMessage
 89        /// and an ExecuteOrderMessage implement IOrderMessage, registering for IOrderMessage
 90        /// and setting receiveDerivedMessagesToo to true will send SendOrderMessage
 91        /// and ExecuteOrderMessage to the recipient that registered.</para>
 92        /// </param>
 93        /// <param name="action">The action that will be executed when a message
 94        /// of type TMessage is sent.</param>
 95        void Register<TMessage>(object recipient, object token, bool receiveDerivedMessagesToo, Action<TMessage> action);
 96
 97        /// <summary>
 98        /// Registers a recipient for a type of message TMessage.
 99        /// The action parameter will be executed when a corresponding 
100        /// message is sent. See the receiveDerivedMessagesToo parameter
101        /// for details on how messages deriving from TMessage (or, if TMessage is an interface,
102        /// messages implementing TMessage) can be received too.
103        /// <para>Registering a recipient does not create a hard reference to it,
104        /// so if this recipient is deleted, no memory leak is caused.</para>
105        /// </summary>
106        /// <typeparam name="TMessage">The type of message that the recipient registers
107        /// for.</typeparam>
108        /// <param name="recipient">The recipient that will receive the messages.</param>
109        /// <param name="receiveDerivedMessagesToo">If true, message types deriving from
110        /// TMessage will also be transmitted to the recipient. For example, if a SendOrderMessage
111        /// and an ExecuteOrderMessage derive from OrderMessage, registering for OrderMessage
112        /// and setting receiveDerivedMessagesToo to true will send SendOrderMessage
113        /// and ExecuteOrderMessage to the recipient that registered.
114        /// <para>Also, if TMessage is an interface, message types implementing TMessage will also be
115        /// transmitted to the recipient. For example, if a SendOrderMessage
116        /// and an ExecuteOrderMessage implement IOrderMessage, registering for IOrderMessage
117        /// and setting receiveDerivedMessagesToo to true will send SendOrderMessage
118        /// and ExecuteOrderMessage to the recipient that registered.</para>
119        /// </param>
120        /// <param name="action">The action that will be executed when a message
121        /// of type TMessage is sent.</param>
122        void Register<TMessage>(object recipient, bool receiveDerivedMessagesToo, Action<TMessage> action);
123
124        /// <summary>
125        /// Sends a message to registered recipients. The message will
126        /// reach all recipients that registered for this message type
127        /// using one of the Register methods.
128        /// </summary>
129        /// <typeparam name="TMessage">The type of message that will be sent.</typeparam>
130        /// <param name="message">The message to send to registered recipients.</param>
131        void Send<TMessage>(TMessage message);
132
133        /// <summary>
134        /// Sends a message to registered recipients. The message will
135        /// reach only recipients that registered for this message type
136        /// using one of the Register methods, and that are
137        /// of the targetType.
138        /// </summary>
139        /// <typeparam name="TMessage">The type of message that will be sent.</typeparam>
140        /// <typeparam name="TTarget">The type of recipients that will receive
141        /// the message. The message won't be sent to recipients of another type.</typeparam>
142        /// <param name="message">The message to send to registered recipients.</param>
143        [SuppressMessage(
144            "Microsoft.Design",
145            "CA1004:GenericMethodsShouldProvideTypeParameter",
146            Justification = "This syntax is more convenient than other alternatives.")]
147        void Send<TMessage, TTarget>(TMessage message);
148
149        /// <summary>
150        /// Sends a message to registered recipients. The message will
151        /// reach only recipients that registered for this message type
152        /// using one of the Register methods, and that are
153        /// of the targetType.
154        /// </summary>
155        /// <typeparam name="TMessage">The type of message that will be sent.</typeparam>
156        /// <param name="message">The message to send to registered recipients.</param>
157        /// <param name="token">A token for a messaging channel. If a recipient registers
158        /// using a token, and a sender sends a message using the same token, then this
159        /// message will be delivered to the recipient. Other recipients who did not
160        /// use a token when registering (or who used a different token) will not
161        /// get the message. Similarly, messages sent without any token, or with a different
162        /// token, will not be delivered to that recipient.</param>
163        void Send<TMessage>(TMessage message, object token);
164
165        /// <summary>
166        /// Unregisters a messager recipient completely. After this method
167        /// is executed, the recipient will not receive any messages anymore.
168        /// </summary>
169        /// <param name="recipient">The recipient that must be unregistered.</param>
170        void Unregister(object recipient);
171
172        /// <summary>
173        /// Unregisters a message recipient for a given type of messages only. 
174        /// After this method is executed, the recipient will not receive messages
175        /// of type TMessage anymore, but will still receive other message types (if it
176        /// registered for them previously).
177        /// </summary>
178        /// <typeparam name="TMessage">The type of messages that the recipient wants
179        /// to unregister from.</typeparam>
180        /// <param name="recipient">The recipient that must be unregistered.</param>
181        [SuppressMessage(
182            "Microsoft.Design",
183            "CA1004:GenericMethodsShouldProvideTypeParameter",
184            Justification = "This syntax is more convenient than other alternatives.")]
185        void Unregister<TMessage>(object recipient);
186
187        /// <summary>
188        /// Unregisters a message recipient for a given type of messages only and for a given token. 
189        /// After this method is executed, the recipient will not receive messages
190        /// of type TMessage anymore with the given token, but will still receive other message types
191        /// or messages with other tokens (if it registered for them previously).
192        /// </summary>
193        /// <param name="recipient">The recipient that must be unregistered.</param>
194        /// <param name="token">The token for which the recipient must be unregistered.</param>
195        /// <typeparam name="TMessage">The type of messages that the recipient wants
196        /// to unregister from.</typeparam>
197        [SuppressMessage(
198            "Microsoft.Design",
199            "CA1004:GenericMethodsShouldProvideTypeParameter",
200            Justification = "This syntax is more convenient than other alternatives.")]
201        void Unregister<TMessage>(object recipient, object token);
202
203        /// <summary>
204        /// Unregisters a message recipient for a given type of messages and for
205        /// a given action. Other message types will still be transmitted to the
206        /// recipient (if it registered for them previously). Other actions that have
207        /// been registered for the message type TMessage and for the given recipient (if
208        /// available) will also remain available.
209        /// </summary>
210        /// <typeparam name="TMessage">The type of messages that the recipient wants
211        /// to unregister from.</typeparam>
212        /// <param name="recipient">The recipient that must be unregistered.</param>
213        /// <param name="action">The action that must be unregistered for
214        /// the recipient and for the message type TMessage.</param>
215        void Unregister<TMessage>(object recipient, Action<TMessage> action);
216
217        /// <summary>
218        /// Unregisters a message recipient for a given type of messages, for
219        /// a given action and a given token. Other message types will still be transmitted to the
220        /// recipient (if it registered for them previously). Other actions that have
221        /// been registered for the message type TMessage, for the given recipient and other tokens (if
222        /// available) will also remain available.
223        /// </summary>
224        /// <typeparam name="TMessage">The type of messages that the recipient wants
225        /// to unregister from.</typeparam>
226        /// <param name="recipient">The recipient that must be unregistered.</param>
227        /// <param name="token">The token for which the recipient must be unregistered.</param>
228        /// <param name="action">The action that must be unregistered for
229        /// the recipient and for the message type TMessage.</param>
230        void Unregister<TMessage>(object recipient, object token, Action<TMessage> action);
231    }
232}