Commit a0aa795f authored by François Grisez's avatar François Grisez
Browse files

Improve clarity of the documentation about LinphonePayloadType

As floating objects are automatically freed by the garbage collector
of bellesip, there is not need to unref PayloadType objects that have
been allocated on the fly by getters in LinphoneCore and LinphoneCallParams.

Then, the lines saying that the gotten LinphonePayloadType objects must be
freed after usage have been removed and there is no more reference to
the floating ref mechanisme as it is totally transparent for API users.
parent 0a2ea96a
......@@ -195,8 +195,7 @@ LINPHONE_PUBLIC const char *linphone_call_params_get_session_name(const Linphone
* Get the audio payload type that has been selected by a call.
* @param[in] cp The call.
* @return The selected payload type. NULL is returned if no audio payload type has been seleced
* by the call. If a payload type is returned, it must be released with linphone_payload_type_unref() after use.
* @warning The returned object is allocated as a floating reference i.e. the reference counter is initialized to 0.
* by the call.
**/
LINPHONE_PUBLIC LinphonePayloadType *linphone_call_params_get_used_audio_payload_type(const LinphoneCallParams *cp);
......@@ -204,8 +203,7 @@ LINPHONE_PUBLIC LinphonePayloadType *linphone_call_params_get_used_audio_payload
* Get the video payload type that has been selected by a call.
* @param[in] cp The call.
* @return The selected payload type. NULL is returned if no video payload type has been seleced
* by the call. If a payload type is returned, it must be released with linphone_payload_type_unref() after use.
* @warning The returned object is allocated as a floating reference i.e. the reference counter is initialized to 0.
* by the call.
**/
LINPHONE_PUBLIC LinphonePayloadType *linphone_call_params_get_used_video_payload_type(const LinphoneCallParams *cp);
......@@ -213,8 +211,7 @@ LINPHONE_PUBLIC LinphonePayloadType *linphone_call_params_get_used_video_payload
* Get the text payload type that has been selected by a call.
* @param[in] cp The call.
* @return The selected payload type. NULL is returned if no text payload type has been seleced
* by the call. If a payload type is returned, it must be released with linphone_payload_type_unref() after use.
* @warning The returned object is allocated as a floating reference i.e. the reference counter is initialized to 0.
* by the call.
**/
LINPHONE_PUBLIC LinphonePayloadType *linphone_call_params_get_used_text_payload_type(const LinphoneCallParams *cp);
......
......@@ -1580,10 +1580,8 @@ LINPHONE_PUBLIC void linphone_core_set_dns_servers(LinphoneCore *lc, const bctbx
/**
* Return the list of the available audio payload types.
* @param[in] lc The core.
* @return \bctbx_list{LinphonePayloadType} A freshly allocated list of the available payload types. It must be released
* with bctbx_list_free_with_data() calling linphone_payload_type_unref() on each element.
* @warning Each element of the returned list is freshly allocated as floating reference. That means their reference counter
* is initialized to 0.
* @return \bctbx_list{LinphonePayloadType} A freshly allocated list of the available payload types. The list
* must be destroyed with bctbx_list_free() after usage. The elements of the list haven't to be unref.
* @ingroup media_parameters
*/
LINPHONE_PUBLIC bctbx_list_t *linphone_core_get_audio_payload_types(LinphoneCore *lc);
......@@ -1628,10 +1626,8 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_set_audio_codec
/**
* Return the list of the available video payload types.
* @param[in] lc The core.
* @return \bctbx_list{LinphonePayloadType} A freshly allocated list of the available payload types. It must be released
* with bctbx_list_free_with_data() calling linphone_payload_type_unref() on each element.
* @warning Each element of the returned list is freshly allocated as floating reference. That means their reference counter
* is initialized to 0.
* @return \bctbx_list{LinphonePayloadType} A freshly allocated list of the available payload types. The list
* must be destroyed with bctbx_list_free() after usage. The elements of the list haven't to be unref.
* @ingroup media_parameters
*/
LINPHONE_PUBLIC bctbx_list_t *linphone_core_get_video_payload_types(LinphoneCore *lc);
......@@ -1677,10 +1673,8 @@ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneStatus linphone_core_set_video_codec
/**
* Return the list of the available text payload types.
* @param[in] lc The core.
* @return \bctbx_list{LinphonePayloadType} A freshly allocated list of the available payload types. It must be released
* with bctbx_list_free_with_data() calling linphone_payload_type_unref() on each element.
* @warning Each element of the returned list is freshly allocated as floating reference. That means their reference counter
* is initialized to 0.
* @return \bctbx_list{LinphonePayloadType} A freshly allocated list of the available payload types. The list
* must be destroyed with bctbx_list_free() after usage. The elements of the list haven't to be unref.
* @ingroup media_parameters
*/
LINPHONE_PUBLIC bctbx_list_t *linphone_core_get_text_payload_types(LinphoneCore *lc);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment