inc/FCntContentManagerUtil.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                        FCntContentManagerUtil.h
  18  * @brief               This is the header file for the %ContentManagerUtil class.
  19  *
  20  * This header file contains the declarations of the %ContentManagerUtil class.
  21  */
  22
  23 #ifndef _FCNT_CONTENT_MANAGER_UTIL_H_
  24 #define _FCNT_CONTENT_MANAGER_UTIL_H_
  25
  26 #include <FBaseObject.h>
  27 #include <FCntTypes.h>
  28
  29 namespace Tizen { namespace Content
  30 {
  31
  32 class ImageMetadata;
  33 class AudioMetadata;
  34 class VideoMetadata;
  35
  36 /**
  37  * @class       ContentManagerUtil
  38  * @brief       This class provides methods for managing the content's utility.
  39  *
  40  * @since       2.0
  41  *
  42  * The %ContentManagerUtil class provides access to different local content types, such as image, audio, and video, and manages the content metadata.
  43  *
  44  * For more information on managing the content's utility on the device, see <a href="../org.tizen.native.appprogramming/html/guide/content/device_content_mgmt.htm">Device Content Management</a>.
  45  *
  46  * The following example demonstrates how to use the %ContentManagerUtil class.
  47  *
  48  * @code
  49  * result
  50  * MyClass::TestContentManagerUtil(void)
  51  * {
  52  *              // Image
  53  *              Tizen::Base::String imagePath = Tizen::System::Environment::GetMediaPath() + L"Images/full_meta.jpg";
  54  *              ImageMetadata* pImageMeta = ContentManagerUtil::GetImageMetaN(imagePath);
  55  *              TryReturn(pImageMeta != null, GetLastResult(), "GetImageMetaN failed.");
  56  *
  57  *              // Audio
  58  *              Tizen::Base::String audioPath = Tizen::System::Environment::GetMediaPath() + L"Sounds/hot.mp3";
  59  *              AudioMetadata* pAudioMeta = ContentManagerUtil::GetAudioMetaN(audioPath);
  60  *              if(pAudioMeta == null)
  61  *              {
  62  *                      delete pImageMeta;
  63  *                      return GetLastResult();
  64  *              }
  65  *
  66  *              // Video
  67  *              Tizen::Base::String videoPath = Tizen::System::Environment::GetMediaPath() + L"Videos/video.mp4";
  68  *              VideoMetadata* pVideoMeta = ContentManagerUtil::GetVideoMetaN(videoPath);
  69  *              if(pVideoMeta == null)
  70  *              {
  71  *                      delete pImageMeta;
  72  *                      delete pAudioMeta;
  73  *                      return GetLastResult();
  74  *              }
  75  *
  76  *              delete pImageMeta;
  77  *              delete pAudioMeta;
  78  *              delete pVideoMeta;
  79  *
  80  *              return E_SUCCESS;
  81  * }
  82  * @endcode
  83  */
  84 class _OSP_EXPORT_ ContentManagerUtil
  85 {
  86 public:
  87         /**
  88          * Gets the metadata for an image from the file.
  89          *
  90          * @if OSPCOMPAT
  91          * @brief       <i> [Compatibility] </i>
  92          * @endif
  93          * @since                       2.0
  94          * @if OSPCOMPAT
  95          * @compatibility This method has compatibility issues with OSP compatible applications. @n
  96          *                       For more information, see @ref CompContentManagerUtilPage "here".
  97          * @endif
  98          *
  99          * @return                      A pointer to ImageMetadata, @n
 100          *                     else @c null if an exception occurs
 101          * @param[in]   filePath                                        The file path
 102          * @exception   E_SUCCESS                                       The method is successful.
 103          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 104          * @remarks
 105          *                              - If the image data is valid but meta information does not exist, the width and height are set from the actual image data.
 106          *                              - The specific error code can be accessed using the GetLastResult() method.
 107          */
 108         static Tizen::Content::ImageMetadata* GetImageMetaN(const Tizen::Base::String& filePath);
 109
 110         /**
 111          * Gets the metadata for an image from the buffer.
 112          *
 113          * @since               2.1
 114          *
 115          * @return                      A pointer to ImageMetadata, @n
 116          *                     else @c null if an exception occurs
 117          * @param[in]   byteBuffer                                      The buffer that contains image data
 118          * @exception   E_SUCCESS                                       The method is successful.
 119          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 120          * @remarks
 121          *                              - If the image data in the buffer is valid but meta information does not exist, the width and height are set from the actual image data.
 122          *                              - The specific error code can be accessed using the GetLastResult() method.
 123          */
 124         static Tizen::Content::ImageMetadata* GetImageMetaN(const Tizen::Base::ByteBuffer& byteBuffer);
 125
 126         /**
 127          * Gets the metadata for an audio from the file.
 128          *
 129          * @if OSPCOMPAT
 130          * @brief       <i> [Compatibility] </i>
 131          * @endif
 132          * @since                       2.0
 133          * @if OSPCOMPAT
 134          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 135          *                       For more information, see @ref CompContentManagerUtilPage "here".
 136          * @endif
 137          *
 138          * @return                      A pointer to AudioMetadata, @n
 139          *                     else @c null if an exception occurs
 140          * @param[in]   filePath                                        The file path
 141          * @exception   E_SUCCESS                                       The method is successful.
 142          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 143          * @remarks
 144          *                              - If the audio data is valid but meta information does not exist, the duration is set from the actual audio data.
 145          *                              - The specific error code can be accessed using the GetLastResult() method.
 146          */
 147         static Tizen::Content::AudioMetadata* GetAudioMetaN(const Tizen::Base::String& filePath);
 148
 149         /**
 150          * Gets the metadata for an audio from the buffer.
 151          *
 152          * @since               2.1
 153          *
 154          * @return                      A pointer to AudioMetadata, @n
 155          *                     else @c null if an exception occurs
 156          * @param[in]   byteBuffer                                      The buffer that contains audio data
 157          * @exception   E_SUCCESS                                       The method is successful.
 158          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 159          * @remarks
 160          *                              - If the audio data in the buffer is valid but meta information does not exist, the duration is set from the actual audio data.
 161          *                              - The specific error code can be accessed using the GetLastResult() method.
 162          */
 163         static Tizen::Content::AudioMetadata* GetAudioMetaN(const Tizen::Base::ByteBuffer& byteBuffer);
 164
 165         /**
 166          * Gets the metadata for a video from the file.
 167          *
 168          * @if OSPCOMPAT
 169          * @brief       <i> [Compatibility] </i>
 170          * @endif
 171          * @since                       2.0
 172          * @if OSPCOMPAT
 173          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 174          *                       For more information, see @ref CompContentManagerUtilPage "here".
 175          * @endif
 176          *
 177          * @return                      A pointer to VideoMetadata, @n
 178          *                     else @c null if an exception occurs
 179          * @param[in]   filePath                                        The file path
 180          * @exception   E_SUCCESS                                       The method is successful.
 181          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 182          * @remarks
 183          *                              - If the video data is valid but meta information does not exist, the duration is set from the actual video data.
 184          *                              - The specific error code can be accessed using the GetLastResult() method.
 185          */
 186         static Tizen::Content::VideoMetadata* GetVideoMetaN(const Tizen::Base::String& filePath);
 187
 188         /**
 189          * Gets the metadata for a video from the buffer.
 190          *
 191          * @since               2.1
 192          *
 193          * @return                      A pointer to VideoMetadata, @n
 194          *                     else @c null if an exception occurs
 195          * @param[in]   byteBuffer                                      The buffer that contains video data
 196          * @exception   E_SUCCESS                                       The method is successful.
 197          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 198          * @remarks
 199          *                              - If the video data in the buffer is valid but meta information does not exist, the duration is set from the actual video data.
 200          *                              - The specific error code can be accessed using the GetLastResult() method.
 201          */
 202         static Tizen::Content::VideoMetadata* GetVideoMetaN(const Tizen::Base::ByteBuffer& byteBuffer);
 203
 204         /**
 205          * Checks the content type from the file path.
 206          *
 207          * @if OSPCOMPAT
 208          * @brief       <i> [Compatibility] </i>
 209          * @endif
 210          * @since           2.0
 211          * @if OSPCOMPAT
 212          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 213          *                       For more information, see @ref CompContentManagerUtilPage "here".
 214          * @endif
 215          *
 216          * @return              The content type
 217          * @param[in]   filePath                                                The file path
 218          * @exception   E_SUCCESS                                               The method is successful.
 219          * @exception   E_INVALID_ARG                                   The specified input parameter is invalid, or
 220          *                                                          the length of the specified path is @c 0 or exceeds system limitations.
 221          * @exception   E_FILE_NOT_FOUND                        The specified file cannot be found.
 222          * @exception   E_UNSUPPORTED_FORMAT    The specified format is invalid or not supported.
 223          * @remarks
 224          *                              - The content type can be different for each device.
 225          *                              - The specific error code can be accessed using the GetLastResult() method.
 226          */
 227         static Tizen::Content::ContentType CheckContentType(const Tizen::Base::String& filePath);
 228
 229         /**
 230          * @if OSPDEPREC
 231          * Copies an existing file to a new directory.
 232          *
 233          * @brief       <i> [Deprecated] </i>
 234          * @deprecated   This method is deprecated because a new method has been added. @n
 235          *                       Instead of using this method, use ContentManager::CreateContent(const Tizen::Base::String&, const Tizen::Base::String&, bool, const ContentInfo*).
 236          * @since                       2.0
 237          *
 238          * @return                      An error code
 239          * @param[in]           srcFilePath                             The source file path
 240          * @param[in]           destFilePath                            The destination file path
 241          * @exception           E_SUCCESS                                       The method is successful.
 242          * @exception           E_INVALID_ARG                           Either of the following conditions has occurred: @n
 243          *                                                                                                                      - The length of the specified path is equal to @c 0 or exceeds system limitations. @n
 244          *                                                                                                                      - The specified path contains prohibited character(s). @n
 245          *                                                                                                                      - The specified path is invalid.
 246          * @exception           E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 247          * @exception           E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 248          * @exception           E_FILE_ALREADY_EXIST    The specified file already exists.
 249          * @exception           E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 250          * @exception           E_STORAGE_FULL                  The disk space is full.
 251          * @exception           E_IO                                                            Either of the following conditions has occurred: @n
 252          *                                                           - An unexpected device failure has occurred as the media ejected suddenly. @n
 253          *                                                           - File corruption is detected. @n
 254          *                                                           - The volume or quota is no more available.
 255          * @remarks
 256          *                               - The source file in the system region cannot be copied.
 257          *                               - The destination file path must start with @c '/Media' or @c '/Storagecard/Media'.
 258          * @endif
 259          */
 260         static result CopyToMediaDirectory(const Tizen::Base::String& srcFilePath, const Tizen::Base::String& destFilePath);
 261
 262         /**
 263          * @if OSPDEPREC
 264          * Moves the file to a new directory.
 265          *
 266          * @brief       <i> [Deprecated] </i>
 267          * @deprecated   This method is deprecated because a new method has been added. @n
 268          *                       Instead of using this method, use ContentManager::CreateContent(const Tizen::Base::String&, const Tizen::Base::String&, bool, const ContentInfo*).
 269          * @since                       2.0
 270          *
 271          * @return                      An error code
 272          * @param[in]           srcFilePath                             The source file path
 273          * @param[in]           destFilePath                            The destination file path
 274          * @exception           E_SUCCESS                                       The method is successful.
 275          * @exception           E_INVALID_ARG                           Either of the following conditions has occurred: @n
 276          *                                                           - The length of the specified path is equal to @c 0 or exceeds system limitations. @n
 277          *                                                           - The specified path contains prohibited character(s). @n
 278          *                                                           - The specified path is invalid.
 279          * @exception           E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 280          * @exception           E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 281          * @exception           E_FILE_ALREADY_EXIST    The specified file already exists.
 282          * @exception           E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 283          * @exception           E_STORAGE_FULL                  The disk space is full.
 284          * @exception           E_IO                                                            Either of the following conditions has occurred: @n
 285          *                                                                                                                      - An unexpected device failure has occurred as the media ejected suddenly. @n
 286          *                                                                                                                      - File corruption is detected. @n
 287          *                                                                                                                      - The volume or quota is no more available.
 288          * @remarks
 289          *                       - The source file in the system region cannot be copied.
 290          *                       - The destination file path must start with @c '/Media' or @c '/Storagecard/Media'.
 291          * @endif
 292          */
 293         static result MoveToMediaDirectory(const Tizen::Base::String& srcFilePath, const Tizen::Base::String& destFilePath);
 294
 295         /**
 296          * @if OSPCOMPAT
 297          * @page        CompContentManagerUtilPage Compatibility for the file path.
 298          * @section     CompContentManagerUtilPageIssueSection Issues
 299          *                 The file path argument of this method in OSP compatible applications has the following issues: @n
 300          *                 -# The file path should be a path that begins with an allowed path prefix. @n
 301          *                     For example, L"/Media/Images/flower.jpg", "/Storagecard/Media/Images/flower.jpg".
 302          *
 303          * @section     CompContentManagerUtilPageSolutionSection Resolutions
 304          *                 This issue has been resolved in Tizen. @n
 305          *                 -# The file path can be a path without a specific allowed path prefix. @n
 306          *                 Application do not need to know the specific allowed path prefixes. @n
 307          *                 To get the directory path, use the following methods: @n
 308          *                 - For accessing the home directory, use Tizen::App::App::GetInstance()->GetAppRootPath().
 309          *                 - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
 310          *                 - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
 311          *
 312          * @endif
 313          */
 314
 315 private:
 316         /**
 317          * This default constructor is intentionally declared as private because this class cannot be constructed.
 318          */
 319         ContentManagerUtil(void);
 320
 321         /**
 322          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 323          */
 324         ContentManagerUtil(const ContentManagerUtil& rhs);
 325
 326         /**
 327          * This destructor is intentionally declared as private because this class cannot be constructed.
 328          */
 329         virtual ~ContentManagerUtil(void);
 330
 331         /**
 332          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 333          */
 334         ContentManagerUtil& operator =(const ContentManagerUtil& rhs);
 335
 336 };  // class ContentManagerUtil
 337
 338 }}  // Tizen::Content
 339
 340 #endif  // _FCNT_CONTENT_MANAGER_UTIL_H_