include/routing/IAmRoutingReceive.h

   1 /**\r
   2  * Copyright (C) 2012, BMW AG\r
   3  *\r
   4  * This file is part of GENIVI Project AudioManager.\r
   5  *\r
   6  * Contributions are licensed to the GENIVI Alliance under one or more\r
   7  * Contribution License Agreements.\r
   8  *\r
   9  * \copyright\r
  10  * This Source Code Form is subject to the terms of the\r
  11  * Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed with\r
  12  * this file, You can obtain one at http://mozilla.org/MPL/2.0/.\r
  13  *\r
  14  *\r
  15  * \author Christian Mueller, christian.linke@bmw.de BMW 2011,2012\r
  16  *\r
  17  * \file\r
  18  * For further information see http://www.genivi.org/.\r
  19  *\r
  20  * THIS CODE HAS BEEN GENERATED BY ENTERPRISE ARCHITECT GENIVI MODEL. PLEASE CHANGE ONLY IN ENTERPRISE ARCHITECT AND GENERATE AGAIN\r
  21  */\r
  22 #if !defined(EA_B7A11CC8_9777_4421_8677_D9CE084D5E2B__INCLUDED_)\r
  23 #define EA_B7A11CC8_9777_4421_8677_D9CE084D5E2B__INCLUDED_\r
  24 \r
  25 #include <vector>\r
  26 #include <string>\r
  27 #include "audiomanagertypes.h"\r
  28 \r
  29 namespace am {\r
  30 class CAmDbusWrapper;\r
  31 class CAmSocketHandler;\r
  32 }\r
  33
  34
  35 #include "audiomanagertypes.h"
  36
  37 #define RoutingReceiveVersion "2.0"
  38 namespace am {
  39         /**
  40          * Routing Receive sendInterface description. This class implements everything from RoutingAdapter -> Audiomanager
  41          * There are two rules that have to be kept in mind when implementing against this interface:\n
  42          * \warning
  43          * 1. CALLS TO THIS INTERFACE ARE NOT THREAD SAFE !!!! \n
  44          * 2. YOU MAY NOT CALL THE CALLING INTERFACE DURING AN SYNCHRONOUS OR ASYNCHRONOUS CALL THAT EXPECTS A RETURN VALUE.\n
  45          * \details
  46          * Violation these rules may lead to unexpected behavior! Nevertheless you can implement thread safe by using the deferred-
  47          * call pattern described on the wiki which also helps to implement calls that are forbidden.\n
  48          * For more information, please check CAmSerializer
  49          * @author Christian Mueller
  50          * @created 17-Jan-2013 10:00:25
  51          */
  52         class IAmRoutingReceive
  53         {
  54
  55         public:
  56                 IAmRoutingReceive() {
  57
  58                 }
  59
  60                 virtual ~IAmRoutingReceive() {
  61
  62                 }
  63
  64                 /**
  65                  * This function returns the version of the interface
  66                  *
  67                  * @param version    retrieves the verison of the interface
  68                  */
  69                 virtual void  getInterfaceVersion(std::string& version) const =0;
  70                 /**
  71                  * acknowledges a asyncConnect
  72                  *
  73                  * @param handle
  74                  * @param connectionID
  75                  * @param error    E_OK on success, E_ABORTED if action was aborted, E_UNKNOWN on error
  76                  */
  77                 virtual void ackConnect(const am_Handle_s handle, const am_connectionID_t connectionID, const am_Error_e error) =0;
  78                 /**
  79                  * acknowledges a asyncDisconnect
  80                  *
  81                  * @param handle
  82                  * @param connectionID
  83                  * @param error    E_OK on success, E_ABORTED if action was aborted, E_UNKNOWN on error
  84                  */
  85                 virtual void ackDisconnect(const am_Handle_s handle, const am_connectionID_t connectionID, const am_Error_e error) =0;
  86                 /**
  87                  * acknowledges a asyncsetSinkVolume
  88                  *
  89                  * @param handle
  90                  * @param volume    The current actual value that is set
  91                  * @param error    E_OK on success, E_ABORTED if action was aborted, E_UNKNOWN on error
  92                  */
  93                 virtual void ackSetSinkVolumeChange(const am_Handle_s handle, const am_volume_t volume, const am_Error_e error) =0;
  94                 /**
  95                  * acknowledges a asyncsetSourceVolume
  96                  *
  97                  * @param handle    handle that belongs to the change
  98                  * @param volume    the current volume
  99                  * @param error    E_OK on success, E_ABORTED if action was aborted, E_UNKNOWN on error
 100                  */
 101                 virtual void ackSetSourceVolumeChange(const am_Handle_s handle, const am_volume_t volume, const am_Error_e error) =0;
 102                 /**
 103                  * acknowlegde for asyncSetSourceState
 104                  *
 105                  * @param handle
 106                  * @param error    E_OK on success, E_ABORTED if action was aborted, E_UNKNOWN on error
 107                  */
 108                 virtual void ackSetSourceState(const am_Handle_s handle, const am_Error_e error) =0;
 109                 /**
 110                  * acknowledges asyncSetSinkSoundProperties
 111                  *
 112                  * @param handle
 113                  * @param error    E_OK on success, E_ABORTED if action was aborted, E_UNKNOWN on error
 114                  */
 115                 virtual void ackSetSinkSoundProperties(const am_Handle_s handle, const am_Error_e error) =0;
 116                 /**
 117                  * acknowledges asyncSetSinkSoundProperty
 118                  *
 119                  * @param handle
 120                  * @param error    E_OK on success, E_ABORTED if action was aborted, E_UNKNOWN on error
 121                  */
 122                 virtual void ackSetSinkSoundProperty(const am_Handle_s handle, const am_Error_e error) =0;
 123                 /**
 124                  * acknowledges asyncSetSourceSoundProperties
 125                  *
 126                  * @param handle
 127                  * @param error    E_OK on success, E_ABORTED if action was aborted, E_UNKNOWN on error
 128                  */
 129                 virtual void ackSetSourceSoundProperties(const am_Handle_s handle, const am_Error_e error) =0;
 130                 /**
 131                  * acknowledges asyncSetSourceSoundProperty
 132                  *
 133                  * @param handle
 134                  * @param error    E_OK on success, E_ABORTED if action was aborted, E_UNKNOWN on error
 135                  */
 136                 virtual void ackSetSourceSoundProperty(const am_Handle_s handle, const am_Error_e error) =0;
 137                 /**
 138                  * acknowledges asyncCrossFade
 139                  *
 140                  * @param handle
 141                  * @param hotSink    this is the current hot sink, HS_INTERMEDIATE is here when a crossfading action did not reach the end
 142                  * @param error    E_OK on success, E_ABORTED if action was aborted, E_UNKNOWN on error
 143                  */
 144                 virtual void ackCrossFading(const am_Handle_s handle, const am_HotSink_e hotSink, const am_Error_e error) =0;
 145                 /**
 146                  * acknowledges a volume tick. This can be used to display volumechanges during ramps
 147                  *
 148                  * @param handle
 149                  * @param sourceID
 150                  * @param volume
 151                  */
 152                 virtual void ackSourceVolumeTick(const am_Handle_s handle, const am_sourceID_t sourceID, const am_volume_t volume) =0;
 153                 /**
 154                  * acknowledges a volume tick. This can be used to display volumechanges during ramps
 155                  *
 156                  * @param handle
 157                  * @param sinkID
 158                  * @param volume
 159                  */
 160                 virtual void ackSinkVolumeTick(const am_Handle_s handle, const am_sinkID_t sinkID, const am_volume_t volume) =0;
 161                 /**
 162                  * This function returns the ID to the given domainName. If already a domain is registered with this name, it will return
 163                  * the corresponding ID, if not it will reserve an ID but not register the domain. The other parameters of the domain will
 164                  * be overwritten when the domain is registered.
 165                  * @return E_OK on success, E_UNKNOWN on error
 166                  *
 167                  * @param name
 168                  * @param domainID
 169                  */
 170                 virtual am_Error_e peekDomain(const std::string& name, am_domainID_t& domainID) =0;
 171                 /**
 172                  * registers a domain
 173                  * @return E_OK on succes, E_ALREADY_EXISTENT if already registered E_UNKOWN on error
 174                  *
 175                  * @param domainData    domainID in am_Domain_s must be 0!
 176                  * @param domainID
 177                  */
 178                 virtual am_Error_e registerDomain(const am_Domain_s& domainData, am_domainID_t& domainID) =0;
 179                 /**
 180                  * deregisters a domain. All sources, sinks, gateways and crossfaders from that domain will be removed as well.
 181                  * @return E_OK on succes, E_NON_EXISTENT if not found E_UNKOWN on error
 182                  *
 183                  * @param domainID    < the nonde of the bus
 184                  */
 185                 virtual am_Error_e deregisterDomain(const am_domainID_t domainID) =0;
 186                 /**
 187                  * registers a gateway. @return E_OK on succes, E_ALREADY_EXISTENT if already registered E_UNKOWN on error
 188                  *
 189                  * @param gatewayData    In a fixed setup, the gatewayID must be below 100. In a dynamic setup, the gatewayID shall be 0.
 190                  * listSourceFormats and listSinkFormats are empty at registration time. Values are taken over when sources and sinks are
 191                  * registered.
 192                  *
 193                  *
 194                  * @param gatewayID
 195                  */
 196                 virtual am_Error_e registerGateway(const am_Gateway_s& gatewayData, am_gatewayID_t& gatewayID) =0;
 197                 /**
 198                  * deregisters a gateway. Also removes all sinks and sources of the controlling domain.
 199                  * @return E_OK on succes, E_NON_EXISTENT if not found E_UNKOWN on error
 200                  *
 201                  * @param gatewayID    domainID of the control domain
 202                  */
 203                 virtual am_Error_e deregisterGateway(const am_gatewayID_t gatewayID) =0;
 204                 /**
 205                  * This function returns the ID to the given sinkName. If already a sink is registered with this name, it will return the
 206                  * corresponding ID, if not it will reserve an ID but not register the sink. The other parameters of the sink will be
 207                  * overwritten when the sink is registered.
 208                  * @return E_OK on success, E_UNKNOWN on error
 209                  *
 210                  * @param name    ID is not valid since not created yet
 211                  * @param sinkID
 212                  */
 213                 virtual am_Error_e peekSink(const std::string& name, am_sinkID_t& sinkID) =0;
 214                 /**
 215                  * Registers a sink. If the sink is part of a gateway, the listconnectionFormats is copied to the gatewayInformation
 216                  * @return E_OK on succes, E_ALREADY_EXISTENT if already registered E_UNKOWN on error
 217                  *
 218                  * @param sinkData    In a fixed setup, the sinkID within am_Sink_s must be below 100. In a dynamic setup the sinkID must
 219                  * be 0 in am_Sink_s.
 220                  * @param sinkID
 221                  */
 222                 virtual am_Error_e registerSink(const am_Sink_s& sinkData, am_sinkID_t& sinkID) =0;
 223                 /**
 224                  * deregisters a sink.
 225                  * @return E_OK on succes, E_NON_EXISTENT if not found E_UNKOWN on error
 226                  *
 227                  * @param sinkID
 228                  */
 229                 virtual am_Error_e deregisterSink(const am_sinkID_t sinkID) =0;
 230                 /**
 231                  * This function returns the ID to the given sourceName. If already a source is registered with this name, it will return
 232                  * the corresponding ID, if not it will reserve an ID but not register the source. The other parameters of the source will
 233                  * be overwritten when the source is registered.
 234                  * @return E_OK on success, E_UNKNOWN on error
 235                  *
 236                  * @param name
 237                  * @param sourceID
 238                  */
 239                 virtual am_Error_e peekSource(const std::string& name, am_sourceID_t& sourceID) =0;
 240                 /**
 241                  * registers a source.  If the source is part of a gateway, the listconnectionFormats is copied to the gatewayInformation
 242                  * @return E_OK on success, E_UNKNOWN on error, E_ALREADY_EXIST if either name or sourceID already exists
 243                  *
 244                  * @param sourceData    In a fixed setup, the sourceID within am_Source_s must be below 100. In a dynamic setup the
 245                  * sourceID must be 0 in am_Source_s
 246                  * @param sourceID
 247                  */
 248                 virtual am_Error_e registerSource(const am_Source_s& sourceData, am_sourceID_t& sourceID) =0;
 249                 /**
 250                  * deregisters a source
 251                  * @return E_OK on succes, E_NON_EXISTENT if not found E_UNKOWN on error
 252                  *
 253                  * @param sourceID
 254                  */
 255                 virtual am_Error_e deregisterSource(const am_sourceID_t sourceID) =0;
 256                 /**
 257                  * this function registers a crossfader.
 258                  * @return E_OK on succes, E_ALREADY_EXISTENT if already registered E_UNKOWN on error
 259                  *
 260                  * @param crossfaderData    in a fixed setup, the crossfaderID must be below 100. In a dynamic setup the crossfasderID
 261                  * shall be 0
 262                  * @param crossfaderID
 263                  */
 264                 virtual am_Error_e registerCrossfader(const am_Crossfader_s& crossfaderData, am_crossfaderID_t& crossfaderID) =0;
 265                 /**
 266                  * this function deregisters a crossfader. removes all sources and sinks assiated as well.
 267                  * @return E_OK on succes, E_NON_EXISTENT if not found E_UNKOWN on error
 268                  *
 269                  * @param crossfaderID
 270                  */
 271                 virtual am_Error_e deregisterCrossfader(const am_crossfaderID_t crossfaderID) =0;
 272                 /**
 273                  * this function peeks a sourceclassID. It is used by the RoutingPlugins to determine the SinkClassIDs of a sinkClass.
 274                  * @return E_OK on succes, E_DATABASE_ERROR on error
 275                  *
 276                  * @param name
 277                  * @param sourceClassID
 278                  */
 279                 virtual am_Error_e peekSourceClassID(const std::string& name, am_sourceClass_t& sourceClassID) =0;
 280                 /**
 281                  * this function peeks a sourceclassID. It is used by the RoutingPlugins to determine the SinkClassIDs of a sinkClass.
 282                  * @return E_OK on succes, E_DATABASE_ERROR on error
 283                  *
 284                  * @param name
 285                  * @param sinkClassID
 286                  */
 287                 virtual am_Error_e peekSinkClassID(const std::string& name, am_sinkClass_t& sinkClassID) =0;
 288                 /**
 289                  * is called when a low level interrupt changes it status.
 290                  *
 291                  * @param sourceID
 292                  * @param interruptState
 293                  */
 294                 virtual void hookInterruptStatusChange(const am_sourceID_t sourceID, const am_InterruptState_e interruptState) =0;
 295                 /**
 296                  * This hook is called when all elements from a domain are registered.
 297                  * Is used by the Controller to know when all expected domains are finally registered
 298                  *
 299                  * @param domainID
 300                  */
 301                 virtual void hookDomainRegistrationComplete(const am_domainID_t domainID) =0;
 302                 /**
 303                  * is called when a sink changes its availability
 304                  *
 305                  * @param sinkID
 306                  * @param availability
 307                  */
 308                 virtual void hookSinkAvailablityStatusChange(const am_sinkID_t sinkID, const am_Availability_s& availability) =0;
 309                 /**
 310                  * is called when a source changes its availability
 311                  *
 312                  * @param sourceID
 313                  * @param availability
 314                  */
 315                 virtual void hookSourceAvailablityStatusChange(const am_sourceID_t sourceID, const am_Availability_s& availability) =0;
 316                 /**
 317                  * is called when a domain changes its status. This used for early domains only
 318                  *
 319                  * @param domainID
 320                  * @param domainState
 321                  */
 322                 virtual void hookDomainStateChange(const am_domainID_t domainID, const am_DomainState_e domainState) =0;
 323                 /**
 324                  * is called when the timinginformation (delay) changed for a connection.
 325                  *
 326                  * @param connectionID
 327                  * @param delay
 328                  */
 329                 virtual void hookTimingInformationChanged(const am_connectionID_t connectionID, const am_timeSync_t delay) =0;
 330                 /**
 331                  * this function is used to send out all data that has been changed in an early state.
 332                  * @return E_OK on success, E_UNKNOWN on error
 333                  *
 334                  * @param earlyData
 335                  */
 336                 virtual void sendChangedData(const std::vector<am_EarlyData_s>& earlyData) =0;
 337                 /**
 338                  * this function is used to retrieve a pointer to the dBusConnectionWrapper
 339                  * @return E_OK if pointer is valid, E_UKNOWN if AudioManager was compiled without DBus Support
 340                  *
 341                  * @param dbusConnectionWrapper    This is a wrapper class that is needed to keep dbus inclusions away from the interface.
 342                  * The DBusWrapperClass will return the pointer to the DbusConnection call (getDBusConnection)
 343                  */
 344                 virtual am_Error_e getDBusConnectionWrapper(CAmDbusWrapper*& dbusConnectionWrapper) const =0;
 345                 /**
 346                  * This function returns the pointer to the socketHandler. This can be used to integrate socket-based activites like
 347                  * communication with the mainloop of the AudioManager.
 348                  * returns E_OK if pointer is valid, E_UNKNOWN in case AudioManager was compiled without socketHandler support,
 349                  *
 350                  * @param socketHandler
 351                  */
 352                 virtual am_Error_e getSocketHandler(CAmSocketHandler*& socketHandler) const =0;
 353                 /**
 354                  * confirms the setRoutingReady Command
 355                  *
 356                  * @param handle    the handle that was given via setRoutingReady
 357                  * @param error    E_OK if the ready command succeeded. E_UNKNOWN if an error happened.
 358                  */
 359                 virtual void  confirmRoutingReady(const uint16_t handle, const am_Error_e error) =0;
 360                 /**
 361                  * confirms the setRoutingRundown Command
 362                  *
 363                  * @param handle    handle that was given via setRoutingRundown
 364                  * @param error    E_OK if the ready command succeeded. E_UNKNOWN if an error happened.
 365                  */
 366                 virtual void  confirmRoutingRundown(const uint16_t handle, const am_Error_e error) =0;
 367                 /**
 368                  * updates data of an gateway. @return E_OK on success, E_NON_EXISTENT if the gatewayID is not valid.
 369                  *
 370                  * @param gatewayID    This is the new gateway data that has been updated. Please note that changing source and sink IDs,
 371                  *
 372                  * @param listSourceFormats
 373                  * @param listSinkFormats
 374                  * @param convertionMatrix
 375                  */
 376                 virtual am_Error_e updateGateway(const am_gatewayID_t gatewayID, const std::vector<am_ConnectionFormat_e>& listSourceFormats, const std::vector<am_ConnectionFormat_e>& listSinkFormats, const std::vector<bool>& convertionMatrix) =0;
 377                 /**
 378                  * updates data of an gateway. @return E_OK on success, E_NON_EXISTENT if the sinkID is not valid.
 379                  *
 380                  * @param sinkID    The sinkID of the sink
 381                  * @param sinkClassID
 382                  * @param listSoundProperties
 383                  * @param listConnectionFormats
 384                  * @param listMainSoundProperties
 385                  */
 386                 virtual am_Error_e updateSink(const am_sinkID_t sinkID, const am_sinkClass_t sinkClassID, const std::vector<am_SoundProperty_s>& listSoundProperties, const std::vector<am_ConnectionFormat_e>& listConnectionFormats, const std::vector<am_MainSoundProperty_s>& listMainSoundProperties) =0;
 387                 /**
 388                  * updates data of an source. @return E_OK on success, E_NON_EXISTENT if the sourceID in the struct is not valid.
 389                  * Please note that only the following data out of am_Source_s have effect when they are changed:
 390                  * sourceClassID,
 391                  * listSoundProperties,
 392                  * listConnectionFormats,
 393                  * listMainSoundProperties
 394                  *
 395                  * @param sourceID    the sourceID of the source
 396                  * @param sourceClassID
 397                  * @param listSoundProperties
 398                  * @param listConnectionFormats
 399                  * @param listMainSoundProperties
 400                  */
 401                 virtual am_Error_e updateSource(const am_sourceID_t sourceID, const am_sourceClass_t sourceClassID, const std::vector<am_SoundProperty_s>& listSoundProperties, const std::vector<am_ConnectionFormat_e>& listConnectionFormats, const std::vector<am_MainSoundProperty_s>& listMainSoundProperties) =0;
 402                 /**
 403                  * acknowledges a asyncSetSinkVolumes
 404                  *
 405                  * @param handle
 406                  * @param listvolumes    The list of volumes that have been set. ramp and time values have no meaning when the struct is
 407                  * used here.
 408                  * @param error    E_OK on success, E_ABORTED if action was aborted, E_UNKNOWN on error
 409                  */
 410                 virtual void ackSetVolumes(const am_Handle_s handle, const std::vector<am_Volumes_s>& listvolumes, const am_Error_e error) =0;
 411                 /**
 412                  * The acknowledge of the SinkNotificationConfiguration
 413                  *
 414                  * @param handle
 415                  * @param error
 416                  */
 417                 virtual void ackSinkNotificationConfiguration(const am_Handle_s handle, const am_Error_e error) =0;
 418                 /**
 419                  * The acknowledge of the SourceNotificationConfiguration
 420                  *
 421                  * @param handle
 422                  * @param error
 423                  */
 424                 virtual void ackSourceNotificationConfiguration(const am_Handle_s handle, const am_Error_e error) =0;
 425                 /**
 426                  * is called whenever a notified value needs to be send
 427                  *
 428                  * @param sinkID    The sinkID of the sink where the data changed
 429                  * @param payload    The payload
 430                  */
 431                 virtual void hookSinkNotificationDataChange(const am_sinkID_t sinkID, const am_NotificationPayload_s& payload) =0;
 432                 /**
 433                  * is called whenever a notified value needs to be send
 434                  *
 435                  * @param sourceID    The sinkID of the sink where the data changed
 436                  * @param payload    The payload
 437                  */
 438                 virtual void hookSourceNotificationDataChange(const am_sourceID_t sourceID, const am_NotificationPayload_s& payload) =0;
 439
 440         };
 441 }
 442 #endif // !defined(EA_B7A11CC8_9777_4421_8677_D9CE084D5E2B__INCLUDED_)