//-----------------------------------------------------------------------
// <copyright file="IProtocolHandler.cs" company="bedug.com">
//     Copyright © 2012 Nils Hammar. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
/*
 * Software to access vehicle information via the OBD-II connector.
 * 
 * Copyright © 2012 Nils Hammar
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 * 
 * Alternative licensing is possible, see the licensing document.
 * 
 * The above text may not be removed or modified.
 */

namespace SharedObjects.Protocol
{
    using global::SharedObjects.Api;
    using global::SharedObjects.Protocol.OBD;

    /// <summary>
    /// Definition of methods that each protocol handler shall implement.
    /// <para>
    /// Notice: This is still under development.
    /// </para>
    /// </summary>
    public interface IProtocolHandler
    {
        /// <summary>
        /// Gets source address value.
        /// </summary>
        uint srcAddr { get; }

        /// <summary>
        /// Gets Current protocol.
        /// </summary>
        Protocols protocol { get; }

        /// <summary>
        /// Initialize the protocol if necessary.
        /// </summary>
        /// <param name="txFlags">TX Flags for any messages that are created during initialization.</param>
        void init(int txFlags);

        /// <summary>
        /// Start protocol services if necessary.
        /// </summary>
        void start();

        /// <summary>
        /// Stop any running protocol services.
        /// </summary>
        void stopProtocol();

        /// <summary>
        /// Send a probe message.
        /// </summary>
        /// <param name="srcAddr">Source address (address of tester).</param>
        /// <param name="txFlags">TX Flags.</param>
        /// <param name="payload">Payload data.</param>
        void sendProbeMessage(uint srcAddr, int txFlags, byte[] payload);

        /// <summary>
        /// Compose according to protocol and send one message.
        /// </summary>
        /// <param name="senderAddrValue">'Our' address, used in some cases.</param>
        /// <param name="receiverAddrValue">Target address.</param>
        /// <param name="txFlags">Flags to add to message.</param>
        /// <param name="payload">The data to send.</param>
        /// <returns>Error text if there was an error.</returns>
        string sendMessage(
            uint senderAddrValue,
            uint receiverAddrValue,
            int txFlags,
            byte[] payload);

        /// <summary>
        /// Set address on message according to protocol rules.
        /// <para>
        /// Notice that not all protocols uses both from and to address.
        /// </para>
        /// </summary>
        /// <param name="msg">Message to set address on.</param>
        /// <param name="fromAddress">From address to set.</param>
        /// <param name="toAddress">To address to set.</param>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1045:DoNotPassTypesByReference", MessageId = "0#", Justification = "Reviewed, intentional.")]
        void setAddress(ref IPassThruMsg msg, uint fromAddress, uint toAddress);

        /// <summary>
        /// Set the address(es) of the message.
        /// <para>
        /// This is a fully composed address, usually used by filters.
        /// </para>
        /// </summary>
        /// <param name="txmsg">Message to set data in.</param>
        /// <param name="address">Combined Address.</param>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1045:DoNotPassTypesByReference", MessageId = "0#", Justification = "Reviewed, intentional.")]
        void setAddress(ref IPassThruMsg txmsg, uint address);

        /// <summary>
        /// Set additional header data.
        /// <para>
        /// Notice that not all protocols supports this.
        /// If the protocol doesn't support this no modifications shall
        /// occur of the message and the function shall return silently.
        /// </para>
        /// </summary>
        /// <param name="msg">Message to set data on.</param>
        /// <param name="size">Size to set.</param>
        /// <param name="functionalTargetAddressing">'true' if functional addressing is used. (depends on protocol)</param>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1045:DoNotPassTypesByReference", MessageId = "0#", Justification = "Reviewed, intentional.")]
        void setHeader(ref IPassThruMsg msg, uint size, bool functionalTargetAddressing);

        /// <summary>
        /// Add a mode parser.
        /// </summary>
        /// <param name="modeParser">Parser instance to add.</param>
        void addModeParser(IModeParser modeParser);
        
        /// <summary>
        /// Remove a mode parser.
        /// </summary>
        /// <param name="modeParser">Parser instance to remove.</param>
        void removeModeParser(IModeParser modeParser);
        
        /// <summary>
        /// Check if protocol supports 29 bit addressing.
        /// </summary>
        /// <returns>'true' if protocol supports 29 bit addressing.</returns>
        bool is29bit();
    }
}