src/lib/adapter/AdapterCommunication.h

   1 #pragma once
   2 /*
   3  * This file is part of the libCEC(R) library.
   4  *
   5  * libCEC(R) is Copyright (C) 2011-2012 Pulse-Eight Limited.  All rights reserved.
   6  * libCEC(R) is an original work, containing original code.
   7  *
   8  * libCEC(R) is a trademark of Pulse-Eight Limited.
   9  *
  10  * This program is dual-licensed; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  23  *
  24  *
  25  * Alternatively, you can license this library under a commercial license,
  26  * please contact Pulse-Eight Licensing for more information.
  27  *
  28  * For more information contact:
  29  * Pulse-Eight Licensing       <license@pulse-eight.com>
  30  *     http://www.pulse-eight.com/
  31  *     http://www.pulse-eight.net/
  32  */
  33
  34 #include "../platform/util/StdString.h"
  35 #include "USBCECAdapterMessage.h"
  36
  37 namespace CEC
  38 {
  39   class CLibCEC;
  40
  41   class IAdapterCommunicationCallback
  42   {
  43   public:
  44     IAdapterCommunicationCallback(void) {}
  45     virtual ~IAdapterCommunicationCallback(void) {}
  46
  47     /*!
  48      * @brief Callback method for IAdapterCommunication, called when a new cec_command is received
  49      * @param command The command that has been received
  50      * @return True when it was handled by this listener, false otherwise.
  51      */
  52     virtual bool OnCommandReceived(const cec_command &command) = 0;
  53
  54     /*!
  55      * @brief Callback method for IAdapterCommunication, called when a poll was received.
  56      * @param initiator The initiator that sent the poll.
  57      * @param destination The destination of the poll message.
  58      */
  59     virtual void HandlePoll(cec_logical_address initiator, cec_logical_address destination) = 0;
  60
  61     /*!
  62      * @brief Callback method for IAdapterCommunication, called when a receive failed message was received.
  63      * @param initiator The initiator that sent the receive failed message.
  64      * @return True when this is an error, false otherwise.
  65      */
  66     virtual bool HandleReceiveFailed(cec_logical_address initiator) = 0;
  67
  68     virtual CLibCEC *GetLib(void) const = 0;
  69   };
  70
  71   class IAdapterCommunication
  72   {
  73   public:
  74     /*!
  75      * @param callback The callback struct. if set to NULL, the Read() method has to be used to read commands. if set, OnCommandReceived() will be called for each command that was received
  76      */
  77     IAdapterCommunication(IAdapterCommunicationCallback *callback) :
  78       m_callback(callback) {}
  79     virtual ~IAdapterCommunication(void) {}
  80
  81     /*!
  82      * @brief Open a connection to the CEC adapter
  83      * @param iTimeoutMs Connection timeout in ms
  84      * @param bSkipChecks Skips all initial checks of the adapter, and starts the reader/writer threads directly after connecting.
  85      * @param bStartListening Start a listener thread when true. False to just open a connection, read the device info, and close the connection.
  86      * @return True when connected, false otherwise
  87      */
  88     virtual bool Open(uint32_t iTimeoutMs = CEC_DEFAULT_CONNECT_TIMEOUT, bool bSkipChecks = false, bool bStartListening = true) = 0;
  89
  90     /*!
  91      * @brief Close an open connection
  92      */
  93     virtual void Close(void) = 0;
  94
  95     /*!
  96      * @return True when the connection is open, false otherwise
  97      */
  98     virtual bool IsOpen(void) = 0;
  99
 100     /*!
 101      * @return The last error message, or an empty string if there was none
 102      */
 103     virtual CStdString GetError(void) const = 0;
 104
 105     /*!
 106      * @brief Write a cec_command to the adapter
 107      * @param data The command to write
 108      * @param bRetry The command can be retried
 109      * @param iLineTimeout The line timeout to be used
 110      * @return The last state of the transmitted command
 111      */
 112     virtual cec_adapter_message_state Write(const cec_command &data, bool &bRetry, uint8_t iLineTimeout = 3) = 0;
 113
 114     /*!
 115      * @brief Change the current line timeout on the CEC bus
 116      * @param iTimeout The new timeout
 117      * @return True when set, false otherwise
 118      */
 119     virtual bool SetLineTimeout(uint8_t iTimeout) = 0;
 120
 121     /*!
 122      * @brief Put the device in bootloader mode (which will disrupt CEC communication when it succeeds)
 123      * @return True when the bootloader command has been sent, false otherwise.
 124      */
 125     virtual bool StartBootloader(void) = 0;
 126
 127     /*!
 128      * @brief Change the ACK-mask of the device, the mask for logical addresses to which the CEC device should ACK
 129      * @param iMask The new mask
 130      * @return True when set, false otherwise.
 131      */
 132     virtual bool SetAckMask(uint16_t iMask) = 0;
 133     virtual uint16_t GetAckMask(void) = 0;
 134
 135     /*!
 136      * @brief Check whether the CEC adapter responds
 137      * @return True when the ping was sent and acked, false otherwise.
 138      */
 139     virtual bool PingAdapter(void) = 0;
 140
 141     /*!
 142      * @return The firmware version of this CEC adapter, or 0 if it's unknown.
 143      */
 144     virtual uint16_t GetFirmwareVersion(void) = 0;
 145
 146     /*!
 147      * @return The build date in seconds since epoch, or 0 when no (valid) reply was received.
 148      */
 149     virtual uint32_t GetFirmwareBuildDate(void) = 0;
 150
 151     /*!
 152      * @return True when this adapter is using the latest firmware build, or when the latest firmware build for this adapter type is unknown. False otherwise.
 153      */
 154     virtual bool IsRunningLatestFirmware(void) = 0;
 155
 156     /*!
 157      * @return True when the control mode has been set, false otherwise.
 158      */
 159     virtual bool SetControlledMode(bool controlled) = 0;
 160
 161     /*!
 162      * @brief Persist the given configuration in adapter (if supported)
 163      * @brief The configuration to store.
 164      * @return True when the configuration was persisted, false otherwise.
 165      */
 166     virtual bool PersistConfiguration(libcec_configuration *configuration) = 0;
 167
 168     /*!
 169      * @brief Get the persisted configuration from the adapter (if supported)
 170      * @param configuration The updated configuration.
 171      * @return True when the configuration was updated, false otherwise.
 172      */
 173     virtual bool GetConfiguration(libcec_configuration *configuration) = 0;
 174
 175     /*!
 176      * @return The name of the port
 177      */
 178     virtual CStdString GetPortName(void) = 0;
 179
 180     /*!
 181      * @return The physical address, if the adapter supports this. 0 otherwise.
 182      */
 183     virtual uint16_t GetPhysicalAddress(void) = 0;
 184
 185     IAdapterCommunicationCallback *m_callback;
 186   };
 187 };