From 2650bba8445a0ecb4e03d9afc0480cf0e238aa9b Mon Sep 17 00:00:00 2001 From: =?utf8?q?Sebastian=20Dr=C3=B6ge?= Date: Mon, 17 Oct 2022 14:43:42 +0300 Subject: [PATCH] sdp: Add/fix various annotations Part-of: --- .../gst-plugins-base/gst-libs/gst/sdp/gstmikey.c | 26 +++++++------- .../gst-libs/gst/sdp/gstsdpmessage.c | 42 +++++++++------------- 2 files changed, 30 insertions(+), 38 deletions(-) diff --git a/subprojects/gst-plugins-base/gst-libs/gst/sdp/gstmikey.c b/subprojects/gst-plugins-base/gst-libs/gst/sdp/gstmikey.c index 99ab676..d17c909 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/sdp/gstmikey.c +++ b/subprojects/gst-plugins-base/gst-libs/gst/sdp/gstmikey.c @@ -177,7 +177,7 @@ gst_mikey_payload_kemac_get_n_sub (const GstMIKEYPayload * payload) * Get the sub payload of @payload at @idx. @payload should be of type * %GST_MIKEY_PT_KEMAC. * - * Returns: (transfer none): the #GstMIKEYPayload at @idx. + * Returns: (transfer none) (nullable): the #GstMIKEYPayload at @idx. * * Since: 1.4 */ @@ -458,7 +458,7 @@ gst_mikey_payload_sp_get_n_params (const GstMIKEYPayload * payload) * Get the Security Policy parameter in a %GST_MIKEY_PT_SP @payload * at @idx. * - * Returns: the #GstMIKEYPayloadSPParam at @idx in @payload + * Returns: (transfer none) (nullable): the #GstMIKEYPayloadSPParam at @idx in @payload * * Since: 1.4 */ @@ -763,7 +763,7 @@ mikey_payload_free (GstMIKEYPayload * payload) * * Make a new #GstMIKEYPayload with @type. * - * Returns: (nullable): a new #GstMIKEYPayload or %NULL on failure. + * Returns: (transfer full) (nullable): a new #GstMIKEYPayload or %NULL on failure. * * Since: 1.4 */ @@ -870,7 +870,7 @@ mikey_message_free (GstMIKEYMessage * msg) * * Make a new MIKEY message. * - * Returns: a new #GstMIKEYMessage on success + * Returns: (transfer full): a new #GstMIKEYMessage on success * * Since: 1.4 */ @@ -895,11 +895,11 @@ gst_mikey_message_new (void) * gst_mikey_message_new_from_bytes: * @bytes: a #GBytes * @info: a #GstMIKEYDecryptInfo - * @error: a #GError + * @error: (optional): a #GError * * Make a new #GstMIKEYMessage from @bytes. * - * Returns: a new #GstMIKEYMessage + * Returns: (transfer full): a new #GstMIKEYMessage * * Since: 1.4 */ @@ -974,7 +974,7 @@ gst_mikey_message_get_n_cs (const GstMIKEYMessage * msg) * * Get the policy information of @msg at @idx. * - * Returns: a #GstMIKEYMapSRTP + * Returns: (transfer none) (nullable): a #GstMIKEYMapSRTP * * Since: 1.4 */ @@ -1125,7 +1125,7 @@ gst_mikey_message_get_n_payloads (const GstMIKEYMessage * msg) * * Get the #GstMIKEYPayload at @idx in @msg * - * Returns: (transfer none): the #GstMIKEYPayload at @idx. The payload + * Returns: (transfer none) (nullable): the #GstMIKEYPayload at @idx. The payload * remains valid for as long as it is part of @msg. * * Since: 1.4 @@ -1149,7 +1149,7 @@ gst_mikey_message_get_payload (const GstMIKEYMessage * msg, guint idx) * * Find the @nth occurrence of the payload with @type in @msg. * - * Returns: the @nth #GstMIKEYPayload of @type. + * Returns: (transfer none) (nullable): the @nth #GstMIKEYPayload of @type. * * Since: 1.4 */ @@ -1667,7 +1667,7 @@ payloads_to_bytes (GArray * payloads, GByteArray * arr, guint8 ** ptr, * * Convert @msg to a #GBytes. * - * Returns: a new #GBytes for @msg. + * Returns: (transfer full): a new #GBytes for @msg. * * Since: 1.4 */ @@ -2048,12 +2048,12 @@ invalid_data: * @data: (array length=size) (element-type guint8): bytes to read * @size: length of @data * @info: #GstMIKEYDecryptInfo - * @error: a #GError + * @error: (optional): a #GError * * Parse @size bytes from @data into a #GstMIKEYMessage. @info contains the * parameters to decrypt and verify the data. * - * Returns: a #GstMIKEYMessage on success or %NULL when parsing failed and + * Returns: (transfer full): a #GstMIKEYMessage on success or %NULL when parsing failed and * @error will be set. * * Since: 1.4 @@ -2238,7 +2238,7 @@ auth_key_length_from_auth_cipher_name (const gchar * auth, const gchar * cipher, * - Key Data Transport Payload * - Key Data Sub-Payload * - * Returns: (transfer full): a #GstMIKEYMessage, + * Returns: (transfer full) (nullable): a #GstMIKEYMessage, * or %NULL if there is no srtp information in the caps. * * Since: 1.8 diff --git a/subprojects/gst-plugins-base/gst-libs/gst/sdp/gstsdpmessage.c b/subprojects/gst-plugins-base/gst-libs/gst/sdp/gstsdpmessage.c index 17bb1c3..a42757b 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/sdp/gstsdpmessage.c +++ b/subprojects/gst-plugins-base/gst-libs/gst/sdp/gstsdpmessage.c @@ -263,7 +263,7 @@ gst_sdp_message_new_from_text (const gchar * text, GstSDPMessage ** msg) /** * gst_sdp_message_init: - * @msg: a #GstSDPMessage + * @msg: (out caller-allocates): a #GstSDPMessage * * Initialize @msg so that its contents are as if it was freshly allocated * with gst_sdp_message_new(). This function is mostly used to initialize a message @@ -340,16 +340,12 @@ gst_sdp_message_uninit (GstSDPMessage * msg) GstSDPResult gst_sdp_message_copy (const GstSDPMessage * msg, GstSDPMessage ** copy) { - GstSDPResult ret; GstSDPMessage *cp; guint i, len; - if (msg == NULL) - return GST_SDP_EINVAL; + g_return_val_if_fail (msg != NULL, GST_SDP_EINVAL); - ret = gst_sdp_message_new (copy); - if (ret != GST_SDP_OK) - return ret; + gst_sdp_message_new (copy); cp = *copy; @@ -489,7 +485,7 @@ gst_sdp_address_is_multicast (const gchar * nettype, const gchar * addrtype, * * Convert the contents of @msg to a text string. * - * Returns: A dynamically allocated string representing the SDP description. + * Returns: (transfer full): A dynamically allocated string representing the SDP description. */ gchar * gst_sdp_message_as_text (const GstSDPMessage * msg) @@ -624,7 +620,7 @@ hex_to_int (gchar c) /** * gst_sdp_message_parse_uri: * @uri: the start of the uri - * @msg: the result #GstSDPMessage + * @msg: (out caller-allocates): the result #GstSDPMessage * * Parse the null-terminated @uri and store the result in @msg. * @@ -736,7 +732,7 @@ static const gchar hex[16] = "0123456789ABCDEF"; * * Where each value is url encoded. * - * Returns: a uri for @msg. + * Returns: (transfer full): a uri for @msg. */ gchar * gst_sdp_message_as_uri (const gchar * scheme, const GstSDPMessage * msg) @@ -1631,7 +1627,7 @@ DEFINE_ARRAY_GETTER (attribute, attributes, GstSDPAttribute); * * Get the @nth attribute with key @key in @msg. * - * Returns: the attribute value of the @nth attribute with @key. + * Returns: (nullable): the attribute value of the @nth attribute with @key. */ const gchar * gst_sdp_message_get_attribute_val_n (const GstSDPMessage * msg, @@ -1663,7 +1659,7 @@ gst_sdp_message_get_attribute_val_n (const GstSDPMessage * msg, * * Get the first attribute with key @key in @msg. * - * Returns: the attribute value of the first attribute with @key. + * Returns: (nullable): the attribute value of the first attribute with @key. */ const gchar * gst_sdp_message_get_attribute_val (const GstSDPMessage * msg, const gchar * key) @@ -1820,7 +1816,7 @@ gst_sdp_media_new (GstSDPMedia ** media) /** * gst_sdp_media_init: - * @media: a #GstSDPMedia + * @media: (out caller-allocates): a #GstSDPMedia * * Initialize @media so that its contents are as if it was freshly allocated * with gst_sdp_media_new(). This function is mostly used to initialize a media @@ -1910,16 +1906,12 @@ gst_sdp_media_free (GstSDPMedia * media) GstSDPResult gst_sdp_media_copy (const GstSDPMedia * media, GstSDPMedia ** copy) { - GstSDPResult ret; GstSDPMedia *cp; guint i, len; - if (media == NULL) - return GST_SDP_EINVAL; + g_return_val_if_fail (media != NULL, GST_SDP_EINVAL); - ret = gst_sdp_media_new (copy); - if (ret != GST_SDP_OK) - return ret; + gst_sdp_media_new (copy); cp = *copy; @@ -1966,7 +1958,7 @@ gst_sdp_media_copy (const GstSDPMedia * media, GstSDPMedia ** copy) * * Convert the contents of @media to a text string. * - * Returns: A dynamically allocated string representing the media. + * Returns: (transfer full): A dynamically allocated string representing the media. */ gchar * gst_sdp_media_as_text (const GstSDPMedia * media) @@ -2803,7 +2795,7 @@ gst_sdp_media_get_attribute (const GstSDPMedia * media, guint idx) * * Get the @nth attribute value for @key in @media. * - * Returns: the @nth attribute value. + * Returns: (nullable): the @nth attribute value. */ const gchar * gst_sdp_media_get_attribute_val_n (const GstSDPMedia * media, const gchar * key, @@ -2835,7 +2827,7 @@ gst_sdp_media_get_attribute_val_n (const GstSDPMedia * media, const gchar * key, * * Get the first attribute value for @key in @media. * - * Returns: the first attribute value for @key. + * Returns: (nullable): the first attribute value for @key. */ const gchar * gst_sdp_media_get_attribute_val (const GstSDPMedia * media, const gchar * key) @@ -3129,7 +3121,7 @@ gst_sdp_parse_line (SDPContext * c, gchar type, gchar * buffer) * gst_sdp_message_parse_buffer: * @data: (array length=size): the start of the buffer * @size: the size of the buffer - * @msg: the result #GstSDPMessage + * @msg: (out caller-allocates): the result #GstSDPMessage * * Parse the contents of @size bytes pointed to by @data and store the result in * @msg. @@ -3585,7 +3577,7 @@ gst_sdp_media_caps_adjust_h264 (GstCaps * caps) * * Note that the extmap, ssrc and rid attributes are set only by gst_sdp_media_attributes_to_caps(). * - * Returns: a #GstCaps, or %NULL if an error happened + * Returns: (transfer full) (nullable): a #GstCaps, or %NULL if an error happened * * Since: 1.8 */ @@ -3774,7 +3766,7 @@ no_rate: /** * gst_sdp_media_set_media_from_caps: * @caps: a #GstCaps - * @media: a #GstSDPMedia + * @media: (out caller-allocates): a #GstSDPMedia * * Mapping of caps to SDP fields: * -- 2.7.4