diff options
author | hjkim <backto.kim@samsung.com> | 2024-09-24 16:50:49 +0900 |
---|---|---|
committer | hjkim <backto.kim@samsung.com> | 2024-09-25 16:01:54 +0900 |
commit | 3c42e5a80fc77776785f9454e51e34d32a51ea85 (patch) | |
tree | 87ec2147e04f9ce2ac2295862a55cb6a93752e68 | |
parent | 80169ac0b5019dc83a5aea404b5c05a7fc353641 (diff) | |
download | media-controller-accepted/tizen_unified.tar.gz media-controller-accepted/tizen_unified.tar.bz2 media-controller-accepted/tizen_unified.zip |
Improve API descriptiontizen_9.0_m2_releaseaccepted/tizen/unified/x/asan/20241013.235955accepted/tizen/unified/x/20240930.134644accepted/tizen/unified/toolchain/20241004.101636accepted/tizen/unified/20240930.083339accepted/tizen/9.0/unified/20241030.232427tizen_9.0tizenaccepted/tizen_unified_x_asanaccepted/tizen_unified_xaccepted/tizen_unified_toolchainaccepted/tizen_unifiedaccepted/tizen_9.0_unified
Change-Id: Ieae51c84ef95a6f93cfe004c9f96b4b7d540334a
-rw-r--r-- | doc/media_controller_doc.h | 13 | ||||
-rw-r--r-- | include/media_controller_client.h | 212 | ||||
-rw-r--r-- | include/media_controller_metadata.h | 24 | ||||
-rw-r--r-- | include/media_controller_playlist.h | 22 | ||||
-rw-r--r-- | include/media_controller_server.h | 148 | ||||
-rw-r--r-- | include/media_controller_type.h | 100 | ||||
-rw-r--r-- | packaging/capi-media-controller.spec | 2 |
7 files changed, 394 insertions, 127 deletions
diff --git a/doc/media_controller_doc.h b/doc/media_controller_doc.h index a2ae36f..5034410 100644 --- a/doc/media_controller_doc.h +++ b/doc/media_controller_doc.h @@ -91,7 +91,7 @@ * @section CAPI_MEDIA_CONTROLLER_METADATA_MODULE_HEADER Required Header * \#include <media_controller_metadata.h> * -* @section CAPI_MEDIA_CONTROLLER_METADAT_MODULE_OVERVIEW Overview +* @section CAPI_MEDIA_CONTROLLER_METADATA_MODULE_OVERVIEW Overview * The @ref CAPI_MEDIA_CONTROLLER_METADATA_MODULE API allows you to get metadata (mc_metadata_get()). \n * You can copy the metadata by using mc_metadata_clone(). And if you don't use handle anymore, you have to destroy it(mc_metadata_destroy()). * @@ -105,7 +105,8 @@ * \#include <media_controller_metadata.h> * * @section CAPI_MEDIA_CONTROLLER_ABILITY_MODULE_OVERVIEW Overview -* The @ref CAPI_MEDIA_CONTROLLER_ABILITY_MODULE API allows you to get playback action ability (mc_playback_action_is_supported()). \n +* The @ref CAPI_MEDIA_CONTROLLER_ABILITY_MODULE API allows you to get playback action ability of the media controller server(mc_playback_action_is_supported()). \n +* If you are media controller client, you can use functions here. \n * You can copy the ability by using mc_playback_ability_clone(). And if you don't use handle anymore, you have to destroy it(mc_playback_ability_destroy()). * */ @@ -118,9 +119,11 @@ * \#include <media_controller_metadata.h> * * @section CAPI_MEDIA_CONTROLLER_SEARCH_MODULE_OVERVIEW Overview -* The @ref CAPI_MEDIA_CONTROLLER_SEARCH_MODULE API allows you to create handle for searching (mc_search_create()). \n -* You can set and get search conditions (mc_search_set_condition() and mc_search_foreach_condition()). \n -* And copy the search by using mc_search_clone(). And if you don't use handle anymore, you have to destroy it(mc_search_destroy()). +* The @ref CAPI_MEDIA_CONTROLLER_SEARCH_MODULE API allows the media controller client can search for the content provided by the media controller server. \n +* And the media controller server can respond to the search request of the media controller client. \n +* You can create handle for searching (mc_search_create()). \n +* And You can set and get search conditions (mc_search_set_condition() and mc_search_foreach_condition()) \n +* and copy the search by using mc_search_clone(). And if you don't use handle anymore, you have to destroy it(mc_search_destroy()). * */ diff --git a/include/media_controller_client.h b/include/media_controller_client.h index 525df84..e5bdad7 100644 --- a/include/media_controller_client.h +++ b/include/media_controller_client.h @@ -30,7 +30,8 @@ extern "C" { /** * @file media_controller_client.h * @brief This file contains the media controller client API and functions related with handling media control. \n - * Functions include operations to get the latest status of the media controller servers. + * Functions include operations to get the latest status of media controller servers. + * It also includes functions that can process commands received from servers. */ /** @@ -151,6 +152,7 @@ typedef void (*mc_repeat_mode_updated_cb)(const char *server_name, mc_repeat_mod * * @see mc_client_set_playback_ability_updated_cb() * @see mc_playback_action_is_supported() + * @see mc_playback_ability_clone() */ typedef void (*mc_playback_ability_updated_cb)(const char *server_name, mc_playback_ability_h ability, void *user_data); @@ -268,11 +270,15 @@ typedef bool (*mc_subscribed_server_cb)(const char *server_name, void *user_data * * @see mc_client_set_playlist_updated_cb() * @see mc_playlist_foreach_playlist() + * @see mc_playlist_get_name() + * @see mc_playlist_get_item_count() + * @see mc_playlist_foreach_item() + * @see mc_playlist_destroy() */ typedef void (*mc_playlist_updated_cb)(const char *server_name, mc_playlist_update_mode_e mode, const char *playlist_name, mc_playlist_h playlist, void *user_data); /** - * @brief Called when receiving custom event of media controller servers. + * @brief Called when receiving custom event from media controller servers. * @since_tizen 4.0 * * @remarks The callback is called in the dbus event loop.\n The @a data should be released using bundle_free(). \n @@ -362,12 +368,13 @@ typedef void (*mc_display_rotation_updated_cb)(const char *server_name, mc_displ * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_INVALID_OPERATION Invalid operation * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory + * * @see mc_client_destroy() */ int mc_client_create(mc_client_h *client); /** - * @brief Sets the callback for monitoring status of the media controller server. + * @brief Sets the callback for monitoring status of media controller servers. * @details The media controller client which calls this function will receive notifications from all media controller servers. * @since_tizen 4.0 * @@ -389,11 +396,13 @@ int mc_client_create(mc_client_h *client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_server_updated_cb() + * @see mc_server_create() + * @see mc_server_destroy() */ int mc_client_set_server_updated_cb(mc_client_h client, mc_server_state_updated_cb callback, void *user_data); /** - * @brief Unsets the callback for monitoring status of the media controller server. + * @brief Unsets the callback for monitoring status of media controller servers. * @since_tizen 4.0 * * @privlevel public @@ -414,7 +423,7 @@ int mc_client_set_server_updated_cb(mc_client_h client, mc_server_state_updated_ int mc_client_unset_server_updated_cb(mc_client_h client); /** - * @brief Sets the callback for monitoring playback status of the media controller server. + * @brief Sets the callback for monitoring playback status of media controller servers. * @details The media controller client which calls this function will receive notifications from all media controller servers. * @since_tizen 4.0 * @@ -436,11 +445,12 @@ int mc_client_unset_server_updated_cb(mc_client_h client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_playback_updated_cb() + * @see mc_server_update_playback_info() */ int mc_client_set_playback_updated_cb(mc_client_h client, mc_playback_updated_cb callback, void *user_data); /** - * @brief Unsets the callback for monitoring playback status of the media controller server. + * @brief Unsets the callback for monitoring playback status of media controller servers. * @since_tizen 4.0 * * @privlevel public @@ -462,7 +472,7 @@ int mc_client_set_playback_updated_cb(mc_client_h client, mc_playback_updated_cb int mc_client_unset_playback_updated_cb(mc_client_h client); /** - * @brief Sets the callback for monitoring metadata status of the media controller server. + * @brief Sets the callback for monitoring metadata status of media controller servers. * @details The media controller client which calls this function will receive notifications from all media controller servers. * @since_tizen 4.0 * @@ -484,11 +494,12 @@ int mc_client_unset_playback_updated_cb(mc_client_h client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_metadata_updated_cb() + * @see mc_server_update_metadata() */ int mc_client_set_metadata_updated_cb(mc_client_h client, mc_metadata_updated_cb callback, void *user_data); /** - * @brief Unsets the callback for monitoring metadata status of the media controller server. + * @brief Unsets the callback for monitoring metadata status of media controller servers. * @since_tizen 4.0 * * @privlevel public @@ -510,7 +521,7 @@ int mc_client_set_metadata_updated_cb(mc_client_h client, mc_metadata_updated_cb int mc_client_unset_metadata_updated_cb(mc_client_h client); /** - * @brief Sets the callback for monitoring shuffle mode of the media controller server. + * @brief Sets the callback for monitoring shuffle mode of media controller servers. * @details The media controller client which calls this function will receive notifications from all media controller servers. * @since_tizen 4.0 * @@ -532,11 +543,12 @@ int mc_client_unset_metadata_updated_cb(mc_client_h client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_shuffle_mode_updated_cb() + * @see mc_server_update_shuffle_mode() */ int mc_client_set_shuffle_mode_updated_cb(mc_client_h client, mc_shuffle_mode_updated_cb callback, void *user_data); /** - * @brief Unsets the callback for monitoring shuffle mode of the media controller server. + * @brief Unsets the callback for monitoring shuffle mode of media controller servers. * @since_tizen 4.0 * * @privlevel public @@ -558,7 +570,7 @@ int mc_client_set_shuffle_mode_updated_cb(mc_client_h client, mc_shuffle_mode_up int mc_client_unset_shuffle_mode_updated_cb(mc_client_h client); /** - * @brief Sets the callback for monitoring repeat mode of the media controller server. + * @brief Sets the callback for monitoring repeat mode of media controller servers. * @details The media controller client which calls this function will receive notifications from all media controller servers. * @since_tizen 4.0 * @@ -580,11 +592,12 @@ int mc_client_unset_shuffle_mode_updated_cb(mc_client_h client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_repeat_mode_updated_cb() + * @see mc_server_update_repeat_mode() */ int mc_client_set_repeat_mode_updated_cb(mc_client_h client, mc_repeat_mode_updated_cb callback, void *user_data); /** - * @brief Unsets the callback for monitoring repeat mode of the media controller server. + * @brief Unsets the callback for monitoring repeat mode of media controller servers. * @since_tizen 4.0 * * @privlevel public @@ -606,7 +619,7 @@ int mc_client_set_repeat_mode_updated_cb(mc_client_h client, mc_repeat_mode_upda int mc_client_unset_repeat_mode_updated_cb(mc_client_h client); /** - * @brief Sets the callback for monitoring the playback ability of the media controller server. + * @brief Sets the callback for monitoring the playback ability of media controller servers. * @details The media controller client which calls this function will receive notifications from all media controller servers. * @since_tizen 5.0 * @@ -628,11 +641,12 @@ int mc_client_unset_repeat_mode_updated_cb(mc_client_h client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_playback_ability_updated_cb() + * @see mc_server_update_playback_ability() */ int mc_client_set_playback_ability_updated_cb(mc_client_h client, mc_playback_ability_updated_cb callback, void *user_data); /** - * @brief Unsets the callback for monitoring the playback ability of the media controller server. + * @brief Unsets the callback for monitoring the playback ability of media controller servers. * @since_tizen 5.0 * * @privlevel public @@ -693,6 +707,7 @@ int mc_client_unset_playback_ability_updated_cb(mc_client_h client); * @see mc_client_set_playback_ability_updated_cb() * @see mc_client_set_display_mode_ability_updated_cb() * @see mc_client_set_display_rotation_ability_updated_cb() + * @see mc_server_set_ability_support() */ int mc_client_set_ability_support_updated_cb(mc_client_h client, mc_ability_support_updated_cb callback, void *user_data); @@ -737,7 +752,7 @@ int mc_client_set_ability_support_updated_cb(mc_client_h client, mc_ability_supp int mc_client_unset_ability_support_updated_cb(mc_client_h client); /** - * @brief Sets the callback for monitoring the display mode ability of the media controller server. + * @brief Sets the callback for monitoring the display mode ability of media controller servers. * @details The media controller client which calls this function will receive notifications from all media controller servers. * @since_tizen 5.5 * @@ -759,11 +774,12 @@ int mc_client_unset_ability_support_updated_cb(mc_client_h client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_display_mode_ability_updated_cb() + * @see mc_server_set_display_mode_ability() */ int mc_client_set_display_mode_ability_updated_cb(mc_client_h client, mc_ability_supported_items_updated_cb callback, void *user_data); /** - * @brief Unsets the callback for monitoring the display mode ability of the media controller server. + * @brief Unsets the callback for monitoring the display mode ability of media controller servers. * @since_tizen 5.5 * * @privlevel public @@ -785,7 +801,7 @@ int mc_client_set_display_mode_ability_updated_cb(mc_client_h client, mc_ability int mc_client_unset_display_mode_ability_updated_cb(mc_client_h client); /** - * @brief Sets the callback for monitoring the display rotation ability of the media controller server. + * @brief Sets the callback for monitoring the display rotation ability of media controller servers. * @details The media controller client which calls this function will receive notifications from all media controller servers. * @since_tizen 5.5 * @@ -807,11 +823,12 @@ int mc_client_unset_display_mode_ability_updated_cb(mc_client_h client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_display_rotation_ability_updated_cb() + * @see mc_server_set_display_rotation_ability() */ int mc_client_set_display_rotation_ability_updated_cb(mc_client_h client, mc_ability_supported_items_updated_cb callback, void *user_data); /** - * @brief Unsets the callback for monitoring the display rotation ability of the media controller server. + * @brief Unsets the callback for monitoring the display rotation ability of media controller servers. * @since_tizen 5.5 * * @privlevel public @@ -833,7 +850,7 @@ int mc_client_set_display_rotation_ability_updated_cb(mc_client_h client, mc_abi int mc_client_unset_display_rotation_ability_updated_cb(mc_client_h client); /** - * @brief Sets the callback for receiving the result of the command from the media controller server. + * @brief Sets the callback for receiving the result of the command from the media controller servers. * @details The media controller client which calls this function will receives the result of the command from all media controller servers. * @since_tizen 4.0 * @@ -853,13 +870,14 @@ int mc_client_unset_display_rotation_ability_updated_cb(mc_client_h client); * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() - * @see mc_client_unset_cmd_reply_received_cb() * @see mc_client_destroy() + * @see mc_client_unset_cmd_reply_received_cb() + * @see mc_server_send_cmd_reply() */ int mc_client_set_cmd_reply_received_cb(mc_client_h client, mc_cmd_reply_received_cb callback, void *user_data); /** - * @brief Unsets the callback for receiving common reply of the media controller server. + * @brief Unsets the callback for receiving common reply of media controller servers. * @since_tizen 4.0 * * @privlevel public @@ -875,13 +893,13 @@ int mc_client_set_cmd_reply_received_cb(mc_client_h client, mc_cmd_reply_receive * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() - * @see mc_client_set_cmd_reply_received_cb() * @see mc_client_destroy() + * @see mc_client_set_cmd_reply_received_cb() */ int mc_client_unset_cmd_reply_received_cb(mc_client_h client); /** - * @brief Sets the callback for monitoring playlist status of the media controller server. + * @brief Sets the callback for monitoring playlist status of media controller servers. * @details The media controller client which calls this function will receive notifications from all media controller servers. * @since_tizen 4.0 * @@ -904,11 +922,13 @@ int mc_client_unset_cmd_reply_received_cb(mc_client_h client); * @see mc_client_destroy() * @see mc_playlist_updated_cb() * @see mc_client_unset_playlist_updated_cb() + * @see mc_server_update_playlist_done() + * @see mc_server_delete_playlist() */ int mc_client_set_playlist_updated_cb(mc_client_h client, mc_playlist_updated_cb callback, void *user_data); /** - * @brief Unsets the callback for monitoring playlist status of the media controller server. + * @brief Unsets the callback for monitoring playlist status of media controller servers. * @since_tizen 4.0 * * @privlevel public @@ -952,6 +972,7 @@ int mc_client_unset_playlist_updated_cb(mc_client_h client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_subtitles_updated_cb() + * @see mc_server_update_subtitles_enabled() */ int mc_client_set_subtitles_updated_cb(mc_client_h client, mc_bool_attribute_updated_cb callback, void *user_data); @@ -1001,6 +1022,7 @@ int mc_client_unset_subtitles_updated_cb(mc_client_h client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_360_mode_updated_cb() + * @see mc_server_update_360_mode_enabled() */ int mc_client_set_360_mode_updated_cb(mc_client_h client, mc_bool_attribute_updated_cb callback, void *user_data); @@ -1050,6 +1072,7 @@ int mc_client_unset_360_mode_updated_cb(mc_client_h client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_display_mode_updated_cb() + * @see mc_server_update_display_mode() */ int mc_client_set_display_mode_updated_cb(mc_client_h client, mc_display_mode_updated_cb callback, void *user_data); @@ -1099,6 +1122,7 @@ int mc_client_unset_display_mode_updated_cb(mc_client_h client); * @see mc_client_create() * @see mc_client_destroy() * @see mc_client_unset_display_rotation_updated_cb() + * @see mc_server_update_display_rotation() */ int mc_client_set_display_rotation_updated_cb(mc_client_h client, mc_display_rotation_updated_cb callback, void *user_data); @@ -1126,12 +1150,14 @@ int mc_client_set_display_rotation_updated_cb(mc_client_h client, mc_display_rot int mc_client_unset_display_rotation_updated_cb(mc_client_h client); /** - * @brief Sets the callback for receiving the custom event from a media controller server. + * @brief Sets the callback for receiving the custom event from a media controller servers. * @since_tizen 4.0 * * @privlevel public * @privilege %http://tizen.org/privilege/mediacontroller.client * + * @remarks If client need to reply to the result of the event, use mc_client_send_event_reply() + * * @param[in] client The handle to media controller client * @param[in] callback The callback to be invoked when the media controller client receives custom event from a media controller server * @param[in] user_data The user data to be passed to the callback function @@ -1149,6 +1175,7 @@ int mc_client_unset_display_rotation_updated_cb(mc_client_h client); * @see mc_client_unset_custom_event_received_cb() * @see mc_client_send_event_reply() * @see mc_client_destroy() + * @see mc_server_send_custom_event() */ int mc_client_set_custom_event_received_cb(mc_client_h client, mc_client_custom_event_received_cb callback, void *user_data); @@ -1201,10 +1228,12 @@ int mc_client_unset_custom_event_received_cb(mc_client_h client); * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory * * @pre Create a media controller server handle by calling mc_server_create(). + * @pre Receive event from media controller servers through mc_client_set_custom_event_received_cb(). * @see mc_client_create() * @see mc_client_set_custom_event_received_cb() * @see mc_client_unset_custom_event_received_cb() * @see mc_client_destroy() + * @see mc_server_set_event_reply_received_cb() */ int mc_client_send_event_reply(mc_client_h client, const char *server_name, const char *request_id, int result_code, bundle *data); @@ -1292,6 +1321,7 @@ int mc_client_unsubscribe(mc_client_h client, mc_subscription_type_e subscriptio * @pre Subscribe the media controller server for monitoring status by calling mc_client_subscribe() * @see mc_client_create() * @see mc_client_subscribe() + * @see mc_client_unsubscribe() */ int mc_client_foreach_server_subscribed(mc_client_h client, mc_subscription_type_e subscription_type, mc_subscribed_server_cb callback, void *user_data); @@ -1363,7 +1393,6 @@ int mc_client_get_playback_position(mc_playback_h playback, unsigned long long * */ int mc_client_get_playlist_item_info(mc_playback_h playback, char **playlist_name, char **index); - /** * @brief Gets the playback content type. * @details Gets the content type of the current playing media. If there is no content type info, result value is #MC_CONTENT_TYPE_UNDECIDED. @@ -1423,7 +1452,7 @@ int mc_client_get_age_rating(mc_playback_h playback, mc_content_age_rating_e *ag int mc_client_destroy_playback(mc_playback_h playback); /** - * @brief Gets the latest media controller server info. + * @brief Gets the last activated media controller server info, even if the server is currently deactivated. * @details The media controller client will get the most recently updated information by the server. * * @since_tizen 2.4 @@ -1447,12 +1476,17 @@ int mc_client_destroy_playback(mc_playback_h playback); * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_INVALID_OPERATION Invalid operation * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory + * + * @pre Create a media controller client handle by calling mc_client_create(). + * @see mc_client_create() + * @see mc_client_destroy() */ int mc_client_get_latest_server_info(mc_client_h client, char **server_name, mc_server_state_e *server_state); /** - * @brief Gets the latest playback info. - * @details The media controller client will get the most recently updated information from @a server_name. + * @brief Gets the latest playback info of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 2.4 * * @privlevel public @@ -1471,12 +1505,18 @@ int mc_client_get_latest_server_info(mc_client_h client, char **server_name, mc_ * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_INVALID_OPERATION Invalid operation * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory + * + * @pre Create a media controller client handle by calling mc_client_create(). + * @see mc_client_create() + * @see mc_client_destroy() + * @see mc_server_update_playback_info() */ int mc_client_get_server_playback_info(mc_client_h client, const char *server_name, mc_playback_h *playback); /** - * @brief Gets the latest metadata. - * @details The media controller client will get the most recently updated information from @a server_name. + * @brief Gets the latest metadata of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 2.4 * * @privlevel public @@ -1495,12 +1535,19 @@ int mc_client_get_server_playback_info(mc_client_h client, const char *server_na * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_INVALID_OPERATION Invalid operation * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory + * + * @pre Create a media controller client handle by calling mc_client_create(). + * @see mc_client_create() + * @see mc_client_destroy() + * @see mc_server_update_metadata() + * @see mc_metadata_get() */ int mc_client_get_server_metadata(mc_client_h client, const char *server_name, mc_metadata_h *metadata); /** - * @brief Gets the latest shuffle mode. - * @details The media controller client will get the most recently updated information from @a server_name. + * @brief Gets the latest shuffle mode of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 2.4 * * @privlevel public @@ -1516,12 +1563,18 @@ int mc_client_get_server_metadata(mc_client_h client, const char *server_name, m * @retval #MEDIA_CONTROLLER_ERROR_NONE Successful * @retval #MEDIA_CONTROLLER_ERROR_PERMISSION_DENIED Permission denied * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter + * + * @pre Create a media controller client handle by calling mc_client_create(). + * @see mc_client_create() + * @see mc_client_destroy() + * @see mc_server_update_shuffle_mode() */ int mc_client_get_server_shuffle_mode(mc_client_h client, const char *server_name, mc_shuffle_mode_e *mode); /** - * @brief Gets the latest repeat mode. - * @details The media controller client will get the most recently updated information from @a server_name. + * @brief Gets the latest repeat mode of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 2.4 * * @privlevel public @@ -1537,11 +1590,18 @@ int mc_client_get_server_shuffle_mode(mc_client_h client, const char *server_nam * @retval #MEDIA_CONTROLLER_ERROR_NONE Successful * @retval #MEDIA_CONTROLLER_ERROR_PERMISSION_DENIED Permission denied * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter + * + * @pre Create a media controller client handle by calling mc_client_create(). + * @see mc_client_create() + * @see mc_client_destroy() + * @see mc_server_update_repeat_mode() */ int mc_client_get_server_repeat_mode(mc_client_h client, const char *server_name, mc_repeat_mode_e *mode); /** - * @brief Gets the icon URI of the media controller server. + * @brief Gets the latest icon URI of the media controller server. + * @details The media controller client will get the icon URI of activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 5.0 * * @privlevel public @@ -1564,12 +1624,14 @@ int mc_client_get_server_repeat_mode(mc_client_h client, const char *server_name * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() * @see mc_client_destroy() + * @see mc_server_set_icon() */ int mc_client_get_server_icon(mc_client_h client, const char *server_name, char **uri); /** - * @brief Gets the latest subtitles display status. - * @details The media controller client will get the most recently updated information from @a server_name. + * @brief Gets the latest subtitles display status of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 5.5 * * @privlevel public @@ -1589,12 +1651,14 @@ int mc_client_get_server_icon(mc_client_h client, const char *server_name, char * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() * @see mc_client_destroy() + * @see mc_server_update_subtitles_enabled() */ int mc_client_get_server_subtitles_enabled(mc_client_h client, const char *server_name, bool *enabled); /** - * @brief Gets the latest 360 mode display status. - * @details The media controller client will get the most recently updated information from @a server_name. + * @brief Gets the latest 360 mode display status of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 5.5 * * @privlevel public @@ -1614,12 +1678,14 @@ int mc_client_get_server_subtitles_enabled(mc_client_h client, const char *serve * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() * @see mc_client_destroy() + * @see mc_server_update_360_mode_enabled() */ int mc_client_get_server_360_mode_enabled(mc_client_h client, const char *server_name, bool *enabled); /** - * @brief Gets the latest display mode. - * @details The media controller client will get the most recently updated information from @a server_name. + * @brief Gets the latest display mode of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 5.5 * * @privlevel public @@ -1641,12 +1707,14 @@ int mc_client_get_server_360_mode_enabled(mc_client_h client, const char *server * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() * @see mc_client_destroy() + * @see mc_server_update_display_mode() */ int mc_client_get_server_display_mode(mc_client_h client, const char *server_name, mc_display_mode_e *mode); /** - * @brief Gets the latest display rotation. - * @details The media controller client will get the most recently updated information from @a server_name. + * @brief Gets the latest display rotation of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 5.5 * * @privlevel public @@ -1668,19 +1736,22 @@ int mc_client_get_server_display_mode(mc_client_h client, const char *server_nam * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() * @see mc_client_destroy() + * @see mc_server_update_display_rotation() */ int mc_client_get_server_display_rotation(mc_client_h client, const char *server_name, mc_display_rotation_e *rotation); /** - * @brief Gets the playback ability of the media controller server. + * @brief Gets the latest playback ability of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 5.0 * * @privlevel public * @privilege %http://tizen.org/privilege/mediacontroller.client * * @remarks The @a ability should be released using mc_playback_ability_destroy().\n - * If the media controller server is deactivated, this function will return #MC_ABILITY_SUPPORTED_UNDECIDED.\n + * If the latest media controller server is deactivated, this function will return #MC_ABILITY_SUPPORTED_UNDECIDED.\n * * @param[in] client The handle of the media controller client * @param[in] server_name The app_id of the media controller server @@ -1700,11 +1771,15 @@ int mc_client_get_server_display_rotation(mc_client_h client, const char *server * @see mc_client_get_latest_server_info() * @see mc_client_foreach_server() * @see mc_playback_action_is_supported() + * @see mc_playback_ability_destroy() + * @see mc_server_update_playback_ability() */ int mc_client_get_server_playback_ability(mc_client_h client, const char *server_name, mc_playback_ability_h *ability); /** - * @brief Gets the ability support of the media controller server. + * @brief Gets the latest ability support of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 5.5 * * @privlevel public @@ -1712,7 +1787,7 @@ int mc_client_get_server_playback_ability(mc_client_h client, const char *server * * @remarks If the server's ability support is not set, the result value is #MC_ABILITY_SUPPORTED_UNDECIDED. \n * It means you can send the corresponding command to the server, but it's not guaranteed that the server can handle it. \n - * If the media controller server is deactivated, this function will return #MC_ABILITY_SUPPORTED_UNDECIDED. + * If the latest media controller server is deactivated, this function will return #MC_ABILITY_SUPPORTED_UNDECIDED. * * @param[in] client The handle of the media controller client * @param[in] server_name The app_id of the media controller server @@ -1735,18 +1810,21 @@ int mc_client_get_server_playback_ability(mc_client_h client, const char *server * @see mc_client_get_server_playback_ability() * @see mc_client_get_server_display_mode_ability() * @see mc_client_get_server_display_rotation_ability() + * @see mc_server_set_ability_support() */ int mc_client_get_server_ability_support(mc_client_h client, const char *server_name, mc_ability_e ability, mc_ability_support_e *support); /** - * @brief Gets the supported display mode of the updated media controller server. + * @brief Gets the latest supported display mode of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 5.5 * * @privlevel public * @privilege %http://tizen.org/privilege/mediacontroller.client * * @remarks If a display mode is not present in the @a supported_modes, then the server's support for this mode is #MC_ABILITY_SUPPORTED_NO and you can't send the corresponding command to the server. \n - * If the media controller server is deactivated, this function will return #MC_ABILITY_SUPPORTED_NO. + * If the latest media controller server is deactivated, this function will return #MC_ABILITY_SUPPORTED_NO. * * @param[in] client The handle of the media controller client * @param[in] server_name The app_id of the media controller server @@ -1768,18 +1846,21 @@ int mc_client_get_server_ability_support(mc_client_h client, const char *server_ * @see mc_client_get_server_playback_ability() * @see mc_client_get_server_ability_support() * @see mc_client_get_server_display_rotation_ability() + * @see mc_server_set_display_mode_ability() */ int mc_client_get_server_display_mode_ability(mc_client_h client, const char *server_name, unsigned int *supported_modes); /** - * @brief Gets the supported display rotation of the updated media controller server. + * @brief Gets the latest supported display rotation of the media controller server. + * @details The media controller client will get the most recently updated information from activated @a server_name. \n + * But if @a server_name is the latest server, client will get the information even though the server is deactivated. * @since_tizen 5.5 * * @privlevel public * @privilege %http://tizen.org/privilege/mediacontroller.client * * @remarks If a display rotation is not present in the @a supported_rotations, then the server's support for this mode is #MC_ABILITY_SUPPORTED_NO and you can't send the corresponding command to the server. \n - * If the media controller server is deactivated, this function will return #MC_ABILITY_SUPPORTED_NO. + * If the latest media controller server is deactivated, this function will return #MC_ABILITY_SUPPORTED_NO. * * @param[in] client The handle of the media controller client * @param[in] server_name The app_id of the media controller server @@ -1801,11 +1882,12 @@ int mc_client_get_server_display_mode_ability(mc_client_h client, const char *se * @see mc_client_get_server_playback_ability() * @see mc_client_get_server_ability_support() * @see mc_client_get_server_display_mode_ability() + * @see mc_server_set_display_rotation_ability() */ int mc_client_get_server_display_rotation_ability(mc_client_h client, const char *server_name, unsigned int *supported_rotations); /** - * @brief Retrieves all created servers. + * @brief Retrieves all activated servers. * @details This function gets all created media controller servers. * The callback function will be invoked for every created media controller server. * If there are no media controller servers, the callback will not be invoked. @@ -1827,6 +1909,8 @@ int mc_client_get_server_display_rotation_ability(mc_client_h client, const char * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() + * @see mc_client_destroy() + * @see mc_server_create() */ int mc_client_foreach_server(mc_client_h client, mc_activated_server_cb callback, void *user_data); @@ -1856,8 +1940,10 @@ int mc_client_foreach_server(mc_client_h client, mc_activated_server_cb callback * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() + * @see mc_client_destroy() * @see mc_client_get_server_playback_info() * @see mc_client_set_cmd_reply_received_cb() + * @see mc_server_set_playback_action_cmd_received_cb() */ int mc_client_send_playback_action_cmd(mc_client_h client, const char *server_name, mc_playback_action_e action, char **request_id); @@ -1887,8 +1973,10 @@ int mc_client_send_playback_action_cmd(mc_client_h client, const char *server_na * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() + * @see mc_client_destroy() * @see mc_client_get_server_playback_info() * @see mc_client_set_cmd_reply_received_cb() + * @see mc_server_set_playback_position_cmd_received_cb() */ int mc_client_send_playback_position_cmd(mc_client_h client, const char *server_name, unsigned long long position, char **request_id); @@ -1918,8 +2006,10 @@ int mc_client_send_playback_position_cmd(mc_client_h client, const char *server_ * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() + * @see mc_client_destroy() * @see mc_client_get_server_playback_info() * @see mc_client_set_cmd_reply_received_cb() + * @see mc_server_set_shuffle_mode_cmd_received_cb() */ int mc_client_send_shuffle_mode_cmd(mc_client_h client, const char *server_name, mc_shuffle_mode_e shuffle_mode, char **request_id); @@ -1949,8 +2039,10 @@ int mc_client_send_shuffle_mode_cmd(mc_client_h client, const char *server_name, * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() + * @see mc_client_destroy() * @see mc_client_get_server_playback_info() * @see mc_client_set_cmd_reply_received_cb() + * @see mc_server_set_repeat_mode_cmd_received_cb() */ int mc_client_send_repeat_mode_cmd(mc_client_h client, const char *server_name, mc_repeat_mode_e repeat_mode, char **request_id); @@ -1984,7 +2076,9 @@ int mc_client_send_repeat_mode_cmd(mc_client_h client, const char *server_name, * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() + * @see mc_client_destroy() * @see mc_client_set_cmd_reply_received_cb() + * @see mc_server_set_playlist_cmd_received_cb() */ int mc_client_send_playlist_cmd(mc_client_h client, const char *server_name, const char *playlist_name, const char *index, mc_playback_action_e action, unsigned long long position, char **request_id); @@ -2016,7 +2110,9 @@ int mc_client_send_playlist_cmd(mc_client_h client, const char *server_name, con * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() + * @see mc_client_destroy() * @see mc_client_set_cmd_reply_received_cb() + * @see mc_server_set_custom_cmd_received_cb() */ int mc_client_send_custom_cmd(mc_client_h client, const char *server_name, const char *command, bundle *data, char **request_id); @@ -2048,9 +2144,11 @@ int mc_client_send_custom_cmd(mc_client_h client, const char *server_name, const * @pre Create a media controller client handle by calling mc_client_create(). * @pre Create search handle and set data by calling mc_search_create() and mc_search_set_condition(). * @see mc_client_create() + * @see mc_client_destroy() * @see mc_client_set_cmd_reply_received_cb() * @see mc_search_create() * @see mc_search_set_condition() + * @see mc_server_set_search_cmd_received_cb() */ int mc_client_send_search_cmd(mc_client_h client, const char *server_name, mc_search_h search, char **request_id); @@ -2081,7 +2179,9 @@ int mc_client_send_search_cmd(mc_client_h client, const char *server_name, mc_se * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() + * @see mc_client_destroy() * @see mc_client_set_cmd_reply_received_cb() + * @see mc_server_set_subtitles_cmd_received_cb() */ int mc_client_send_subtitles_cmd(mc_client_h client, const char *server_name, bool enable, char **request_id); @@ -2112,7 +2212,9 @@ int mc_client_send_subtitles_cmd(mc_client_h client, const char *server_name, bo * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() + * @see mc_client_destroy() * @see mc_client_set_cmd_reply_received_cb() + * @see mc_server_set_360_mode_cmd_received_cb() */ int mc_client_send_360_mode_cmd(mc_client_h client, const char *server_name, bool enable, char **request_id); @@ -2143,7 +2245,9 @@ int mc_client_send_360_mode_cmd(mc_client_h client, const char *server_name, boo * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() + * @see mc_client_destroy() * @see mc_client_set_cmd_reply_received_cb() + * @see mc_server_set_display_mode_cmd_received_cb() */ int mc_client_send_display_mode_cmd(mc_client_h client, const char *server_name, mc_display_mode_e mode, char **request_id); @@ -2174,7 +2278,9 @@ int mc_client_send_display_mode_cmd(mc_client_h client, const char *server_name, * * @pre Create a media controller client handle by calling mc_client_create(). * @see mc_client_create() + * @see mc_client_destroy() * @see mc_client_set_cmd_reply_received_cb() + * @see mc_server_set_display_rotation_cmd_received_cb() */ int mc_client_send_display_rotation_cmd(mc_client_h client, const char *server_name, mc_display_rotation_e rotation, char **request_id); diff --git a/include/media_controller_metadata.h b/include/media_controller_metadata.h index fe4f98b..0eeeced 100644 --- a/include/media_controller_metadata.h +++ b/include/media_controller_metadata.h @@ -97,10 +97,10 @@ int mc_metadata_destroy(mc_metadata_h metadata); * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory * - * @pre Sets mc_client_set_metadata_updated_cb() function to get the metadata if you are media controller client. \n + * @pre Call mc_client_set_metadata_updated_cb() or mc_client_get_server_metadata() function to get the metadata if you are media controller client. \n * and also you can use this function when get the metadata when callback function invoked in mc_playlist_foreach_item(). - * * @see mc_client_set_metadata_updated_cb() + * @see mc_client_get_server_metadata() * @see mc_playlist_foreach_item() */ int mc_metadata_get(mc_metadata_h metadata, mc_meta_e attribute, char **value); @@ -298,6 +298,8 @@ int mc_metadata_decode_resolution(const char *encoded_resolution, unsigned int * * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory * + * @pre Call the mc_client_set_playback_ability_updated_cb() or mc_client_get_server_playback_ability() function to get the ability if you are media controller client. + * * @see mc_playback_ability_destroy() */ int mc_playback_ability_clone(mc_playback_ability_h src, mc_playback_ability_h *dst); @@ -318,6 +320,8 @@ int mc_playback_ability_clone(mc_playback_ability_h src, mc_playback_ability_h * * @retval #MEDIA_CONTROLLER_ERROR_NONE Successful * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * + * @pre Call the mc_client_set_playback_ability_updated_cb() or mc_client_get_server_playback_ability() function to get the ability if you are media controller client. + * * @see mc_playback_ability_clone() */ int mc_playback_ability_destroy(mc_playback_ability_h ability); @@ -339,7 +343,7 @@ int mc_playback_ability_destroy(mc_playback_ability_h ability); * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory * - * @pre Call the mc_client_set_playback_ability_updated_cb() function to get the ability if you are the media controller client. + * @pre Call the mc_client_set_playback_ability_updated_cb() or mc_client_get_server_playback_ability() function to get the ability if you are media controller client. * * @see mc_client_set_playback_ability_updated_cb() * @see mc_client_get_server_playback_ability() @@ -391,8 +395,12 @@ typedef bool (*mc_search_condition_cb)(mc_content_type_e content_type, mc_search * @retval #MEDIA_CONTROLLER_ERROR_NONE Successful * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory + * * @see mc_search_set_condition() * @see mc_search_foreach_condition() + * @see mc_client_send_search_cmd() + * @see mc_server_search_cmd_received_cb() + * @see mc_server_set_search_cmd_received_cb() */ int mc_search_create(mc_search_h *search); @@ -412,7 +420,8 @@ int mc_search_create(mc_search_h *search); * @retval #MEDIA_CONTROLLER_ERROR_NONE Successful * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory - * @pre mc_search_create() + * + * @pre Call the mc_search_create() function to create handle if you are media controller client. * @see mc_search_foreach_condition() */ int mc_search_set_condition(mc_search_h search, mc_content_type_e content_type, mc_search_category_e category, const char *search_keyword, bundle *data); @@ -426,6 +435,7 @@ int mc_search_set_condition(mc_search_h search, mc_content_type_e content_type, * @retval #MEDIA_CONTROLLER_ERROR_NONE Successful * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_INVALID_OPERATION Invalid operation + * * @pre Create a media controller search handle by calling mc_search_create(). * @see mc_search_create() */ @@ -467,10 +477,11 @@ int mc_search_get_condition_count(mc_search_h search, int *condition_count); * @retval #MEDIA_CONTROLLER_ERROR_NONE Successful * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * - * @pre Create a media controller search handle by calling mc_search_create(). - * @pre Set the search conditions by calling mc_search_set_condition(). + * @pre Create a media controller search handle by calling mc_search_create() and set the search conditions by calling mc_search_set_condition() if you are media controller client. + * @pre Receive search command from the media controller client by calling mc_server_search_cmd_received_cb() if you are media controller server. * @see mc_search_create() * @see mc_search_set_condition() + * @see mc_server_search_cmd_received_cb() */ int mc_search_foreach_condition(mc_search_h search, mc_search_condition_cb callback, void *user_data); @@ -494,6 +505,7 @@ int mc_search_foreach_condition(mc_search_h search, mc_search_condition_cb callb * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory * * @see mc_search_destroy() + * @see mc_server_search_cmd_received_cb() */ int mc_search_clone(mc_search_h src, mc_search_h *dst); diff --git a/include/media_controller_playlist.h b/include/media_controller_playlist.h index e1cf945..49120a4 100644 --- a/include/media_controller_playlist.h +++ b/include/media_controller_playlist.h @@ -43,7 +43,7 @@ extern "C" { * To use the @a playlist outside this function, copy the handle with the mc_playlist_clone() function. \n * The callback is called in the main loop. * - * @param[in] playlist The handle of the media controller playlist. + * @param[in] playlist The handle of the media controller playlist * @param[in] user_data The user data passed from the foreach function * * @return @c true to continue with the next iteration of the loop, @@ -68,8 +68,8 @@ typedef bool (*mc_playlist_cb)(mc_playlist_h playlist, void *user_data); * And @a metadata also can be used only in the callback. To use outside, make a copy with the mc_metadata_clone() function. \n * The callback is called in the main loop. * - * @param[in] index The ID of the playlist member. - * @param[in] metadata The handle to metadata of the playlist item. + * @param[in] index The ID of the playlist member + * @param[in] metadata The handle to metadata of the playlist item * @param[in] user_data The user data passed from the foreach function * * @return @c true to continue with the next iteration of the loop, @@ -99,10 +99,12 @@ typedef bool (*mc_playlist_item_cb)(const char *index, mc_metadata_h metadata, v * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory * - * @pre The playlist handle should be received by calling mc_playlist_foreach_playlist() or mc_playlist_get_playlist(). + * @pre The playlist handle should be received by calling mc_playlist_foreach_playlist(), mc_playlist_get_playlist() or mc_playlist_updated_cb(). * * @see mc_playlist_foreach_playlist() * @see mc_playlist_get_playlist() + * @see mc_playlist_updated_cb() + * @see mc_client_set_playlist_updated_cb() * @see mc_playlist_destroy() */ int mc_playlist_get_name(mc_playlist_h playlist, char **playlist_name); @@ -112,7 +114,7 @@ int mc_playlist_get_name(mc_playlist_h playlist, char **playlist_name); * @since_tizen 5.5 * * @param[in] playlist The handle of the media controller playlist - * @param[out] item_count The number of media items. + * @param[out] item_count The number of media items * * @return @c 0 on success, * otherwise a negative error value @@ -121,10 +123,12 @@ int mc_playlist_get_name(mc_playlist_h playlist, char **playlist_name); * @retval #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #MEDIA_CONTROLLER_ERROR_INVALID_OPERATION Invalid operation * - * @pre The playlist handle should be received by calling mc_playlist_foreach_playlist() or mc_playlist_get_playlist(). + * @pre The playlist handle should be received by calling mc_playlist_foreach_playlist(), mc_playlist_get_playlist() or mc_playlist_updated_cb(). * * @see mc_playlist_foreach_playlist() * @see mc_playlist_get_playlist() + * @see mc_playlist_updated_cb() + * @see mc_client_set_playlist_updated_cb() * @see mc_playlist_destroy() */ int mc_playlist_get_item_count(mc_playlist_h playlist, int *item_count); @@ -148,11 +152,13 @@ int mc_playlist_get_item_count(mc_playlist_h playlist, int *item_count); * @retval #MEDIA_CONTROLLER_ERROR_INVALID_OPERATION Invalid operation * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory * - * @pre The playlist handle should be received by calling mc_playlist_foreach_playlist() or mc_playlist_get_playlist(). + * @pre The playlist handle should be received by calling mc_playlist_foreach_playlist(), mc_playlist_get_playlist() or mc_playlist_updated_cb(). * @post This function invokes mc_playlist_item_cb(). * * @see mc_playlist_foreach_playlist() * @see mc_playlist_get_playlist() + * @see mc_playlist_updated_cb() + * @see mc_client_set_playlist_updated_cb() * @see mc_playlist_item_cb() * @see mc_playlist_destroy() */ @@ -172,7 +178,7 @@ int mc_playlist_foreach_item(mc_playlist_h playlist, mc_playlist_item_cb callbac * You must add privilege %http://tizen.org/privilege/mediacontroller.client, if your application is a media controller client. * * @param[in] app_id The app_id of the media controller server - * @param[out] playlist_count The number of playlists that the media controller server has. + * @param[out] playlist_count The number of playlists that the media controller server has * * @return @c 0 on success, * otherwise a negative error value diff --git a/include/media_controller_server.h b/include/media_controller_server.h index e6d9c82..9ed268c 100644 --- a/include/media_controller_server.h +++ b/include/media_controller_server.h @@ -30,7 +30,8 @@ extern "C" { /** * @file media_controller_server.h * @brief This file contains the media controller server API and functions related with handling media controller server. \n - * Functions include operations to send the latest status of the server to client. + * Functions include operations to send the latest status of the server to clients. + * It also includes functions that can process commands received from clients. */ /** @@ -43,7 +44,7 @@ extern "C" { * @since_tizen 4.0 * * @remarks The callback is called in the dbus event loop.\n - * If @a request_id is not null, the server should send the reply to the client with the @a request_id. \n + * If @a request_id is not null, the server should send the reply to the media controller client with the @a request_id by using mc_server_send_cmd_reply(). \n * The @a client_name and @a request_id should not be released by the application. \n * The @a client_name and @a request_id can be used only in the callback. To use outside, make a copy. * @@ -64,7 +65,7 @@ typedef void (*mc_server_playback_action_cmd_received_cb)(const char* client_nam * @since_tizen 4.0 * * @remarks The callback is called in the dbus event loop.\n - * If @a request_id is not null, the server should send the reply to the client with the @a request_id.\n + * If @a request_id is not null, the server should send the reply to the media controller client with the @a request_id by using mc_server_send_cmd_reply().\n * The @a client_name and @a request_id should not be released by the application. \n * The @a client_name and @a request_id can be used only in the callback. To use outside, make a copy. * @@ -85,7 +86,7 @@ typedef void (*mc_server_playback_position_cmd_received_cb)(const char* client_n * @since_tizen 4.0 * * @remarks The callback is called in the dbus event loop.\n - * If @a request_id is not null, the server should send the reply to the client with the @a request_id.\n + * If @a request_id is not null, the server should send the reply to the media controller client with the @a request_id by using mc_server_send_cmd_reply().\n * The @a client_name and @a request_id should not be released by the application. \n * The @a client_name and @a request_id can be used only in the callback. To use outside, make a copy. * @@ -106,7 +107,7 @@ typedef void (*mc_server_shuffle_mode_cmd_received_cb)(const char* client_name, * @since_tizen 4.0 * * @remarks The callback is called in the dbus event loop.\n - * If @a request_id is not null, the server should send the reply to the client with the @a request_id.\n + * If @a request_id is not null, the server should send the reply to the media controller client with the @a request_id by using mc_server_send_cmd_reply().\n * The @a client_name and @a request_id should not be released by the application. \n * The @a client_name and @a request_id can be used only in the callback. To use outside, make a copy. * @@ -127,7 +128,7 @@ typedef void (*mc_server_repeat_mode_cmd_received_cb)(const char* client_name, c * @since_tizen 4.0 * * @remarks The callback is called in the dbus event loop. \n - * If @a request_id is not null, the server should send the reply to the client with the @a request_id.\n + * If @a request_id is not null, the server should send the reply to the media controller client with the @a request_id by using mc_server_send_cmd_reply().\n * The @a client_name, @a request_id, @a playlist_name and @a index should not be released by the application. \n * The @a client_name, @a request_id, @a playlist_name and @a index can be used only in the callback. To use outside, make a copy. * @@ -148,12 +149,10 @@ typedef void (*mc_server_playlist_cmd_received_cb)(const char* client_name, cons /** * @brief Called when the Server receives custom command from the client. - * @details This callback is called when server receives custom command from client. - * If you want to reply to the command, call mc_server_send_cmd_reply() function. * @since_tizen 4.0 * * @remarks The callback is called in the dbus event loop. @a data should be released using bundle_free().\n - * If @a request_id is not null, the server should send the reply to the client with the @a request_id.\n + * If @a request_id is not null, the server should send the reply to the media controller client with the @a request_id by using mc_server_send_cmd_reply().\n * The @a client_name, @a request_id and @a command should not be released by the application. \n * The @a client_name, @a request_id and @a command can be used only in the callback. To use outside, make a copy. * @@ -216,12 +215,10 @@ typedef void (*mc_server_event_reply_received_cb)(const char *client_name, const /** * @brief Called when the Server receives search command from the client. - * @details This callback is called when server receives search command from client. - * If you want to reply to the command, call mc_server_send_cmd_reply() function. * @since_tizen 5.0 * * @remarks The callback is called in the dbus event loop.\n - * If @a request_id is not null, the server should send the reply to the client with the @a request_id.\n + * If @a request_id is not null, the server should send the reply to the media controller client with the @a request_id by using mc_server_send_cmd_reply().\n * The @a client_name, @a request_id and @a search should not be released by the application. \n * The @a client_name and @a request_id can be used only in the callback. To use outside, make a copy.\n * @a search also can be used only in the callback. To use outside, make a copy using mc_search_clone(). @@ -245,7 +242,7 @@ typedef void (*mc_server_search_cmd_received_cb)(const char *client_name, const * @since_tizen 5.5 * * @remarks The callback is called in the dbus event loop.\n - * If @a request_id is not null, the server should send the reply to the client with the @a request_id.\n + * If @a request_id is not null, the server should send the reply to the media controller client with the @a request_id by using mc_server_send_cmd_reply().\n * The @a client_name and @a request_id should not be released by the application. \n * The @a client_name and @a request_id can be used only in the callback. To use outside, make a copy. * @@ -267,7 +264,7 @@ typedef void (*mc_server_enable_cmd_received_cb)(const char* client_name, const * @since_tizen 5.5 * * @remarks The callback is called in the dbus event loop.\n - * If @a request_id is not null, the server should send the reply to the client with the @a request_id.\n + * If @a request_id is not null, the server should send the reply to the media controller client with the @a request_id by using mc_server_send_cmd_reply().\n * The @a client_name and @a request_id should not be released by the application. \n * The @a client_name and @a request_id can be used only in the callback. To use outside, make a copy. * @@ -288,7 +285,7 @@ typedef void (*mc_server_display_mode_cmd_received_cb)(const char* client_name, * @since_tizen 5.5 * * @remarks The callback is called in the dbus event loop.\n - * If @a request_id is not null, the server should send the reply to the client with the @a request_id.\n + * If @a request_id is not null, the server should send the reply to the media controller client with the @a request_id by using mc_server_send_cmd_reply().\n * The @a client_name and @a request_id should not be released by the application. \n * The @a client_name and @a request_id can be used only in the callback. To use outside, make a copy. * @@ -306,6 +303,7 @@ typedef void (*mc_server_display_rotation_cmd_received_cb)(const char* client_na /** * @brief Creates a media controller server. + * @details If this function is called, the server information with #MC_SERVER_STATE_ACTIVATE will be sent to media controller clients who set callback by using mc_client_set_server_updated_cb(). * @since_tizen 2.4 * * @privlevel public @@ -323,6 +321,7 @@ typedef void (*mc_server_display_rotation_cmd_received_cb)(const char* client_na * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory * * @see mc_server_destroy() + * @see mc_client_set_server_updated_cb() */ int mc_server_create(mc_server_h *server); @@ -378,7 +377,7 @@ int mc_server_set_playback_position(mc_server_h server, unsigned long long posit /** * @brief Sets the playlist name and index of the current playing media in the playlist to update the latest playback info. - * @details If a media controller server has a playlist, the server can register and share it with media controller client. + * @details If a media controller server has a playlist, the server can register and share it with media controller clients. * A playlist is a set of "index" and "media metadata".\n * The media controller server can let media controller clients know the playlist name and index of current playing media by using this function. * @since_tizen 5.0 @@ -408,7 +407,6 @@ int mc_server_set_playlist_item_info(mc_server_h server, const char *playlist_na /** * @brief Sets the playback content type to update the latest playback info. - * @details If this function is called, the updated content type information will be sent to all clients. * @since_tizen 5.0 * * @privlevel public @@ -436,7 +434,7 @@ int mc_server_set_playback_content_type(mc_server_h server, mc_content_type_e co /** * @brief Sets the content age rating to update the latest playback info. - * @details If this function is called, the updated age rating information will be sent to all clients. Default value is #MC_CONTENT_RATING_ALL. + * @details Default value is #MC_CONTENT_RATING_ALL. * @since_tizen 5.0 * * @privlevel public @@ -462,7 +460,7 @@ int mc_server_set_content_age_rating(mc_server_h server, mc_content_age_rating_e /** * @brief Updates the modified playback info. - * @details If this function is called, the updated playback information will be sent to the controller. + * @details If this function is called, the updated playback information will be sent to media controller clients who set callback by using mc_client_set_playback_updated_cb(). * @since_tizen 2.4 * * @privlevel public @@ -480,6 +478,12 @@ int mc_server_set_content_age_rating(mc_server_h server, mc_content_age_rating_e * @pre Create a media controller server handle by calling mc_server_create(). * @see mc_server_create() * @see mc_server_destroy() + * @see mc_server_set_playback_state() + * @see mc_server_set_playback_position() + * @see mc_server_set_playlist_item_info() + * @see mc_server_set_playback_content_type() + * @see mc_server_set_content_age_rating() + * @see mc_client_set_playback_updated_cb() */ int mc_server_update_playback_info(mc_server_h server); @@ -511,7 +515,7 @@ int mc_server_set_metadata(mc_server_h server, mc_meta_e attribute, const char * /** * @brief Updates the modified metadata info. - * @details If this function is called, the updated metadata will be sent to all clients. + * @details If this function is called, the updated metadata will be sent to media controller clients who set callback by using mc_client_set_metadata_updated_cb(). * @since_tizen 2.4 * * @privlevel public @@ -527,14 +531,17 @@ int mc_server_set_metadata(mc_server_h server, mc_meta_e attribute, const char * * @retval #MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORY Out of memory * * @pre Create a media controller server handle by calling mc_server_create(). + * @pre Set metadata by calling mc_server_set_metadata(). * @see mc_server_create() * @see mc_server_destroy() + * @see mc_server_set_metadata() + * @see mc_client_set_metadata_updated_cb() */ int mc_server_update_metadata(mc_server_h server); /** * @brief Updates the modified shuffle mode. - * @details If this function is called, the updated mode information will be sent to all clients. + * @details If this function is called, the updated mode information will be sent to media controller clients who set callback by using mc_client_set_shuffle_mode_updated_cb(). * @since_tizen 2.4 * * @privlevel public @@ -553,12 +560,13 @@ int mc_server_update_metadata(mc_server_h server); * @pre Create a media controller server handle by calling mc_server_create(). * @see mc_server_create() * @see mc_server_destroy() + * @see mc_client_set_shuffle_mode_updated_cb() */ int mc_server_update_shuffle_mode(mc_server_h server, mc_shuffle_mode_e mode); /** * @brief Updates the modified repeat mode. - * @details If this function is called, the updated mode information will be sent to all clients. + * @details If this function is called, the updated mode information will be sent to media controller clients who set callback by using mc_client_set_repeat_mode_updated_cb(). * @since_tizen 2.4 * * @privlevel public @@ -577,12 +585,13 @@ int mc_server_update_shuffle_mode(mc_server_h server, mc_shuffle_mode_e mode); * @pre Create a media controller server handle by calling mc_server_create(). * @see mc_server_create() * @see mc_server_destroy() + * @see mc_client_set_repeat_mode_updated_cb() */ int mc_server_update_repeat_mode(mc_server_h server, mc_repeat_mode_e mode); /** * @brief Updates the modified subtitles display status. - * @details If this function is called, the updated subtitles display status will be sent to all clients. + * @details If this function is called, the updated subtitles display status will be sent to media controller clients who set callback by using mc_client_set_subtitles_updated_cb(). * @since_tizen 5.5 * * @privlevel public @@ -603,12 +612,13 @@ int mc_server_update_repeat_mode(mc_server_h server, mc_repeat_mode_e mode); * @pre Create a media controller server handle by calling mc_server_create(). * @see mc_server_create() * @see mc_server_destroy() + * @see mc_client_set_subtitles_updated_cb() */ int mc_server_update_subtitles_enabled(mc_server_h server, bool enabled); /** * @brief Updates the modified 360 mode display status. - * @details If this function is called, the updated 360 mode display status will be sent to all clients. + * @details If this function is called, the updated 360 mode display status will be sent to media controller clients who set callback by using mc_client_set_360_mode_updated_cb(). * @since_tizen 5.5 * * @privlevel public @@ -629,12 +639,13 @@ int mc_server_update_subtitles_enabled(mc_server_h server, bool enabled); * @pre Create a media controller server handle by calling mc_server_create(). * @see mc_server_create() * @see mc_server_destroy() + * @see mc_client_set_360_mode_updated_cb() */ int mc_server_update_360_mode_enabled(mc_server_h server, bool enabled); /** * @brief Updates the modified display mode. - * @details If this function is called, the updated display mode information will be sent to all clients. + * @details If this function is called, the updated display mode information will be sent to media controller clients who set callback by using mc_client_set_display_mode_updated_cb(). * @since_tizen 5.5 * * @privlevel public @@ -655,12 +666,13 @@ int mc_server_update_360_mode_enabled(mc_server_h server, bool enabled); * @pre Create a media controller server handle by calling mc_server_create(). * @see mc_server_create() * @see mc_server_destroy() + * @see mc_client_set_display_mode_updated_cb() */ int mc_server_update_display_mode(mc_server_h server, mc_display_mode_e mode); /** * @brief Updates the modified display rotation. - * @details If this function is called, the updated display rotation information will be sent to all clients. + * @details If this function is called, the updated display rotation information will be sent to media controller clients who set callback by using mc_client_set_display_rotation_updated_cb(). * @since_tizen 5.5 * * @privlevel public @@ -681,6 +693,7 @@ int mc_server_update_display_mode(mc_server_h server, mc_display_mode_e mode); * @pre Create a media controller server handle by calling mc_server_create(). * @see mc_server_create() * @see mc_server_destroy() + * @see mc_client_set_display_rotation_updated_cb() */ int mc_server_update_display_rotation(mc_server_h server, mc_display_rotation_e rotation); @@ -709,6 +722,7 @@ int mc_server_update_display_rotation(mc_server_h server, mc_display_rotation_e * @see mc_server_destroy() * @see mc_server_unset_playback_action_cmd_received_cb() * @see mc_server_set_playback_ability() + * @see mc_client_send_playback_action_cmd() */ int mc_server_set_playback_action_cmd_received_cb(mc_server_h server, mc_server_playback_action_cmd_received_cb callback, void *user_data); @@ -762,6 +776,7 @@ int mc_server_unset_playback_action_cmd_received_cb(mc_server_h server); * @see mc_server_destroy() * @see mc_server_unset_playback_position_cmd_received_cb() * @see mc_server_set_ability_support() + * @see mc_client_send_playback_position_cmd() */ int mc_server_set_playback_position_cmd_received_cb(mc_server_h server, mc_server_playback_position_cmd_received_cb callback, void *user_data); @@ -815,6 +830,7 @@ int mc_server_unset_playback_position_cmd_received_cb(mc_server_h server); * @see mc_server_destroy() * @see mc_server_unset_shuffle_mode_cmd_received_cb() * @see mc_server_set_ability_support() + * @see mc_client_send_shuffle_mode_cmd() */ int mc_server_set_shuffle_mode_cmd_received_cb(mc_server_h server, mc_server_shuffle_mode_cmd_received_cb callback, void *user_data); @@ -868,6 +884,7 @@ int mc_server_unset_shuffle_mode_cmd_received_cb(mc_server_h server); * @see mc_server_destroy() * @see mc_server_unset_repeat_mode_cmd_received_cb() * @see mc_server_set_ability_support() + * @see mc_client_send_repeat_mode_cmd() */ int mc_server_set_repeat_mode_cmd_received_cb(mc_server_h server, mc_server_repeat_mode_cmd_received_cb callback, void *user_data); @@ -921,6 +938,7 @@ int mc_server_unset_repeat_mode_cmd_received_cb(mc_server_h server); * @see mc_server_destroy() * @see mc_server_unset_playlist_cmd_received_cb() * @see mc_server_set_ability_support() + * @see mc_client_send_playlist_cmd() */ int mc_server_set_playlist_cmd_received_cb(mc_server_h server, mc_server_playlist_cmd_received_cb callback, void *user_data); @@ -974,6 +992,7 @@ int mc_server_unset_playlist_cmd_received_cb(mc_server_h server); * @see mc_server_destroy() * @see mc_server_unset_custom_cmd_received_cb() * @see mc_server_set_ability_support() + * @see mc_client_send_custom_cmd() */ int mc_server_set_custom_cmd_received_cb(mc_server_h server, mc_server_custom_cmd_received_cb callback, void *user_data); @@ -1028,6 +1047,7 @@ int mc_server_unset_custom_cmd_received_cb(mc_server_h server); * @see mc_server_destroy() * @see mc_server_unset_subtitles_cmd_received_cb() * @see mc_server_set_ability_support() + * @see mc_client_send_subtitles_cmd() */ int mc_server_set_subtitles_cmd_received_cb(mc_server_h server, mc_server_enable_cmd_received_cb callback, void *user_data); @@ -1083,6 +1103,7 @@ int mc_server_unset_subtitles_cmd_received_cb(mc_server_h server); * @see mc_server_destroy() * @see mc_server_unset_360_mode_cmd_received_cb() * @see mc_server_set_ability_support() + * @see mc_client_send_360_mode_cmd() */ int mc_server_set_360_mode_cmd_received_cb(mc_server_h server, mc_server_enable_cmd_received_cb callback, void *user_data); @@ -1138,6 +1159,7 @@ int mc_server_unset_360_mode_cmd_received_cb(mc_server_h server); * @see mc_server_destroy() * @see mc_server_unset_display_mode_cmd_received_cb() * @see mc_server_set_display_mode_ability() + * @see mc_client_send_display_mode_cmd() */ int mc_server_set_display_mode_cmd_received_cb(mc_server_h server, mc_server_display_mode_cmd_received_cb callback, void *user_data); @@ -1193,6 +1215,7 @@ int mc_server_unset_display_mode_cmd_received_cb(mc_server_h server); * @see mc_server_destroy() * @see mc_server_unset_display_rotation_cmd_received_cb() * @see mc_server_set_display_rotation_ability() + * @see mc_client_send_display_rotation_cmd() */ int mc_server_set_display_rotation_cmd_received_cb(mc_server_h server, mc_server_display_rotation_cmd_received_cb callback, void *user_data); @@ -1223,7 +1246,8 @@ int mc_server_set_display_rotation_cmd_received_cb(mc_server_h server, mc_server int mc_server_unset_display_rotation_cmd_received_cb(mc_server_h server); /** - * @brief Replies the result of the requested command to the client. + * @brief Replies the result of the requested command to the media controller client. + * @details If this function is called, reply for the command will be sent to the media controller client who set callback by using mc_client_set_cmd_reply_received_cb(). * @since_tizen 4.0 * * @privlevel public @@ -1254,6 +1278,7 @@ int mc_server_unset_display_rotation_cmd_received_cb(mc_server_h server); * @see mc_server_playlist_cmd_received_cb() * @see mc_server_custom_cmd_received_cb() * @see mc_server_destroy() + * @see mc_client_set_cmd_reply_received_cb() */ int mc_server_send_cmd_reply(mc_server_h server, const char *client_name, const char *request_id, int result_code, bundle *data); @@ -1286,7 +1311,7 @@ int mc_server_send_cmd_reply(mc_server_h server, const char *client_name, const int mc_server_foreach_client(mc_server_h server, mc_activated_client_cb callback, void *user_data); /** - * @brief Sends the customized event with the bundle data. + * @brief Sends the customized event with the bundle data to the media controller client. * @details If the event is needed in the client, this function should be called. @a data is a bundle. * @since_tizen 4.0 * @@ -1314,6 +1339,8 @@ int mc_server_foreach_client(mc_server_h server, mc_activated_client_cb callback * @see mc_server_event_reply_received_cb() * @see mc_server_set_event_reply_received_cb() * @see mc_server_destroy() + * @see mc_server_foreach_client() + * @see mc_client_set_custom_event_received_cb() */ int mc_server_send_custom_event(mc_server_h server, const char *client_name, const char *event, bundle *data, char **request_id); @@ -1342,6 +1369,8 @@ int mc_server_send_custom_event(mc_server_h server, const char *client_name, con * @see mc_server_create() * @see mc_server_unset_event_reply_received_cb() * @see mc_server_destroy() + * @see mc_server_send_custom_event() + * @see mc_client_send_event_reply() */ int mc_server_set_event_reply_received_cb(mc_server_h server, mc_server_event_reply_received_cb callback, void *user_data); @@ -1392,6 +1421,7 @@ int mc_server_unset_event_reply_received_cb(mc_server_h server); * @see mc_server_destroy() * @see mc_server_unset_search_cmd_received_cb() * @see mc_server_set_ability_support() + * @see mc_client_send_search_cmd() */ int mc_server_set_search_cmd_received_cb(mc_server_h server, mc_server_search_cmd_received_cb callback, void *user_data); @@ -1422,6 +1452,7 @@ int mc_server_unset_search_cmd_received_cb(mc_server_h server); /** * @brief Destroys media controller server. + * @details If this function is called, the changed server's state to #MC_SERVER_STATE_DEACTIVATE will be sent to media controller clients who set callback by using mc_client_set_server_updated_cb(). * @since_tizen 2.4 * * @remarks After the server is destroyed, all its abilities will be initialized to the default automatically. @@ -1435,6 +1466,7 @@ int mc_server_unset_search_cmd_received_cb(mc_server_h server); * * @pre Create a media controller server handle by calling mc_server_create(). * @see mc_server_create() + * @see mc_client_set_server_updated_cb() */ int mc_server_destroy(mc_server_h server); @@ -1510,6 +1542,7 @@ int mc_server_add_item_to_playlist(mc_server_h server, mc_playlist_h playlist, c /** * @brief Registers items to the playlist. + * @details If this function is called, the updated playlist information with mode #MC_PLAYLIST_UPDATED will be sent to media controller clients who set callback by using mc_client_set_playlist_updated_cb(). * @since_tizen 4.0 * * @privlevel public @@ -1529,15 +1562,19 @@ int mc_server_add_item_to_playlist(mc_server_h server, mc_playlist_h playlist, c * * @pre Create a media controller server handle by calling mc_server_create(). * @pre Create a media controller playlist handle by calling mc_server_create_playlist(). + * @pre Add items to the playlist by calling mc_server_add_item_to_playlist(). * @see mc_server_create() * @see mc_server_destroy() * @see mc_server_create_playlist() + * @see mc_server_add_item_to_playlist() * @see mc_playlist_destroy() + * @see mc_client_set_playlist_updated_cb() */ int mc_server_update_playlist_done(mc_server_h server, mc_playlist_h playlist); /** * @brief Deletes the playlist of the media controller server. + * @details If this function is called, the updated playlist information with mode #MC_PLAYLIST_REMOVED will be sent to media controller clients who set callback by using mc_client_set_playlist_updated_cb(). * @since_tizen 4.0 * * @privlevel public @@ -1561,18 +1598,33 @@ int mc_server_update_playlist_done(mc_server_h server, mc_playlist_h playlist); * @see mc_server_destroy() * @see mc_server_create_playlist() * @see mc_playlist_destroy() + * @see mc_client_set_playlist_updated_cb() */ int mc_server_delete_playlist(mc_server_h server, mc_playlist_h playlist); /** - * @brief Sets the playback ability's support of the media controller. + * @brief Sets the playback ability's support of the media controller server. + * @details This function allows setting the support for the following abilities: \n + * #MC_PLAYBACK_ACTION_PLAY, \n + * #MC_PLAYBACK_ACTION_PAUSE, \n + * #MC_PLAYBACK_ACTION_STOP, \n + * #MC_PLAYBACK_ACTION_NEXT, \n + * #MC_PLAYBACK_ACTION_PREV, \n + * #MC_PLAYBACK_ACTION_FAST_FORWARD, \n + * #MC_PLAYBACK_ACTION_REWIND, \n + * #MC_PLAYBACK_ACTION_TOGGLE_PLAY_PAUSE, \n + * To set the support for other abilities, use corresponding function. \n + * For a ability like shuffle, repeat, use mc_server_set_ability_support(). \n + * For a display mode ability, use mc_server_set_display_mode_ability(). \n + * For a display rotation ability, use mc_server_set_display_rotation_ability(). \n * @since_tizen 5.0 * * @privlevel public * @privilege %http://tizen.org/privilege/mediacontroller.server * * @remarks If @a support is #MC_ABILITY_SUPPORTED_UNDECIDED, this function will return #MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER. - * To notify all clients about the changes of the playback's ability support, use mc_server_update_playback_ability(). + * Default value is #MC_ABILITY_SUPPORTED_UNDECIDED. \n + * To notify media controller clients about the changes of the playback's ability support, use mc_server_update_playback_ability(). * * @param[in] server The handle to media controller server * @param[in] action The playback action @@ -1595,7 +1647,7 @@ int mc_server_set_playback_ability(mc_server_h server, mc_playback_action_e acti /** * @brief Updates the modified ability info. - * @details If this function is called, the updated ability will be sent to all clients. + * @details If this function is called, the updated ability will be sent to media controller clients who set callback by using mc_client_set_playback_ability_updated_cb(). * @since_tizen 5.0 * * @privlevel public @@ -1615,24 +1667,26 @@ int mc_server_set_playback_ability(mc_server_h server, mc_playback_action_e acti * @see mc_server_create() * @see mc_server_destroy() * @see mc_server_set_playback_ability() + * @see mc_client_set_playback_ability_updated_cb() */ int mc_server_update_playback_ability(mc_server_h server); /** * @brief Sets the ability's support of the media controller. - * @details This function allows setting the support for the following abilities: - * #MC_ABILITY_SHUFFLE, \n - * #MC_ABILITY_REPEAT, \n - * #MC_ABILITY_PLAYBACK_POSITION, \n - * #MC_ABILITY_PLAYLIST, \n - * #MC_ABILITY_CLIENT_CUSTOM, \n - * #MC_ABILITY_SEARCH, \n - * #MC_ABILITY_SUBTITLES, \n - * #MC_ABILITY_360_MODE, \n - * To set the support for other abilities, use corresponding function. \n - * For a playback ability, use mc_server_set_playback_ability() and mc_server_update_playback_ability(). \n - * For a display mode ability, use mc_server_set_display_mode_ability(). \n - * For a display rotation ability, use mc_server_set_display_rotation_ability(). \n + * @details This function allows setting the support for the following abilities: \n + * #MC_ABILITY_SHUFFLE, \n + * #MC_ABILITY_REPEAT, \n + * #MC_ABILITY_PLAYBACK_POSITION, \n + * #MC_ABILITY_PLAYLIST, \n + * #MC_ABILITY_CLIENT_CUSTOM, \n + * #MC_ABILITY_SEARCH, \n + * #MC_ABILITY_SUBTITLES, \n + * #MC_ABILITY_360_MODE, \n + * If this function is called, the updated ability will be sent to media controller clients who set callback by using mc_client_set_ability_support_updated_cb(). + * To set the support for other abilities, use corresponding function. \n + * For a playback ability, use mc_server_set_playback_ability() and mc_server_update_playback_ability(). \n + * For a display mode ability, use mc_server_set_display_mode_ability(). \n + * For a display rotation ability, use mc_server_set_display_rotation_ability(). \n * @since_tizen 5.5 * * @privlevel public @@ -1662,11 +1716,13 @@ int mc_server_update_playback_ability(mc_server_h server); * @see mc_server_update_playback_ability() * @see mc_server_set_display_mode_ability() * @see mc_server_set_display_rotation_ability() + * @see mc_client_set_ability_support_updated_cb() */ int mc_server_set_ability_support(mc_server_h server, mc_ability_e ability, mc_ability_support_e support); /** * @brief Sets the display mode ability of the media controller. + * @details If this function is called, the updated display mode will be sent to media controller clients who set callback by using mc_client_set_display_mode_ability_updated_cb(). * @since_tizen 5.5 * * @privlevel public @@ -1691,11 +1747,13 @@ int mc_server_set_ability_support(mc_server_h server, mc_ability_e ability, mc_a * @see mc_server_create() * @see mc_server_destroy() * @see mc_server_set_display_mode_cmd_received_cb() + * @see mc_client_set_display_mode_ability_updated_cb() */ int mc_server_set_display_mode_ability(mc_server_h server, unsigned int mode, mc_ability_support_e support); /** * @brief Sets the display rotation ability of the media controller. + * @details If this function is called, the updated display rotation will be sent to media controller clients who set callback by using mc_client_set_display_rotation_ability_updated_cb(). * @since_tizen 5.5 * * @privlevel public @@ -1719,6 +1777,7 @@ int mc_server_set_display_mode_ability(mc_server_h server, unsigned int mode, mc * @pre Create a media controller server handle by calling mc_server_create(). * @see mc_server_create() * @see mc_server_destroy() + * @see mc_client_set_display_rotation_ability_updated_cb() */ int mc_server_set_display_rotation_ability(mc_server_h server, unsigned int rotation, mc_ability_support_e support); @@ -1744,6 +1803,7 @@ int mc_server_set_display_rotation_ability(mc_server_h server, unsigned int rota * @pre Create a media controller server handle by calling mc_server_create(). * @see mc_server_create() * @see mc_server_destroy() + * @see mc_client_get_server_icon() */ int mc_server_set_icon(mc_server_h server, const char *uri); diff --git a/include/media_controller_type.h b/include/media_controller_type.h index 883dfe9..a703542 100644 --- a/include/media_controller_type.h +++ b/include/media_controller_type.h @@ -95,6 +95,9 @@ typedef enum { /** * @brief Enumeration for the media controller server state. * @since_tizen 2.4 + * + * @see mc_client_get_latest_server_info() + * @see mc_server_state_updated_cb() */ typedef enum { MC_SERVER_STATE_NONE = 0, /**< None state*/ @@ -105,6 +108,10 @@ typedef enum { /** * @brief Enumeration for the media meta info. * @since_tizen 2.4 + * + * @see mc_server_set_metadata() + * @see mc_server_add_item_to_playlist() + * @see mc_metadata_get() */ typedef enum { MC_META_MEDIA_TITLE = 0, /**< Title */ @@ -124,8 +131,11 @@ typedef enum { } mc_meta_e; /** - * @brief Enumeration for the media playback state. + * @brief Enumeration for the media playback state of the media controller server. * @since_tizen 2.4 + * + * @see mc_server_set_playback_state() + * @see mc_client_get_playback_state() */ typedef enum { MC_PLAYBACK_STATE_NONE = 0, /**< None */ @@ -143,7 +153,16 @@ typedef enum { /** * @brief Enumeration for the media playback action. + * @details Media controller clients can control media controller server's playback by calling mc_client_send_playback_action_cmd() or mc_client_send_playlist_cmd(). \n + * Media controller servers have to set proper playback ability by using mc_server_set_playback_ability(). * @since_tizen 4.0 + * + * @see mc_server_set_playback_ability() + * @see mc_client_send_playback_action_cmd() + * @see mc_client_send_playlist_cmd() + * @see mc_playback_action_is_supported() + * @see mc_server_playback_action_cmd_received_cb() + * @see mc_server_playlist_cmd_received_cb() */ typedef enum { MC_PLAYBACK_ACTION_PLAY, /**< Play */ @@ -157,8 +176,14 @@ typedef enum { } mc_playback_action_e; /** - * @brief Enumeration for the shuffle mode. + * @brief Enumeration for the shuffle mode of the media controller server. * @since_tizen 2.4 + * + * @see mc_server_update_shuffle_mode() + * @see mc_server_shuffle_mode_cmd_received_cb() + * @see mc_client_get_server_shuffle_mode() + * @see mc_client_send_shuffle_mode_cmd() + * @see mc_shuffle_mode_updated_cb() */ typedef enum { MC_SHUFFLE_MODE_ON = 0, /**< Shuffle mode on */ @@ -166,8 +191,14 @@ typedef enum { } mc_shuffle_mode_e; /** - * @brief Enumeration for the repeat mode. + * @brief Enumeration for the repeat mode of the media controller server. * @since_tizen 2.4 + * + * @see mc_server_update_repeat_mode() + * @see mc_server_repeat_mode_cmd_received_cb() + * @see mc_client_get_server_repeat_mode() + * @see mc_client_send_repeat_mode_cmd() + * @see mc_repeat_mode_updated_cb() */ typedef enum { MC_REPEAT_MODE_ON = 0, /**< Repeat mode on for all media*/ @@ -176,8 +207,12 @@ typedef enum { } mc_repeat_mode_e; /** - * @brief Enumeration for the subscription type. + * @brief Enumeration for the subscription type of the media controller client. * @since_tizen 2.4 + * + * @see mc_client_subscribe() + * @see mc_client_unsubscribe() + * @see mc_client_foreach_server_subscribed() */ typedef enum { MC_SUBSCRIPTION_TYPE_SERVER_STATE = 0, /**< Server state */ @@ -194,7 +229,13 @@ typedef enum { /** * @brief Enumeration for the playlist update mode. + * @details Media controller clients can know the playlist change status of the media controller server by calling mc_client_set_playlist_updated_cb(). \n * @since_tizen 4.0 + * + * @see mc_client_set_playlist_updated_cb() + * @see mc_playlist_updated_cb() + * @see mc_server_update_playlist_done() + * @see mc_server_delete_playlist() */ typedef enum { MC_PLAYLIST_UPDATED, /**< Create or Update playlist */ @@ -202,8 +243,14 @@ typedef enum { } mc_playlist_update_mode_e; /** - * @brief Enumeration for the content type of the content. + * @brief Enumeration for the content type of the media content by the media controller server. + * @details Media controller clients can use this to know the playback status of the media controller server. \n + * And media controller clients can also use to search for the content provided by the media controller server. * @since_tizen 5.0 + * + * @see mc_server_set_playback_content_type() + * @see mc_client_get_playback_content_type() + * @see mc_search_set_condition() */ typedef enum { MC_CONTENT_TYPE_IMAGE = 0, /**< Image content type */ @@ -214,8 +261,11 @@ typedef enum { } mc_content_type_e; /** - * @brief Enumeration for the content age rating of the content. + * @brief Enumeration for the content age rating of the media content by the media controller server. * @since_tizen 5.0 + * + * @see mc_server_set_content_age_rating() + * @see mc_client_get_age_rating() */ typedef enum { MC_CONTENT_RATING_ALL = 0, /**< Suitable for all ages */ @@ -241,8 +291,19 @@ typedef enum { } mc_content_age_rating_e; /** - * @brief Enumeration for the support of the ability. + * @brief Enumeration for the support of the ability by the media controller server. * @since_tizen 5.0 + * + * @remarks The media controller server should set the proper abilities. \n + * Only then can media controller clients send the appropriate control commands. + * + * @see mc_server_set_playback_ability() + * @see mc_server_set_ability_support() + * @see mc_server_set_display_mode_ability() + * @see mc_server_set_display_rotation_ability() + * @see mc_client_get_server_ability_support() + * @see mc_ability_support_updated_cb() + * @see mc_playback_action_is_supported() */ typedef enum { MC_ABILITY_SUPPORTED_YES = 0, /**< Supported */ @@ -251,8 +312,12 @@ typedef enum { } mc_ability_support_e; /** - * @brief Enumeration for the ability. + * @brief Enumeration for the ability of the media controller server. * @since_tizen 5.5 + * + * @see mc_server_set_ability_support() + * @see mc_client_get_server_ability_support() + * @see mc_ability_support_updated_cb() */ typedef enum { MC_ABILITY_SHUFFLE, /**< Shuffle */ @@ -267,7 +332,10 @@ typedef enum { /** * @brief Enumeration for the search category. + * @details Media controller clients can use this to search for the content provided by the media controller server. * @since_tizen 5.0 + * + * @see mc_search_set_condition() */ typedef enum { MC_SEARCH_NO_CATEGORY = 0, /**< No search category */ @@ -279,8 +347,14 @@ typedef enum { } mc_search_category_e; /** - * @brief Enumeration for the display mode. + * @brief Enumeration for the display mode of the media controller server. * @since_tizen 5.5 + * + * @see mc_server_update_display_mode() + * @see mc_server_display_mode_cmd_received_cb() + * @see mc_client_get_server_display_mode() + * @see mc_client_send_display_mode_cmd() + * @see mc_display_mode_updated_cb() */ typedef enum { MC_DISPLAY_MODE_LETTER_BOX = 1 << 0, /**< Letter box */ @@ -290,8 +364,14 @@ typedef enum { } mc_display_mode_e; /** - * @brief Enumeration for the display rotation. + * @brief Enumeration for the display rotation of the media controller server. * @since_tizen 5.5 + * + * @see mc_server_update_display_rotation() + * @see mc_server_display_rotation_cmd_received_cb() + * @see mc_client_get_server_display_rotation() + * @see mc_client_send_display_rotation_cmd() + * @see mc_display_rotation_updated_cb() */ typedef enum { MC_DISPLAY_ROTATION_NONE = 1 << 0, /**< Display is not rotated */ diff --git a/packaging/capi-media-controller.spec b/packaging/capi-media-controller.spec index 905800d..26267b8 100644 --- a/packaging/capi-media-controller.spec +++ b/packaging/capi-media-controller.spec @@ -1,6 +1,6 @@ Name: capi-media-controller Summary: A media controller library in Tizen Native API -Version: 1.0.5 +Version: 1.0.6 Release: 0 Group: Multimedia/API License: Apache-2.0 |