inc/FCntContentManagerUtil.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  * @file                        FCntContentManagerUtil.h
  19  * @brief               This is the header file for the %ContentManagerUtil class.
  20  *
  21  * This header file contains the declarations of the %ContentManagerUtil class.
  22  */
  23
  24 #ifndef _FCNT_CONTENT_MANAGER_UTIL_H_
  25 #define _FCNT_CONTENT_MANAGER_UTIL_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FCntTypes.h>
  29
  30 namespace Tizen { namespace Content
  31 {
  32
  33 class ImageMetadata;
  34 class AudioMetadata;
  35 class VideoMetadata;
  36
  37 /**
  38  * @class       ContentManagerUtil
  39  * @brief       This class provides methods for managing the content's utility.
  40  *
  41  * @since       2.0
  42  *
  43  * The %ContentManagerUtil class provides access to different local content types, such as image, audio, and video, and manages the content metadata.
  44  *
  45  * 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>.
  46  *
  47  * The following example demonstrates how to use the %ContentManagerUtil class.
  48  *
  49  * @code
  50  * result
  51  * MyClass::TestContentManagerUtil(void)
  52  * {
  53  *              // Image
  54  *              Tizen::Base::String imagePath = Tizen::System::Environment::GetMediaPath() + L"Images/full_meta.jpg";
  55  *              ImageMetadata* pImageMeta = ContentManagerUtil::GetImageMetaN(imagePath);
  56  *              TryReturn(pImageMeta != null, GetLastResult(), "GetImageMetaN failed.");
  57  *
  58  *              // Audio
  59  *              Tizen::Base::String audioPath = Tizen::System::Environment::GetMediaPath() + L"Sounds/hot.mp3";
  60  *              AudioMetadata* pAudioMeta = ContentManagerUtil::GetAudioMetaN(audioPath);
  61  *              if(pAudioMeta == null)
  62  *              {
  63  *                      delete pImageMeta;
  64  *                      return GetLastResult();
  65  *              }
  66  *
  67  *              // Video
  68  *              Tizen::Base::String videoPath = Tizen::System::Environment::GetMediaPath() + L"Videos/video.mp4";
  69  *              VideoMetadata* pVideoMeta = ContentManagerUtil::GetVideoMetaN(videoPath);
  70  *              if(pVideoMeta == null)
  71  *              {
  72  *                      delete pImageMeta;
  73  *                      delete pAudioMeta;
  74  *                      return GetLastResult();
  75  *              }
  76  *
  77  *              delete pImageMeta;
  78  *              delete pAudioMeta;
  79  *              delete pVideoMeta;
  80  *
  81  *              return E_SUCCESS;
  82  * }
  83  * @endcode
  84  */
  85 class _OSP_EXPORT_ ContentManagerUtil
  86 {
  87 public:
  88         /**
  89          * Gets the metadata for an image from the file.
  90          *
  91          * @if OSPCOMPAT
  92          * @brief       <i> [Compatibility] </i>
  93          * @endif
  94          * @since                       2.0
  95          * @if OSPCOMPAT
  96          * @compatibility This method has compatibility issues with OSP compatible applications. @n
  97          *                       For more information, see @ref CompContentManagerUtilPage "here".
  98          * @endif
  99          *
 100          * @return                      A pointer to ImageMetadata, @n
 101          *                     else @c null if an exception occurs
 102          * @param[in]   filePath                                        The file path
 103          * @exception   E_SUCCESS                                       The method is successful.
 104          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 105          * @remarks
 106          *                              - If the image data is valid but meta information does not exist, the width and height are set from actual image data.
 107          *                              - The specific error code can be accessed using the GetLastResult() method.
 108          */
 109         static Tizen::Content::ImageMetadata* GetImageMetaN(const Tizen::Base::String& filePath);
 110
 111         /**
 112          * Gets the metadata for an image from the buffer.
 113          *
 114          * @since               2.1
 115          *
 116          * @return                      A pointer to ImageMetadata, @n
 117          *                     else @c null if an exception occurs
 118          * @param[in]   byteBuffer                                      The buffer that contains image data
 119          * @exception   E_SUCCESS                                       The method is successful.
 120          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 121          * @remarks
 122          *                              - If the image data in the buffer is valid but meta information does not exist, the width and height are set from actual image data.
 123          *                              - The specific error code can be accessed using the GetLastResult() method.
 124          */
 125         static Tizen::Content::ImageMetadata* GetImageMetaN(const Tizen::Base::ByteBuffer& byteBuffer);
 126
 127         /**
 128          * Gets the metadata for an audio from the file.
 129          *
 130          * @if OSPCOMPAT
 131          * @brief       <i> [Compatibility] </i>
 132          * @endif
 133          * @since                       2.0
 134          * @if OSPCOMPAT
 135          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 136          *                       For more information, see @ref CompContentManagerUtilPage "here".
 137          * @endif
 138          *
 139          * @return                      A pointer to AudioMetadata, @n
 140          *                     else @c null if an exception occurs
 141          * @param[in]   filePath                                        The file path
 142          * @exception   E_SUCCESS                                       The method is successful.
 143          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 144          * @remarks
 145          *                              - If the audio data is valid but meta information does not exist, the duration is set from actual audio data.
 146          *                              - The specific error code can be accessed using the GetLastResult() method.
 147          */
 148         static Tizen::Content::AudioMetadata* GetAudioMetaN(const Tizen::Base::String& filePath);
 149
 150         /**
 151          * Gets the metadata for an audio from the buffer.
 152          *
 153          * @since               2.1
 154          *
 155          * @return                      A pointer to AudioMetadata, @n
 156          *                     else @c null if an exception occurs
 157          * @param[in]   byteBuffer                                      The buffer that contains audio data
 158          * @exception   E_SUCCESS                                       The method is successful.
 159          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 160          * @remarks
 161          *                              - If the audio data in the buffer is valid but meta information does not exist, the duration is set from actual audio data.
 162          *                              - The specific error code can be accessed using the GetLastResult() method.
 163          */
 164         static Tizen::Content::AudioMetadata* GetAudioMetaN(const Tizen::Base::ByteBuffer& byteBuffer);
 165
 166         /**
 167          * Gets the metadata for a video from the file.
 168          *
 169          * @if OSPCOMPAT
 170          * @brief       <i> [Compatibility] </i>
 171          * @endif
 172          * @since                       2.0
 173          * @if OSPCOMPAT
 174          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 175          *                       For more information, see @ref CompContentManagerUtilPage "here".
 176          * @endif
 177          *
 178          * @return                      A pointer to VideoMetadata, @n
 179          *                     else @c null if an exception occurs
 180          * @param[in]   filePath                                        The file path
 181          * @exception   E_SUCCESS                                       The method is successful.
 182          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 183          * @remarks
 184          *                              - If the video data is valid but meta information does not exist, the duration is set from actual video data.
 185          *                              - The specific error code can be accessed using the GetLastResult() method.
 186          */
 187         static Tizen::Content::VideoMetadata* GetVideoMetaN(const Tizen::Base::String& filePath);
 188
 189         /**
 190          * Gets the metadata for a video from the buffer.
 191          *
 192          * @since               2.1
 193          *
 194          * @return                      A pointer to VideoMetadata, @n
 195          *                     else @c null if an exception occurs
 196          * @param[in]   byteBuffer                                      The buffer that contains video data
 197          * @exception   E_SUCCESS                                       The method is successful.
 198          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 199          * @remarks
 200          *                              - If the video data in the buffer is valid but meta information does not exist, the duration is set from actual video data.
 201          *                              - The specific error code can be accessed using the GetLastResult() method.
 202          */
 203         static Tizen::Content::VideoMetadata* GetVideoMetaN(const Tizen::Base::ByteBuffer& byteBuffer);
 204
 205         /**
 206          * Checks the content type from the file path.
 207          *
 208          * @if OSPCOMPAT
 209          * @brief       <i> [Compatibility] </i>
 210          * @endif
 211          * @since           2.0
 212          * @if OSPCOMPAT
 213          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 214          *                       For more information, see @ref CompContentManagerUtilPage "here".
 215          * @endif
 216          *
 217          * @return              The content type
 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
 225          *                              - The content type can be different for each device.
 226          *                              - The specific error code can be accessed using the GetLastResult() method.
 227          */
 228         static Tizen::Content::ContentType CheckContentType(const Tizen::Base::String& filePath);
 229
 230         /**
 231          * @if OSPDEPREC
 232          * Copies an existing file to a new directory.
 233          *
 234          * @brief       <i> [Deprecated] </i>
 235          * @deprecated   This method is deprecated because a new method has been added. @n
 236          *                       Instead of using this method, use ContentManager::CreateContent(const Tizen::Base::String&, const Tizen::Base::String&, bool, const ContentInfo*).
 237          * @since                       2.0
 238          *
 239          * @return                      An error code
 240          * @param[in]           srcFilePath                             The source file path
 241          * @param[in]           destFilePath                            The destination file path
 242          * @exception           E_SUCCESS                                       The method is successful.
 243          * @exception           E_INVALID_ARG                           Either of the following conditions has occurred: @n
 244          *                                                                                                                      - The length of the specified path is equal to @c 0 or exceeds system limitations. @n
 245          *                                                                                                                      - The specified path contains prohibited character(s). @n
 246          *                                                                                                                      - The specified path is invalid.
 247          * @exception           E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 248          * @exception           E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 249          * @exception           E_FILE_ALREADY_EXIST    The specified file already exists.
 250          * @exception           E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 251          * @exception           E_STORAGE_FULL                  The disk space is full.
 252          * @exception           E_IO                                                            Either of the following conditions has occurred: @n
 253          *                                                           - An unexpected device failure has occurred as the media ejected suddenly. @n
 254          *                                                           - File corruption is detected. @n
 255          *                                                           - The volume or quota is no more available.
 256          * @remarks             The source file in the system region cannot be copied. @n
 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             The source file in the system region cannot be copied. @n
 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_