From: Sangchul Lee Date: Wed, 23 Jun 2021 08:29:45 +0000 (+0900) Subject: Revise header X-Git-Tag: submit/tizen/20210804.071712~3 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=699e5b4e7458b3e16529cbb671c8b3c124f1cbc3;p=platform%2Fcore%2Fapi%2Fwebrtc.git Revise header Remove '\n' command from related sentence. Add more references. Add more @remarks and @post. Some sentences are rephrased. [Version] 0.2.62 [Issue Type] Doxygen Change-Id: I4b90e3baab26ab21cd047d874e87b1c0ac152274 Signed-off-by: Sangchul Lee --- diff --git a/doc/webrtc_doc.h b/doc/webrtc_doc.h index 438a9152..3d2d28e3 100644 --- a/doc/webrtc_doc.h +++ b/doc/webrtc_doc.h @@ -27,7 +27,7 @@ /** * @ingroup CAPI_MEDIA_FRAMEWORK * @defgroup CAPI_MEDIA_WEBRTC_MODULE WebRTC - * @brief The @ref CAPI_MEDIA_WEBRTC_MODULE API provides functions for real-time communication between peers. + * @brief The @ref CAPI_MEDIA_WEBRTC_MODULE API provides functions for real-time audio/video communication between peers. It supports WebRTC as a native API based on GStreamer multimedia framework. * * @section CAPI_MEDIA_WEBRTC_MODULE_HEADER Required Header * \#include @@ -42,7 +42,7 @@ * - start/stop the state of the handle * - make negotiation with the remote peer * - query the various states of the handle including session negotiation - * - get notified various states changes via callbacks + * - get notified about various changes via callbacks * * @subsection CAPI_MEDIA_WEBRTC_LIFE_CYCLE_STATE_TRANSITIONS State Transitions *
@@ -181,7 +181,7 @@ /** * @ingroup CAPI_MEDIA_WEBRTC_MODULE * @defgroup CAPI_MEDIA_WEBRTC_MEDIA_SOURCE_MODULE Media Source - * @brief The @ref CAPI_MEDIA_WEBRTC_MEDIA_SOURCE_MODULE API provides functions to manage media sources to send to the remote peer. + * @brief The @ref CAPI_MEDIA_WEBRTC_MEDIA_SOURCE_MODULE API provides functions to manage media sources to communicate with the remote peer. * @section CAPI_MEDIA_WEBRTC_MEDIA_SOURCE_MODULE_HEADER Required Header * \#include * diff --git a/include/webrtc.h b/include/webrtc.h index ca025c1b..ddb64e05 100644 --- a/include/webrtc.h +++ b/include/webrtc.h @@ -62,6 +62,7 @@ typedef enum { /** * @brief Enumeration for WebRTC state. + * @details See \ref CAPI_MEDIA_WEBRTC_LIFE_CYCLE_STATE_TRANSITIONS. * @since_tizen 6.5 */ typedef enum { @@ -73,6 +74,7 @@ typedef enum { /** * @brief Enumeration for WebRTC peer connection state. * @since_tizen 6.5 + * @remarks It corresponds with the RTCPeerConnectionState enum described in https://www.w3.org/TR/webrtc/#rtcpeerconnectionstate-enum. */ typedef enum { WEBRTC_PEER_CONNECTION_STATE_NEW, /**< New */ @@ -86,6 +88,7 @@ typedef enum { /** * @brief Enumeration for WebRTC signaling state. * @since_tizen 6.5 + * @remarks It corresponds with the RTCSignalingState enum described in https://www.w3.org/TR/webrtc/#rtcsignalingstate-enum. */ typedef enum { WEBRTC_SIGNALING_STATE_STABLE, /**< Stable */ @@ -99,6 +102,7 @@ typedef enum { /** * @brief Enumeration for WebRTC ICE gathering state. * @since_tizen 6.5 + * @remarks It corresponds with the RTCIceGatheringState enum described in https://www.w3.org/TR/webrtc/#rtcicegatheringstate-enum. */ typedef enum { WEBRTC_ICE_GATHERING_STATE_NEW, /**< New */ @@ -109,6 +113,7 @@ typedef enum { /** * @brief Enumeration for WebRTC ICE connection state. * @since_tizen 6.5 + * @remarks It corresponds with the RTCIceConnectionState enum described in https://www.w3.org/TR/webrtc/#rtciceconnectionstate-enum. */ typedef enum { WEBRTC_ICE_CONNECTION_STATE_NEW, /**< New */ @@ -123,6 +128,7 @@ typedef enum { /** * @brief Enumeration for WebRTC ICE transport policy. * @since_tizen 6.5 + * @remarks It corresponds with the RTCIceTransportPolicy enum described in https://www.w3.org/TR/webrtc/#rtcicetransportpolicy-enum. */ typedef enum { WEBRTC_ICE_TRANSPORT_POLICY_ALL, /**< All */ @@ -192,6 +198,10 @@ typedef enum { /** * @brief WebRTC display handle type. * @since_tizen 6.5 + * @remarks The pointer of this handle can be obtained from EFL UI API.\n + * For example, in case of #WEBRTC_DISPLAY_TYPE_OVERLAY, elm_win_add() can be used to get the window handle.\n + * In case of #WEBRTC_DISPLAY_TYPE_EVAS, evas_object_image_add() can be used to get the renderable image handle.\n + * For more details, please refer to https://docs.tizen.org/application/native/guides/ui/efl/. */ typedef void *webrtc_display_h; @@ -360,6 +370,7 @@ typedef void (*webrtc_negotiation_needed_cb)(webrtc_h webrtc, void *user_data); * @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 + * @post @a candidate must be sent to the remote peer via the signaling channel. * @see webrtc_set_ice_candidate_cb() * @see webrtc_unset_ice_candidate_cb() */ @@ -477,7 +488,7 @@ typedef void (*webrtc_data_channel_open_cb)(webrtc_data_channel_h channel, void * @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 + * When @a type is #WEBRTC_DATA_CHANNEL_TYPE_BYTES, @a message should be casted to #webrtc_bytes_data_h. * 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 @@ -568,7 +579,8 @@ int webrtc_unset_error_cb(webrtc_h webrtc); * @since_tizen 6.5 * @privlevel public * @privilege %http://tizen.org/privilege/internet - * @remarks The @a webrtc should be released using webrtc_destroy(). + * @remarks A signaling channel not addressed in this API should be established to send SDP or ICE candidate messages to each other.\n + * The @a webrtc should be released using webrtc_destroy(). * @param[out] webrtc WebRTC handle * @return @c 0 on success, * otherwise a negative error value @@ -793,7 +805,7 @@ int webrtc_media_source_get_transceiver_direction(webrtc_h webrtc, unsigned int int webrtc_media_source_set_pause(webrtc_h webrtc, unsigned int source_id, webrtc_media_type_e media_type, bool pause); /** - * @brief Gets the pause of the media source. + * @brief Gets the pause state of the media source. * @since_tizen 6.5 * @remarks The default value is @c false. * @param[in] webrtc WebRTC handle @@ -829,7 +841,7 @@ int webrtc_media_source_get_pause(webrtc_h webrtc, unsigned int source_id, webrt int webrtc_media_source_set_mute(webrtc_h webrtc, unsigned int source_id, webrtc_media_type_e media_type, bool mute); /** - * @brief Gets the mute of the media source. + * @brief Gets the mute state of the media source. * @details If @a source_id is a media source of #WEBRTC_MEDIA_SOURCE_TYPE_FILE or #WEBRTC_MEDIA_SOURCE_TYPE_MEDIA_PACKET, this function will return #WEBRTC_ERROR_INVALID_PARAMETER. * @since_tizen 6.5 @@ -849,7 +861,7 @@ int webrtc_media_source_get_mute(webrtc_h webrtc, unsigned int source_id, webrtc /** * @brief Sets a video resolution to the media source. - * @details The following media source types are for the video:\n + * @details The following media source types contain video:\n * #WEBRTC_MEDIA_SOURCE_TYPE_VIDEOTEST\n * #WEBRTC_MEDIA_SOURCE_TYPE_CAMERA\n * #WEBRTC_MEDIA_SOURCE_TYPE_SCREEN @@ -872,7 +884,7 @@ int webrtc_media_source_set_video_resolution(webrtc_h webrtc, unsigned int sourc /** * @brief Gets the video resolution of the media source. - * @details The following media source types are for the video:\n + * @details The following media source types contain video:\n * #WEBRTC_MEDIA_SOURCE_TYPE_VIDEOTEST\n * #WEBRTC_MEDIA_SOURCE_TYPE_CAMERA\n * #WEBRTC_MEDIA_SOURCE_TYPE_SCREEN @@ -1207,6 +1219,7 @@ int webrtc_media_source_set_video_loopback(webrtc_h webrtc, unsigned source_id, /** * @brief Sets a STUN server URL. * @since_tizen 6.5 + * @remarks Regarding STUN, refer to the RFC7064(https://tools.ietf.org/html/rfc7064). * @param[in] webrtc WebRTC handle * @param[in] stun_server The STUN server URL * @return @c 0 on success, @@ -1234,8 +1247,9 @@ int webrtc_get_stun_server(webrtc_h webrtc, char **stun_server); /** * @brief Adds a TURN server URL. * @since_tizen 6.5 + * @remarks Regarding TURN, refer to the RFC7065(https://tools.ietf.org/html/rfc7065). * @param[in] webrtc WebRTC handle - * @param[in] turn_server The TURN server URL of the form turn(s)://username:password@host:port + * @param[in] turn_server The TURN server URL of the form turn(s)://username:password\@host:port * @return @c 0 on success, * otherwise a negative error value * @retval #WEBRTC_ERROR_NONE Successful @@ -1264,7 +1278,6 @@ int webrtc_foreach_turn_server(webrtc_h webrtc, webrtc_turn_server_cb callback, /** * @brief Sets a ICE transport policy that represents which candidates the ICE Agent is allowed to use. * @since_tizen 6.5 - * @remarks The @a policy enum corresponds with the RTCIceTransportPolicy enum described in https://www.w3.org/TR/webrtc/#rtcicetransportpolicy-enum.\n * @param[in] webrtc WebRTC handle * @param[in] policy The ICE transport policy * @return @c 0 on success, @@ -1280,8 +1293,7 @@ int webrtc_set_ice_transport_policy(webrtc_h webrtc, webrtc_ice_transport_policy /** * @brief Gets the ICE transport policy. * @since_tizen 6.5 - * @remarks The @a policy enum corresponds with the RTCIceTransportPolicy enum described in https://www.w3.org/TR/webrtc/#rtcicetransportpolicy-enum.\n - * The default value is #WEBRTC_ICE_TRANSPORT_POLICY_ALL. + * @remarks The default value is #WEBRTC_ICE_TRANSPORT_POLICY_ALL. * @param[in] webrtc WebRTC handle * @param[out] policy The ICE transport policy * @return @c 0 on success, @@ -1566,6 +1578,8 @@ int webrtc_unset_ice_candidate_cb(webrtc_h webrtc); * @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. + * @post @a offer must be set as a local description by calling webrtc_set_local_description() + * @post @a offer must be sent to the remote peer via the signaling channel. * @see webrtc_state_changed_cb() * @see webrtc_negotiation_needed_cb() * @see webrtc_set_local_description() @@ -1589,6 +1603,8 @@ int webrtc_create_offer(webrtc_h webrtc, bundle *options, char **offer); * @pre @a webrtc state must be set to #WEBRTC_STATE_NEGOTIATING. * @pre The remote SDP offer must be set by calling webrtc_set_remote_description(). * @pre The signaling state must be set to #WEBRTC_SIGNALING_STATE_HAVE_REMOTE_OFFER. + * @post @a answer must be set as a local description by calling webrtc_set_local_description() + * @post @a answer must be sent to the remote peer via the signaling channel. * @see webrtc_set_remote_description() * @see webrtc_set_local_description() * @see webrtc_get_signaling_state() diff --git a/packaging/capi-media-webrtc.spec b/packaging/capi-media-webrtc.spec index 1af033e8..ceea00e8 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.61 +Version: 0.2.62 Release: 0 Group: Multimedia/API License: Apache-2.0