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
  36 namespace CEC
  37 {
  38   typedef enum cec_adapter_message_state
  39   {
  40     ADAPTER_MESSAGE_STATE_UNKNOWN = 0,          /**< the initial state */
  41     ADAPTER_MESSAGE_STATE_WAITING_TO_BE_SENT,   /**< waiting in the send queue of the adapter, or timed out */
  42     ADAPTER_MESSAGE_STATE_SENT,                 /**< sent and waiting on an ACK */
  43     ADAPTER_MESSAGE_STATE_SENT_NOT_ACKED,       /**< sent, but failed to ACK */
  44     ADAPTER_MESSAGE_STATE_SENT_ACKED,           /**< sent, and ACK received */
  45     ADAPTER_MESSAGE_STATE_INCOMING,             /**< received from another device */
  46     ADAPTER_MESSAGE_STATE_ERROR                 /**< an error occured */
  47   } cec_adapter_message_state;
  48
  49   class IAdapterCommunicationCallback
  50   {
  51   public:
  52     IAdapterCommunicationCallback(void) {}
  53     virtual ~IAdapterCommunicationCallback(void) {}
  54
  55     /*!
  56      * @brief Callback method for IAdapterCommunication, called when a new cec_command is received
  57      * @param command The command that has been received
  58      * @return True when it was handled by this listener, false otherwise.
  59      */
  60     virtual bool OnCommandReceived(const cec_command &command) = 0;
  61   };
  62
  63   class IAdapterCommunication
  64   {
  65   public:
  66     IAdapterCommunication(void) {}
  67     virtual ~IAdapterCommunication(void) {}
  68
  69     /*!
  70      * @brief Open a connection to the CEC adapter
  71      * @param cb 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
  72      * @param iTimeoutMs Connection timeout in ms
  73      * @param bSkipChecks Skips all initial checks of the adapter, and starts the reader/writer threads directly after connecting.
  74      * @param bStartListening Start a listener thread when true. False to just open a connection, read the device info, and close the connection.
  75      * @return True when connected, false otherwise
  76      */
  77     virtual bool Open(IAdapterCommunicationCallback *cb, uint32_t iTimeoutMs = 10000, bool bSkipChecks = false, bool bStartListening = true) = 0;
  78
  79     /*!
  80      * @brief Close an open connection
  81      */
  82     virtual void Close(void) = 0;
  83
  84     /*!
  85      * @return True when the connection is open, false otherwise
  86      */
  87     virtual bool IsOpen(void) = 0;
  88
  89     /*!
  90      * @return The last error message, or an empty string if there was none
  91      */
  92     virtual CStdString GetError(void) const = 0;
  93
  94     /*!
  95      * @brief Reads one cec_command from the adapter
  96      * @param command The command that will be read (output)
  97      * @param iTimeout The read timeout
  98      * @return True when a command has been read, false otherwise.
  99      */
 100     virtual bool Read(cec_command &command, uint32_t iTimeout) = 0;
 101
 102     /*!
 103      * @brief Write a cec_command to the adapter
 104      * @param data The command to write
 105      * @param iMaxTries The maximum number of tries
 106      * @param iLineTimeout The line timeout for the first try
 107      * @param iRetryLineTimeout The line timeout for each next try
 108      * @return The last state of the transmitted command
 109      */
 110     virtual cec_adapter_message_state Write(const cec_command &data, uint8_t iMaxTries, uint8_t iLineTimeout = 3, uint8_t iRetryLineTimeout = 3) = 0;
 111
 112     /*!
 113      * @brief Change the current line timeout on the CEC bus
 114      * @param iTimeout The new timeout
 115      * @return True when set, false otherwise
 116      */
 117     virtual bool SetLineTimeout(uint8_t iTimeout) = 0;
 118
 119     /*!
 120      * @brief Put the device in bootloader mode (which will disrupt CEC communication when it succeeds)
 121      * @return True when the bootloader command has been sent, false otherwise.
 122      */
 123     virtual bool StartBootloader(void) = 0;
 124
 125     /*!
 126      * @brief Change the ACK-mask of the device, the mask for logical addresses to which the CEC device should ACK
 127      * @param iMask The new mask
 128      * @return True when set, false otherwise.
 129      */
 130     virtual bool SetAckMask(uint16_t iMask) = 0;
 131
 132     /*!
 133      * @brief Check whether the CEC adapter responds
 134      * @return True when the ping was sent and acked, false otherwise.
 135      */
 136     virtual bool PingAdapter(void) = 0;
 137
 138     /*!
 139      * @return The firmware version of this CEC adapter, or 0 if it's unknown.
 140      */
 141     virtual uint16_t GetFirmwareVersion(void) = 0;
 142
 143     /*!
 144      * @return True when the control mode has been set, false otherwise.
 145      */
 146     virtual bool SetControlledMode(bool controlled) = 0;
 147
 148     /*!
 149      * @brief Persist the given configuration in adapter (if supported)
 150      * @brief The configuration to store.
 151      * @return True when the configuration was persisted, false otherwise.
 152      */
 153     virtual bool PersistConfiguration(libcec_configuration *configuration) = 0;
 154
 155     /*!
 156      * @brief Get the persisted configuration from the adapter (if supported)
 157      * @param configuration The updated configuration.
 158      * @return True when the configuration was updated, false otherwise.
 159      */
 160     virtual bool GetConfiguration(libcec_configuration *configuration) = 0;
 161
 162     /*!
 163      * @return The name of the port
 164      */
 165     virtual CStdString GetPortName(void) = 0;
 166
 167     /*!
 168      * @return The physical address, if the adapter supports this. 0 otherwise.
 169      */
 170     virtual uint16_t GetPhysicalAddress(void) = 0;
 171   };
 172 };