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     If the image data is valid but meta information does not exist, the width and height are set from 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     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.
 121          *                              The specific error code can be accessed using the GetLastResult() method.
 122          */
 123         static Tizen::Content::ImageMetadata* GetImageMetaN(const Tizen::Base::ByteBuffer& byteBuffer);
 124
 125         /**
 126          * Gets the metadata for an audio from the file.
 127          *
 128          * @if OSPCOMPAT
 129          * @brief       <i> [Compatibility] </i>
 130          * @endif
 131          * @since                       2.0
 132          * @if OSPCOMPAT
 133          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 134          *                       For more information, see @ref CompContentManagerUtilPage "here".
 135          * @endif
 136          *
 137          * @return                      A pointer to AudioMetadata, @n
 138          *                     else @c null if an exception occurs
 139          * @param[in]   filePath                                        The file path
 140          * @exception   E_SUCCESS                                       The method is successful.
 141          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 142          * @remarks     If the audio data is valid but meta information does not exist, the duration is set from actual audio data.
 143          *                              The specific error code can be accessed using the GetLastResult() method.
 144          */
 145         static Tizen::Content::AudioMetadata* GetAudioMetaN(const Tizen::Base::String& filePath);
 146
 147         /**
 148          * Gets the metadata for an audio from the buffer.
 149          *
 150          * @since               2.1
 151          *
 152          * @return                      A pointer to AudioMetadata, @n
 153          *                     else @c null if an exception occurs
 154          * @param[in]   byteBuffer                                      The buffer that contains audio data
 155          * @exception   E_SUCCESS                                       The method is successful.
 156          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 157          * @remarks     If the audio data in the buffer is valid but meta information does not exist, the duration is set from actual audio data.
 158          *                              The specific error code can be accessed using the GetLastResult() method.
 159          */
 160         static Tizen::Content::AudioMetadata* GetAudioMetaN(const Tizen::Base::ByteBuffer& byteBuffer);
 161
 162         /**
 163          * Gets the metadata for a video from the file.
 164          *
 165          * @if OSPCOMPAT
 166          * @brief       <i> [Compatibility] </i>
 167          * @endif
 168          * @since                       2.0
 169          * @if OSPCOMPAT
 170          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 171          *                       For more information, see @ref CompContentManagerUtilPage "here".
 172          * @endif
 173          *
 174          * @return                      A pointer to VideoMetadata, @n
 175          *                     else @c null if an exception occurs
 176          * @param[in]   filePath                                        The file path
 177          * @exception   E_SUCCESS                                       The method is successful.
 178          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 179          * @remarks     If the video data is valid but meta information does not exist, the duration is set from actual video data.
 180          *                              The specific error code can be accessed using the GetLastResult() method.
 181          */
 182         static Tizen::Content::VideoMetadata* GetVideoMetaN(const Tizen::Base::String& filePath);
 183
 184         /**
 185          * Gets the metadata for a video from the buffer.
 186          *
 187          * @since               2.1
 188          *
 189          * @return                      A pointer to VideoMetadata, @n
 190          *                     else @c null if an exception occurs
 191          * @param[in]   byteBuffer                                      The buffer that contains video data
 192          * @exception   E_SUCCESS                                       The method is successful.
 193          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 194          * @remarks     If the video data in the buffer is valid but meta information does not exist, the duration is set from actual video data.
 195          *                              The specific error code can be accessed using the GetLastResult() method.
 196          */
 197         static Tizen::Content::VideoMetadata* GetVideoMetaN(const Tizen::Base::ByteBuffer& byteBuffer);
 198
 199         /**
 200          * Checks the content type from the file path.
 201          *
 202          * @if OSPCOMPAT
 203          * @brief       <i> [Compatibility] </i>
 204          * @endif
 205          * @since           2.0
 206          * @if OSPCOMPAT
 207          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 208          *                       For more information, see @ref CompContentManagerUtilPage "here".
 209          * @endif
 210          *
 211          * @return                      The content type
 212          * @param[in]   filePath                                                The file path
 213          * @exception   E_SUCCESS                                               The method is successful.
 214          * @exception   E_INVALID_ARG                                   The specified input parameter is invalid, or
 215          *                                                          the length of the specified path is @c 0 or exceeds system limitations.
 216          * @exception   E_FILE_NOT_FOUND                        The specified file cannot be found.
 217          * @exception    E_UNSUPPORTED_FORMAT   The specified format is invalid or not supported.
 218          * @remarks             The content type can be different for each device. @n
 219          *                     The specific error code can be accessed using the GetLastResult() method.
 220          */
 221         static Tizen::Content::ContentType CheckContentType(const Tizen::Base::String& filePath);
 222
 223         /**
 224          * @if OSPDEPREC
 225          * Copies an existing file to a new directory.
 226          *
 227          * @brief       <i> [Deprecated] </i>
 228          * @deprecated   This method is deprecated because a new method has been added. @n
 229          *                       Instead of using this method, use ContentManager::CreateContent(const Tizen::Base::String&, const Tizen::Base::String&, bool, const ContentInfo*).
 230          * @since                       2.0
 231          *
 232          * @return                      An error code
 233          * @param[in]           srcFilePath                             The source file path
 234          * @param[in]           destFilePath                            The destination file path
 235          * @exception           E_SUCCESS                                       The method is successful.
 236          * @exception           E_INVALID_ARG                           Either of the following conditions has occurred: @n
 237          *                                                                                                                      - The length of the specified path is equal to @c 0 or exceeds system limitations. @n
 238          *                                                                                                                      - The specified path contains prohibited character(s). @n
 239          *                                                                                                                      - The specified path is invalid.
 240          * @exception           E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 241          * @exception           E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 242          * @exception           E_FILE_ALREADY_EXIST    The specified file already exists.
 243          * @exception           E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 244          * @exception           E_STORAGE_FULL                  The disk space is full.
 245          * @exception           E_IO                                                            Either of the following conditions has occurred: @n
 246          *                                                           - An unexpected device failure has occurred as the media ejected suddenly. @n
 247          *                                                           - File corruption is detected. @n
 248          *                                                           - The volume or quota is no more available.
 249          * @remarks             The source file in the system region cannot be copied. @n
 250          *                       The destination file path must start with @c '/Media' or @c '/Storagecard/Media'.
 251          * @endif
 252          */
 253         static result CopyToMediaDirectory(const Tizen::Base::String& srcFilePath, const Tizen::Base::String& destFilePath);
 254
 255         /**
 256          * @if OSPDEPREC
 257          * Moves the file to a new directory.
 258          *
 259          * @brief       <i> [Deprecated] </i>
 260          * @deprecated   This method is deprecated because a new method has been added. @n
 261          *                       Instead of using this method, use ContentManager::CreateContent(const Tizen::Base::String&, const Tizen::Base::String&, bool, const ContentInfo*).
 262          * @since                       2.0
 263          *
 264          * @return                      An error code
 265          * @param[in]           srcFilePath                             The source file path
 266          * @param[in]           destFilePath                            The destination file path
 267          * @exception           E_SUCCESS                                       The method is successful.
 268          * @exception           E_INVALID_ARG                           Either of the following conditions has occurred: @n
 269          *                                                           - The length of the specified path is equal to @c 0 or exceeds system limitations. @n
 270          *                                                           - The specified path contains prohibited character(s). @n
 271          *                                                           - The specified path is invalid.
 272          * @exception           E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 273          * @exception           E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 274          * @exception           E_FILE_ALREADY_EXIST    The specified file already exists.
 275          * @exception           E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 276          * @exception           E_STORAGE_FULL                  The disk space is full.
 277          * @exception           E_IO                                                            Either of the following conditions has occurred: @n
 278          *                                                                                                                      - An unexpected device failure has occurred as the media ejected suddenly. @n
 279          *                                                                                                                      - File corruption is detected. @n
 280          *                                                                                                                      - The volume or quota is no more available.
 281          * @remarks             The source file in the system region cannot be copied. @n
 282          *                       The destination file path must start with @c '/Media' or @c '/Storagecard/Media'.
 283          * @endif
 284          */
 285         static result MoveToMediaDirectory(const Tizen::Base::String& srcFilePath, const Tizen::Base::String& destFilePath);
 286
 287         /**
 288          * @if OSPCOMPAT
 289          * @page        CompContentManagerUtilPage Compatibility for the file path.
 290          * @section     CompContentManagerUtilPageIssueSection Issues
 291          *                 The file path argument of this method in OSP compatible applications has the following issues: @n
 292          *                 -# The file path should be a path that begins with an allowed path prefix. @n
 293          *                     For example, L"/Media/Images/flower.jpg", "/Storagecard/Media/Images/flower.jpg".
 294          *
 295          * @section     CompContentManagerUtilPageSolutionSection Resolutions
 296          *                 This issue has been resolved in Tizen. @n
 297          *                 -# The file path can be a path without a specific allowed path prefix. @n
 298          *                 Application do not need to know the specific allowed path prefixes. @n
 299          *                 To get the directory path, use the following methods: @n
 300          *                 - For accessing the home directory, use Tizen::App::App::GetInstance()->GetAppRootPath().
 301          *                 - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
 302          *                 - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
 303          *
 304          * @endif
 305          */
 306
 307 private:
 308         /**
 309          * This default constructor is intentionally declared as private because this class cannot be constructed.
 310          */
 311         ContentManagerUtil(void);
 312
 313         /**
 314          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 315          */
 316         ContentManagerUtil(const ContentManagerUtil& rhs);
 317
 318         /**
 319          * This destructor is intentionally declared as private because this class cannot be constructed.
 320          */
 321         virtual ~ContentManagerUtil(void);
 322
 323         /**
 324          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 325          */
 326         ContentManagerUtil& operator =(const ContentManagerUtil& rhs);
 327
 328 };  // class ContentManagerUtil
 329
 330 }}  // Tizen::Content
 331
 332 #endif  // _FCNT_CONTENT_MANAGER_UTIL_H_