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