* @file mtp.h
* @brief This file contains the MTP API
*/
-#ifndef TIZEN_ERROR_MTP
-#define TIZEN_ERROR_MTP -0x01CC0000
-#endif
/**
* @addtogroup CAPI_NETWORK_MTP_MANAGER_MODULE
*/
/**
- * @brief The handle to the mtp device
+ * @brief The handle to the mtp device.
* @since_tizen 3.0
*/
typedef int mtp_device_h;
/**
- * @brief The handle to the mtp storage
+ * @brief The handle to the mtp storage.
* @since_tizen 3.0
*/
typedef int mtp_storage_h;
/**
- * @brief The handle to the mtp object
+ * @brief The handle to the mtp object.
* @since_tizen 3.0
*/
typedef int mtp_object_h;
} mtp_error_e;
/**
- * @brief Enumerations for MTP Storage type
+ * @brief Enumerations for MTP Storage type.
* @since_tizen 3.0
*/
typedef enum {
} mtp_storage_type_e;
/**
- * @brief Enumerations for MTP file type
+ * @brief Enumerations for MTP file type.
* @since_tizen 3.0
*/
typedef enum {
MTP_FILETYPE_PLAYLIST, /**< PLAYLIST file type */
MTP_FILETYPE_UNKNOWN, /**< Unknown file type */
- MTP_FILETYPE_ALL, /**< Helper enum value for certain function */
- MTP_FILETYPE_ALL_IMAGE /**< Helper enum value for certain function */
+ MTP_FILETYPE_ALL, /**< Helper enum value for all file types */
+ MTP_FILETYPE_ALL_IMAGE /**< Helper enum value for all image files types */
} mtp_filetype_e;
/**
- * @brief Enumerations for MTP event type
+ * @brief Enumerations for MTP event type.
* @since_tizen 3.0
*/
typedef enum {
* @brief Called when mtp event is occured.
* @since_tizen 3.0
* @remarks Depending on the type of event, the meaning of event parameter is different.
- * - If event is device event, then event_parameter type is mtp_device_h.
- * - If event is storage event, then event_parameter type is mtp_storage_h.
- * - If event is object event, then event_parameter type is mtp_object_h.
- * - If event is MTP_EVENT_TURNED_OFF, then event_parameter is 0.
+ * - If event is device event, then event_parameter type is #mtp_device_h.
+ * - If event is storage event, then event_parameter type is #mtp_storage_h.
+ * - If event is object event, then event_parameter type is #mtp_object_h.
+ * - If event is #MTP_EVENT_TURNED_OFF, then event_parameter is 0.
*
- * @param [in] event The event
- * @param [in] event_parameter The event parameter
- * @param [in] user_data The user data passed from the callback registration function
+ * @param[in] event The event
+ * @param[in] event_parameter The event parameter
+ * @param[in] user_data The user data passed from the callback registration function
*
* @see mtp_set_mtp_event_cb()
* @see mtp_unset_mtp_event_cb()
/**
* @brief Gets the mtp devices.
* @since_tizen 3.0
- * @param [out] mtp_devices The MTP device list
- * @param [out] device_count Length of device list
+ *
+ * @remarks The @a mtp_devices should be released using free().
+ *
+ * @param[out] mtp_devices The MTP device list
+ * @param[out] device_count Length of device list
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @since_tizen 3.0
* @remarks The @a mtp_storages should be freed using free().
*
- * @param [in] mtp_device The MTP device
- * @param [out] mtp_storages Current mtp storage list
- * @param [out] storage_count Length of storage list
+ * @param[in] mtp_device The MTP device
+ * @param[out] mtp_storages Current mtp storage list
+ * @param[out] storage_count Length of storage list
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @remarks The @a object_handles should be freed using free().
* @remarks If the @a parent is 0, it means "root folder" of mtp storage.
*
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [in] file_type The file type what you want
- * @param [in] parent The parent object handle
- * @param [out] object_handles The object handle list
- * @param [out] object_count Length of object handle list
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[in] file_type The file type what you want
+ * @param[in] parent The parent object handle
+ * @param[out] object_handles The object handle list
+ * @param[out] object_count Length of object handle list
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @remarks http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
* http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage. \n
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [in] dest_path The dest path
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[in] dest_path The dest path
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @remarks http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.\n
* http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [in] dest_path The dest path
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[in] dest_path The dest path
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* If object state is changed, #MTP_EVENT_OBJECT_ADDED or #MTP_EVENT_OBJECT_REMOVED event is occur. \n
* If mtp service is turned off, #MTP_EVENT_TURNED_OFF event is occur. \n
*
- * @param [in] event_cb The callback
- * @param [in] user_data The user data
+ * @param[in] event_cb The callback
+ * @param[in] user_data The user data
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Removes the callback function.
* @since_tizen 3.0
*
- * @param [in] event_cb The callback
+ * @param[in] event_cb The callback
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @since_tizen 3.0
* @remarks The @a manufacturer_name should be freed using free().
*
- * @param [in] mtp_device The MTP device
- * @param [out] manufacturer_name The manufacturer name of Device information
+ * @param[in] mtp_device The MTP device
+ * @param[out] manufacturer_name The manufacturer name of Device information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @since_tizen 3.0
* @remarks The @a model_name should be freed using free().
*
- * @param [in] mtp_device The MTP device
- * @param [out] model_name The model name of Device information
+ * @param[in] mtp_device The MTP device
+ * @param[out] model_name The model name of Device information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @since_tizen 3.0
* @remarks The @a serial_number should be freed using free().
*
- * @param [in] mtp_device The MTP device
- * @param [out] serial_number The serial number of Device information
+ * @param[in] mtp_device The MTP device
+ * @param[out] serial_number The serial number of Device information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @since_tizen 3.0
* @remarks The @a device_version should be freed using free().
*
- * @param [in] mtp_device The MTP device
- * @param [out] device_version The device version of Device information
+ * @param[in] mtp_device The MTP device
+ * @param[out] device_version The device version of Device information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @since_tizen 3.0
* @remarks The @a description should be freed using free().
*
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [out] description The description of Storage information
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[out] description The description of Storage information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the free space of the storage information in bytes.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [out] free_space The free space of Storage information (bytes)
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[out] free_space The free space of Storage information (bytes)
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the max capacity of the storage information in bytes.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [out] max_capacity The max capacity of Storage information (bytes)
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[out] max_capacity The max capacity of Storage information (bytes)
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the storage type of the storage information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [out] storage_type The storage type of Storage information
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[out] storage_type The storage type of Storage information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @since_tizen 3.0
* @remarks The @a volume_identifier should be freed using free().
*
- * @param [in] mtp_device The MTP device
- * @param [in] mtp_storage The MTP storage
- * @param [out] volume_identifier The volume identifier of Storage information
+ * @param[in] mtp_device The MTP device
+ * @param[in] mtp_storage The MTP storage
+ * @param[out] volume_identifier The volume identifier of Storage information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @since_tizen 3.0
* @remarks The @a file_name should be freed using free().
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] file_name The file name of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] file_name The file name of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @remarks The @a keywords should be freed using free().
* @remarks The keywords are separated by comma.
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] keywords The keywords of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] keywords The keywords of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the association desc of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] asso_desc The association description of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] asso_desc The association description of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the association type of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] asso_type The association type of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] asso_type The association type of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the size of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] size The size of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] size The size of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the parent object handle of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] parent_object_handle The parent of Object information
+ * @remarks The @a parent_object_handle should not be released.
+ * @remarks The @a parent_object_handle can be used until the MTP service stops.
+ * @remarks The @a parent_object_handle is managed by the platform when the MTP service stop.
+ *
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] parent_object_handle The parent of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the mtp storage of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] mtp_storage The MTP storage of Object information
+ * @remarks The @a mtp_storage should not be released.
+ * @remarks The @a mtp_storage can be used until the MTP service stops.
+ * @remarks The @a mtp_storage is managed by the platform when the MTP service stop.
+ *
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] mtp_storage The MTP storage of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the object created time of the object information.
* @since_tizen 3.0
* @remarks When interpreted as an absolute time value, \n
- * @a data_created represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
+ * @a date_created represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] date_created The object created time of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] date_created The object created time of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the object modified time of the object information.
* @since_tizen 3.0
* @remarks When interpreted as an absolute time value, \n
- * @a data_modified represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
+ * @a date_modified represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] date_modified The object modified time of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] date_modified The object modified time of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the file type of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] file_type The file type of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] file_type The file type of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the image bit depth of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] depth The image bit depth of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] depth The image bit depth of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the image pixel width of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] width The image pixel width of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] width The image pixel width of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the image pixel height of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] height The image pixel height of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] height The image pixel height of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the thumbnail size of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] size The thumbnail size of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] size The thumbnail size of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the thumbnail file type of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] file_type The file type of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] file_type The file type of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the thumbnail pixel height of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] height The thumbnail pixel height of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] height The thumbnail pixel height of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful
* @brief Gets the thumbnail pixel width of the object information.
* @since_tizen 3.0
*
- * @param [in] mtp_device The MTP device
- * @param [in] object_handle The object handle
- * @param [out] width The thumbnail pixel width of Object information
+ * @param[in] mtp_device The MTP device
+ * @param[in] object_handle The object handle
+ * @param[out] width The thumbnail pixel width of Object information
*
* @return 0 on success, otherwise a negative error value.
* @retval #MTP_ERROR_NONE Successful