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 class _AudioContentData;
  33
  34 /**
  35  * @class       AudioContentInfo
  36  * @brief       This class provides methods to access the audio content information.
  37  *
  38  * @since       2.0
  39  *
  40  * @final       This class is not intended for extension.
  41  *
  42  * The %AudioContentInfo class provides methods to access the audio content information that is extracted from a physical file. @n
  43  * Before getting the audio content information, ContentManager must be used to create the content.
  44  *
  45  * 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>.
  46  *
  47  * The following example demonstrates how to use the %AudioContentInfo class.
  48  *
  49  * @code
  50  * #include <FApp.h>
  51  * #include <FBase.h>
  52  * #include <FContent.h>
  53  * #include <FSystem.h>
  54  *
  55  * using namespace Tizen::Content;
  56  *
  57  * result
  58  * MyClass::TestAudioContentInfo(void)
  59  * {
  60  *              ContentManager contentManager;
  61  *              result r = contentManager.Construct();
  62  *
  63  *              AudioContentInfo audioContentInfo;
  64  *              r = audioContentInfo.Construct(null);
  65  *
  66  *              Tizen::Base::String sourcePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/flower.wma";
  67  *              Tizen::Base::String destPath = Tizen::System::Environment::GetMediaPath() + L"Sounds/flower.wma";
  68  *
  69  *              ContentId contentId = contentManager.CreateContent(sourcePath, destPath, false, &audioContentInfo);
  70  *              r = GetLastResult();
  71  *
  72  *              return r;
  73  * }
  74  * @endcode
  75  */
  76 class _OSP_EXPORT_ AudioContentInfo
  77         : public Tizen::Content::ContentInfo
  78 {
  79 public:
  80         /**
  81          * The object is not fully constructed after this constructor is called. @n
  82          * For full construction, the Construct() method must be called right after calling this constructor.
  83          *
  84          * @since               2.0
  85          */
  86         AudioContentInfo(void);
  87
  88         /**
  89          * This destructor overrides Tizen::Base::Object::~Object().
  90          *
  91          * @since               2.0
  92          */
  93         virtual ~AudioContentInfo(void);
  94
  95         /**
  96          * Initializes this instance of %AudioContentInfo with the specified parameter.
  97          *
  98          * @if OSPCOMPAT
  99          * @brief <i> [Compatibility] </i>
 100          * @endif
 101          * @since                       2.0
 102          * @if OSPCOMPAT
 103          * @compatibility  This method has compatibility issues with OSP compatible applications. @n
 104          *                 For more information, see @ref CompAudioContentInfoConstructPage "here".
 105          * @endif
 106          *
 107          * @return              An error code
 108          * @param[in]   pContentPath        The content path @n
 109          *                                                                      The path should be started with the directory path returned by
 110          *                                                                      either Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath(). @n
 111          *                                                                      If the path is @c null,
 112          *                                                                      use ContentManager::CreateContent(const Tizen::Base::ByteBuffer&, const Tizen::Base::String&, const ContentInfo*) @n
 113          *                                                                      or ContentManager::CreateContent(const Tizen::Base::String&, const Tizen::Base::String&, bool, const ContentInfo*),
 114          *                                                                      instead of this method.
 115          * @exception   E_SUCCESS                       The method is successful.
 116          * @exception   E_FILE_NOT_FOUND    The specified file cannot be found or accessed.
 117          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 118          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 119          * @exception   E_IO                            An I/O error has occurred.
 120          * @exception   E_SYSTEM                        An internal error has occurred.
 121          */
 122         result Construct(const Tizen::Base::String* pContentPath);
 123
 124         /**
 125          * @if OSPCOMPAT
 126          * @page        CompAudioContentInfoConstructPage Compatibility for the file path.
 127          * @section     CompAudioContentInfoConstructPageIssueSection Issues
 128          *          The content path argument of this method in OSP compatible applications has the following issues: @n
 129          *          -# The content path should be a path that begins with an allowed path prefix. @n
 130          *             For example, L"/Media/Images/flower.jpg", L"/Storagecard/Media/Images/flower.jpg".
 131          *
 132          * @section     CompAudioContentInfoConstructPageSolutionSection Resolutions
 133          *          This issue has been resolved in Tizen. @n
 134          *          -# The content path can be a path without a specific allowed path prefix. @n
 135          *             Application do not need to know the specific allowed path prefixes. @n
 136          *             To get the directory path, use the following methods: @n
 137          *             - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
 138          *             - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
 139          *
 140          * @endif
 141          */
 142
 143         /**
 144          * @if OSPDEPREC
 145          * Initializes this instance of %AudioContentInfo with the specified parameters.
 146          *
 147          * @brief       <i> [Deprecated] </i>
 148          * @deprecated  This method is deprecated as there is a problem in managing the user-defined thumbnail and device coordinates. @n
 149          *              Instead of using this method, use Construct(const Tizen::Base::String*). @n
 150          *              To set the coordinates of the ContentInfo instance, use ContentInfo::SetCoordinates(const Tizen::Locations::Coordinates&).
 151          * @since                       2.0
 152          *
 153          * @return              An error code
 154          * @param[in]   contentPath                             The content path
 155          * @param[in]   thumbnailPath                   The thumbnail path
 156          * @param[in]   setGps                                  Set to @c true to save the device's last known coordinates of the ContentInfo instance, @n
 157          *                                                                              else @c false @n
 158          *                                                                              The coordinate information may be incorrect if it is outdated or has never been updated. @n
 159          *                                      To update the coordinate information or to get the exact value,
 160          *                                      use Tizen::Locations::LocationProvider::RequestLocationUpdates() before calling this method.
 161          * @exception   E_SUCCESS                               The method is successful.
 162          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 163          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 164          * @exception   E_OUT_OF_MEMORY             The memory is insufficient.
 165          * @exception   E_IO                                    An I/O error has occurred.
 166          * @remarks
 167          *                               - The content path must start with @c '/Media' or @c '/Storagecard/Media'.
 168          *                               - The thumbnail path must start with @c '/Home', @c '/Media', or @c '/Storagecard/Media'. @n
 169          *                               - The permitted format for a thumbnail image is bitmap (bmp).
 170          * @endif
 171          */
 172         virtual result Construct(const Tizen::Base::String& contentPath, const Tizen::Base::String& thumbnailPath = L"", bool setGps = false);
 173
 174         /**
 175          * Gets the genre information of the audio file.
 176          *
 177          * @since               2.0
 178          *
 179          * @return              The genre information of the audio file, @n
 180          *              else @c Unknown if the value is empty
 181          */
 182         Tizen::Base::String GetGenre(void) const;
 183
 184         /**
 185          * Gets the artist information of the audio file.
 186          *
 187          * @since               2.0
 188          *
 189          * @return              The artist information of the audio file, @n
 190          *              else @c Unknown if the value is empty
 191          */
 192         Tizen::Base::String GetArtist(void) const;
 193
 194         /**
 195          * Gets the composer information of the audio file.
 196          *
 197          * @since               2.0
 198          *
 199          * @return              The composer information of the audio file, @n
 200          *              else @c Unknown if the value is empty
 201          */
 202         Tizen::Base::String GetComposer(void) const;
 203
 204         /**
 205          * Gets the album name of the audio file.
 206          *
 207          * @since               2.0
 208          *
 209          * @return              The album name of the audio file, @n
 210          *              else @c Unknown if the value is empty
 211          */
 212         Tizen::Base::String GetAlbumName(void) const;
 213
 214         /**
 215          * Gets the release year information of the audio file.
 216          *
 217          * @since               2.0
 218          *
 219          * @return              The release year information of the audio file
 220          */
 221         int GetReleaseYear(void) const;
 222
 223         /**
 224          * Gets the bit rate information of the audio file.
 225          *
 226          * @since               2.0
 227          *
 228          * @return              The bit rate in bits per second (bps)
 229          */
 230         int GetBitrate(void) const;
 231
 232         /**
 233          * Gets the title of the audio file.
 234          *
 235          * @since               2.0
 236          *
 237          * @return              The title of the audio file, @n
 238          *              else @c Unknown if the value is empty
 239          */
 240         Tizen::Base::String GetTitle(void) const;
 241
 242         /**
 243          * Gets the copyright of the audio file.
 244          *
 245          * @since               2.0
 246          *
 247          * @return              The copyright of the audio file, @n
 248          *              else @c Unknown if the value is empty
 249          */
 250         Tizen::Base::String GetCopyright(void) const;
 251
 252         /**
 253          * Gets the track information of the audio file.
 254          *
 255          * @since               2.0
 256          *
 257          * @return              The track information of the audio file, @n
 258          *              else @c Unknown if the value is empty
 259          */
 260         Tizen::Base::String GetTrackInfo(void) const;
 261
 262         /**
 263          * Gets the duration of the audio file.
 264          *
 265          * @since               2.0
 266          *
 267          * @return              The duration of the audio file in milliseconds
 268          */
 269         long GetDuration(void) const;
 270
 271 private:
 272
 273         /**
 274          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 275          */
 276         AudioContentInfo(const AudioContentInfo& rhs);
 277
 278         /**
 279          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 280          */
 281         AudioContentInfo& operator =(const AudioContentInfo& rhs);
 282
 283 private:
 284
 285         _AudioContentData* __pAudioContentData;
 286         _AudioContentInfoImpl* __pAudioContentInfoImpl;
 287         friend class _AudioContentInfoImpl;
 288
 289 };  // AudioContentInfo
 290
 291 }}  // Tizen::Content
 292
 293 #endif  // _FCNT_AUDIO_CONTENT_INFO_H_