//-----------------------------------------------------------------------
// <copyright file="IPassThruBase.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.Api
{
    /// <summary>
    /// In-between interface to handle different implementations of calls to external DLL:s.
    /// </summary>
    public interface IPassThruBase
    {
        /// <summary>
        /// Implementation of PassThruOpen.
        /// </summary>
        /// <param name="pName">Always 'null'.</param>
        /// <param name="pDeviceID">Pointer to selected device ID. (return value)</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        unsafe PassThruConstants.resultCode PassThruOpen(void* pName, int* pDeviceID);

        /// <summary>
        /// Close the given device.
        /// </summary>
        /// <param name="DeviceID">ID of device to close.</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        PassThruConstants.resultCode PassThruClose(int DeviceID);

        /// <summary>
        /// Establish a connection on the given device.
        /// </summary>
        /// <param name="DeviceID">ID of current device.</param>
        /// <param name="ProtocolID">ID of protocol to use.</param>
        /// <param name="Flags">Connection Flags.</param>
        /// <param name="Baudrate">Baudrate to use for connection.</param>
        /// <param name="pChannelID">Pointer to value for channel id (return value)</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        unsafe PassThruConstants.resultCode PassThruConnect(int DeviceID, int ProtocolID, uint Flags, uint Baudrate, int* pChannelID);

        /// <summary>
        /// Disconnect the given channel.
        /// </summary>
        /// <param name="ChannelID">ID of channel to disconnect.</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        PassThruConstants.resultCode PassThruDisconnect(int ChannelID);

        /// <summary>
        /// Read messages from the given channel.
        /// </summary>
        /// <param name="ChannelID">ID of channel to read from.</param>
        /// <param name="pMsg">Pointer to message(s) read.</param>
        /// <param name="pNumMsgs">Number of messages to read, value set at return to actual number read.</param>
        /// <param name="Timeout">Timeout value before returning with no message read.</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        unsafe PassThruConstants.resultCode PassThruReadMsgs(int ChannelID, PASSTHRU_MSG* pMsg, int* pNumMsgs, int Timeout);

        /// <summary>
        /// Write messages to the given channel.
        /// </summary>
        /// <param name="ChannelID">ID of channel to write to.</param>
        /// <param name="pMsg">Message(s) to write.</param>
        /// <param name="pNumMsgs">Number of messages to write.</param>
        /// <param name="Timeout">Timeout when writing message to out channel.</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        unsafe PassThruConstants.resultCode PassThruWriteMsgs(int ChannelID, PASSTHRU_MSG* pMsg, int* pNumMsgs, int Timeout);

        /// <summary>
        /// Start a periodic message to send from application to vehicle.
        /// </summary>
        /// <param name="ChannelID">ID of channel to write to.</param>
        /// <param name="pMsg">Message(s) to write.</param>
        /// <param name="pMsgID">Return value: ID of message being sent.</param>
        /// <param name="TimeInterval">Interval between each message in milliseconds.</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        unsafe PassThruConstants.resultCode PassThruStartPeriodicMsg(int ChannelID, PASSTHRU_MSG* pMsg, int* pMsgID, int TimeInterval);

        /// <summary>
        /// Stop a periodic message from being sent to the vehicle.
        /// </summary>
        /// <param name="ChannelID">ID of channel to stop message on.</param>
        /// <param name="MsgID">ID of message to stop sending.</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        PassThruConstants.resultCode PassThruStopPeriodicMsg(int ChannelID, int MsgID);

        /// <summary>
        /// Configure a message filter.
        /// </summary>
        /// <param name="ChannelID">Channel to configure filter on.</param>
        /// <param name="FilterType">Type of filter to configure.</param>
        /// <param name="pMaskMsg">Mask message in filter.</param>
        /// <param name="pPatternMsg">Pattern message in filter.</param>
        /// <param name="pFlowControlMsg">Flow control message in filter.</param>
        /// <param name="pMsgID">ID of filter created (out value)</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        unsafe PassThruConstants.resultCode PassThruStartMsgFilter(
            int ChannelID,
            int FilterType,
            PASSTHRU_MSG* pMaskMsg,
            PASSTHRU_MSG* pPatternMsg,
            PASSTHRU_MSG* pFlowControlMsg,
            int* pMsgID);

        /// <summary>
        /// Stop a message filter.
        /// </summary>
        /// <param name="ChannelID">Channel to remove filter from.</param>
        /// <param name="MsgID">ID of filter to remove.</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        PassThruConstants.resultCode PassThruStopMsgFilter(int ChannelID, int MsgID);

        /// <summary>
        /// Configure the programming voltage pin and voltage.
        /// </summary>
        /// <param name="DeviceID">ID of Device to configure.</param>
        /// <param name="Pin">Number of pin to configure.</param>
        /// <param name="Voltage">Voltage to set at pin.</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        PassThruConstants.resultCode PassThruSetProgrammingVoltage(int DeviceID, int Pin, int Voltage);

        /// <summary>
        /// Read API version.
        /// </summary>
        /// <param name="DeviceID">ID to get version information from.</param>
        /// <param name="pFirmwareVersion">Firmware version (return value).</param>
        /// <param name="pDllVersion">DLL version (return value).</param>
        /// <param name="pApiVersion">API version (return value).</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        unsafe PassThruConstants.resultCode PassThruReadVersion(int DeviceID, byte* pFirmwareVersion, byte* pDllVersion, byte* pApiVersion);

        /// <summary>
        /// Get the last error encountered on the device.
        /// </summary>
        /// <param name="pErrorDescription">Pointer to string with error description.</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        unsafe PassThruConstants.resultCode PassThruGetLastError(sbyte* pErrorDescription);

        /// <summary>
        /// Perform IOCTL operation on the device.
        /// </summary>
        /// <param name="ChannelID">ID of channel to perform operation on.</param>
        /// <param name="IoctlID">IOCTL Operation.</param>
        /// <param name="pInput">Input parameter for operation.</param>
        /// <param name="pOutput">Output parameter for operation.</param>
        /// <returns>'0' if success, non-zero if a failure occurred.</returns>
        unsafe PassThruConstants.resultCode PassThruIoctl(
            int ChannelID,
            int IoctlID,
            void* pInput,
            void* pOutput);
    }
}