inc/FCntAudioContentInfo.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16 /**
  17  * @file                        FCntAudioContentInfo.h
  18  * @brief               This is the header file for the %AudioContentInfo class.
  19  *
  20  * This header file contains the declarations of the %AudioContentInfo class.
  21  */
  22
  23 #ifndef _FCNT_AUDIO_CONTENT_INFO_H_
  24 #define _FCNT_AUDIO_CONTENT_INFO_H_
  25
  26 #include <FCntContentInfo.h>
  27
  28 namespace Tizen { namespace Content
  29 {
  30
  31 class _AudioContentInfoImpl;
  32
  33 /**
  34  * @class       AudioContentInfo
  35  * @brief       This class provides methods to access the audio content information.
  36  *
  37  * @since       2.0
  38  *
  39  * @final       This class is not intended for extension.
  40  *
  41  * The %AudioContentInfo class provides methods to access the audio content information that is extracted from a physical file. @n
  42  * Before getting the audio content information, ContentManager must be used to create the content.
  43  *
  44  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/content/device_content_attributes.htm#media">Device Content Attributes</a>.
  45  *
  46  * The following example demonstrates how to use the %AudioContentInfo class.
  47  *
  48  * @code
  49  * result
  50  * MyClass::TestAudioContentInfo(void)
  51  * {
  52  *              result r = E_SUCCESS;
  53  *
  54  *              ContentId contentId;
  55  *              ContentManager contentManager;
  56  *              r = contentManager.Construct();
  57  *              TryReturn(!IsFailed(r), r, "Construct failed.");
  58  *
  59  *              AudioContentInfo audioContentInfo;
  60  *              r = audioContentInfo.Construct(null);
  61  *              TryReturn(!IsFailed(r), r, "Construct failed.");
  62  *
  63  *              Tizen::Base::String sourcePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/flower.wma";
  64  *              Tizen::Base::String destPath = Tizen::System::Environment::GetMediaPath() + L"Sounds/flower.wma";
  65  *
  66  *              contentId = contentManager.CreateContent(sourcePath, destPath, false, &audioContentInfo);
  67  *              TryReturn(Tizen::Base::UuId::GetInvalidUuId() != contentId, GetLastResult(), "CreateContent failed.");
  68  *
  69  *              return r;
  70  * }
  71  * @endcode
  72  */
  73 class _OSP_EXPORT_ AudioContentInfo
  74         : public Tizen::Content::ContentInfo
  75 {
  76 public:
  77         /**
  78          * The object is not fully constructed after this constructor is called. @n
  79          * For full construction, the Construct() method must be called right after calling this constructor.
  80          *
  81          * @since               2.0
  82          */
  83         AudioContentInfo(void);
  84
  85         /**
  86          * This destructor overrides Tizen::Base::Object::~Object().
  87          *
  88          * @since               2.0
  89          */
  90         virtual ~AudioContentInfo(void);
  91
  92         /**
  93          * Initializes this instance of %AudioContentInfo with the specified parameter.
  94          *
  95          * @if OSPCOMPAT
  96          * @brief <i> [Compatibility] </i>
  97          * @endif
  98          * @since                       2.0
  99          * @if OSPCOMPAT
 100          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 101          *                       For more information, see @ref CompAudioContentInfoConstructPage "here".
 102          * @endif
 103          *
 104          * @return                      An error code
 105          * @param[in]   pContentPath                    The content path @n
 106          *                                                              The path should be started with directory path returned by
 107          *                                                              either Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath(). @n
 108          *                                                              If the path is @c null,
 109          *                                                              use ContentManager::CreateContent(const Tizen::Base::ByteBuffer&, const Tizen::Base::String&, const ContentInfo*) @n
 110          *                                                              or ContentManager::CreateContent(const Tizen::Base::String&, const Tizen::Base::String&, bool, const ContentInfo*),
 111          *                                                              instead of this method.
 112          * @exception   E_SUCCESS                       The method is successful.
 113          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 114          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 115          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 116          * @exception   E_IO                                    An I/O error has occurred.
 117          * @exception   E_SYSTEM                                An internal error has occurred.
 118          */
 119         result Construct(const Tizen::Base::String* pContentPath);
 120
 121         /**
 122          * @if OSPCOMPAT
 123          * @page        CompAudioContentInfoConstructPage Compatibility for the file path.
 124          * @section     CompAudioContentInfoConstructPageIssueSection Issues
 125          *                 The content path argument of this method in OSP compatible applications has the following issues: @n
 126          *                 -# The content path should be a path that begins with an allowed path prefix. @n
 127          *                     For example, L"/Media/Images/flower.jpg", L"/Storagecard/Media/Images/flower.jpg".
 128          *
 129          * @section     CompAudioContentInfoConstructPageSolutionSection Resolutions
 130          *                 This issue has been resolved in Tizen. @n
 131          *                 -# The content path can be a path without a specific allowed path prefix. @n
 132          *                 Application do not need to know the specific allowed path prefixes. @n
 133          *                 To get the directory path, use the following methods: @n
 134          *                 - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
 135          *                 - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
 136          *
 137          * @endif
 138          */
 139
 140         /**
 141          * @if OSPDEPREC
 142          * Initializes this instance of %AudioContentInfo with the specified parameters.
 143          *
 144          * @brief       <i> [Deprecated] </i>
 145          * @deprecated  This method is deprecated as there is a problem in managing the user-defined thumbnail and device coordinates. @n
 146          *                      Instead of using this method, use Construct(const Tizen::Base::String*). @n
 147          *                      To set the coordinates in the ContentInfo instance, use ContentInfo::SetCoordinates(const Tizen::Locations::Coordinates&).
 148          * @since                       2.0
 149          *
 150          * @return                      An error code
 151          * @param[in]   contentPath                                     The content path
 152          * @param[in]   thumbnailPath                           The thumbnail path
 153          * @param[in]   setGps                                                  Set to @c true to save the device's last known coordinates in the ContentInfo instance, @n
 154          *                                                                                              else @c false @n
 155          *                                                                                              The coordinate information may be incorrect if it is outdated or has never been updated. @n
 156          *                                              To update the coordinate information or to get the exact value,
 157          *                                              use Tizen::Locations::LocationProvider::RequestLocationUpdates() before calling this method.
 158          * @exception   E_SUCCESS                                       The method is successful.
 159          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 160          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 161          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 162          * @exception   E_IO                                                            An I/O error has occurred.
 163          * @remarks
 164          *                               - The content path must start with @c '/Media' or @c '/Storagecard/Media'.
 165          *                               - The thumbnail path must start with @c '/Home', @c '/Media', or @c '/Storagecard/Media'. @n
 166          *                                              The permitted format for a thumbnail image is Bitmap (bmp).
 167          * @endif
 168          */
 169         virtual result Construct(const Tizen::Base::String& contentPath, const Tizen::Base::String& thumbnailPath = L"", bool setGps = false);
 170
 171         /**
 172          * Gets the genre information of the audio file.
 173          *
 174          * @since               2.0
 175          *
 176          * @return              The genre information of the audio file, @n
 177          *              else @c Unknown if the value is empty
 178          */
 179         Tizen::Base::String GetGenre(void) const;
 180
 181         /**
 182          * Gets the artist information of the audio file.
 183          *
 184          * @since               2.0
 185          *
 186          * @return              The artist information of the audio file, @n
 187          *              else @c Unknown if the value is empty
 188          */
 189         Tizen::Base::String GetArtist(void) const;
 190
 191         /**
 192          * Gets the composer information of the audio file.
 193          *
 194          * @since               2.0
 195          *
 196          * @return              The composer information of the audio file, @n
 197          *              else @c Unknown if the value is empty
 198          */
 199         Tizen::Base::String GetComposer(void) const;
 200
 201         /**
 202          * Gets the album name of the audio file.
 203          *
 204          * @since               2.0
 205          *
 206          * @return              The album name of the audio file, @n
 207          *              else @c Unknown if the value is empty
 208          */
 209         Tizen::Base::String GetAlbumName(void) const;
 210
 211         /**
 212          * Gets the release year information of the audio file.
 213          *
 214          * @since               2.0
 215          *
 216          * @return              The release year information of the audio file
 217          */
 218         int GetReleaseYear(void) const;
 219
 220         /**
 221          * Gets the bit rate information of the audio file.
 222          *
 223          * @since               2.0
 224          *
 225          * @return              The bit rate in bits per second (bps)
 226          */
 227         int GetBitrate(void) const;
 228
 229         /**
 230          * Gets the title of the audio file.
 231          *
 232          * @since               2.0
 233          *
 234          * @return              The title of the audio file, @n
 235          *              else @c Unknown if the value is empty
 236          */
 237         Tizen::Base::String GetTitle(void) const;
 238
 239         /**
 240          * Gets the copyright of the audio file.
 241          *
 242          * @since               2.0
 243          *
 244          * @return              The copyright of the audio file, @n
 245          *              else @c Unknown if the value is empty
 246          */
 247         Tizen::Base::String GetCopyright(void) const;
 248
 249         /**
 250          * Gets the track information of the audio file.
 251          *
 252          * @since               2.0
 253          *
 254          * @return              The track information of the audio file, @n
 255          *              else @c Unknown if the value is empty
 256          */
 257         Tizen::Base::String GetTrackInfo(void) const;
 258
 259         /**
 260          * Gets the duration of the audio file.
 261          *
 262          * @since               2.0
 263          *
 264          * @return              The duration of the audio file in milliseconds
 265          */
 266         long GetDuration(void) const;
 267
 268 private:
 269         class _AudioContentData
 270         {
 271         public:
 272                 _AudioContentData()
 273                         : bitrate(0)
 274                         , releaseYear(0)
 275                         , duration(0)
 276                         , pTitle(null)
 277                         , pAlbumName(null)
 278                         , pArtist(null)
 279                         , pComposer(null)
 280                         , pGenre(null)
 281                         , pCopyright(null)
 282                         , pTrackInfo(null) {}
 283
 284                 int bitrate;
 285                 int releaseYear;
 286                 long duration;
 287                 Tizen::Base::String* pTitle;
 288                 Tizen::Base::String* pAlbumName;
 289                 Tizen::Base::String* pArtist;
 290                 Tizen::Base::String* pComposer;
 291                 Tizen::Base::String* pGenre;
 292                 Tizen::Base::String* pCopyright;
 293                 Tizen::Base::String* pTrackInfo;
 294         };
 295
 296         /**
 297          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 298          */
 299         AudioContentInfo(const AudioContentInfo& rhs);
 300
 301         /**
 302          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 303          */
 304         AudioContentInfo& operator =(const AudioContentInfo& rhs);
 305
 306         result SetAudioContentData(const _AudioContentData* pAudioContentData);
 307
 308         _AudioContentData* GetAudioContentData(void);
 309
 310 private:
 311         _AudioContentData* __pAudioContentData;
 312
 313         friend class _ContentManagerImpl;
 314         friend class _ContentSearchImpl;
 315         friend class _ContentDirectoryImpl;
 316         friend class _ContentUtility;
 317         friend class _PlayListManagerImpl;
 318         friend class _PlayListImpl;
 319
 320         friend class _AudioContentInfoImpl;
 321         _AudioContentInfoImpl* __pImpl;
 322
 323 };  // Class AudioContentInfo
 324
 325 }}  // Tizen::Content
 326
 327 #endif  // _FCNT_AUDIO_CONTENT_INFO_H_