inc/FMediaMediaStreamInfo.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                        FMediaMediaStreamInfo.h
  20  * @brief                       This is the header file for the %MediaStreamInfo class.
  21  *
  22  * This header file contains the declarations of the %MediaStreamInfo class.
  23  */
  24
  25 #ifndef _FMEDIA_MEDIA_STREAM_INFO_H_
  26 #define _FMEDIA_MEDIA_STREAM_INFO_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseColIList.h>
  30 #include <FBaseString.h>
  31 #include <FBaseByteBuffer.h>
  32 #include <FMediaAudioStreamInfo.h>
  33 #include <FMediaVideoStreamInfo.h>
  34
  35 namespace Tizen { namespace Media
  36 {
  37 /**
  38  * @class        MediaStreamInfo
  39  * @brief        This class provides methods to get media stream information.
  40  *
  41  * @since               2.0
  42  *
  43  * The %MediaStreamInfo class provides methods to get media stream information, including:
  44  * - %Content metadata, such as the title, artist, album title, genre, year, and album art.
  45  * - Audio and video stream information.
  46  *
  47  * This class supports multiple stream content that consists of several audio or video tracks.
  48  * This class provides a list of AudioStreamInfo and VideoStreamInfo that has the stream information of each audio or video track.
  49  *
  50  * For more detailed information, see %AudioStreamInfo and %VideoStreamInfo classes.
  51  *
  52  * The following example demonstrates how to use the %MediaStreamInfo class.
  53  * @code
  54  * #include <FBase.h>
  55  * #include <FApp.h>
  56  * #include <FMedia.h>
  57  *
  58  * using namespace Tizen::Base;
  59  * using namespace Tizen::Base::Collection;
  60  * using namespace Tizen::Media;
  61  *
  62  * class MediaStreamInfoSample
  63  *       : public Tizen::Media::IPlayerEventListener
  64  * {
  65  * public:
  66  *       result Test(void);
  67  *
  68  * protected:
  69  *       virtual void OnPlayerOpened(result r) {}
  70  *       virtual void OnPlayerEndOfClip(void) {}
  71  *       virtual void OnPlayerBuffering(int percent) {}
  72  *       virtual void OnPlayerErrorOccurred(PlayerErrorReason r) {}
  73  *       virtual void OnPlayerInterrupted() {}
  74  *       virtual void OnPlayerReleased() {}
  75  *       virtual void OnPlayerSeekCompleted(result r) {}
  76  *  virtual void OnPlayerAudioFocusChanged (void) {}
  77  *
  78  * private:
  79  *       Player __player;
  80  * };
  81  *
  82  * result
  83  * MediaStreamInfoSample::Test(void)
  84  * {
  85  *       MediaStreamInfo*  pStreamInfo = null;
  86  *       const IList* pInfoList = null;
  87  *       const AudioStreamInfo* pInfo = null;
  88  *       String path = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.aac";
  89  *
  90  *       __player.Construct(*this);
  91  *       __player.OpenFile(path);
  92  *       __player.Play();
  93  *
  94  *       // Checks the Player's state
  95  *       if (__player.GetState() != PLAYER_STATE_PLAYING)
  96  *       {
  97  *               return E_INVALID_STATE;
  98  *       }
  99  *
 100  *       // Gets the stream information from Player
 101  *       pStreamInfo = __player.GetCurrentMediaStreamInfoN();
 102  *       if (pStreamInfo == null)
 103  *       {
 104  *               return GetLastResult();
 105  *       }
 106  *
 107  *       pInfoList = pStreamInfo->GetAudioStreamInfoList();
 108  *       if (pInfoList == null)
 109  *       {
 110  *               goto CATCH;
 111  *       }
 112  *
 113  *       pInfo = (const AudioStreamInfo*)pInfoList->GetAt(0);
 114  *       if (pInfo == null)
 115  *       {
 116  *               goto CATCH;
 117  *       }
 118  *
 119  *       AppLog("AudioStreamInfo: codec:0x%x, bitRate:%d, channel:%d, sampleRate:%d",
 120  *                      pInfo->GetCodecType(), pInfo->GetBitRate(),
 121  *                      pInfo->GetChannelType(), pInfo->GetSampleRate());
 122  *
 123  *       __player.Stop();
 124  *       __player.Close();
 125  *       return E_SUCCESS;
 126  *
 127  * CATCH:
 128  *       delete pStreamInfo;
 129  *       return E_SUCCESS;
 130  * }
 131  *
 132  * @endcode
 133  */
 134 class _OSP_EXPORT_ MediaStreamInfo
 135         : public Tizen::Base::Object
 136 {
 137 public:
 138         /**
 139         *       This destructor overrides Tizen::Base::Object::~Object().
 140         *
 141         * @since                2.0
 142         */
 143         virtual ~MediaStreamInfo(void);
 144
 145 public:
 146         /**
 147         *       Gets the title.
 148         *
 149         *       @since          2.0
 150         *
 151         *       @return           The value of the title, @n
 152         *                                 else an empty string if the content has no title
 153         */
 154         Tizen::Base::String GetTitle(void) const;
 155
 156         /**
 157         *       Gets the name of the artist from the content.
 158         *
 159         *       @since          2.0
 160         *
 161         *       @return                                  The artist, @n
 162         *                                                        else an empty string if the content has no artist name
 163         */
 164         Tizen::Base::String GetArtist(void) const;
 165
 166         /**
 167         *       Gets the album title.
 168         *
 169         *       @since          2.0
 170         *
 171         *       @return           The title of the album, @n
 172         *                                 else an empty string if the content has no album
 173         */
 174         Tizen::Base::String GetAlbumTitle(void) const;
 175
 176         /**
 177         *       Gets the genre.
 178         *
 179         *       @since          2.0
 180         *
 181         *       @return           The genre, @n
 182         *                                 else an empty string if the content has no genre
 183         */
 184         Tizen::Base::String GetGenre(void) const;
 185
 186         /**
 187         *       Gets the year.
 188         *
 189         *       @since          2.0
 190         *
 191         *       @return         The year, @n
 192         *                               else @c 0 if the content has no year
 193         */
 194         int GetYear(void) const;
 195
 196         /**
 197         *       Gets the album art.
 198         *
 199         *       @since          2.0
 200         *
 201         *       @return         The album art in the content, @n
 202         *                               else @c null if the content has no album art
 203         */
 204         Tizen::Base::ByteBuffer* GetAlbumArtN(void) const;
 205
 206         /**
 207         *       Gets a list of the audio stream information.
 208         *
 209         *   @since              2.0
 210         *
 211         *       @return                                                                 A pointer to the list containing the audio stream information @n
 212         *                                                                                       The value belongs to the AudioStreamInfo class.
 213         *       @exception        E_SUCCESS                             The method is successful.
 214         *       @exception        E_INVALID_DATA                        The stream cannot be parsed successfully.
 215         *       @exception        E_SYSTEM                               A system error has occurred.
 216         *       @remarks                                The specific error code can be accessed using the GetLastResult() method.
 217         */
 218         const Tizen::Base::Collection::IList* GetAudioStreamInfoList(void) const;
 219
 220         /**
 221         *       Gets a list of the video stream information.
 222         *
 223         *   @since              2.0
 224         *
 225         *       @return          A pointer to a list containing the video stream information @n
 226         *                                                               The value belongs to the VideoStreamInfo class.
 227         *       @exception        E_SUCCESS                             The method is successful.
 228         *       @exception        E_INVALID_DATA                        The stream cannot be parsed successfully.
 229         *       @exception        E_SYSTEM                               A system error has occurred.
 230         *       @remarks                                The specific error code can be accessed using the GetLastResult() method.
 231         */
 232         const Tizen::Base::Collection::IList* GetVideoStreamInfoList(void) const;
 233
 234         /**
 235         * Copying of objects using this copy constructor is allowed.
 236         *
 237         * @since                2.0
 238         *
 239         * @return               The copy of this instance
 240         * @param[in]    rhs     An instance of %MediaStreamInfo
 241         */
 242         MediaStreamInfo(const MediaStreamInfo & rhs);
 243
 244         /**
 245         * Copying of objects using this copy assignment operator is allowed.
 246         *
 247         * @since                2.0
 248         *
 249         * @return The reference of this instance
 250         * @param[in] rhs An instance of %MediaStreamInfo
 251         */
 252         MediaStreamInfo & operator =(const MediaStreamInfo & rhs);
 253
 254         /**
 255         * Compares the specified instance of Tizen::Base::Object with the calling instance of %MediaStreamInfo.
 256         *
 257         * @since                2.0
 258         *
 259         * @return        @c true if the value of the specified instance equals the value of the current instance, @n
 260         *                         else @c false
 261         * @param[in]  rhs   The object to compare with the current instance
 262         */
 263         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 264
 265         /**
 266         * Gets the hash value of the current instance.
 267         *
 268         * @since                2.0
 269         *
 270         * @return                                                 The hash value of the current instance
 271         */
 272         virtual int GetHashCode(void) const;
 273
 274 private:
 275         /**
 276         *       This default constructor is intentionally declared as private so that only the platform can create an instance.
 277         *
 278         *       @param[in]              title                                   The value of the title @n
 279         *       @param[in]              artist                                  The value of the artist @n
 280         *       @param[in]              albumTitle                              The value of the title of the album @n
 281         *       @param[in]              genre                                   The value of the genre @n
 282         *       @param[in]              year                                    The value of the year @n
 283         *       @param[in]              albumArt                                The value of the album art @n
 284         *       @param[in]              pAudioStream                    A pointer to an audio stream list @n
 285         *       @param[in]              pVideoStream                    A pointer to a video stream list @n
 286         *       @param[in]              titleException                  An exception generated due to the title of audio or video @n
 287         *       @param[in]              audioStreamException    The exception generated during audio streaming @n
 288         *       @param[in]              videoStreamException    The exception generated during video streaming @n
 289         */
 290         MediaStreamInfo(const Tizen::Base::String& title, const Tizen::Base::String& artist, const Tizen::Base::String& albumTitle, const Tizen::Base::String& genre, int year, Tizen::Base::ByteBuffer* pAlbumArt, Tizen::Base::Collection::IList* pAudioStream, Tizen::Base::Collection::IList* pVideoStream, result audioStreamException, result videoStreamException);
 291
 292 private:
 293         class _MediaStreamInfoImpl *__pMediaStreamInfoImpl;
 294         friend class _PlayerImpl;
 295 };
 296
 297 }}//Tizen::Media
 298
 299 #endif