mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-16 21:36:35 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs: gst: more gobject introspection annotations

Browse source 
Many of these are superfluous, added for clarity.
This commit is contained in:
Tim-Philipp Müller 2010-12-07 18:35:04 +00:00
parent 0eaa25cbf5
commit 3256c708be
55 changed files with 1080 additions and 803 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
gst/gst.c
View file

@ -297,7 +297,7 @@ DllMain (HINSTANCE hinstDLL, DWORD fdwReason, LPVOID lpvReserved)
* threading system as one of the very first things in your program * threading system as one of the very first things in your program
* (see the example at the beginning of this section). * (see the example at the beginning of this section).
* *
* Returns: a pointer to GStreamer's option group. * Returns: (transfer full): a pointer to GStreamer's option group.
*/ */
GOptionGroup * GOptionGroup *
@ -398,7 +398,7 @@ gst_init_get_option_group (void)
/** /**
* gst_init_check: * gst_init_check:
* @argc: (inout): pointer to application's argc * @argc: (inout) (allow-none): pointer to application's argc
* @argv: (inout) (array length=argc) (allow-none): pointer to application's argv * @argv: (inout) (array length=argc) (allow-none): pointer to application's argv
* @err: pointer to a #GError to which a message will be posted on error * @err: pointer to a #GError to which a message will be posted on error
* *
@ -457,7 +457,7 @@ gst_init_check (int *argc, char **argv[], GError ** err)
/** /**
* gst_init: * gst_init:
* @argc: (inout): pointer to application's argc * @argc: (inout) (allow-none): pointer to application's argc
* @argv: (inout) (array length=argc) (allow-none): pointer to application's argv * @argv: (inout) (array length=argc) (allow-none): pointer to application's argv
* *
* Initializes the GStreamer library, setting up internal path lists, * Initializes the GStreamer library, setting up internal path lists,
@ -1125,10 +1125,10 @@ gst_deinit (void)
/** /**
* gst_version: * gst_version:
* @major: pointer to a guint to store the major version number * @major: (out): pointer to a guint to store the major version number
* @minor: pointer to a guint to store the minor version number * @minor: (out): pointer to a guint to store the minor version number
* @micro: pointer to a guint to store the micro version number * @micro: (out): pointer to a guint to store the micro version number
* @nano: pointer to a guint to store the nano version number * @nano: (out): pointer to a guint to store the nano version number
* *
* Gets the version number of the GStreamer library. * Gets the version number of the GStreamer library.
*/ */
@ -1152,7 +1152,8 @@ gst_version (guint * major, guint * minor, guint * micro, guint * nano)
* This function returns a string that is useful for describing this version * This function returns a string that is useful for describing this version
* of GStreamer to the outside world: user agent strings, logging, ... * of GStreamer to the outside world: user agent strings, logging, ...
* *
* Returns: a newly allocated string describing this version of GStreamer. * Returns: (transfer full): a newly allocated string describing this version
* of GStreamer.
*/ */
gchar * gchar *

26
gst/gstbin.c
View file

@ -588,7 +588,7 @@ gst_bin_dispose (GObject * object)
* *
* Creates a new bin with the given name. * Creates a new bin with the given name.
* *
* Returns: a new #GstBin * Returns: (transfer full): a new #GstBin
*/ */
GstElement * GstElement *
gst_bin_new (const gchar * name) gst_bin_new (const gchar * name)
@ -1186,7 +1186,7 @@ had_parent:
/** /**
* gst_bin_add: * gst_bin_add:
* @bin: a #GstBin * @bin: a #GstBin
* @element: the #GstElement to add * @element: (transfer full): the #GstElement to add
* *
* Adds the given element to the bin. Sets the element's parent, and thus * Adds the given element to the bin. Sets the element's parent, and thus
* takes ownership of the element. An element can only be added to one bin. * takes ownership of the element. An element can only be added to one bin.
@ -1482,7 +1482,7 @@ already_removing:
/** /**
* gst_bin_remove: * gst_bin_remove:
* @bin: a #GstBin * @bin: a #GstBin
* @element: the #GstElement to remove * @element: (transfer none): the #GstElement to remove
* *
* Removes the element from the bin, unparenting it as well. * Removes the element from the bin, unparenting it as well.
* Unparenting the element means that the element will be dereferenced, * Unparenting the element means that the element will be dereferenced,
@ -1547,7 +1547,7 @@ iterate_child (GstIterator * it, GstElement * child)
* *
* MT safe. Caller owns returned value. * MT safe. Caller owns returned value.
* *
* Returns: a #GstIterator of #GstElement, or NULL * Returns: (transfer full): a #GstIterator of #GstElement, or NULL
*/ */
GstIterator * GstIterator *
gst_bin_iterate_elements (GstBin * bin) gst_bin_iterate_elements (GstBin * bin)
@ -1597,7 +1597,7 @@ iterate_child_recurse (GstIterator * it, GstElement * child)
* *
* MT safe. Caller owns returned value. * MT safe. Caller owns returned value.
* *
* Returns: a #GstIterator of #GstElement, or NULL * Returns: (transfer full): a #GstIterator of #GstElement, or NULL
*/ */
GstIterator * GstIterator *
gst_bin_iterate_recurse (GstBin * bin) gst_bin_iterate_recurse (GstBin * bin)
@ -1668,7 +1668,7 @@ sink_iterator_filter (GstElement * child, GstBin * bin)
* *
* MT safe. Caller owns returned value. * MT safe. Caller owns returned value.
* *
* Returns: a #GstIterator of #GstElement, or NULL * Returns: (transfer full): a #GstIterator of #GstElement, or NULL
*/ */
GstIterator * GstIterator *
gst_bin_iterate_sinks (GstBin * bin) gst_bin_iterate_sinks (GstBin * bin)
@ -1730,7 +1730,7 @@ src_iterator_filter (GstElement * child, GstBin * bin)
* *
* MT safe. Caller owns returned value. * MT safe. Caller owns returned value.
* *
* Returns: a #GstIterator of #GstElement, or NULL * Returns: (transfer full): a #GstIterator of #GstElement, or NULL
*/ */
GstIterator * GstIterator *
gst_bin_iterate_sources (GstBin * bin) gst_bin_iterate_sources (GstBin * bin)
@ -2083,7 +2083,7 @@ gst_bin_sort_iterator_new (GstBin * bin)
* *
* MT safe. Caller owns returned value. * MT safe. Caller owns returned value.
* *
* Returns: a #GstIterator of #GstElement, or NULL * Returns: (transfer full): a #GstIterator of #GstElement, or NULL
*/ */
GstIterator * GstIterator *
gst_bin_iterate_sorted (GstBin * bin) gst_bin_iterate_sorted (GstBin * bin)
@ -3688,7 +3688,7 @@ compare_name (GstElement * element, const gchar * name)
* *
* MT safe. Caller owns returned reference. * MT safe. Caller owns returned reference.
* *
* Returns: the #GstElement with the given name, or NULL * Returns: (transfer full): the #GstElement with the given name, or NULL
*/ */
GstElement * GstElement *
gst_bin_get_by_name (GstBin * bin, const gchar * name) gst_bin_get_by_name (GstBin * bin, const gchar * name)
@ -3722,7 +3722,7 @@ gst_bin_get_by_name (GstBin * bin, const gchar * name)
* *
* MT safe. Caller owns returned reference. * MT safe. Caller owns returned reference.
* *
* Returns: the #GstElement with the given name, or NULL * Returns: (transfer full): the #GstElement with the given name, or NULL
*/ */
GstElement * GstElement *
gst_bin_get_by_name_recurse_up (GstBin * bin, const gchar * name) gst_bin_get_by_name_recurse_up (GstBin * bin, const gchar * name)
@ -3779,7 +3779,7 @@ compare_interface (GstElement * element, gpointer interface)
* *
* MT safe. Caller owns returned reference. * MT safe. Caller owns returned reference.
* *
* Returns: A #GstElement inside the bin implementing the interface * Returns: (transfer full): A #GstElement inside the bin implementing the interface
*/ */
GstElement * GstElement *
gst_bin_get_by_interface (GstBin * bin, GType iface) gst_bin_get_by_interface (GstBin * bin, GType iface)
@ -3813,8 +3813,8 @@ gst_bin_get_by_interface (GstBin * bin, GType iface)
* *
* MT safe. Caller owns returned value. * MT safe. Caller owns returned value.
* *
* Returns: a #GstIterator of #GstElement for all elements in the bin * Returns: (transfer full): a #GstIterator of #GstElement for all elements
* implementing the given interface, or NULL * in the bin implementing the given interface, or NULL
*/ */
GstIterator * GstIterator *
gst_bin_iterate_all_by_interface (GstBin * bin, GType iface) gst_bin_iterate_all_by_interface (GstBin * bin, GType iface)

28
gst/gstbuffer.c
View file

