inc/FMediaAudioRouteManager.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                        FMediaAudioRouteManager.h
  20  * @brief               This is the header file for the %AudioRouteManager class.
  21  *
  22  * This header file contains the declarations of the %AudioRouteManager class.
  23  */
  24
  25 #ifndef _FMEDIA_AUDIO_ROUTE_MANAGER_H_
  26 #define _FMEDIA_AUDIO_ROUTE_MANAGER_H_
  27
  28 #include <FMediaAudioManagerTypes.h>
  29 #include <FMediaIAudioRouteEventListener.h>
  30
  31 namespace Tizen { namespace Media
  32 {
  33 /**
  34  *      @class AudioRouteManager
  35  * @brief       This class is used to manage audio routing.
  36  *
  37  *      @since          2.0
  38  *
  39  * @final This class is not intended for extension.
  40  *
  41  *      @remarks   Only one instance of the class works at a time.
  42  *
  43  * The following example demonstrates how to use the %AudioRouteManager class.
  44  *
  45  * @code
  46  *
  47  * #include <FBase.h>
  48  * #include <FMedia.h>
  49  *
  50  * using namespace Tizen::Base;
  51  * using namespace Tizen::Base::Collection;
  52  * using namespace Tizen::Media;
  53  *
  54  * class RouteManagerSample
  55  *     : public Tizen::Media::IPlayerEventListener
  56  *     ,        public Tizen::Media::IAudioRouteEventListener
  57   * {
  58  * public:
  59  *     result Initialize(void);
  60  *     result Play(void);
  61  *     result Route(void);
  62  *     void Stop(void);
  63  *
  64  * protected:
  65  *     // IPlayerEventListener
  66  *     virtual void OnPlayerOpened(result r) {}
  67  *     virtual void OnPlayerEndOfClip(void) {}
  68  *     virtual void OnPlayerBuffering(int percent) {}
  69  *     virtual void OnPlayerErrorOccurred(PlayerErrorReason r) {}
  70  *     virtual void OnPlayerInterrupted(void) {}
  71  *     virtual void OnPlayerReleased(void) {}
  72  *     virtual void OnPlayerSeekCompleted(result r) {}
  73  *     virtual void OnPlayerAudioFocusChanged (void) {}
  74  *
  75  *     virtual  void OnActiveAudioRouteChanged(const Tizen::Media::AudioRouteInfo& route)       {}
  76  *     virtual void OnAudioRouteAdded(const Tizen::Media::AudioRouteInfo& route) {}
  77  *     virtual void OnAudioRouteRemoved(const Tizen::Media::AudioRouteInfo& route) {}
  78  *
  79  *
  80  * private:
  81  *     Player __player;
  82  *     AudioRouteManager *__pAudioRouteManager;
  83  * };
  84  *
  85  * result
  86  * RouteManagerSample::Initialize(void)
  87  * {
  88  *     result r = E_SUCCESS;
  89  *     String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.mp3";
  90  *
  91  *     r = __player.Construct(*this);
  92  *     if (IsFailed(r))
  93  *     {
  94  *         return r;
  95  *     }
  96  *
  97  *                 __pAudioRouteManager = AudioRouteManager::GetInstance();
  98  *               if (!__pAudioRouteManger)
  99  *         {
 100  *                              return E_OUT_OF_MEMORY;
 101  *              }
 102  *
 103  *     r = __player.OpenFile(filePath, false);
 104  *     if (IsFailed(r))
 105  *     {
 106  *         return r;
 107  *     }
 108  *     return r;
 109  * }
 110  *
 111  *
 112  * result
 113  * RouteManagerSample::Play(void)
 114  * {
 115   * result r = E_SUCCESS;
 116   * r = __player.Play();
 117   * return r;
 118  * }
 119  *
 120  * result
 121  * RouteManagerSample::Route(void)
 122  * {
 123  *        result r = E_SUCCESS;
 124  *   IList *pAudioDeviceList = null;
 125  *   int count;
 126  *
 127  *     pAudioDeviceList = __pAudioRouteManager->GetAvailableaudioRouteListN();
 128  *     count = pAudioDeviceList->GetCount();
 129  *     if (count)
 130  *     {
 131  *     AudioRouteInfo *audioDevice = (AudioRouteInfo *) pAudioDeviceList->GetAt(0);
 132  *     r = __pAudioRouteManager->SetActiveAudioRoute(*audioDevice);
 133  *      if (IsFailed(r))
 134  *              {
 135  *              return r;
 136  *              }
 137  *      }
 138  *      pAudioDeviceList->RemoveAll();
 139  *      pAudioDeviceList = null;
 140  *
 141  *        return r;
 142  * }
 143  *
 144  *
 145  * void
 146  * RouteManagerSample::Stop(void)
 147  * {
 148  *     __player.Stop();
 149  *     __player.Close();
 150  * }
 151  *
 152  * @endcode
 153  */
 154
 155 class _OSP_EXPORT_ AudioRouteManager
 156         :public Tizen::Base::Object
 157 {
 158 public:
 159         /**
 160         *       Gets the audio route manager instance pointer.
 161         *
 162         *       @since          2.0
 163         *
 164         *       @privlevel                              partner
 165         *       @privilege                              %http://tizen.org/privilege/audiomanager.route
 166         *
 167         *       @return                 A pointer to the audio route manager instance, @n
 168         *                                                               else @c null if it fails
 169         *       @exception                      E_SUCCESS                                               The method is successful.
 170         *       @exception                      E_OUT_OF_MEMORY                 The memory is insufficient to perform the operation.
 171         *       @exception                      E_PRIVILEGE_DENIED                      The application does not have the privilege to call this method.
 172         *       @remarks                The specific error code can be accessed using the GetLastResult() method.
 173         */
 174         static AudioRouteManager* GetInstance(void);
 175
 176         /**
 177         *       Sets audio route event listener.
 178         *
 179         *       @since          2.0
 180         *
 181         *       @privlevel                              partner
 182         *       @privilege                              %http://tizen.org/privilege/audiomanager.route
 183         *
 184         *       @return                                 An error code
 185         *       @param[in]                              pListener                                                       The audio route event listener @n
 186         *                                                                                                                                                       To unset the listener, pass a @c null value to the listener parameter.
 187         *       @exception                      E_SUCCESS                                                       The method is successful.
 188         *       @exception                      E_PRIVILEGE_DENIED                      The application does not have the privilege to call this method.
 189         */
 190         result SetAudioRouteEventListener(IAudioRouteEventListener* pListener);
 191
 192         /**
 193         *       Gets the name of the active bluetooth A2DP device.
 194         *
 195         *       @since          2.0
 196         *
 197         *       @privlevel                              partner
 198         *       @privilege                              %http://tizen.org/privilege/audiomanager.route
 199         *
 200         *       @return                         The name of active bluetooth A2DP device
 201         *       @exception                      E_SUCCESS                                                       The method is successful.
 202         *       @exception                      E_DEVICE_UNAVAILABLE            A2DP device is not connected or available.
 203         *       @exception                      E_PRIVILEGE_DENIED                      The application does not have the privilege to call this method.
 204         *       @remarks                The specific error code can be accessed using the GetLastResult() method.
 205         */
 206         Tizen::Base::String GetActiveBluetoothA2dpName(void) const;
 207
 208         /**
 209         *       Gets the active audio stream type
 210         *
 211         *       @since          2.0
 212         *
 213         *       @privlevel                              partner
 214         *       @privilege                              %http://tizen.org/privilege/audiomanager.route
 215         *
 216         *       @return                                 An active audio stream type
 217         *       @exception                      E_SUCCESS                                               The method is successful.
 218         *       @exception                      E_PRIVILEGE_DENIED                      The application does not have the privilege to call this method.
 219         *       @remarks                The specific error code can be accessed using the GetLastResult() method.
 220         *       @remarks                                @c AUDIO_STREAM_TYPE_NO_SOUND is returned when no sound is playing.
 221         */
 222         AudioStreamType GetActiveAudioStreamType(void) const;
 223
 224         /**
 225         *       Gets available audio routes.
 226         *
 227         *       @since          2.0
 228         *
 229         *       @privlevel                              partner
 230         *       @privilege                              %http://tizen.org/privilege/audiomanager.route
 231         *
 232         *       @return                                 The list of available audio routes, @n
 233         *                                                                       else @c null if it fails
 234         *       @exception                      E_SUCCESS                                               The method is successful.
 235         *       @exception                      E_OUT_OF_MEMORY                 The memory is insufficient to make the list.
 236         *       @exception                      E_PRIVILEGE_DENIED                      The application does not have the privilege to call this method.
 237         *       @remarks                The specific error code can be accessed using the GetLastResult() method.
 238         *       @remarks                                The item type of returned list is AudioRouteInfo.
 239         */
 240         Tizen::Base::Collection::IList* GetAvailableAudioRouteListN(void) const;
 241
 242         /**
 243         *       Checks the specified @c route availability.
 244         *
 245         *       @since          2.0
 246         *
 247         *       @privlevel                              partner
 248         *       @privilege                              %http://tizen.org/privilege/audiomanager.route
 249         *
 250         *       @return                                 @c true if the audio route is available, @n
 251         *                                                               else @c false
 252         *       @param[in]                              route                                                                   An instance of AudioRouteInfo
 253         *       @exception                      E_SUCCESS                                               The method is successful.
 254         *       @exception                      E_INVALID_ARG                                   A specified input parameter is invalid.
 255         *       @exception                      E_PRIVILEGE_DENIED                      The application does not have the privilege to call this method.
 256         *       @remarks                The specific error code can be accessed using the GetLastResult() method.
 257         */
 258         bool IsAudioRouteAvailable(const AudioRouteInfo& route) const;
 259
 260         /**
 261         *       Sets the active audio route.
 262         *
 263         *       @since          2.0
 264         *
 265         *       @privlevel                              partner
 266         *       @privilege                              %http://tizen.org/privilege/audiomanager.route
 267         *
 268         *       @return                                 An error code
 269         *       @param[in]                              route                                                           An instance of AudioRouteInfo to set
 270         *       @exception                      E_SUCCESS                                               The method is successful.
 271         *       @exception                      E_INVALID_ARG                                   A specified input parameter is invalid.
 272         *       @exception                      E_DEVICE_UNAVAILABLE                    The audio route is not available.
 273         *       @exception                      E_PRIVILEGE_DENIED                      The application does not have the privilege to call this method.
 274         */
 275         result SetActiveAudioRoute(const AudioRouteInfo& route);
 276
 277         /**
 278         *       Gets the active audio route.
 279         *
 280         *       @since          2.0
 281         *
 282         *       @privlevel                              partner
 283         *       @privilege                              %http://tizen.org/privilege/audiomanager.route
 284         *
 285         *       @return                                 The active audio route
 286         *       @exception                      E_SUCCESS                                               The method is successful.
 287         *       @exception                      E_PRIVILEGE_DENIED                      The application does not have the privilege to call this method.
 288         *       @remarks                The specific error code can be accessed using the GetLastResult() method.
 289         *       @remarks @c INPUT_AUDIO_DEVICE_NONE and @c OUTPUT_AUDIO_DEVICE_NONE are set in AudioRouteInfo if this method fails.
 290         */
 291         AudioRouteInfo GetActiveAudioRoute(void) const;
 292
 293
 294 private:
 295         /**
 296          * This default constructor is intentionally declared as private to implement the Singleton semantic.
 297          *
 298          * @since               2.0
 299          *
 300          */
 301         AudioRouteManager(void);
 302
 303         /**
 304         *       This destructor is intentionally declared as private to implement the Singleton semantic.
 305         *
 306         *       @since          2.0
 307         *
 308         */
 309         virtual ~AudioRouteManager(void);
 310
 311         /**
 312          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 313          *
 314          * @since               2.0
 315          *
 316          */
 317         AudioRouteManager(const AudioRouteManager& rhs);
 318
 319         /**
 320          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 321          *
 322          * @since               2.0
 323          *
 324          */
 325         AudioRouteManager& operator =(const AudioRouteManager& rhs);
 326
 327         class _AudioRouteManagerImpl* __pAudioRouteManagerImpl;
 328 };
 329
 330 }} // Tizen::Media
 331
 332 #endif