#region  --------------- Copyright Dresser Wayne Pignone -------------
/*
 * $Log: /Wrk/Support/ForecourtControl/Wrk/ForecourtControl/Com/IFuelling.cs $
 * 
 * 4     07-02-27 12:35 roger.månsson
 * Set decimal MarshalAs Currency to be better compliant with COM.
 * 
 * 3     07-01-05 15:14 roger.månsson
 * Added PumpAccumulator property
 * 
 * 2     07-01-05 9:01 roger.månsson
 * Documentation changes
 */
#endregion
using System;
using System.Runtime.InteropServices;

namespace Wayne.ForecourtControl.Com
{
    /// <summary>
    /// Represents a fuelling. It provides properties to display Amount, Volume and so on for a fuelling. It does
    /// also give the possibilities to change the state of the fuelling and eventually get it removed when it is paid.
    /// </summary>
    [System.Runtime.InteropServices.ComVisible(true)]
    public interface IFuelling
    {
        #region Properties
        /// <summary>
        /// Fuelling sequence number is a unique number created for ever 
        /// completed fuelling. Begins to count from 1 at system cold-start
        /// </summary>
        int FuellingSequenceNumber { get;}

        /// <summary>
        /// Reference to the owning pump.
        /// </summary>
        IPump Pump { get;}

        /// <summary>
        /// The Nozzle object on which this fuelling was made
        /// </summary>
        INozzle Nozzle { get;}

        /// <summary>
        /// 0 if not reserved,  else it contains the ClientId of the application 
        /// that has reserved the fuelling.
        /// </summary>
        int ReservedBy { get;}

        /// <summary>
        /// State of the fuelling.
        /// </summary>
        FuellingState State { get;}

        /// <summary>
        /// Type of fuelling.
        /// </summary>
        FuellingType Type { get;}

        /// <summary>
        /// Filled volume
        /// </summary>
        decimal Quantity { [return:MarshalAs( UnmanagedType.Currency)] get;}

        /// <summary>
        /// Filled amount in domestic currency value.
        /// </summary>
        decimal Amount { [return: MarshalAs(UnmanagedType.Currency)]get;}

        /// <summary>
        /// Preset value when the fuelling was released.
        /// </summary>
        decimal PresetValue { [return: MarshalAs(UnmanagedType.Currency)]get;}

        /// <summary>
        /// Specifies if PresetValue is Amount or Volume.
        /// </summary>
        PresetType PresetType { get;}

        /// <summary>
        /// Price used for the fuelling in domestic currency value.
        /// </summary>
        decimal Price { [return: MarshalAs(UnmanagedType.Currency)]get;}

        /// <summary>
        /// The date time of when the fuelling was completed.
        /// </summary>
        DateTime CompletionDateTime { get;}

        /// <summary>
        /// A status code indicating what caused ending of the fuelling.
        /// <list type="bullet">
        /// <item>0=Ok</item>
        /// <item>1=Timeout</item>
        /// <item>2=BNT Timeout</item>
        /// <item>3=Disconnected</item>
        /// <item>4=BNT disconnected</item>
        /// <item>5=Stopped</item>
        /// <item>6=Volume or amount decreased</item>
        /// <item>7=Pulser error</item>
        /// <item>8=Pulser current error</item>
        /// <item>9=Zero fuelling</item>
        /// <item>10=No decimals set</item>
        /// <item>11=Price error</item>
        /// <item>12=Volume or amuont garbage</item>
        /// <item>13=Display error</item>
        /// <item>14=Checksum error</item>
        /// </list>
        /// </summary>
        int CompletionReason { get;}

        /// <summary>
        /// Fuel grade used.
        /// </summary>
        int FuelGrade { get;}

        /// <summary>
        /// PriceGroup used.
        /// </summary>
        int PriceGroup { get;}

        /// <summary>
        /// The Fuel period that the fuelling belongs to.
        /// </summary>
        int FuelPeriodId { get;}

        /// <summary>
        /// An identifiaction of the authorization that is originally returned in the 
        /// async callback for the IReservePump.AuthorizeAsync. It is used to match the 
        /// authorization with the fuelling completion.
        /// </summary>
        int AuthorizationId { get;}

        /// <summary>
        /// Pump accumulator read after completed fuelling. May be null if pump accumulator reading not is supported.
        /// </summary>
        IPumpAccumulatorReading PumpAccumulator { get;}

        #endregion

        #region Methods

        #region Reserve
        /// <summary>
        /// Reserves the fuelling for exclusive use. When the fuelling is successfully reserved, the ReservedBy property will
        /// be set to the ClientId of the reserving client.
        /// </summary>
        /// <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(object userToken);

        #endregion

        #region UnreserveAsync
        /// <summary>
        /// Cancel fuelling lock. 
        /// </summary>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void UnreserveAsync(object userToken);

        #endregion

        #region Transfer

        /// <summary>
        /// Changes the state of the fuelling to Transferred. 
        /// If the fuelling is not already reserved, that is done implicitly, and must succeed before the 
        /// transfer can succeed.
        /// </summary>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void TransferAsync(object userToken);

        #endregion

        #region UndoTransfer

        /// <summary>
        /// Rolls back the transfer and unreserves the fuelling.
        /// </summary>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void UndoTransferAsync(object userToken);

        #endregion

        #region SetAsPaid

        /// <summary>
        /// Sets the fuelling to paid state, which means that it will no longer will be availiable in the Fuellings array.
        /// </summary>
        /// <param name="userToken">A user supplied object that will be returned in the requestCompleted callback</param>
        void SetAsPaidAsync(object userToken);

        #endregion

        #endregion
    }
}