Org.Lwes/Listener/IEventSink.cs

   1 //
   2 // This file is part of the LWES .NET Binding (LWES.net)
   3 //
   4 // COPYRIGHT© 2009, Phillip Clark (phillip[at*flitbit[dot*org)
   5 //       original .NET implementation
   6 //
   7 // LWES.net is free software: you can redistribute it and/or modify
   8 // it under the terms of the Lesser GNU General Public License as published by
   9 // the Free Software Foundation, either version 3 of the License, or
  10 // (at your option) any later version.
  11 //
  12 // LWES.net is distributed in the hope that it will be useful,
  13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 // Lesser GNU General Public License for more details.
  16 //
  17 // You should have received a copy of the Lesser GNU General Public License
  18 // along with LWES.net.  If not, see <http://www.gnu.org/licenses/>.
  19 //
  20 namespace Org.Lwes.Listener
  21 {
  22         using System.Net;
  23
  24         /// <summary>
  25         /// Interface for event sinks that handle events received by the event listeners.
  26         /// </summary>
  27         public interface IEventSink
  28         {
  29                 /// <summary>
  30                 /// Indicates whether the event sink is thread-safe.
  31                 /// </summary>
  32                 /// <remarks>A sink is thread-safe if BOTH HandleEventArrival and HandleGarbageData
  33                 /// can be called multiple times concurrently without failure.</remarks>
  34                 bool IsThreadSafe
  35                 {
  36                         get;
  37                 }
  38
  39                 /// <summary>
  40                 /// Callback method invoked by event listeners when LWES events arrive.
  41                 /// </summary>
  42                 /// <param name="key">Registration key for controlling the registration and status of
  43                 /// an event sink</param>
  44                 /// <param name="ev">a newly arrived LWES event</param>
  45                 void HandleEventArrival(IEventSinkRegistrationKey key, Event ev);
  46
  47                 /// <summary>
  48                 /// Callback method invoked by event listeners when garbage data arrives on an endpoint.
  49                 /// </summary>
  50                 /// <param name="key">Registration key for controlling the registration and status of
  51                 /// an event sink</param>
  52                 /// <param name="remoteEndPoint">endpoint that sent the garbage data</param>
  53                 /// <param name="priorGarbageCountForEndpoint">number of times garbage data has arrived from the
  54                 /// endpoint</param>
  55                 /// <param name="garbage">byte array containing the garbage</param>
  56                 /// <returns>a vote as to how future traffic from the endpoint should be handled -- possible values are:
  57                 /// { None | TreatTrafficFromEndpointAsGarbage | IgnoreAllTrafficFromEndpoint }</returns>
  58                 /// <remarks>
  59                 /// <para>Whether a listener invokes garbage handling on the event sinks is dictated by the listner's
  60                 /// garbage handling setting --  { <em>FailSilently</em> | <em>IgnoreEndpointsThatSendGarbage</em> | <em>AskEventSinksToVoteOnStrategy</em> }.</para>
  61                 /// <para>If the listener's garbage handling setting is <em>AskEventSinksToVoteOnStrategy</em> then the
  62                 /// the event sinks are asked to vote.</para>
  63                 /// <para>Votes are recorded on a per-remote endpoint basis. Upon Each active sink
  64                 /// is given a copy of the garbage data and the listener records the sink's vote. The most
  65                 /// restrictive vote dictates the future data handling for the remote endpoint.</para></remarks>
  66                 GarbageHandlingVote HandleGarbageData(IEventSinkRegistrationKey key, EndPoint remoteEndPoint, int priorGarbageCountForEndpoint, byte[] garbage);
  67         }
  68 }