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