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 @n
 217          *                              The value can be different for each device
 218          * @param[in]   filePath                                                The file path
 219          * @exception   E_SUCCESS                                               The method is successful.
 220          * @exception   E_INVALID_ARG                                   The specified input parameter is invalid, or
 221          *                                                          the length of the specified path is @c 0 or exceeds system limitations.
 222          * @exception   E_FILE_NOT_FOUND                        The specified file cannot be found.
 223          * @exception   E_UNSUPPORTED_FORMAT    The specified format is invalid or not supported.
 224          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 225          */
 226         static Tizen::Content::ContentType CheckContentType(const Tizen::Base::String& filePath);
 227
 228         /**
 229          * @if OSPDEPREC
 230          * Copies an existing file to a new directory.
 231          *
 232          * @brief       <i> [Deprecated] </i>
 233          * @deprecated   This method is deprecated because a new method has been added. @n
 234          *                       Instead of using this method, use ContentManager::CreateContent(const Tizen::Base::String&, const Tizen::Base::String&, bool, const ContentInfo*).
 235          * @since                       2.0
 236          *
 237          * @return                      An error code
 238          * @param[in]           srcFilePath                             The source file path
 239          * @param[in]           destFilePath                            The destination file path
 240          * @exception           E_SUCCESS                                       The method is successful.
 241          * @exception           E_INVALID_ARG                           Either of the following conditions has occurred: @n
 242          *                                                                                                                      - The length of the specified path is equal to @c 0 or exceeds system limitations. @n
 243          *                                                                                                                      - The specified path contains prohibited character(s). @n
 244          *                                                                                                                      - The specified path is invalid.
 245          * @exception           E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 246          * @exception           E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 247          * @exception           E_FILE_ALREADY_EXIST    The specified file already exists.
 248          * @exception           E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 249          * @exception           E_STORAGE_FULL                  The disk space is full.
 250          * @exception           E_IO                                                            Either of the following conditions has occurred: @n
 251          *                                                           - An unexpected device failure has occurred as the media ejected suddenly. @n
 252          *                                                           - File corruption is detected. @n
 253          *                                                           - The volume or quota is no more available.
 254          * @remarks
 255          *                               - The source file in the system region cannot be copied.
 256          *                               - The destination file path must start with @c '/Media' or @c '/Storagecard/Media'.
 257          * @endif
 258          */
 259         static result CopyToMediaDirectory(const Tizen::Base::String& srcFilePath, const Tizen::Base::String& destFilePath);
 260
 261         /**
 262          * @if OSPDEPREC
 263          * Moves the file to a new directory.
 264          *
 265          * @brief       <i> [Deprecated] </i>
 266          * @deprecated   This method is deprecated because a new method has been added. @n
 267          *                       Instead of using this method, use ContentManager::CreateContent(const Tizen::Base::String&, const Tizen::Base::String&, bool, const ContentInfo*).
 268          * @since                       2.0
 269          *
 270          * @return                      An error code
 271          * @param[in]           srcFilePath                             The source file path
 272          * @param[in]           destFilePath                            The destination file path
 273          * @exception           E_SUCCESS                                       The method is successful.
 274          * @exception           E_INVALID_ARG                           Either of the following conditions has occurred: @n
 275          *                                                           - The length of the specified path is equal to @c 0 or exceeds system limitations. @n
 276          *                                                           - The specified path contains prohibited character(s). @n
 277          *                                                           - The specified path is invalid.
 278          * @exception           E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 279          * @exception           E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 280          * @exception           E_FILE_ALREADY_EXIST    The specified file already exists.
 281          * @exception           E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 282          * @exception           E_STORAGE_FULL                  The disk space is full.
 283          * @exception           E_IO                                                            Either of the following conditions has occurred: @n
 284          *                                                                                                                      - An unexpected device failure has occurred as the media ejected suddenly. @n
 285          *                                                                                                                      - File corruption is detected. @n
 286          *                                                                                                                      - The volume or quota is no more available.
 287          * @remarks
 288          *                       - The source file in the system region cannot be copied.
 289          *                       - The destination file path must start with @c '/Media' or @c '/Storagecard/Media'.
 290          * @endif
 291          */
 292         static result MoveToMediaDirectory(const Tizen::Base::String& srcFilePath, const Tizen::Base::String& destFilePath);
 293
 294         /**
 295          * @if OSPCOMPAT
 296          * @page        CompContentManagerUtilPage Compatibility for the file path.
 297          * @section     CompContentManagerUtilPageIssueSection Issues
 298          *                 The file path argument of this method in OSP compatible applications has the following issues: @n
 299          *                 -# The file path should be a path that begins with an allowed path prefix. @n
 300          *                     For example, L"/Media/Images/flower.jpg", "/Storagecard/Media/Images/flower.jpg".
 301          *
 302          * @section     CompContentManagerUtilPageSolutionSection Resolutions
 303          *                 This issue has been resolved in Tizen. @n
 304          *                 -# The file path can be a path without a specific allowed path prefix. @n
 305          *                 Application do not need to know the specific allowed path prefixes. @n
 306          *                 To get the directory path, use the following methods: @n
 307          *                 - For accessing the home directory, use Tizen::App::App::GetInstance()->GetAppRootPath().
 308          *                 - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
 309          *                 - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
 310          *
 311          * @endif
 312          */
 313
 314 private:
 315         /**
 316          * This default constructor is intentionally declared as private because this class cannot be constructed.
 317          */
 318         ContentManagerUtil(void);
 319
 320         /**
 321          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 322          */
 323         ContentManagerUtil(const ContentManagerUtil& rhs);
 324
 325         /**
 326          * This destructor is intentionally declared as private because this class cannot be constructed.
 327          */
 328         virtual ~ContentManagerUtil(void);
 329
 330         /**
 331          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 332          */
 333         ContentManagerUtil& operator =(const ContentManagerUtil& rhs);
 334
 335 };  // class ContentManagerUtil
 336
 337 }}  // Tizen::Content
 338
 339 #endif  // _FCNT_CONTENT_MANAGER_UTIL_H_