cec: updated documentation for CBCecMenuStateChanged because we can't suppress displa...

[deb_libcec.git] / include / cectypes.h

diff --git a/include/cectypes.h b/include/cectypes.h
index 95ab891d3fcc3d031e0a5b424d044fca93af790e..c1cc1af89c2b9989af09e5878eb228d419a320da 100644 (file)
--- a/include/cectypes.h
+++ b/include/cectypes.h
@@ -82,6 +82,7 @@ namespace CEC {
 #define CEC_DEFAULT_SETTING_SHUTDOWN_ON_STANDBY   0
 #define CEC_DEFAULT_SETTING_SEND_INACTIVE_SOURCE  1
 #define CEC_DEFAULT_SETTING_POWER_OFF_DEVICES_STANDBY 1
+#define CEC_DEFAULT_DEVICE_LANGUAGE "eng"
 
 #define CEC_DEFAULT_TRANSMIT_RETRY_WAIT 500
 #define CEC_DEFAULT_TRANSMIT_TIMEOUT    1000
@@ -646,7 +647,7 @@ typedef enum cec_vendor_id
 
 typedef struct cec_menu_language
 {
-  char                language[4]; /**< the iso language code */
+  char                language[4]; /**< the iso language code. @bug the language code is only 3 chars long, not 4. will be changed in v2.0, because changing it now would break backwards compat */
   cec_logical_address device;      /**< the logical address of the device */
 } cec_menu_language;
 
@@ -1016,7 +1017,8 @@ typedef struct cec_logical_addresses
 
 typedef enum libcec_alert
 {
-  CEC_ALERT_SERVICE_DEVICE
+  CEC_ALERT_SERVICE_DEVICE,
+  CEC_ALERT_CONNECTION_LOST
 } libcec_alert;
 
 typedef enum libcec_parameter_type
@@ -1037,6 +1039,7 @@ typedef int (CEC_CDECL* CBCecKeyPressType)(void *param, const cec_keypress &);
 typedef int (CEC_CDECL* CBCecCommandType)(void *param, const cec_command &);
 typedef int (CEC_CDECL* CBCecConfigurationChangedType)(void *param, const libcec_configuration &);
 typedef int (CEC_CDECL* CBCecAlertType)(void *param, const libcec_alert, const libcec_parameter &);
+typedef int (CEC_CDECL* CBCecMenuStateChangedType)(void *param, const cec_menu_state newVal);
 
 typedef struct ICECCallbacks
 {
@@ -1075,6 +1078,32 @@ typedef struct ICECCallbacks
    * @return 1 when ok, 0 otherwise
    */
   CBCecAlertType CBCecAlert;
+
+  /*!
+   * @brief Transfer a menu state change to the client.
+   * Transfer a menu state change to the client. If the command returns 1, then the change will be processed by
+   * the busdevice. If 0, then the state of the busdevice won't be changed, and will always be kept 'activated',
+   * @warning CEC does not allow the player to suppress the menu state change on the TV, so the menu on the TV will always be displayed, whatever the return value of this method is.
+   * so keypresses are always routed.
+   * @param newVal The new value.
+   * @return 1 when libCEC should use this new value, 0 otherwise.
+   */
+  CBCecMenuStateChangedType CBCecMenuStateChanged;
+
+#ifdef __cplusplus
+   ICECCallbacks(void) { Clear(); }
+  ~ICECCallbacks(void) { Clear(); };
+
+  void Clear(void)
+  {
+    CBCecLogMessage           = NULL;
+    CBCecKeyPress             = NULL;
+    CBCecCommand              = NULL;
+    CBCecConfigurationChanged = NULL;
+    CBCecAlert                = NULL;
+    CBCecMenuStateChanged     = NULL;
+  }
+#endif
 } ICECCallbacks;
 
 typedef enum cec_client_version
@@ -1085,7 +1114,8 @@ typedef enum cec_client_version
   CEC_CLIENT_VERSION_1_5_2   = 0x1502,
   CEC_CLIENT_VERSION_1_5_3   = 0x1503,
   CEC_CLIENT_VERSION_1_6_0   = 0x1600,
-  CEC_CLIENT_VERSION_1_6_1   = 0x1601
+  CEC_CLIENT_VERSION_1_6_1   = 0x1601,
+  CEC_CLIENT_VERSION_1_6_2   = 0x1602
 } cec_client_version;
 
 typedef enum cec_server_version
@@ -1096,7 +1126,8 @@ typedef enum cec_server_version
   CEC_SERVER_VERSION_1_5_2   = 0x1502,
   CEC_SERVER_VERSION_1_5_3   = 0x1503,
   CEC_SERVER_VERSION_1_6_0   = 0x1600,
-  CEC_SERVER_VERSION_1_6_1   = 0x1601
+  CEC_SERVER_VERSION_1_6_1   = 0x1601,
+  CEC_SERVER_VERSION_1_6_2   = 0x1602
 } cec_server_version;
 
 typedef struct libcec_configuration
@@ -1129,8 +1160,12 @@ typedef struct libcec_configuration
   uint16_t              iFirmwareVersion;     /*!< the firmware version of the adapter. added in 1.6.0 */
   uint8_t               bPowerOffDevicesOnStandby; /*!< put devices in standby when the PC/player is put in standby. added in 1.6.0 */
   uint8_t               bShutdownOnStandby;   /*!< shutdown this PC when the TV is switched off. only used when bPowerOffOnStandby = 0. added in 1.6.0 */
+  char                  strDeviceLanguage[3]; /*!< the menu language used by the client. 3 character ISO 639-2 country code. see http://http://www.loc.gov/standards/iso639-2/ */
 
 #ifdef __cplusplus
+   libcec_configuration(void) { Clear(); }
+  ~libcec_configuration(void) { Clear(); }
+
   /*!
    * @brief Reset this configution struct to the default values.
    */
@@ -1164,6 +1199,7 @@ typedef struct libcec_configuration
     logicalAddresses.Clear();
     iFirmwareVersion          = CEC_FW_VERSION_UNKNOWN;
     bPowerOffDevicesOnStandby = CEC_DEFAULT_SETTING_POWER_OFF_DEVICES_STANDBY;
+    memcpy(strDeviceLanguage, CEC_DEFAULT_DEVICE_LANGUAGE, 3);
 
     callbackParam    = NULL;
     callbacks        = NULL;