From a0aa795f63c5292c67cad0cf5e04575291e5b0cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Grisez?= Date: Mon, 24 Apr 2017 15:20:03 +0200 Subject: [PATCH] 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. --- include/linphone/call_params.h | 9 +++------ include/linphone/core.h | 18 ++++++------------ 2 files changed, 9 insertions(+), 18 deletions(-) diff --git a/include/linphone/call_params.h b/include/linphone/call_params.h index 918887fc8..173cca313 100644 --- a/include/linphone/call_params.h +++ b/include/linphone/call_params.h @@ -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); diff --git a/include/linphone/core.h b/include/linphone/core.h index 8d90636c0..ac5035880 100644 --- a/include/linphone/core.h +++ b/include/linphone/core.h @@ -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);