From: Sangchul Lee Date: Wed, 23 Jun 2021 08:29:45 +0000 (+0900) Subject: Revise doxygen X-Git-Tag: submit/tizen/20210729.023123~21 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=d212c7108e7c12fc90498ce182f86ed749d94799;p=platform%2Fcore%2Fapi%2Fwebrtc.git Revise doxygen Remarks regarding callback thread are added. Fix invalid parameter direction. Add missing release handle information. Put a space after using '\n' command. [Version] 0.2.39 [Issue Type] Doxygen Change-Id: I0dc23a36b4cab50cc74809df20168f5f11e94f12 Signed-off-by: Sangchul Lee --- diff --git a/include/webrtc.h b/include/webrtc.h index abb196cb..df670367 100644 --- a/include/webrtc.h +++ b/include/webrtc.h @@ -27,10 +27,6 @@ extern "C" { #endif /* __cplusplus */ -#ifndef TIZEN_ERROR_MEDIA_WEBRTC -#define TIZEN_ERROR_MEDIA_WEBRTC -0x03000000 -#endif - /** * @file webrtc.h * @brief This file contains the WebRTC API. @@ -247,7 +243,8 @@ typedef enum { * #WEBRTC_ERROR_RESOURCE_FAILED\n * #WEBRTC_ERROR_RESOURCE_CONFLICT * @since_tizen 6.5 - * @remarks The @a webrtc is the same object for which the callback was set.\nThe @a webrtc should not be released. + * @remarks The @a webrtc is the same object for which the callback was set.\n + * The @a webrtc should not be released. * @param[in] webrtc WebRTC handle * @param[in] error The error code * @param[in] state The current state of the WebRTC handle @@ -260,7 +257,8 @@ typedef void (*webrtc_error_cb)(webrtc_h webrtc, webrtc_error_e error, webrtc_st /** * @brief Called when the WebRTC state is changed. * @since_tizen 6.5 - * @remarks The @a webrtc is the same object for which the callback was set.\nThe @a webrtc should not be released. + * @remarks The @a webrtc is the same object for which the callback was set.\n + * The @a webrtc should not be released. * @param[in] webrtc WebRTC handle * @param[in] previous The previous state of the WebRTC handle * @param[in] current The current state of the WebRTC handle @@ -273,7 +271,8 @@ typedef void (*webrtc_state_changed_cb)(webrtc_h webrtc, webrtc_state_e previous /** * @brief Called when the WebRTC peer connection state is changed. * @since_tizen 6.5 - * @remarks The @a webrtc is the same object for which the callback was set.\nThe @a webrtc should not be released. + * @remarks The @a webrtc is the same object for which the callback was set.\n + * The @a webrtc should not be released. * @param[in] webrtc WebRTC handle * @param[in] state The peer connection state * @param[in] user_data The user data passed from the callback registration function @@ -285,7 +284,8 @@ typedef void (*webrtc_peer_connection_state_change_cb)(webrtc_h webrtc, webrtc_p /** * @brief Called when the WebRTC signaling state is changed. * @since_tizen 6.5 - * @remarks The @a webrtc is the same object for which the callback was set.\nThe @a webrtc should not be released. + * @remarks The @a webrtc is the same object for which the callback was set.\n + * The @a webrtc should not be released. * @param[in] webrtc WebRTC handle * @param[in] state The signaling state * @param[in] user_data The user data passed from the callback registration function @@ -297,7 +297,8 @@ typedef void (*webrtc_signaling_state_change_cb)(webrtc_h webrtc, webrtc_signali /** * @brief Called when the WebRTC ICE gathering state is changed. * @since_tizen 6.5 - * @remarks The @a webrtc is the same object for which the callback was set.\nThe @a webrtc should not be released. + * @remarks The @a webrtc is the same object for which the callback was set.\n + * The @a webrtc should not be released. * @param[in] webrtc WebRTC handle * @param[in] state The ICE gathering state * @param[in] user_data The user data passed from the callback registration function @@ -309,7 +310,8 @@ typedef void (*webrtc_ice_gathering_state_change_cb)(webrtc_h webrtc, webrtc_ice /** * @brief Called when the WebRTC ICE connection state is changed. * @since_tizen 6.5 - * @remarks The @a webrtc is the same object for which the callback was set.\nThe @a webrtc should not be released. + * @remarks The @a webrtc is the same object for which the callback was set.\n + * The @a webrtc should not be released. * @param[in] webrtc WebRTC handle * @param[in] state The ICE connection state * @param[in] user_data The user data passed from the callback registration function @@ -332,7 +334,8 @@ typedef bool (*webrtc_turn_server_cb)(const char *turn_server, void *user_data); /** * @brief Called when the WebRTC needs session negotiation. * @since_tizen 6.5 - * @remarks The @a webrtc is the same object for which the callback was set.\nThe @a webrtc should not be released. + * @remarks The @a webrtc is the same object for which the callback was set.\n + * The @a webrtc should not be released. * @param[in] webrtc WebRTC handle * @param[in] user_data The user data passed from the callback registration function * @see webrtc_set_negotiation_needed_cb() @@ -343,7 +346,8 @@ typedef void (*webrtc_negotiation_needed_cb)(webrtc_h webrtc, void *user_data); /** * @brief Called when the WebRTC needs to send the ICE candidate message to the remote peer through the signaling channel. * @since_tizen 6.5 - * @remarks The @a webrtc is the same object for which the callback was set.\nThe @a webrtc should not be released. + * @remarks The @a webrtc is the same object for which the callback was set.\n + * The @a webrtc should not be released. * @param[in] webrtc WebRTC handle * @param[in] candidate The ICE candidate message * @param[in] user_data The user data passed from the callback registration function @@ -355,7 +359,8 @@ typedef void (*webrtc_ice_candidate_cb)(webrtc_h webrtc, const char *candidate, /** * @brief Called when a new track has been added to the WebRTC pipeline after the negotiation. * @since_tizen 6.5 - * @remarks The @a webrtc is the same object for which the callback was set.\nThe @a webrtc should not be released. + * @remarks The @a webrtc is the same object for which the callback was set.\n + * The @a webrtc should not be released. * @param[in] webrtc WebRTC handle * @param[in] type The media type * @param[in] track_id The track id @@ -397,7 +402,8 @@ typedef void (*webrtc_media_packet_source_buffer_state_changed_cb)(unsigned int /** * @brief Called when each audio or video frame is ready to be rendered via the WebRTC pipeline after the negotiation. * @since_tizen 6.5 - * @remarks The @a webrtc is the same object for which the callback was set.\nThe @a webrtc should not be released.\n + * @remarks The @a webrtc is the same object for which the callback was set.\n + * The @a webrtc should not be released.\n * Use media_packet_get_buffer_data_ptr() with @a packet to get the Gstreamer buffer pointer.\n * The @a packet should be released using media_packet_destroy(). * @param[in] webrtc WebRTC handle @@ -425,7 +431,8 @@ typedef void (*webrtc_encoded_frame_cb)(webrtc_h webrtc, webrtc_media_type_e typ /** * @brief Called when the data channel is created to the connection by the remote peer. * @since_tizen 6.5 - * @remarks The @a webrtc is the same object for which the callback was set.\nThe @a webrtc should not be released.\n + * @remarks The @a webrtc is the same object for which the callback was set.\n + * The @a webrtc should not be released.\n * The @a channel should not be released. * @param[in] webrtc WebRTC handle * @param[in] channel WebRTC data channel handle @@ -444,7 +451,8 @@ typedef void (*webrtc_data_channel_cb)(webrtc_h webrtc, webrtc_data_channel_h ch /** * @brief Called when the data channel's underlying data transport is established. * @since_tizen 6.5 - * @remarks The @a channel is the same object for which the callback was set.\nThe @a channel should not be released. + * @remarks The @a channel is the same object for which the callback was set.\n + * The @a channel should not be released. * @param[in] channel WebRTC data channel handle * @param[in] user_data The user data passed from the callback registration function * @see webrtc_create_data_channel() @@ -457,10 +465,11 @@ typedef void (*webrtc_data_channel_open_cb)(webrtc_data_channel_h channel, void /** * @brief Called when a message is received from other peer via the data channel. * @since_tizen 6.5 - * @remarks The @a channel is the same object for which the callback was set.\nThe @a channel should not be released.\n + * @remarks The @a channel is the same object for which the callback was set.\n + * The @a channel should not be released.\n * When @a type is #WEBRTC_DATA_CHANNEL_TYPE_STRING, @a message should be casted to char pointer.\n * When @a type is #WEBRTC_DATA_CHANNEL_TYPE_BYTES, @a message should be casted to #webrtc_bytes_data_h.\n - * In this case, webrtc_get_data() can be used to get the data and its size inside of this callback. + * In this case, webrtc_get_data() can be used to get the data and its size inside of this callback.\n * The @a message should not be released. * @param[in] channel WebRTC data channel handle * @param[in] type The data type @@ -481,7 +490,8 @@ typedef void (*webrtc_data_channel_message_cb)(webrtc_data_channel_h channel, we * #WEBRTC_ERROR_STREAM_FAILED\n * #WEBRTC_ERROR_RESOURCE_FAILED * @since_tizen 6.5 - * @remarks The @a channel is the same object for which the callback was set.\nThe @a channel should not be released. + * @remarks The @a channel is the same object for which the callback was set.\n + * The @a channel should not be released. * @param[in] channel WebRTC data channel handle * @param[in] error The error code * @param[in] user_data The user data passed from the callback registration function @@ -495,7 +505,8 @@ typedef void (*webrtc_data_channel_error_cb)(webrtc_data_channel_h channel, webr /** * @brief Called when the data channel has closed down. * @since_tizen 6.5 - * @remarks The @a channel is the same object for which the callback was set.\nThe @a channel should not be released. + * @remarks The @a channel is the same object for which the callback was set.\n + * The @a channel should not be released. * @param[in] channel WebRTC data channel handle * @param[in] user_data The user data passed from the callback registration function * @see webrtc_create_data_channel() @@ -548,7 +559,7 @@ int webrtc_unset_error_cb(webrtc_h webrtc); * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * @remarks You must release @a webrtc using webrtc_destroy(). + * @remarks The @a webrtc should be released using webrtc_destroy(). * @param[out] webrtc WebRTC handle * @return @c 0 on success, * otherwise a negative error value @@ -615,6 +626,7 @@ int webrtc_destroy(webrtc_h webrtc); /** * @brief Sets a callback function to be invoked when the WebRTC state is changed. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in the main thread. * @param[in] webrtc WebRTC handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -626,6 +638,7 @@ int webrtc_destroy(webrtc_h webrtc); * @see webrtc_unset_state_changed_cb() * @see webrtc_state_changed_cb() * @see webrtc_get_state() + * @see webrtc_create_offer() */ int webrtc_set_state_changed_cb(webrtc_h webrtc, webrtc_state_changed_cb callback, void *user_data); @@ -795,7 +808,7 @@ int webrtc_media_source_get_pause(webrtc_h webrtc, unsigned int source_id, webrt * @param[in] webrtc WebRTC handle * @param[in] source_id The media source id * @param[in] media_type The media type - * @param[in] muted Muted or not (@c true = muted, @c false = not muted) + * @param[in] mute Mute or not (@c true = mute, @c false = not mute) * @return @c 0 on success, * otherwise a negative error value * @retval #WEBRTC_ERROR_NONE Successful @@ -813,7 +826,7 @@ int webrtc_media_source_set_mute(webrtc_h webrtc, unsigned int source_id, webrtc * @param[in] webrtc WebRTC handle * @param[in] source_id The media source id * @param[in] media_type The media type - * @param[in] muted The current mute status: (@c true = mute, @c false = not muted) + * @param[out] muted Muted or not (@c true = muted, @c false = not muted) * @return @c 0 on success, * otherwise a negative error value * @retval #WEBRTC_ERROR_NONE Successful @@ -872,7 +885,7 @@ int webrtc_media_source_get_video_resolution(webrtc_h webrtc, unsigned int sourc * @details If @a source_id is not a media source of #WEBRTC_MEDIA_SOURCE_TYPE_MIC, this function will return #WEBRTC_ERROR_INVALID_PARAMETER. * @since_tizen 6.5 * @remarks You can set sound stream information including audio routing.\n - * The following sound stream types can be used for the @a stream_info:\n + * The following sound stream types can be used for the @a stream_info :\n * #SOUND_STREAM_TYPE_MEDIA\n * #SOUND_STREAM_TYPE_VOICE_RECOGNITION\n * #SOUND_STREAM_TYPE_VOIP\n @@ -980,7 +993,7 @@ int webrtc_media_packet_source_push_packet(webrtc_h webrtc, unsigned int source_ * @since_tizen 6.5 * @remarks Call this function within webrtc_track_added_cb(), otherwise #WEBRTC_ERROR_INVALID_OPERATION will be returned.\n * If webrtc_set_encoded_audio_frame_cb() has been called, it will return #WEBRTC_ERROR_INVALID_OPERATION.\n - * The following sound stream types can be used for the @a stream_info:\n + * The following sound stream types can be used for the @a stream_info :\n * #SOUND_STREAM_TYPE_MEDIA\n * #SOUND_STREAM_TYPE_VOIP\n * #SOUND_STREAM_TYPE_MEDIA_EXTERNAL_ONLY @@ -1125,7 +1138,7 @@ int webrtc_set_stun_server(webrtc_h webrtc, const char *stun_server); int webrtc_get_stun_server(webrtc_h webrtc, char **stun_server); /** - * @brief Add a TURN server URL. + * @brief Adds a TURN server URL. * @since_tizen 6.5 * @param[in] webrtc WebRTC handle * @param[in] turn_server The TURN server URL of the form turn(s)://username:password@host:port @@ -1157,6 +1170,7 @@ int webrtc_foreach_turn_server(webrtc_h webrtc, webrtc_turn_server_cb callback, /** * @brief Sets a callback function to be invoked when the WebRTC peer connection state is changed. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in an internal thread of the webrtc. * @param[in] webrtc WebRTC handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -1203,6 +1217,7 @@ int webrtc_get_peer_connection_state(webrtc_h webrtc, webrtc_peer_connection_sta /** * @brief Sets a callback function to be invoked when the WebRTC signaling state is changed. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in an internal thread of the webrtc. * @param[in] webrtc WebRTC handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -1249,6 +1264,7 @@ int webrtc_get_signaling_state(webrtc_h webrtc, webrtc_signaling_state_e *state) /** * @brief Sets a callback function to be invoked when the WebRTC ICE gathering state is changed. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in an internal thread of the webrtc. * @param[in] webrtc WebRTC handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -1295,6 +1311,7 @@ int webrtc_get_ice_gathering_state(webrtc_h webrtc, webrtc_ice_gathering_state_e /** * @brief Sets a callback function to be invoked when the WebRTC ICE connection state is changed. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in an internal thread of the webrtc. * @param[in] webrtc WebRTC handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -1341,6 +1358,7 @@ int webrtc_get_ice_connection_state(webrtc_h webrtc, webrtc_ice_connection_state /** * @brief Sets a negotiation needed callback function to be invoked when a change has occurred which requires session negotiation. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in an internal thread of the webrtc. * @param[in] webrtc WebRTC handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -1374,7 +1392,8 @@ int webrtc_unset_negotiation_needed_cb(webrtc_h webrtc); /** * @brief Sets an ICE candidate callback function to be invoked when the WebRTC needs to send the ICE candidate message to the remote peer. * @since_tizen 6.5 - * @remarks If all the ICE candidates have been gathered, ICE gathering state will be changed to #WEBRTC_ICE_GATHERING_STATE_COMPLETE. + * @remarks If all the ICE candidates have been gathered, ICE gathering state will be changed to #WEBRTC_ICE_GATHERING_STATE_COMPLETE.\n + * The registered callback will be invoked in an internal thread of the webrtc. * @param[in] webrtc WebRTC handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -1431,7 +1450,7 @@ int webrtc_create_offer(webrtc_h webrtc, bundle *options, char **offer); /** * @brief Creates SDP answer to an offer received from a remote peer during the negotiation of a WebRTC connection. * @since_tizen 6.5 - * @remarks The @a answer should be released using free(). + * @remarks The @a answer should be released using free().\n * The @a options currently has no effect. * @param[in] webrtc WebRTC handle * @param[in] options Configuration options for the answer (optional, this can be NULL) @@ -1487,6 +1506,7 @@ int webrtc_set_local_description(webrtc_h webrtc, const char *description); * @retval #WEBRTC_ERROR_INVALID_OPERATION Invalid operation * @retval #WEBRTC_ERROR_INVALID_STATE Invalid state * @pre @a webrtc state must be set to #WEBRTC_STATE_NEGOTIATING. + * @see webrtc_state_changed_cb() * @see webrtc_set_signaling_state_change_cb() * @see webrtc_get_signaling_state() */ @@ -1512,6 +1532,7 @@ int webrtc_add_ice_candidate(webrtc_h webrtc, const char *candidate); /** * @brief Sets a track added callback function to be invoked when a new track has been added to the WebRTC. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in an internal thread of the webrtc. * @param[in] webrtc WebRTC handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -1552,6 +1573,7 @@ int webrtc_unset_track_added_cb(webrtc_h webrtc); /** * @brief Sets a data channel callback function to be invoked when the data channel is created to the connection by the remote peer. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in an internal thread of the webrtc. * @param[in] webrtc WebRTC handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -1585,7 +1607,8 @@ int webrtc_unset_data_channel_cb(webrtc_h webrtc); /** * @brief Creates a new data channel which is linked with the remote peer. * @since_tizen 6.5 - * @remarks The @a options dictionary is similar format as the RTCDataChannelInit members outlined https://www.w3.org/TR/webrtc/#dom-rtcdatachannelinit.\n + * @remarks The @a channel should be released using webrtc_destroy().\n + * The @a options dictionary is similar format as the RTCDataChannelInit members outlined https://www.w3.org/TR/webrtc/#dom-rtcdatachannelinit.\n * The following attributes can be set to @a options by using #bundle API:\n * 'ordered' of type bool : Whether the channel will send data with guaranteed ordering. The default value is true.\n * 'max-packet-lifetime' of type int : The time in milliseconds to attempt transmitting unacknowledged data. -1 for unset. The default value is -1.\n @@ -1623,6 +1646,7 @@ int webrtc_destroy_data_channel(webrtc_data_channel_h channel); /** * @brief Sets a data channel open callback function to be invoked when the data channel's underlying data transport is established. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in an internal thread of the webrtc. * @param[in] channel Data channel handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -1652,6 +1676,7 @@ int webrtc_data_channel_unset_open_cb(webrtc_data_channel_h channel); /** * @brief Sets a data channel message callback function to be invoked when a message is received from the remote peer. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in an internal thread of the webrtc. * @param[in] channel Data channel handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -1681,6 +1706,7 @@ int webrtc_data_channel_unset_message_cb(webrtc_data_channel_h channel); /** * @brief Sets a data channel error callback function to be invoked when an error occurs on the data channel. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in an internal thread of the webrtc. * @param[in] channel Data channel handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function @@ -1710,6 +1736,7 @@ int webrtc_data_channel_unset_error_cb(webrtc_data_channel_h channel); /** * @brief Sets a data channel close callback function to be invoked when the data channel has closed down. * @since_tizen 6.5 + * @remarks The registered callback will be invoked in an internal thread of the webrtc. * @param[in] channel Data channel handle * @param[in] callback Callback function pointer * @param[in] user_data The user data to be passed to the callback function diff --git a/include/webrtc_internal.h b/include/webrtc_internal.h index 906b78f2..59f99b8e 100644 --- a/include/webrtc_internal.h +++ b/include/webrtc_internal.h @@ -17,7 +17,7 @@ #ifndef __TIZEN_MEDIA_WEBRTC_INTERNAL_H__ #define __TIZEN_MEDIA_WEBRTC_INTERNAL_H__ -#include "webrtc.h" +#include #ifdef __cplusplus extern "C" { @@ -85,7 +85,7 @@ typedef void (*webrtc_signaling_message_cb)(webrtc_signaling_message_type_e type /** * @internal - * @brief Set an ecore wayland display to the media track. + * @brief Sets an ecore wayland display to the media track. * @since_tizen 6.5 * @remarks Call this function within webrtc_track_added_cb(), otherwise #WEBRTC_ERROR_INVALID_OPERATION will be returned. * @param[in] webrtc WebRTC handle @@ -132,7 +132,7 @@ int webrtc_add_media_source_internal(webrtc_h webrtc, webrtc_media_source_type_i /** * @internal - * @brief Create a signaling server for private network. + * @brief Creates a signaling server for private network. * @since_tizen 6.5 * @param[in] port The port number * @param[out] server Signaling server handle @@ -149,7 +149,7 @@ int webrtc_signaling_server_create(int port, webrtc_signaling_server_h *server); /** * @internal - * @brief Start the signaling server. + * @brief Starts the signaling server. * @since_tizen 6.5 * @param[in] server Signaling server handle * @return @c 0 on success, @@ -165,7 +165,7 @@ int webrtc_signaling_server_start(webrtc_signaling_server_h server); /** * @internal - * @brief Stop the signaling server. + * @brief Stops the signaling server. * @since_tizen 6.5 * @param[in] server Signaling server handle * @return @c 0 on success, @@ -181,7 +181,7 @@ int webrtc_signaling_server_stop(webrtc_signaling_server_h server); /** * @internal - * @brief Destroy the signaling server. + * @brief Destroys the signaling server. * @since_tizen 6.5 * @param[in] server Signaling server handle * @return @c 0 on success, diff --git a/packaging/capi-media-webrtc.spec b/packaging/capi-media-webrtc.spec index 16562d5f..8ecc855f 100644 --- a/packaging/capi-media-webrtc.spec +++ b/packaging/capi-media-webrtc.spec @@ -1,6 +1,6 @@ Name: capi-media-webrtc Summary: A WebRTC library in Tizen Native API -Version: 0.2.38 +Version: 0.2.39 Release: 0 Group: Multimedia/API License: Apache-2.0