@ -323,7 +323,8 @@ gst_buffer_init (GstBuffer * buffer)
* Creates a newly allocated buffer without any data. * Creates a newly allocated buffer without any data.
* *
* MT safe. * MT safe.
* Returns: the new #GstBuffer. *
* Returns: (transfer full): the new #GstBuffer.
*/ */
GstBuffer * GstBuffer *
gst_buffer_new (void) gst_buffer_new (void)
@ -352,7 +353,8 @@ gst_buffer_new (void)
* Note that when @size == 0, the buffer data pointer will be NULL. * Note that when @size == 0, the buffer data pointer will be NULL.
* *
* MT safe. * MT safe.
* Returns: the new #GstBuffer. *
* Returns: (transfer full): the new #GstBuffer.
*/ */
GstBuffer * GstBuffer *
gst_buffer_new_and_alloc (guint size) gst_buffer_new_and_alloc (guint size)
@ -397,7 +399,8 @@ gst_buffer_new_and_alloc (guint size)
* *
* MT safe. * MT safe.
* *
* Returns: a new #GstBuffer, or NULL if the memory couldn't be allocated. * Returns: (transfer full): a new #GstBuffer, or NULL if the memory couldn't
* be allocated.
* *
* Since: 0.10.13 * Since: 0.10.13
*/ */
@ -448,7 +451,7 @@ gst_buffer_try_new_and_alloc (guint size)
* Gets the media type of the buffer. This can be NULL if there * Gets the media type of the buffer. This can be NULL if there
* is no media type attached to this buffer. * is no media type attached to this buffer.
* *
* Returns: a reference to the #GstCaps. unref after usage. * Returns: (transfer full): a reference to the #GstCaps. unref after usage.
* Returns NULL if there were no caps on this buffer. * Returns NULL if there were no caps on this buffer.
*/ */
/* this is not made atomic because if the buffer were reffed from multiple /* this is not made atomic because if the buffer were reffed from multiple
@ -472,7 +475,7 @@ gst_buffer_get_caps (GstBuffer * buffer)
/** /**
* gst_buffer_set_caps: * gst_buffer_set_caps:
* @buffer: a #GstBuffer. * @buffer: a #GstBuffer.
* @caps: a #GstCaps. * @caps: (transfer none): a #GstCaps.
* *
* Sets the media type on the buffer. The refcount of the caps will * Sets the media type on the buffer. The refcount of the caps will
* be increased and any previous caps on the buffer will be * be increased and any previous caps on the buffer will be
@ -514,7 +517,7 @@ gst_buffer_is_metadata_writable (GstBuffer * buf)
/** /**
* gst_buffer_make_metadata_writable: * gst_buffer_make_metadata_writable:
* @buf: a #GstBuffer * @buf: (transfer full): a #GstBuffer
* *
* Similar to gst_buffer_make_writable, but does not ensure that the buffer * Similar to gst_buffer_make_writable, but does not ensure that the buffer
* data array is writable. Instead, this just ensures that the returned buffer * data array is writable. Instead, this just ensures that the returned buffer
@ -524,7 +527,8 @@ gst_buffer_is_metadata_writable (GstBuffer * buf)
* After calling this function, @buf should not be referenced anymore. The * After calling this function, @buf should not be referenced anymore. The
* result of this function has guaranteed writable metadata. * result of this function has guaranteed writable metadata.
* *
* Returns: A new #GstBuffer with writable metadata. * Returns: (transfer full): a new #GstBuffer with writable metadata, which
* may or may not be the same as @buf.
*/ */
GstBuffer * GstBuffer *
gst_buffer_make_metadata_writable (GstBuffer * buf) gst_buffer_make_metadata_writable (GstBuffer * buf)
@ -561,8 +565,9 @@ gst_buffer_make_metadata_writable (GstBuffer * buf)
* to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE. * to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE.
* *
* MT safe. * MT safe.
* Returns: the new #GstBuffer. *
* Returns NULL if the arguments were invalid. * Returns: (transfer full): the new #GstBuffer or NULL if the arguments were
* invalid.
*/ */
GstBuffer * GstBuffer *
gst_buffer_create_sub (GstBuffer * buffer, guint offset, guint size) gst_buffer_create_sub (GstBuffer * buffer, guint offset, guint size)
@ -680,8 +685,9 @@ gst_buffer_is_span_fast (GstBuffer * buf1, GstBuffer * buf2)
* gst_buffer_is_span_fast() to determine if a memcpy will be needed. * gst_buffer_is_span_fast() to determine if a memcpy will be needed.
* *
* MT safe. * MT safe.
* Returns: the new #GstBuffer that spans the two source buffers. *
* Returns NULL if the arguments are invalid. * Returns: (transfer full): the new #GstBuffer that spans the two source
* buffers, or NULL if the arguments are invalid.
*/ */
GstBuffer * GstBuffer *
gst_buffer_span (GstBuffer * buf1, guint32 offset, GstBuffer * buf2, gst_buffer_span (GstBuffer * buf1, guint32 offset, GstBuffer * buf2,

24
gst/gstbuffer.h
View file

@ -333,7 +333,7 @@ G_STMT_START { \
* GstBuffer instances can potentially increase the number * GstBuffer instances can potentially increase the number
* of memcpy operations in a pipeline. * of memcpy operations in a pipeline.
* *
* Returns: @buf * Returns: (transfer full): @buf
*/ */
#ifdef _FOOL_GTK_DOC_ #ifdef _FOOL_GTK_DOC_
G_INLINE_FUNC GstBuffer * gst_buffer_ref (GstBuffer * buf); G_INLINE_FUNC GstBuffer * gst_buffer_ref (GstBuffer * buf);
@ -347,7 +347,7 @@ gst_buffer_ref (GstBuffer * buf)
/** /**
* gst_buffer_unref: * gst_buffer_unref:
* @buf: a #GstBuffer. * @buf: (transfer full): a #GstBuffer.
* *
* Decreases the refcount of the buffer. If the refcount reaches 0, the buffer * Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
* will be freed. If GST_BUFFER_MALLOCDATA() is non-NULL, this pointer will * will be freed. If GST_BUFFER_MALLOCDATA() is non-NULL, this pointer will
@ -371,7 +371,7 @@ gst_buffer_unref (GstBuffer * buf)
* Create a copy of the given buffer. This will also make a newly allocated * Create a copy of the given buffer. This will also make a newly allocated
* copy of the data the source buffer contains. * copy of the data the source buffer contains.
* *
* Returns: a new copy of @buf. * Returns: (transfer full): a new copy of @buf.
*/ */
#ifdef _FOOL_GTK_DOC_ #ifdef _FOOL_GTK_DOC_
G_INLINE_FUNC GstBuffer * gst_buffer_copy (const GstBuffer * buf); G_INLINE_FUNC GstBuffer * gst_buffer_copy (const GstBuffer * buf);
@ -428,11 +428,14 @@ void gst_buffer_copy_metadata (GstBuffer *dest, const GstBuffe
#define gst_buffer_is_writable(buf) gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (buf)) #define gst_buffer_is_writable(buf) gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (buf))
/** /**
* gst_buffer_make_writable: * gst_buffer_make_writable:
* @buf: a #GstBuffer * @buf: (transfer full): a #GstBuffer
* *
* Makes a writable buffer from the given buffer. If the source buffer is * Makes a writable buffer from the given buffer. If the source buffer is
* already writable, this will simply return the same buffer. A copy will * already writable, this will simply return the same buffer. A copy will
* otherwise be made using gst_buffer_copy(). * otherwise be made using gst_buffer_copy().
*
* Returns: (transfer full): a writable buffer which may or may not be the
* same as @buf
*/ */
#define gst_buffer_make_writable(buf) GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (buf))) #define gst_buffer_make_writable(buf) GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (buf)))
@ -443,9 +446,10 @@ GstBuffer* gst_buffer_make_metadata_writable (GstBuffer *buf);
/** /**
* gst_buffer_replace: * gst_buffer_replace:
* @obuf: pointer to a pointer to a #GstBuffer to be replaced. * @obuf: (inout) (transfer full): pointer to a pointer to a #GstBuffer to be
* @nbuf: pointer to a #GstBuffer that will replace the buffer pointed to by * replaced.
* @obuf. * @nbuf: (transfer none) (allow-none): pointer to a #GstBuffer that will
* replace the buffer pointed to by @obuf.
* *
* Modifies a pointer to a #GstBuffer to point to a different #GstBuffer. The * Modifies a pointer to a #GstBuffer to point to a different #GstBuffer. The
* modification is done atomically (so this is useful for ensuring thread safety * modification is done atomically (so this is useful for ensuring thread safety
@ -474,7 +478,7 @@ GstBuffer* gst_buffer_span (GstBuffer *buf1, guint32 offset
/** /**
* gst_value_set_buffer: * gst_value_set_buffer:
* @v: a #GValue to receive the data * @v: a #GValue to receive the data
* @b: a #GstBuffer to assign to the GstValue * @b: (transfer none): a #GstBuffer to assign to the GstValue
* *
* Sets @b as the value of @v. Caller retains reference to buffer. * Sets @b as the value of @v. Caller retains reference to buffer.
*/ */
@ -482,7 +486,7 @@ GstBuffer* gst_buffer_span (GstBuffer *buf1, guint32 offset
/** /**
* gst_value_take_buffer: * gst_value_take_buffer:
* @v: a #GValue to receive the data * @v: a #GValue to receive the data
* @b: a #GstBuffer to assign to the GstValue * @b: (transfer full): a #GstBuffer to assign to the GstValue
* *
* Sets @b as the value of @v. Caller gives away reference to buffer. * Sets @b as the value of @v. Caller gives away reference to buffer.
*/ */
@ -494,6 +498,8 @@ GstBuffer* gst_buffer_span (GstBuffer *buf1, guint32 offset
* Receives a #GstBuffer as the value of @v. Does not return a reference to * Receives a #GstBuffer as the value of @v. Does not return a reference to
* the buffer, so the pointer is only valid for as long as the caller owns * the buffer, so the pointer is only valid for as long as the caller owns
* a reference to @v. * a reference to @v.
*
* Returns: (transfer none): buffer
*/ */
#define gst_value_get_buffer(v) GST_BUFFER_CAST (gst_value_get_mini_object(v)) #define gst_value_get_buffer(v) GST_BUFFER_CAST (gst_value_get_mini_object(v))

36
gst/gstbufferlist.c
View file

@ -248,7 +248,10 @@ gst_buffer_list_class_init (GstBufferListClass * list_class)
* Creates a new, empty #GstBufferList. The caller is responsible for unreffing * Creates a new, empty #GstBufferList. The caller is responsible for unreffing
* the returned #GstBufferList. * the returned #GstBufferList.
* *
* Returns: the new #GstBufferList. gst_buffer_list_unref() after usage. * Free-function: gst_buffer_list_unref
*
* Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref()
* after usage.
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -377,8 +380,8 @@ gst_buffer_list_foreach (GstBufferList * list, GstBufferListFunc func,
* Note that this function is not efficient for iterating over the entire list. * Note that this function is not efficient for iterating over the entire list.
* Use an iterator or gst_buffer_list_foreach() instead. * Use an iterator or gst_buffer_list_foreach() instead.
* *
* Returns: the buffer at @idx in @group or NULL when there is no buffer. The * Returns: (transfer none): the buffer at @idx in @group or NULL when there
* buffer remains valid as long as @list is valid. * is no buffer. The buffer remains valid as long as @list is valid.
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -426,8 +429,10 @@ gst_buffer_list_get (GstBufferList * list, guint group, guint idx)
* Iterate the buffers in @list. The owner of the iterator must also be the * Iterate the buffers in @list. The owner of the iterator must also be the
* owner of a reference to @list while the returned iterator is in use. * owner of a reference to @list while the returned iterator is in use.
* *
* Returns: a new #GstBufferListIterator of the buffers in @list. * Free-function: gst_buffer_list_iterator_free
* gst_buffer_list_iterator_free() after usage *
* Returns: (transfer full): a new #GstBufferListIterator of the buffers in
* @list. gst_buffer_list_iterator_free() after usage
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -448,7 +453,7 @@ gst_buffer_list_iterate (GstBufferList * list)
/** /**
* gst_buffer_list_iterator_free: * gst_buffer_list_iterator_free:
* @it: the #GstBufferListIterator to free * @it: (transfer full): the #GstBufferListIterator to free
* *
* Free the iterator. * Free the iterator.
* *
@ -500,7 +505,7 @@ gst_buffer_list_iterator_n_buffers (const GstBufferListIterator * it)
/** /**
* gst_buffer_list_iterator_add: * gst_buffer_list_iterator_add:
* @it: a #GstBufferListIterator * @it: a #GstBufferListIterator
* @buffer: a #GstBuffer * @buffer: (transfer full): a #GstBuffer
* *
* Inserts @buffer into the #GstBufferList iterated with @it. The buffer is * Inserts @buffer into the #GstBufferList iterated with @it. The buffer is
* inserted into the current group, immediately before the buffer that would be * inserted into the current group, immediately before the buffer that would be
@ -529,7 +534,7 @@ gst_buffer_list_iterator_add (GstBufferListIterator * it, GstBuffer * buffer)
/** /**
* gst_buffer_list_iterator_add_list: * gst_buffer_list_iterator_add_list:
* @it: a #GstBufferListIterator * @it: a #GstBufferListIterator
* @list: a #GList * @list: (transfer full) (element-type Gst.Buffer): a #GList of buffers
* *
* Inserts @list of buffers into the #GstBufferList iterated with @it. The list is * Inserts @list of buffers into the #GstBufferList iterated with @it. The list is
* inserted into the current group, immediately before the buffer that would be * inserted into the current group, immediately before the buffer that would be
@ -610,7 +615,8 @@ gst_buffer_list_iterator_add_group (GstBufferListIterator * it)
* The caller will not get a new ref to the returned #GstBuffer and must not * The caller will not get a new ref to the returned #GstBuffer and must not
* unref it. * unref it.
* *
* Returns: the next buffer in the current group of the buffer list, or NULL * Returns: (transfer none): the next buffer in the current group of the
* buffer list, or NULL
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -707,7 +713,7 @@ gst_buffer_list_iterator_remove (GstBufferListIterator * it)
/** /**
* gst_buffer_list_iterator_take: * gst_buffer_list_iterator_take:
* @it: a #GstBufferListIterator * @it: a #GstBufferListIterator
* @buffer: a #GstBuffer * @buffer: (transfer full): a #GstBuffer
* *
* Replaces the last buffer returned by gst_buffer_list_iterator_next() with * Replaces the last buffer returned by gst_buffer_list_iterator_next() with
* @buffer in the #GstBufferList iterated with @it and takes ownership of * @buffer in the #GstBufferList iterated with @it and takes ownership of
@ -719,6 +725,8 @@ gst_buffer_list_iterator_remove (GstBufferListIterator * it)
* gst_buffer_list_iterator_steal() and takes ownership of @buffer (i.e. the * gst_buffer_list_iterator_steal() and takes ownership of @buffer (i.e. the
* refcount of @buffer is not increased). * refcount of @buffer is not increased).
* *
* FIXME 0.11: this conditional taking-ownership is not good for bindings
*
* Since: 0.10.24 * Since: 0.10.24
*/ */
void void
@ -742,7 +750,8 @@ gst_buffer_list_iterator_take (GstBufferListIterator * it, GstBuffer * buffer)
* Returns the last buffer returned by gst_buffer_list_iterator_next() without * Returns the last buffer returned by gst_buffer_list_iterator_next() without
* modifying the refcount of the buffer. * modifying the refcount of the buffer.
* *
* Returns: the last buffer returned by gst_buffer_list_iterator_next() * Returns: (transfer none): the last buffer returned by
* gst_buffer_list_iterator_next()
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -776,7 +785,7 @@ gst_buffer_list_iterator_steal (GstBufferListIterator * it)
* *
* See #GstBufferListDoFunction for more details. * See #GstBufferListDoFunction for more details.
* *
* Returns: the return value from @do_func * Returns: (transfer none): the return value from @do_func
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -818,7 +827,8 @@ gst_buffer_list_iterator_do (GstBufferListIterator * it,
* This function will not move the implicit cursor or in any other way affect * This function will not move the implicit cursor or in any other way affect
* the state of the iterator @it or the list. * the state of the iterator @it or the list.
* *
* Returns: a new #GstBuffer, gst_buffer_unref() after usage, or NULL * Returns: (transfer full): a new #GstBuffer, gst_buffer_unref() after usage,
* or NULL
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */

17
gst/gstbufferlist.h
View file

@ -41,7 +41,7 @@ typedef struct _GstBufferListIterator GstBufferListIterator;
/** /**
* GstBufferListDoFunction: * GstBufferListDoFunction:
* @buffer: the #GstBuffer * @buffer: (transfer full): the #GstBuffer
* @user_data: user data * @user_data: user data
* *
* A function for accessing the last buffer returned by * A function for accessing the last buffer returned by
@ -56,8 +56,8 @@ typedef struct _GstBufferListIterator GstBufferListIterator;
* unreffed. If NULL is returned, the buffer will be removed from the list. The * unreffed. If NULL is returned, the buffer will be removed from the list. The
* list must be writable. * list must be writable.
* *
* Returns: the buffer to replace @buffer in the list, or NULL to remove @buffer * Returns: (transfer full): the buffer to replace @buffer in the list, or NULL
* from the list * to remove @buffer from the list
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -125,7 +125,7 @@ GstBufferList *gst_buffer_list_new (void);
* additional references to GstBufferList instances can potentially increase * additional references to GstBufferList instances can potentially increase
* the number of memcpy operations in a pipeline. * the number of memcpy operations in a pipeline.
* *
* Returns: @list * Returns: (transfer full): @list
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -142,7 +142,7 @@ gst_buffer_list_ref (GstBufferList * list)
/** /**
* gst_buffer_list_unref: * gst_buffer_list_unref:
* @list: a #GstBufferList * @list: (transfer full): a #GstBufferList
* *
* Decreases the refcount of the buffer list. If the refcount reaches 0, the * Decreases the refcount of the buffer list. If the refcount reaches 0, the
* buffer list will be freed. * buffer list will be freed.
@ -168,7 +168,7 @@ gst_buffer_list_unref (GstBufferList * list)
* allocated copy of the source list with copies of buffer pointers. The * allocated copy of the source list with copies of buffer pointers. The
* refcount of buffers pointed to will be increased by one. * refcount of buffers pointed to will be increased by one.
* *
* Returns: a new copy of @list. * Returns: (transfer full): a new copy of @list.
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -194,12 +194,15 @@ gst_buffer_list_copy (const GstBufferList * list)
/** /**
* gst_buffer_list_make_writable: * gst_buffer_list_make_writable:
* @list: a #GstBufferList * @list: (transfer full): a #GstBufferList
* *
* Makes a writable buffer list from the given buffer list. If the source buffer * Makes a writable buffer list from the given buffer list. If the source buffer
* list is already writable, this will simply return the same buffer list. A * list is already writable, this will simply return the same buffer list. A
* copy will otherwise be made using gst_buffer_list_copy(). * copy will otherwise be made using gst_buffer_list_copy().
* *
* Returns: (transfer full): a writable list, which may or may not be the
* same as @list
*
* Since: 0.10.24 * Since: 0.10.24
*/ */
#define gst_buffer_list_make_writable(list) GST_BUFFER_LIST_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (list))) #define gst_buffer_list_make_writable(list) GST_BUFFER_LIST_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (list)))

41
gst/gstbus.c
View file

@ -265,7 +265,7 @@ gst_bus_set_main_context (GstBus * bus, GMainContext * ctx)
* *
* Creates a new #GstBus instance. * Creates a new #GstBus instance.
* *
* Returns: a new #GstBus instance * Returns: (transfer full): a new #GstBus instance
*/ */
GstBus * GstBus *
gst_bus_new (void) gst_bus_new (void)
@ -281,7 +281,7 @@ gst_bus_new (void)
/** /**
* gst_bus_post: * gst_bus_post:
* @bus: a #GstBus to post on * @bus: a #GstBus to post on
* @message: The #GstMessage to post * @message: (transfer full): the #GstMessage to post
* *
* Post a message on the given bus. Ownership of the message * Post a message on the given bus. Ownership of the message
* is taken by the bus. * is taken by the bus.
@ -468,10 +468,10 @@ gst_bus_set_flushing (GstBus * bus, gboolean flushing)
* @timeout is #GST_CLOCK_TIME_NONE, this function will block forever until a * @timeout is #GST_CLOCK_TIME_NONE, this function will block forever until a
* matching message was posted on the bus. * matching message was posted on the bus.
* *
* Returns: a #GstMessage matching the filter in @types, or NULL if no matching * Returns: (transfer full): a #GstMessage matching the filter in @types,
* message was found on the bus until the timeout expired. * or NULL if no matching message was found on the bus until the timeout
* The message is taken from the bus and needs to be unreffed with * expired. The message is taken from the bus and needs to be unreffed
* gst_message_unref() after usage. * with gst_message_unref() after usage.
* *
* MT safe. * MT safe.
* *
@ -558,8 +558,8 @@ beach:
* #GST_CLOCK_TIME_NONE, this function will block forever until a message was * #GST_CLOCK_TIME_NONE, this function will block forever until a message was
* posted on the bus. * posted on the bus.
* *
* Returns: The #GstMessage that is on the bus after the specified timeout * Returns: (transfer full): the #GstMessage that is on the bus after the
* or NULL if the bus is empty after the timeout expired. * specified timeout or NULL if the bus is empty after the timeout expired.
* The message is taken from the bus and needs to be unreffed with * The message is taken from the bus and needs to be unreffed with
* gst_message_unref() after usage. * gst_message_unref() after usage.
* *
@ -585,10 +585,10 @@ gst_bus_timed_pop (GstBus * bus, GstClockTime timeout)
* message that does match @type. If there is no message matching @type on * message that does match @type. If there is no message matching @type on
* the bus, all messages will be discarded. * the bus, all messages will be discarded.
* *
* Returns: The next #GstMessage matching @type that is on the bus, or NULL if * Returns: (transfer full): the next #GstMessage matching @type that is on
* the bus is empty or there is no message matching @type. * the bus, or NULL if the bus is empty or there is no message matching
* The message is taken from the bus and needs to be unreffed with * @type. The message is taken from the bus and needs to be unreffed with
* gst_message_unref() after usage. * gst_message_unref() after usage.
* *
* MT safe. * MT safe.
* *
@ -609,9 +609,9 @@ gst_bus_pop_filtered (GstBus * bus, GstMessageType types)
* *
* Get a message from the bus. * Get a message from the bus.
* *
* Returns: The #GstMessage that is on the bus, or NULL if the bus is empty. * Returns: (transfer full): the #GstMessage that is on the bus, or NULL if the
* The message is taken from the bus and needs to be unreffed with * bus is empty. The message is taken from the bus and needs to be unreffed
* gst_message_unref() after usage. * with gst_message_unref() after usage.
* *
* MT safe. * MT safe.
*/ */
@ -631,7 +631,8 @@ gst_bus_pop (GstBus * bus)
* on the bus' message queue. A reference is returned, and needs to be unreffed * on the bus' message queue. A reference is returned, and needs to be unreffed
* by the caller. * by the caller.
* *
* Returns: The #GstMessage that is on the bus, or NULL if the bus is empty. * Returns: (transfer full): the #GstMessage that is on the bus, or NULL if the
* bus is empty.
* *
* MT safe. * MT safe.
*/ */
@ -808,7 +809,7 @@ static GSourceFuncs gst_bus_source_funcs = {
* a message is on the bus. After the GSource is dispatched, the * a message is on the bus. After the GSource is dispatched, the
* message is popped off the bus and unreffed. * message is popped off the bus and unreffed.
* *
* Returns: A #GSource that can be added to a mainloop. * Returns: (transfer full): a #GSource that can be added to a mainloop.
*/ */
GSource * GSource *
gst_bus_create_watch (GstBus * bus) gst_bus_create_watch (GstBus * bus)
@ -1025,9 +1026,9 @@ poll_destroy_timeout (GstBusPollData * poll_data)
* better handled by setting up an asynchronous bus watch and doing things * better handled by setting up an asynchronous bus watch and doing things
* from there. * from there.
* *
* Returns: The message that was received, or NULL if the poll timed out. * Returns: (transfer full): the message that was received, or NULL if the
* The message is taken from the bus and needs to be unreffed with * poll timed out. The message is taken from the bus and needs to be
* gst_message_unref() after usage. * unreffed with gst_message_unref() after usage.
*/ */
GstMessage * GstMessage *
gst_bus_poll (GstBus * bus, GstMessageType events, GstClockTimeDiff timeout) gst_bus_poll (GstBus * bus, GstMessageType events, GstClockTimeDiff timeout)

48
gst/gstcaps.c
View file

@ -157,7 +157,7 @@ gst_caps_get_type (void)
* #GstCaps contains no media formats. * #GstCaps contains no media formats.
* Caller is responsible for unreffing the returned caps. * Caller is responsible for unreffing the returned caps.
* *
* Returns: the new #GstCaps * Returns: (transfer full): the new #GstCaps
*/ */
GstCaps * GstCaps *
gst_caps_new_empty (void) gst_caps_new_empty (void)
@ -187,7 +187,7 @@ gst_caps_new_empty (void)
* Creates a new #GstCaps that indicates that it is compatible with * Creates a new #GstCaps that indicates that it is compatible with
* any media format. * any media format.
* *
* Returns: the new #GstCaps * Returns: (transfer full): the new #GstCaps
*/ */
GstCaps * GstCaps *
gst_caps_new_any (void) gst_caps_new_any (void)
@ -210,7 +210,7 @@ gst_caps_new_any (void)
* as gst_structure_new(). * as gst_structure_new().
* Caller is responsible for unreffing the returned caps. * Caller is responsible for unreffing the returned caps.
* *
* Returns: the new #GstCaps * Returns: (transfer full): the new #GstCaps
*/ */
GstCaps * GstCaps *
gst_caps_new_simple (const char *media_type, const char *fieldname, ...) gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
@ -239,7 +239,7 @@ gst_caps_new_simple (const char *media_type, const char *fieldname, ...)
* arguments. The list must be NULL-terminated. The structures * arguments. The list must be NULL-terminated. The structures
* are not copied; the returned #GstCaps owns the structures. * are not copied; the returned #GstCaps owns the structures.
* *
* Returns: the new #GstCaps * Returns: (transfer full): the new #GstCaps
*/ */
GstCaps * GstCaps *
gst_caps_new_full (GstStructure * struct1, ...) gst_caps_new_full (GstStructure * struct1, ...)
@ -263,7 +263,7 @@ gst_caps_new_full (GstStructure * struct1, ...)
* arguments. The list must be NULL-terminated. The structures * arguments. The list must be NULL-terminated. The structures
* are not copied; the returned #GstCaps owns the structures. * are not copied; the returned #GstCaps owns the structures.
* *
* Returns: the new #GstCaps * Returns: (transfer full): the new #GstCaps
*/ */
GstCaps * GstCaps *
gst_caps_new_full_valist (GstStructure * structure, va_list var_args) gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
@ -293,7 +293,7 @@ gst_caps_new_full_valist (GstStructure * structure, va_list var_args)
* *
* When you are finished with the caps, call gst_caps_unref() on it. * When you are finished with the caps, call gst_caps_unref() on it.
* *
* Returns: the new #GstCaps * Returns: (transfer full): the new #GstCaps
*/ */
GstCaps * GstCaps *
gst_caps_copy (const GstCaps * caps) gst_caps_copy (const GstCaps * caps)
@ -346,7 +346,7 @@ _gst_caps_free (GstCaps * caps)
/** /**
* gst_caps_make_writable: * gst_caps_make_writable:
* @caps: the #GstCaps to make writable * @caps: (transfer full): the #GstCaps to make writable
* *
* Returns a writable copy of @caps. * Returns a writable copy of @caps.
* *
@ -360,7 +360,7 @@ _gst_caps_free (GstCaps * caps)
* that it returns. Don't access the argument after calling this function. See * that it returns. Don't access the argument after calling this function. See
* also: gst_caps_ref(). * also: gst_caps_ref().
* *
* Returns: the same #GstCaps object. * Returns: (transfer full): the same #GstCaps object.
*/ */
GstCaps * GstCaps *
gst_caps_make_writable (GstCaps * caps) gst_caps_make_writable (GstCaps * caps)
@ -394,7 +394,7 @@ gst_caps_make_writable (GstCaps * caps)
* implicitly by e.g. gst_caps_new_simple(), or via taking one explicitly with * implicitly by e.g. gst_caps_new_simple(), or via taking one explicitly with
* this function. * this function.
* *
* Returns: the same #GstCaps object. * Returns: (transfer full): the same #GstCaps object.
*/ */
GstCaps * GstCaps *
gst_caps_ref (GstCaps * caps) gst_caps_ref (GstCaps * caps)
@ -414,7 +414,7 @@ gst_caps_ref (GstCaps * caps)
/** /**
* gst_caps_unref: * gst_caps_unref:
* @caps: the #GstCaps to unref * @caps: (transfer full): the #GstCaps to unref
* *
* Unref a #GstCaps and and free all its structures and the * Unref a #GstCaps and and free all its structures and the
* structures' values when the refcount reaches 0. * structures' values when the refcount reaches 0.
@ -454,9 +454,9 @@ gst_static_caps_get_type (void)
* *
* Converts a #GstStaticCaps to a #GstCaps. * Converts a #GstStaticCaps to a #GstCaps.
* *
* Returns: A pointer to the #GstCaps. Unref after usage. Since the * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage.
* core holds an additional ref to the returned caps, * Since the core holds an additional ref to the returned caps,
* use gst_caps_make_writable() on the returned caps to modify it. * use gst_caps_make_writable() on the returned caps to modify it.
*/ */
GstCaps * GstCaps *
gst_static_caps_get (GstStaticCaps * static_caps) gst_static_caps_get (GstStaticCaps * static_caps)
@ -545,7 +545,8 @@ gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
* Retrieves the stucture with the given index from the list of structures * Retrieves the stucture with the given index from the list of structures
* contained in @caps. The caller becomes the owner of the returned structure. * contained in @caps. The caller becomes the owner of the returned structure.
* *
* Returns: a pointer to the #GstStructure corresponding to @index. * Returns: (transfer full): a pointer to the #GstStructure corresponding
* to @index.
* *
* Since: 0.10.30 * Since: 0.10.30
*/ */
@ -640,7 +641,7 @@ gst_caps_structure_is_subset (const GstStructure * minuend,
/** /**
* gst_caps_append: * gst_caps_append:
* @caps1: the #GstCaps that will be appended to * @caps1: the #GstCaps that will be appended to
* @caps2: the #GstCaps to append * @caps2: (transfer full): the #GstCaps to append
* *
* Appends the structures contained in @caps2 to @caps1. The structures in * Appends the structures contained in @caps2 to @caps1. The structures in
* @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is
@ -679,7 +680,7 @@ gst_caps_append (GstCaps * caps1, GstCaps * caps2)
/** /**
* gst_caps_merge: * gst_caps_merge:
* @caps1: the #GstCaps that will take the new entries * @caps1: the #GstCaps that will take the new entries
* @caps2: the #GstCaps to merge in * @caps2: (transfer full): the #GstCaps to merge in
* *
* Appends the structures contained in @caps2 to @caps1 if they are not yet * Appends the structures contained in @caps2 to @caps1 if they are not yet
* expressed by @caps1. The structures in @caps2 are not copied -- they are * expressed by @caps1. The structures in @caps2 are not copied -- they are
@ -734,7 +735,7 @@ gst_caps_merge (GstCaps * caps1, GstCaps * caps2)
/** /**
* gst_caps_append_structure: * gst_caps_append_structure:
* @caps: the #GstCaps that will be appended to * @caps: the #GstCaps that will be appended to
* @structure: the #GstStructure to append * @structure: (transfer full): the #GstStructure to append
* *
* Appends @structure to @caps. The structure is not copied; @caps * Appends @structure to @caps. The structure is not copied; @caps
* becomes the owner of @structure. * becomes the owner of @structure.
@ -780,7 +781,7 @@ gst_caps_remove_structure (GstCaps * caps, guint idx)
/** /**
* gst_caps_merge_structure: * gst_caps_merge_structure:
* @caps: the #GstCaps that will the the new structure * @caps: the #GstCaps that will the the new structure
* @structure: the #GstStructure to merge * @structure: (transfer full): the #GstStructure to merge
* *
* Appends @structure to @caps if its not already expressed by @caps. The * Appends @structure to @caps if its not already expressed by @caps. The
* structure is not copied; @caps becomes the owner of @structure. * structure is not copied; @caps becomes the owner of @structure.
@ -855,7 +856,8 @@ gst_caps_get_size (const GstCaps * caps)
* You do not need to free or unref the structure returned, it * You do not need to free or unref the structure returned, it
* belongs to the #GstCaps. * belongs to the #GstCaps.
* *
* Returns: a pointer to the #GstStructure corresponding to @index * Returns: (transfer none): a pointer to the #GstStructure corresponding
* to @index
*/ */
GstStructure * GstStructure *
gst_caps_get_structure (const GstCaps * caps, guint index) gst_caps_get_structure (const GstCaps * caps, guint index)
@ -874,7 +876,7 @@ gst_caps_get_structure (const GstCaps * caps, guint index)
* Creates a new #GstCaps and appends a copy of the nth structure * Creates a new #GstCaps and appends a copy of the nth structure
* contained in @caps. * contained in @caps.
* *
* Returns: the new #GstCaps * Returns: (transfer full): the new #GstCaps
*/ */
GstCaps * GstCaps *
gst_caps_copy_nth (const GstCaps * caps, guint nth) gst_caps_copy_nth (const GstCaps * caps, guint nth)
@ -2005,7 +2007,7 @@ gst_caps_load_thyself (xmlNodePtr parent)
/** /**
* gst_caps_replace: * gst_caps_replace:
* @caps: a pointer to #GstCaps * @caps: (inout) (transfer full): a pointer to #GstCaps
* @newcaps: a #GstCaps to replace *caps * @newcaps: a #GstCaps to replace *caps
* *
* Replaces *caps with @newcaps. Unrefs the #GstCaps in the location * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location
@ -2050,7 +2052,7 @@ gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
* ]| * ]|
* This prints the caps in human readble form. * This prints the caps in human readble form.
* *
* Returns: a newly allocated string representing @caps. * Returns: (transfer full): a newly allocated string representing @caps.
*/ */
gchar * gchar *
gst_caps_to_string (const GstCaps * caps) gst_caps_to_string (const GstCaps * caps)
@ -2146,7 +2148,7 @@ gst_caps_from_string_inplace (GstCaps * caps, const gchar * string)
* *
* Converts @caps from a string representation. * Converts @caps from a string representation.
* *
* Returns: a newly allocated #GstCaps * Returns: (transfer full): a newly allocated #GstCaps
*/ */
GstCaps * GstCaps *
gst_caps_from_string (const gchar * string) gst_caps_from_string (const gchar * string)

15
gst/gstchildproxy.c
View file

@ -71,7 +71,8 @@ static guint signals[LAST_SIGNAL] = { 0 };
* *
* Implementors can use #GstObject together with gst_object_get_name() * Implementors can use #GstObject together with gst_object_get_name()
* *
* Returns: the child object or %NULL if not found. Unref after usage. * Returns: (transfer full): the child object or %NULL if not found. Unref
* after usage.
* *
* MT safe. * MT safe.
*/ */
@ -120,8 +121,8 @@ gst_child_proxy_get_child_by_name (GstChildProxy * parent, const gchar * name)
* *
* Fetches a child by its number. * Fetches a child by its number.
* *
* Returns: the child object or %NULL if not found (index too high). Unref * Returns: (transfer full): the child object or %NULL if not found (index
* after usage. * too high). Unref after usage.
* *
* MT safe. * MT safe.
*/ */
@ -156,8 +157,10 @@ gst_child_proxy_get_children_count (GstChildProxy * parent)
* gst_child_proxy_lookup: * gst_child_proxy_lookup:
* @object: object to lookup the property in * @object: object to lookup the property in
* @name: name of the property to look up * @name: name of the property to look up
* @target: pointer to a #GstObject that takes the real object to set property on * @target: (out) (allow-none) (transfer full): pointer to a #GstObject that
* @pspec: pointer to take the #GParamSpec describing the property * takes the real object to set property on
* @pspec: (out) (allow-none) (transfer full): pointer to take the #GParamSpec
* describing the property
* *
* Looks up which object and #GParamSpec would be effected by the given @name. * Looks up which object and #GParamSpec would be effected by the given @name.
* *
@ -223,7 +226,7 @@ gst_child_proxy_lookup (GstObject * object, const gchar * name,
* gst_child_proxy_get_property: * gst_child_proxy_get_property:
* @object: object to query * @object: object to query
* @name: name of the property * @name: name of the property
* @value: a #GValue that should take the result. * @value: (out caller-allocates): a #GValue that should take the result.
* *
* Gets a single property using the GstChildProxy mechanism. * Gets a single property using the GstChildProxy mechanism.
* You are responsible for for freeing it by calling g_value_unset() * You are responsible for for freeing it by calling g_value_unset()

33
gst/gstclock.c
View file

@ -254,7 +254,7 @@ gst_clock_single_shot_id_reinit (GstClock * clock, GstClockID id,
* *
* Increase the refcount of given @id. * Increase the refcount of given @id.
* *
* Returns: The same #GstClockID with increased refcount. * Returns: (transfer full): The same #GstClockID with increased refcount.
* *
* MT safe. * MT safe.
*/ */
@ -287,7 +287,7 @@ _gst_clock_id_free (GstClockID id)
/** /**
* gst_clock_id_unref: * gst_clock_id_unref:
* @id: The #GstClockID to unref * @id: (transfer full): The #GstClockID to unref
* *
* Unref given @id. When the refcount reaches 0 the * Unref given @id. When the refcount reaches 0 the
* #GstClockID will be freed. * #GstClockID will be freed.
@ -317,7 +317,10 @@ gst_clock_id_unref (GstClockID id)
* notification at the requested time. The single shot id should be * notification at the requested time. The single shot id should be
* unreffed after usage. * unreffed after usage.
* *
* Returns: A #GstClockID that can be used to request the time notification. * Free-function: gst_clock_id_unref
*
* Returns: (transfer full): a #GstClockID that can be used to request the
* time notification.
* *
* MT safe. * MT safe.
*/ */
@ -341,7 +344,10 @@ gst_clock_new_single_shot_id (GstClock * clock, GstClockTime time)
* will then be fired with the given @interval. @id should be unreffed * will then be fired with the given @interval. @id should be unreffed
* after usage. * after usage.
* *
* Returns: A #GstClockID that can be used to request the time notification. * Free-function: gst_clock_id_unref
*
* Returns: (transfer full): a #GstClockID that can be used to request the
* time notification.
* *
* MT safe. * MT safe.
*/ */
@ -408,7 +414,8 @@ gst_clock_id_get_time (GstClockID id)
/** /**
* gst_clock_id_wait * gst_clock_id_wait
* @id: The #GstClockID to wait on * @id: The #GstClockID to wait on
* @jitter: A pointer that will contain the jitter, can be %NULL. * @jitter (out) (allow-none): a pointer that will contain the jitter,
* can be %NULL.
* *
* Perform a blocking wait on @id. * Perform a blocking wait on @id.
* @id should have been created with gst_clock_new_single_shot_id() * @id should have been created with gst_clock_new_single_shot_id()
@ -1027,10 +1034,10 @@ gst_clock_set_calibration (GstClock * clock, GstClockTime internal, GstClockTime
/** /**
* gst_clock_get_calibration * gst_clock_get_calibration
* @clock: a #GstClock * @clock: a #GstClock
* @internal: a location to store the internal time * @internal: (out) (allow-none): a location to store the internal time
* @external: a location to store the external time * @external: (out) (allow-none): a location to store the external time
* @rate_num: a location to store the rate numerator * @rate_num: (out) (allow-none): a location to store the rate numerator
* @rate_denom: a location to store the rate denominator * @rate_denom: (out) (allow-none): a location to store the rate denominator
* *
* Gets the internal rate and reference time of @clock. See * Gets the internal rate and reference time of @clock. See
* gst_clock_set_calibration() for more information. * gst_clock_set_calibration() for more information.
@ -1088,7 +1095,7 @@ gst_clock_slave_callback (GstClock * master, GstClockTime time,
/** /**
* gst_clock_set_master * gst_clock_set_master
* @clock: a #GstClock * @clock: a #GstClock
* @master: a master #GstClock * @master: (allow-none): a master #GstClock
* *
* Set @master as the master clock for @clock. @clock will be automatically * Set @master as the master clock for @clock. @clock will be automatically
* calibrated so that gst_clock_get_time() reports the same time as the * calibrated so that gst_clock_get_time() reports the same time as the
@ -1166,8 +1173,8 @@ not_supported:
* Get the master clock that @clock is slaved to or %NULL when the clock is * Get the master clock that @clock is slaved to or %NULL when the clock is
* not slaved to any master clock. * not slaved to any master clock.
* *
* Returns: a master #GstClock or %NULL when this clock is not slaved to a * Returns: (transfer full): a master #GstClock or %NULL when this clock is
* master clock. Unref after usage. * not slaved to a master clock. Unref after usage.
* *
* MT safe. * MT safe.
*/ */
@ -1314,7 +1321,7 @@ invalid:
* @clock: a #GstClock * @clock: a #GstClock
* @slave: a time on the slave * @slave: a time on the slave
* @master: a time on the master * @master: a time on the master
* @r_squared: a pointer to hold the result * @r_squared: (out): a pointer to hold the result
* *
* The time @master of the master clock and the time @slave of the slave * The time @master of the master clock and the time @slave of the slave
* clock are added to the list of observations. If enough observations * clock are added to the list of observations. If enough observations

32
gst/gstdatetime.c
View file

@ -152,7 +152,9 @@
* Creates a new #GstDateTime using the time since Jan 1, 1970 specified by * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
* @secs. The #GstDateTime is in the local timezone. * @secs. The #GstDateTime is in the local timezone.
* *
* Return value: the newly created #GstDateTime * Free-function: gst_date_time_unref
*
* Return value: (transfer full): the newly created #GstDateTime
* *
* Since: 0.10.31 * Since: 0.10.31
*/ */
@ -164,7 +166,9 @@
* Creates a new #GstDateTime using the time since Jan 1, 1970 specified by * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
* @secs. The #GstDateTime is in the UTC timezone. * @secs. The #GstDateTime is in the UTC timezone.
* *
* Return value: the newly created #GstDateTime * Free-function: gst_date_time_unref
*
* Return value: (transfer full): the newly created #GstDateTime
* *
* Since: 0.10.31 * Since: 0.10.31
*/ */
@ -186,7 +190,9 @@
* 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59 and * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59 and
* @microsecond from 0 to 999999. * @microsecond from 0 to 999999.
* *
* Return value: the newly created #GstDateTime * Free-function: gst_date_time_unref
*
* Return value: (transfer full): the newly created #GstDateTime
* *
* Since: 0.10.31 * Since: 0.10.31
*/ */
@ -213,7 +219,9 @@
* some fractional timezones, while it still keeps the readability of * some fractional timezones, while it still keeps the readability of
* represeting it in hours for most timezones. * represeting it in hours for most timezones.
* *
* Return value: the newly created #GstDateTime * Free-function: gst_date_time_unref
*
* Return value: (transfer full): the newly created #GstDateTime
* *
* Since: 0.10.31 * Since: 0.10.31
*/ */
@ -223,8 +231,10 @@
* *
* Creates a new #GstDateTime representing the current date and time. * Creates a new #GstDateTime representing the current date and time.
* *
* Return value: the newly created #GstDateTime which should be freed with * Free-function: gst_date_time_unref
* gst_date_time_unref(). *
* Return value: (transfer full): the newly created #GstDateTime which should
* be freed with gst_date_time_unref().
* *
* Since: 0.10.31 * Since: 0.10.31
*/ */
@ -235,8 +245,10 @@
* Creates a new #GstDateTime that represents the current instant at Universal * Creates a new #GstDateTime that represents the current instant at Universal
* coordinated time. * coordinated time.
* *
* Return value: the newly created #GstDateTime which should be freed with * Free-function: gst_date_time_unref
* gst_date_time_unref(). *
* Return value: (transfer full): the newly created #GstDateTime which should
* be freed with gst_date_time_unref().
* *
* Since: 0.10.31 * Since: 0.10.31
*/ */
@ -767,7 +779,7 @@ gst_date_time_free (GstDateTime * datetime)
* *
* Atomically increments the reference count of @datetime by one. * Atomically increments the reference count of @datetime by one.
* *
* Return value: the reference @datetime * Return value: (transfer full): the reference @datetime
* *
* Since: 0.10.31 * Since: 0.10.31
*/ */
@ -782,7 +794,7 @@ gst_date_time_ref (GstDateTime * datetime)
/** /**
* gst_date_time_unref: * gst_date_time_unref:
* @datetime: a #GstDateTime * @datetime: (transfer full): a #GstDateTime
* *
* Atomically decrements the reference count of @datetime by one. When the * Atomically decrements the reference count of @datetime by one. When the
* reference count reaches zero, the structure is freed. * reference count reaches zero, the structure is freed.

67
gst/gstelement.c
View file

@ -630,7 +630,7 @@ gst_element_is_indexable (GstElement * element)
/** /**
* gst_element_set_index: * gst_element_set_index:
* @element: a #GstElement. * @element: a #GstElement.
* @index: a #GstIndex. * @index: (transfer none): a #GstIndex.
* *
* Set @index on the element. The refcount of the index * Set @index on the element. The refcount of the index
* will be increased, any previously set index is unreffed. * will be increased, any previously set index is unreffed.
@ -657,7 +657,7 @@ gst_element_set_index (GstElement * element, GstIndex * index)
* *
* Gets the index from the element. * Gets the index from the element.
* *
* Returns: a #GstIndex or %NULL when no index was set on the * Returns: (transfer full): a #GstIndex or %NULL when no index was set on the
* element. unref after usage. * element. unref after usage.
* *
* MT safe. * MT safe.
@ -681,7 +681,7 @@ gst_element_get_index (GstElement * element)
/** /**
* gst_element_add_pad: * gst_element_add_pad:
* @element: a #GstElement to add the pad to. * @element: a #GstElement to add the pad to.
* @pad: the #GstPad to add to the element. * @pad: (transfer full): the #GstPad to add to the element.
* *
* Adds a pad (link point) to @element. @pad's parent will be set to @element; * Adds a pad (link point) to @element. @pad's parent will be set to @element;
* see gst_object_set_parent() for refcounting information. * see gst_object_set_parent() for refcounting information.
@ -797,7 +797,7 @@ no_direction:
/** /**
* gst_element_remove_pad: * gst_element_remove_pad:
* @element: a #GstElement to remove pad from. * @element: a #GstElement to remove pad from.
* @pad: the #GstPad to remove from the element. * @pad: (transfer none): the #GstPad to remove from the element.
* *
* Removes @pad from @element. @pad will be destroyed if it has not been * Removes @pad from @element. @pad will be destroyed if it has not been
* referenced elsewhere using gst_object_unparent(). * referenced elsewhere using gst_object_unparent().
@ -933,8 +933,8 @@ pad_compare_name (GstPad * pad1, const gchar * name)
* Retrieves a pad from @element by name. This version only retrieves * Retrieves a pad from @element by name. This version only retrieves
* already-existing (i.e. 'static') pads. * already-existing (i.e. 'static') pads.
* *
* Returns: the requested #GstPad if found, otherwise %NULL. unref after * Returns: (transfer full): the requested #GstPad if found, otherwise %NULL.
* usage. * unref after usage.
* *
* MT safe. * MT safe.
*/ */
@ -994,7 +994,8 @@ gst_element_request_pad (GstElement * element, GstPadTemplate * templ,
* request pads. The pad should be released with * request pads. The pad should be released with
* gst_element_release_request_pad(). * gst_element_release_request_pad().
* *
* Returns: requested #GstPad if found, otherwise %NULL. Release after usage. * Returns: (transfer full): requested #GstPad if found, otherwise %NULL.
* Release after usage.
*/ */
GstPad * GstPad *
gst_element_get_request_pad (GstElement * element, const gchar * name) gst_element_get_request_pad (GstElement * element, const gchar * name)
@ -1141,7 +1142,8 @@ gst_element_iterate_pad_list (GstElement * element, GList ** padlist)
* Retrieves an iterattor of @element's pads. The iterator should * Retrieves an iterattor of @element's pads. The iterator should
* be freed after usage. * be freed after usage.
* *
* Returns: the #GstIterator of #GstPad. Unref each pad after use. * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
* after use.
* *
* MT safe. * MT safe.
*/ */
@ -1159,7 +1161,8 @@ gst_element_iterate_pads (GstElement * element)
* *
* Retrieves an iterator of @element's source pads. * Retrieves an iterator of @element's source pads.
* *
* Returns: the #GstIterator of #GstPad. Unref each pad after use. * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
* after use.
* *
* MT safe. * MT safe.
*/ */
@ -1177,7 +1180,8 @@ gst_element_iterate_src_pads (GstElement * element)
* *
* Retrieves an iterator of @element's sink pads. * Retrieves an iterator of @element's sink pads.
* *
* Returns: the #GstIterator of #GstPad. Unref each pad after use. * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad
* after use.
* *
* MT safe. * MT safe.
*/ */
@ -1192,7 +1196,7 @@ gst_element_iterate_sink_pads (GstElement * element)
/** /**
* gst_element_class_add_pad_template: * gst_element_class_add_pad_template:
* @klass: the #GstElementClass to add the pad template to. * @klass: the #GstElementClass to add the pad template to.
* @templ: a #GstPadTemplate to add to the element class. * @templ: (transfer none): a #GstPadTemplate to add to the element class.
* *
* Adds a padtemplate to an element class. This is mainly used in the _base_init * Adds a padtemplate to an element class. This is mainly used in the _base_init
* functions of classes. * functions of classes.
@ -1345,7 +1349,8 @@ gst_element_class_set_details_simple (GstElementClass * klass,
* that has subclasses, make sure to pass the g_class parameter of the * that has subclasses, make sure to pass the g_class parameter of the
* #GInstanceInitFunc here.</note> * #GInstanceInitFunc here.</note>
* *
* Returns: the #GList of padtemplates. * Returns: (transfer none) (element-type Gst.PadTemplate): the #GList of
* pad templates.
*/ */
GList * GList *
gst_element_class_get_pad_template_list (GstElementClass * element_class) gst_element_class_get_pad_template_list (GstElementClass * element_class)
@ -1365,8 +1370,8 @@ gst_element_class_get_pad_template_list (GstElementClass * element_class)
* that has subclasses, make sure to pass the g_class parameter of the * that has subclasses, make sure to pass the g_class parameter of the
* #GInstanceInitFunc here.</note> * #GInstanceInitFunc here.</note>
* *
* Returns: the #GstPadTemplate with the given name, or %NULL if none was found. * Returns: (transfer none): the #GstPadTemplate with the given name, or %NULL
* No unreferencing is necessary. * if none was found. No unreferencing is necessary.
*/ */
GstPadTemplate * GstPadTemplate *
gst_element_class_get_pad_template (GstElementClass * element_class, gst_element_class_get_pad_template (GstElementClass * element_class,
@ -1495,7 +1500,7 @@ gst_element_default_send_event (GstElement * element, GstEvent * event)
/** /**
* gst_element_send_event: * gst_element_send_event:
* @element: a #GstElement to send the event to. * @element: a #GstElement to send the event to.
* @event: the #GstEvent to send to the element. * @event: (transfer full): the #GstEvent to send to the element.
* *
* Sends an event to an element. If the element doesn't implement an * Sends an event to an element. If the element doesn't implement an
* event handler, the event will be pushed on a random linked sink pad for * event handler, the event will be pushed on a random linked sink pad for
@ -1640,7 +1645,7 @@ gst_element_default_query (GstElement * element, GstQuery * query)
/** /**
* gst_element_query: * gst_element_query:
* @element: a #GstElement to perform the query on. * @element: a #GstElement to perform the query on.
* @query: the #GstQuery. * @query: (transfer none): the #GstQuery.
* *
* Performs a query on the given element. * Performs a query on the given element.
* *
@ -1678,7 +1683,7 @@ gst_element_query (GstElement * element, GstQuery * query)
/** /**
* gst_element_post_message: * gst_element_post_message:
* @element: a #GstElement posting the message * @element: a #GstElement posting the message
* @message: a #GstMessage to post * @message: (transfer full): a #GstMessage to post
* *
* Post a message on the element's #GstBus. This function takes ownership of the * Post a message on the element's #GstBus. This function takes ownership of the
* message; if you want to access the message after this call, you should add an * message; if you want to access the message after this call, you should add an
@ -1731,7 +1736,8 @@ no_bus:
* *
* This function is only used internally by the gst_element_error() macro. * This function is only used internally by the gst_element_error() macro.
* *
* Returns: a newly allocated string, or %NULL if the format was %NULL or "" * Returns: (transfer full): a newly allocated string, or %NULL if the format
* was %NULL or ""
* *
* MT safe. * MT safe.
*/ */
@ -1758,10 +1764,12 @@ _gst_element_error_printf (const gchar * format, ...)
* @type: the #GstMessageType * @type: the #GstMessageType
* @domain: the GStreamer GError domain this message belongs to * @domain: the GStreamer GError domain this message belongs to
* @code: the GError code belonging to the domain * @code: the GError code belonging to the domain
* @text: an allocated text string to be used as a replacement for the * @text: (allow-none) (transfer full): an allocated text string to be used
* default message connected to code, or %NULL * as a replacement for the default message connected to code,
* @debug: an allocated debug message to be used as a replacement for the * or %NULL
* default debugging information, or %NULL * @debug: (allow-none) (transfer full): an allocated debug message to be
* used as a replacement for the default debugging information,
* or %NULL
* @file: the source code file where the error was generated * @file: the source code file where the error was generated
* @function: the source code function where the error was generated * @function: the source code function where the error was generated
* @line: the source code line where the error was generated * @line: the source code line where the error was generated
@ -2100,9 +2108,10 @@ interrupted:
/** /**
* gst_element_get_state: * gst_element_get_state:
* @element: a #GstElement to get the state of. * @element: a #GstElement to get the state of.
* @state: (out): a pointer to #GstState to hold the state. Can be %NULL. * @state: (out) (allow-none): a pointer to #GstState to hold the state.
* @pending: (out): a pointer to #GstState to hold the pending state. * Can be %NULL.
* Can be %NULL. * @pending: (out) (allow-none): a pointer to #GstState to hold the pending
* state. Can be %NULL.
* @timeout: a #GstClockTime to specify the timeout for an async * @timeout: a #GstClockTime to specify the timeout for an async
* state change or %GST_CLOCK_TIME_NONE for infinite timeout. * state change or %GST_CLOCK_TIME_NONE for infinite timeout.
* *
@ -2888,8 +2897,8 @@ was_ok:
* *
* Retrieves the factory that was used to create this element. * Retrieves the factory that was used to create this element.
* *
* Returns: the #GstElementFactory used for creating this element. * Returns: (transfer none): the #GstElementFactory used for creating this
* no refcounting is needed. * element. no refcounting is needed.
*/ */
GstElementFactory * GstElementFactory *
gst_element_get_factory (GstElement * element) gst_element_get_factory (GstElement * element)
@ -3137,7 +3146,7 @@ gst_element_set_bus_func (GstElement * element, GstBus * bus)
/** /**
* gst_element_set_bus: * gst_element_set_bus:
* @element: a #GstElement to set the bus of. * @element: a #GstElement to set the bus of.
* @bus: the #GstBus to set. * @bus: (transfer none): the #GstBus to set.
* *
* Sets the bus of the element. Increases the refcount on the bus. * Sets the bus of the element. Increases the refcount on the bus.
* For internal use only, unless you're testing elements. * For internal use only, unless you're testing elements.
@ -3164,7 +3173,7 @@ gst_element_set_bus (GstElement * element, GstBus * bus)
* Returns the bus of the element. Note that only a #GstPipeline will provide a * Returns the bus of the element. Note that only a #GstPipeline will provide a
* bus for the application. * bus for the application.
* *
* Returns: the element's #GstBus. unref after usage. * Returns: (transfer full): the element's #GstBus. unref after usage.
* *
* MT safe. * MT safe.
*/ */

4
gst/gstelement.h
View file

@ -696,7 +696,7 @@ GType gst_element_get_type (void);
* For a nameless element, this returns NULL, which you can safely g_free() * For a nameless element, this returns NULL, which you can safely g_free()
* as well. * as well.
* *
* Returns: the name of @elem. g_free() after usage. MT safe. * Returns: (transfer full): the name of @elem. g_free() after usage. MT safe.
* *
*/ */
#define gst_element_get_name(elem) gst_object_get_name(GST_OBJECT_CAST(elem)) #define gst_element_get_name(elem) gst_object_get_name(GST_OBJECT_CAST(elem))
@ -714,7 +714,7 @@ GType gst_element_get_type (void);
* gst_element_get_parent: * gst_element_get_parent:
* @elem: a #GstElement to get the parent of. * @elem: a #GstElement to get the parent of.
* *
* Gets the parent of an element. * Returns: (transfer full): the parent of an element.
*/ */
#define gst_element_get_parent(elem) gst_object_get_parent(GST_OBJECT_CAST(elem)) #define gst_element_get_parent(elem) gst_object_get_parent(GST_OBJECT_CAST(elem))

31
gst/gstelementfactory.c
View file

@ -125,7 +125,7 @@ gst_element_factory_finalize (GObject * object)
* Search for an element factory of the given name. Refs the returned * Search for an element factory of the given name. Refs the returned
* element factory; caller is responsible for unreffing. * element factory; caller is responsible for unreffing.
* *
* Returns: #GstElementFactory if found, NULL otherwise * Returns: (transfer full): #GstElementFactory if found, NULL otherwise
*/ */
GstElementFactory * GstElementFactory *
gst_element_factory_find (const gchar * name) gst_element_factory_find (const gchar * name)
@ -193,8 +193,9 @@ gst_element_factory_cleanup (GstElementFactory * factory)
/** /**
* gst_element_register: * gst_element_register:
* @plugin: #GstPlugin to register the element with, or NULL for a static * @plugin: (allow-none): #GstPlugin to register the element with, or NULL for
* element (note that passing NULL only works in GStreamer 0.10.13 and later) * a static element (note that passing NULL only works in GStreamer 0.10.13
* and later)
* @name: name of elements of this type * @name: name of elements of this type
* @rank: rank of element (higher rank means more importance when autoplugging) * @rank: rank of element (higher rank means more importance when autoplugging)
* @type: GType of element to register * @type: GType of element to register
@ -342,7 +343,8 @@ detailserror:
* It will be given the name supplied, since all elements require a name as * It will be given the name supplied, since all elements require a name as
* their first argument. * their first argument.
* *
* Returns: new #GstElement or NULL if the element couldn't be created * Returns: (transfer full): new #GstElement or NULL if the element couldn't
* be created
*/ */
GstElement * GstElement *
gst_element_factory_create (GstElementFactory * factory, const gchar * name) gst_element_factory_create (GstElementFactory * factory, const gchar * name)
@ -427,7 +429,7 @@ no_element:
* consisting of the element factory name and a number. * consisting of the element factory name and a number.
* If name is given, it will be given the name supplied. * If name is given, it will be given the name supplied.
* *
* Returns: new #GstElement or NULL if unable to create element * Returns: (transfer full): new #GstElement or NULL if unable to create element
*/ */
GstElement * GstElement *
gst_element_factory_make (const gchar * factoryname, const gchar * name) gst_element_factory_make (const gchar * factoryname, const gchar * name)
@ -650,7 +652,8 @@ __gst_element_factory_add_interface (GstElementFactory * elementfactory,
* *
* Gets the #GList of #GstStaticPadTemplate for this factory. * Gets the #GList of #GstStaticPadTemplate for this factory.
* *
* Returns: the padtemplates * Returns: (transfer none) (element-type Gst.StaticPadTemplate): the
* static pad templates
*/ */
G_CONST_RETURN GList * G_CONST_RETURN GList *
gst_element_factory_get_static_pad_templates (GstElementFactory * factory) gst_element_factory_get_static_pad_templates (GstElementFactory * factory)
@ -685,7 +688,8 @@ gst_element_factory_get_uri_type (GstElementFactory * factory)
* array, as it is still owned by the element factory. Use g_strdupv() to * array, as it is still owned by the element factory. Use g_strdupv() to
* make a copy of the protocol string array if you need to. * make a copy of the protocol string array if you need to.
* *
* Returns: the supported protocols or NULL * Returns: (transfer none) (array zero-terminated=1): the supported protocols
* or NULL
*/ */
gchar ** gchar **
gst_element_factory_get_uri_protocols (GstElementFactory * factory) gst_element_factory_get_uri_protocols (GstElementFactory * factory)
@ -826,8 +830,9 @@ element_filter (GstPluginFeature * feature, FilterData * data)
* with a rank greater or equal to @minrank will be returned. * with a rank greater or equal to @minrank will be returned.
* The list of factories is returned by decreasing rank. * The list of factories is returned by decreasing rank.
* *
* Returns: a #GList of #GstElementFactory elements. Use * Returns: (transfer full) (element-type Gst.ElementFactory): a #GList of
* gst_plugin_feature_list_free() after usage. * #GstElementFactory elements. Use gst_plugin_feature_list_free() after
* usage.
* *
* Since: 0.10.31 * Since: 0.10.31
*/ */
@ -854,7 +859,8 @@ gst_element_factory_list_get_elements (GstElementFactoryListType type,
/** /**
* gst_element_factory_list_filter: * gst_element_factory_list_filter:
* @list: a #GList of #GstElementFactory to filter * @list: (transfer none) (element-type Gst.ElementFactory): a #GList of
* #GstElementFactory to filter
* @caps: a #GstCaps * @caps: a #GstCaps
* @direction: a #GstPadDirection to filter on * @direction: a #GstPadDirection to filter on
* @subsetonly: whether to filter on caps subsets or not. * @subsetonly: whether to filter on caps subsets or not.
@ -866,8 +872,9 @@ gst_element_factory_list_get_elements (GstElementFactoryListType type,
* are a complete superset of @caps will be returned. Else any element * are a complete superset of @caps will be returned. Else any element
* whose pad templates caps can intersect with @caps will be returned. * whose pad templates caps can intersect with @caps will be returned.
* *
* Returns: a #GList of #GstElementFactory elements that match the * Returns: (transfer full) (element-type Gst.ElementFactory): a #GList of
* given requisits. Use #gst_plugin_feature_list_free after usage. * #GstElementFactory elements that match the given requisits.
* Use #gst_plugin_feature_list_free after usage.
* *
* Since: 0.10.31 * Since: 0.10.31
*/ */

4
gst/gsterror.c
View file

@ -300,8 +300,8 @@ QUARK_FUNC (stream);
* *
* Get a string describing the error message in the current locale. * Get a string describing the error message in the current locale.
* *
* Returns: a newly allocated string describing the error message in the * Returns: (transfer full) (type gchar*): a newly allocated string describing
* current locale. * the error message in the current locale.
*/ */
gchar * gchar *
gst_error_get_message (GQuark domain, gint code) gst_error_get_message (GQuark domain, gint code)

53
gst/gstevent.c
View file

@ -279,8 +279,8 @@ gst_event_new (GstEventType type)
/** /**
* gst_event_new_custom: * gst_event_new_custom:
* @type: The type of the new event * @type: The type of the new event
* @structure: The structure for the event. The event will take ownership of * @structure: (transfer full): the structure for the event. The event will
* the structure. * take ownership of the structure.
* *
* Create a new custom-typed event. This can be used for anything not * Create a new custom-typed event. This can be used for anything not
* handled by other event-specific functions to pass an event to another * handled by other event-specific functions to pass an event to another
@ -293,7 +293,7 @@ gst_event_new (GstEventType type)
* New custom events can also be created by subclassing the event type if * New custom events can also be created by subclassing the event type if
* needed. * needed.
* *
* Returns: The new custom event. * Returns: (transfer full): the new custom event.
*/ */
GstEvent * GstEvent *
gst_event_new_custom (GstEventType type, GstStructure * structure) gst_event_new_custom (GstEventType type, GstStructure * structure)
@ -431,7 +431,7 @@ gst_event_set_seqnum (GstEvent * event, guint32 seqnum)
* This event is typically generated after a seek to flush out all queued data * This event is typically generated after a seek to flush out all queued data
* in the pipeline so that the new media is played as soon as possible. * in the pipeline so that the new media is played as soon as possible.
* *
* Returns: A new flush start event. * Returns: (transfer full): a new flush start event.
*/ */
GstEvent * GstEvent *
gst_event_new_flush_start (void) gst_event_new_flush_start (void)
@ -453,7 +453,7 @@ gst_event_new_flush_start (void)
* This event is typically generated to complete a seek and to resume * This event is typically generated to complete a seek and to resume
* dataflow. * dataflow.
* *
* Returns: A new flush stop event. * Returns: (transfer full): a new flush stop event.
*/ */
GstEvent * GstEvent *
gst_event_new_flush_stop (void) gst_event_new_flush_stop (void)
@ -478,7 +478,7 @@ gst_event_new_flush_stop (void)
* *
* The EOS event itself will not cause any state transitions of the pipeline. * The EOS event itself will not cause any state transitions of the pipeline.
* *
* Returns: The new EOS event. * Returns: (transfer full): the new EOS event.
*/ */
GstEvent * GstEvent *
gst_event_new_eos (void) gst_event_new_eos (void)
@ -500,7 +500,7 @@ gst_event_new_eos (void)
* This method calls gst_event_new_new_segment_full() passing a default * This method calls gst_event_new_new_segment_full() passing a default
* value of 1.0 for applied_rate * value of 1.0 for applied_rate
* *
* Returns: A new newsegment event. * Returns: (transfer full): a new newsegment event.
*/ */
GstEvent * GstEvent *
gst_event_new_new_segment (gboolean update, gdouble rate, GstFormat format, gst_event_new_new_segment (gboolean update, gdouble rate, GstFormat format,
@ -575,7 +575,7 @@ gst_event_parse_new_segment (GstEvent * event, gboolean * update,
* *
* position + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate) * position + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate)
* *
* Returns: A new newsegment event. * Returns: (transfer full): a new newsegment event.
* *
* Since: 0.10.6 * Since: 0.10.6
*/ */
@ -687,7 +687,7 @@ gst_event_parse_new_segment_full (GstEvent * event, gboolean * update,
* *
* Generates a metadata tag event from the given @taglist. * Generates a metadata tag event from the given @taglist.
* *
* Returns: a new #GstEvent * Returns: (transfer full): a new #GstEvent
*/ */
GstEvent * GstEvent *
gst_event_new_tag (GstTagList * taglist) gst_event_new_tag (GstTagList * taglist)
@ -700,7 +700,7 @@ gst_event_new_tag (GstTagList * taglist)
/** /**
* gst_event_parse_tag: * gst_event_parse_tag:
* @event: a tag event * @event: a tag event
* @taglist: (out): pointer to metadata list * @taglist: (out) (transfer none): pointer to metadata list
* *
* Parses a tag @event and stores the results in the given @taglist location. * Parses a tag @event and stores the results in the given @taglist location.
*/ */
@ -727,7 +727,7 @@ gst_event_parse_tag (GstEvent * event, GstTagList ** taglist)
* *
* When the @async flag is set, a thread boundary is prefered. * When the @async flag is set, a thread boundary is prefered.
* *
* Returns: a new #GstEvent * Returns: (transfer full): a new #GstEvent
*/ */
GstEvent * GstEvent *
gst_event_new_buffer_size (GstFormat format, gint64 minsize, gst_event_new_buffer_size (GstFormat format, gint64 minsize,
@ -829,7 +829,7 @@ gst_event_parse_buffer_size (GstEvent * event, GstFormat * format,
* The application can use general event probes to intercept the QoS * The application can use general event probes to intercept the QoS
* event and implement custom application specific QoS handling. * event and implement custom application specific QoS handling.
* *
* Returns: A new QOS event. * Returns: (transfer full): a new QOS event.
*/ */
GstEvent * GstEvent *
gst_event_new_qos (gdouble proportion, GstClockTimeDiff diff, gst_event_new_qos (gdouble proportion, GstClockTimeDiff diff,
@ -931,7 +931,7 @@ gst_event_parse_qos (GstEvent * event, gdouble * proportion,
* #GST_QUERY_POSITION and update the playback segment current position with a * #GST_QUERY_POSITION and update the playback segment current position with a
* #GST_SEEK_TYPE_SET to the desired position. * #GST_SEEK_TYPE_SET to the desired position.
* *
* Returns: A new seek event. * Returns: (transfer full): a new seek event.
*/ */
GstEvent * GstEvent *
gst_event_new_seek (gdouble rate, GstFormat format, GstSeekFlags flags, gst_event_new_seek (gdouble rate, GstFormat format, GstSeekFlags flags,
@ -1027,12 +1027,12 @@ gst_event_parse_seek (GstEvent * event, gdouble * rate,
/** /**
* gst_event_new_navigation: * gst_event_new_navigation:
* @structure: description of the event. The event will take ownership of the * @structure: (transfer full): description of the event. The event will take
* structure. * ownership of the structure.
* *
* Create a new navigation event from the given description. * Create a new navigation event from the given description.
* *
* Returns: a new #GstEvent * Returns: (transfer full): a new #GstEvent
*/ */
GstEvent * GstEvent *
gst_event_new_navigation (GstStructure * structure) gst_event_new_navigation (GstStructure * structure)
@ -1053,7 +1053,7 @@ gst_event_new_navigation (GstStructure * structure)
* The latency is mostly used in live sinks and is always expressed in * The latency is mostly used in live sinks and is always expressed in
* the time format. * the time format.
* *
* Returns: a new #GstEvent * Returns: (transfer full): a new #GstEvent
* *
* Since: 0.10.12 * Since: 0.10.12
*/ */
@ -1115,7 +1115,7 @@ gst_event_parse_latency (GstEvent * event, GstClockTime * latency)
* The @intermediate flag instructs the pipeline that this step operation is * The @intermediate flag instructs the pipeline that this step operation is
* part of a larger step operation. * part of a larger step operation.
* *
* Returns: a new #GstEvent * Returns: (transfer full): a new #GstEvent
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -1144,11 +1144,12 @@ gst_event_new_step (GstFormat format, guint64 amount, gdouble rate,
/** /**
* gst_event_parse_step: * gst_event_parse_step:
* @event: The event to query * @event: The event to query
* @format: (out): A pointer to store the format in. * @format: (out) (allow-none): a pointer to store the format in
* @amount: (out): A pointer to store the amount in. * @amount: (out) (allow-none): a pointer to store the amount in
* @rate: (out): A pointer to store the rate in. * @rate: (out) (allow-none): a pointer to store the rate in
* @flush: (out): A pointer to store the flush boolean in. * @flush: (out) (allow-none): a pointer to store the flush boolean in
* @intermediate: (out): A pointer to store the intermediate boolean in. * @intermediate: (out) (allow-none): a pointer to store the intermediate
* boolean in
* *
* Parse the step event. * Parse the step event.
* *
@ -1183,13 +1184,13 @@ gst_event_parse_step (GstEvent * event, GstFormat * format, guint64 * amount,
/** /**
* gst_event_new_sink_message: * gst_event_new_sink_message:
* @msg: The #GstMessage to be posted * @msg: (transfer none): the #GstMessage to be posted
* *
* Create a new sink-message event. The purpose of the sink-message event is * Create a new sink-message event. The purpose of the sink-message event is
* to instruct a sink to post the message contained in the event synchronized * to instruct a sink to post the message contained in the event synchronized
* with the stream. * with the stream.
* *
* Returns: a new #GstEvent * Returns: (transfer full): a new #GstEvent
* *
* Since: 0.10.26 * Since: 0.10.26
*/ */
@ -1213,7 +1214,7 @@ gst_event_new_sink_message (GstMessage * msg)
/** /**
* gst_event_parse_sink_message: * gst_event_parse_sink_message:
* @event: The event to query * @event: The event to query
* @msg: (out): A pointer to store the #GstMessage in. * @msg: (out) (transfer full): a pointer to store the #GstMessage in.
* *
* Parse the sink-message event. Unref @msg after usage. * Parse the sink-message event. Unref @msg after usage.
* *

13
gst/gstevent.h
View file

@ -224,9 +224,10 @@ typedef struct _GstEventClass GstEventClass;
/** /**
* gst_event_replace: * gst_event_replace:
* @old_event: pointer to a pointer to a #GstEvent to be replaced. * @old_event: (inout) (transfer full): pointer to a pointer to a #GstEvent
* @new_event: pointer to a #GstEvent that will replace the event pointed to * to be replaced.
* by @old_event. * @new_event: (allow-none) (transfer none): pointer to a #GstEvent that will
* replace the event pointed to by @old_event.
* *
* Modifies a pointer to a #GstEvent to point to a different #GstEvent. The * Modifies a pointer to a #GstEvent to point to a different #GstEvent. The
* modification is done atomically (so this is useful for ensuring thread safety * modification is done atomically (so this is useful for ensuring thread safety
@ -356,7 +357,7 @@ GType gst_event_get_type (void);
* *
* Increase the refcount of this event. * Increase the refcount of this event.
* *
* Returns: @event (for convenience when doing assignments) * Returns: (transfer full): @event (for convenience when doing assignments)
*/ */
#ifdef _FOOL_GTK_DOC_ #ifdef _FOOL_GTK_DOC_
G_INLINE_FUNC GstEvent * gst_event_ref (GstEvent * event); G_INLINE_FUNC GstEvent * gst_event_ref (GstEvent * event);
@ -370,7 +371,7 @@ gst_event_ref (GstEvent * event)
/** /**
* gst_event_unref: * gst_event_unref:
* @event: The event to refcount * @event: (transfer full): the event to refcount
* *
* Decrease the refcount of an event, freeing it if the refcount reaches 0. * Decrease the refcount of an event, freeing it if the refcount reaches 0.
*/ */
@ -391,7 +392,7 @@ gst_event_unref (GstEvent * event)
* *
* Copy the event using the event specific copy function. * Copy the event using the event specific copy function.
* *
* Returns: the new event * Returns: (transfer full): the new event
*/ */
#ifdef _FOOL_GTK_DOC_ #ifdef _FOOL_GTK_DOC_
G_INLINE_FUNC GstEvent * gst_event_copy (const GstEvent * event); G_INLINE_FUNC GstEvent * gst_event_copy (const GstEvent * event);

6
gst/gstfilter.c
View file

@ -56,9 +56,9 @@
* @data wil be made in any other way when prepending @data to the list of * @data wil be made in any other way when prepending @data to the list of
* results. * results.
* *
* Returns: the list of results. Free with g_list_free() when no longer needed * Returns: (transfer container): the list of results. Free with g_list_free()
* (the data contained in the list is a flat copy and does need to be * when no longer needed (the data contained in the list is a flat copy
* unreferenced or freed). * and does need to be unreferenced or freed).
*/ */
GList * GList *
gst_filter_run (const GList * list, GstFilterFunc func, gboolean first, gst_filter_run (const GList * list, GstFilterFunc func, gboolean first,

2
gst/gstfilter.h
View file

@ -29,7 +29,7 @@ G_BEGIN_DECLS
* @obj: the object * @obj: the object
* @user_data: filter data * @user_data: filter data
* *
* Function prototype for a filter callback taht can be use in gst_filter_run(). * Function prototype for a filter callback that can be use in gst_filter_run().
* The function should apply its filtering to @obj. Additional data passed to * The function should apply its filtering to @obj. Additional data passed to
* gst_filter_run() are in @data. * gst_filter_run() are in @data.
* *

2
gst/gstformat.c
View file

@ -247,7 +247,7 @@ gst_format_get_details (GstFormat format)
* Iterate all the registered formats. The format definition is read * Iterate all the registered formats. The format definition is read
* only. * only.
* *
* Returns: A GstIterator of #GstFormatDefinition. * Returns: (transfer full): a GstIterator of #GstFormatDefinition.
*/ */
GstIterator * GstIterator *
gst_format_iterate_definitions (void) gst_format_iterate_definitions (void)

32
gst/gstghostpad.c
View file

@ -1023,7 +1023,7 @@ construct_failed:
/** /**
* gst_ghost_pad_new_no_target: * gst_ghost_pad_new_no_target:
* @name: the name of the new pad, or NULL to assign a default name. * @name: (allow-none): the name of the new pad, or NULL to assign a default name.
* @dir: the direction of the ghostpad * @dir: the direction of the ghostpad
* *
* Create a new ghostpad without a target with the given direction. * Create a new ghostpad without a target with the given direction.
@ -1032,7 +1032,7 @@ construct_failed:
* *
* The created ghostpad will not have a padtemplate. * The created ghostpad will not have a padtemplate.
* *
* Returns: a new #GstPad, or NULL in case of an error. * Returns: (transfer full): a new #GstPad, or NULL in case of an error.
*/ */
GstPad * GstPad *
gst_ghost_pad_new_no_target (const gchar * name, GstPadDirection dir) gst_ghost_pad_new_no_target (const gchar * name, GstPadDirection dir)
@ -1050,15 +1050,15 @@ gst_ghost_pad_new_no_target (const gchar * name, GstPadDirection dir)
/** /**
* gst_ghost_pad_new: * gst_ghost_pad_new:
* @name: the name of the new pad, or NULL to assign a default name. * @name: (allow-none): the name of the new pad, or NULL to assign a default name
* @target: the pad to ghost. * @target: (transfer none): the pad to ghost.
* *
* Create a new ghostpad with @target as the target. The direction will be taken * Create a new ghostpad with @target as the target. The direction will be taken
* from the target pad. @target must be unlinked. * from the target pad. @target must be unlinked.
* *
* Will ref the target. * Will ref the target.
* *
* Returns: a new #GstPad, or NULL in case of an error. * Returns: (transfer full): a new #GstPad, or NULL in case of an error.
*/ */
GstPad * GstPad *
gst_ghost_pad_new (const gchar * name, GstPad * target) gst_ghost_pad_new (const gchar * name, GstPad * target)
@ -1089,16 +1089,16 @@ set_target_failed:
/** /**
* gst_ghost_pad_new_from_template: * gst_ghost_pad_new_from_template:
* @name: the name of the new pad, or NULL to assign a default name. * @name: (allow-none): the name of the new pad, or NULL to assign a default name.
* @target: the pad to ghost. * @target: (transfer none): the pad to ghost.
* @templ: the #GstPadTemplate to use on the ghostpad. * @templ: (transfer none): the #GstPadTemplate to use on the ghostpad.
* *
* Create a new ghostpad with @target as the target. The direction will be taken * Create a new ghostpad with @target as the target. The direction will be taken
* from the target pad. The template used on the ghostpad will be @template. * from the target pad. The template used on the ghostpad will be @template.
* *
* Will ref the target. * Will ref the target.
* *
* Returns: a new #GstPad, or NULL in case of an error. * Returns: (transfer full): a new #GstPad, or NULL in case of an error.
* *
* Since: 0.10.10 * Since: 0.10.10
*/ */
@ -1136,13 +1136,13 @@ set_target_failed:
/** /**
* gst_ghost_pad_new_no_target_from_template: * gst_ghost_pad_new_no_target_from_template:
* @name: the name of the new pad, or NULL to assign a default name. * @name: (allow-none): the name of the new pad, or NULL to assign a default name
* @templ: the #GstPadTemplate to create the ghostpad from. * @templ: (transfer none): the #GstPadTemplate to create the ghostpad from.
* *
* Create a new ghostpad based on @templ, without setting a target. The * Create a new ghostpad based on @templ, without setting a target. The
* direction will be taken from the @templ. * direction will be taken from the @templ.
* *
* Returns: a new #GstPad, or NULL in case of an error. * Returns: (transfer full): a new #GstPad, or NULL in case of an error.
* *
* Since: 0.10.10 * Since: 0.10.10
*/ */
@ -1166,7 +1166,7 @@ gst_ghost_pad_new_no_target_from_template (const gchar * name,
* *
* Get the target pad of @gpad. Unref target pad after usage. * Get the target pad of @gpad. Unref target pad after usage.
* *
* Returns: the target #GstPad, can be NULL if the ghostpad * Returns: (transfer full): the target #GstPad, can be NULL if the ghostpad
* has no target set. Unref target pad after usage. * has no target set. Unref target pad after usage.
*/ */
GstPad * GstPad *
@ -1186,14 +1186,14 @@ gst_ghost_pad_get_target (GstGhostPad * gpad)
/** /**
* gst_ghost_pad_set_target: * gst_ghost_pad_set_target:
* @gpad: the #GstGhostPad * @gpad: the #GstGhostPad
* @newtarget: the new pad target * @newtarget: (transfer none) (allow-none): the new pad target
* *
* Set the new target of the ghostpad @gpad. Any existing target * Set the new target of the ghostpad @gpad. Any existing target
* is unlinked and links to the new target are established. if @newtarget is * is unlinked and links to the new target are established. if @newtarget is
* NULL the target will be cleared. * NULL the target will be cleared.
* *
* Returns: TRUE if the new target could be set. This function can return FALSE * Returns: (transfer full): TRUE if the new target could be set. This function
* when the internal pads could not be linked. * can return FALSE when the internal pads could not be linked.
*/ */
gboolean gboolean
gst_ghost_pad_set_target (GstGhostPad * gpad, GstPad * newtarget) gst_ghost_pad_set_target (GstGhostPad * gpad, GstPad * newtarget)

14
gst/gstindex.c
View file

@ -29,6 +29,8 @@
* in a pipeline. * in a pipeline.
*/ */
/* FIXME: complete gobject annotations */
#include "gst_private.h" #include "gst_private.h"
#include "gstinfo.h" #include "gstinfo.h"
@ -281,7 +283,7 @@ gst_index_group_free (GstIndexGroup * group)
* *
* Create a new tileindex object * Create a new tileindex object
* *
* Returns: a new index object * Returns: (transfer full): a new index object
*/ */
GstIndex * GstIndex *
gst_index_new (void) gst_index_new (void)
@ -501,7 +503,9 @@ gst_index_set_resolver_full (GstIndex * index, GstIndexResolver resolver,
* *
* Copies an entry and returns the result. * Copies an entry and returns the result.
* *
* Returns: a newly allocated #GstIndexEntry. * Free-function: gst_index_entry_free
*
* Returns: (transfer full): a newly allocated #GstIndexEntry.
*/ */
GstIndexEntry * GstIndexEntry *
gst_index_entry_copy (GstIndexEntry * entry) gst_index_entry_copy (GstIndexEntry * entry)
@ -514,7 +518,7 @@ gst_index_entry_copy (GstIndexEntry * entry)
/** /**
* gst_index_entry_free: * gst_index_entry_free:
* @entry: the entry to free * @entry: (transfer full): the entry to free
* *
* Free the memory used by the given entry. * Free the memory used by the given entry.
*/ */
@ -553,7 +557,9 @@ gst_index_entry_free (GstIndexEntry * entry)
* used to map dynamic GstFormat ids to their original * used to map dynamic GstFormat ids to their original
* format key. * format key.
* *
* Returns: a pointer to the newly added entry in the index. * Free-function: gst_index_entry_free
*
* Returns: (transfer full): a pointer to the newly added entry in the index.
*/ */
GstIndexEntry * GstIndexEntry *
gst_index_add_format (GstIndex * index, gint id, GstFormat format) gst_index_add_format (GstIndex * index, gint id, GstFormat format)

9
gst/gstindexfactory.c
View file

@ -78,7 +78,7 @@ gst_index_factory_finalize (GObject * object)
* *
* Create a new indexfactory with the given parameters * Create a new indexfactory with the given parameters
* *
* Returns: a new #GstIndexFactory. * Returns: (transfer full): a new #GstIndexFactory.
*/ */
GstIndexFactory * GstIndexFactory *
gst_index_factory_new (const gchar * name, const gchar * longdesc, GType type) gst_index_factory_new (const gchar * name, const gchar * longdesc, GType type)
@ -109,6 +109,7 @@ gst_index_factory_destroy (GstIndexFactory * factory)
g_return_if_fail (factory != NULL); g_return_if_fail (factory != NULL);
/* we don't free the struct bacause someone might have a handle to it.. */ /* we don't free the struct bacause someone might have a handle to it.. */
/* FIXME: gst_index_factory_destroy */
} }
/** /**
@ -117,7 +118,7 @@ gst_index_factory_destroy (GstIndexFactory * factory)
* *
* Search for an indexfactory of the given name. * Search for an indexfactory of the given name.
* *
* Returns: #GstIndexFactory if found, NULL otherwise * Returns: (transfer full): #GstIndexFactory if found, NULL otherwise
*/ */
GstIndexFactory * GstIndexFactory *
gst_index_factory_find (const gchar * name) gst_index_factory_find (const gchar * name)
@ -143,7 +144,7 @@ gst_index_factory_find (const gchar * name)
* Create a new #GstIndex instance from the * Create a new #GstIndex instance from the
* given indexfactory. * given indexfactory.
* *
* Returns: A new #GstIndex instance. * Returns: (transfer full): a new #GstIndex instance.
*/ */
GstIndex * GstIndex *
gst_index_factory_create (GstIndexFactory * factory) gst_index_factory_create (GstIndexFactory * factory)
@ -173,7 +174,7 @@ gst_index_factory_create (GstIndexFactory * factory)
* Create a new #GstIndex instance from the * Create a new #GstIndex instance from the
* indexfactory with the given name. * indexfactory with the given name.
* *
* Returns: A new #GstIndex instance. * Returns: (transfer full): a new #GstIndex instance.
*/ */
GstIndex * GstIndex *
gst_index_factory_make (const gchar * name) gst_index_factory_make (const gchar * name)

17
gst/gstinfo.c
View file

@ -439,7 +439,8 @@ _gst_debug_init (void)
* @file: the file that emitted the message, usually the __FILE__ identifier * @file: the file that emitted the message, usually the __FILE__ identifier
* @function: the function that emitted the message * @function: the function that emitted the message
* @line: the line from that the message was emitted, usually __LINE__ * @line: the line from that the message was emitted, usually __LINE__
* @object: the object this message relates to or NULL if none * @object: (transfer none) (allow-none): the object this message relates to,
* or NULL if none
* @format: a printf style format string * @format: a printf style format string
* @...: optional arguments for the format * @...: optional arguments for the format
* *
@ -465,7 +466,8 @@ gst_debug_log (GstDebugCategory * category, GstDebugLevel level,
* @file: the file that emitted the message, usually the __FILE__ identifier * @file: the file that emitted the message, usually the __FILE__ identifier
* @function: the function that emitted the message * @function: the function that emitted the message
* @line: the line from that the message was emitted, usually __LINE__ * @line: the line from that the message was emitted, usually __LINE__
* @object: the object this message relates to or NULL if none * @object: (transfer none) (allow-none): the object this message relates to,
* or NULL if none
* @format: a printf style format string * @format: a printf style format string
* @args: optional arguments for the format * @args: optional arguments for the format
* *
@ -734,7 +736,8 @@ gst_debug_print_segment (gpointer ptr)
* terminals. * terminals.
* You need to free the string after use. * You need to free the string after use.
* *
* Returns: a string containing the color definition * Returns: (transfer full) (type gchar*): a string containing the color
* definition
*/ */
gchar * gchar *
gst_debug_construct_term_color (guint colorinfo) gst_debug_construct_term_color (guint colorinfo)
@ -883,7 +886,8 @@ static const gchar *levelcolormap[GST_LEVEL_COUNT] = {
* @function: the function that emitted the message * @function: the function that emitted the message
* @line: the line from that the message was emitted, usually __LINE__ * @line: the line from that the message was emitted, usually __LINE__
* @message: the actual message * @message: the actual message
* @object: the object this message relates to or NULL if none * @object: (transfer none) (allow-none): the object this message relates to,
* or NULL if none
* @unused: an unused variable, reserved for some user_data. * @unused: an unused variable, reserved for some user_data.
* *
* The default logging handler used by GStreamer. Logging functions get called * The default logging handler used by GStreamer. Logging functions get called
@ -1034,7 +1038,7 @@ gst_debug_level_get_name (GstDebugLevel level)
/** /**
* gst_debug_add_log_function: * gst_debug_add_log_function:
* @func: the function to use * @func: the function to use
* @data: user data * @data: (closure): user data
* *
* Adds the logging function to the list of logging functions. * Adds the logging function to the list of logging functions.
* Be sure to use #G_GNUC_NO_INSTRUMENT on that function, it is needed. * Be sure to use #G_GNUC_NO_INSTRUMENT on that function, it is needed.
@ -1509,7 +1513,8 @@ gst_debug_category_get_description (GstDebugCategory * category)
* may change anytime. * may change anytime.
* The caller has to free the list after use. * The caller has to free the list after use.
* *
* Returns: the list of categories * Returns: (transfer container) (element-type Gst.DebugCategory): the list of
* debug categories
*/ */
GSList * GSList *
gst_debug_get_all_categories (void) gst_debug_get_all_categories (void)

261
gst/gstmessage.c
View file

@ -246,14 +246,14 @@ _gst_message_copy (GstMessage * message)
* gst_message_new_custom: * gst_message_new_custom:
* @type: The #GstMessageType to distinguish messages * @type: The #GstMessageType to distinguish messages
* @src: The object originating the message. * @src: The object originating the message.
* @structure: The structure for the message. The message will take ownership of * @structure: (transfer full): the structure for the message. The message
* the structure. * will take ownership of the structure.
* *
* Create a new custom-typed message. This can be used for anything not * Create a new custom-typed message. This can be used for anything not
* handled by other message-specific functions to pass a message to the * handled by other message-specific functions to pass a message to the
* app. The structure field can be NULL. * app. The structure field can be NULL.
* *
* Returns: The new message. * Returns: (transfer full): The new message.
* *
* MT safe. * MT safe.
*/ */
@ -342,13 +342,13 @@ gst_message_set_seqnum (GstMessage * message, guint32 seqnum)
/** /**
* gst_message_new_eos: * gst_message_new_eos:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* *
* Create a new eos message. This message is generated and posted in * Create a new eos message. This message is generated and posted in
* the sink elements of a GstBin. The bin will only forward the EOS * the sink elements of a GstBin. The bin will only forward the EOS
* message to the application if all sinks have posted an EOS message. * message to the application if all sinks have posted an EOS message.
* *
* Returns: The new eos message. * Returns: (transfer full): The new eos message.
* *
* MT safe. * MT safe.
*/ */
@ -364,8 +364,8 @@ gst_message_new_eos (GstObject * src)
/** /**
* gst_message_new_error: * gst_message_new_error:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* @error: The GError for this message. * @error: (transfer none): The GError for this message.
* @debug: A debugging string. * @debug: A debugging string.
* *
* Create a new error message. The message will copy @error and * Create a new error message. The message will copy @error and
@ -373,7 +373,7 @@ gst_message_new_eos (GstObject * src)
* occured. The pipeline will probably (partially) stop. The application * occured. The pipeline will probably (partially) stop. The application
* receiving this message should stop the pipeline. * receiving this message should stop the pipeline.
* *
* Returns: The new error message. * Returns: (transfer full): the new error message.
* *
* MT safe. * MT safe.
*/ */
@ -393,14 +393,14 @@ gst_message_new_error (GstObject * src, GError * error, const gchar * debug)
/** /**
* gst_message_new_warning: * gst_message_new_warning:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* @error: The GError for this message. * @error: (transfer none): The GError for this message.
* @debug: A debugging string. * @debug: A debugging string.
* *
* Create a new warning message. The message will make copies of @error and * Create a new warning message. The message will make copies of @error and
* @debug. * @debug.
* *
* Returns: The new warning message. * Returns: (transfer full): The new warning message.
* *
* MT safe. * MT safe.
*/ */
@ -420,8 +420,8 @@ gst_message_new_warning (GstObject * src, GError * error, const gchar * debug)
/** /**
* gst_message_new_info: * gst_message_new_info:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* @error: The GError for this message. * @error: (transfer none): The GError for this message.
* @debug: A debugging string. * @debug: A debugging string.
* *
* Create a new info message. The message will make copies of @error and * Create a new info message. The message will make copies of @error and
@ -429,7 +429,7 @@ gst_message_new_warning (GstObject * src, GError * error, const gchar * debug)
* *
* MT safe. * MT safe.
* *
* Returns: The new info message. * Returns: (transfer full): the new info message.
* *
* Since: 0.10.12 * Since: 0.10.12
*/ */
@ -449,13 +449,13 @@ gst_message_new_info (GstObject * src, GError * error, const gchar * debug)
/** /**
* gst_message_new_tag: * gst_message_new_tag:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* @tag_list: The tag list for the message. * @tag_list: (transfer full): the tag list for the message.
* *
* Create a new tag message. The message will take ownership of the tag list. * Create a new tag message. The message will take ownership of the tag list.
* The message is posted by elements that discovered a new taglist. * The message is posted by elements that discovered a new taglist.
* *
* Returns: The new tag message. * Returns: (transfer full): the new tag message.
* *
* MT safe. * MT safe.
*/ */
@ -474,16 +474,16 @@ gst_message_new_tag (GstObject * src, GstTagList * tag_list)
/** /**
* gst_message_new_tag_full: * gst_message_new_tag_full:
* @src: The object originating the message. * @src: (transfer none): the object originating the message.
* @pad: The originating pad for the tag. * @pad: (transfer none): the originating pad for the tag.
* @tag_list: The tag list for the message. * @tag_list: (transfer full): the tag list for the message.
* *
* Create a new tag message. The message will take ownership of the tag list. * Create a new tag message. The message will take ownership of the tag list.
* The message is posted by elements that discovered a new taglist. * The message is posted by elements that discovered a new taglist.
* *
* MT safe. * MT safe.
* *
* Returns: The new tag message. * Returns: (transfer full): the new tag message.
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -507,7 +507,7 @@ gst_message_new_tag_full (GstObject * src, GstPad * pad, GstTagList * tag_list)
/** /**
* gst_message_new_buffering: * gst_message_new_buffering:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* @percent: The buffering percent * @percent: The buffering percent
* *
* Create a new buffering message. This message can be posted by an element that * Create a new buffering message. This message can be posted by an element that
@ -523,7 +523,7 @@ gst_message_new_tag_full (GstObject * src, GstPad * pad, GstTagList * tag_list)
* *
* MT safe. * MT safe.
* *
* Returns: The new buffering message. * Returns: (transfer full): The new buffering message.
* *
* Since: 0.10.11 * Since: 0.10.11
*/ */
@ -549,7 +549,7 @@ gst_message_new_buffering (GstObject * src, gint percent)
/** /**
* gst_message_new_state_changed: * gst_message_new_state_changed:
* @src: the object originating the message * @src: (transfer none): the object originating the message
* @oldstate: the previous state * @oldstate: the previous state
* @newstate: the new (current) state * @newstate: the new (current) state
* @pending: the pending (target) state * @pending: the pending (target) state
@ -557,7 +557,7 @@ gst_message_new_buffering (GstObject * src, gint percent)
* Create a state change message. This message is posted whenever an element * Create a state change message. This message is posted whenever an element
* changed its state. * changed its state.
* *
* Returns: The new state change message. * Returns: (transfer full): the new state change message.
* *
* MT safe. * MT safe.
*/ */
@ -579,13 +579,13 @@ gst_message_new_state_changed (GstObject * src,
/** /**
* gst_message_new_state_dirty: * gst_message_new_state_dirty:
* @src: the object originating the message * @src: (transfer none): the object originating the message
* *
* Create a state dirty message. This message is posted whenever an element * Create a state dirty message. This message is posted whenever an element
* changed its state asynchronously and is used internally to update the * changed its state asynchronously and is used internally to update the
* states of container objects. * states of container objects.
* *
* Returns: The new state dirty message. * Returns: (transfer full): the new state dirty message.
* *
* MT safe. * MT safe.
*/ */
@ -601,8 +601,8 @@ gst_message_new_state_dirty (GstObject * src)
/** /**
* gst_message_new_clock_provide: * gst_message_new_clock_provide:
* @src: The object originating the message. * @src: (transfer none): the object originating the message.
* @clock: The clock it provides * @clock: (transfer none): the clock it provides
* @ready: TRUE if the sender can provide a clock * @ready: TRUE if the sender can provide a clock
* *
* Create a clock provide message. This message is posted whenever an * Create a clock provide message. This message is posted whenever an
@ -612,7 +612,7 @@ gst_message_new_state_dirty (GstObject * src)
* This message is mainly used internally to manage the clock * This message is mainly used internally to manage the clock
* selection. * selection.
* *
* Returns: The new provide clock message. * Returns: (transfer full): the new provide clock message.
* *
* MT safe. * MT safe.
*/ */
@ -633,8 +633,8 @@ gst_message_new_clock_provide (GstObject * src, GstClock * clock,
/** /**
* gst_message_new_clock_lost: * gst_message_new_clock_lost:
* @src: The object originating the message. * @src: (transfer none): the object originating the message.
* @clock: the clock that was lost * @clock: (transfer none): the clock that was lost
* *
* Create a clock lost message. This message is posted whenever the * Create a clock lost message. This message is posted whenever the
* clock is not valid anymore. * clock is not valid anymore.
@ -643,7 +643,7 @@ gst_message_new_clock_provide (GstObject * src, GstClock * clock,
* select a new clock again when it goes to PLAYING. It might therefore * select a new clock again when it goes to PLAYING. It might therefore
* be needed to set the pipeline to PAUSED and PLAYING again. * be needed to set the pipeline to PAUSED and PLAYING again.
* *
* Returns: The new clock lost message. * Returns: (transfer full): The new clock lost message.
* *
* MT safe. * MT safe.
*/ */
@ -662,13 +662,13 @@ gst_message_new_clock_lost (GstObject * src, GstClock * clock)
/** /**
* gst_message_new_new_clock: * gst_message_new_new_clock:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* @clock: the new selected clock * @clock: (transfer none): the new selected clock
* *
* Create a new clock message. This message is posted whenever the * Create a new clock message. This message is posted whenever the
* pipeline selectes a new clock for the pipeline. * pipeline selectes a new clock for the pipeline.
* *
* Returns: The new new clock message. * Returns: (transfer full): The new new clock message.
* *
* MT safe. * MT safe.
*/ */
@ -687,9 +687,9 @@ gst_message_new_new_clock (GstObject * src, GstClock * clock)
/** /**
* gst_message_new_structure_change: * gst_message_new_structure_change:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* @type: The change type. * @type: The change type.
* @owner: The owner element of @src. * @owner: (transfer none): The owner element of @src.
* @busy: Whether the structure change is busy. * @busy: Whether the structure change is busy.
* *
* Create a new structure change message. This message is posted when the * Create a new structure change message. This message is posted when the
@ -698,7 +698,7 @@ gst_message_new_new_clock (GstObject * src, GstClock * clock)
* *
* @src should be the sinkpad that unlinked or linked. * @src should be the sinkpad that unlinked or linked.
* *
* Returns: The new structure change message. * Returns: (transfer full): the new structure change message.
* *
* MT safe. * MT safe.
* *
@ -728,7 +728,7 @@ gst_message_new_structure_change (GstObject * src, GstStructureChangeType type,
/** /**
* gst_message_new_segment_start: * gst_message_new_segment_start:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* @format: The format of the position being played * @format: The format of the position being played
* @position: The position of the segment being played * @position: The position of the segment being played
* *
@ -737,7 +737,7 @@ gst_message_new_structure_change (GstObject * src, GstStructureChangeType type,
* is not received by the application but is used for maintenance reasons in * is not received by the application but is used for maintenance reasons in
* container elements. * container elements.
* *
* Returns: The new segment start message. * Returns: (transfer full): the new segment start message.
* *
* MT safe. * MT safe.
*/ */
@ -758,7 +758,7 @@ gst_message_new_segment_start (GstObject * src, GstFormat format,
/** /**
* gst_message_new_segment_done: * gst_message_new_segment_done:
* @src: The object originating the message. * @src: (transfer none): the object originating the message.
* @format: The format of the position being done * @format: The format of the position being done
* @position: The position of the segment being done * @position: The position of the segment being done
* *
@ -767,7 +767,7 @@ gst_message_new_segment_start (GstObject * src, GstFormat format,
* is received by the application after all elements that posted a segment_start * is received by the application after all elements that posted a segment_start
* have posted the segment_done. * have posted the segment_done.
* *
* Returns: The new segment done message. * Returns: (transfer full): the new segment done message.
* *
* MT safe. * MT safe.
*/ */
@ -788,14 +788,14 @@ gst_message_new_segment_done (GstObject * src, GstFormat format,
/** /**
* gst_message_new_application: * gst_message_new_application:
* @src: The object originating the message. * @src: (transfer none): the object originating the message.
* @structure: The structure for the message. The message will take ownership of * @structure: (transfer full): the structure for the message. The message
* the structure. * will take ownership of the structure.
* *
* Create a new application-typed message. GStreamer will never create these * Create a new application-typed message. GStreamer will never create these
* messages; they are a gift from us to you. Enjoy. * messages; they are a gift from us to you. Enjoy.
* *
* Returns: The new application message. * Returns: (transfer full): The new application message.
* *
* MT safe. * MT safe.
*/ */
@ -807,16 +807,16 @@ gst_message_new_application (GstObject * src, GstStructure * structure)
/** /**
* gst_message_new_element: * gst_message_new_element:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* @structure: The structure for the message. The message will take ownership of * @structure: (transfer full): The structure for the message. The message
* the structure. * will take ownership of the structure.
* *
* Create a new element-specific message. This is meant as a generic way of * Create a new element-specific message. This is meant as a generic way of
* allowing one-way communication from an element to an application, for example * allowing one-way communication from an element to an application, for example
* "the firewire cable was unplugged". The format of the message should be * "the firewire cable was unplugged". The format of the message should be
* documented in the element's documentation. The structure field can be NULL. * documented in the element's documentation. The structure field can be NULL.
* *
* Returns: The new element message. * Returns: (transfer full): The new element message.
* *
* MT safe. * MT safe.
*/ */
@ -828,7 +828,7 @@ gst_message_new_element (GstObject * src, GstStructure * structure)
/** /**
* gst_message_new_duration: * gst_message_new_duration:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* @format: The format of the duration * @format: The format of the duration
* @duration: The new duration * @duration: The new duration
* *
@ -840,7 +840,7 @@ gst_message_new_element (GstObject * src, GstStructure * structure)
* cached duration should be discarded. The new duration can then be * cached duration should be discarded. The new duration can then be
* retrieved via a query. * retrieved via a query.
* *
* Returns: The new duration message. * Returns: (transfer full): The new duration message.
* *
* MT safe. * MT safe.
*/ */
@ -860,14 +860,14 @@ gst_message_new_duration (GstObject * src, GstFormat format, gint64 duration)
/** /**
* gst_message_new_async_start: * gst_message_new_async_start:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* @new_base_time: if a new base_time should be set on the element * @new_base_time: if a new base_time should be set on the element
* *
* This message is posted by elements when they start an ASYNC state change. * This message is posted by elements when they start an ASYNC state change.
* @new_base_time is set to TRUE when the element lost its state when it was * @new_base_time is set to TRUE when the element lost its state when it was
* PLAYING. * PLAYING.
* *
* Returns: The new async_start message. * Returns: (transfer full): The new async_start message.
* *
* MT safe. * MT safe.
* *
@ -888,11 +888,11 @@ gst_message_new_async_start (GstObject * src, gboolean new_base_time)
/** /**
* gst_message_new_async_done: * gst_message_new_async_done:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* *
* The message is posted when elements completed an ASYNC state change. * The message is posted when elements completed an ASYNC state change.
* *
* Returns: The new async_done message. * Returns: (transfer full): The new async_done message.
* *
* MT safe. * MT safe.
* *
@ -910,12 +910,12 @@ gst_message_new_async_done (GstObject * src)
/** /**
* gst_message_new_latency: * gst_message_new_latency:
* @src: The object originating the message. * @src: (transfer none): The object originating the message.
* *
* This message can be posted by elements when their latency requirements have * This message can be posted by elements when their latency requirements have
* changed. * changed.
* *
* Returns: The new latency message. * Returns: (transfer full): The new latency message.
* *
* MT safe. * MT safe.
* *
@ -933,14 +933,14 @@ gst_message_new_latency (GstObject * src)
/** /**
* gst_message_new_request_state: * gst_message_new_request_state:
* @src: The object originating the message. * @src: (transfer none): the object originating the message.
* @state: The new requested state * @state: The new requested state
* *
* This message can be posted by elements when they want to have their state * This message can be posted by elements when they want to have their state
* changed. A typical use case would be an audio server that wants to pause the * changed. A typical use case would be an audio server that wants to pause the
* pipeline because a higher priority stream is being played. * pipeline because a higher priority stream is being played.
* *
* Returns: The new requst state message. * Returns: (transfer full): the new requst state message.
* *
* MT safe. * MT safe.
* *
@ -965,8 +965,8 @@ gst_message_new_request_state (GstObject * src, GstState state)
* *
* Access the structure of the message. * Access the structure of the message.
* *
* Returns: The structure of the message. The structure is still * Returns: (transfer none): The structure of the message. The structure is
* owned by the message, which means that you should not free it and * still owned by the message, which means that you should not free it and
* that the pointer becomes invalid when you free the message. * that the pointer becomes invalid when you free the message.
* *
* MT safe. * MT safe.
@ -982,7 +982,7 @@ gst_message_get_structure (GstMessage * message)
/** /**
* gst_message_parse_tag: * gst_message_parse_tag:
* @message: A valid #GstMessage of type GST_MESSAGE_TAG. * @message: A valid #GstMessage of type GST_MESSAGE_TAG.
* @tag_list: (out): Return location for the tag-list. * @tag_list: (out callee-allocates): return location for the tag-list.
* *
* Extracts the tag list from the GstMessage. The tag list returned in the * Extracts the tag list from the GstMessage. The tag list returned in the
* output argument is a copy; the caller must free it when done. * output argument is a copy; the caller must free it when done.
@ -1025,8 +1025,9 @@ gst_message_parse_tag (GstMessage * message, GstTagList ** tag_list)
/** /**
* gst_message_parse_tag_full: * gst_message_parse_tag_full:
* @message: A valid #GstMessage of type GST_MESSAGE_TAG. * @message: A valid #GstMessage of type GST_MESSAGE_TAG.
* @pad: (out): Location where the originating pad is stored, unref after usage * @pad: (out callee-allocates): location where the originating pad is stored,
* @tag_list: (out): Return location for the tag-list. * unref after usage
* @tag_list: (out callee-allocates): return location for the tag-list.
* *
* Extracts the tag list from the GstMessage. The tag list returned in the * Extracts the tag list from the GstMessage. The tag list returned in the
* output argument is a copy; the caller must free it when done. * output argument is a copy; the caller must free it when done.
@ -1066,7 +1067,7 @@ gst_message_parse_tag_full (GstMessage * message, GstPad ** pad,
/** /**
* gst_message_parse_buffering: * gst_message_parse_buffering:
* @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING. * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
* @percent: (out): Return location for the percent. * @percent: (out) (allow-none): Return location for the percent.
* *
* Extracts the buffering percent from the GstMessage. see also * Extracts the buffering percent from the GstMessage. see also
* gst_message_new_buffering(). * gst_message_new_buffering().
@ -1114,10 +1115,11 @@ gst_message_set_buffering_stats (GstMessage * message, GstBufferingMode mode,
/** /**
* gst_message_parse_buffering_stats: * gst_message_parse_buffering_stats:
* @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING. * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
* @mode: (out): a buffering mode * @mode: (out) (allow-none): a buffering mode, or NULL
* @avg_in: (out): the average input rate * @avg_in: (out) (allow-none): the average input rate, or NULL
* @avg_out: (out): the average output rate * @avg_out: (out) (allow-none): the average output rate, or NULL
* @buffering_left: (out): amount of buffering time left in milliseconds. * @buffering_left: (out) (allow-none): amount of buffering time left in
* milliseconds, or NULL
* *
* Extracts the buffering stats values from @message. * Extracts the buffering stats values from @message.
* *
@ -1148,9 +1150,9 @@ gst_message_parse_buffering_stats (GstMessage * message,
/** /**
* gst_message_parse_state_changed: * gst_message_parse_state_changed:
* @message: a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED * @message: a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED
* @oldstate: (out): the previous state, or NULL * @oldstate: (out) (allow-none): the previous state, or NULL
* @newstate: (out): the new (current) state, or NULL * @newstate: (out) (allow-none): the new (current) state, or NULL
* @pending: (out): the pending (target) state, or NULL * @pending: (out) (allow-none): the pending (target) state, or NULL
* *
* Extracts the old and new states from the GstMessage. * Extracts the old and new states from the GstMessage.
* *
@ -1198,8 +1200,9 @@ gst_message_parse_state_changed (GstMessage * message,
/** /**
* gst_message_parse_clock_provide: * gst_message_parse_clock_provide:
* @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE. * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE.
* @clock: (out): A pointer to hold a clock object. * @clock: (out) (allow-none) (transfer none): a pointer to hold a clock
* @ready: (out): A pointer to hold the ready flag. * object, or NULL
* @ready: (out) (allow-none): a pointer to hold the ready flag, or NULL
* *
* Extracts the clock and ready flag from the GstMessage. * Extracts the clock and ready flag from the GstMessage.
* The clock object returned remains valid until the message is freed. * The clock object returned remains valid until the message is freed.
@ -1231,7 +1234,7 @@ gst_message_parse_clock_provide (GstMessage * message, GstClock ** clock,
/** /**
* gst_message_parse_clock_lost: * gst_message_parse_clock_lost:
* @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST. * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST.
* @clock: (out): A pointer to hold the lost clock * @clock: (out) (allow-none) (transfer none): a pointer to hold the lost clock
* *
* Extracts the lost clock from the GstMessage. * Extracts the lost clock from the GstMessage.
* The clock object returned remains valid until the message is freed. * The clock object returned remains valid until the message is freed.
@ -1258,7 +1261,8 @@ gst_message_parse_clock_lost (GstMessage * message, GstClock ** clock)
/** /**
* gst_message_parse_new_clock: * gst_message_parse_new_clock:
* @message: A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK. * @message: A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK.
* @clock: A pointer to hold the selected new clock * @clock: (out) (allow-none) (transfer none): a pointer to hold the selected
* new clock
* *
* Extracts the new clock from the GstMessage. * Extracts the new clock from the GstMessage.
* The clock object returned remains valid until the message is freed. * The clock object returned remains valid until the message is freed.
@ -1286,9 +1290,10 @@ gst_message_parse_new_clock (GstMessage * message, GstClock ** clock)
* gst_message_parse_structure_change: * gst_message_parse_structure_change:
* @message: A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE. * @message: A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE.
* @type: (out): A pointer to hold the change type * @type: (out): A pointer to hold the change type
* @owner: (out): The owner element of the message source * @owner: (out) (allow-none) (transfer none): The owner element of the
* @busy: (out): A pointer to hold whether the change is in progress or has been * message source
* completed * @busy: (out) (allow-none): a pointer to hold whether the change is in
* progress or has been completed
* *
* Extracts the change type and completion status from the GstMessage. * Extracts the change type and completion status from the GstMessage.
* *
@ -1324,8 +1329,9 @@ gst_message_parse_structure_change (GstMessage * message,
/** /**
* gst_message_parse_error: * gst_message_parse_error:
* @message: A valid #GstMessage of type GST_MESSAGE_ERROR. * @message: A valid #GstMessage of type GST_MESSAGE_ERROR.
* @gerror: (out): Location for the GError * @gerror: (out) (allow-none) (transfer full): location for the GError
* @debug: (out): Location for the debug message, or NULL * @debug: (out) (allow-none) (transfer full): location for the debug message,
* or NULL
* *
* Extracts the GError and debug string from the GstMessage. The values returned * Extracts the GError and debug string from the GstMessage. The values returned
* in the output arguments are copies; the caller must free them when done. * in the output arguments are copies; the caller must free them when done.
@ -1382,8 +1388,9 @@ gst_message_parse_error (GstMessage * message, GError ** gerror, gchar ** debug)
/** /**
* gst_message_parse_warning: * gst_message_parse_warning:
* @message: A valid #GstMessage of type GST_MESSAGE_WARNING. * @message: A valid #GstMessage of type GST_MESSAGE_WARNING.
* @gerror: (out): Location for the GError * @gerror: (out) (allow-none) (transfer full): location for the GError
* @debug: (out): Location for the debug message, or NULL * @debug: (out) (allow-none) (transfer full): location for the debug message,
* or NULL
* *
* Extracts the GError and debug string from the GstMessage. The values returned * Extracts the GError and debug string from the GstMessage. The values returned
* in the output arguments are copies; the caller must free them when done. * in the output arguments are copies; the caller must free them when done.
@ -1420,8 +1427,9 @@ gst_message_parse_warning (GstMessage * message, GError ** gerror,
/** /**
* gst_message_parse_info: * gst_message_parse_info:
* @message: A valid #GstMessage of type GST_MESSAGE_INFO. * @message: A valid #GstMessage of type GST_MESSAGE_INFO.
* @gerror: (out): Location for the GError * @gerror: (out) (allow-none) (transfer full): location for the GError
* @debug: (out): Location for the debug message, or NULL * @debug: (out) (allow-none) (transfer full): location for the debug message,
* or NULL
* *
* Extracts the GError and debug string from the GstMessage. The values returned * Extracts the GError and debug string from the GstMessage. The values returned
* in the output arguments are copies; the caller must free them when done. * in the output arguments are copies; the caller must free them when done.
@ -1589,12 +1597,12 @@ gst_message_parse_request_state (GstMessage * message, GstState * state)
* gst_message_new_stream_status: * gst_message_new_stream_status:
* @src: The object originating the message. * @src: The object originating the message.
* @type: The stream status type. * @type: The stream status type.
* @owner: The owner element of @src. * @owner: (transfer none): the owner element of @src.
* *
* Create a new stream status message. This message is posted when a streaming * Create a new stream status message. This message is posted when a streaming
* thread is created/destroyed or when the state changed. * thread is created/destroyed or when the state changed.
* *
* Returns: The new stream status message. * Returns: (transfer full): the new stream status message.
* *
* MT safe. * MT safe.
* *
@ -1619,7 +1627,7 @@ gst_message_new_stream_status (GstObject * src, GstStreamStatusType type,
* gst_message_parse_stream_status: * gst_message_parse_stream_status:
* @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS.
* @type: (out): A pointer to hold the status type * @type: (out): A pointer to hold the status type
* @owner: (out): The owner element of the message source * @owner: (out) (transfer none): The owner element of the message source
* *
* Extracts the stream status type and owner the GstMessage. The returned * Extracts the stream status type and owner the GstMessage. The returned
* owner remains valid for as long as the reference to @message is valid and * owner remains valid for as long as the reference to @message is valid and
@ -1712,7 +1720,7 @@ gst_message_get_stream_status_object (GstMessage * message)
* @duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped * @duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped
* @amount of media in format @format. * @amount of media in format @format.
* *
* Returns: The new step_done message. * Returns: (transfer full): the new step_done message.
* *
* MT safe. * MT safe.
* *
@ -1742,13 +1750,13 @@ gst_message_new_step_done (GstObject * src, GstFormat format, guint64 amount,
/** /**
* gst_message_parse_step_done: * gst_message_parse_step_done:
* @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE. * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE.
* @format: (out): result location for the format * @format: (out) (allow-none): result location for the format
* @amount: (out): result location for the amount * @amount: (out) (allow-none): result location for the amount
* @rate: (out): result location for the rate * @rate: (out) (allow-none): result location for the rate
* @flush: (out): result location for the flush flag * @flush: (out) (allow-none): result location for the flush flag
* @intermediate: (out): result location for the intermediate flag * @intermediate: (out) (allow-none): result location for the intermediate flag
* @duration: (out): result location for the duration * @duration: (out) (allow-none): result location for the duration
* @eos: (out): result location for the EOS flag * @eos: (out) (allow-none): result location for the EOS flag
* *
* Extract the values the step_done message. * Extract the values the step_done message.
* *
@ -1795,7 +1803,7 @@ gst_message_parse_step_done (GstMessage * message, GstFormat * format,
* message is emited, the application can queue a new step operation in the * message is emited, the application can queue a new step operation in the
* element. * element.
* *
* Returns: The new step_start message. * Returns: (transfer full): The new step_start message.
* *
* MT safe. * MT safe.
* *
@ -1823,12 +1831,12 @@ gst_message_new_step_start (GstObject * src, gboolean active, GstFormat format,
/** /**
* gst_message_parse_step_start: * gst_message_parse_step_start:
* @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE. * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE.
* @active: (out): result location for the active flag * @active: (out) (allow-none): result location for the active flag
* @format: (out): result location for the format * @format: (out) (allow-none): result location for the format
* @amount: (out): result location for the amount * @amount: (out) (allow-none): result location for the amount
* @rate: (out): result location for the rate * @rate: (out) (allow-none): result location for the rate
* @flush: (out): result location for the flush flag * @flush: (out) (allow-none): result location for the flush flag
* @intermediate: (out): result location for the intermediate flag * @intermediate: (out) (allow-none): result location for the intermediate flag
* *
* Extract the values from step_start message. * Extract the values from step_start message.
* *
@ -1876,7 +1884,7 @@ gst_message_parse_step_start (GstMessage * message, gboolean * active,
* buffer that generated the QoS event. Values can be left to * buffer that generated the QoS event. Values can be left to
* GST_CLOCK_TIME_NONE when unknown. * GST_CLOCK_TIME_NONE when unknown.
* *
* Returns: The new qos message. * Returns: (transfer full): The new qos message.
* *
* MT safe. * MT safe.
* *
@ -1971,11 +1979,15 @@ gst_message_set_qos_stats (GstMessage * message, GstFormat format,
/** /**
* gst_message_parse_qos: * gst_message_parse_qos:
* @message: A valid #GstMessage of type GST_MESSAGE_QOS. * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
* @live: (out): if the message was generated by a live element * @live: (out) (allow-none): if the message was generated by a live element
* @running_time: (out): the running time of the buffer that generated the message * @running_time: (out) (allow-none): the running time of the buffer that
* @stream_time: (out): the stream time of the buffer that generated the message * generated the message
* @timestamp: (out): the timestamps of the buffer that generated the message * @stream_time: (out) (allow-none): the stream time of the buffer that
* @duration: (out): the duration of the buffer that generated the message * generated the message
* @timestamp: (out) (allow-none): the timestamps of the buffer that
* generated the message
* @duration: (out) (allow-none): the duration of the buffer that
* generated the message
* *
* Extract the timestamps and live status from the QoS message. * Extract the timestamps and live status from the QoS message.
* *
@ -2006,11 +2018,13 @@ gst_message_parse_qos (GstMessage * message, gboolean * live,
/** /**
* gst_message_parse_qos_values: * gst_message_parse_qos_values:
* @message: A valid #GstMessage of type GST_MESSAGE_QOS. * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
* @jitter: (out): The difference of the running-time against the deadline. * @jitter: (out) (allow-none): The difference of the running-time against
* @proportion: (out): Long term prediction of the ideal rate relative to normal rate * the deadline.
* to get optimal quality. * @proportion: (out) (allow-none): Long term prediction of the ideal rate
* @quality: (out): An element dependent integer value that specifies the current * relative to normal rate to get optimal quality.
* quality level of the element. The default maximum quality is 1000000. * @quality: (out) (allow-none): An element dependent integer value that
* specifies the current quality level of the element. The default
* maximum quality is 1000000.
* *
* Extract the QoS values that have been calculated/analysed from the QoS data * Extract the QoS values that have been calculated/analysed from the QoS data
* *
@ -2034,13 +2048,14 @@ gst_message_parse_qos_values (GstMessage * message, gint64 * jitter,
/** /**
* gst_message_parse_qos_stats: * gst_message_parse_qos_stats:
* @message: A valid #GstMessage of type GST_MESSAGE_QOS. * @message: A valid #GstMessage of type GST_MESSAGE_QOS.
* @format: (out): Units of the 'processed' and 'dropped' fields. Video sinks and video * @format: (out) (allow-none): Units of the 'processed' and 'dropped' fields.
* filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters * Video sinks and video filters will use GST_FORMAT_BUFFERS (frames).
* will likely use GST_FORMAT_DEFAULT (samples). * Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT
* @processed: (out): Total number of units correctly processed since the last state * (samples).
* change to READY or a flushing operation. * @processed: (out) (allow-none): Total number of units correctly processed
* @dropped: (out): Total number of units dropped since the last state change to READY * since the last state change to READY or a flushing operation.
* or a flushing operation. * @dropped: (out) (allow-none): Total number of units dropped since the last
* state change to READY or a flushing operation.
* *
* Extract the QoS stats representing the history of the current continuous * Extract the QoS stats representing the history of the current continuous
* pipeline playback period. * pipeline playback period.

8
gst/gstmessage.h
View file

@ -330,7 +330,7 @@ gst_message_unref (GstMessage * msg)
* *
* Creates a copy of the message. Returns a copy of the message. * Creates a copy of the message. Returns a copy of the message.
* *
* Returns: a new copy of @msg. * Returns: (transfer full): a new copy of @msg.
* *
* MT safe * MT safe
*/ */
@ -346,10 +346,12 @@ gst_message_copy (const GstMessage * msg)
/** /**
* gst_message_make_writable: * gst_message_make_writable:
* @msg: the message to make writable * @msg: (transfer full): the message to make writable
* *
* Checks if a message is writable. If not, a writable copy is made and * Checks if a message is writable. If not, a writable copy is made and
* returned. Returns a message (possibly a duplicate) that is writable. * returned.
*
* Returns: (transfer full): a message (possibly a duplicate) that is writable.
* *
* MT safe * MT safe
*/ */

24
gst/gstminiobject.c
View file

@ -177,7 +177,7 @@ gst_mini_object_finalize (GstMiniObject * obj)
* *
* MT safe * MT safe
* *
* Returns: the new mini-object. * Returns: (transfer full): the new mini-object.
*/ */
GstMiniObject * GstMiniObject *
gst_mini_object_new (GType type) gst_mini_object_new (GType type)
@ -217,7 +217,7 @@ gst_mini_object_new (GType type)
* *
* MT safe * MT safe
* *
* Returns: the new mini-object. * Returns: (transfer full): the new mini-object.
*/ */
GstMiniObject * GstMiniObject *
gst_mini_object_copy (const GstMiniObject * mini_object) gst_mini_object_copy (const GstMiniObject * mini_object)
@ -255,7 +255,7 @@ gst_mini_object_is_writable (const GstMiniObject * mini_object)
/** /**
* gst_mini_object_make_writable: * gst_mini_object_make_writable:
* @mini_object: the mini-object to make writable * @mini_object: (transfer full): the mini-object to make writable
* *
* Checks if a mini-object is writable. If not, a writable copy is made and * Checks if a mini-object is writable. If not, a writable copy is made and
* returned. This gives away the reference to the original mini object, * returned. This gives away the reference to the original mini object,
@ -263,7 +263,8 @@ gst_mini_object_is_writable (const GstMiniObject * mini_object)
* *
* MT safe * MT safe
* *
* Returns: a mini-object (possibly the same pointer) that is writable. * Returns: (transfer full): a mini-object (possibly the same pointer) that
* is writable.
*/ */
GstMiniObject * GstMiniObject *
gst_mini_object_make_writable (GstMiniObject * mini_object) gst_mini_object_make_writable (GstMiniObject * mini_object)
@ -371,7 +372,8 @@ gst_mini_object_unref (GstMiniObject * mini_object)
/** /**
* gst_mini_object_replace: * gst_mini_object_replace:
* @olddata: pointer to a pointer to a mini-object to be replaced * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
* be replaced
* @newdata: pointer to new mini-object * @newdata: pointer to new mini-object
* *
* Modifies a pointer to point to a new mini-object. The modification * Modifies a pointer to point to a new mini-object. The modification
@ -475,8 +477,8 @@ gst_value_mini_object_lcopy (const GValue * value, guint n_collect_values,
/** /**
* gst_value_set_mini_object: * gst_value_set_mini_object:
* @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type * @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type
* @mini_object: mini object value to set * @mini_object: (transfer none): mini object value to set
* *
* Set the contents of a %GST_TYPE_MINI_OBJECT derived #GValue to * Set the contents of a %GST_TYPE_MINI_OBJECT derived #GValue to
* @mini_object. * @mini_object.
@ -496,8 +498,8 @@ gst_value_set_mini_object (GValue * value, GstMiniObject * mini_object)
/** /**
* gst_value_take_mini_object: * gst_value_take_mini_object:
* @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type * @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type
* @mini_object: mini object value to take * @mini_object: (transfer full): mini object value to take
* *
* Set the contents of a %GST_TYPE_MINI_OBJECT derived #GValue to * Set the contents of a %GST_TYPE_MINI_OBJECT derived #GValue to
* @mini_object. * @mini_object.
@ -527,7 +529,7 @@ gst_value_take_mini_object (GValue * value, GstMiniObject * mini_object)
* Get the contents of a %GST_TYPE_MINI_OBJECT derived #GValue. * Get the contents of a %GST_TYPE_MINI_OBJECT derived #GValue.
* Does not increase the refcount of the returned object. * Does not increase the refcount of the returned object.
* *
* Returns: mini object contents of @value * Returns: (transfer none): mini object contents of @value
*/ */
GstMiniObject * GstMiniObject *
gst_value_get_mini_object (const GValue * value) gst_value_get_mini_object (const GValue * value)
@ -544,7 +546,7 @@ gst_value_get_mini_object (const GValue * value)
* Get the contents of a %GST_TYPE_MINI_OBJECT derived #GValue, * Get the contents of a %GST_TYPE_MINI_OBJECT derived #GValue,
* increasing its reference count. * increasing its reference count.
* *
* Returns: mini object contents of @value * Returns: (transfer full): mini object contents of @value
* *
* Since: 0.10.20 * Since: 0.10.20
*/ */

25
gst/gstobject.c
View file

@ -409,8 +409,9 @@ gst_object_sink (gpointer object)
/** /**
* gst_object_replace: * gst_object_replace:
* @oldobj: pointer to a place of a #GstObject to replace * @oldobj: (inout) (transfer full): pointer to a place of a #GstObject to
* @newobj: a new #GstObject * replace
* @newobj: (transfer none): a new #GstObject
* *
* Unrefs the #GstObject pointed to by @oldobj, refs @newobj and * Unrefs the #GstObject pointed to by @oldobj, refs @newobj and
* puts @newobj in *@oldobj. Be carefull when calling this * puts @newobj in *@oldobj. Be carefull when calling this
@ -558,8 +559,9 @@ gst_object_dispatch_properties_changed (GObject * object,
* @object: the #GObject that signalled the notify. * @object: the #GObject that signalled the notify.
* @orig: a #GstObject that initiated the notify. * @orig: a #GstObject that initiated the notify.
* @pspec: a #GParamSpec of the property. * @pspec: a #GParamSpec of the property.
* @excluded_props: a set of user-specified properties to exclude or * @excluded_props: (array zero-terminated=1) (element-type gchar*)
* NULL to show all changes. * (allow-none):a set of user-specified properties to exclude or
* NULL to show all changes.
* *
* A default deep_notify signal callback for an object. The user data * A default deep_notify signal callback for an object. The user data
* should contain a pointer to an array of strings that should be excluded * should contain a pointer to an array of strings that should be excluded
@ -727,7 +729,9 @@ had_parent:
* For a nameless object, this returns NULL, which you can safely g_free() * For a nameless object, this returns NULL, which you can safely g_free()
* as well. * as well.
* *
* Returns: the name of @object. g_free() after usage. * Free-function: g_free
*
* Returns: (transfer full): the name of @object. g_free() after usage.
* *
* MT safe. This function grabs and releases @object's LOCK. * MT safe. This function grabs and releases @object's LOCK.
*/ */
@ -875,8 +879,8 @@ had_parent:
* Returns the parent of @object. This function increases the refcount * Returns the parent of @object. This function increases the refcount
* of the parent object so you should gst_object_unref() it after usage. * of the parent object so you should gst_object_unref() it after usage.
* *
* Returns: parent of @object, this can be NULL if @object has no * Returns: (transfer full): parent of @object, this can be NULL if @object
* parent. unref after usage. * has no parent. unref after usage.
* *
* MT safe. Grabs and releases @object's LOCK. * MT safe. Grabs and releases @object's LOCK.
*/ */
@ -965,7 +969,8 @@ gst_object_has_ancestor (GstObject * object, GstObject * ancestor)
/** /**
* gst_object_check_uniqueness: * gst_object_check_uniqueness:
* @list: a list of #GstObject to check through * @list: (transfer none) (element-type Gst.Object): a list of #GstObject to
* check through
* @name: the name to search for * @name: the name to search for
* *
* Checks to see if there is any object named @name in @list. This function * Checks to see if there is any object named @name in @list. This function
@ -1107,7 +1112,9 @@ gst_object_get_property (GObject * object, guint prop_id,
* Generates a string describing the path of @object in * Generates a string describing the path of @object in
* the object hierarchy. Only useful (or used) for debugging. * the object hierarchy. Only useful (or used) for debugging.
* *
* Returns: a string describing the path of @object. You must * Free-function: g_free
*
* Returns: (transfer full): a string describing the path of @object. You must
* g_free() the string after usage. * g_free() the string after usage.
* *
* MT safe. Grabs and releases the #GstObject's LOCK for all objects * MT safe. Grabs and releases the #GstObject's LOCK for all objects

102
gst/gstpad.c
View file

@ -529,7 +529,7 @@ gst_pad_get_property (GObject * object, guint prop_id,
* will be assigned. * will be assigned.
* This function makes a copy of the name so you can safely free the name. * This function makes a copy of the name so you can safely free the name.
* *
* Returns: a new #GstPad, or NULL in case of an error. * Returns: (transfer full): a new #GstPad, or NULL in case of an error.
* *
* MT safe. * MT safe.
*/ */
@ -550,7 +550,7 @@ gst_pad_new (const gchar * name, GstPadDirection direction)
* will be assigned. * will be assigned.
* This function makes a copy of the name so you can safely free the name. * This function makes a copy of the name so you can safely free the name.
* *
* Returns: a new #GstPad, or NULL in case of an error. * Returns: (transfer full): a new #GstPad, or NULL in case of an error.
*/ */
GstPad * GstPad *
gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name) gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name)
@ -571,7 +571,7 @@ gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name)
* will be assigned. * will be assigned.
* This function makes a copy of the name so you can safely free the name. * This function makes a copy of the name so you can safely free the name.
* *
* Returns: a new #GstPad, or NULL in case of an error. * Returns: (transfer full): a new #GstPad, or NULL in case of an error.
*/ */
GstPad * GstPad *
gst_pad_new_from_static_template (GstStaticPadTemplate * templ, gst_pad_new_from_static_template (GstStaticPadTemplate * templ,
@ -1019,7 +1019,7 @@ gst_pad_is_active (GstPad * pad)
* @blocked: boolean indicating whether the pad should be blocked or unblocked * @blocked: boolean indicating whether the pad should be blocked or unblocked
* @callback: #GstPadBlockCallback that will be called when the * @callback: #GstPadBlockCallback that will be called when the
* operation succeeds * operation succeeds
* @user_data: user data passed to the callback * @user_data: (closure): user data passed to the callback
* @destroy_data: #GDestroyNotify for user_data * @destroy_data: #GDestroyNotify for user_data
* *
* Blocks or unblocks the dataflow on a pad. The provided callback * Blocks or unblocks the dataflow on a pad. The provided callback
@ -1115,7 +1115,7 @@ had_right_state:
* @blocked: boolean indicating whether the pad should be blocked or unblocked * @blocked: boolean indicating whether the pad should be blocked or unblocked
* @callback: #GstPadBlockCallback that will be called when the * @callback: #GstPadBlockCallback that will be called when the
* operation succeeds * operation succeeds
* @user_data: user data passed to the callback * @user_data: (closure): user data passed to the callback
* *
* Blocks or unblocks the dataflow on a pad. The provided callback * Blocks or unblocks the dataflow on a pad. The provided callback
* is called when the operation succeeds; this happens right before the next * is called when the operation succeeds; this happens right before the next
@ -1422,7 +1422,8 @@ gst_pad_set_query_type_function (GstPad * pad,
* Get an array of supported queries that can be performed * Get an array of supported queries that can be performed
* on this pad. * on this pad.
* *
* Returns: a zero-terminated array of #GstQueryType. * Returns: (transfer none) (array zero-terminated=1): a zero-terminated array
* of #GstQueryType.
*/ */
const GstQueryType * const GstQueryType *
gst_pad_get_query_types (GstPad * pad) gst_pad_get_query_types (GstPad * pad)
@ -1457,8 +1458,9 @@ gst_pad_get_query_types_dispatcher (GstPad * pad, const GstQueryType ** data)
* Invoke the default dispatcher for the query types on * Invoke the default dispatcher for the query types on
* the pad. * the pad.
* *
* Returns: an zero-terminated array of #GstQueryType, or NULL if none of the * Returns: (transfer none) (array zero-terminated=1): a zero-terminated array
* internally-linked pads has a query types function. * of #GstQueryType, or NULL if none of the internally-linked pads has a
* query types function.
*/ */
const GstQueryType * const GstQueryType *
gst_pad_get_query_types_default (GstPad * pad) gst_pad_get_query_types_default (GstPad * pad)
@ -2182,8 +2184,8 @@ gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ)
* *
* Gets the template for @pad. * Gets the template for @pad.
* *
* Returns: the #GstPadTemplate from which this pad was instantiated, or %NULL * Returns: (transfer none): the #GstPadTemplate from which this pad was
* if this pad has no template. * instantiated, or %NULL if this pad has no template.
* *
* FIXME: currently returns an unrefcounted padtemplate. * FIXME: currently returns an unrefcounted padtemplate.
*/ */
@ -2281,7 +2283,7 @@ done:
* Gets the capabilities this pad can produce or consume. Preferred function if * Gets the capabilities this pad can produce or consume. Preferred function if
* one only wants to read or intersect the caps. * one only wants to read or intersect the caps.
* *
* Returns: the caps of the pad with incremented ref-count. * Returns: (transfer full): the caps of the pad with incremented ref-count.
* *
* Since: 0.10.26 * Since: 0.10.26
*/ */
@ -2314,7 +2316,7 @@ gst_pad_get_caps_reffed (GstPad * pad)
* the pad's get_caps function; * the pad's get_caps function;
* this returns the pad template caps if not explicitly set. * this returns the pad template caps if not explicitly set.
* *
* Returns: a newly allocated copy of the #GstCaps of this pad. * Returns: (transfer full): a newly allocated copy of the #GstCaps of this pad
* *
* MT safe. * MT safe.
*/ */
@ -2340,7 +2342,7 @@ gst_pad_get_caps (GstPad * pad)
* Gets the capabilities of the peer connected to this pad. Preferred function * Gets the capabilities of the peer connected to this pad. Preferred function
* if one only wants to read or intersect the caps. * if one only wants to read or intersect the caps.
* *
* Returns: the caps of the pad with incremented ref-count. * Returns: (transfer full): the caps of the pad with incremented ref-count
* *
* Since: 0.10.26 * Since: 0.10.26
*/ */
@ -2383,9 +2385,9 @@ no_peer:
* Gets the capabilities of the peer connected to this pad. Similar to * Gets the capabilities of the peer connected to this pad. Similar to
* gst_pad_get_caps(). * gst_pad_get_caps().
* *
* Returns: a newly allocated copy of the #GstCaps of the peer pad. Use * Returns: (transfer full): a newly allocated copy of the #GstCaps of the
* gst_caps_unref() to get rid of it. This function returns %NULL if there is * peer pad. Use gst_caps_unref() to get rid of it. This function
* no peer pad. * returns %NULL if there is no peer pad.
*/ */
GstCaps * GstCaps *
gst_pad_peer_get_caps (GstPad * pad) gst_pad_peer_get_caps (GstPad * pad)
@ -2649,7 +2651,7 @@ no_peer:
/** /**
* gst_pad_set_caps: * gst_pad_set_caps:
* @pad: a #GstPad to set the capabilities of. * @pad: a #GstPad to set the capabilities of.
* @caps: a #GstCaps to set. * @caps: (transfer none): a #GstCaps to set.
* *
* Sets the capabilities of this pad. The caps must be fixed. Any previous * Sets the capabilities of this pad. The caps must be fixed. Any previous
* caps on the pad will be unreffed. This function refs the caps so you should * caps on the pad will be unreffed. This function refs the caps so you should
@ -2792,8 +2794,8 @@ not_accepted:
* *
* Gets the capabilities for @pad's template. * Gets the capabilities for @pad's template.
* *
* Returns: the #GstCaps of this pad template. If you intend to keep a * Returns: (transfer none): the #GstCaps of this pad template. If you intend
* reference on the caps, make a copy (see gst_caps_copy ()). * to keep a reference on the caps, make a copy (see gst_caps_copy ()).
*/ */
const GstCaps * const GstCaps *
gst_pad_get_pad_template_caps (GstPad * pad) gst_pad_get_pad_template_caps (GstPad * pad)
@ -2815,7 +2817,7 @@ gst_pad_get_pad_template_caps (GstPad * pad)
* Gets the peer of @pad. This function refs the peer pad so * Gets the peer of @pad. This function refs the peer pad so
* you need to unref it after use. * you need to unref it after use.
* *
* Returns: the peer #GstPad. Unref after usage. * Returns: (transfer full): the peer #GstPad. Unref after usage.
* *
* MT safe. * MT safe.
*/ */
@ -2846,8 +2848,9 @@ gst_pad_get_peer (GstPad * pad)
* calling gst_pad_get_caps() on @pad and its peer. The caller owns a reference * calling gst_pad_get_caps() on @pad and its peer. The caller owns a reference
* on the resulting caps. * on the resulting caps.
* *
* Returns: the allowed #GstCaps of the pad link. Unref the caps when you no * Returns: (transfer full): the allowed #GstCaps of the pad link. Unref the
* longer need it. This function returns NULL when @pad has no peer. * caps when you no longer need it. This function returns NULL when @pad
* has no peer.
* *
* MT safe. * MT safe.
*/ */
@ -2905,9 +2908,9 @@ no_peer:
* always negotiated before sinkpads so it is possible that the negotiated caps * always negotiated before sinkpads so it is possible that the negotiated caps
* on the srcpad do not match the negotiated caps of the peer. * on the srcpad do not match the negotiated caps of the peer.
* *
* Returns: the negotiated #GstCaps of the pad link. Unref the caps when * Returns: (transfer full): the negotiated #GstCaps of the pad link. Unref
* you no longer need it. This function returns NULL when the @pad has no * the caps when you no longer need it. This function returns NULL when
* peer or is not negotiated yet. * the @pad has no peer or is not negotiated yet.
* *
* MT safe. * MT safe.
*/ */
@ -3174,8 +3177,8 @@ gst_pad_alloc_buffer (GstPad * pad, guint64 offset, gint size, GstCaps * caps,
* @pad: a source #GstPad * @pad: a source #GstPad
* @offset: the offset of the new buffer in the stream * @offset: the offset of the new buffer in the stream
* @size: the size of the new buffer * @size: the size of the new buffer
* @caps: the caps of the new buffer * @caps: (transfer none): the caps of the new buffer
* @buf: a newly allocated buffer * @buf: (out callee-allocates): a newly allocated buffer
* *
* In addition to the function gst_pad_alloc_buffer(), this function * In addition to the function gst_pad_alloc_buffer(), this function
* automatically calls gst_pad_set_caps() when the caps of the * automatically calls gst_pad_set_caps() when the caps of the
@ -3331,8 +3334,11 @@ no_parent:
* Each #GstPad element yielded by the iterator will have its refcount increased, * Each #GstPad element yielded by the iterator will have its refcount increased,
* so unref after use. * so unref after use.
* *
* Returns: a new #GstIterator of #GstPad or %NULL when the pad does not have an * Free-function: gst_iterator_free
* iterator function configured. Use gst_iterator_free() after usage. *
* Returns: (transfer full): a new #GstIterator of #GstPad or %NULL when the
* pad does not have an iterator function configured. Use
* gst_iterator_free() after usage.
* *
* Since: 0.10.21 * Since: 0.10.21
*/ */
@ -3369,7 +3375,8 @@ add_unref_pad_to_list (GstPad * pad, GList ** list)
* *
* The caller must free this list after use with g_list_free(). * The caller must free this list after use with g_list_free().
* *
* Returns: a newly allocated #GList of pads, or NULL if the pad has no parent. * Returns: (transfer full) (element-type Gst.Pad): a newly allocated #GList
* of pads, or NULL if the pad has no parent.
* *
* Not MT safe. * Not MT safe.
* *
@ -3466,7 +3473,8 @@ no_parent:
* *
* Not MT safe. * Not MT safe.
* *
* Returns: a newly allocated #GList of pads, free with g_list_free(). * Returns: (transfer full) (element-type Gst.Pad): a newly allocated #GList
* of pads, free with g_list_free().
* *
* Deprecated: This function does not ref the pads in the list so that they * Deprecated: This function does not ref the pads in the list so that they
* could become invalid by the time the application accesses them. It's also * could become invalid by the time the application accesses them. It's also
@ -3584,7 +3592,7 @@ no_iter:
/** /**
* gst_pad_event_default: * gst_pad_event_default:
* @pad: a #GstPad to call the default event handler on. * @pad: a #GstPad to call the default event handler on.
* @event: the #GstEvent to handle. * @event: (transfer full): the #GstEvent to handle.
* *
* Invokes the default event handler for the given pad. End-of-stream and * Invokes the default event handler for the given pad. End-of-stream and
* discontinuity events are handled specially, and then the event is sent to all * discontinuity events are handled specially, and then the event is sent to all
@ -3620,7 +3628,7 @@ gst_pad_event_default (GstPad * pad, GstEvent * event)
* gst_pad_dispatcher: * gst_pad_dispatcher:
* @pad: a #GstPad to dispatch. * @pad: a #GstPad to dispatch.
* @dispatch: the #GstPadDispatcherFunction to call. * @dispatch: the #GstPadDispatcherFunction to call.
* @data: gpointer user data passed to the dispatcher function. * @data: (closure): gpointer user data passed to the dispatcher function.
* *
* Invokes the given dispatcher function on each respective peer of * Invokes the given dispatcher function on each respective peer of
* all pads that are internally linked to the given pad. * all pads that are internally linked to the given pad.
@ -3688,7 +3696,7 @@ no_iter:
/** /**
* gst_pad_query: * gst_pad_query:
* @pad: a #GstPad to invoke the default query on. * @pad: a #GstPad to invoke the default query on.
* @query: the #GstQuery to perform. * @query: (transfer none): the #GstQuery to perform.
* *
* Dispatches a query to a pad. The query should have been allocated by the * Dispatches a query to a pad. The query should have been allocated by the
* caller via one of the type-specific allocation functions. The element that * caller via one of the type-specific allocation functions. The element that
@ -3728,7 +3736,7 @@ no_func:
/** /**
* gst_pad_peer_query: * gst_pad_peer_query:
* @pad: a #GstPad to invoke the peer query on. * @pad: a #GstPad to invoke the peer query on.
* @query: the #GstQuery to perform. * @query: (transfer none): the #GstQuery to perform.
* *
* Performs gst_pad_query() on the peer of @pad. * Performs gst_pad_query() on the peer of @pad.
* *
@ -3778,7 +3786,7 @@ no_peer:
/** /**
* gst_pad_query_default: * gst_pad_query_default:
* @pad: a #GstPad to call the default query handler on. * @pad: a #GstPad to call the default query handler on.
* @query: the #GstQuery to handle. * @query: (transfer none): the #GstQuery to handle.
* *
* Invokes the default query handler for the given pad. * Invokes the default query handler for the given pad.
* The query is sent to all pads internally linked to @pad. Note that * The query is sent to all pads internally linked to @pad. Note that
@ -4322,7 +4330,8 @@ no_function:
/** /**
* gst_pad_chain: * gst_pad_chain:
* @pad: a sink #GstPad, returns GST_FLOW_ERROR if not. * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
* @buffer: the #GstBuffer to send, return GST_FLOW_ERROR if not. * @buffer: (transfer full): the #GstBuffer to send, return GST_FLOW_ERROR
* if not.
* *
* Chain a buffer to @pad. * Chain a buffer to @pad.
* *
@ -4358,7 +4367,8 @@ gst_pad_chain (GstPad * pad, GstBuffer * buffer)
/** /**
* gst_pad_chain_list: * gst_pad_chain_list:
* @pad: a sink #GstPad, returns GST_FLOW_ERROR if not. * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
* @list: the #GstBufferList to send, return GST_FLOW_ERROR if not. * @list: (transfer full): the #GstBufferList to send, return GST_FLOW_ERROR
* if not.
* *
* Chain a bufferlist to @pad. * Chain a bufferlist to @pad.
* *
@ -4594,7 +4604,8 @@ _priv_gst_pad_invalidate_cache (GstPad * pad)
/** /**
* gst_pad_push: * gst_pad_push:
* @pad: a source #GstPad, returns #GST_FLOW_ERROR if not. * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
* @buffer: the #GstBuffer to push returns GST_FLOW_ERROR if not. * @buffer: (transfer full): the #GstBuffer to push returns GST_FLOW_ERROR
* if not.
* *
* Pushes a buffer to the peer of @pad. * Pushes a buffer to the peer of @pad.
* *
@ -4691,7 +4702,8 @@ slow_path:
/** /**
* gst_pad_push_list: * gst_pad_push_list:
* @pad: a source #GstPad, returns #GST_FLOW_ERROR if not. * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
* @list: the #GstBufferList to push returns GST_FLOW_ERROR if not. * @list: (transfer full): the #GstBufferList to push returns GST_FLOW_ERROR
* if not.
* *
* Pushes a buffer list to the peer of @pad. * Pushes a buffer list to the peer of @pad.
* *
@ -4965,7 +4977,8 @@ not_negotiated:
* @pad: a src #GstPad, returns #GST_FLOW_ERROR if not. * @pad: a src #GstPad, returns #GST_FLOW_ERROR if not.
* @offset: The start offset of the buffer * @offset: The start offset of the buffer
* @size: The length of the buffer * @size: The length of the buffer
* @buffer: a pointer to hold the #GstBuffer, returns #GST_FLOW_ERROR if %NULL. * @buffer: (out callee-allocates): a pointer to hold the #GstBuffer,
* returns #GST_FLOW_ERROR if %NULL.
* *
* When @pad is flushing this function returns #GST_FLOW_WRONG_STATE * When @pad is flushing this function returns #GST_FLOW_WRONG_STATE
* immediatly and @buffer is %NULL. * immediatly and @buffer is %NULL.
@ -4997,7 +5010,8 @@ gst_pad_get_range (GstPad * pad, guint64 offset, guint size,
* @pad: a sink #GstPad, returns GST_FLOW_ERROR if not. * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
* @offset: The start offset of the buffer * @offset: The start offset of the buffer
* @size: The length of the buffer * @size: The length of the buffer
* @buffer: a pointer to hold the #GstBuffer, returns GST_FLOW_ERROR if %NULL. * @buffer: (out callee-allocates): a pointer to hold the #GstBuffer, returns
* GST_FLOW_ERROR if %NULL.
* *
* Pulls a @buffer from the peer pad. * Pulls a @buffer from the peer pad.
* *
@ -5115,7 +5129,7 @@ not_negotiated:
/** /**
* gst_pad_push_event: * gst_pad_push_event:
* @pad: a #GstPad to push the event to. * @pad: a #GstPad to push the event to.
* @event: the #GstEvent to send to the pad. * @event: (transfer full): the #GstEvent to send to the pad.
* *
* Sends the event to the peer of the given pad. This function is * Sends the event to the peer of the given pad. This function is
* mainly used by elements to send events to their peer * mainly used by elements to send events to their peer
@ -5236,7 +5250,7 @@ flushed:
/** /**
* gst_pad_send_event: * gst_pad_send_event:
* @pad: a #GstPad to send the event to. * @pad: a #GstPad to send the event to.
* @event: the #GstEvent to send to the pad. * @event: (transfer full): the #GstEvent to send to the pad.
* *
* Sends the event to the pad. This function can be used * Sends the event to the pad. This function can be used
* by applications to send events in the pipeline. * by applications to send events in the pipeline.

13
gst/gstpadtemplate.c
View file

@ -307,7 +307,7 @@ gst_static_pad_template_get_type (void)
* *
* Converts a #GstStaticPadTemplate into a #GstPadTemplate. * Converts a #GstStaticPadTemplate into a #GstPadTemplate.
* *
* Returns: a new #GstPadTemplate. * Returns: (transfer full): a new #GstPadTemplate.
*/ */
/* FIXME0.11: rename to gst_pad_template_new_from_static_pad_template() */ /* FIXME0.11: rename to gst_pad_template_new_from_static_pad_template() */
GstPadTemplate * GstPadTemplate *
@ -337,13 +337,14 @@ gst_static_pad_template_get (GstStaticPadTemplate * pad_template)
* @name_template: the name template. * @name_template: the name template.
* @direction: the #GstPadDirection of the template. * @direction: the #GstPadDirection of the template.
* @presence: the #GstPadPresence of the pad. * @presence: the #GstPadPresence of the pad.
* @caps: a #GstCaps set for the template. The caps are taken ownership of. * @caps: (transfer full): a #GstCaps set for the template. The caps are
* taken ownership of.
* *
* Creates a new pad template with a name according to the given template * Creates a new pad template with a name according to the given template
* and with the given arguments. This functions takes ownership of the provided * and with the given arguments. This functions takes ownership of the provided
* caps, so be sure to not use them afterwards. * caps, so be sure to not use them afterwards.
* *
* Returns: a new #GstPadTemplate. * Returns: (transfer full): a new #GstPadTemplate.
*/ */
GstPadTemplate * GstPadTemplate *
gst_pad_template_new (const gchar * name_template, gst_pad_template_new (const gchar * name_template,
@ -378,7 +379,7 @@ gst_pad_template_new (const gchar * name_template,
* *
* Gets the capabilities of the static pad template. * Gets the capabilities of the static pad template.
* *
* Returns: the #GstCaps of the static pad template. * Returns: (transfer full): the #GstCaps of the static pad template.
* Unref after usage. Since the core holds an additional * Unref after usage. Since the core holds an additional
* ref to the returned caps, use gst_caps_make_writable() * ref to the returned caps, use gst_caps_make_writable()
* on the returned caps to modify it. * on the returned caps to modify it.
@ -397,8 +398,8 @@ gst_static_pad_template_get_caps (GstStaticPadTemplate * templ)
* *
* Gets the capabilities of the pad template. * Gets the capabilities of the pad template.
* *
* Returns: the #GstCaps of the pad template. If you need to keep a reference to * Returns: (transfer none): the #GstCaps of the pad template. If you need to
* the caps, take a ref (see gst_caps_ref ()). * keep a reference to the caps, take a ref (see gst_caps_ref ()).
*/ */
GstCaps * GstCaps *
gst_pad_template_get_caps (GstPadTemplate * templ) gst_pad_template_get_caps (GstPadTemplate * templ)

45
gst/gstparse.c
View file

@ -68,8 +68,10 @@ gst_parse_error_quark (void)
* Allocates a parse context for use with gst_parse_launch_full() or * Allocates a parse context for use with gst_parse_launch_full() or
* gst_parse_launchv_full(). * gst_parse_launchv_full().
* *
* Returns: a newly-allocated parse context. Free with gst_parse_context_free() * Free-function: gst_parse_context_free
* when no longer needed. *
* Returns: (transfer full): a newly-allocated parse context. Free with
* gst_parse_context_free() when no longer needed.
* *
* Since: 0.10.20 * Since: 0.10.20
*/ */
@ -90,7 +92,7 @@ gst_parse_context_new (void)
/** /**
* gst_parse_context_free: * gst_parse_context_free:
* @context: a #GstParseContext * @context: (transfer full): a #GstParseContext
* *
* Frees a parse context previously allocated with gst_parse_context_new(). * Frees a parse context previously allocated with gst_parse_context_new().
* *
@ -116,8 +118,9 @@ gst_parse_context_free (GstParseContext * context)
* or gst_parse_launchv_full(). Will only return results if an error code * or gst_parse_launchv_full(). Will only return results if an error code
* of %GST_PARSE_ERROR_NO_SUCH_ELEMENT was returned. * of %GST_PARSE_ERROR_NO_SUCH_ELEMENT was returned.
* *
* Returns: a NULL-terminated array of element factory name strings of * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*): a
* missing elements. Free with g_strfreev() when no longer needed. * NULL-terminated array of element factory name strings of missing
* elements. Free with g_strfreev() when no longer needed.
* *
* Since: 0.10.20 * Since: 0.10.20
*/ */
@ -172,14 +175,14 @@ _gst_parse_escape (const gchar * str)
/** /**
* gst_parse_launchv: * gst_parse_launchv:
* @argv: null-terminated array of arguments * @argv: (in) (array zero-terminated=1): null-terminated array of arguments
* @error: pointer to a #GError * @error: pointer to a #GError
* *
* Create a new element based on command line syntax. * Create a new element based on command line syntax.
* @error will contain an error message if an erroneuos pipeline is specified. * @error will contain an error message if an erroneuos pipeline is specified.
* An error does not mean that the pipeline could not be constructed. * An error does not mean that the pipeline could not be constructed.
* *
* Returns: a new element on success and %NULL on failure. * Returns: (transfer full): a new element on success and %NULL on failure.
*/ */
GstElement * GstElement *
gst_parse_launchv (const gchar ** argv, GError ** error) gst_parse_launchv (const gchar ** argv, GError ** error)
@ -189,8 +192,9 @@ gst_parse_launchv (const gchar ** argv, GError ** error)
/** /**
* gst_parse_launchv_full: * gst_parse_launchv_full:
* @argv: null-terminated array of arguments * @argv: (in) (array zero-terminated=1): null-terminated array of arguments
* @context: a parse context allocated with gst_parse_context_new(), or %NULL * @context: (allow-none): a parse context allocated with
* gst_parse_context_new(), or %NULL
* @flags: parsing options, or #GST_PARSE_FLAG_NONE * @flags: parsing options, or #GST_PARSE_FLAG_NONE
* @error: pointer to a #GError (which must be initialised to %NULL) * @error: pointer to a #GError (which must be initialised to %NULL)
* *
@ -198,10 +202,10 @@ gst_parse_launchv (const gchar ** argv, GError ** error)
* @error will contain an error message if an erroneous pipeline is specified. * @error will contain an error message if an erroneous pipeline is specified.
* An error does not mean that the pipeline could not be constructed. * An error does not mean that the pipeline could not be constructed.
* *
* Returns: a new element on success; on failure, either %NULL or a * Returns: (transfer full): a new element on success; on failure, either %NULL
* partially-constructed bin or element will be returned and @error will be set * or a partially-constructed bin or element will be returned and @error will
* (unless you passed #GST_PARSE_FLAG_FATAL_ERRORS in @flags, then %NULL will * be set (unless you passed #GST_PARSE_FLAG_FATAL_ERRORS in @flags, then
* always be returned on failure) * %NULL will always be returned on failure)
* *
* Since: 0.10.20 * Since: 0.10.20
*/ */
@ -252,9 +256,9 @@ gst_parse_launchv_full (const gchar ** argv, GstParseContext * context,
* the @error is set. In this case there was a recoverable parsing error and you * the @error is set. In this case there was a recoverable parsing error and you
* can try to play the pipeline. * can try to play the pipeline.
* *
* Returns: a new element on success, %NULL on failure. If more than one toplevel * Returns: (transfer full): a new element on success, %NULL on failure. If
* element is specified by the @pipeline_description, all elements are put into * more than one toplevel element is specified by the @pipeline_description,
* a #GstPipeline, which than is returned. * all elements are put into a #GstPipeline, which than is returned.
*/ */
GstElement * GstElement *
gst_parse_launch (const gchar * pipeline_description, GError ** error) gst_parse_launch (const gchar * pipeline_description, GError ** error)
@ -265,7 +269,8 @@ gst_parse_launch (const gchar * pipeline_description, GError ** error)
/** /**
* gst_parse_launch_full: * gst_parse_launch_full:
* @pipeline_description: the command line describing the pipeline * @pipeline_description: the command line describing the pipeline
* @context: a parse context allocated with gst_parse_context_new(), or %NULL * @context: (allow-none): a parse context allocated with
* gst_parse_context_new(), or %NULL
* @flags: parsing options, or #GST_PARSE_FLAG_NONE * @flags: parsing options, or #GST_PARSE_FLAG_NONE
* @error: the error message in case of an erroneous pipeline. * @error: the error message in case of an erroneous pipeline.
* *
@ -274,9 +279,9 @@ gst_parse_launch (const gchar * pipeline_description, GError ** error)
* the @error is set. In this case there was a recoverable parsing error and you * the @error is set. In this case there was a recoverable parsing error and you
* can try to play the pipeline. * can try to play the pipeline.
* *
* Returns: a new element on success, %NULL on failure. If more than one toplevel * Returns: (transfer full): a new element on success, %NULL on failure. If
* element is specified by the @pipeline_description, all elements are put into * more than one toplevel element is specified by the @pipeline_description,
* a #GstPipeline, which then is returned. * all elements are put into a #GstPipeline, which then is returned.
* *
* Since: 0.10.20 * Since: 0.10.20
*/ */

10
gst/gstpipeline.c
View file

@ -310,7 +310,7 @@ reset_start_time (GstPipeline * pipeline)
* *
* Create a new pipeline with the given name. * Create a new pipeline with the given name.
* *
* Returns: newly created GstPipeline * Returns: (transfer full): newly created GstPipeline
* *
* MT safe. * MT safe.
*/ */
@ -594,7 +594,7 @@ gst_pipeline_handle_message (GstBin * bin, GstMessage * message)
* Gets the #GstBus of @pipeline. The bus allows applications to receive * Gets the #GstBus of @pipeline. The bus allows applications to receive
* #GstMessage packets. * #GstMessage packets.
* *
* Returns: a #GstBus, unref after usage. * Returns: (transfer full): a #GstBus, unref after usage.
* *
* MT safe. * MT safe.
*/ */
@ -720,7 +720,7 @@ gst_pipeline_provide_clock_func (GstElement * element)
* *
* Gets the current clock used by @pipeline. * Gets the current clock used by @pipeline.
* *
* Returns: a #GstClock, unref after usage. * Returns: (transfer full): a #GstClock, unref after usage.
*/ */
GstClock * GstClock *
gst_pipeline_get_clock (GstPipeline * pipeline) gst_pipeline_get_clock (GstPipeline * pipeline)
@ -734,7 +734,7 @@ gst_pipeline_get_clock (GstPipeline * pipeline)
/** /**
* gst_pipeline_use_clock: * gst_pipeline_use_clock:
* @pipeline: a #GstPipeline * @pipeline: a #GstPipeline
* @clock: the clock to use * @clock: (transfer none): the clock to use
* *
* Force @pipeline to use the given @clock. The pipeline will * Force @pipeline to use the given @clock. The pipeline will
* always use the given clock even if new clock providers are added * always use the given clock even if new clock providers are added
@ -766,7 +766,7 @@ gst_pipeline_use_clock (GstPipeline * pipeline, GstClock * clock)
/** /**
* gst_pipeline_set_clock: * gst_pipeline_set_clock:
* @pipeline: a #GstPipeline * @pipeline: a #GstPipeline
* @clock: the clock to set * @clock: (transfer none): the clock to set
* *
* Set the clock for @pipeline. The clock will be distributed * Set the clock for @pipeline. The clock will be distributed
* to all the elements managed by the pipeline. * to all the elements managed by the pipeline.

16
gst/gstplugin.c
View file

@ -1025,8 +1025,8 @@ gst_plugin_get_origin (GstPlugin * plugin)
* Gets the #GModule of the plugin. If the plugin isn't loaded yet, NULL is * Gets the #GModule of the plugin. If the plugin isn't loaded yet, NULL is
* returned. * returned.
* *
* Returns: module belonging to the plugin or NULL if the plugin isn't * Returns: (transfer none): module belonging to the plugin or NULL if the
* loaded yet. * plugin isn't loaded yet.
*/ */
GModule * GModule *
gst_plugin_get_module (GstPlugin * plugin) gst_plugin_get_module (GstPlugin * plugin)
@ -1059,7 +1059,7 @@ gst_plugin_is_loaded (GstPlugin * plugin)
* Gets the plugin specific data cache. If it is %NULL there is no cached data * Gets the plugin specific data cache. If it is %NULL there is no cached data
* stored. This is the case when the registry is getting rebuilt. * stored. This is the case when the registry is getting rebuilt.
* *
* Returns: The cached data as a #GstStructure or %NULL. * Returns: (transfer none): The cached data as a #GstStructure or %NULL.
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -1074,7 +1074,7 @@ gst_plugin_get_cache_data (GstPlugin * plugin)
/** /**
* gst_plugin_set_cache_data: * gst_plugin_set_cache_data:
* @plugin: a plugin * @plugin: a plugin
* @cache_data: a structure containing the data to cache * @cache_data: (transfer full): a structure containing the data to cache
* *
* Adds plugin specific data to cache. Passes the ownership of the structure to * Adds plugin specific data to cache. Passes the ownership of the structure to
* the @plugin. * the @plugin.
@ -1281,7 +1281,7 @@ gst_plugin_find_feature_by_name (GstPlugin * plugin, const gchar * name)
* *
* Load the named plugin. Refs the plugin. * Load the named plugin. Refs the plugin.
* *
* Returns: A reference to a loaded plugin, or NULL on error. * Returns: (transfer full): a reference to a loaded plugin, or NULL on error.
*/ */
GstPlugin * GstPlugin *
gst_plugin_load_by_name (const gchar * name) gst_plugin_load_by_name (const gchar * name)
@ -1311,7 +1311,7 @@ gst_plugin_load_by_name (const gchar * name)
/** /**
* gst_plugin_load: * gst_plugin_load:
* @plugin: plugin to load * @plugin: (transfer none): plugin to load
* *
* Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is * Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is
* untouched. The normal use pattern of this function goes like this: * untouched. The normal use pattern of this function goes like this:
@ -1324,7 +1324,7 @@ gst_plugin_load_by_name (const gchar * name)
* plugin = loaded_plugin; * plugin = loaded_plugin;
* </programlisting> * </programlisting>
* *
* Returns: A reference to a loaded plugin, or NULL on error. * Returns: (transfer full): a reference to a loaded plugin, or NULL on error.
*/ */
GstPlugin * GstPlugin *
gst_plugin_load (GstPlugin * plugin) gst_plugin_load (GstPlugin * plugin)
@ -1351,7 +1351,7 @@ load_error:
/** /**
* gst_plugin_list_free: * gst_plugin_list_free:
* @list: list of #GstPlugin * @list: (transfer full) (element-type Gst.Plugin): list of #GstPlugin
* *
* Unrefs each member of @list, then frees the list. * Unrefs each member of @list, then frees the list.
*/ */

18
gst/gstpluginfeature.c
View file

@ -72,7 +72,7 @@ gst_plugin_feature_finalize (GObject * object)
/** /**
* gst_plugin_feature_load: * gst_plugin_feature_load:
* @feature: the plugin feature to check * @feature: (transfer none): the plugin feature to check
* *
* Loads the plugin containing @feature if it's not already loaded. @feature is * Loads the plugin containing @feature if it's not already loaded. @feature is
* unaffected; use the return value instead. * unaffected; use the return value instead.
@ -87,7 +87,7 @@ gst_plugin_feature_finalize (GObject * object)
* feature = loaded_feature; * feature = loaded_feature;
* ]| * ]|
* *
* Returns: A reference to the loaded feature, or NULL on error. * Returns: (transfer full): a reference to the loaded feature, or NULL on error
*/ */
GstPluginFeature * GstPluginFeature *
gst_plugin_feature_load (GstPluginFeature * feature) gst_plugin_feature_load (GstPluginFeature * feature)
@ -146,7 +146,7 @@ not_found:
/** /**
* gst_plugin_feature_type_name_filter: * gst_plugin_feature_type_name_filter:
* @feature: the #GstPluginFeature * @feature: the #GstPluginFeature
* @data: the type and name to check against * @data: (in): the type and name to check against
* *
* Compares type and name of plugin feature. Can be used with gst_filter_run(). * Compares type and name of plugin feature. Can be used with gst_filter_run().
* *
@ -238,7 +238,8 @@ gst_plugin_feature_get_rank (GstPluginFeature * feature)
/** /**
* gst_plugin_feature_list_free: * gst_plugin_feature_list_free:
* @list: list of #GstPluginFeature * @list: (transfer full) (element-type Gst.PluginFeature): list
* of #GstPluginFeature
* *
* Unrefs each member of @list, then frees the list. * Unrefs each member of @list, then frees the list.
*/ */
@ -257,12 +258,14 @@ gst_plugin_feature_list_free (GList * list)
/** /**
* gst_plugin_feature_list_copy: * gst_plugin_feature_list_copy:
* @list: list of #GstPluginFeature * @list: (transfer none) (element-type Gst.PluginFeature): list
* of #GstPluginFeature
* *
* Copies the list of features. Caller should call @gst_plugin_feature_list_free * Copies the list of features. Caller should call @gst_plugin_feature_list_free
* when done with the list. * when done with the list.
* *
* Returns: a copy of @list, with each feature's reference count incremented. * Returns: (transfer full) (element-type Gst.PluginFeature): a copy of @list,
* with each feature's reference count incremented.
* *
* Since: 0.10.26 * Since: 0.10.26
*/ */
@ -294,7 +297,8 @@ gst_plugin_feature_list_copy (GList * list)
/** /**
* gst_plugin_feature_list_debug: * gst_plugin_feature_list_debug:
* @list: a #GList of plugin features * @list: (transfer none) (element-type Gst.PluginFeature): a #GList of
* plugin features
* *
* Debug the plugin feature names in @list. * Debug the plugin feature names in @list.
* *

14
gst/gstpoll.c
View file

@ -533,8 +533,10 @@ gst_poll_collect_winsock_events (GstPoll * set)
* is possible to restart or flush a call to gst_poll_wait() with * is possible to restart or flush a call to gst_poll_wait() with
* gst_poll_restart() and gst_poll_set_flushing() respectively. * gst_poll_restart() and gst_poll_set_flushing() respectively.
* *
* Returns: a new #GstPoll, or %NULL in case of an error. Free with * Free-function: gst_poll_free
* gst_poll_free(). *
* Returns: (transfer full): a new #GstPoll, or %NULL in case of an error.
* Free with gst_poll_free().
* *
* Since: 0.10.18 * Since: 0.10.18
*/ */
@ -603,8 +605,10 @@ no_socket_pair:
* A timeout is performed with gst_poll_wait(). Multiple timeouts can be * A timeout is performed with gst_poll_wait(). Multiple timeouts can be
* performed from different threads. * performed from different threads.
* *
* Returns: a new #GstPoll, or %NULL in case of an error. Free with * Free-function: gst_poll_free
* gst_poll_free(). *
* Returns: (transfer full): a new #GstPoll, or %NULL in case of an error.
* Free with gst_poll_free().
* *
* Since: 0.10.23 * Since: 0.10.23
*/ */
@ -626,7 +630,7 @@ done:
/** /**
* gst_poll_free: * gst_poll_free:
* @set: a file descriptor set. * @set: (transfer full): a file descriptor set.
* *
* Free a file descriptor set. * Free a file descriptor set.
* *

8
gst/gstpreset.c
View file

@ -867,7 +867,8 @@ no_presets:
* *
* Get a copy of preset names as a NULL terminated string array. * Get a copy of preset names as a NULL terminated string array.
* *
* Returns: list with names, ue g_strfreev() after usage. * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*):
* list with names, ue g_strfreev() after usage.
* *
* Since: 0.10.20 * Since: 0.10.20
*/ */
@ -885,7 +886,8 @@ gst_preset_get_preset_names (GstPreset * preset)
* *
* Get a the names of the GObject properties that can be used for presets. * Get a the names of the GObject properties that can be used for presets.
* *
* Returns: an array of property names which should be freed with g_strfreev() after use. * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*): an
* array of property names which should be freed with g_strfreev() after use.
* *
* Since: 0.10.20 * Since: 0.10.20
*/ */
@ -1014,7 +1016,7 @@ gst_preset_set_meta (GstPreset * preset, const gchar * name, const gchar * tag,
* @preset: a #GObject that implements #GstPreset * @preset: a #GObject that implements #GstPreset
* @name: preset name * @name: preset name
* @tag: meta data item name * @tag: meta data item name
* @value: value * @value: (out callee-allocates): value
* *
* Gets the @value for an existing meta data @tag. Meta data @tag names can be * Gets the @value for an existing meta data @tag. Meta data @tag names can be
* something like e.g. "comment". Returned values need to be released when done. * something like e.g. "comment". Returned values need to be released when done.

126
gst/gstquery.c
View file

@ -334,7 +334,9 @@ gst_query_type_get_details (GstQueryType type)
* Get a #GstIterator of all the registered query types. The definitions * Get a #GstIterator of all the registered query types. The definitions
* iterated over are read only. * iterated over are read only.
* *
* Returns: A #GstIterator of #GstQueryTypeDefinition. * Free-function: gst_iterator_free
*
* Returns: (transfer full): a #GstIterator of #GstQueryTypeDefinition.
*/ */
GstIterator * GstIterator *
gst_query_type_iterate_definitions (void) gst_query_type_iterate_definitions (void)
@ -381,7 +383,9 @@ gst_query_new (GstQueryType type, GstStructure * structure)
* when done with it. A position query is used to query the current position * when done with it. A position query is used to query the current position
* of playback in the streams, in some format. * of playback in the streams, in some format.
* *
* Returns: A #GstQuery * Free-function: gst_query_unref
*
* Returns: (transfer full): a new #GstQuery
*/ */
GstQuery * GstQuery *
gst_query_new_position (GstFormat format) gst_query_new_position (GstFormat format)
@ -419,8 +423,9 @@ gst_query_set_position (GstQuery * query, GstFormat format, gint64 cur)
/** /**
* gst_query_parse_position: * gst_query_parse_position:
* @query: a #GstQuery * @query: a #GstQuery
* @format: (out): the storage for the #GstFormat of the position values (may be NULL) * @format: (out) (allow-none): the storage for the #GstFormat of the
* @cur: (out): the storage for the current position (may be NULL) * position values (may be NULL)
* @cur: (out) (allow-none): the storage for the current position (may be NULL)
* *
* Parse a position query, writing the format into @format, and the position * Parse a position query, writing the format into @format, and the position
* into @cur, if the respective parameters are non-NULL. * into @cur, if the respective parameters are non-NULL.
@ -450,7 +455,9 @@ gst_query_parse_position (GstQuery * query, GstFormat * format, gint64 * cur)
* Use gst_query_unref() when done with it. A duration query will give the * Use gst_query_unref() when done with it. A duration query will give the
* total length of the stream. * total length of the stream.
* *
* Returns: A #GstQuery * Free-function: gst_query_unref
*
* Returns: (transfer full): a new #GstQuery
*/ */
GstQuery * GstQuery *
gst_query_new_duration (GstFormat format) gst_query_new_duration (GstFormat format)
@ -488,8 +495,9 @@ gst_query_set_duration (GstQuery * query, GstFormat format, gint64 duration)
/** /**
* gst_query_parse_duration: * gst_query_parse_duration:
* @query: a #GstQuery * @query: a #GstQuery
* @format: (out): the storage for the #GstFormat of the duration value, or NULL. * @format: (out) (allow-none): the storage for the #GstFormat of the duration
* @duration: (out): the storage for the total duration, or NULL. * value, or NULL.
* @duration: (out) (allow-none): the storage for the total duration, or NULL.
* *
* Parse a duration query answer. Write the format of the duration into @format, * Parse a duration query answer. Write the format of the duration into @format,
* and the value into @duration, if the respective variables are non-NULL. * and the value into @duration, if the respective variables are non-NULL.
@ -519,7 +527,9 @@ gst_query_parse_duration (GstQuery * query, GstFormat * format,
* by sinks to compensate for additional latency introduced by elements in the * by sinks to compensate for additional latency introduced by elements in the
* pipeline. * pipeline.
* *
* Returns: A #GstQuery * Free-function: gst_query_unref
*
* Returns: (transfer full): a #GstQuery
* *
* Since: 0.10.12 * Since: 0.10.12
*/ */
@ -565,9 +575,9 @@ gst_query_set_latency (GstQuery * query, gboolean live,
/** /**
* gst_query_parse_latency: * gst_query_parse_latency:
* @query: a #GstQuery * @query: a #GstQuery
* @live: (out): storage for live or NULL * @live: (out) (allow-none): storage for live or NULL
* @min_latency: (out): the storage for the min latency or NULL * @min_latency: (out) (allow-none): the storage for the min latency or NULL
* @max_latency: (out): the storage for the max latency or NULL * @max_latency: (out) (allow-none): the storage for the max latency or NULL
* *
* Parse a latency query answer. * Parse a latency query answer.
* *
@ -604,7 +614,9 @@ gst_query_parse_latency (GstQuery * query, gboolean * live,
* when done with it. A convert query is used to ask for a conversion between * when done with it. A convert query is used to ask for a conversion between
* one format and another. * one format and another.
* *
* Returns: A #GstQuery * Free-function: gst_query_unref
*
* Returns: (transfer full): a #GstQuery
*/ */
GstQuery * GstQuery *
gst_query_new_convert (GstFormat src_format, gint64 value, gst_query_new_convert (GstFormat src_format, gint64 value,
@ -650,10 +662,13 @@ gst_query_set_convert (GstQuery * query, GstFormat src_format, gint64 src_value,
/** /**
* gst_query_parse_convert: * gst_query_parse_convert:
* @query: a #GstQuery * @query: a #GstQuery
* @src_format: (out): the storage for the #GstFormat of the source value, or NULL * @src_format: (out) (allow-none): the storage for the #GstFormat of the
* @src_value: (out): the storage for the source value, or NULL * source value, or NULL
* @dest_format: (out): the storage for the #GstFormat of the destination value, or NULL * @src_value: (out) (allow-none): the storage for the source value, or NULL
* @dest_value: (out): the storage for the destination value, or NULL * @dest_format: (out) (allow-none): the storage for the #GstFormat of the
* destination value, or NULL
* @dest_value: (out) (allow-none): the storage for the destination value,
* or NULL
* *
* Parse a convert query answer. Any of @src_format, @src_value, @dest_format, * Parse a convert query answer. Any of @src_format, @src_value, @dest_format,
* and @dest_value may be NULL, in which case that value is omitted. * and @dest_value may be NULL, in which case that value is omitted.
@ -689,7 +704,9 @@ gst_query_parse_convert (GstQuery * query, GstFormat * src_format,
* when done with it. A segment query is used to discover information about the * when done with it. A segment query is used to discover information about the
* currently configured segment for playback. * currently configured segment for playback.
* *
* Returns: a #GstQuery * Free-function: gst_query_unref
*
* Returns: (transfer full): a new #GstQuery
*/ */
GstQuery * GstQuery *
gst_query_new_segment (GstFormat format) gst_query_new_segment (GstFormat format)
@ -744,10 +761,11 @@ gst_query_set_segment (GstQuery * query, gdouble rate, GstFormat format,
/** /**
* gst_query_parse_segment: * gst_query_parse_segment:
* @query: a #GstQuery * @query: a #GstQuery
* @rate: (out): the storage for the rate of the segment, or NULL * @rate: (out) (allow-none): the storage for the rate of the segment, or NULL
* @format: (out): the storage for the #GstFormat of the values, or NULL * @format: (out) (allow-none): the storage for the #GstFormat of the values,
* @start_value: (out): the storage for the start value, or NULL * or NULL
* @stop_value: (out): the storage for the stop value, or NULL * @start_value: (out) (allow-none): the storage for the start value, or NULL
* @stop_value: (out) (allow-none): the storage for the stop value, or NULL
* *
* Parse a segment query answer. Any of @rate, @format, @start_value, and * Parse a segment query answer. Any of @rate, @format, @start_value, and
* @stop_value may be NULL, which will cause this value to be omitted. * @stop_value may be NULL, which will cause this value to be omitted.
@ -785,7 +803,9 @@ gst_query_parse_segment (GstQuery * query, gdouble * rate, GstFormat * format,
* Constructs a new custom application query object. Use gst_query_unref() * Constructs a new custom application query object. Use gst_query_unref()
* when done with it. * when done with it.
* *
* Returns: a #GstQuery * Free-function: gst_query_unref
*
* Returns: (transfer full): a new #GstQuery
*/ */
GstQuery * GstQuery *
gst_query_new_application (GstQueryType type, GstStructure * structure) gst_query_new_application (GstQueryType type, GstStructure * structure)
@ -802,8 +822,9 @@ gst_query_new_application (GstQueryType type, GstStructure * structure)
* *
* Get the structure of a query. * Get the structure of a query.
* *
* Returns: The #GstStructure of the query. The structure is still owned * Returns: (transfer none): the #GstStructure of the query. The structure is
* by the query and will therefore be freed when the query is unreffed. * still owned by the query and will therefore be freed when the query
* is unreffed.
*/ */
GstStructure * GstStructure *
gst_query_get_structure (GstQuery * query) gst_query_get_structure (GstQuery * query)
@ -820,7 +841,9 @@ gst_query_get_structure (GstQuery * query)
* Constructs a new query object for querying seeking properties of * Constructs a new query object for querying seeking properties of
* the stream. * the stream.
* *
* Returns: A #GstQuery * Free-function: gst_query_unref
*
* Returns: (transfer full): a new #GstQuery
*/ */
GstQuery * GstQuery *
gst_query_new_seeking (GstFormat format) gst_query_new_seeking (GstFormat format)
@ -865,10 +888,11 @@ gst_query_set_seeking (GstQuery * query, GstFormat format,
/** /**
* gst_query_parse_seeking: * gst_query_parse_seeking:
* @query: a GST_QUERY_SEEKING type query #GstQuery * @query: a GST_QUERY_SEEKING type query #GstQuery
* @format: (out): the format to set for the @segment_start and @segment_end values * @format: (out) (allow-none): the format to set for the @segment_start
* @seekable: (out): the seekable flag to set * and @segment_end values, or NULL
* @segment_start: (out): the segment_start to set * @seekable: (out) (allow-none): the seekable flag to set, or NULL
* @segment_end: (out): the segment_end to set * @segment_start: (out) (allow-none): the segment_start to set, or NULL
* @segment_end: (out) (allow-none): the segment_end to set, or NULL
* *
* Parse a seeking query, writing the format into @format, and * Parse a seeking query, writing the format into @format, and
* other results into the passed parameters, if the respective parameters * other results into the passed parameters, if the respective parameters
@ -903,7 +927,9 @@ gst_query_parse_seeking (GstQuery * query, GstFormat * format,
* Constructs a new query object for querying formats of * Constructs a new query object for querying formats of
* the stream. * the stream.
* *
* Returns: A #GstQuery * Free-function: gst_query_unref
*
* Returns: (transfer full): a new #GstQuery
* *
* Since: 0.10.4 * Since: 0.10.4
*/ */
@ -966,7 +992,8 @@ gst_query_set_formats (GstQuery * query, gint n_formats, ...)
* gst_query_set_formatsv: * gst_query_set_formatsv:
* @query: a #GstQuery * @query: a #GstQuery
* @n_formats: the number of formats to set. * @n_formats: the number of formats to set.
* @formats: An array containing @n_formats @GstFormat values. * @formats: (in) (array length=n_formats): an array containing @n_formats
* @GstFormat values.
* *
* Set the formats query result fields in @query. The number of formats passed * Set the formats query result fields in @query. The number of formats passed
* in the @formats array must be equal to @n_formats. * in the @formats array must be equal to @n_formats.
@ -1054,7 +1081,9 @@ gst_query_parse_formats_nth (GstQuery * query, guint nth, GstFormat * format)
* Constructs a new query object for querying the buffering status of * Constructs a new query object for querying the buffering status of
* a stream. * a stream.
* *
* Returns: A #GstQuery * Free-function: gst_query_new
*
* Returns: (transfer full): a new #GstQuery
* *
* Since: 0.10.20 * Since: 0.10.20
*/ */
@ -1108,8 +1137,8 @@ gst_query_set_buffering_percent (GstQuery * query, gboolean busy, gint percent)
/** /**
* gst_query_parse_buffering_percent * gst_query_parse_buffering_percent
* @query: A valid #GstQuery of type GST_QUERY_BUFFERING. * @query: A valid #GstQuery of type GST_QUERY_BUFFERING.
* @busy: (out): if buffering is busy * @busy: (out) (allow-none): if buffering is busy, or NULL
* @percent: (out): a buffering percent * @percent: (out) (allow-none): a buffering percent, or NULL
* *
* Get the percentage of buffered data. This is a value between 0 and 100. * Get the percentage of buffered data. This is a value between 0 and 100.
* The @busy indicator is %TRUE when the buffering is in progress. * The @busy indicator is %TRUE when the buffering is in progress.
@ -1158,10 +1187,10 @@ gst_query_set_buffering_stats (GstQuery * query, GstBufferingMode mode,
/** /**
* gst_query_parse_buffering_stats: * gst_query_parse_buffering_stats:
* @query: A valid #GstQuery of type GST_QUERY_BUFFERING. * @query: A valid #GstQuery of type GST_QUERY_BUFFERING.
* @mode: (out): a buffering mode * @mode: (out) (allow-none): a buffering mode, or NULL
* @avg_in: (out): the average input rate * @avg_in: (out) (allow-none): the average input rate, or NULL
* @avg_out: (out): the average output rate * @avg_out: (out) (allow-none): the average output rat, or NULLe
* @buffering_left: (out): amount of buffering time left * @buffering_left: (out) (allow-none): amount of buffering time left, or NULL
* *
* Extracts the buffering stats values from @query. * Extracts the buffering stats values from @query.
* *
@ -1218,10 +1247,12 @@ gst_query_set_buffering_range (GstQuery * query, GstFormat format,
/** /**
* gst_query_parse_buffering_range: * gst_query_parse_buffering_range:
* @query: a GST_QUERY_BUFFERING type query #GstQuery * @query: a GST_QUERY_BUFFERING type query #GstQuery
* @format: (out): the format to set for the @segment_start and @segment_end values * @format: (out) (allow-none): the format to set for the @segment_start
* @start: (out): the start to set * and @segment_end values, or NULL
* @stop: (out): the stop to set * @start: (out) (allow-none): the start to set, or NULL
* @estimated_total: (out): estimated total amount of download time * @stop: (out) (allow-none): the stop to set, or NULL
* @estimated_total: (out) (allow-none): estimated total amount of download
* time, or NULL
* *
* Parse an available query, writing the format into @format, and * Parse an available query, writing the format into @format, and
* other results into the passed parameters, if the respective parameters * other results into the passed parameters, if the respective parameters
@ -1344,8 +1375,8 @@ gst_query_get_n_buffering_ranges (GstQuery * query)
* gst_query_parse_nth_buffering_range * gst_query_parse_nth_buffering_range
* @query: a GST_QUERY_BUFFERING type query #GstQuery * @query: a GST_QUERY_BUFFERING type query #GstQuery
* @index: position in the buffered-ranges array to read * @index: position in the buffered-ranges array to read
* @start: (out): the start position to set * @start: (out) (allow-none): the start position to set, or NULL
* @stop: (out): the stop position to set * @stop: (out) (allow-none): the stop position to set, or NULL
* *
* Parse an available query and get the start and stop values stored * Parse an available query and get the start and stop values stored
* at the @index of the buffered ranges array. * at the @index of the buffered ranges array.
@ -1389,7 +1420,9 @@ gst_query_parse_nth_buffering_range (GstQuery * query, guint index,
* when done with it. An URI query is used to query the current URI * when done with it. An URI query is used to query the current URI
* that is used by the source or sink. * that is used by the source or sink.
* *
* Returns: A #GstQuery * Free-function: gst_query_unref
*
* Returns: (transfer full): a new #GstQuery
* *
* Since: 0.10.22 * Since: 0.10.22
*/ */
@ -1429,7 +1462,8 @@ gst_query_set_uri (GstQuery * query, const gchar * uri)
/** /**
* gst_query_parse_uri: * gst_query_parse_uri:
* @query: a #GstQuery * @query: a #GstQuery
* @uri: (out): the storage for the current URI (may be NULL) * @uri: (out callee-allocates) (allow-none): the storage for the current URI
* (may be NULL)
* *
* Parse an URI query, writing the URI into @uri as a newly * Parse an URI query, writing the URI into @uri as a newly
* allocated string, if the respective parameters are non-NULL. * allocated string, if the respective parameters are non-NULL.

8
gst/gstquery.h
View file

@ -228,7 +228,9 @@ gst_query_unref (GstQuery * q)
* *
* Copies the given query using the copy function of the parent #GstStructure. * Copies the given query using the copy function of the parent #GstStructure.
* *
* Returns: a new copy of @q. * Free-function: gst_query_unref
*
* Returns: (transfer full): a new copy of @q.
*/ */
#ifdef _FOOL_GTK_DOC_ #ifdef _FOOL_GTK_DOC_
G_INLINE_FUNC GstQuery * gst_query_copy (const GstQuery * q); G_INLINE_FUNC GstQuery * gst_query_copy (const GstQuery * q);
@ -242,9 +244,11 @@ gst_query_copy (const GstQuery * q)
/** /**
* gst_query_make_writable: * gst_query_make_writable:
* @q: a #GstQuery to make writable * @q: (transfer full): a #GstQuery to make writable
* *
* Makes a writable query from the given query. * Makes a writable query from the given query.
*
* Returns: (transfer full): a new writable query (possibly same as @q)
*/ */
#define gst_query_make_writable(q) GST_QUERY_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (q))) #define gst_query_make_writable(q) GST_QUERY_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (q)))

51
gst/gstregistry.c
View file

@ -310,7 +310,7 @@ gst_registry_finalize (GObject * object)
* Retrieves the default registry. The caller does not own a reference on the * Retrieves the default registry. The caller does not own a reference on the
* registry, as it is alive as long as GStreamer is initialized. * registry, as it is alive as long as GStreamer is initialized.
* *
* Returns: The default #GstRegistry. * Returns: (transfer none): The default #GstRegistry.
*/ */
GstRegistry * GstRegistry *
gst_registry_get_default (void) gst_registry_get_default (void)
@ -375,7 +375,8 @@ was_added:
* *
* Get the list of paths for the given registry. * Get the list of paths for the given registry.
* *
* Returns: A Glist of paths as strings. g_list_free after use. * Returns: (transfer container) (element-type char*): A #GList of paths as
* strings. g_list_free after use.
* *
* MT safe. * MT safe.
*/ */
@ -399,7 +400,7 @@ gst_registry_get_path_list (GstRegistry * registry)
/** /**
* gst_registry_add_plugin: * gst_registry_add_plugin:
* @registry: the registry to add the plugin to * @registry: the registry to add the plugin to
* @plugin: the plugin to add * @plugin: (transfer full): the plugin to add
* *
* Add the plugin to the registry. The plugin-added signal will be emitted. * Add the plugin to the registry. The plugin-added signal will be emitted.
* This function will sink @plugin. * This function will sink @plugin.
@ -484,7 +485,7 @@ gst_registry_remove_features_for_plugin_unlocked (GstRegistry * registry,
/** /**
* gst_registry_remove_plugin: * gst_registry_remove_plugin:
* @registry: the registry to remove the plugin from * @registry: the registry to remove the plugin from
* @plugin: the plugin to remove * @plugin: (transfer none): the plugin to remove
* *
* Remove the plugin from the registry. * Remove the plugin from the registry.
* *
@ -511,7 +512,7 @@ gst_registry_remove_plugin (GstRegistry * registry, GstPlugin * plugin)
/** /**
* gst_registry_add_feature: * gst_registry_add_feature:
* @registry: the registry to add the plugin to * @registry: the registry to add the plugin to
* @feature: the feature to add * @feature: (transfer full): the feature to add
* *
* Add the feature to the registry. The feature-added signal will be emitted. * Add the feature to the registry. The feature-added signal will be emitted.
* This function sinks @feature. * This function sinks @feature.
@ -567,7 +568,7 @@ gst_registry_add_feature (GstRegistry * registry, GstPluginFeature * feature)
/** /**
* gst_registry_remove_feature: * gst_registry_remove_feature:
* @registry: the registry to remove the feature from * @registry: the registry to remove the feature from
* @feature: the feature to remove * @feature: (transfer none): the feature to remove
* *
* Remove the feature from the registry. * Remove the feature from the registry.
* *
@ -595,7 +596,7 @@ gst_registry_remove_feature (GstRegistry * registry, GstPluginFeature * feature)
* @registry: registry to query * @registry: registry to query
* @filter: the filter to use * @filter: the filter to use
* @first: only return first match * @first: only return first match
* @user_data: user data passed to the filter function * @user_data: (closure): user data passed to the filter function
* *
* Runs a filter against all plugins in the registry and returns a #GList with * Runs a filter against all plugins in the registry and returns a #GList with
* the results. If the first flag is set, only the first match is * the results. If the first flag is set, only the first match is
@ -603,7 +604,8 @@ gst_registry_remove_feature (GstRegistry * registry, GstPluginFeature * feature)
* Every plugin is reffed; use gst_plugin_list_free() after use, which * Every plugin is reffed; use gst_plugin_list_free() after use, which
* will unref again. * will unref again.
* *
* Returns: a #GList of #GstPlugin. Use gst_plugin_list_free() after usage. * Returns: (transfer full) (element-type Gst.Plugin): a #GList of #GstPlugin.
* Use gst_plugin_list_free() after usage.
* *
* MT safe. * MT safe.
*/ */
@ -714,15 +716,15 @@ gst_registry_get_typefind_factory_list (GstRegistry * registry)
* @registry: registry to query * @registry: registry to query
* @filter: the filter to use * @filter: the filter to use
* @first: only return first match * @first: only return first match
* @user_data: user data passed to the filter function * @user_data: (closure): user data passed to the filter function
* *
* Runs a filter against all features of the plugins in the registry * Runs a filter against all features of the plugins in the registry
* and returns a GList with the results. * and returns a GList with the results.
* If the first flag is set, only the first match is * If the first flag is set, only the first match is
* returned (as a list with a single object). * returned (as a list with a single object).
* *
* Returns: a #GList of #GstPluginFeature. Use gst_plugin_feature_list_free() * Returns: (transfer full) (element-type Gst.PluginFeature): a #GList of
* after usage. * #GstPluginFeature. Use gst_plugin_feature_list_free() after usage.
* *
* MT safe. * MT safe.
*/ */
@ -754,8 +756,8 @@ gst_registry_feature_filter (GstRegistry * registry,
* Find the plugin with the given name in the registry. * Find the plugin with the given name in the registry.
* The plugin will be reffed; caller is responsible for unreffing. * The plugin will be reffed; caller is responsible for unreffing.
* *
* Returns: The plugin with the given name or NULL if the plugin was not found. * Returns: (transfer full): the plugin with the given name or NULL if the
* gst_object_unref() after usage. * plugin was not found. gst_object_unref() after usage.
* *
* MT safe. * MT safe.
*/ */
@ -788,8 +790,8 @@ gst_registry_find_plugin (GstRegistry * registry, const gchar * name)
* *
* Find the pluginfeature with the given name and type in the registry. * Find the pluginfeature with the given name and type in the registry.
* *
* Returns: The pluginfeature with the given name and type or NULL * Returns: (transfer full): the pluginfeature with the given name and type
* if the plugin was not found. gst_object_unref() after usage. * or NULL if the plugin was not found. gst_object_unref() after usage.
* *
* MT safe. * MT safe.
*/ */
@ -819,8 +821,8 @@ gst_registry_find_feature (GstRegistry * registry, const gchar * name,
* *
* Retrieves a #GList of #GstPluginFeature of @type. * Retrieves a #GList of #GstPluginFeature of @type.
* *
* Returns: a #GList of #GstPluginFeature of @type. Use * Returns: (transfer full) (element-type Gst.PluginFeature): a #GList of
* gst_plugin_feature_list_free() after usage. * #GstPluginFeature of @type. Use gst_plugin_feature_list_free() after use
* *
* MT safe. * MT safe.
*/ */
@ -853,7 +855,8 @@ gst_registry_get_feature_list (GstRegistry * registry, GType type)
* Get a copy of all plugins registered in the given registry. The refcount * Get a copy of all plugins registered in the given registry. The refcount
* of each element in the list in incremented. * of each element in the list in incremented.
* *
* Returns: a #GList of #GstPlugin. Use gst_plugin_list_free() after usage. * Returns: (transfer full) (element-type Gst.Plugin): a #GList of #GstPlugin.
* Use gst_plugin_list_free() after usage.
* *
* MT safe. * MT safe.
*/ */
@ -888,8 +891,8 @@ gst_registry_lookup_feature_locked (GstRegistry * registry, const char *name)
* *
* Find a #GstPluginFeature with @name in @registry. * Find a #GstPluginFeature with @name in @registry.
* *
* Returns: a #GstPluginFeature with its refcount incremented, use * Returns: (transfer full): a #GstPluginFeature with its refcount incremented,
* gst_object_unref() after usage. * use gst_object_unref() after usage.
* *
* MT safe. * MT safe.
*/ */
@ -938,8 +941,8 @@ gst_registry_lookup_bn (GstRegistry * registry, const char *basename)
* Look up a plugin in the given registry with the given filename. * Look up a plugin in the given registry with the given filename.
* If found, plugin is reffed. * If found, plugin is reffed.
* *
* Returns: the #GstPlugin if found, or NULL if not. gst_object_unref() * Returns: (transfer full): the #GstPlugin if found, or NULL if not.
* after usage. * gst_object_unref() after usage.
*/ */
GstPlugin * GstPlugin *
gst_registry_lookup (GstRegistry * registry, const char *filename) gst_registry_lookup (GstRegistry * registry, const char *filename)
@ -1276,8 +1279,8 @@ _gst_plugin_feature_filter_plugin_name (GstPluginFeature * feature,
* *
* Retrieves a #GList of features of the plugin with name @name. * Retrieves a #GList of features of the plugin with name @name.
* *
* Returns: a #GList of #GstPluginFeature. Use gst_plugin_feature_list_free() * Returns: (transfer full) (element-type Gst.PluginFeature): a #GList of
* after usage. * #GstPluginFeature. Use gst_plugin_feature_list_free() after usage.
*/ */
GList * GList *
gst_registry_get_feature_list_by_plugin (GstRegistry * registry, gst_registry_get_feature_list_by_plugin (GstRegistry * registry,

18
gst/gstregistry.h
View file

@ -127,7 +127,7 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo
/** /**
* gst_default_registry_add_plugin: * gst_default_registry_add_plugin:
* @plugin: the plugin to add * @plugin: (transfer full): the plugin to add
* *
* Add the plugin to the default registry. * Add the plugin to the default registry.
* The plugin-added signal will be emitted. * The plugin-added signal will be emitted.
@ -153,7 +153,8 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo
* *
* Get the list of paths for the default registry. * Get the list of paths for the default registry.
* *
* Returns: A Glist of paths as strings. g_list_free after use. * Returns: (transfer container) (element-type char*): a #GList of paths as
* strings. g_list_free() after use.
*/ */
#define gst_default_registry_get_path_list() \ #define gst_default_registry_get_path_list() \
gst_registry_get_path_list (gst_registry_get_default()) gst_registry_get_path_list (gst_registry_get_default())
@ -163,7 +164,8 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo
* *
* Get a copy of all plugins registered in the default registry. * Get a copy of all plugins registered in the default registry.
* *
* Returns: a copy of the list. Free after use. * Returns: (transfer full) (element-type Gst.Plugin): a copy of the list.
* Free after use.
*/ */
#define gst_default_registry_get_plugin_list() \ #define gst_default_registry_get_plugin_list() \
gst_registry_get_plugin_list (gst_registry_get_default()) gst_registry_get_plugin_list (gst_registry_get_default())
@ -175,8 +177,8 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo
* *
* Find the pluginfeature with the given name and type in the default registry. * Find the pluginfeature with the given name and type in the default registry.
* *
* Returns: The pluginfeature with the given name and type or NULL * Returns: (transfer full): the pluginfeature with the given name and type or
* if the plugin was not found. * NULL if the plugin was not found.
*/ */
#define gst_default_registry_find_feature(name,type) \ #define gst_default_registry_find_feature(name,type) \
gst_registry_find_feature (gst_registry_get_default(),name,type) gst_registry_find_feature (gst_registry_get_default(),name,type)
@ -188,7 +190,8 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo
* Find the plugin with the given name in the default registry. * Find the plugin with the given name in the default registry.
* The plugin will be reffed; caller is responsible for unreffing. * The plugin will be reffed; caller is responsible for unreffing.
* *
* Returns: The plugin with the given name or NULL if the plugin was not found. * Returns: (transfer full): The plugin with the given name or NULL if the
* plugin was not found.
*/ */
#define gst_default_registry_find_plugin(name) \ #define gst_default_registry_find_plugin(name) \
gst_registry_find_plugin (gst_registry_get_default(),name) gst_registry_find_plugin (gst_registry_get_default(),name)
@ -204,7 +207,8 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo
* If the first flag is set, only the first match is * If the first flag is set, only the first match is
* returned (as a list with a single object). * returned (as a list with a single object).
* *
* Returns: a GList of plugin features, gst_plugin_feature_list_free after use. * Returns: (transfer full) (element-type Gst.PluginFeature): a #GList of
* plugin features, gst_plugin_feature_list_free after use.
*/ */
#define gst_default_registry_feature_filter(filter,first,user_data) \ #define gst_default_registry_feature_filter(filter,first,user_data) \
gst_registry_feature_filter (gst_registry_get_default(),filter,first,user_data) gst_registry_feature_filter (gst_registry_get_default(),filter,first,user_data)

16
gst/gstsegment.c
View file

@ -86,11 +86,13 @@
/** /**
* gst_segment_copy: * gst_segment_copy:
* @segment: a #GstSegment * @segment: (transfer none): a #GstSegment
* *
* Create a copy of given @segment. * Create a copy of given @segment.
* *
* Returns: a new #GstSegment, free with gst_segment_free(). * Free-function: gst_segment_free
*
* Returns: (transfer full): a new #GstSegment, free with gst_segment_free().
* *
* Since: 0.10.20 * Since: 0.10.20
*/ */
@ -124,7 +126,9 @@ gst_segment_get_type (void)
* Allocate a new #GstSegment structure and initialize it using * Allocate a new #GstSegment structure and initialize it using
* gst_segment_init(). * gst_segment_init().
* *
* Returns: a new #GstSegment, free with gst_segment_free(). * Free-function: gst_segment_free
*
* Returns: (transfer full): a new #GstSegment, free with gst_segment_free().
*/ */
GstSegment * GstSegment *
gst_segment_new (void) gst_segment_new (void)
@ -139,7 +143,7 @@ gst_segment_new (void)
/** /**
* gst_segment_free: * gst_segment_free:
* @segment: a #GstSegment * @segment: (in) (transfer full): a #GstSegment
* *
* Free the allocated segment @segment. * Free the allocated segment @segment.
*/ */
@ -699,8 +703,8 @@ gst_segment_to_running_time (GstSegment * segment, GstFormat format,
* @format: the format of the segment. * @format: the format of the segment.
* @start: the start position in the segment * @start: the start position in the segment
* @stop: the stop position in the segment * @stop: the stop position in the segment
* @clip_start: the clipped start position in the segment * @clip_start: (out) (allow-none): the clipped start position in the segment
* @clip_stop: the clipped stop position in the segment * @clip_stop: (out) (allow-none): the clipped stop position in the segment
* *
* Clip the given @start and @stop values to the segment boundaries given * Clip the given @start and @stop values to the segment boundaries given
* in @segment. @start and @stop are compared and clipped to @segment * in @segment. @start and @stop are compared and clipped to @segment

68
gst/gststructure.c
View file

@ -136,7 +136,9 @@ gst_structure_id_empty_new_with_size (GQuark quark, guint prealloc)
* *
* Creates a new, empty #GstStructure with the given name as a GQuark. * Creates a new, empty #GstStructure with the given name as a GQuark.
* *
* Returns: a new, empty #GstStructure * Free-function: gst_structure_free
*
* Returns: (transfer full): a new, empty #GstStructure
*/ */
GstStructure * GstStructure *
gst_structure_id_empty_new (GQuark quark) gst_structure_id_empty_new (GQuark quark)
@ -184,7 +186,9 @@ gst_structure_validate_name (const gchar * name)
* *
* See gst_structure_set_name() for constraints on the @name parameter. * See gst_structure_set_name() for constraints on the @name parameter.
* *
* Returns: a new, empty #GstStructure * Free-function: gst_structure_free
*
* Returns: (transfer full): a new, empty #GstStructure
*/ */
GstStructure * GstStructure *
gst_structure_empty_new (const gchar * name) gst_structure_empty_new (const gchar * name)
@ -205,7 +209,9 @@ gst_structure_empty_new (const gchar * name)
* Variable arguments should be passed as field name, field type, * Variable arguments should be passed as field name, field type,
* and value. Last variable argument should be NULL. * and value. Last variable argument should be NULL.
* *
* Returns: a new #GstStructure * Free-function: gst_structure_free
*
* Returns: (transfer full): a new #GstStructure
*/ */
GstStructure * GstStructure *
gst_structure_new (const gchar * name, const gchar * firstfield, ...) gst_structure_new (const gchar * name, const gchar * firstfield, ...)
@ -234,7 +240,9 @@ gst_structure_new (const gchar * name, const gchar * firstfield, ...)
* *
* See gst_structure_set_name() for constraints on the @name parameter. * See gst_structure_set_name() for constraints on the @name parameter.
* *
* Returns: a new #GstStructure * Free-function: gst_structure_free
*
* Returns: (transfer full): a new #GstStructure
*/ */
GstStructure * GstStructure *
gst_structure_new_valist (const gchar * name, gst_structure_new_valist (const gchar * name,
@ -255,7 +263,7 @@ gst_structure_new_valist (const gchar * name,
/** /**
* gst_structure_set_parent_refcount: * gst_structure_set_parent_refcount:
* @structure: a #GstStructure * @structure: a #GstStructure
* @refcount: a pointer to the parent's refcount * @refcount: (in): a pointer to the parent's refcount
* *
* Sets the parent_refcount field of #GstStructure. This field is used to * Sets the parent_refcount field of #GstStructure. This field is used to
* determine whether a structure is mutable or not. This function should only be * determine whether a structure is mutable or not. This function should only be
@ -283,7 +291,9 @@ gst_structure_set_parent_refcount (GstStructure * structure, gint * refcount)
* *
* Duplicates a #GstStructure and all its fields and values. * Duplicates a #GstStructure and all its fields and values.
* *
* Returns: a new #GstStructure. * Free-function: gst_structure_free
*
* Returns: (transfer none): a new #GstStructure.
*/ */
GstStructure * GstStructure *
gst_structure_copy (const GstStructure * structure) gst_structure_copy (const GstStructure * structure)
@ -312,7 +322,7 @@ gst_structure_copy (const GstStructure * structure)
/** /**
* gst_structure_free: * gst_structure_free:
* @structure: the #GstStructure to free * @structure: (in) (transfer full): the #GstStructure to free
* *
* Frees a #GstStructure and all its fields and values. The structure must not * Frees a #GstStructure and all its fields and values. The structure must not
* have a parent when this function is called. * have a parent when this function is called.
@ -709,7 +719,9 @@ gst_structure_id_set_valist (GstStructure * structure,
* *
* The last variable argument must be NULL (or 0). * The last variable argument must be NULL (or 0).
* *
* Returns: a new #GstStructure * Free-function: gst_structure_free
*
* Returns: (transfer full): a new #GstStructure
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -1048,7 +1060,7 @@ gst_structure_nth_field_name (const GstStructure * structure, guint index)
* gst_structure_foreach: * gst_structure_foreach:
* @structure: a #GstStructure * @structure: a #GstStructure
* @func: a function to call for each field * @func: a function to call for each field
* @user_data: private data * @user_data: (closure): private data
* *
* Calls the provided function once for each field in the #GstStructure. The * Calls the provided function once for each field in the #GstStructure. The
* function must not modify the fields. Also see gst_structure_map_in_place(). * function must not modify the fields. Also see gst_structure_map_in_place().
@ -1084,7 +1096,7 @@ gst_structure_foreach (const GstStructure * structure,
* gst_structure_map_in_place: * gst_structure_map_in_place:
* @structure: a #GstStructure * @structure: a #GstStructure
* @func: a function to call for each field * @func: a function to call for each field
* @user_data: private data * @user_data: (closure): private data
* *
* Calls the provided function once for each field in the #GstStructure. In * Calls the provided function once for each field in the #GstStructure. In
* contrast to gst_structure_foreach(), the function may modify but not delete the * contrast to gst_structure_foreach(), the function may modify but not delete the
@ -1216,7 +1228,7 @@ gst_structure_has_field_typed (const GstStructure * structure,
* gst_structure_get_boolean: * gst_structure_get_boolean:
* @structure: a #GstStructure * @structure: a #GstStructure
* @fieldname: the name of a field * @fieldname: the name of a field
* @value: a pointer to a #gboolean to set * @value: (out): a pointer to a #gboolean to set
* *
* Sets the boolean pointed to by @value corresponding to the value of the * Sets the boolean pointed to by @value corresponding to the value of the
* given field. Caller is responsible for making sure the field exists * given field. Caller is responsible for making sure the field exists
@ -1251,7 +1263,7 @@ gst_structure_get_boolean (const GstStructure * structure,
* gst_structure_get_int: * gst_structure_get_int:
* @structure: a #GstStructure * @structure: a #GstStructure
* @fieldname: the name of a field * @fieldname: the name of a field
* @value: a pointer to an int to set * @value: (out): a pointer to an int to set
* *
* Sets the int pointed to by @value corresponding to the value of the * Sets the int pointed to by @value corresponding to the value of the
* given field. Caller is responsible for making sure the field exists * given field. Caller is responsible for making sure the field exists
@ -1287,7 +1299,7 @@ gst_structure_get_int (const GstStructure * structure,
* gst_structure_get_uint: * gst_structure_get_uint:
* @structure: a #GstStructure * @structure: a #GstStructure
* @fieldname: the name of a field * @fieldname: the name of a field
* @value: a pointer to a uint to set * @value: (out): a pointer to a uint to set
* *
* Sets the uint pointed to by @value corresponding to the value of the * Sets the uint pointed to by @value corresponding to the value of the
* given field. Caller is responsible for making sure the field exists * given field. Caller is responsible for making sure the field exists
@ -1325,7 +1337,7 @@ gst_structure_get_uint (const GstStructure * structure,
* gst_structure_get_fourcc: * gst_structure_get_fourcc:
* @structure: a #GstStructure * @structure: a #GstStructure
* @fieldname: the name of a field * @fieldname: the name of a field
* @value: a pointer to a 32bit unsigned int to set * @value: (out): a pointer to a 32bit unsigned int to set
* *
* Sets the Fourcc pointed to by @value corresponding to the value of the * Sets the Fourcc pointed to by @value corresponding to the value of the
* given field. Caller is responsible for making sure the field exists * given field. Caller is responsible for making sure the field exists
@ -1361,7 +1373,7 @@ gst_structure_get_fourcc (const GstStructure * structure,
* gst_structure_get_date: * gst_structure_get_date:
* @structure: a #GstStructure * @structure: a #GstStructure
* @fieldname: the name of a field * @fieldname: the name of a field
* @value: a pointer to a #GDate to set * @value: (out callee-allocates): a pointer to a #GDate to set
* *
* Sets the date pointed to by @value corresponding to the date of the * Sets the date pointed to by @value corresponding to the date of the
* given field. Caller is responsible for making sure the field exists * given field. Caller is responsible for making sure the field exists
@ -1403,7 +1415,7 @@ gst_structure_get_date (const GstStructure * structure, const gchar * fieldname,
* gst_structure_get_date_time: * gst_structure_get_date_time:
* @structure: a #GstStructure * @structure: a #GstStructure
* @fieldname: the name of a field * @fieldname: the name of a field
* @value: a pointer to a #GstDateTime to set * @value: (out callee-allocates): a pointer to a #GstDateTime to set
* *
* Sets the datetime pointed to by @value corresponding to the datetime of the * Sets the datetime pointed to by @value corresponding to the datetime of the
* given field. Caller is responsible for making sure the field exists * given field. Caller is responsible for making sure the field exists
@ -1445,7 +1457,7 @@ gst_structure_get_date_time (const GstStructure * structure,
* gst_structure_get_clock_time: * gst_structure_get_clock_time:
* @structure: a #GstStructure * @structure: a #GstStructure
* @fieldname: the name of a field * @fieldname: the name of a field
* @value: a pointer to a #GstClockTime to set * @value: (out): a pointer to a #GstClockTime to set
* *
* Sets the clock time pointed to by @value corresponding to the clock time * Sets the clock time pointed to by @value corresponding to the clock time
* of the given field. Caller is responsible for making sure the field exists * of the given field. Caller is responsible for making sure the field exists
@ -1481,7 +1493,7 @@ gst_structure_get_clock_time (const GstStructure * structure,
* gst_structure_get_double: * gst_structure_get_double:
* @structure: a #GstStructure * @structure: a #GstStructure
* @fieldname: the name of a field * @fieldname: the name of a field
* @value: a pointer to a gdouble to set * @value: (out): a pointer to a gdouble to set
* *
* Sets the double pointed to by @value corresponding to the value of the * Sets the double pointed to by @value corresponding to the value of the
* given field. Caller is responsible for making sure the field exists * given field. Caller is responsible for making sure the field exists
@ -1552,7 +1564,7 @@ gst_structure_get_string (const GstStructure * structure,
* @structure: a #GstStructure * @structure: a #GstStructure
* @fieldname: the name of a field * @fieldname: the name of a field
* @enumtype: the enum type of a field * @enumtype: the enum type of a field
* @value: a pointer to an int to set * @value: (out): a pointer to an int to set
* *
* Sets the int pointed to by @value corresponding to the value of the * Sets the int pointed to by @value corresponding to the value of the
* given field. Caller is responsible for making sure the field exists, * given field. Caller is responsible for making sure the field exists,
@ -1589,8 +1601,8 @@ gst_structure_get_enum (const GstStructure * structure,
* gst_structure_get_fraction: * gst_structure_get_fraction:
* @structure: a #GstStructure * @structure: a #GstStructure
* @fieldname: the name of a field * @fieldname: the name of a field
* @value_numerator: a pointer to an int to set * @value_numerator: (out): a pointer to an int to set
* @value_denominator: a pointer to an int to set * @value_denominator: (out): a pointer to an int to set
* *
* Sets the integers pointed to by @value_numerator and @value_denominator * Sets the integers pointed to by @value_numerator and @value_denominator
* corresponding to the value of the given field. Caller is responsible * corresponding to the value of the given field. Caller is responsible
@ -1809,8 +1821,10 @@ priv_gst_structure_append_to_gstring (const GstStructure * structure,
* ]| * ]|
* This prints the structure in human readble form. * This prints the structure in human readble form.
* *
* Returns: a pointer to string allocated by g_malloc(). g_free() after * Free-function: g_free
* usage. *
* Returns: (transfer full)L a pointer to string allocated by g_malloc().
* g_free() after usage.
*/ */
gchar * gchar *
gst_structure_to_string (const GstStructure * structure) gst_structure_to_string (const GstStructure * structure)
@ -2192,14 +2206,16 @@ gst_structure_parse_value (gchar * str,
/** /**
* gst_structure_from_string: * gst_structure_from_string:
* @string: a string representation of a #GstStructure. * @string: a string representation of a #GstStructure.
* @end: pointer to store the end of the string in. * @end: (out) (allow-none): pointer to store the end of the string in.
* *
* Creates a #GstStructure from a string representation. * Creates a #GstStructure from a string representation.
* If end is not NULL, a pointer to the place inside the given string * If end is not NULL, a pointer to the place inside the given string
* where parsing ended will be returned. * where parsing ended will be returned.
* *
* Returns: a new #GstStructure or NULL when the string could not * Free-function: gst_structure_free
* be parsed. Free with gst_structure_free() after use. *
* Returns: (transfer full): a new #GstStructure or NULL when the string could
* not be parsed. Free with gst_structure_free() after use.
*/ */
GstStructure * GstStructure *
gst_structure_from_string (const gchar * string, gchar ** end) gst_structure_from_string (const gchar * string, gchar ** end)

2
gst/gstsystemclock.c
View file

@ -268,7 +268,7 @@ gst_system_clock_get_property (GObject * object, guint prop_id, GValue * value,
* clock will be increased so you need to unref the clock after * clock will be increased so you need to unref the clock after
* usage. * usage.
* *
* Returns: the default clock. * Returns: (transfer full): the default clock.
* *
* MT safe. * MT safe.
*/ */

130
gst/gsttaglist.c
View file

@ -369,7 +369,7 @@ _gst_tag_initialize (void)
/** /**
* gst_tag_merge_use_first: * gst_tag_merge_use_first:
* @dest: uninitialized GValue to store result in * @dest: (out caller-allocates): uninitialized GValue to store result in
* @src: GValue to copy from * @src: GValue to copy from
* *
* This is a convenience function for the func argument of gst_tag_register(). * This is a convenience function for the func argument of gst_tag_register().
@ -386,7 +386,7 @@ gst_tag_merge_use_first (GValue * dest, const GValue * src)
/** /**
* gst_tag_merge_strings_with_comma: * gst_tag_merge_strings_with_comma:
* @dest: uninitialized GValue to store result in * @dest: (out caller-allocates): uninitialized GValue to store result in
* @src: GValue to copy from * @src: GValue to copy from
* *
* This is a convenience function for the func argument of gst_tag_register(). * This is a convenience function for the func argument of gst_tag_register().
@ -612,7 +612,9 @@ gst_tag_is_fixed (const gchar * tag)
* *
* Creates a new empty GstTagList. * Creates a new empty GstTagList.
* *
* Returns: An empty tag list * Free-function: gst_tag_list_free
*
* Returns: (transfer full): An empty tag list
*/ */
GstTagList * GstTagList *
gst_tag_list_new (void) gst_tag_list_new (void)
@ -633,8 +635,10 @@ gst_tag_list_new (void)
* function. The tag list will make copies of any arguments passed * function. The tag list will make copies of any arguments passed
* (e.g. strings, buffers). * (e.g. strings, buffers).
* *
* Returns: a new #GstTagList. Free with gst_tag_list_free() when no longer * Free-function: gst_tag_list_free
* needed. *
* Returns: (transfer full): a new #GstTagList. Free with gst_tag_list_free()
* when no longer needed.
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -662,8 +666,10 @@ gst_tag_list_new_full (const gchar * tag, ...)
* Just like gst_tag_list_new_full(), only that it takes a va_list argument. * Just like gst_tag_list_new_full(), only that it takes a va_list argument.
* Useful mostly for language bindings. * Useful mostly for language bindings.
* *
* Returns: a new #GstTagList. Free with gst_tag_list_free() when no longer * Free-function: gst_tag_list_free
* needed. *
* Returns: (transfer full): a new #GstTagList. Free with gst_tag_list_free()
* when no longer needed.
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -829,7 +835,9 @@ gst_tag_list_insert (GstTagList * into, const GstTagList * from,
* *
* Copies a given #GstTagList. * Copies a given #GstTagList.
* *
* Returns: copy of the given list * Free-function: gst_tag_list_free
*
* Returns: (transfer full): copy of the given list
*/ */
GstTagList * GstTagList *
gst_tag_list_copy (const GstTagList * list) gst_tag_list_copy (const GstTagList * list)
@ -848,7 +856,9 @@ gst_tag_list_copy (const GstTagList * list)
* Merges the two given lists into a new list. If one of the lists is NULL, a * Merges the two given lists into a new list. If one of the lists is NULL, a
* copy of the other is returned. If both lists are NULL, NULL is returned. * copy of the other is returned. If both lists are NULL, NULL is returned.
* *
* Returns: the new list * Free-function: gst_tag_list_free
*
* Returns: (transfer full): the new list
*/ */
GstTagList * GstTagList *
gst_tag_list_merge (const GstTagList * list1, const GstTagList * list2, gst_tag_list_merge (const GstTagList * list1, const GstTagList * list2,
@ -880,7 +890,7 @@ gst_tag_list_merge (const GstTagList * list1, const GstTagList * list2,
/** /**
* gst_tag_list_free: * gst_tag_list_free:
* @list: the list to free * @list: (in) (transfer full): the list to free
* *
* Frees the given list and all associated values. * Frees the given list and all associated values.
*/ */
@ -1111,7 +1121,7 @@ structure_foreach_wrapper (GQuark field_id, const GValue * value,
* gst_tag_list_foreach: * gst_tag_list_foreach:
* @list: list to iterate over * @list: list to iterate over
* @func: function to be called for each tag * @func: function to be called for each tag
* @user_data: user specified data * @user_data: (closure): user specified data
* *
* Calls the given function for each tag inside the tag list. Note that if there * Calls the given function for each tag inside the tag list. Note that if there
* is no tag, the function won't be called at all. * is no tag, the function won't be called at all.
@ -1141,8 +1151,8 @@ gst_tag_list_foreach (const GstTagList * list, GstTagForeachFunc func,
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
* *
* Returns: The GValue for the specified entry or NULL if the tag wasn't * Returns: (transfer none): The GValue for the specified entry or NULL if the
* available or the tag doesn't have as many entries * tag wasn't available or the tag doesn't have as many entries
*/ */
G_CONST_RETURN GValue * G_CONST_RETURN GValue *
gst_tag_list_get_value_index (const GstTagList * list, const gchar * tag, gst_tag_list_get_value_index (const GstTagList * list, const gchar * tag,
@ -1170,7 +1180,7 @@ gst_tag_list_get_value_index (const GstTagList * list, const gchar * tag,
/** /**
* gst_tag_list_copy_value: * gst_tag_list_copy_value:
* @dest: uninitialized #GValue to copy into * @dest: (out caller-allocates): uninitialized #GValue to copy into
* @list: list to get the tag from * @list: list to get the tag from
* @tag: tag to read out * @tag: tag to read out
* *
@ -1268,7 +1278,7 @@ gst_tag_list_get_ ## name ## _index (const GstTagList *list, \
* gst_tag_list_get_char: * gst_tag_list_get_char:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1281,7 +1291,7 @@ gst_tag_list_get_ ## name ## _index (const GstTagList *list, \
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1294,7 +1304,7 @@ TAG_MERGE_FUNCS (char, gchar, TRUE)
* gst_tag_list_get_uchar: * gst_tag_list_get_uchar:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1307,7 +1317,7 @@ TAG_MERGE_FUNCS (char, gchar, TRUE)
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1320,7 +1330,7 @@ TAG_MERGE_FUNCS (uchar, guchar, TRUE)
* gst_tag_list_get_boolean: * gst_tag_list_get_boolean:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1333,7 +1343,7 @@ TAG_MERGE_FUNCS (uchar, guchar, TRUE)
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1346,7 +1356,7 @@ TAG_MERGE_FUNCS (boolean, gboolean, TRUE)
* gst_tag_list_get_int: * gst_tag_list_get_int:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1359,7 +1369,7 @@ TAG_MERGE_FUNCS (boolean, gboolean, TRUE)
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1372,7 +1382,7 @@ TAG_MERGE_FUNCS (int, gint, TRUE)
* gst_tag_list_get_uint: * gst_tag_list_get_uint:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1385,7 +1395,7 @@ TAG_MERGE_FUNCS (int, gint, TRUE)
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1398,7 +1408,7 @@ TAG_MERGE_FUNCS (uint, guint, TRUE)
* gst_tag_list_get_long: * gst_tag_list_get_long:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1411,7 +1421,7 @@ TAG_MERGE_FUNCS (uint, guint, TRUE)
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1424,7 +1434,7 @@ TAG_MERGE_FUNCS (long, glong, TRUE)
* gst_tag_list_get_ulong: * gst_tag_list_get_ulong:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1437,7 +1447,7 @@ TAG_MERGE_FUNCS (long, glong, TRUE)
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1450,7 +1460,7 @@ TAG_MERGE_FUNCS (ulong, gulong, TRUE)
* gst_tag_list_get_int64: * gst_tag_list_get_int64:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1463,7 +1473,7 @@ TAG_MERGE_FUNCS (ulong, gulong, TRUE)
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1476,7 +1486,7 @@ TAG_MERGE_FUNCS (int64, gint64, TRUE)
* gst_tag_list_get_uint64: * gst_tag_list_get_uint64:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1489,7 +1499,7 @@ TAG_MERGE_FUNCS (int64, gint64, TRUE)
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1502,7 +1512,7 @@ TAG_MERGE_FUNCS (uint64, guint64, TRUE)
* gst_tag_list_get_float: * gst_tag_list_get_float:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1515,7 +1525,7 @@ TAG_MERGE_FUNCS (uint64, guint64, TRUE)
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1528,7 +1538,7 @@ TAG_MERGE_FUNCS (float, gfloat, TRUE)
* gst_tag_list_get_double: * gst_tag_list_get_double:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1541,7 +1551,7 @@ TAG_MERGE_FUNCS (float, gfloat, TRUE)
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1554,7 +1564,7 @@ TAG_MERGE_FUNCS (double, gdouble, TRUE)
* gst_tag_list_get_pointer: * gst_tag_list_get_pointer:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out) (transfer none): location for the result
* *
* Copies the contents for the given tag into the value, merging multiple values * Copies the contents for the given tag into the value, merging multiple values
* into one if multiple values are associated with the tag. * into one if multiple values are associated with the tag.
@ -1567,7 +1577,7 @@ TAG_MERGE_FUNCS (double, gdouble, TRUE)
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out) (transfer none): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1582,7 +1592,7 @@ TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL))
* gst_tag_list_get_string: * gst_tag_list_get_string:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: location for the result * @value: (out callee-allocates) (transfer full): location for the result
* *
* Copies the contents for the given tag into the value, possibly merging * Copies the contents for the given tag into the value, possibly merging
* multiple values into one if multiple values are associated with the tag. * multiple values into one if multiple values are associated with the tag.
@ -1594,6 +1604,8 @@ TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL))
* freed by the caller using g_free when no longer needed. Since 0.10.24 the * freed by the caller using g_free when no longer needed. Since 0.10.24 the
* returned string is also guaranteed to be non-NULL and non-empty. * returned string is also guaranteed to be non-NULL and non-empty.
* *
* Free-function: g_free
*
* Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
* given list. * given list.
*/ */
@ -1602,7 +1614,7 @@ TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL))
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out callee-allocates) (transfer full): location for the result
* *
* Gets the value that is at the given index for the given tag in the given * Gets the value that is at the given index for the given tag in the given
* list. * list.
@ -1611,6 +1623,8 @@ TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL))
* freed by the caller using g_free when no longer needed. Since 0.10.24 the * freed by the caller using g_free when no longer needed. Since 0.10.24 the
* returned string is also guaranteed to be non-NULL and non-empty. * returned string is also guaranteed to be non-NULL and non-empty.
* *
* Free-function: g_free
*
* Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
* given list. * given list.
*/ */
@ -1626,7 +1640,7 @@ TAG_MERGE_FUNCS (string, gchar *, (*value != NULL && **value != '\0'))
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out) (transfer none): location for the result
* *
* Peeks at the value that is at the given index for the given tag in the given * Peeks at the value that is at the given index for the given tag in the given
* list. * list.
@ -1658,12 +1672,15 @@ gst_tag_list_peek_string_index (const GstTagList * list,
* gst_tag_list_get_date: * gst_tag_list_get_date:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: address of a GDate pointer variable to store the result into * @value: (out callee-allocates) (transfer full): address of a GDate pointer
* variable to store the result into
* *
* Copies the first date for the given tag in the taglist into the variable * Copies the first date for the given tag in the taglist into the variable
* pointed to by @value. Free the date with g_date_free() when it is no longer * pointed to by @value. Free the date with g_date_free() when it is no longer
* needed. * needed.
* *
* Free-function: g_date_free
*
* Returns: TRUE, if a date was copied, FALSE if the tag didn't exist in the * Returns: TRUE, if a date was copied, FALSE if the tag didn't exist in the
* given list or if it was #NULL. * given list or if it was #NULL.
*/ */
@ -1689,12 +1706,14 @@ gst_tag_list_get_date (const GstTagList * list, const gchar * tag,
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out callee-allocates) (transfer full): location for the result
* *
* Gets the date that is at the given index for the given tag in the given * Gets the date that is at the given index for the given tag in the given
* list and copies it into the variable pointed to by @value. Free the date * list and copies it into the variable pointed to by @value. Free the date
* with g_date_free() when it is no longer needed. * with g_date_free() when it is no longer needed.
* *
* Free-function: g_date_free
*
* Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
* given list or if it was #NULL. * given list or if it was #NULL.
*/ */
@ -1718,14 +1737,18 @@ gst_tag_list_get_date_index (const GstTagList * list,
* gst_tag_list_get_date_time: * gst_tag_list_get_date_time:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: address of a #GstDateTime pointer variable to store the result into * @value: (out callee-allocates) (transfer full): address of a #GstDateTime
* pointer variable to store the result into
* *
* Copies the first datetime for the given tag in the taglist into the variable * Copies the first datetime for the given tag in the taglist into the variable
* pointed to by @value. Unref the date with gst_date_time_unref() when * pointed to by @value. Unref the date with gst_date_time_unref() when
* it is no longer needed. * it is no longer needed.
* *
* Returns: TRUE, if a datetime was copied, FALSE if the tag didn't exist in the * Free-function: gst_date_time_unref
* given list or if it was #NULL. *
* Returns: TRUE, if a datetime was copied, FALSE if the tag didn't exist in
* thegiven list or if it was #NULL.
*
* Since: 0.10.31 * Since: 0.10.31
*/ */
gboolean gboolean
@ -1753,14 +1776,17 @@ gst_tag_list_get_date_time (const GstTagList * list, const gchar * tag,
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: location for the result * @value: (out callee-allocates) (transfer full): location for the result
* *
* Gets the datetime that is at the given index for the given tag in the given * Gets the datetime that is at the given index for the given tag in the given
* list and copies it into the variable pointed to by @value. Unref the datetime * list and copies it into the variable pointed to by @value. Unref the datetime
* with gst_date_time_unref() when it is no longer needed. * with gst_date_time_unref() when it is no longer needed.
* *
* Free-function: gst_date_time_unref
*
* Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
* given list or if it was #NULL. * given list or if it was #NULL.
*
* Since: 0.10.31 * Since: 0.10.31
*/ */
gboolean gboolean
@ -1783,12 +1809,15 @@ gst_tag_list_get_date_time_index (const GstTagList * list,
* gst_tag_list_get_buffer: * gst_tag_list_get_buffer:
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @value: address of a GstBuffer pointer variable to store the result into * @value: (out callee-allocates) (transfer full): address of a GstBuffer
* pointer variable to store the result into
* *
* Copies the first buffer for the given tag in the taglist into the variable * Copies the first buffer for the given tag in the taglist into the variable
* pointed to by @value. Free the buffer with gst_buffer_unref() when it is * pointed to by @value. Free the buffer with gst_buffer_unref() when it is
* no longer needed. * no longer needed.
* *
* Free-function: gst_buffer_unref
*
* Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the
* given list or if it was #NULL. * given list or if it was #NULL.
* *
@ -1816,12 +1845,15 @@ gst_tag_list_get_buffer (const GstTagList * list, const gchar * tag,
* @list: a #GstTagList to get the tag from * @list: a #GstTagList to get the tag from
* @tag: tag to read out * @tag: tag to read out
* @index: number of entry to read out * @index: number of entry to read out
* @value: address of a GstBuffer pointer variable to store the result into * @value: (out callee-allocates) (transfer full): address of a GstBuffer
* pointer variable to store the result into
* *
* Gets the buffer that is at the given index for the given tag in the given * Gets the buffer that is at the given index for the given tag in the given
* list and copies it into the variable pointed to by @value. Free the buffer * list and copies it into the variable pointed to by @value. Free the buffer
* with gst_buffer_unref() when it is no longer needed. * with gst_buffer_unref() when it is no longer needed.
* *
* Free-function: gst_buffer_unref
*
* Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the
* given list or if it was #NULL. * given list or if it was #NULL.
* *

4
gst/gsttagsetter.c
View file

@ -368,8 +368,8 @@ gst_tag_setter_add_tag_value (GstTagSetter * setter,
* *
* This function is not thread-safe. * This function is not thread-safe.
* *
* Returns: a current snapshot of the taglist used in the setter * Returns: (transfer none): a current snapshot of the taglist used in the
* or NULL if none is used. * setter or NULL if none is used.
*/ */
G_CONST_RETURN GstTagList * G_CONST_RETURN GstTagList *
gst_tag_setter_get_tag_list (GstTagSetter * setter) gst_tag_setter_get_tag_list (GstTagSetter * setter)

12
gst/gsttask.c
View file

@ -379,7 +379,7 @@ gst_task_cleanup_all (void)
/** /**
* gst_task_create: * gst_task_create:
* @func: The #GstTaskFunction to use * @func: The #GstTaskFunction to use
* @data: User data to pass to @func * @data: (closure): User data to pass to @func
* *
* Create a new Task that will repeatedly call the provided @func * Create a new Task that will repeatedly call the provided @func
* with @data as a parameter. Typically the task will run in * with @data as a parameter. Typically the task will run in
@ -395,7 +395,7 @@ gst_task_cleanup_all (void)
* gst_task_set_lock() function. This lock will always be acquired while * gst_task_set_lock() function. This lock will always be acquired while
* @func is called. * @func is called.
* *
* Returns: A new #GstTask. * Returns: (transfer full): A new #GstTask.
* *
* MT safe. * MT safe.
*/ */
@ -489,7 +489,7 @@ gst_task_set_priority (GstTask * task, GThreadPriority priority)
* *
* MT safe. * MT safe.
* *
* Returns: the #GstTaskPool used by @task. gst_object_unref() * Returns: (transfer full): the #GstTaskPool used by @task. gst_object_unref()
* after usage. * after usage.
* *
* Since: 0.10.24 * Since: 0.10.24
@ -514,7 +514,7 @@ gst_task_get_pool (GstTask * task)
/** /**
* gst_task_set_pool: * gst_task_set_pool:
* @task: a #GstTask * @task: a #GstTask
* @pool: a #GstTaskPool * @pool: (transfer none): a #GstTaskPool
* *
* Set @pool as the new GstTaskPool for @task. Any new streaming threads that * Set @pool as the new GstTaskPool for @task. Any new streaming threads that
* will be created by @task will now use @pool. * will be created by @task will now use @pool.
@ -550,8 +550,8 @@ gst_task_set_pool (GstTask * task, GstTaskPool * pool)
/** /**
* gst_task_set_thread_callbacks: * gst_task_set_thread_callbacks:
* @task: The #GstTask to use * @task: The #GstTask to use
* @callbacks: a #GstTaskThreadCallbacks pointer * @callbacks: (in): a #GstTaskThreadCallbacks pointer
* @user_data: user data passed to the callbacks * @user_data: (closure): user data passed to the callbacks
* @notify: called when @user_data is no longer referenced * @notify: called when @user_data is no longer referenced
* *
* Set callbacks which will be executed when a new thread is needed, the thread * Set callbacks which will be executed when a new thread is needed, the thread

4
gst/gsttaskpool.c
View file

@ -158,7 +158,7 @@ gst_task_pool_finalize (GObject * object)
* Create a new default task pool. The default task pool will use a regular * Create a new default task pool. The default task pool will use a regular
* GThreadPool for threads. * GThreadPool for threads.
* *
* Returns: a new #GstTaskPool. gst_object_unref() after usage. * Returns: (transfer full): a new #GstTaskPool. gst_object_unref() after usage.
* *
* Since: 0.10.24 * Since: 0.10.24
*/ */
@ -224,7 +224,7 @@ gst_task_pool_cleanup (GstTaskPool * pool)
* gst_task_pool_push: * gst_task_pool_push:
* @pool: a #GstTaskPool * @pool: a #GstTaskPool
* @func: the function to call * @func: the function to call
* @user_data: data to pass to @func * @user_data: (closure): data to pass to @func
* @error: return location for an error * @error: return location for an error
* *
* Start the execution of a new thread from @pool. * Start the execution of a new thread from @pool.

8
gst/gsttrace.c
View file

@ -86,7 +86,7 @@ read_tsc (gint64 * dst)
/** /**
* gst_trace_read_tsc: * gst_trace_read_tsc:
* @dst: pointer to hold the result. * @dst: (out) pointer to hold the result.
* *
* Read a platform independent timer value that can be used in * Read a platform independent timer value that can be used in
* benchmarks. * benchmarks.
@ -108,7 +108,9 @@ gint _gst_trace_on = 1;
* Create a ringbuffer of @size in the file with @filename to * Create a ringbuffer of @size in the file with @filename to
* store trace results in. * store trace results in.
* *
* Returns: a new #GstTrace. * Free-function: gst_trace_destroy
*
* Returns: (transfer full): a new #GstTrace.
*/ */
GstTrace * GstTrace *
gst_trace_new (const gchar * filename, gint size) gst_trace_new (const gchar * filename, gint size)
@ -138,7 +140,7 @@ gst_trace_new (const gchar * filename, gint size)
/** /**
* gst_trace_destroy: * gst_trace_destroy:
* @trace: the #GstTrace to destroy * @trace: (in) (transfer full): the #GstTrace to destroy
* *
* Flush an close the previously allocated @trace. * Flush an close the previously allocated @trace.
*/ */

6
gst/gsttypefind.c
View file

@ -56,7 +56,8 @@ gst_type_find_get_type (void)
* @name: The name for registering * @name: The name for registering
* @rank: The rank (or importance) of this typefind function * @rank: The rank (or importance) of this typefind function
* @func: The #GstTypeFindFunction to use * @func: The #GstTypeFindFunction to use
* @extensions: Optional extensions that could belong to this type * @extensions: (transfer none) (array zero-terminated=1) (element-type utf8):
* Optional extensions that could belong to this type
* @possible_caps: Optionally the caps that could be returned when typefinding * @possible_caps: Optionally the caps that could be returned when typefinding
* succeeds * succeeds
* @data: Optional user data. This user data must be available until the plugin * @data: Optional user data. This user data must be available until the plugin
@ -123,7 +124,8 @@ gst_type_find_register (GstPlugin * plugin, const gchar * name, guint rank,
* the stream. The returned memory is valid until the typefinding function * the stream. The returned memory is valid until the typefinding function
* returns and must not be freed. * returns and must not be freed.
* *
* Returns: the requested data, or NULL if that data is not available. * Returns: (transfer none) (array length=size): the requested data, or NULL
* if that data is not available.
*/ */
guint8 * guint8 *
gst_type_find_peek (GstTypeFind * find, gint64 offset, guint size) gst_type_find_peek (GstTypeFind * find, gint64 offset, guint size)

14
gst/gsttypefindfactory.c
View file

@ -149,7 +149,10 @@ gst_type_find_factory_dispose (GObject * object)
* The returned factories are sorted by highest rank first, and then by * The returned factories are sorted by highest rank first, and then by
* factory name. (behaviour change since 0.10.26) * factory name. (behaviour change since 0.10.26)
* *
* Returns: the list of all registered #GstTypeFindFactory. * Free-function: gst_plugin_feature_list_free
*
* Returns: (transfer full) (element-type Gst.TypeFindFactory): the list of all
* registered #GstTypeFindFactory.
*/ */
GList * GList *
gst_type_find_factory_get_list (void) gst_type_find_factory_get_list (void)
@ -164,7 +167,7 @@ gst_type_find_factory_get_list (void)
* *
* Gets the #GstCaps associated with a typefind factory. * Gets the #GstCaps associated with a typefind factory.
* *
* Returns: The #GstCaps associated with this factory * Returns: (transfer none): the #GstCaps associated with this factory
*/ */
GstCaps * GstCaps *
gst_type_find_factory_get_caps (GstTypeFindFactory * factory) gst_type_find_factory_get_caps (GstTypeFindFactory * factory)
@ -183,7 +186,8 @@ gst_type_find_factory_get_caps (GstTypeFindFactory * factory)
* copy it using g_strdupv(). This function may return NULL to indicate * copy it using g_strdupv(). This function may return NULL to indicate
* a 0-length list. * a 0-length list.
* *
* Returns: a NULL-terminated array of extensions associated with this factory * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): a
* NULL-terminated array of extensions associated with this factory
*/ */
gchar ** gchar **
gst_type_find_factory_get_extensions (GstTypeFindFactory * factory) gst_type_find_factory_get_extensions (GstTypeFindFactory * factory)
@ -196,8 +200,8 @@ gst_type_find_factory_get_extensions (GstTypeFindFactory * factory)
/** /**
* gst_type_find_factory_call_function: * gst_type_find_factory_call_function:
* @factory: A #GstTypeFindFactory * @factory: A #GstTypeFindFactory
* @find: A properly setup #GstTypeFind entry. The get_data and suggest_type * @find: (transfer none): a properly setup #GstTypeFind entry. The get_data
* members must be set. * and suggest_type members must be set.
* *
* Calls the #GstTypeFindFunction associated with this factory. * Calls the #GstTypeFindFunction associated with this factory.
*/ */

42
gst/gsturi.c
View file

@ -101,7 +101,7 @@ gst_uri_handler_base_init (gpointer g_class)
/** /**
* GstURIHandler::new-uri: * GstURIHandler::new-uri:
* @handler: The #GstURIHandler which emitted the signal * @handler: The #GstURIHandler which emitted the signal
* @uri: The new URI, or NULL if the URI was removed * @uri: (transfer none): The new URI, or NULL if the URI was removed
* *
* The URI of the given @handler has changed. * The URI of the given @handler has changed.
*/ */
@ -208,8 +208,7 @@ escape_string_internal (const gchar * string, UnsafeCharacterSet mask)
return result; return result;
} }
/** /* escape_string:
* escape_string:
* @string: string to be escaped * @string: string to be escaped
* *
* Escapes @string, replacing any and all special characters * Escapes @string, replacing any and all special characters
@ -251,8 +250,7 @@ unescape_character (const char *scanner)
return (first_digit << 4) | second_digit; return (first_digit << 4) | second_digit;
} }
/** /* unescape_string:
* unescape_string:
* @escaped_string: an escaped URI, path, or other string * @escaped_string: an escaped URI, path, or other string
* @illegal_characters: a string containing a sequence of characters * @illegal_characters: a string containing a sequence of characters
* considered "illegal", '\0' is automatically in this list. * considered "illegal", '\0' is automatically in this list.
@ -388,7 +386,7 @@ gst_uri_get_protocol (const gchar * uri)
/** /**
* gst_uri_has_protocol: * gst_uri_has_protocol:
* @uri: an URI string * @uri: a URI string
* @protocol: a protocol string (e.g. "http") * @protocol: a protocol string (e.g. "http")
* *
* Checks if the protocol of a given valid URI matches @protocol. * Checks if the protocol of a given valid URI matches @protocol.
@ -423,8 +421,11 @@ gst_uri_has_protocol (const gchar * uri, const gchar * protocol)
* the hostname if one is specified. The returned string must be freed using * the hostname if one is specified. The returned string must be freed using
* g_free(). * g_free().
* *
* Returns: The location for this URI. Returns NULL if the URI isn't valid. If * Free-function: g_free
* the URI does not contain a location, an empty string is returned. *
* Returns: (transfer full) (array zero-terminated=1): the location for this
* URI. Returns NULL if the URI isn't valid. If the URI does not contain
* a location, an empty string is returned.
*/ */
gchar * gchar *
gst_uri_get_location (const gchar * uri) gst_uri_get_location (const gchar * uri)
@ -463,12 +464,15 @@ gst_uri_get_location (const gchar * uri)
/** /**
* gst_uri_construct: * gst_uri_construct:
* @protocol: Protocol for URI * @protocol: Protocol for URI
* @location: Location for URI * @location: (array zero-terminated=1) (transfer none): Location for URI
* *
* Constructs a URI for a given valid protocol and location. * Constructs a URI for a given valid protocol and location.
* *
* Returns: a new string for this URI. Returns NULL if the given URI protocol * Free-function: g_free
* is not valid, or the given location is NULL. *
* Returns: (transfer full) (array zero-terminated=1): a new string for this
* URI. Returns NULL if the given URI protocol is not valid, or the given
* location is NULL.
*/ */
gchar * gchar *
gst_uri_construct (const gchar * protocol, const gchar * location) gst_uri_construct (const gchar * protocol, const gchar * location)
@ -582,11 +586,11 @@ gst_uri_protocol_is_supported (const GstURIType type, const gchar * protocol)
* gst_element_make_from_uri: * gst_element_make_from_uri:
* @type: Whether to create a source or a sink * @type: Whether to create a source or a sink
* @uri: URI to create an element for * @uri: URI to create an element for
* @elementname: Name of created element, can be NULL. * @elementname: (allow-none): Name of created element, can be NULL.
* *
* Creates an element for handling the given URI. * Creates an element for handling the given URI.
* *
* Returns: a new element or NULL if none could be created * Returns: (transfer full): a new element or NULL if none could be created
*/ */
GstElement * GstElement *
gst_element_make_from_uri (const GstURIType type, const gchar * uri, gst_element_make_from_uri (const GstURIType type, const gchar * uri,
@ -669,9 +673,9 @@ gst_uri_handler_get_uri_type (GstURIHandler * handler)
* Gets the list of protocols supported by @handler. This list may not be * Gets the list of protocols supported by @handler. This list may not be
* modified. * modified.
* *
* Returns: the supported protocols. * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): the
* Returns NULL if the @handler isn't implemented properly, or the @handler * supported protocols. Returns NULL if the @handler isn't implemented
* doesn't support any protocols. * properly, or the @handler doesn't support any protocols.
*/ */
gchar ** gchar **
gst_uri_handler_get_protocols (GstURIHandler * handler) gst_uri_handler_get_protocols (GstURIHandler * handler)
@ -702,9 +706,9 @@ gst_uri_handler_get_protocols (GstURIHandler * handler)
* *
* Gets the currently handled URI. * Gets the currently handled URI.
* *
* Returns: the URI currently handled by the @handler. * Returns: (transfer none): the URI currently handled by the @handler.
* Returns NULL if there are no URI currently handled. The returned * Returns NULL if there are no URI currently handled. The
* string must not be modified or freed. * returned string must not be modified or freed.
*/ */
G_CONST_RETURN gchar * G_CONST_RETURN gchar *
gst_uri_handler_get_uri (GstURIHandler * handler) gst_uri_handler_get_uri (GstURIHandler * handler)

12
gst/gsturi.h
View file

@ -75,11 +75,13 @@ typedef struct _GstURIHandlerInterface GstURIHandlerInterface;
* @get_uri: Method to return the URI currently handled by the element. * @get_uri: Method to return the URI currently handled by the element.
* @set_uri: Method to set a new URI. * @set_uri: Method to set a new URI.
* @get_type_full: Variant of get_type which takes a GType argument. This is * @get_type_full: Variant of get_type which takes a GType argument. This is
* for use by bindings that need to pass context when creating a URI Handler. * If implemented, get_type will be used in preference to get_type_full. Since: 0.10.15. * for use by bindings that need to pass context when creating a URI Handler.
* @get_protocols_full: Variant of get_type which takes a GType argument. * If implemented, get_type will be used in preference to get_type_full.
* This is for use by bindings that need to pass context when creating a URI * Since: 0.10.15.
* Handler. If implemented, get_protocols will be used in preference to * @get_protocols_full: Variant of get_protocols which takes a GType argument.
* get_protocols_full. Since: 0.10.15. * This is for use by bindings that need to pass context when creating a URI
* Handler. If implemented, get_protocols will be used in preference to
* get_protocols_full. Since: 0.10.15.
* *
* Any #GstElement using this interface should implement these methods. * Any #GstElement using this interface should implement these methods.
*/ */

209
gst/gstutils.c
View file

@ -82,7 +82,7 @@ gst_util_dump_mem (const guchar * mem, guint size)
/** /**
* gst_util_set_value_from_string: * gst_util_set_value_from_string:
* @value: the value to set * @value: (out caller-allocates): the value to set
* @value_str: the string to get the value from * @value_str: the string to get the value from
* *
* Converts the string to the type of the value and * Converts the string to the type of the value and
@ -748,7 +748,7 @@ string_append_indent (GString * str, gint count)
* gst_print_pad_caps: * gst_print_pad_caps:
* @buf: the buffer to print the caps in * @buf: the buffer to print the caps in
* @indent: initial indentation * @indent: initial indentation
* @pad: the pad to print the caps from * @pad: (transfer none): the pad to print the caps from
* *
* Write the pad capabilities in a human readable format into * Write the pad capabilities in a human readable format into
* the given GString. * the given GString.
@ -777,7 +777,7 @@ gst_print_pad_caps (GString * buf, gint indent, GstPad * pad)
* gst_print_element_args: * gst_print_element_args:
* @buf: the buffer to print the args in * @buf: the buffer to print the args in
* @indent: initial indentation * @indent: initial indentation
* @element: the element to print the args of * @element: (transfer none): the element to print the args of
* *
* Print the element argument in a human readable format in the given * Print the element argument in a human readable format in the given
* GString. * GString.
@ -825,7 +825,7 @@ gst_print_element_args (GString * buf, gint indent, GstElement * element)
/** /**
* gst_element_create_all_pads: * gst_element_create_all_pads:
* @element: a #GstElement to create pads for * @element: (transfer none): a #GstElement to create pads for
* *
* Creates a pad for each pad template that is always available. * Creates a pad for each pad template that is always available.
* This function is only useful during object intialization of * This function is only useful during object intialization of
@ -858,14 +858,15 @@ gst_element_create_all_pads (GstElement * element)
/** /**
* gst_element_get_compatible_pad_template: * gst_element_get_compatible_pad_template:
* @element: a #GstElement to get a compatible pad template for. * @element: (transfer none): a #GstElement to get a compatible pad template for
* @compattempl: the #GstPadTemplate to find a compatible template for. * @compattempl: (transfer none): the #GstPadTemplate to find a compatible
* template for
* *
* Retrieves a pad template from @element that is compatible with @compattempl. * Retrieves a pad template from @element that is compatible with @compattempl.
* Pads from compatible templates can be linked together. * Pads from compatible templates can be linked together.
* *
* Returns: a compatible #GstPadTemplate, or NULL if none was found. No * Returns: (transfer none): a compatible #GstPadTemplate, or NULL if none
* unreferencing is necessary. * was found. No unreferencing is necessary.
*/ */
GstPadTemplate * GstPadTemplate *
gst_element_get_compatible_pad_template (GstElement * element, gst_element_get_compatible_pad_template (GstElement * element,
@ -954,14 +955,15 @@ gst_element_request_pad (GstElement * element, GstPadTemplate * templ,
/** /**
* gst_element_get_pad_from_template: * gst_element_get_pad_from_template:
* @element: a #GstElement. * @element: (transfer none): a #GstElement.
* @templ: a #GstPadTemplate belonging to @element. * @templ: (transfer none): a #GstPadTemplate belonging to @element.
* *
* Gets a pad from @element described by @templ. If the presence of @templ is * Gets a pad from @element described by @templ. If the presence of @templ is
* #GST_PAD_REQUEST, requests a new pad. Can return %NULL for #GST_PAD_SOMETIMES * #GST_PAD_REQUEST, requests a new pad. Can return %NULL for #GST_PAD_SOMETIMES
* templates. * templates.
* *
* Returns: the #GstPad, or NULL if one could not be found or created. * Returns: (transfer full): the #GstPad, or NULL if one could not be found
* or created.
*/ */
static GstPad * static GstPad *
gst_element_get_pad_from_template (GstElement * element, GstPadTemplate * templ) gst_element_get_pad_from_template (GstElement * element, GstPadTemplate * templ)
@ -1082,8 +1084,8 @@ gst_pad_check_link (GstPad * srcpad, GstPad * sinkpad)
/** /**
* gst_element_get_compatible_pad: * gst_element_get_compatible_pad:
* @element: a #GstElement in which the pad should be found. * @element: (transfer none): a #GstElement in which the pad should be found.
* @pad: the #GstPad to find a compatible one for. * @pad: (transfer none): the #GstPad to find a compatible one for.
* @caps: the #GstCaps to use as a filter. * @caps: the #GstCaps to use as a filter.
* *
* Looks for an unlinked pad to which the given pad can link. It is not * Looks for an unlinked pad to which the given pad can link. It is not
@ -1094,8 +1096,8 @@ gst_pad_check_link (GstPad * srcpad, GstPad * sinkpad)
* and if none can be found, it will request a compatible REQUEST pad by looking * and if none can be found, it will request a compatible REQUEST pad by looking
* at the templates of @element. * at the templates of @element.
* *
* Returns: the #GstPad to which a link can be made, or %NULL if one cannot be * Returns: (transfer full): the #GstPad to which a link can be made, or %NULL
* found. gst_object_unref() after usage. * if one cannot be found. gst_object_unref() after usage.
*/ */
GstPad * GstPad *
gst_element_get_compatible_pad (GstElement * element, GstPad * pad, gst_element_get_compatible_pad (GstElement * element, GstPad * pad,
@ -1228,7 +1230,7 @@ gst_element_get_compatible_pad (GstElement * element, GstPad * pad,
* *
* Gets a string representing the given state. * Gets a string representing the given state.
* *
* Returns: a string with the name of the state. * Returns: (transfer none): a string with the name of the state.
*/ */
G_CONST_RETURN gchar * G_CONST_RETURN gchar *
gst_element_state_get_name (GstState state) gst_element_state_get_name (GstState state)
@ -1272,7 +1274,8 @@ gst_element_state_get_name (GstState state)
* *
* Gets a string representing the given state change result. * Gets a string representing the given state change result.
* *
* Returns: a string with the name of the state change result. * Returns: (transfer none): a string with the name of the state
* result.
* *
* Since: 0.10.11 * Since: 0.10.11
*/ */
@ -1576,9 +1579,10 @@ pad_link_maybe_ghosting (GstPad * src, GstPad * sink, GstPadLinkCheck flags)
/** /**
* gst_element_link_pads_full: * gst_element_link_pads_full:
* @src: a #GstElement containing the source pad. * @src: a #GstElement containing the source pad.
* @srcpadname: the name of the #GstPad in source element or NULL for any pad. * @srcpadname: (allow-none): the name of the #GstPad in source element
* @dest: the #GstElement containing the destination pad. * or NULL for any pad.
* @destpadname: the name of the #GstPad in destination element, * @dest: (transfer none): the #GstElement containing the destination pad.
* @destpadname: (allow-none): the name of the #GstPad in destination element,
* or NULL for any pad. * or NULL for any pad.
* @flags: the #GstPadLinkCheck to be performed when linking pads. * @flags: the #GstPadLinkCheck to be performed when linking pads.
* *
@ -1842,9 +1846,10 @@ gst_element_link_pads_full (GstElement * src, const gchar * srcpadname,
/** /**
* gst_element_link_pads: * gst_element_link_pads:
* @src: a #GstElement containing the source pad. * @src: a #GstElement containing the source pad.
* @srcpadname: the name of the #GstPad in source element or NULL for any pad. * @srcpadname: (allow-none): the name of the #GstPad in source element
* @dest: the #GstElement containing the destination pad. * or NULL for any pad.
* @destpadname: the name of the #GstPad in destination element, * @dest: (transfer none): the #GstElement containing the destination pad.
* @destpadname: (allow-none): the name of the #GstPad in destination element,
* or NULL for any pad. * or NULL for any pad.
* *
* Links the two named pads of the source and destination elements. * Links the two named pads of the source and destination elements.
@ -1865,10 +1870,13 @@ gst_element_link_pads (GstElement * src, const gchar * srcpadname,
/** /**
* gst_element_link_pads_filtered: * gst_element_link_pads_filtered:
* @src: a #GstElement containing the source pad. * @src: a #GstElement containing the source pad.
* @srcpadname: the name of the #GstPad in source element or NULL for any pad. * @srcpadname: (allow-none): the name of the #GstPad in source element
* @dest: the #GstElement containing the destination pad. * or NULL for any pad.
* @destpadname: the name of the #GstPad in destination element or NULL for any pad. * @dest: (transfer none): the #GstElement containing the destination pad.
* @filter: the #GstCaps to filter the link, or #NULL for no filter. * @destpadname: (allow-none): the name of the #GstPad in destination element
* or NULL for any pad.
* @filter: (transfer none) (allow-none): the #GstCaps to filter the link,
* or #NULL for no filter.
* *
* Links the two named pads of the source and destination elements. Side effect * Links the two named pads of the source and destination elements. Side effect
* is that if one of the pads has no parent, it becomes a child of the parent of * is that if one of the pads has no parent, it becomes a child of the parent of
@ -1949,8 +1957,8 @@ gst_element_link_pads_filtered (GstElement * src, const gchar * srcpadname,
/** /**
* gst_element_link: * gst_element_link:
* @src: a #GstElement containing the source pad. * @src: (transfer none): a #GstElement containing the source pad.
* @dest: the #GstElement containing the destination pad. * @dest: (transfer none): the #GstElement containing the destination pad.
* *
* Links @src to @dest. The link must be from source to * Links @src to @dest. The link must be from source to
* destination; the other direction will not be tried. The function looks for * destination; the other direction will not be tried. The function looks for
@ -1971,8 +1979,8 @@ gst_element_link (GstElement * src, GstElement * dest)
/** /**
* gst_element_link_many: * gst_element_link_many:
* @element_1: the first #GstElement in the link chain. * @element_1: (transfer none): the first #GstElement in the link chain.
* @element_2: the second #GstElement in the link chain. * @element_2: (transfer none): the second #GstElement in the link chain.
* @...: the NULL-terminated list of elements to link in order. * @...: the NULL-terminated list of elements to link in order.
* *
* Chain together a series of elements. Uses gst_element_link(). * Chain together a series of elements. Uses gst_element_link().
@ -2010,8 +2018,9 @@ gst_element_link_many (GstElement * element_1, GstElement * element_2, ...)
/** /**
* gst_element_link_filtered: * gst_element_link_filtered:
* @src: a #GstElement containing the source pad. * @src: a #GstElement containing the source pad.
* @dest: the #GstElement containing the destination pad. * @dest: (transfer none): the #GstElement containing the destination pad.
* @filter: the #GstCaps to filter the link, or #NULL for no filter. * @filter: (transfer none) (allow-none): the #GstCaps to filter the link,
* or #NULL for no filter.
* *
* Links @src to @dest using the given caps as filtercaps. * Links @src to @dest using the given caps as filtercaps.
* The link must be from source to * The link must be from source to
@ -2033,9 +2042,9 @@ gst_element_link_filtered (GstElement * src, GstElement * dest,
/** /**
* gst_element_unlink_pads: * gst_element_unlink_pads:
* @src: a #GstElement containing the source pad. * @src: a (transfer none): #GstElement containing the source pad.
* @srcpadname: the name of the #GstPad in source element. * @srcpadname: the name of the #GstPad in source element.
* @dest: a #GstElement containing the destination pad. * @dest: (transfer none): a #GstElement containing the destination pad.
* @destpadname: the name of the #GstPad in destination element. * @destpadname: the name of the #GstPad in destination element.
* *
* Unlinks the two named pads of the source and destination elements. * Unlinks the two named pads of the source and destination elements.
@ -2088,8 +2097,8 @@ free_src:
/** /**
* gst_element_unlink_many: * gst_element_unlink_many:
* @element_1: the first #GstElement in the link chain. * @element_1: (transfer none): the first #GstElement in the link chain.
* @element_2: the second #GstElement in the link chain. * @element_2: (transfer none): the second #GstElement in the link chain.
* @...: the NULL-terminated list of elements to unlink in order. * @...: the NULL-terminated list of elements to unlink in order.
* *
* Unlinks a series of elements. Uses gst_element_unlink(). * Unlinks a series of elements. Uses gst_element_unlink().
@ -2116,8 +2125,8 @@ gst_element_unlink_many (GstElement * element_1, GstElement * element_2, ...)
/** /**
* gst_element_unlink: * gst_element_unlink:
* @src: the source #GstElement to unlink. * @src: (transfer none): the source #GstElement to unlink.
* @dest: the sink #GstElement to unlink. * @dest: (transfer none): the sink #GstElement to unlink.
* *
* Unlinks all source pads of the source element with all sink pads * Unlinks all source pads of the source element with all sink pads
* of the sink element to which they are linked. * of the sink element to which they are linked.
@ -2184,9 +2193,10 @@ gst_element_unlink (GstElement * src, GstElement * dest)
/** /**
* gst_element_query_position: * gst_element_query_position:
* @element: a #GstElement to invoke the position query on. * @element: a #GstElement to invoke the position query on.
* @format: a pointer to the #GstFormat asked for. * @format: (inout): a pointer to the #GstFormat asked for.
* On return contains the #GstFormat used. * On return contains the #GstFormat used.
* @cur: A location in which to store the current position, or NULL. * @cur: (out) (allow-none): a location in which to store the current
* position, or NULL.
* *
* Queries an element for the stream position. * Queries an element for the stream position.
* *
@ -2248,10 +2258,10 @@ gst_element_query_duration (GstElement * element, GstFormat * format,
/** /**
* gst_element_query_convert: * gst_element_query_convert:
* @element: a #GstElement to invoke the convert query on. * @element: a #GstElement to invoke the convert query on.
* @src_format: a #GstFormat to convert from. * @src_format: (inout): a #GstFormat to convert from.
* @src_val: a value to convert. * @src_val: a value to convert.
* @dest_format: a pointer to the #GstFormat to convert to. * @dest_format: (inout): a pointer to the #GstFormat to convert to.
* @dest_val: a pointer to the result. * @dest_val: (out): a pointer to the result.
* *
* Queries an element to convert @src_val in @src_format to @dest_format. * Queries an element to convert @src_val in @src_format to @dest_format.
* *
@ -2352,7 +2362,9 @@ gst_pad_use_fixed_caps (GstPad * pad)
* will return the currently negotiated caps or the padtemplate * will return the currently negotiated caps or the padtemplate
* when NULL. * when NULL.
* *
* Returns: The currently negotiated caps or the padtemplate. * Free-function: gst_caps_unref
*
* Returns: (transfer full): the currently negotiated caps or the padtemplate.
*/ */
GstCaps * GstCaps *
gst_pad_get_fixed_caps_func (GstPad * pad) gst_pad_get_fixed_caps_func (GstPad * pad)
@ -2394,8 +2406,8 @@ gst_pad_get_fixed_caps_func (GstPad * pad)
* Gets the parent of @pad, cast to a #GstElement. If a @pad has no parent or * Gets the parent of @pad, cast to a #GstElement. If a @pad has no parent or
* its parent is not an element, return NULL. * its parent is not an element, return NULL.
* *
* Returns: The parent of the pad. The caller has a reference on the parent, so * Returns: (transfer full): the parent of the pad. The caller has a
* unref when you're finished with it. * reference on the parent, so unref when you're finished with it.
* *
* MT safe. * MT safe.
*/ */
@ -2418,8 +2430,8 @@ gst_pad_get_parent_element (GstPad * pad)
/** /**
* gst_object_default_error: * gst_object_default_error:
* @source: the #GstObject that initiated the error. * @source: the #GstObject that initiated the error.
* @error: the GError. * @error: (in): the GError.
* @debug: an additional debug information string, or NULL. * @debug: (in) (allow-none): an additional debug information string, or NULL
* *
* A default error function. * A default error function.
* *
@ -2440,8 +2452,8 @@ gst_object_default_error (GstObject * source, GError * error, gchar * debug)
/** /**
* gst_bin_add_many: * gst_bin_add_many:
* @bin: a #GstBin * @bin: a #GstBin
* @element_1: the #GstElement element to add to the bin * @element_1: (transfer full): the #GstElement element to add to the bin
* @...: additional elements to add to the bin * @...: (transfer full): additional elements to add to the bin
* *
* Adds a NULL-terminated list of elements to a bin. This function is * Adds a NULL-terminated list of elements to a bin. This function is
* equivalent to calling gst_bin_add() for each member of the list. The return * equivalent to calling gst_bin_add() for each member of the list. The return
@ -2469,8 +2481,8 @@ gst_bin_add_many (GstBin * bin, GstElement * element_1, ...)
/** /**
* gst_bin_remove_many: * gst_bin_remove_many:
* @bin: a #GstBin * @bin: a #GstBin
* @element_1: the first #GstElement to remove from the bin * @element_1: (transfer none): the first #GstElement to remove from the bin
* @...: NULL-terminated list of elements to remove from the bin * @...: (transfer none): NULL-terminated list of elements to remove from the bin
* *
* Remove a list of elements from a bin. This function is equivalent * Remove a list of elements from a bin. This function is equivalent
* to calling gst_bin_remove() with each member of the list. * to calling gst_bin_remove() with each member of the list.
@ -2618,8 +2630,8 @@ gst_element_class_install_std_props (GstElementClass * klass,
/** /**
* gst_buffer_merge: * gst_buffer_merge:
* @buf1: the first source #GstBuffer to merge. * @buf1: (transfer none): the first source #GstBuffer to merge.
* @buf2: the second source #GstBuffer to merge. * @buf2: (transfer none): the second source #GstBuffer to merge.
* *
* Create a new buffer that is the concatenation of the two source * Create a new buffer that is the concatenation of the two source
* buffers. The original source buffers will not be modified or * buffers. The original source buffers will not be modified or
@ -2629,7 +2641,10 @@ gst_element_class_install_std_props (GstElementClass * klass,
* If the buffers point to contiguous areas of memory, the buffer * If the buffers point to contiguous areas of memory, the buffer
* is created without copying the data. * is created without copying the data.
* *
* Returns: the new #GstBuffer which is the concatenation of the source buffers. * Free-function: gst_buffer_unref
*
* Returns: (transfer full): the new #GstBuffer which is the concatenation
* of the source buffers.
*/ */
GstBuffer * GstBuffer *
gst_buffer_merge (GstBuffer * buf1, GstBuffer * buf2) gst_buffer_merge (GstBuffer * buf1, GstBuffer * buf2)
@ -2675,7 +2690,7 @@ gst_buffer_join (GstBuffer * buf1, GstBuffer * buf2)
/** /**
* gst_buffer_stamp: * gst_buffer_stamp:
* @dest: buffer to stamp * @dest: (transfer none): buffer to stamp
* @src: buffer to stamp from * @src: buffer to stamp from
* *
* Copies additional information (the timestamp, duration, and offset start * Copies additional information (the timestamp, duration, and offset start
@ -2730,7 +2745,9 @@ getcaps_fold_func (GstPad * pad, GValue * ret, GstPad * orig)
* that can handle any stream format, but requires all its pads to have * that can handle any stream format, but requires all its pads to have
* the same caps. Two such elements are tee and adder. * the same caps. Two such elements are tee and adder.
* *
* Returns: the intersection of the other pads' allowed caps. * Free-function: gst_caps_unref
*
* Returns: (transfer full): the intersection of the other pads' allowed caps.
*/ */
GstCaps * GstCaps *
gst_pad_proxy_getcaps (GstPad * pad) gst_pad_proxy_getcaps (GstPad * pad)
@ -2845,7 +2862,7 @@ setcaps_fold_func (GstPad * pad, GValue * ret, SetCapsFoldData * data)
/** /**
* gst_pad_proxy_setcaps * gst_pad_proxy_setcaps
* @pad: a #GstPad to proxy from * @pad: a #GstPad to proxy from
* @caps: the #GstCaps to link with * @caps: (transfer none): the #GstCaps to link with
* *
* Calls gst_pad_set_caps() for every other pad belonging to the * Calls gst_pad_set_caps() for every other pad belonging to the
* same element as @pad. If gst_pad_set_caps() fails on any pad, * same element as @pad. If gst_pad_set_caps() fails on any pad,
@ -2956,9 +2973,10 @@ gst_pad_query_position (GstPad * pad, GstFormat * format, gint64 * cur)
* gst_pad_query_peer_position: * gst_pad_query_peer_position:
* @pad: a #GstPad on whose peer to invoke the position query on. * @pad: a #GstPad on whose peer to invoke the position query on.
* Must be a sink pad. * Must be a sink pad.
* @format: a pointer to the #GstFormat asked for. * @format: (inout): a pointer to the #GstFormat asked for.
* On return contains the #GstFormat used. * On return contains the #GstFormat used.
* @cur: A location in which to store the current position, or NULL. * @cur: (out) (allow-none): a location in which to store the current
* position, or NULL.
* *
* Queries the peer of a given sink pad for the stream position. * Queries the peer of a given sink pad for the stream position.
* *
@ -2986,9 +3004,10 @@ gst_pad_query_peer_position (GstPad * pad, GstFormat * format, gint64 * cur)
/** /**
* gst_pad_query_duration: * gst_pad_query_duration:
* @pad: a #GstPad to invoke the duration query on. * @pad: a #GstPad to invoke the duration query on.
* @format: a pointer to the #GstFormat asked for. * @format: (inout): a pointer to the #GstFormat asked for.
* On return contains the #GstFormat used. * On return contains the #GstFormat used.
* @duration: A location in which to store the total duration, or NULL. * @duration: (out) (allow-none): a location in which to store the total
* duration, or NULL.
* *
* Queries a pad for the total stream duration. * Queries a pad for the total stream duration.
* *
@ -3018,9 +3037,10 @@ gst_pad_query_duration (GstPad * pad, GstFormat * format, gint64 * duration)
* gst_pad_query_peer_duration: * gst_pad_query_peer_duration:
* @pad: a #GstPad on whose peer pad to invoke the duration query on. * @pad: a #GstPad on whose peer pad to invoke the duration query on.
* Must be a sink pad. * Must be a sink pad.
* @format: a pointer to the #GstFormat asked for. * @format: (inout) :a pointer to the #GstFormat asked for.
* On return contains the #GstFormat used. * On return contains the #GstFormat used.
* @duration: A location in which to store the total duration, or NULL. * @duration: (out) (allow-none): a location in which to store the total
* duration, or NULL.
* *
* Queries the peer pad of a given sink pad for the total stream duration. * Queries the peer pad of a given sink pad for the total stream duration.
* *
@ -3051,8 +3071,8 @@ gst_pad_query_peer_duration (GstPad * pad, GstFormat * format,
* @pad: a #GstPad to invoke the convert query on. * @pad: a #GstPad to invoke the convert query on.
* @src_format: a #GstFormat to convert from. * @src_format: a #GstFormat to convert from.
* @src_val: a value to convert. * @src_val: a value to convert.
* @dest_format: a pointer to the #GstFormat to convert to. * @dest_format: (inout): a pointer to the #GstFormat to convert to.
* @dest_val: a pointer to the result. * @dest_val: (out): a pointer to the result.
* *
* Queries a pad to convert @src_val in @src_format to @dest_format. * Queries a pad to convert @src_val in @src_format to @dest_format.
* *
@ -3091,8 +3111,8 @@ gst_pad_query_convert (GstPad * pad, GstFormat src_format, gint64 src_val,
* Must be a sink pad. * Must be a sink pad.
* @src_format: a #GstFormat to convert from. * @src_format: a #GstFormat to convert from.
* @src_val: a value to convert. * @src_val: a value to convert.
* @dest_format: a pointer to the #GstFormat to convert to. * @dest_format: (inout): a pointer to the #GstFormat to convert to.
* @dest_val: a pointer to the result. * @dest_val: (out): a pointer to the result.
* *
* Queries the peer pad of a given sink pad to convert @src_val in @src_format * Queries the peer pad of a given sink pad to convert @src_val in @src_format
* to @dest_format. * to @dest_format.
@ -3123,7 +3143,7 @@ gst_pad_query_peer_convert (GstPad * pad, GstFormat src_format, gint64 src_val,
/** /**
* gst_atomic_int_set: * gst_atomic_int_set:
* @atomic_int: pointer to an atomic integer * @atomic_int: (inout): pointer to an atomic integer
* @value: value to set * @value: value to set
* *
* Unconditionally sets the atomic integer to @value. * Unconditionally sets the atomic integer to @value.
@ -3146,7 +3166,7 @@ gst_atomic_int_set (gint * atomic_int, gint value)
* gst_pad_add_data_probe: * gst_pad_add_data_probe:
* @pad: pad to add the data probe handler to * @pad: pad to add the data probe handler to
* @handler: function to call when data is passed over pad * @handler: function to call when data is passed over pad
* @data: data to pass along with the handler * @data: (closure): data to pass along with the handler
* *
* Adds a "data probe" to a pad. This function will be called whenever data * Adds a "data probe" to a pad. This function will be called whenever data
* passes through a pad. In this case data means both events and buffers. The * passes through a pad. In this case data means both events and buffers. The
@ -3182,8 +3202,9 @@ gst_pad_add_data_probe (GstPad * pad, GCallback handler, gpointer data)
* gst_pad_add_data_probe_full: * gst_pad_add_data_probe_full:
* @pad: pad to add the data probe handler to * @pad: pad to add the data probe handler to
* @handler: function to call when data is passed over pad * @handler: function to call when data is passed over pad
* @data: data to pass along with the handler * @data: (closure): data to pass along with the handler
* @notify: function to call when the probe is disconnected, or NULL * @notify: (allow-none): function to call when the probe is disconnected,
* or NULL
* *
* Adds a "data probe" to a pad. This function will be called whenever data * Adds a "data probe" to a pad. This function will be called whenever data
* passes through a pad. In this case data means both events and buffers. The * passes through a pad. In this case data means both events and buffers. The
@ -3244,7 +3265,7 @@ gst_pad_add_data_probe_full (GstPad * pad, GCallback handler,
* gst_pad_add_event_probe: * gst_pad_add_event_probe:
* @pad: pad to add the event probe handler to * @pad: pad to add the event probe handler to
* @handler: function to call when events are passed over pad * @handler: function to call when events are passed over pad
* @data: data to pass along with the handler * @data: (closure): data to pass along with the handler
* *
* Adds a probe that will be called for all events passing through a pad. See * Adds a probe that will be called for all events passing through a pad. See
* gst_pad_add_data_probe() for more information. * gst_pad_add_data_probe() for more information.
@ -3261,8 +3282,8 @@ gst_pad_add_event_probe (GstPad * pad, GCallback handler, gpointer data)
* gst_pad_add_event_probe_full: * gst_pad_add_event_probe_full:
* @pad: pad to add the event probe handler to * @pad: pad to add the event probe handler to
* @handler: function to call when events are passed over pad * @handler: function to call when events are passed over pad
* @data: data to pass along with the handler, or NULL * @data: (closure): data to pass along with the handler, or NULL
* @notify: function to call when probe is disconnected, or NULL * @notify: (allow-none): function to call when probe is disconnected, or NULL
* *
* Adds a probe that will be called for all events passing through a pad. See * Adds a probe that will be called for all events passing through a pad. See
* gst_pad_add_data_probe() for more information. * gst_pad_add_data_probe() for more information.
@ -3302,7 +3323,7 @@ gst_pad_add_event_probe_full (GstPad * pad, GCallback handler,
* gst_pad_add_buffer_probe: * gst_pad_add_buffer_probe:
* @pad: pad to add the buffer probe handler to * @pad: pad to add the buffer probe handler to
* @handler: function to call when buffers are passed over pad * @handler: function to call when buffers are passed over pad
* @data: data to pass along with the handler * @data: (closure): data to pass along with the handler
* *
* Adds a probe that will be called for all buffers passing through a pad. See * Adds a probe that will be called for all buffers passing through a pad. See
* gst_pad_add_data_probe() for more information. * gst_pad_add_data_probe() for more information.
@ -3319,8 +3340,9 @@ gst_pad_add_buffer_probe (GstPad * pad, GCallback handler, gpointer data)
* gst_pad_add_buffer_probe_full: * gst_pad_add_buffer_probe_full:
* @pad: pad to add the buffer probe handler to * @pad: pad to add the buffer probe handler to
* @handler: function to call when buffer are passed over pad * @handler: function to call when buffer are passed over pad
* @data: data to pass along with the handler * @data: (closure): data to pass along with the handler
* @notify: function to call when the probe is disconnected, or NULL * @notify: (allow-none): function to call when the probe is disconnected,
* or NULL
* *
* Adds a probe that will be called for all buffers passing through a pad. See * Adds a probe that will be called for all buffers passing through a pad. See
* gst_pad_add_data_probe() for more information. * gst_pad_add_data_probe() for more information.
@ -3428,8 +3450,8 @@ gst_pad_remove_buffer_probe (GstPad * pad, guint handler_id)
/** /**
* gst_element_found_tags_for_pad: * gst_element_found_tags_for_pad:
* @element: element for which to post taglist to bus. * @element: element for which to post taglist to bus.
* @pad: pad on which to push tag-event. * @pad: (transfer none): pad on which to push tag-event
* @list: the taglist to post on the bus and create event from. * @list: (transfer full): the taglist to post on the bus and create event from
* *
* Posts a message to the bus that new tags were found and pushes the * Posts a message to the bus that new tags were found and pushes the
* tags as event. Takes ownership of the @list. * tags as event. Takes ownership of the @list.
@ -3462,7 +3484,7 @@ push_and_ref (GstPad * pad, GstEvent * event)
/** /**
* gst_element_found_tags: * gst_element_found_tags:
* @element: element for which we found the tags. * @element: element for which we found the tags.
* @list: list of tags. * @list: (transfer full): list of tags.
* *
* Posts a message to the bus that new tags were found, and pushes an event * Posts a message to the bus that new tags were found, and pushes an event
* to all sourcepads. Takes ownership of the @list. * to all sourcepads. Takes ownership of the @list.
@ -3559,7 +3581,7 @@ element_find_unlinked_pad (GstElement * element, GstPadDirection direction)
* owns a reference to it and should use gst_object_unref() on the * owns a reference to it and should use gst_object_unref() on the
* pad when it is not needed any longer. * pad when it is not needed any longer.
* *
* Returns: unlinked pad of the given direction, or NULL. * Returns: (transfer full): unlinked pad of the given direction, or NULL.
* *
* Since: 0.10.20 * Since: 0.10.20
*/ */
@ -3613,7 +3635,7 @@ gst_bin_find_unlinked_pad (GstBin * bin, GstPadDirection direction)
* owns a reference to it and should use gst_object_unref() on the * owns a reference to it and should use gst_object_unref() on the
* pad when it is not needed any longer. * pad when it is not needed any longer.
* *
* Returns: unlinked pad of the given direction, or NULL. * Returns: (transfer full): unlinked pad of the given direction, or NULL.
* *
* Since: 0.10.3 * Since: 0.10.3
* *
@ -3664,7 +3686,8 @@ gst_parse_bin_from_description (const gchar * bin_description,
* @bin_description: command line describing the bin * @bin_description: command line describing the bin
* @ghost_unlinked_pads: whether to automatically create ghost pads * @ghost_unlinked_pads: whether to automatically create ghost pads
* for unlinked source or sink pads within the bin * for unlinked source or sink pads within the bin
* @context: a parse context allocated with gst_parse_context_new(), or %NULL * @context: (transfer none) (allow-none): a parse context allocated with
* gst_parse_context_new(), or %NULL
* @flags: parsing options, or #GST_PARSE_FLAG_NONE * @flags: parsing options, or #GST_PARSE_FLAG_NONE
* @err: where to store the error message in case of an error, or NULL * @err: where to store the error message in case of an error, or NULL
* *
@ -3838,7 +3861,7 @@ gst_util_get_timestamp (void)
* @search_func: function to compare two elements, @search_data will always be passed as second argument * @search_func: function to compare two elements, @search_data will always be passed as second argument
* @mode: search mode that should be used * @mode: search mode that should be used
* @search_data: element that should be found * @search_data: element that should be found
* @user_data: data to pass to @search_func * @user_data: (closure): data to pass to @search_func
* *
* Searches inside @array for @search_data by using the comparison function * Searches inside @array for @search_data by using the comparison function
* @search_func. @array must be sorted ascending. * @search_func. @array must be sorted ascending.
@ -3951,7 +3974,7 @@ gst_util_greatest_common_divisor (gint a, gint b)
* gst_util_fraction_to_double: * gst_util_fraction_to_double:
* @src_n: Fraction numerator as #gint * @src_n: Fraction numerator as #gint
* @src_d: Fraction denominator #gint * @src_d: Fraction denominator #gint
* @dest: pointer to a #gdouble for the result * @dest: (out): pointer to a #gdouble for the result
* *
* Transforms a #gdouble to a fraction and simplifies the result. * Transforms a #gdouble to a fraction and simplifies the result.
* *
@ -3978,8 +4001,8 @@ gst_util_fraction_to_double (gint src_n, gint src_d, gdouble * dest)
/** /**
* gst_util_double_to_fraction: * gst_util_double_to_fraction:
* @src: #gdouble to transform * @src: #gdouble to transform
* @dest_n: pointer to a #gint to hold the result numerator * @dest_n: (out): pointer to a #gint to hold the result numerator
* @dest_d: pointer to a #gint to hold the result denominator * @dest_d: (out): pointer to a #gint to hold the result denominator
* *
* Transforms a #gdouble to a fraction and simplifies * Transforms a #gdouble to a fraction and simplifies
* the result. * the result.
@ -4077,8 +4100,8 @@ gst_util_double_to_fraction (gdouble src, gint * dest_n, gint * dest_d)
* @a_d: Denominator of first value * @a_d: Denominator of first value
* @b_n: Numerator of second value * @b_n: Numerator of second value
* @b_d: Denominator of second value * @b_d: Denominator of second value
* @res_n: Pointer to #gint to hold the result numerator * @res_n: (out): Pointer to #gint to hold the result numerator
* @res_d: Pointer to #gint to hold the result denominator * @res_d: (out): Pointer to #gint to hold the result denominator
* *
* Multiplies the fractions @a_n/@a_d and @b_n/@b_d and stores * Multiplies the fractions @a_n/@a_d and @b_n/@b_d and stores
* the result in @res_n and @res_d. * the result in @res_n and @res_d.
@ -4136,8 +4159,8 @@ gst_util_fraction_multiply (gint a_n, gint a_d, gint b_n, gint b_d,
* @a_d: Denominator of first value * @a_d: Denominator of first value
* @b_n: Numerator of second value * @b_n: Numerator of second value
* @b_d: Denominator of second value * @b_d: Denominator of second value
* @res_n: Pointer to #gint to hold the result numerator * @res_n: (out): Pointer to #gint to hold the result numerator
* @res_d: Pointer to #gint to hold the result denominator * @res_d: (out): Pointer to #gint to hold the result denominator
* *
* Adds the fractions @a_n/@a_d and @b_n/@b_d and stores * Adds the fractions @a_n/@a_d and @b_n/@b_d and stores
* the result in @res_n and @res_d. * the result in @res_n and @res_d.

30
gst/gstvalue.c
View file

@ -336,7 +336,7 @@ gst_value_list_prepend_value (GValue * value, const GValue * prepend_value)
/** /**
* gst_value_list_concat: * gst_value_list_concat:
* @dest: an uninitialized #GValue to take the result * @dest: (out caller-allocates): an uninitialized #GValue to take the result
* @value1: a #GValue * @value1: a #GValue
* @value2: a #GValue * @value2: a #GValue
* *
@ -408,7 +408,7 @@ gst_value_list_get_size (const GValue * value)
* Gets the value that is a member of the list contained in @value and * Gets the value that is a member of the list contained in @value and
* has the index @index. * has the index @index.
* *
* Returns: the value at the given index * Returns: (transfer none): the value at the given index
*/ */
const GValue * const GValue *
gst_value_list_get_value (const GValue * value, guint index) gst_value_list_get_value (const GValue * value, guint index)
@ -482,7 +482,7 @@ gst_value_array_get_size (const GValue * value)
* Gets the value that is a member of the array contained in @value and * Gets the value that is a member of the array contained in @value and
* has the index @index. * has the index @index.
* *
* Returns: the value at the given index * Returns: (transfer none): the value at the given index
*/ */
const GValue * const GValue *
gst_value_array_get_value (const GValue * value, guint index) gst_value_array_get_value (const GValue * value, guint index)
@ -1480,7 +1480,7 @@ gst_value_deserialize_fraction_range (GValue * dest, const gchar * s)
/** /**
* gst_value_set_caps: * gst_value_set_caps:
* @value: a GValue initialized to GST_TYPE_CAPS * @value: a GValue initialized to GST_TYPE_CAPS
* @caps: the caps to set the value to * @caps: (transfer none): the caps to set the value to
* *
* Sets the contents of @value to @caps. A reference to the * Sets the contents of @value to @caps. A reference to the
* provided @caps will be taken by the @value. * provided @caps will be taken by the @value.
@ -1503,7 +1503,7 @@ gst_value_set_caps (GValue * value, const GstCaps * caps)
* #GstCaps will not be modified, therefore the caller must take one * #GstCaps will not be modified, therefore the caller must take one
* before getting rid of the @value. * before getting rid of the @value.
* *
* Returns: the contents of @value * Returns: (transfer none): the contents of @value
*/ */
const GstCaps * const GstCaps *
gst_value_get_caps (const GValue * value) gst_value_get_caps (const GValue * value)
@ -1565,7 +1565,7 @@ gst_value_set_structure (GValue * value, const GstStructure * structure)
* *
* Gets the contents of @value. * Gets the contents of @value.
* *
* Returns: the contents of @value * Returns: (transfer none): the contents of @value
* *
* Since: 0.10.15 * Since: 0.10.15
*/ */
@ -3370,7 +3370,7 @@ gst_value_can_union (const GValue * value1, const GValue * value2)
/** /**
* gst_value_union: * gst_value_union:
* @dest: the destination value * @dest: (out caller-allocates): the destination value
* @value1: a value to union * @value1: a value to union
* @value2: another value to union * @value2: another value to union
* *
@ -3489,7 +3489,7 @@ gst_value_can_intersect (const GValue * value1, const GValue * value2)
/** /**
* gst_value_intersect: * gst_value_intersect:
* @dest: a uninitialized #GValue that will hold the calculated * @dest: (out caller-allocates): a uninitialized #GValue that will hold the calculated
* intersection value * intersection value
* @value1: a value to intersect * @value1: a value to intersect
* @value2: another value to intersect * @value2: another value to intersect
@ -3575,7 +3575,8 @@ gst_value_register_intersect_func (GType type1, GType type2,
/** /**
* gst_value_subtract: * gst_value_subtract:
* @dest: the destination value for the result if the subtraction is not empty * @dest: (out caller-allocates): the destination value for the result if the
* subtraction is not empty
* @minuend: the value to subtract from * @minuend: the value to subtract from
* @subtrahend: the value to subtract * @subtrahend: the value to subtract
* *
@ -3732,7 +3733,7 @@ gst_value_register (const GstValueTable * table)
/** /**
* gst_value_init_and_copy: * gst_value_init_and_copy:
* @dest: the target value * @dest: (out caller-allocates): the target value
* @src: the source value * @src: the source value
* *
* Initialises the target value to be of the same type as source and then copies * Initialises the target value to be of the same type as source and then copies
@ -3755,7 +3756,9 @@ gst_value_init_and_copy (GValue * dest, const GValue * src)
* tries to transform the given @value into a string representation that allows * tries to transform the given @value into a string representation that allows
* getting back this string later on using gst_value_deserialize(). * getting back this string later on using gst_value_deserialize().
* *
* Returns: the serialization for @value or NULL if none exists * Free-function: g_free
*
* Returns: (transfer full): the serialization for @value or NULL if none exists
*/ */
gchar * gchar *
gst_value_serialize (const GValue * value) gst_value_serialize (const GValue * value)
@ -3799,7 +3802,8 @@ gst_value_serialize (const GValue * value)
/** /**
* gst_value_deserialize: * gst_value_deserialize:
* @dest: #GValue to fill with contents of deserialization * @dest: (out caller-allocates): #GValue to fill with contents of
* deserialization
* @src: string to deserialize * @src: string to deserialize
* *
* Tries to deserialize a string into the type specified by the given GValue. * Tries to deserialize a string into the type specified by the given GValue.
@ -4261,7 +4265,7 @@ gst_value_set_date (GValue * value, const GDate * date)
* *
* Gets the contents of @value. * Gets the contents of @value.
* *
* Returns: the contents of @value * Returns: (transfer none): the contents of @value
*/ */
const GDate * const GDate *
gst_value_get_date (const GValue * value) gst_value_get_date (const GValue * value)

8
gst/gstvalue.h
View file

@ -352,7 +352,9 @@ typedef gint (* GstValueCompareFunc) (const GValue *value1,
* *
* Used by gst_value_serialize() to obtain a non-binary form of the #GValue. * Used by gst_value_serialize() to obtain a non-binary form of the #GValue.
* *
* Returns: the string representation of the value * Free-function: g_free
*
* Returns: (transfer full): the string representation of the value
*/ */
typedef gchar * (* GstValueSerializeFunc) (const GValue *value1); typedef gchar * (* GstValueSerializeFunc) (const GValue *value1);
@ -385,7 +387,7 @@ typedef gboolean (* GstValueUnionFunc) (GValue *dest,
/** /**
* GstValueIntersectFunc: * GstValueIntersectFunc:
* @dest: a #GValue for the result * @dest: (out caller-allocates): a #GValue for the result
* @value1: a #GValue operand * @value1: a #GValue operand
* @value2: a #GValue operand * @value2: a #GValue operand
* *
@ -403,7 +405,7 @@ typedef gboolean (* GstValueIntersectFunc) (GValue *dest,
/** /**
* GstValueSubtractFunc: * GstValueSubtractFunc:
* @dest: a #GValue for the result * @dest: (out caller-allocates): a #GValue for the result
* @minuend: a #GValue operand * @minuend: a #GValue operand
* @subtrahend: a #GValue operand * @subtrahend: a #GValue operand
* *