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 <string>
  35
  36 namespace CEC
  37 {
  38   class CLibCEC;
  39
  40   typedef enum cec_adapter_message_state
  41   {
  42     ADAPTER_MESSAGE_STATE_UNKNOWN = 0,        /**< the initial state */
  43     ADAPTER_MESSAGE_STATE_WAITING_TO_BE_SENT, /**< waiting in the send queue of the adapter, or timed out */
  44     ADAPTER_MESSAGE_STATE_SENT,               /**< sent and waiting on an ACK */
  45     ADAPTER_MESSAGE_STATE_SENT_NOT_ACKED,     /**< sent, but failed to ACK */
  46     ADAPTER_MESSAGE_STATE_SENT_ACKED,         /**< sent, and ACK received */
  47     ADAPTER_MESSAGE_STATE_INCOMING,           /**< received from another device */
  48     ADAPTER_MESSAGE_STATE_ERROR               /**< an error occured */
  49   } cec_adapter_message_state;
  50
  51   class IAdapterCommunicationCallback
  52   {
  53   public:
  54     IAdapterCommunicationCallback(void) {}
  55     virtual ~IAdapterCommunicationCallback(void) {}
  56
  57     /*!
  58      * @brief Callback method for IAdapterCommunication, called when a new cec_command is received
  59      * @param command The command that has been received
  60      * @return True when it was handled by this listener, false otherwise.
  61      */
  62     virtual bool OnCommandReceived(const cec_command &command) = 0;
  63
  64     /*!
  65      * @brief Callback method for IAdapterCommunication, called when a poll was received.
  66      * @param initiator The initiator that sent the poll.
  67      * @param destination The destination of the poll message.
  68      */
  69     virtual void HandlePoll(cec_logical_address initiator, cec_logical_address destination) = 0;
  70
  71     /*!
  72      * @brief Callback method for IAdapterCommunication, called when a receive failed message was received.
  73      * @param initiator The initiator that sent the receive failed message.
  74      * @return True when this is an error, false otherwise.
  75      */
  76     virtual bool HandleReceiveFailed(cec_logical_address initiator) = 0;
  77
  78     /*!
  79      * @brief Callback method for IAdapterCommunication, called when a logical address that libCEC uses was taken by another device.
  80      * @param oldAddress The logical address that was taken by another device.
  81      */
  82     virtual void HandleLogicalAddressLost(cec_logical_address oldAddress) = 0;
  83
  84     virtual CLibCEC *GetLib(void) const = 0;
  85   };
  86
  87   class IAdapterCommunication
  88   {
  89   public:
  90     /*!
  91      * @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
  92      */
  93     IAdapterCommunication(IAdapterCommunicationCallback *callback) :
  94       m_callback(callback) {}
  95     virtual ~IAdapterCommunication(void) {}
  96
  97     /*!
  98      * @brief Open a connection to the CEC adapter
  99      * @param iTimeoutMs Connection timeout in ms
 100      * @param bSkipChecks Skips all initial checks of the adapter, and starts the reader/writer threads directly after connecting.
 101      * @param bStartListening Start a listener thread when true. False to just open a connection, read the device info, and close the connection.
 102      * @return True when connected, false otherwise
 103      */
 104     virtual bool Open(uint32_t iTimeoutMs = CEC_DEFAULT_CONNECT_TIMEOUT, bool bSkipChecks = false, bool bStartListening = true) = 0;
 105
 106     /*!
 107      * @brief Close an open connection
 108      */
 109     virtual void Close(void) = 0;
 110
 111     /*!
 112      * @return True when the connection is open, false otherwise
 113      */
 114     virtual bool IsOpen(void) = 0;
 115
 116     /*!
 117      * @return The last error message, or an empty string if there was none
 118      */
 119     virtual std::string GetError(void) const = 0;
 120
 121     /*!
 122      * @brief Write a cec_command to the adapter
 123      * @param data The command to write
 124      * @param bRetry The command can be retried
 125      * @param iLineTimeout The line timeout to be used
 126      * @param bIsReply True when this message is a reply, false otherwise
 127      * @return The last state of the transmitted command
 128      */
 129     virtual cec_adapter_message_state Write(const cec_command &data, bool &bRetry, uint8_t iLineTimeout, bool bIsReply) = 0;
 130
 131     /*!
 132      * @brief Change the current line timeout on the CEC bus
 133      * @param iTimeout The new timeout
 134      * @return True when set, false otherwise
 135      */
 136     virtual bool SetLineTimeout(uint8_t iTimeout) = 0;
 137
 138     /*!
 139      * @brief Put the device in bootloader mode (which will disrupt CEC communication when it succeeds)
 140      * @return True when the bootloader command has been sent, false otherwise.
 141      */
 142     virtual bool StartBootloader(void) = 0;
 143
 144     virtual bool SetLogicalAddresses(const cec_logical_addresses &addresses) = 0;
 145     virtual cec_logical_addresses GetLogicalAddresses(void) = 0;
 146
 147     /*!
 148      * @brief Check whether the CEC adapter responds
 149      * @return True when the ping was sent and acked, false otherwise.
 150      */
 151     virtual bool PingAdapter(void) = 0;
 152
 153     /*!
 154      * @return The firmware version of this CEC adapter, or 0 if it's unknown.
 155      */
 156     virtual uint16_t GetFirmwareVersion(void) = 0;
 157
 158     /*!
 159      * @return The build date in seconds since epoch, or 0 when no (valid) reply was received.
 160      */
 161     virtual uint32_t GetFirmwareBuildDate(void) = 0;
 162
 163     /*!
 164      * @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.
 165      */
 166     virtual bool IsRunningLatestFirmware(void) = 0;
 167
 168     /*!
 169      * @return True when the control mode has been set, false otherwise.
 170      */
 171     virtual bool SetControlledMode(bool controlled) = 0;
 172
 173     /*!
 174      * @brief Persist the given configuration in adapter (if supported)
 175      * @brief The configuration to store.
 176      * @return True when the configuration was persisted, false otherwise.
 177      */
 178     virtual bool PersistConfiguration(const libcec_configuration &configuration) = 0;
 179
 180     /*!
 181      * @brief Get the persisted configuration from the adapter (if supported)
 182      * @param configuration The updated configuration.
 183      * @return True when the configuration was updated, false otherwise.
 184      */
 185     virtual bool GetConfiguration(libcec_configuration &configuration) = 0;
 186
 187     /*!
 188      * @return The name of the port
 189      */
 190     virtual std::string GetPortName(void) = 0;
 191
 192     /*!
 193      * @return The physical address, if the adapter supports this. 0 otherwise.
 194      */
 195     virtual uint16_t GetPhysicalAddress(void) = 0;
 196
 197     /*!
 198      * @return The vendor id for this device
 199      */
 200     virtual cec_vendor_id GetVendorId(void) = 0;
 201
 202     /*!
 203      * @brief Checks whether a logical address is supported by the adapter.
 204      * @param address The address to check.
 205      * @return True when supported, false otherwise.
 206      */
 207     virtual bool SupportsSourceLogicalAddress(const cec_logical_address address) = 0;
 208
 209     /*!
 210      * @return The type of adapter that this instance is connected to.
 211      */
 212     virtual cec_adapter_type GetAdapterType(void) = 0;
 213
 214     /*!
 215      * @return The (virtual) USB vendor id
 216      */
 217     virtual uint16_t GetAdapterVendorId(void) const = 0;
 218
 219     /*!
 220      * @return The (virtual) USB product id
 221      */
 222     virtual uint16_t GetAdapterProductId(void) const = 0;
 223
 224     /*!
 225      * @brief Marks the adapter as active or inactive source
 226      * @param bSetTo True to mark as active source, false to mark as inactive source
 227      * @param bClientUnregistered True when the client was unregistered, false when the device was explicitly marked as (in)active source
 228      */
 229     virtual void SetActiveSource(bool bSetTo, bool bClientUnregistered) = 0;
 230
 231     IAdapterCommunicationCallback *m_callback;
 232   };
 233 };