#region  --------------- Copyright Dresser Wayne Pignone -------------
/*
 * $Log: /Wrk/Support/ForecourtControl/Wrk/ForecourtControl/IPump.cs $
 *
 * 8     07-05-21 16:28 roger.månsson
 * Added TankLevelSwitchStatus property, and OnTankLevelSwitchStatusChange
 * event.
 *
 * 7     07-02-16 9:59 roger.månsson
 * FxCop changes
 *
 * 6     07-02-02 17:17 roger.månsson
 * Changed so AuthorizeAsync takes IAuthorizeParameters interface instead
 * of class (For COM support). SignalEventAsync uses PumpEventType instead
 * of int.
 *
 * 5     07-01-09 9:28 roger.månsson
 * Documentation fixes
 *
 * 4     07-01-08 16:11 roger.månsson
 * Added support for the SignalEvent/OnEventOccured on the pump
 * interfaces.
 *
 * 3     07-01-08 11:22 roger.månsson
 * Added Id as a "new" parameter, so we can document it better.
 */
#endregion
using System;

namespace Wayne.ForecourtControl
{
    /// <summary>
    /// The IPump interface represents a logical fuel dispenser. It does only contain the methods that can be called
    /// without a pump reservation. When the pump is reserved, the IReservedPump interface is used, with an extended set
    /// of methods.
    /// </summary>
    public interface IPump : Wayne.Lib.IIdentifiableEntity
    {
        #region Properties

        /// <summary>
        /// Pump id, zero based pump number. The pump number that will be displayed is 1-based, so in this
        /// property, pump 1 will have Id 0.
        /// </summary>
        new int Id { get;}

        /// <summary>
        /// State of the pump.
        /// </summary>
        PumpState State { get;}

        /// <summary>
        /// Indicates if a valid fuel grade has been selected. Operation may be restricted
        /// by <c>CapFuelGradeSelected</c> for pump protocols not supporting this feature.
        /// </summary>
        bool FuelGradeSelected { get;}

        /// <summary>
        /// 0 if not reserved.
        /// If reserved then this contains the ClientId of the application that has reserved it (using <c>Reserve</c> command).
        /// </summary>
        int ReservedBy { get;}

        /// <summary>
        /// An array with Nozzles connected to this pump.
        /// </summary>
        System.Collections.ObjectModel.ReadOnlyCollection<INozzle> Nozzles { get;}

        /// <summary>
        /// Enable continous updates on the CurrentFuelling information during a fuelling. Events will be fired on OnFuellingDataChange
        /// when the filling data has changed, and current fuelling will be updated.
        /// </summary>
        bool RunningFuellingUpdates { get;set;}

        /// <summary>
        /// The running fuelling object. this should reflect what is shown on the pump display.
        /// </summary>
        IFuelling CurrentFuelling { get;}

        /// <summary>
        /// Fuelling collection holding the fuellings availiable for payment.
        /// </summary>
        System.Collections.ObjectModel.ReadOnlyCollection<IFuelling> Fuellings { get;}

        /// <summary>
        /// Price group that should be used to calculate the fuelling price.
        /// It will aslo set the unit price(s) present when the pump is idle.
        /// use SetPriceGroup to change the property.
        /// </summary>
        PriceGroup PriceGroup { get;}

        /// <summary>
        /// True if Suspend/Resume commands are supported by the pump/protocol.
        /// </summary>
        bool CapSuspendFuelling { get;}

        /// <summary>
        /// True if the pump light on/off command is supported by the pump/protocol.
        /// </summary>
        bool CapSetLight { get;}

        /// <summary>
        /// True if pump protocol is capable to report nozzle in/out
        /// </summary>
        bool CapNozzleDetection { get;}

        /// <summary>
        /// Indicates if the pump is capable to supply information when a fuel grade is selected.
        /// </summary>
        bool CapFuelGradeSelected { get;}

        /// <summary>
        /// Indicates if the pump is online to on the link.
        /// </summary>
        bool Connected { get;}

        /// <summary>
        /// Indicates if the pump is open.
        /// </summary>
        bool Open { get;}

        /// <summary>
        /// Indicates if the pump is blocked by a client
        /// </summary>
        bool Blocked { get; }

        /// <summary>
        /// Indicates the status of a low tank level switch. If no tank level switch exists on the pump or if no information has been received from it, the
        /// status is 'unknown'.
        /// </summary>
        TankLevelSwitchStatus TankLevelSwitchStatus { get;}

        #endregion

        #region Methods

        /// <summary>
        /// Async version of Reserve() <see cref="IPump.ReserveAsync"/>
        /// </summary>
        /// <param name="deviceId">The Device id that the pump will be reserved for. For example
        /// the terminal number if it is reserved for a specific terminal.</param>
        /// <param name="fuellingType">The fuelling type that the pump will be reserved for.</param>
        /// <param name="reservedCompleted"></param>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures")]
        void ReserveAsync(FuellingType fuellingType, byte deviceId, EventHandler<Wayne.Lib.AsyncCompletedEventArgs> reservedCompleted, object userToken);

        /// <summary>
        /// Cancel pump reservation asynchronously. The reservation allows the the reservation owner to authorize the pump.
        /// </summary>
        /// <param name="requestCompleted">Delegate that will be called after completion of the request.</param>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void UnreserveAsync(EventHandler<Wayne.Lib.AsyncCompletedEventArgs> requestCompleted, object userToken);

