#region  --------------- Copyright Dresser Wayne Pignone -------------
/*
 * $Log: /Wrk/Support/ForecourtControl/Wrk/ForecourtControl/Com/IPump.cs $
 * 
 * 5     07-02-26 14:06 roger.månsson
 * Added pump Id.
 * 
 * 4     07-02-16 9:59 roger.månsson
 * FxCop changes
 * 
 * 3     07-01-08 16:11 roger.månsson
 * Added support for the SignalEvent/OnEventOccured on the pump
 * interfaces.
 * 
 * 2     07-01-05 9:01 roger.månsson
 * Documentation changes
 */
#endregion

using System.Runtime.InteropServices;
using System.Diagnostics.CodeAnalysis;

namespace Wayne.ForecourtControl.Com
{
    /// <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>
    [ComVisible(true)]
    public interface IPump 
    {
        #region Properties

        /// <summary>
        /// 0 based pump number for this instance.
        /// </summary>
        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>
        [SuppressMessage("Microsoft.Performance", "CA1819:PropertiesShouldNotReturnArrays")]
        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>
        [SuppressMessage("Microsoft.Performance", "CA1819:PropertiesShouldNotReturnArrays")]
        IFuelling[] Fuellings { get;}

        /// <summary>
        /// Idle price group used to calculate the prices to show on the pump when the pump is idle.
        /// When the pump is authorized, the pricegroup is specified again for that fuelling in the 
        /// AuthorizeParameters.
        /// Use method SetPriceGroupAsync to change idle price group.
        /// </summary>
        int 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; }

        #endregion

        #region Methods

        #region Reserve

        /// <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="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void ReserveAsync(FuellingType fuellingType, byte deviceId, object userToken);

        #endregion

        #region Suspend

        /// <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="userToken">User supplied object that will be returned in the suspendCompleted callback.</param>
        void SuspendAsync(object userToken);

        #endregion

        #region Resume

        /// <summary>
        /// Resumes a suspended fuelling
        /// </summary>
        /// <see cref="IPump.SuspendAsync"/>
        /// <param name="userToken">User supplied object that will be returned in the suspendCompleted callback.</param>
        void ResumeAsync(object userToken);

        #endregion

        #region Stop

        /// <summary>
        /// Stops the current activity on the pump.
        /// </summary>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        /// <see cref="IPump.StopAsync"/>
        void StopAsync(object userToken);

        #endregion

        #region SetBlocked

        /// <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="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void SetBlockedAsync(bool blocked, object userToken);

        #endregion

        #region SetPriceGroup

        /// <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="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void SetPriceGroupAsync(int priceGroup, object userToken);

        #endregion

        #region Unreserve
        /// <summary>
        /// Cancel pump reservation asynchronously. When the request is completed, the supplied delegate will be called. 
        /// After a call to this, the reference to the IReseredPump interface may not be used and
        /// should be unreferenced.
        /// </summary>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void UnreserveAsync(object userToken);

        #endregion

        #region Authorize

        /// <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.
        /// </summary>
        /// <see cref="IFuelling.AuthorizationId"/>
        /// <param name="authorizeParameters">Object that describes the rules for the authorization.</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, object userToken);

        #endregion

        #region AuthorizeUpdate

        /// <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.
        /// </summary>
        /// <param name="authorizeParameters">Object that describes the rules for the authorization.</param>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void AuthorizeUpdateAsync(IAuthorizeParameters authorizeParameters, object userToken);

        #endregion

        #region Unauthorize

        /// <summary>
        /// Cancel of a fuelling authorization. This command is only allowed after a successful 
        /// call to <c>Reserve()</c> and <c>Authorize</c>.
        /// This is the asynchronous version of the request, and will call 
        /// the supplied delegate on completion.
        /// </summary>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void UnauthorizeAsync(object userToken);

        #endregion

        #region SignalEvent

        /// <summary>
        /// Signals that something regarding this pump has happened. The event will be signalled to all registered clients
        /// using the OnEventOccured event. When the operation completes, it is signalled through the event OnSignalEventCompleted.
        /// </summary>
        /// <param name="pumpEventType">Type of the event that occured.</param>
        /// <param name="userToken">User token to be returned in the completion event.</param>
        void SignalEventAsync(PumpEventType pumpEventType, object userToken);

        #endregion 

        #endregion


    }
}