mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-27 10:40:34 +00:00
Code Issues 1 Projects Releases Wiki Activity

rtsp: Add/fix various annotations

Browse source 
Also initialize out parameters so that they don't have an undefined
value in case of errors.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/3194>
This commit is contained in:
Sebastian Dröge 2022-10-14 23:52:40 +03:00 committed by GStreamer Marge Bot
parent 2ede719b4b
commit 84ab8c9e12
5 changed files with 75 additions and 59 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
subprojects/gst-plugins-base/gst-libs/gst/rtsp/gstrtspconnection.c
View file

@ -453,7 +453,7 @@ collect_addresses (GSocket * socket, gchar ** ip, guint16 * port,
* @ip: the IP address of the other end
* @port: the port used by the other end
* @initial_buffer: data already read from @fd
* @conn: (out) (transfer full): storage for a #GstRTSPConnection
* @conn: (out) (transfer full) (nullable): storage for a #GstRTSPConnection
*
* Create a new #GstRTSPConnection for handling communication on the existing
* socket @socket. The @initial_buffer contains zero terminated data already
@ -478,6 +478,8 @@ gst_rtsp_connection_create_from_socket (GSocket * socket, const gchar * ip,
g_return_val_if_fail (ip != NULL, GST_RTSP_EINVAL);
g_return_val_if_fail (conn != NULL, GST_RTSP_EINVAL);
*conn = NULL;
if (!collect_addresses (socket, &local_ip, NULL, FALSE, &err))
goto getnameinfo_failed;
@ -531,7 +533,7 @@ newconn_failed:
/**
* gst_rtsp_connection_accept:
* @socket: a socket
* @conn: (out) (transfer full): storage for a #GstRTSPConnection
* @conn: (out) (transfer full) (nullable): storage for a #GstRTSPConnection
* @cancellable: a #GCancellable to cancel the operation
*
* Accept a new connection on @socket and create a new #GstRTSPConnection for
@ -552,6 +554,8 @@ gst_rtsp_connection_accept (GSocket * socket, GstRTSPConnection ** conn,
g_return_val_if_fail (G_IS_SOCKET (socket), GST_RTSP_EINVAL);
g_return_val_if_fail (conn != NULL, GST_RTSP_EINVAL);
*conn = NULL;
client_sock = g_socket_accept (socket, cancellable, &err);
if (!client_sock)
goto accept_failed;
@ -593,7 +597,7 @@ getnameinfo_failed:
/**
* gst_rtsp_connection_get_tls:
* @conn: a #GstRTSPConnection
* @error: #GError for error reporting, or NULL to ignore.
* @error: (optional): #GError for error reporting, or NULL to ignore.
*
* Get the TLS connection of @conn.
*
@ -707,7 +711,7 @@ gst_rtsp_connection_get_tls_validation_flags (GstRTSPConnection * conn)
/**
* gst_rtsp_connection_set_tls_database:
* @conn: a #GstRTSPConnection
* @database: a #GTlsDatabase
* @database: (nullable): a #GTlsDatabase
*
* Sets the anchor certificate authorities database. This certificate
* database will be used to verify the server's certificate in case it
@ -741,7 +745,7 @@ gst_rtsp_connection_set_tls_database (GstRTSPConnection * conn,
* after a server certificate can't be verified with the default
* certificate database.
*
* Returns: (transfer full): the anchor certificate authorities database, or NULL if no
* Returns: (transfer full) (nullable): the anchor certificate authorities database, or NULL if no
* database has been previously set. Use g_object_unref() to release the
* certificate database.
*
@ -763,7 +767,7 @@ gst_rtsp_connection_get_tls_database (GstRTSPConnection * conn)
/**
* gst_rtsp_connection_set_tls_interaction:
* @conn: a #GstRTSPConnection
* @interaction: a #GTlsInteraction
* @interaction: (nullable): a #GTlsInteraction
*
* Sets a #GTlsInteraction object to be used when the connection or certificate
* database need to interact with the user. This will be used to prompt the
@ -797,7 +801,7 @@ gst_rtsp_connection_set_tls_interaction (GstRTSPConnection * conn,
* database need to interact with the user. This will be used to prompt the
* user for passwords where necessary.
*
* Returns: (transfer full): a reference on the #GTlsInteraction. Use
* Returns: (transfer full) (nullable): a reference on the #GTlsInteraction. Use
* g_object_unref() to release.
*
* Since: 1.6
@ -1743,7 +1747,7 @@ clear_write_socket_timeout (GstRTSPConnection * conn)
/**
* gst_rtsp_connection_write_usec:
* @conn: a #GstRTSPConnection
* @data: the data to write
* @data: (array length=size): the data to write
* @size: the size of @data
* @timeout: a timeout value or 0
*
@ -2722,7 +2726,7 @@ invalid_format:
/**
* gst_rtsp_connection_read_usec:
* @conn: a #GstRTSPConnection
* @data: the data to read
* @data: (array length=size): the data to read
* @size: the size of @data
* @timeout: a timeout value in microseconds
*
@ -2803,7 +2807,7 @@ no_message:
/**
* gst_rtsp_connection_receive_usec:
* @conn: a #GstRTSPConnection
* @message: the message to read
* @message: (out caller-allocates): the message to read
* @timeout: a timeout value or 0
*
* Attempt to read into @message from the connected @conn, blocking up to
@ -2991,7 +2995,7 @@ gst_rtsp_connection_free (GstRTSPConnection * conn)
* gst_rtsp_connection_poll_usec:
* @conn: a #GstRTSPConnection
* @events: a bitmask of #GstRTSPEvent flags to check
* @revents: location for result flags
* @revents: (out caller-allocates): location for result flags
* @timeout: a timeout in microseconds
*
* Wait up to the specified @timeout for the connection to become available for
@ -3484,7 +3488,7 @@ gst_rtsp_connection_set_ip (GstRTSPConnection * conn, const gchar * ip)
*
* Get the file descriptor for reading.
*
* Returns: (transfer none): the file descriptor used for reading or %NULL on
* Returns: (transfer none) (nullable): the file descriptor used for reading or %NULL on
* error. The file descriptor remains valid until the connection is closed.
*/
GSocket *
@ -3502,7 +3506,7 @@ gst_rtsp_connection_get_read_socket (const GstRTSPConnection * conn)
*
* Get the file descriptor for writing.
*
* Returns: (transfer none): the file descriptor used for writing or NULL on
* Returns: (transfer none) (nullable): the file descriptor used for writing or NULL on
* error. The file descriptor remains valid until the connection is closed.
*/
GSocket *
@ -3571,7 +3575,7 @@ gst_rtsp_connection_is_tunneled (const GstRTSPConnection * conn)
*
* Get the tunnel session id the connection.
*
* Returns: returns a non-empty string if @conn is being tunneled over HTTP.
* Returns: (nullable): returns a non-empty string if @conn is being tunneled over HTTP.
*/
const gchar *
gst_rtsp_connection_get_tunnelid (const GstRTSPConnection * conn)
@ -3626,7 +3630,7 @@ gst_rtsp_connection_get_ignore_x_server_reply (const GstRTSPConnection * conn)
/**
* gst_rtsp_connection_do_tunnel:
* @conn: a #GstRTSPConnection
* @conn2: a #GstRTSPConnection or %NULL
* @conn2: (nullable): a #GstRTSPConnection or %NULL
*
* If @conn received the first tunnel connection and @conn2 received
* the second tunnel connection, link the two connections together so that
@ -4371,7 +4375,7 @@ static GSourceFuncs gst_rtsp_source_funcs = {
*
* @conn must exist for the entire lifetime of the watch.
*
* Returns: a #GstRTSPWatch that can be used for asynchronous RTSP
* Returns: (transfer full): a #GstRTSPWatch that can be used for asynchronous RTSP
* communication. Free with gst_rtsp_watch_unref () after usage.
*/
GstRTSPWatch *
@ -4466,7 +4470,7 @@ gst_rtsp_watch_reset (GstRTSPWatch * watch)
/**
* gst_rtsp_watch_attach:
* @watch: a #GstRTSPWatch
* @context: a GMainContext (if NULL, the default context will be used)
* @context: (nullable): a GMainContext (if NULL, the default context will be used)
*
* Adds a #GstRTSPWatch to a context so that it will be executed within that context.
*
@ -4798,7 +4802,7 @@ too_much_backlog:
* @watch: a #GstRTSPWatch
* @data: (array length=size) (transfer full): the data to queue
* @size: the size of @data
* @id: (out) (allow-none): location for a message ID or %NULL
* @id: (out) (optional): location for a message ID or %NULL
*
* Write @data using the connection of the @watch. If it cannot be sent
* immediately, it will be queued for transmission in @watch. The contents of
@ -4835,7 +4839,7 @@ gst_rtsp_watch_write_data (GstRTSPWatch * watch, const guint8 * data,
* gst_rtsp_watch_send_message:
* @watch: a #GstRTSPWatch
* @message: a #GstRTSPMessage
* @id: (out) (allow-none): location for a message ID or %NULL
* @id: (out) (optional): location for a message ID or %NULL
*
* Send a @message using the connection of the @watch. If it cannot be sent
* immediately, it will be queued for transmission in @watch. The contents of
@ -4861,7 +4865,7 @@ gst_rtsp_watch_send_message (GstRTSPWatch * watch, GstRTSPMessage * message,
* @watch: a #GstRTSPWatch
* @messages: (array length=n_messages): the messages to send
* @n_messages: the number of messages to send
* @id: (out) (allow-none): location for a message ID or %NULL
* @id: (out) (optional): location for a message ID or %NULL
*
* Sends @messages using the connection of the @watch. If they cannot be sent
* immediately, they will be queued for transmission in @watch. The contents of
@ -5056,7 +5060,7 @@ gst_rtsp_connection_connect_with_response (GstRTSPConnection * conn,
/**
* gst_rtsp_connection_read:
* @conn: a #GstRTSPConnection
* @data: the data to read
* @data: (array length=size): the data to read
* @size: the size of @data
* @timeout: a timeout value or %NULL
*
@ -5080,7 +5084,7 @@ gst_rtsp_connection_read (GstRTSPConnection * conn, guint8 * data, guint size,
/**
* gst_rtsp_connection_write:
* @conn: a #GstRTSPConnection
* @data: the data to write
* @data: (array length=size): the data to write
* @size: the size of @data
* @timeout: a timeout value or %NULL
*
@ -5154,7 +5158,7 @@ gst_rtsp_connection_send_messages (GstRTSPConnection * conn,
/**
* gst_rtsp_connection_receive:
* @conn: a #GstRTSPConnection
* @message: the message to read
* @message: (out caller-allocates): the message to read
* @timeout: a timeout value or %NULL
*
* Attempt to read into @message from the connected @conn, blocking up to
@ -5178,7 +5182,7 @@ gst_rtsp_connection_receive (GstRTSPConnection * conn, GstRTSPMessage * message,
* gst_rtsp_connection_poll:
* @conn: a #GstRTSPConnection
* @events: a bitmask of #GstRTSPEvent flags to check
* @revents: location for result flags
* @revents: (out): location for result flags
* @timeout: a timeout
*
* Wait up to the specified @timeout for the connection to become available for

12
subprojects/gst-plugins-base/gst-libs/gst/rtsp/gstrtspdefs.c
View file

@ -313,7 +313,7 @@ gst_rtsp_strresult (GstRTSPResult result)
*
* Convert @method to a string.
*
* Returns: a string representation of @method.
* Returns: (nullable): a string representation of @method.
*/
const gchar *
gst_rtsp_method_as_text (GstRTSPMethod method)
@ -364,7 +364,7 @@ gst_rtsp_version_as_text (GstRTSPVersion version)
*
* Convert @field to a string.
*
* Returns: a string representation of @field.
* Returns: (nullable): a string representation of @field.
*/
const gchar *
gst_rtsp_header_as_text (GstRTSPHeaderField field)
@ -602,7 +602,7 @@ done:
/**
* gst_rtsp_generate_digest_auth_response:
* @algorithm: (allow-none): Hash algorithm to use, or %NULL for MD5
* @algorithm: (nullable): Hash algorithm to use, or %NULL for MD5
* @method: Request method, e.g. PLAY
* @realm: Realm
* @username: Username
@ -615,7 +615,7 @@ done:
*
* Currently only supported algorithm "md5".
*
* Returns: Authentication response or %NULL if unsupported
* Returns: (nullable): Authentication response or %NULL if unsupported
*
* Since: 1.12
*/
@ -643,7 +643,7 @@ gst_rtsp_generate_digest_auth_response (const gchar * algorithm,
/**
* gst_rtsp_generate_digest_auth_response_from_md5:
* @algorithm: (allow-none): Hash algorithm to use, or %NULL for MD5
* @algorithm: (nullable): Hash algorithm to use, or %NULL for MD5
* @method: Request method, e.g. PLAY
* @md5: The md5 sum of username:realm:password
* @uri: Original request URI
@ -657,7 +657,7 @@ gst_rtsp_generate_digest_auth_response (const gchar * algorithm,
*
* Currently only supported algorithm "md5".
*
* Returns: Authentication response or %NULL if unsupported
* Returns: (nullable): Authentication response or %NULL if unsupported
*
* Since: 1.16
*/

48
subprojects/gst-plugins-base/gst-libs/gst/rtsp/gstrtspmessage.c
View file

@ -136,7 +136,7 @@ gst_rtsp_message_new (GstRTSPMessage ** msg)
/**
* gst_rtsp_message_init:
* @msg: a #GstRTSPMessage
* @msg: (out caller-allocates): a #GstRTSPMessage
*
* Initialize @msg. This function is mostly used when @msg is allocated on the
* stack. The reverse operation of this is gst_rtsp_message_unset().
@ -201,7 +201,7 @@ gst_rtsp_message_new_request (GstRTSPMessage ** msg, GstRTSPMethod method,
/**
* gst_rtsp_message_init_request:
* @msg: a #GstRTSPMessage
* @msg: (out caller-allocates): a #GstRTSPMessage
* @method: the request method to use
* @uri: (transfer none): the uri of the request
*
@ -231,9 +231,9 @@ gst_rtsp_message_init_request (GstRTSPMessage * msg, GstRTSPMethod method,
/**
* gst_rtsp_message_parse_request:
* @msg: a #GstRTSPMessage
* @method: (out) (allow-none): location to hold the method
* @uri: (out) (allow-none) (transfer none): location to hold the uri
* @version: (out) (allow-none) (transfer none): location to hold the version
* @method: (out) (optional): location to hold the method
* @uri: (out) (optional) (transfer none): location to hold the uri
* @version: (out) (optional) (transfer none): location to hold the version
*
* Parse the request message @msg and store the values @method, @uri and
* @version. The result locations can be %NULL if one is not interested in its
@ -265,8 +265,8 @@ gst_rtsp_message_parse_request (GstRTSPMessage * msg,
* gst_rtsp_message_new_response:
* @msg: (out) (transfer full): a location for the new #GstRTSPMessage
* @code: the status code
* @reason: (transfer none) (allow-none): the status reason or %NULL
* @request: (transfer none) (allow-none): the request that triggered the response or %NULL
* @reason: (transfer none) (optional): the status reason or %NULL
* @request: (transfer none) (optional): the request that triggered the response or %NULL
*
* Create a new response #GstRTSPMessage with @code and @reason and store the
* result message in @msg. Free with gst_rtsp_message_free().
@ -295,10 +295,10 @@ gst_rtsp_message_new_response (GstRTSPMessage ** msg, GstRTSPStatusCode code,
/**
* gst_rtsp_message_init_response:
* @msg: a #GstRTSPMessage
* @msg: (out caller-allocates): a #GstRTSPMessage
* @code: the status code
* @reason: (transfer none) (allow-none): the status reason or %NULL
* @request: (transfer none) (allow-none): the request that triggered the response or %NULL
* @reason: (transfer none) (optional): the status reason or %NULL
* @request: (transfer none) (optional): the request that triggered the response or %NULL
*
* Initialize @msg with @code and @reason.
*
@ -365,9 +365,9 @@ gst_rtsp_message_init_response (GstRTSPMessage * msg, GstRTSPStatusCode code,
/**
* gst_rtsp_message_parse_response:
* @msg: a #GstRTSPMessage
* @code: (out) (allow-none): location to hold the status code
* @reason: (out) (allow-none) (transfer none): location to hold the status reason
* @version: (out) (allow-none) (transfer none): location to hold the version
* @code: (out) (optional): location to hold the status code
* @reason: (out) (optional) (transfer none): location to hold the status reason
* @version: (out) (optional) (transfer none): location to hold the version
*
* Parse the response message @msg and store the values @code, @reason and
* @version. The result locations can be %NULL if one is not interested in its
@ -421,7 +421,7 @@ gst_rtsp_message_new_data (GstRTSPMessage ** msg, guint8 channel)
/**
* gst_rtsp_message_init_data:
* @msg: a #GstRTSPMessage
* @msg: (out caller-allocates): a #GstRTSPMessage
* @channel: a channel
*
* Initialize a new data #GstRTSPMessage for @channel.
@ -444,7 +444,7 @@ gst_rtsp_message_init_data (GstRTSPMessage * msg, guint8 channel)
/**
* gst_rtsp_message_parse_data:
* @msg: a #GstRTSPMessage
* @channel: (out): location to hold the channel
* @channel: (out) (optional): location to hold the channel
*
* Parse the data message @msg and store the channel in @channel.
*
@ -539,7 +539,7 @@ gst_rtsp_message_free (GstRTSPMessage * msg)
/**
* gst_rtsp_message_copy:
* @msg: a #GstRTSPMessage
* @copy: (out) (transfer full): pointer to new #GstRTSPMessage
* @copy: (out) (nullable) (transfer full): pointer to new #GstRTSPMessage
*
* Allocate a new copy of @msg and store the result in @copy. The value in
* @copy should be release with gst_rtsp_message_free function.
@ -554,6 +554,10 @@ gst_rtsp_message_copy (const GstRTSPMessage * msg, GstRTSPMessage ** copy)
GstRTSPResult ret;
GstRTSPMessage *cp;
g_return_val_if_fail (copy != NULL, GST_RTSP_EINVAL);
*copy = NULL;
if (msg == NULL)
return GST_RTSP_EINVAL;
@ -684,7 +688,7 @@ gst_rtsp_message_remove_header (GstRTSPMessage * msg, GstRTSPHeaderField field,
* gst_rtsp_message_get_header:
* @msg: a #GstRTSPMessage
* @field: a #GstRTSPHeaderField
* @value: (out) (transfer none): pointer to hold the result
* @value: (out) (transfer none) (optional) (nullable): pointer to hold the result
* @indx: the index of the header
*
* Get the @indx header value with key @field from @msg. The result in @value
@ -702,6 +706,9 @@ gst_rtsp_message_get_header (const GstRTSPMessage * msg,
g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
if (value)
*value = NULL;
/* no header initialized, there are no headers */
if (msg->hdr_fields == NULL)
return GST_RTSP_ENOTIMPL;
@ -858,7 +865,7 @@ gst_rtsp_message_remove_header_by_name (GstRTSPMessage * msg,
* gst_rtsp_message_get_header_by_name:
* @msg: a #GstRTSPMessage
* @header: a #GstRTSPHeaderField
* @value: (out) (transfer none): pointer to hold the result
* @value: (out) (transfer none) (optional) (nullable): pointer to hold the result
* @index: the index of the header
*
* Get the @index header value with key @header from @msg. The result in @value
@ -879,6 +886,9 @@ gst_rtsp_message_get_header_by_name (GstRTSPMessage * msg,
g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
g_return_val_if_fail (header != NULL, GST_RTSP_EINVAL);
if (value)
*value = NULL;
pos = gst_rtsp_message_find_header_by_name (msg, header, index);
if (pos < 0)
@ -1445,7 +1455,7 @@ parse_auth_credentials (GPtrArray * auth_credentials, const gchar * header,
*
* Parses the credentials given in a WWW-Authenticate or Authorization header.
*
* Returns: (array zero-terminated=1):
* Returns: (transfer full) (array zero-terminated=1):
* %NULL-terminated array of GstRTSPAuthCredential or %NULL.
*
* Since: 1.12

12
subprojects/gst-plugins-base/gst-libs/gst/rtsp/gstrtsptransport.c
View file

@ -145,7 +145,7 @@ G_STMT_START { \
/**
* gst_rtsp_transport_new:
* @transport: location to hold the new #GstRTSPTransport
* @transport: (out) (transfer full): location to hold the new #GstRTSPTransport
*
* Allocate a new initialized #GstRTSPTransport. Use gst_rtsp_transport_free()
* after usage.
@ -168,7 +168,7 @@ gst_rtsp_transport_new (GstRTSPTransport ** transport)
/**
* gst_rtsp_transport_init:
* @transport: a #GstRTSPTransport
* @transport: (out caller-allocates): a #GstRTSPTransport
*
* Initialize @transport so that it can be used.
*
@ -205,7 +205,7 @@ gst_rtsp_transport_init (GstRTSPTransport * transport)
/**
* gst_rtsp_transport_get_mime:
* @trans: a #GstRTSPTransMode
* @mime: location to hold the result
* @mime: (out) (transfer none): location to hold the result
*
* Get the mime type of the transport mode @trans. This mime type is typically
* used to generate #GstCaps events.
@ -433,7 +433,7 @@ rtsp_transport_ltrans_as_text (const GstRTSPTransport * transport)
/**
* gst_rtsp_transport_parse:
* @str: a transport string
* @transport: a #GstRTSPTransport
* @transport: (out caller-allocates): a #GstRTSPTransport
*
* Parse the RTSP transport string @str into @transport.
*
@ -592,8 +592,8 @@ invalid_transport:
* Convert @transport into a string that can be used to signal the transport in
* an RTSP SETUP response.
*
* Returns: a string describing the RTSP transport or %NULL when the transport
* is invalid.
* Returns: (transfer full) (nullable): a string describing the RTSP transport
* or %NULL when the transport is invalid.
*/
gchar *
gst_rtsp_transport_as_text (GstRTSPTransport * transport)

10
subprojects/gst-plugins-base/gst-libs/gst/rtsp/gstrtspurl.c
View file

@ -90,7 +90,7 @@ static const struct
/**
* gst_rtsp_url_parse:
* @urlstr: the url string to parse
* @url: (out): location to hold the result.
* @url: (out) (transfer full) (nullable): location to hold the result.
*
* Parse the RTSP @urlstr into a newly allocated #GstRTSPUrl. Free after usage
* with gst_rtsp_url_free().
@ -108,6 +108,8 @@ gst_rtsp_url_parse (const gchar * urlstr, GstRTSPUrl ** url)
g_return_val_if_fail (urlstr != NULL, GST_RTSP_EINVAL);
g_return_val_if_fail (url != NULL, GST_RTSP_EINVAL);
*url = NULL;
res = g_new0 (GstRTSPUrl, 1);
p = (gchar *) urlstr;
@ -222,7 +224,7 @@ invalid:
*
* Make a copy of @url.
*
* Returns: a copy of @url. Free with gst_rtsp_url_free () after usage.
* Returns: (transfer full): a copy of @url. Free with gst_rtsp_url_free () after usage.
*/
GstRTSPUrl *
gst_rtsp_url_copy (const GstRTSPUrl * url)
@ -314,7 +316,7 @@ gst_rtsp_url_get_port (const GstRTSPUrl * url, guint16 * port)
*
* Get a newly allocated string describing the request URI for @url.
*
* Returns: a string with the request URI. g_free() after usage.
* Returns: (transfer full): a string with the request URI. g_free() after usage.
*/
gchar *
gst_rtsp_url_get_request_uri (const GstRTSPUrl * url)
@ -350,7 +352,7 @@ gst_rtsp_url_get_request_uri (const GstRTSPUrl * url)
* Get a newly allocated string describing the request URI for @url
* combined with the control path for @control_path
*
* Returns: a string with the request URI combined with the control path.
* Returns: (transfer full): a string with the request URI combined with the control path.
* g_free() after usage.
*
* Since: 1.18