        /// <summary>
        /// This command temporary suspends a running fuelling i.e. stops the pump motors.
        /// It may be possible to continue the fuelling again when teh <c>Resume</c> command is
        /// called but not all pump modles support Suspend / Resume handling. In this case
        /// the fuelling will be stopped without any possibility to resume operation.
        /// </summary>
        /// <param name="suspendCompleted">Callback delegate that is called on completion.</param>
        /// <param name="userToken">User supplied object that will be returned in the suspendCompleted callback.</param>
        void SuspendAsync(EventHandler<Wayne.Lib.AsyncCompletedEventArgs> suspendCompleted, object userToken);

        /// <summary>
        /// Resumes a suspended fuelling
        /// </summary>
        /// <see cref="IPump.SuspendAsync"/>
        /// <param name="resumeCompleted">Callback delegate that is called on completion.</param>
        /// <param name="userToken">User supplied object that will be returned in the suspendCompleted callback.</param>
        void ResumeAsync(EventHandler<Wayne.Lib.AsyncCompletedEventArgs> resumeCompleted, object userToken);

        /// <summary>
        /// Stops the current activity on the pump.
        /// </summary>
        /// <param name="requestCompleted">Delegate that gets called when operation is completed.</param>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        /// <see cref="IPump.StopAsync"/>
        void StopAsync(EventHandler<Wayne.Lib.AsyncCompletedEventArgs> requestCompleted, object userToken);

        /// <summary>
        /// Blocks or unblocks a pump for operation.
        /// </summary>
        /// <param name="blocked">True if the pump should be blocked, and false if it should be unblocked.</param>
        /// <param name="requestCompleted">Delegate that gets called when operation is completed</param>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void SetBlockedAsync(bool blocked, EventHandler<Wayne.Lib.AsyncCompletedEventArgs> requestCompleted, object userToken);

        /// <summary>
        /// Sets the Idle price group for the pump. This is the price group that will be used to calculate the fuelprice
        /// that is shown on the pump display.
        /// </summary>
        /// <param name="priceGroup"></param>
        /// <param name="requestCompleted">Delegate that gets called when operation is completed</param>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void SetPriceGroupAsync(PriceGroup priceGroup, EventHandler<Wayne.Lib.AsyncCompletedEventArgs> requestCompleted, object userToken);

        /// <summary>
        /// Authorize pump for fuelling.
        /// The supplied AuthoriseParameters object contains the volume amount and grade restrictions of the
        /// release. The AsyncCompletedEventArgs will also contain a result (long) that will contain the AuthorizationId
        /// for the authorization. This can be matched with the IFuelling.AuthorizationId when the fuelling is running or
        /// is finished. This method may only be called when the pump is successfully reserved.
        /// </summary>
        /// <see cref="IFuelling.AuthorizationId"/>
        /// <param name="authorizeParameters">Object that describes the rules for the authorization.</param>
        /// <param name="requestCompleted">Delegate that will be called after completion of the request.</param>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures")]
        void AuthorizeAsync(IAuthorizeParameters authorizeParameters, EventHandler<Wayne.Lib.AsyncCompletedEventArgs<long>> requestCompleted, object userToken);

        /// <summary>
        /// Update of the limits for an already authorised pump. This is the asynchronous version of the request, and will call
        /// the supplied delegate on completion. This method may only be called when the pump is successfully reserved.
        /// </summary>
        /// <param name="authorizeParameters">Object that describes the rules for the authorization.</param>
        /// <param name="requestCompleted">Delegate that will be called after completion of the request.</param>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void AuthorizeUpdateAsync(IAuthorizeParameters authorizeParameters, EventHandler<Wayne.Lib.AsyncCompletedEventArgs> requestCompleted, object userToken);

        /// <summary>
        /// Cancel of a fuelling authorization.
        /// This is the asynchronous version of the request, and will call
        /// the supplied delegate on completion. This method may only be called when the pump is successfully reserved.
        /// </summary>
        /// <param name="requestCompleted">Delegate that will be called after completion of the request.</param>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void UnauthorizeAsync(EventHandler<Wayne.Lib.AsyncCompletedEventArgs> requestCompleted, object userToken);

        /// <summary>
        /// Signals that something regarding this pump has happened. The event will be signalled to all registered clients
        /// using the OnEventOccured event.
        /// </summary>
        /// <param name="eventType"></param>
        /// <param name="signalEventCompleted"></param>
        /// <param name="userToken"></param>
        void SignalEventAsync(PumpEventType eventType, EventHandler<Wayne.Lib.AsyncCompletedEventArgs> signalEventCompleted, object userToken);

        string ToString();
        #endregion

        #region Events

        /// <summary>
        /// Fired when a pump state is changed
        /// </summary>
        event EventHandler<PumpStateChangeEventArgs> OnStateChange;

        /// <summary>
        /// Fired when a Nozzle has been hooked in or out. Returns a handle to itself. Event firing is dependent on CapNozzleDetection
        /// </summary>
        event EventHandler<NozzleStateChangeEventArgs> OnNozzleStateChange;

        /// <summary>
        /// Fired when a fuelling is running and the volume and amount values has changed.
        /// </summary>
        event EventHandler<FuellingDataChangeEventArgs> OnFuellingDataChange;

        /// <summary>
        /// Fired when the state or reservation of a fuelling has changed. Returns a handle affected fuelling.
        /// </summary>
        event EventHandler<FuellingStateChangeEventArgs> OnFuellingStateChange;

        /// <summary>
        /// Event that is fired when a client has signalled an event using the SignalEventAsync method or from inside the forecourt
        /// controller.
        /// </summary>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1704:IdentifiersShouldBeSpelledCorrectly", MessageId = "Occured")]
        event EventHandler<PumpEventOccuredEventArgs> OnEventOccured;

        /// <summary>
        /// Event that is fired when the status of the tank level switch has changed.
        /// </summary>
        event EventHandler<TankLevelSwitchStatusChangeEventArgs> OnTankLevelSwitchStatusChange;

        #endregion
    }
}