commit 3a2097e0401bf75793bf2edd9f96fc8701195abb Author: Sebastian Dröge Date: Wed Apr 5 17:16:16 2017 +0300 Initial commit diff --git a/Gir_Gst.toml b/Gir_Gst.toml new file mode 100644 index 000000000..3337d5b26 --- /dev/null +++ b/Gir_Gst.toml @@ -0,0 +1,12 @@ +[options] +girs_dir = "gir-files" +library = "Gst" +version = "1.0" +min_cfg_version = "1.0" +target_path = "gst-sys" +work_mode = "sys" + +external_libraries = [ + "GLib", + "GObject", +] diff --git a/gir-files/GLib-2.0.gir b/gir-files/GLib-2.0.gir new file mode 100644 index 000000000..2282f57b7 --- /dev/null +++ b/gir-files/GLib-2.0.gir @@ -0,0 +1,48803 @@ + + + + + + + + Integer representing a day of the month; between 1 and 31. +#G_DATE_BAD_DAY represents an invalid day of the month. + + + + Integer representing a year; #G_DATE_BAD_YEAR is the invalid +value. The year must be 1 or higher; negative (BC) years are not +allowed. The year is represented with four digits. + + + + Opaque type. See g_mutex_locker_new() for details. + + + + A type which is used to hold a process identification. + +On UNIX, processes are identified by a process id (an integer), +while Windows uses process handles (which are pointers). + +GPid is used in GLib only for descendant processes spawned with +the g_spawn functions. + + + + A GQuark is a non-zero integer which uniquely identifies a +particular string. A GQuark value of zero is associated to %NULL. + + + + A typedef alias for gchar**. This is mostly useful when used together with +g_auto(). + + + + Simply a replacement for time_t. It has been deprecated +since it is not equivalent to time_t on 64-bit platforms +with a 64-bit time_t. Unrelated to #GTimer. + +Note that #GTime is defined to always be a 32-bit integer, +unlike time_t which may be 64-bit on some systems. Therefore, +#GTime will overflow in the year 2038, and you cannot use the +address of a #GTime variable as argument to the UNIX time() +function. + +Instead, do the following: +|[<!-- language="C" --> +time_t ttime; +GTime gtime; + +time (&ttime); +gtime = (GTime)ttime; +]| + + + + A value representing an interval of time, in microseconds. + + + + + + + + + + A good size for a buffer to be passed into g_ascii_dtostr(). +It is guaranteed to be enough for all output of that function +on systems with 64bit IEEE-compatible doubles. + +The typical usage would be something like: +|[<!-- language="C" --> + char buf[G_ASCII_DTOSTR_BUF_SIZE]; + + fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); +]| + + + + Contains the public fields of a GArray. + + a pointer to the element data. The data may be moved as + elements are added to the #GArray. + + + + the number of elements in the #GArray not including the + possible terminating zero element. + + + + Adds @len elements onto the end of the array. + + the #GArray + + + + + + + a #GArray + + + + + + a pointer to the elements to append to the end of the array + + + + the number of elements to append + + + + + + Frees the memory allocated for the #GArray. If @free_segment is +%TRUE it frees the memory block holding the elements as well and +also each element if @array has a @element_free_func set. Pass +%FALSE if you want to free the #GArray wrapper but preserve the +underlying array for use elsewhere. If the reference count of @array +is greater than one, the #GArray wrapper is preserved but the size +of @array will be set to zero. + +If array elements contain dynamically-allocated memory, they should +be freed separately. + + the element data if @free_segment is %FALSE, otherwise + %NULL. The element data should be freed using g_free(). + + + + + a #GArray + + + + + + if %TRUE the actual element data is freed as well + + + + + + Gets the size of the elements in @array. + + Size of each element, in bytes + + + + + A #GArray + + + + + + + + Inserts @len elements into a #GArray at the given index. + + the #GArray + + + + + + + a #GArray + + + + + + the index to place the elements at + + + + a pointer to the elements to insert + + + + the number of elements to insert + + + + + + Creates a new #GArray with a reference count of 1. + + the new #GArray + + + + + + + %TRUE if the array should have an extra element at + the end which is set to 0 + + + + %TRUE if #GArray elements should be automatically cleared + to 0 when they are allocated + + + + the size of each element in bytes + + + + + + Adds @len elements onto the start of the array. + +This operation is slower than g_array_append_vals() since the +existing elements in the array have to be moved to make space for +the new elements. + + the #GArray + + + + + + + a #GArray + + + + + + a pointer to the elements to prepend to the start of the array + + + + the number of elements to prepend + + + + + + Atomically increments the reference count of @array by one. +This function is MT-safe and may be called from any thread. + + The passed in #GArray + + + + + + + A #GArray + + + + + + + + Removes the element at the given index from a #GArray. The following +elements are moved down one place. + + the #GArray + + + + + + + a #GArray + + + + + + the index of the element to remove + + + + + + Removes the element at the given index from a #GArray. The last +element in the array is used to fill in the space, so this function +does not preserve the order of the #GArray. But it is faster than +g_array_remove_index(). + + the #GArray + + + + + + + a @GArray + + + + + + the index of the element to remove + + + + + + Removes the given number of elements starting at the given index +from a #GArray. The following elements are moved to close the gap. + + the #GArray + + + + + + + a @GArray + + + + + + the index of the first element to remove + + + + the number of elements to remove + + + + + + Sets a function to clear an element of @array. + +The @clear_func will be called when an element in the array +data segment is removed and when the array is freed and data +segment is deallocated as well. + +Note that in contrast with other uses of #GDestroyNotify +functions, @clear_func is expected to clear the contents of +the array element it is given, but not free the element itself. + + + + + + A #GArray + + + + + + a function to clear an element of @array + + + + + + Sets the size of the array, expanding it if necessary. If the array +was created with @clear_ set to %TRUE, the new elements are set to 0. + + the #GArray + + + + + + + a #GArray + + + + + + the new size of the #GArray + + + + + + Creates a new #GArray with @reserved_size elements preallocated and +a reference count of 1. This avoids frequent reallocation, if you +are going to add many elements to the array. Note however that the +size of the array is still 0. + + the new #GArray + + + + + + + %TRUE if the array should have an extra element at + the end with all bits cleared + + + + %TRUE if all bits in the array should be cleared to 0 on + allocation + + + + size of each element in the array + + + + number of elements preallocated + + + + + + Sorts a #GArray using @compare_func which should be a qsort()-style +comparison function (returns less than zero for first arg is less +than second arg, zero for equal, greater zero if first arg is +greater than second arg). + +This is guaranteed to be a stable sort since version 2.32. + + + + + + a #GArray + + + + + + comparison function + + + + + + Like g_array_sort(), but the comparison function receives an extra +user data argument. + +This is guaranteed to be a stable sort since version 2.32. + +There used to be a comment here about making the sort stable by +using the addresses of the elements in the comparison function. +This did not actually work, so any such code should be removed. + + + + + + a #GArray + + + + + + comparison function + + + + data to pass to @compare_func + + + + + + Atomically decrements the reference count of @array by one. If the +reference count drops to 0, all memory allocated by the array is +released. This function is MT-safe and may be called from any +thread. + + + + + + A #GArray + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The GAsyncQueue struct is an opaque data structure which represents +an asynchronous queue. It should only be accessed through the +g_async_queue_* functions. + + Returns the length of the queue. + +Actually this function returns the number of data items in +the queue minus the number of waiting threads, so a negative +value means waiting threads, and a positive value means available +entries in the @queue. A return value of 0 could mean n entries +in the queue and n threads waiting. This can happen due to locking +of the queue or due to scheduling. + + the length of the @queue + + + + + a #GAsyncQueue. + + + + + + Returns the length of the queue. + +Actually this function returns the number of data items in +the queue minus the number of waiting threads, so a negative +value means waiting threads, and a positive value means available +entries in the @queue. A return value of 0 could mean n entries +in the queue and n threads waiting. This can happen due to locking +of the queue or due to scheduling. + +This function must be called while holding the @queue's lock. + + the length of the @queue. + + + + + a #GAsyncQueue + + + + + + Acquires the @queue's lock. If another thread is already +holding the lock, this call will block until the lock +becomes available. + +Call g_async_queue_unlock() to drop the lock again. + +While holding the lock, you can only call the +g_async_queue_*_unlocked() functions on @queue. Otherwise, +deadlock may occur. + + + + + + a #GAsyncQueue + + + + + + Pops data from the @queue. If @queue is empty, this function +blocks until data becomes available. + + data from the queue + + + + + a #GAsyncQueue + + + + + + Pops data from the @queue. If @queue is empty, this function +blocks until data becomes available. + +This function must be called while holding the @queue's lock. + + data from the queue. + + + + + a #GAsyncQueue + + + + + + Pushes the @data into the @queue. @data must not be %NULL. + + + + + + a #GAsyncQueue + + + + @data to push into the @queue + + + + + + Pushes the @item into the @queue. @item must not be %NULL. +In contrast to g_async_queue_push(), this function +pushes the new item ahead of the items already in the queue, +so that it will be the next one to be popped off the queue. + + + + + + a #GAsyncQueue + + + + data to push into the @queue + + + + + + Pushes the @item into the @queue. @item must not be %NULL. +In contrast to g_async_queue_push_unlocked(), this function +pushes the new item ahead of the items already in the queue, +so that it will be the next one to be popped off the queue. + +This function must be called while holding the @queue's lock. + + + + + + a #GAsyncQueue + + + + data to push into the @queue + + + + + + Inserts @data into @queue using @func to determine the new +position. + +This function requires that the @queue is sorted before pushing on +new elements, see g_async_queue_sort(). + +This function will lock @queue before it sorts the queue and unlock +it when it is finished. + +For an example of @func see g_async_queue_sort(). + + + + + + a #GAsyncQueue + + + + the @data to push into the @queue + + + + the #GCompareDataFunc is used to sort @queue + + + + user data passed to @func. + + + + + + Inserts @data into @queue using @func to determine the new +position. + +The sort function @func is passed two elements of the @queue. +It should return 0 if they are equal, a negative value if the +first element should be higher in the @queue or a positive value +if the first element should be lower in the @queue than the second +element. + +This function requires that the @queue is sorted before pushing on +new elements, see g_async_queue_sort(). + +This function must be called while holding the @queue's lock. + +For an example of @func see g_async_queue_sort(). + + + + + + a #GAsyncQueue + + + + the @data to push into the @queue + + + + the #GCompareDataFunc is used to sort @queue + + + + user data passed to @func. + + + + + + Pushes the @data into the @queue. @data must not be %NULL. + +This function must be called while holding the @queue's lock. + + + + + + a #GAsyncQueue + + + + @data to push into the @queue + + + + + + Increases the reference count of the asynchronous @queue by 1. +You do not need to hold the lock to call this function. + + the @queue that was passed in (since 2.6) + + + + + a #GAsyncQueue + + + + + + Increases the reference count of the asynchronous @queue by 1. + Reference counting is done atomically. +so g_async_queue_ref() can be used regardless of the @queue's +lock. + + + + + + a #GAsyncQueue + + + + + + Remove an item from the queue. + + %TRUE if the item was removed + + + + + a #GAsyncQueue + + + + the data to remove from the @queue + + + + + + Remove an item from the queue. + +This function must be called while holding the @queue's lock. + + %TRUE if the item was removed + + + + + a #GAsyncQueue + + + + the data to remove from the @queue + + + + + + Sorts @queue using @func. + +The sort function @func is passed two elements of the @queue. +It should return 0 if they are equal, a negative value if the +first element should be higher in the @queue or a positive value +if the first element should be lower in the @queue than the second +element. + +This function will lock @queue before it sorts the queue and unlock +it when it is finished. + +If you were sorting a list of priority numbers to make sure the +lowest priority would be at the top of the queue, you could use: +|[<!-- language="C" --> + gint32 id1; + gint32 id2; + + id1 = GPOINTER_TO_INT (element1); + id2 = GPOINTER_TO_INT (element2); + + return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1); +]| + + + + + + a #GAsyncQueue + + + + the #GCompareDataFunc is used to sort @queue + + + + user data passed to @func + + + + + + Sorts @queue using @func. + +The sort function @func is passed two elements of the @queue. +It should return 0 if they are equal, a negative value if the +first element should be higher in the @queue or a positive value +if the first element should be lower in the @queue than the second +element. + +This function must be called while holding the @queue's lock. + + + + + + a #GAsyncQueue + + + + the #GCompareDataFunc is used to sort @queue + + + + user data passed to @func + + + + + + Pops data from the @queue. If the queue is empty, blocks until +@end_time or until data becomes available. + +If no data is received before @end_time, %NULL is returned. + +To easily calculate @end_time, a combination of g_get_current_time() +and g_time_val_add() can be used. + use g_async_queue_timeout_pop(). + + data from the queue or %NULL, when no data is + received before @end_time. + + + + + a #GAsyncQueue + + + + a #GTimeVal, determining the final time + + + + + + Pops data from the @queue. If the queue is empty, blocks until +@end_time or until data becomes available. + +If no data is received before @end_time, %NULL is returned. + +To easily calculate @end_time, a combination of g_get_current_time() +and g_time_val_add() can be used. + +This function must be called while holding the @queue's lock. + use g_async_queue_timeout_pop_unlocked(). + + data from the queue or %NULL, when no data is + received before @end_time. + + + + + a #GAsyncQueue + + + + a #GTimeVal, determining the final time + + + + + + Pops data from the @queue. If the queue is empty, blocks for +@timeout microseconds, or until data becomes available. + +If no data is received before the timeout, %NULL is returned. + + data from the queue or %NULL, when no data is + received before the timeout. + + + + + a #GAsyncQueue + + + + the number of microseconds to wait + + + + + + Pops data from the @queue. If the queue is empty, blocks for +@timeout microseconds, or until data becomes available. + +If no data is received before the timeout, %NULL is returned. + +This function must be called while holding the @queue's lock. + + data from the queue or %NULL, when no data is + received before the timeout. + + + + + a #GAsyncQueue + + + + the number of microseconds to wait + + + + + + Tries to pop data from the @queue. If no data is available, +%NULL is returned. + + data from the queue or %NULL, when no data is + available immediately. + + + + + a #GAsyncQueue + + + + + + Tries to pop data from the @queue. If no data is available, +%NULL is returned. + +This function must be called while holding the @queue's lock. + + data from the queue or %NULL, when no data is + available immediately. + + + + + a #GAsyncQueue + + + + + + Releases the queue's lock. + +Calling this function when you have not acquired +the with g_async_queue_lock() leads to undefined +behaviour. + + + + + + a #GAsyncQueue + + + + + + Decreases the reference count of the asynchronous @queue by 1. + +If the reference count went to 0, the @queue will be destroyed +and the memory allocated will be freed. So you are not allowed +to use the @queue afterwards, as it might have disappeared. +You do not need to hold the lock to call this function. + + + + + + a #GAsyncQueue. + + + + + + Decreases the reference count of the asynchronous @queue by 1 +and releases the lock. This function must be called while holding +the @queue's lock. If the reference count went to 0, the @queue +will be destroyed and the memory allocated will be freed. + Reference counting is done atomically. +so g_async_queue_unref() can be used regardless of the @queue's +lock. + + + + + + a #GAsyncQueue + + + + + + Creates a new asynchronous queue. + + a new #GAsyncQueue. Free with g_async_queue_unref() + + + + + Creates a new asynchronous queue and sets up a destroy notify +function that is used to free any remaining queue items when +the queue is destroyed after the final unref. + + a new #GAsyncQueue. Free with g_async_queue_unref() + + + + + function to free queue elements + + + + + + + Specifies one of the possible types of byte order. +See #G_BYTE_ORDER. + + + + The `GBookmarkFile` structure contains only +private data and should not be directly accessed. + + Adds the application with @name and @exec to the list of +applications that have registered a bookmark for @uri into +@bookmark. + +Every bookmark inside a #GBookmarkFile must have at least an +application registered. Each application must provide a name, a +command line useful for launching the bookmark, the number of times +the bookmark has been registered by the application and the last +time the application registered this bookmark. + +If @name is %NULL, the name of the application will be the +same returned by g_get_application_name(); if @exec is %NULL, the +command line will be a composition of the program name as +returned by g_get_prgname() and the "\%u" modifier, which will be +expanded to the bookmark's URI. + +This function will automatically take care of updating the +registrations count and timestamping in case an application +with the same @name had already registered a bookmark for +@uri inside @bookmark. + +If no bookmark for @uri is found, one is created. + + + + + + a #GBookmarkFile + + + + a valid URI + + + + the name of the application registering the bookmark + or %NULL + + + + command line to be used to launch the bookmark or %NULL + + + + + + Adds @group to the list of groups to which the bookmark for @uri +belongs to. + +If no bookmark for @uri is found then it is created. + + + + + + a #GBookmarkFile + + + + a valid URI + + + + the group name to be added + + + + + + Frees a #GBookmarkFile. + + + + + + a #GBookmarkFile + + + + + + Gets the time the bookmark for @uri was added to @bookmark + +In the event the URI cannot be found, -1 is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + a timestamp + + + + + a #GBookmarkFile + + + + a valid URI + + + + + + Gets the registration informations of @app_name for the bookmark for +@uri. See g_bookmark_file_set_app_info() for more informations about +the returned data. + +The string returned in @app_exec must be freed. + +In the event the URI cannot be found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the +event that no application with name @app_name has registered a bookmark +for @uri, %FALSE is returned and error is set to +#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting +the command line fails, an error of the #G_SHELL_ERROR domain is +set and %FALSE is returned. + + %TRUE on success. + + + + + a #GBookmarkFile + + + + a valid URI + + + + an application's name + + + + return location for the command line of the application, or %NULL + + + + return location for the registration count, or %NULL + + + + return location for the last registration time, or %NULL + + + + + + Retrieves the names of the applications that have registered the +bookmark for @uri. + +In the event the URI cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + a newly allocated %NULL-terminated array of strings. + Use g_strfreev() to free it. + + + + + + + a #GBookmarkFile + + + + a valid URI + + + + return location of the length of the returned list, or %NULL + + + + + + Retrieves the description of the bookmark for @uri. + +In the event the URI cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + a newly allocated string or %NULL if the specified + URI cannot be found. + + + + + a #GBookmarkFile + + + + a valid URI + + + + + + Retrieves the list of group names of the bookmark for @uri. + +In the event the URI cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + +The returned array is %NULL terminated, so @length may optionally +be %NULL. + + a newly allocated %NULL-terminated array of group names. + Use g_strfreev() to free it. + + + + + + + a #GBookmarkFile + + + + a valid URI + + + + return location for the length of the returned string, or %NULL + + + + + + Gets the icon of the bookmark for @uri. + +In the event the URI cannot be found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + %TRUE if the icon for the bookmark for the URI was found. + You should free the returned strings. + + + + + a #GBookmarkFile + + + + a valid URI + + + + return location for the icon's location or %NULL + + + + return location for the icon's MIME type or %NULL + + + + + + Gets whether the private flag of the bookmark for @uri is set. + +In the event the URI cannot be found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the +event that the private flag cannot be found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. + + %TRUE if the private flag is set, %FALSE otherwise. + + + + + a #GBookmarkFile + + + + a valid URI + + + + + + Retrieves the MIME type of the resource pointed by @uri. + +In the event the URI cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the +event that the MIME type cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. + + a newly allocated string or %NULL if the specified + URI cannot be found. + + + + + a #GBookmarkFile + + + + a valid URI + + + + + + Gets the time when the bookmark for @uri was last modified. + +In the event the URI cannot be found, -1 is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + a timestamp + + + + + a #GBookmarkFile + + + + a valid URI + + + + + + Gets the number of bookmarks inside @bookmark. + + the number of bookmarks + + + + + a #GBookmarkFile + + + + + + Returns the title of the bookmark for @uri. + +If @uri is %NULL, the title of @bookmark is returned. + +In the event the URI cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + a newly allocated string or %NULL if the specified + URI cannot be found. + + + + + a #GBookmarkFile + + + + a valid URI or %NULL + + + + + + Returns all URIs of the bookmarks in the bookmark file @bookmark. +The array of returned URIs will be %NULL-terminated, so @length may +optionally be %NULL. + + a newly allocated %NULL-terminated array of strings. + Use g_strfreev() to free it. + + + + + + + a #GBookmarkFile + + + + return location for the number of returned URIs, or %NULL + + + + + + Gets the time the bookmark for @uri was last visited. + +In the event the URI cannot be found, -1 is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + a timestamp. + + + + + a #GBookmarkFile + + + + a valid URI + + + + + + Checks whether the bookmark for @uri inside @bookmark has been +registered by application @name. + +In the event the URI cannot be found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + %TRUE if the application @name was found + + + + + a #GBookmarkFile + + + + a valid URI + + + + the name of the application + + + + + + Checks whether @group appears in the list of groups to which +the bookmark for @uri belongs to. + +In the event the URI cannot be found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + %TRUE if @group was found. + + + + + a #GBookmarkFile + + + + a valid URI + + + + the group name to be searched + + + + + + Looks whether the desktop bookmark has an item with its URI set to @uri. + + %TRUE if @uri is inside @bookmark, %FALSE otherwise + + + + + a #GBookmarkFile + + + + a valid URI + + + + + + Loads a bookmark file from memory into an empty #GBookmarkFile +structure. If the object cannot be created then @error is set to a +#GBookmarkFileError. + + %TRUE if a desktop bookmark could be loaded. + + + + + an empty #GBookmarkFile struct + + + + desktop bookmarks loaded in memory + + + + the length of @data in bytes + + + + + + This function looks for a desktop bookmark file named @file in the +paths returned from g_get_user_data_dir() and g_get_system_data_dirs(), +loads the file into @bookmark and returns the file's full path in +@full_path. If the file could not be loaded then an %error is +set to either a #GFileError or #GBookmarkFileError. + + %TRUE if a key file could be loaded, %FALSE otherwise + + + + + a #GBookmarkFile + + + + a relative path to a filename to open and parse + + + + return location for a string + containing the full path of the file, or %NULL + + + + + + Loads a desktop bookmark file into an empty #GBookmarkFile structure. +If the file could not be loaded then @error is set to either a #GFileError +or #GBookmarkFileError. + + %TRUE if a desktop bookmark file could be loaded + + + + + an empty #GBookmarkFile struct + + + + the path of a filename to load, in the + GLib file name encoding + + + + + + Changes the URI of a bookmark item from @old_uri to @new_uri. Any +existing bookmark for @new_uri will be overwritten. If @new_uri is +%NULL, then the bookmark is removed. + +In the event the URI cannot be found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + %TRUE if the URI was successfully changed + + + + + a #GBookmarkFile + + + + a valid URI + + + + a valid URI, or %NULL + + + + + + Removes application registered with @name from the list of applications +that have registered a bookmark for @uri inside @bookmark. + +In the event the URI cannot be found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. +In the event that no application with name @app_name has registered +a bookmark for @uri, %FALSE is returned and error is set to +#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. + + %TRUE if the application was successfully removed. + + + + + a #GBookmarkFile + + + + a valid URI + + + + the name of the application + + + + + + Removes @group from the list of groups to which the bookmark +for @uri belongs to. + +In the event the URI cannot be found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. +In the event no group was defined, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. + + %TRUE if @group was successfully removed. + + + + + a #GBookmarkFile + + + + a valid URI + + + + the group name to be removed + + + + + + Removes the bookmark for @uri from the bookmark file @bookmark. + + %TRUE if the bookmark was removed successfully. + + + + + a #GBookmarkFile + + + + a valid URI + + + + + + Sets the time the bookmark for @uri was added into @bookmark. + +If no bookmark for @uri is found then it is created. + + + + + + a #GBookmarkFile + + + + a valid URI + + + + a timestamp or -1 to use the current time + + + + + + Sets the meta-data of application @name inside the list of +applications that have registered a bookmark for @uri inside +@bookmark. + +You should rarely use this function; use g_bookmark_file_add_application() +and g_bookmark_file_remove_application() instead. + +@name can be any UTF-8 encoded string used to identify an +application. +@exec can have one of these two modifiers: "\%f", which will +be expanded as the local file name retrieved from the bookmark's +URI; "\%u", which will be expanded as the bookmark's URI. +The expansion is done automatically when retrieving the stored +command line using the g_bookmark_file_get_app_info() function. +@count is the number of times the application has registered the +bookmark; if is < 0, the current registration count will be increased +by one, if is 0, the application with @name will be removed from +the list of registered applications. +@stamp is the Unix time of the last registration; if it is -1, the +current time will be used. + +If you try to remove an application by setting its registration count to +zero, and no bookmark for @uri is found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly, +in the event that no application @name has registered a bookmark +for @uri, %FALSE is returned and error is set to +#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark +for @uri is found, one is created. + + %TRUE if the application's meta-data was successfully + changed. + + + + + a #GBookmarkFile + + + + a valid URI + + + + an application's name + + + + an application's command line + + + + the number of registrations done for this application + + + + the time of the last registration for this application + + + + + + Sets @description as the description of the bookmark for @uri. + +If @uri is %NULL, the description of @bookmark is set. + +If a bookmark for @uri cannot be found then it is created. + + + + + + a #GBookmarkFile + + + + a valid URI or %NULL + + + + a string + + + + + + Sets a list of group names for the item with URI @uri. Each previously +set group name list is removed. + +If @uri cannot be found then an item for it is created. + + + + + + a #GBookmarkFile + + + + an item's URI + + + + an array of group names, or %NULL to remove all groups + + + + number of group name values in @groups + + + + + + Sets the icon for the bookmark for @uri. If @href is %NULL, unsets +the currently set icon. @href can either be a full URL for the icon +file or the icon name following the Icon Naming specification. + +If no bookmark for @uri is found one is created. + + + + + + a #GBookmarkFile + + + + a valid URI + + + + the URI of the icon for the bookmark, or %NULL + + + + the MIME type of the icon for the bookmark + + + + + + Sets the private flag of the bookmark for @uri. + +If a bookmark for @uri cannot be found then it is created. + + + + + + a #GBookmarkFile + + + + a valid URI + + + + %TRUE if the bookmark should be marked as private + + + + + + Sets @mime_type as the MIME type of the bookmark for @uri. + +If a bookmark for @uri cannot be found then it is created. + + + + + + a #GBookmarkFile + + + + a valid URI + + + + a MIME type + + + + + + Sets the last time the bookmark for @uri was last modified. + +If no bookmark for @uri is found then it is created. + +The "modified" time should only be set when the bookmark's meta-data +was actually changed. Every function of #GBookmarkFile that +modifies a bookmark also changes the modification time, except for +g_bookmark_file_set_visited(). + + + + + + a #GBookmarkFile + + + + a valid URI + + + + a timestamp or -1 to use the current time + + + + + + Sets @title as the title of the bookmark for @uri inside the +bookmark file @bookmark. + +If @uri is %NULL, the title of @bookmark is set. + +If a bookmark for @uri cannot be found then it is created. + + + + + + a #GBookmarkFile + + + + a valid URI or %NULL + + + + a UTF-8 encoded string + + + + + + Sets the time the bookmark for @uri was last visited. + +If no bookmark for @uri is found then it is created. + +The "visited" time should only be set if the bookmark was launched, +either using the command line retrieved by g_bookmark_file_get_app_info() +or by the default application for the bookmark's MIME type, retrieved +using g_bookmark_file_get_mime_type(). Changing the "visited" time +does not affect the "modified" time. + + + + + + a #GBookmarkFile + + + + a valid URI + + + + a timestamp or -1 to use the current time + + + + + + This function outputs @bookmark as a string. + + a newly allocated string holding + the contents of the #GBookmarkFile + + + + + a #GBookmarkFile + + + + return location for the length of the returned string, or %NULL + + + + + + This function outputs @bookmark into a file. The write process is +guaranteed to be atomic by using g_file_set_contents() internally. + + %TRUE if the file was successfully written. + + + + + a #GBookmarkFile + + + + path of the output file + + + + + + + + + + + Creates a new empty #GBookmarkFile object. + +Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data() +or g_bookmark_file_load_from_data_dirs() to read an existing bookmark +file. + + an empty #GBookmarkFile + + + + + + Error codes returned by bookmark file parsing. + + URI was ill-formed + + + a requested field was not found + + + a requested application did + not register a bookmark + + + a requested URI was not found + + + document was ill formed + + + the text being parsed was + in an unknown encoding + + + an error occurred while writing + + + requested file was not found + + + + Contains the public fields of a GByteArray. + + a pointer to the element data. The data may be moved as + elements are added to the #GByteArray + + + + the number of elements in the #GByteArray + + + + Adds the given bytes to the end of the #GByteArray. +The array will grow in size automatically if necessary. + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the byte data to be added + + + + the number of bytes to add + + + + + + Frees the memory allocated by the #GByteArray. If @free_segment is +%TRUE it frees the actual byte data. If the reference count of +@array is greater than one, the #GByteArray wrapper is preserved but +the size of @array will be set to zero. + + the element data if @free_segment is %FALSE, otherwise + %NULL. The element data should be freed using g_free(). + + + + + a #GByteArray + + + + + + if %TRUE the actual byte data is freed as well + + + + + + Transfers the data from the #GByteArray into a new immutable #GBytes. + +The #GByteArray is freed unless the reference count of @array is greater +than one, the #GByteArray wrapper is preserved but the size of @array +will be set to zero. + +This is identical to using g_bytes_new_take() and g_byte_array_free() +together. + + a new immutable #GBytes representing same + byte data that was in the array + + + + + a #GByteArray + + + + + + + + Creates a new #GByteArray with a reference count of 1. + + the new #GByteArray + + + + + + + Create byte array containing the data. The data will be owned by the array +and will be freed with g_free(), i.e. it could be allocated using g_strdup(). + + a new #GByteArray + + + + + + + byte data for the array + + + + + + length of @data + + + + + + Adds the given data to the start of the #GByteArray. +The array will grow in size automatically if necessary. + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the byte data to be added + + + + the number of bytes to add + + + + + + Atomically increments the reference count of @array by one. +This function is thread-safe and may be called from any thread. + + The passed in #GByteArray + + + + + + + A #GByteArray + + + + + + + + Removes the byte at the given index from a #GByteArray. +The following bytes are moved down one place. + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the index of the byte to remove + + + + + + Removes the byte at the given index from a #GByteArray. The last +element in the array is used to fill in the space, so this function +does not preserve the order of the #GByteArray. But it is faster +than g_byte_array_remove_index(). + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the index of the byte to remove + + + + + + Removes the given number of bytes starting at the given index from a +#GByteArray. The following elements are moved to close the gap. + + the #GByteArray + + + + + + + a @GByteArray + + + + + + the index of the first byte to remove + + + + the number of bytes to remove + + + + + + Sets the size of the #GByteArray, expanding it if necessary. + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the new size of the #GByteArray + + + + + + Creates a new #GByteArray with @reserved_size bytes preallocated. +This avoids frequent reallocation, if you are going to add many +bytes to the array. Note however that the size of the array is still +0. + + the new #GByteArray + + + + + + + number of bytes preallocated + + + + + + Sorts a byte array, using @compare_func which should be a +qsort()-style comparison function (returns less than zero for first +arg is less than second arg, zero for equal, greater than zero if +first arg is greater than second arg). + +If two array elements compare equal, their order in the sorted array +is undefined. If you want equal elements to keep their order (i.e. +you want a stable sort) you can write a comparison function that, +if two elements would otherwise compare equal, compares them by +their addresses. + + + + + + a #GByteArray + + + + + + comparison function + + + + + + Like g_byte_array_sort(), but the comparison function takes an extra +user data argument. + + + + + + a #GByteArray + + + + + + comparison function + + + + data to pass to @compare_func + + + + + + Atomically decrements the reference count of @array by one. If the +reference count drops to 0, all memory allocated by the array is +released. This function is thread-safe and may be called from any +thread. + + + + + + A #GByteArray + + + + + + + + + A simple refcounted data type representing an immutable sequence of zero or +more bytes from an unspecified origin. + +The purpose of a #GBytes is to keep the memory region that it holds +alive for as long as anyone holds a reference to the bytes. When +the last reference count is dropped, the memory is released. Multiple +unrelated callers can use byte data in the #GBytes without coordinating +their activities, resting assured that the byte data will not change or +move while they hold a reference. + +A #GBytes can come from many different origins that may have +different procedures for freeing the memory region. Examples are +memory from g_malloc(), from memory slices, from a #GMappedFile or +memory from other allocators. + +#GBytes work well as keys in #GHashTable. Use g_bytes_equal() and +g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full(). +#GBytes can also be used as keys in a #GTree by passing the g_bytes_compare() +function to g_tree_new(). + +The data pointed to by this bytes must not be modified. For a mutable +array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a +mutable array for a #GBytes sequence. To create an immutable #GBytes from +a mutable #GByteArray, use the g_byte_array_free_to_bytes() function. + + Creates a new #GBytes from @data. + +@data is copied. If @size is 0, @data may be %NULL. + + a new #GBytes + + + + + + the data to be used for the bytes + + + + + + the size of @data + + + + + + Creates a new #GBytes from static data. + +@data must be static (ie: never modified or freed). It may be %NULL if @size +is 0. + + a new #GBytes + + + + + + the data to be used for the bytes + + + + + + the size of @data + + + + + + Creates a new #GBytes from @data. + +After this call, @data belongs to the bytes and may no longer be +modified by the caller. g_free() will be called on @data when the +bytes is no longer in use. Because of this @data must have been created by +a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many +functions that wrap these calls (such as g_new(), g_strdup(), etc). + +For creating #GBytes with memory from other allocators, see +g_bytes_new_with_free_func(). + +@data may be %NULL if @size is 0. + + a new #GBytes + + + + + + the data to be used for the bytes + + + + + + the size of @data + + + + + + Creates a #GBytes from @data. + +When the last reference is dropped, @free_func will be called with the +@user_data argument. + +@data must not be modified after this call is made until @free_func has +been called to indicate that the bytes is no longer in use. + +@data may be %NULL if @size is 0. + + a new #GBytes + + + + + + the data to be used for the bytes + + + + + + the size of @data + + + + the function to call to release the data + + + + data to pass to @free_func + + + + + + Compares the two #GBytes values. + +This function can be used to sort GBytes instances in lexographical order. + + a negative value if bytes2 is lesser, a positive value if bytes2 is + greater, and zero if bytes2 is equal to bytes1 + + + + + a pointer to a #GBytes + + + + a pointer to a #GBytes to compare with @bytes1 + + + + + + Compares the two #GBytes values being pointed to and returns +%TRUE if they are equal. + +This function can be passed to g_hash_table_new() as the @key_equal_func +parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. + + %TRUE if the two keys match. + + + + + a pointer to a #GBytes + + + + a pointer to a #GBytes to compare with @bytes1 + + + + + + Get the byte data in the #GBytes. This data should not be modified. + +This function will always return the same pointer for a given #GBytes. + +%NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes +may represent an empty string with @data non-%NULL and @size as 0. %NULL will +not be returned if @size is non-zero. + + + a pointer to the byte data, or %NULL + + + + + + + a #GBytes + + + + location to return size of byte data + + + + + + Get the size of the byte data in the #GBytes. + +This function will always return the same value for a given #GBytes. + + the size + + + + + a #GBytes + + + + + + Creates an integer hash code for the byte data in the #GBytes. + +This function can be passed to g_hash_table_new() as the @key_hash_func +parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. + + a hash value corresponding to the key. + + + + + a pointer to a #GBytes key + + + + + + Creates a #GBytes which is a subsection of another #GBytes. The @offset + +@length may not be longer than the size of @bytes. + +A reference to @bytes will be held by the newly created #GBytes until +the byte data is no longer needed. + + a new #GBytes + + + + + a #GBytes + + + + offset which subsection starts at + + + + length of subsection + + + + + + Increase the reference count on @bytes. + + the #GBytes + + + + + a #GBytes + + + + + + Releases a reference on @bytes. This may result in the bytes being +freed. + + + + + + a #GBytes + + + + + + Unreferences the bytes, and returns a new mutable #GByteArray containing +the same byte data. + +As an optimization, the byte data is transferred to the array without copying +if this was the last reference to bytes and bytes was created with +g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all +other cases the data is copied. + + a new mutable #GByteArray containing the same byte data + + + + + + + a #GBytes + + + + + + Unreferences the bytes, and returns a pointer the same byte data +contents. + +As an optimization, the byte data is returned without copying if this was +the last reference to bytes and bytes was created with g_bytes_new(), +g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the +data is copied. + + a pointer to the same byte data, which should be + freed with g_free() + + + + + + + a #GBytes + + + + location to place the length of the returned data + + + + + + + The set of uppercase ASCII alphabet characters. +Used for specifying valid identifier characters +in #GScannerConfig. + + + + The set of ASCII digits. +Used for specifying valid identifier characters +in #GScannerConfig. + + + + The set of lowercase ASCII alphabet characters. +Used for specifying valid identifier characters +in #GScannerConfig. + + + + An opaque structure representing a checksumming operation. +To create a new GChecksum, use g_checksum_new(). To free +a GChecksum, use g_checksum_free(). + + Creates a new #GChecksum, using the checksum algorithm @checksum_type. +If the @checksum_type is not known, %NULL is returned. +A #GChecksum can be used to compute the checksum, or digest, of an +arbitrary binary blob, using different hashing algorithms. + +A #GChecksum works by feeding a binary blob through g_checksum_update() +until there is data to be checked; the digest can then be extracted +using g_checksum_get_string(), which will return the checksum as a +hexadecimal string; or g_checksum_get_digest(), which will return a +vector of raw bytes. Once either g_checksum_get_string() or +g_checksum_get_digest() have been called on a #GChecksum, the checksum +will be closed and it won't be possible to call g_checksum_update() +on it anymore. + + the newly created #GChecksum, or %NULL. + Use g_checksum_free() to free the memory allocated by it. + + + + + the desired type of checksum + + + + + + Copies a #GChecksum. If @checksum has been closed, by calling +g_checksum_get_string() or g_checksum_get_digest(), the copied +checksum will be closed as well. + + the copy of the passed #GChecksum. Use g_checksum_free() + when finished using it. + + + + + the #GChecksum to copy + + + + + + Frees the memory allocated for @checksum. + + + + + + a #GChecksum + + + + + + Gets the digest from @checksum as a raw binary vector and places it +into @buffer. The size of the digest depends on the type of checksum. + +Once this function has been called, the #GChecksum is closed and can +no longer be updated with g_checksum_update(). + + + + + + a #GChecksum + + + + output buffer + + + + an inout parameter. The caller initializes it to the size of @buffer. + After the call it contains the length of the digest. + + + + + + Gets the digest as an hexadecimal string. + +Once this function has been called the #GChecksum can no longer be +updated with g_checksum_update(). + +The hexadecimal characters will be lower case. + + the hexadecimal representation of the checksum. The + returned string is owned by the checksum and should not be modified + or freed. + + + + + a #GChecksum + + + + + + Resets the state of the @checksum back to its initial state. + + + + + + the #GChecksum to reset + + + + + + Feeds @data into an existing #GChecksum. The checksum must still be +open, that is g_checksum_get_string() or g_checksum_get_digest() must +not have been called on @checksum. + + + + + + a #GChecksum + + + + buffer used to compute the checksum + + + + + + size of the buffer, or -1 if it is a null-terminated string. + + + + + + Gets the length in bytes of digests of type @checksum_type + + the checksum length, or -1 if @checksum_type is +not supported. + + + + + a #GChecksumType + + + + + + + The hashing algorithm to be used by #GChecksum when performing the +digest of some data. + +Note that the #GChecksumType enumeration may be extended at a later +date to include new hashing algorithm types. + + Use the MD5 hashing algorithm + + + Use the SHA-1 hashing algorithm + + + Use the SHA-256 hashing algorithm + + + Use the SHA-512 hashing algorithm (Since: 2.36) + + + + Prototype of a #GChildWatchSource callback, called when a child +process has exited. To interpret @status, see the documentation +for g_spawn_check_exit_status(). + + + + + + the process id of the child process + + + + Status information about the child process, encoded + in a platform-specific manner + + + + user data passed to g_child_watch_add() + + + + + + Specifies the type of a comparison function used to compare two +values. The function should return a negative integer if the first +value comes before the second, 0 if they are equal, or a positive +integer if the first value comes after the second. + + negative value if @a < @b; zero if @a = @b; positive + value if @a > @b + + + + + a value + + + + a value to compare with + + + + user data + + + + + + Specifies the type of a comparison function used to compare two +values. The function should return a negative integer if the first +value comes before the second, 0 if they are equal, or a positive +integer if the first value comes after the second. + + negative value if @a < @b; zero if @a = @b; positive + value if @a > @b + + + + + a value + + + + a value to compare with + + + + + + The #GCond struct is an opaque data structure that represents a +condition. Threads can block on a #GCond if they find a certain +condition to be false. If other threads change the state of this +condition they signal the #GCond, and that causes the waiting +threads to be woken up. + +Consider the following example of a shared variable. One or more +threads can wait for data to be published to the variable and when +another thread publishes the data, it can signal one of the waiting +threads to wake up to collect the data. + +Here is an example for using GCond to block a thread until a condition +is satisfied: +|[<!-- language="C" --> + gpointer current_data = NULL; + GMutex data_mutex; + GCond data_cond; + + void + push_data (gpointer data) + { + g_mutex_lock (&data_mutex); + current_data = data; + g_cond_signal (&data_cond); + g_mutex_unlock (&data_mutex); + } + + gpointer + pop_data (void) + { + gpointer data; + + g_mutex_lock (&data_mutex); + while (!current_data) + g_cond_wait (&data_cond, &data_mutex); + data = current_data; + current_data = NULL; + g_mutex_unlock (&data_mutex); + + return data; + } +]| +Whenever a thread calls pop_data() now, it will wait until +current_data is non-%NULL, i.e. until some other thread +has called push_data(). + +The example shows that use of a condition variable must always be +paired with a mutex. Without the use of a mutex, there would be a +race between the check of @current_data by the while loop in +pop_data() and waiting. Specifically, another thread could set +@current_data after the check, and signal the cond (with nobody +waiting on it) before the first thread goes to sleep. #GCond is +specifically useful for its ability to release the mutex and go +to sleep atomically. + +It is also important to use the g_cond_wait() and g_cond_wait_until() +functions only inside a loop which checks for the condition to be +true. See g_cond_wait() for an explanation of why the condition may +not be true even after it returns. + +If a #GCond is allocated in static storage then it can be used +without initialisation. Otherwise, you should call g_cond_init() +on it and g_cond_clear() when done. + +A #GCond should only be accessed via the g_cond_ functions. + + + + + + + + + + If threads are waiting for @cond, all of them are unblocked. +If no threads are waiting for @cond, this function has no effect. +It is good practice to lock the same mutex as the waiting threads +while calling this function, though not required. + + + + + + a #GCond + + + + + + Frees the resources allocated to a #GCond with g_cond_init(). + +This function should not be used with a #GCond that has been +statically allocated. + +Calling g_cond_clear() for a #GCond on which threads are +blocking leads to undefined behaviour. + + + + + + an initialised #GCond + + + + + + Initialises a #GCond so that it can be used. + +This function is useful to initialise a #GCond that has been +allocated as part of a larger structure. It is not necessary to +initialise a #GCond that has been statically allocated. + +To undo the effect of g_cond_init() when a #GCond is no longer +needed, use g_cond_clear(). + +Calling g_cond_init() on an already-initialised #GCond leads +to undefined behaviour. + + + + + + an uninitialized #GCond + + + + + + If threads are waiting for @cond, at least one of them is unblocked. +If no threads are waiting for @cond, this function has no effect. +It is good practice to hold the same lock as the waiting thread +while calling this function, though not required. + + + + + + a #GCond + + + + + + Atomically releases @mutex and waits until @cond is signalled. +When this function returns, @mutex is locked again and owned by the +calling thread. + +When using condition variables, it is possible that a spurious wakeup +may occur (ie: g_cond_wait() returns even though g_cond_signal() was +not called). It's also possible that a stolen wakeup may occur. +This is when g_cond_signal() is called, but another thread acquires +@mutex before this thread and modifies the state of the program in +such a way that when g_cond_wait() is able to return, the expected +condition is no longer met. + +For this reason, g_cond_wait() must always be used in a loop. See +the documentation for #GCond for a complete example. + + + + + + a #GCond + + + + a #GMutex that is currently locked + + + + + + Waits until either @cond is signalled or @end_time has passed. + +As with g_cond_wait() it is possible that a spurious or stolen wakeup +could occur. For that reason, waiting on a condition variable should +always be in a loop, based on an explicitly-checked predicate. + +%TRUE is returned if the condition variable was signalled (or in the +case of a spurious wakeup). %FALSE is returned if @end_time has +passed. + +The following code shows how to correctly perform a timed wait on a +condition variable (extending the example presented in the +documentation for #GCond): + +|[<!-- language="C" --> +gpointer +pop_data_timed (void) +{ + gint64 end_time; + gpointer data; + + g_mutex_lock (&data_mutex); + + end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND; + while (!current_data) + if (!g_cond_wait_until (&data_cond, &data_mutex, end_time)) + { + // timeout has passed. + g_mutex_unlock (&data_mutex); + return NULL; + } + + // there is data for us + data = current_data; + current_data = NULL; + + g_mutex_unlock (&data_mutex); + + return data; +} +]| + +Notice that the end time is calculated once, before entering the +loop and reused. This is the motivation behind the use of absolute +time on this API -- if a relative time of 5 seconds were passed +directly to the call and a spurious wakeup occurred, the program would +have to start over waiting again (which would lead to a total wait +time of more than 5 seconds). + + %TRUE on a signal, %FALSE on a timeout + + + + + a #GCond + + + + a #GMutex that is currently locked + + + + the monotonic time to wait until + + + + + + + Error codes returned by character set conversion routines. + + Conversion between the requested character + sets is not supported. + + + Invalid byte sequence in conversion input. + + + Conversion failed for some reason. + + + Partial character sequence at end of input. + + + URI is invalid. + + + Pathname is not an absolute path. + + + No memory available. Since: 2.40 + + + + A function of this signature is used to copy the node data +when doing a deep-copy of a tree. + + A pointer to the copy + + + + + A pointer to the data which should be copied + + + + Additional data + + + + + + A bitmask that restricts the possible flags passed to +g_datalist_set_flags(). Passing a flags value where +flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. + + + + Represents an invalid #GDateDay. + + + + Represents an invalid Julian day number. + + + + Represents an invalid year. + + + + The directory separator character. +This is '/' on UNIX machines and '\' under Windows. + + + + The directory separator as a string. +This is "/" on UNIX machines and "\" under Windows. + + + + The #GData struct is an opaque data structure to represent a +[Keyed Data List][glib-Keyed-Data-Lists]. It should only be +accessed via the following functions. + + + Specifies the type of function passed to g_dataset_foreach(). It is +called with each #GQuark id and associated data element, together +with the @user_data parameter supplied to g_dataset_foreach(). + + + + + + the #GQuark id to identifying the data element. + + + + the data element. + + + + user data passed to g_dataset_foreach(). + + + + + + Represents a day between January 1, Year 1 and a few thousand years in +the future. None of its members should be accessed directly. + +If the #GDate-struct is obtained from g_date_new(), it will be safe +to mutate but invalid and thus not safe for calendrical computations. + +If it's declared on the stack, it will contain garbage so must be +initialized with g_date_clear(). g_date_clear() makes the date invalid +but sane. An invalid date doesn't represent a day, it's "empty." A date +becomes valid after you set it to a Julian day or you set a day, month, +and year. + + the Julian representation of the date + + + + this bit is set if @julian_days is valid + + + + this is set if @day, @month and @year are valid + + + + the day of the day-month-year representation of the date, + as a number between 1 and 31 + + + + the day of the day-month-year representation of the date, + as a number between 1 and 12 + + + + the day of the day-month-year representation of the date + + + + Allocates a #GDate and initializes +it to a sane state. The new date will +be cleared (as if you'd called g_date_clear()) but invalid (it won't +represent an existing day). Free the return value with g_date_free(). + + a newly-allocated #GDate + + + + + Like g_date_new(), but also sets the value of the date. Assuming the +day-month-year triplet you pass in represents an existing day, the +returned date will be valid. + + a newly-allocated #GDate initialized with @day, @month, and @year + + + + + day of the month + + + + month of the year + + + + year + + + + + + Like g_date_new(), but also sets the value of the date. Assuming the +Julian day number you pass in is valid (greater than 0, less than an +unreasonably large number), the returned date will be valid. + + a newly-allocated #GDate initialized with @julian_day + + + + + days since January 1, Year 1 + + + + + + Increments a date some number of days. +To move forward by weeks, add weeks*7 days. +The date must be valid. + + + + + + a #GDate to increment + + + + number of days to move the date forward + + + + + + Increments a date by some number of months. +If the day of the month is greater than 28, +this routine may change the day of the month +(because the destination month may not have +the current day in it). The date must be valid. + + + + + + a #GDate to increment + + + + number of months to move forward + + + + + + Increments a date by some number of years. +If the date is February 29, and the destination +year is not a leap year, the date will be changed +to February 28. The date must be valid. + + + + + + a #GDate to increment + + + + number of years to move forward + + + + + + If @date is prior to @min_date, sets @date equal to @min_date. +If @date falls after @max_date, sets @date equal to @max_date. +Otherwise, @date is unchanged. +Either of @min_date and @max_date may be %NULL. +All non-%NULL dates must be valid. + + + + + + a #GDate to clamp + + + + minimum accepted value for @date + + + + maximum accepted value for @date + + + + + + Initializes one or more #GDate structs to a sane but invalid +state. The cleared dates will not represent an existing date, but will +not contain garbage. Useful to init a date declared on the stack. +Validity can be tested with g_date_valid(). + + + + + + pointer to one or more dates to clear + + + + number of dates to clear + + + + + + qsort()-style comparison function for dates. +Both dates must be valid. + + 0 for equal, less than zero if @lhs is less than @rhs, + greater than zero if @lhs is greater than @rhs + + + + + first date to compare + + + + second date to compare + + + + + + Computes the number of days between two dates. +If @date2 is prior to @date1, the returned value is negative. +Both dates must be valid. + + the number of days between @date1 and @date2 + + + + + the first date + + + + the second date + + + + + + Frees a #GDate returned from g_date_new(). + + + + + + a #GDate to free + + + + + + Returns the day of the month. The date must be valid. + + day of the month + + + + + a #GDate to extract the day of the month from + + + + + + Returns the day of the year, where Jan 1 is the first day of the +year. The date must be valid. + + day of the year + + + + + a #GDate to extract day of year from + + + + + + Returns the week of the year, where weeks are interpreted according +to ISO 8601. + + ISO 8601 week number of the year. + + + + + a valid #GDate + + + + + + Returns the Julian day or "serial number" of the #GDate. The +Julian day is simply the number of days since January 1, Year 1; i.e., +January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, +etc. The date must be valid. + + Julian day + + + + + a #GDate to extract the Julian day from + + + + + + Returns the week of the year, where weeks are understood to start on +Monday. If the date is before the first Monday of the year, return 0. +The date must be valid. + + week of the year + + + + + a #GDate + + + + + + Returns the month of the year. The date must be valid. + + month of the year as a #GDateMonth + + + + + a #GDate to get the month from + + + + + + Returns the week of the year during which this date falls, if +weeks are understood to begin on Sunday. The date must be valid. +Can return 0 if the day is before the first Sunday of the year. + + week number + + + + + a #GDate + + + + + + Returns the day of the week for a #GDate. The date must be valid. + + day of the week as a #GDateWeekday. + + + + + a #GDate + + + + + + Returns the year of a #GDate. The date must be valid. + + year in which the date falls + + + + + a #GDate + + + + + + Returns %TRUE if the date is on the first of a month. +The date must be valid. + + %TRUE if the date is the first of the month + + + + + a #GDate to check + + + + + + Returns %TRUE if the date is the last day of the month. +The date must be valid. + + %TRUE if the date is the last day of the month + + + + + a #GDate to check + + + + + + Checks if @date1 is less than or equal to @date2, +and swap the values if this is not the case. + + + + + + the first date + + + + the second date + + + + + + Sets the day of the month for a #GDate. If the resulting +day-month-year triplet is invalid, the date will be invalid. + + + + + + a #GDate + + + + day to set + + + + + + Sets the value of a #GDate from a day, month, and year. +The day-month-year triplet must be valid; if you aren't +sure it is, call g_date_valid_dmy() to check before you +set it. + + + + + + a #GDate + + + + day + + + + month + + + + year + + + + + + Sets the value of a #GDate from a Julian day number. + + + + + + a #GDate + + + + Julian day number (days since January 1, Year 1) + + + + + + Sets the month of the year for a #GDate. If the resulting +day-month-year triplet is invalid, the date will be invalid. + + + + + + a #GDate + + + + month to set + + + + + + Parses a user-inputted string @str, and try to figure out what date it +represents, taking the [current locale][setlocale] into account. If the +string is successfully parsed, the date will be valid after the call. +Otherwise, it will be invalid. You should check using g_date_valid() +to see whether the parsing succeeded. + +This function is not appropriate for file formats and the like; it +isn't very precise, and its exact behavior varies with the locale. +It's intended to be a heuristic routine that guesses what the user +means by a given string (and it does work pretty well in that +capacity). + + + + + + a #GDate to fill in + + + + string to parse + + + + + + Sets the value of a date from a #GTime value. +The time to date conversion is done using the user's current timezone. + Use g_date_set_time_t() instead. + + + + + + a #GDate. + + + + #GTime value to set. + + + + + + Sets the value of a date to the date corresponding to a time +specified as a time_t. The time to date conversion is done using +the user's current timezone. + +To set the value of a date to the current day, you could write: +|[<!-- language="C" --> + g_date_set_time_t (date, time (NULL)); +]| + + + + + + a #GDate + + + + time_t value to set + + + + + + Sets the value of a date from a #GTimeVal value. Note that the +@tv_usec member is ignored, because #GDate can't make use of the +additional precision. + +The time to date conversion is done using the user's current timezone. + + + + + + a #GDate + + + + #GTimeVal value to set + + + + + + Sets the year for a #GDate. If the resulting day-month-year +triplet is invalid, the date will be invalid. + + + + + + a #GDate + + + + year to set + + + + + + Moves a date some number of days into the past. +To move by weeks, just move by weeks*7 days. +The date must be valid. + + + + + + a #GDate to decrement + + + + number of days to move + + + + + + Moves a date some number of months into the past. +If the current day of the month doesn't exist in +the destination month, the day of the month +may change. The date must be valid. + + + + + + a #GDate to decrement + + + + number of months to move + + + + + + Moves a date some number of years into the past. +If the current day doesn't exist in the destination +year (i.e. it's February 29 and you move to a non-leap-year) +then the day is changed to February 29. The date +must be valid. + + + + + + a #GDate to decrement + + + + number of years to move + + + + + + Fills in the date-related bits of a struct tm using the @date value. +Initializes the non-date parts with something sane but meaningless. + + + + + + a #GDate to set the struct tm from + + + + struct tm to fill + + + + + + Returns %TRUE if the #GDate represents an existing day. The date must not +contain garbage; it should have been initialized with g_date_clear() +if it wasn't allocated by one of the g_date_new() variants. + + Whether the date is valid + + + + + a #GDate to check + + + + + + Returns the number of days in a month, taking leap +years into account. + + number of days in @month during the @year + + + + + month + + + + year + + + + + + Returns the number of weeks in the year, where weeks +are taken to start on Monday. Will be 52 or 53. The +date must be valid. (Years always have 52 7-day periods, +plus 1 or 2 extra days depending on whether it's a leap +year. This function is basically telling you how many +Mondays are in the year, i.e. there are 53 Mondays if +one of the extra days happens to be a Monday.) + + number of Mondays in the year + + + + + a year + + + + + + Returns the number of weeks in the year, where weeks +are taken to start on Sunday. Will be 52 or 53. The +date must be valid. (Years always have 52 7-day periods, +plus 1 or 2 extra days depending on whether it's a leap +year. This function is basically telling you how many +Sundays are in the year, i.e. there are 53 Sundays if +one of the extra days happens to be a Sunday.) + + the number of weeks in @year + + + + + year to count weeks in + + + + + + Returns %TRUE if the year is a leap year. + +For the purposes of this function, leap year is every year +divisible by 4 unless that year is divisible by 100. If it +is divisible by 100 it would be a leap year only if that year +is also divisible by 400. + + %TRUE if the year is a leap year + + + + + year to check + + + + + + Generates a printed representation of the date, in a +[locale][setlocale]-specific way. +Works just like the platform's C library strftime() function, +but only accepts date-related formats; time-related formats +give undefined results. Date must be valid. Unlike strftime() +(which uses the locale encoding), works on a UTF-8 format +string and stores a UTF-8 result. + +This function does not provide any conversion specifiers in +addition to those implemented by the platform's C library. +For example, don't expect that using g_date_strftime() would +make the \%F provided by the C99 strftime() work on Windows +where the C library only complies to C89. + + number of characters written to the buffer, or 0 the buffer was too small + + + + + destination buffer + + + + buffer size + + + + format string + + + + valid #GDate + + + + + + Returns %TRUE if the day of the month is valid (a day is valid if it's +between 1 and 31 inclusive). + + %TRUE if the day is valid + + + + + day to check + + + + + + Returns %TRUE if the day-month-year triplet forms a valid, existing day +in the range of days #GDate understands (Year 1 or later, no more than +a few thousand years in the future). + + %TRUE if the date is a valid one + + + + + day + + + + month + + + + year + + + + + + Returns %TRUE if the Julian day is valid. Anything greater than zero +is basically a valid Julian, though there is a 32-bit limit. + + %TRUE if the Julian day is valid + + + + + Julian day to check + + + + + + Returns %TRUE if the month value is valid. The 12 #GDateMonth +enumeration values are the only valid months. + + %TRUE if the month is valid + + + + + month + + + + + + Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration +values are the only valid weekdays. + + %TRUE if the weekday is valid + + + + + weekday + + + + + + Returns %TRUE if the year is valid. Any year greater than 0 is valid, +though there is a 16-bit limit to what #GDate will understand. + + %TRUE if the year is valid + + + + + year + + + + + + + This enumeration isn't used in the API, but may be useful if you need +to mark a number as a day, month, or year. + + a day + + + a month + + + a year + + + + Enumeration representing a month; values are #G_DATE_JANUARY, +#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value. + + invalid value + + + January + + + February + + + March + + + April + + + May + + + June + + + July + + + August + + + September + + + October + + + November + + + December + + + + `GDateTime` is an opaque structure whose members +cannot be accessed directly. + + Creates a new #GDateTime corresponding to the given date and time in +the time zone @tz. + +The @year must be between 1 and 9999, @month between 1 and 12 and @day +between 1 and 28, 29, 30 or 31 depending on the month and the year. + +@hour must be between 0 and 23 and @minute must be between 0 and 59. + +@seconds must be at least 0.0 and must be strictly less than 60.0. +It will be rounded down to the nearest microsecond. + +If the given time is not representable in the given time zone (for +example, 02:30 on March 14th 2010 in Toronto, due to daylight savings +time) then the time will be rounded up to the nearest existing time +(in this case, 03:00). If this matters to you then you should verify +the return value for containing the same as the numbers you gave. + +In the case that the given time is ambiguous in the given time zone +(for example, 01:30 on November 7th 2010 in Toronto, due to daylight +savings time) then the time falling within standard (ie: +non-daylight) time is taken. + +It not considered a programmer error for the values to this function +to be out of range, but in the case that they are, the function will +return %NULL. + +You should release the return value by calling g_date_time_unref() +when you are done with it. + + a new #GDateTime, or %NULL + + + + + a #GTimeZone + + + + the year component of the date + + + + the month component of the date + + + + the day component of the date + + + + the hour component of the date + + + + the minute component of the date + + + + the number of seconds past the minute + + + + + + Creates a #GDateTime corresponding to the given #GTimeVal @tv in the +local time zone. + +The time contained in a #GTimeVal is always stored in the form of +seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the +local time offset. + +This call can fail (returning %NULL) if @tv represents a time outside +of the supported range of #GDateTime. + +You should release the return value by calling g_date_time_unref() +when you are done with it. + + a new #GDateTime, or %NULL + + + + + a #GTimeVal + + + + + + Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC. + +The time contained in a #GTimeVal is always stored in the form of +seconds elapsed since 1970-01-01 00:00:00 UTC. + +This call can fail (returning %NULL) if @tv represents a time outside +of the supported range of #GDateTime. + +You should release the return value by calling g_date_time_unref() +when you are done with it. + + a new #GDateTime, or %NULL + + + + + a #GTimeVal + + + + + + Creates a #GDateTime corresponding to the given Unix time @t in the +local time zone. + +Unix time is the number of seconds that have elapsed since 1970-01-01 +00:00:00 UTC, regardless of the local time offset. + +This call can fail (returning %NULL) if @t represents a time outside +of the supported range of #GDateTime. + +You should release the return value by calling g_date_time_unref() +when you are done with it. + + a new #GDateTime, or %NULL + + + + + the Unix time + + + + + + Creates a #GDateTime corresponding to the given Unix time @t in UTC. + +Unix time is the number of seconds that have elapsed since 1970-01-01 +00:00:00 UTC. + +This call can fail (returning %NULL) if @t represents a time outside +of the supported range of #GDateTime. + +You should release the return value by calling g_date_time_unref() +when you are done with it. + + a new #GDateTime, or %NULL + + + + + the Unix time + + + + + + Creates a new #GDateTime corresponding to the given date and time in +the local time zone. + +This call is equivalent to calling g_date_time_new() with the time +zone returned by g_time_zone_new_local(). + + a #GDateTime, or %NULL + + + + + the year component of the date + + + + the month component of the date + + + + the day component of the date + + + + the hour component of the date + + + + the minute component of the date + + + + the number of seconds past the minute + + + + + + Creates a #GDateTime corresponding to this exact instant in the given +time zone @tz. The time is as accurate as the system allows, to a +maximum accuracy of 1 microsecond. + +This function will always succeed unless the system clock is set to +truly insane values (or unless GLib is still being used after the +year 9999). + +You should release the return value by calling g_date_time_unref() +when you are done with it. + + a new #GDateTime, or %NULL + + + + + a #GTimeZone + + + + + + Creates a #GDateTime corresponding to this exact instant in the local +time zone. + +This is equivalent to calling g_date_time_new_now() with the time +zone returned by g_time_zone_new_local(). + + a new #GDateTime, or %NULL + + + + + Creates a #GDateTime corresponding to this exact instant in UTC. + +This is equivalent to calling g_date_time_new_now() with the time +zone returned by g_time_zone_new_utc(). + + a new #GDateTime, or %NULL + + + + + Creates a new #GDateTime corresponding to the given date and time in +UTC. + +This call is equivalent to calling g_date_time_new() with the time +zone returned by g_time_zone_new_utc(). + + a #GDateTime, or %NULL + + + + + the year component of the date + + + + the month component of the date + + + + the day component of the date + + + + the hour component of the date + + + + the minute component of the date + + + + the number of seconds past the minute + + + + + + Creates a copy of @datetime and adds the specified timespan to the copy. + + the newly created #GDateTime which should be freed with + g_date_time_unref(). + + + + + a #GDateTime + + + + a #GTimeSpan + + + + + + Creates a copy of @datetime and adds the specified number of days to the +copy. Add negative values to subtract days. + + the newly created #GDateTime which should be freed with + g_date_time_unref(). + + + + + a #GDateTime + + + + the number of days + + + + + + Creates a new #GDateTime adding the specified values to the current date and +time in @datetime. Add negative values to subtract. + + the newly created #GDateTime that should be freed with + g_date_time_unref(). + + + + + a #GDateTime + + + + the number of years to add + + + + the number of months to add + + + + the number of days to add + + + + the number of hours to add + + + + the number of minutes to add + + + + the number of seconds to add + + + + + + Creates a copy of @datetime and adds the specified number of hours. +Add negative values to subtract hours. + + the newly created #GDateTime which should be freed with + g_date_time_unref(). + + + + + a #GDateTime + + + + the number of hours to add + + + + + + Creates a copy of @datetime adding the specified number of minutes. +Add negative values to subtract minutes. + + the newly created #GDateTime which should be freed with + g_date_time_unref(). + + + + + a #GDateTime + + + + the number of minutes to add + + + + + + Creates a copy of @datetime and adds the specified number of months to the +copy. Add negative values to subtract months. + + the newly created #GDateTime which should be freed with + g_date_time_unref(). + + + + + a #GDateTime + + + + the number of months + + + + + + Creates a copy of @datetime and adds the specified number of seconds. +Add negative values to subtract seconds. + + the newly created #GDateTime which should be freed with + g_date_time_unref(). + + + + + a #GDateTime + + + + the number of seconds to add + + + + + + Creates a copy of @datetime and adds the specified number of weeks to the +copy. Add negative values to subtract weeks. + + the newly created #GDateTime which should be freed with + g_date_time_unref(). + + + + + a #GDateTime + + + + the number of weeks + + + + + + Creates a copy of @datetime and adds the specified number of years to the +copy. Add negative values to subtract years. + + the newly created #GDateTime which should be freed with + g_date_time_unref(). + + + + + a #GDateTime + + + + the number of years + + + + + + Calculates the difference in time between @end and @begin. The +#GTimeSpan that is returned is effectively @end - @begin (ie: +positive if the first parameter is larger). + + the difference between the two #GDateTime, as a time + span expressed in microseconds. + + + + + a #GDateTime + + + + a #GDateTime + + + + + + Creates a newly allocated string representing the requested @format. + +The format strings understood by this function are a subset of the +strftime() format language as specified by C99. The \%D, \%U and \%W +conversions are not supported, nor is the 'E' modifier. The GNU +extensions \%k, \%l, \%s and \%P are supported, however, as are the +'0', '_' and '-' modifiers. + +In contrast to strftime(), this function always produces a UTF-8 +string, regardless of the current locale. Note that the rendering of +many formats is locale-dependent and may not match the strftime() +output exactly. + +The following format specifiers are supported: + +- \%a: the abbreviated weekday name according to the current locale +- \%A: the full weekday name according to the current locale +- \%b: the abbreviated month name according to the current locale +- \%B: the full month name according to the current locale +- \%c: the preferred date and time representation for the current locale +- \%C: the century number (year/100) as a 2-digit integer (00-99) +- \%d: the day of the month as a decimal number (range 01 to 31) +- \%e: the day of the month as a decimal number (range 1 to 31) +- \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format) +- \%g: the last two digits of the ISO 8601 week-based year as a + decimal number (00-99). This works well with \%V and \%u. +- \%G: the ISO 8601 week-based year as a decimal number. This works + well with \%V and \%u. +- \%h: equivalent to \%b +- \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23) +- \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12) +- \%j: the day of the year as a decimal number (range 001 to 366) +- \%k: the hour (24-hour clock) as a decimal number (range 0 to 23); + single digits are preceded by a blank +- \%l: the hour (12-hour clock) as a decimal number (range 1 to 12); + single digits are preceded by a blank +- \%m: the month as a decimal number (range 01 to 12) +- \%M: the minute as a decimal number (range 00 to 59) +- \%p: either "AM" or "PM" according to the given time value, or the + corresponding strings for the current locale. Noon is treated as + "PM" and midnight as "AM". +- \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for + the current locale +- \%r: the time in a.m. or p.m. notation +- \%R: the time in 24-hour notation (\%H:\%M) +- \%s: the number of seconds since the Epoch, that is, since 1970-01-01 + 00:00:00 UTC +- \%S: the second as a decimal number (range 00 to 60) +- \%t: a tab character +- \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S) +- \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7, + Monday being 1. This works well with \%G and \%V. +- \%V: the ISO 8601 standard week number of the current year as a decimal + number, range 01 to 53, where week 1 is the first week that has at + least 4 days in the new year. See g_date_time_get_week_of_year(). + This works well with \%G and \%u. +- \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0. + This is not the ISO 8601 standard format -- use \%u instead. +- \%x: the preferred date representation for the current locale without + the time +- \%X: the preferred time representation for the current locale without + the date +- \%y: the year as a decimal number without the century +- \%Y: the year as a decimal number including the century +- \%z: the time zone as an offset from UTC (+hhmm) +- \%:z: the time zone as an offset from UTC (+hh:mm). + This is a gnulib strftime() extension. Since: 2.38 +- \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a + gnulib strftime() extension. Since: 2.38 +- \%:::z: the time zone as an offset from UTC, with : to necessary + precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38 +- \%Z: the time zone or name or abbreviation +- \%\%: a literal \% character + +Some conversion specifications can be modified by preceding the +conversion specifier by one or more modifier characters. The +following modifiers are supported for many of the numeric +conversions: + +- O: Use alternative numeric symbols, if the current locale supports those. +- _: Pad a numeric result with spaces. This overrides the default padding + for the specifier. +- -: Do not pad a numeric result. This overrides the default padding + for the specifier. +- 0: Pad a numeric result with zeros. This overrides the default padding + for the specifier. + + a newly allocated string formatted to the requested format + or %NULL in the case that there was an error. The string + should be freed with g_free(). + + + + + A #GDateTime + + + + a valid UTF-8 string, containing the format for the + #GDateTime + + + + + + Retrieves the day of the month represented by @datetime in the gregorian +calendar. + + the day of the month + + + + + a #GDateTime + + + + + + Retrieves the ISO 8601 day of the week on which @datetime falls (1 is +Monday, 2 is Tuesday... 7 is Sunday). + + the day of the week + + + + + a #GDateTime + + + + + + Retrieves the day of the year represented by @datetime in the Gregorian +calendar. + + the day of the year + + + + + a #GDateTime + + + + + + Retrieves the hour of the day represented by @datetime + + the hour of the day + + + + + a #GDateTime + + + + + + Retrieves the microsecond of the date represented by @datetime + + the microsecond of the second + + + + + a #GDateTime + + + + + + Retrieves the minute of the hour represented by @datetime + + the minute of the hour + + + + + a #GDateTime + + + + + + Retrieves the month of the year represented by @datetime in the Gregorian +calendar. + + the month represented by @datetime + + + + + a #GDateTime + + + + + + Retrieves the second of the minute represented by @datetime + + the second represented by @datetime + + + + + a #GDateTime + + + + + + Retrieves the number of seconds since the start of the last minute, +including the fractional part. + + the number of seconds + + + + + a #GDateTime + + + + + + Determines the time zone abbreviation to be used at the time and in +the time zone of @datetime. + +For example, in Toronto this is currently "EST" during the winter +months and "EDT" during the summer months when daylight savings +time is in effect. + + the time zone abbreviation. The returned + string is owned by the #GDateTime and it should not be + modified or freed + + + + + a #GDateTime + + + + + + Determines the offset to UTC in effect at the time and in the time +zone of @datetime. + +The offset is the number of microseconds that you add to UTC time to +arrive at local time for the time zone (ie: negative numbers for time +zones west of GMT, positive numbers for east). + +If @datetime represents UTC time, then the offset is always zero. + + the number of microseconds that should be added to UTC to + get the local time + + + + + a #GDateTime + + + + + + Returns the ISO 8601 week-numbering year in which the week containing +@datetime falls. + +This function, taken together with g_date_time_get_week_of_year() and +g_date_time_get_day_of_week() can be used to determine the full ISO +week date on which @datetime falls. + +This is usually equal to the normal Gregorian year (as returned by +g_date_time_get_year()), except as detailed below: + +For Thursday, the week-numbering year is always equal to the usual +calendar year. For other days, the number is such that every day +within a complete week (Monday to Sunday) is contained within the +same week-numbering year. + +For Monday, Tuesday and Wednesday occurring near the end of the year, +this may mean that the week-numbering year is one greater than the +calendar year (so that these days have the same week-numbering year +as the Thursday occurring early in the next year). + +For Friday, Saturday and Sunday occurring near the start of the year, +this may mean that the week-numbering year is one less than the +calendar year (so that these days have the same week-numbering year +as the Thursday occurring late in the previous year). + +An equivalent description is that the week-numbering year is equal to +the calendar year containing the majority of the days in the current +week (Monday to Sunday). + +Note that January 1 0001 in the proleptic Gregorian calendar is a +Monday, so this function never returns 0. + + the ISO 8601 week-numbering year for @datetime + + + + + a #GDateTime + + + + + + Returns the ISO 8601 week number for the week containing @datetime. +The ISO 8601 week number is the same for every day of the week (from +Moday through Sunday). That can produce some unusual results +(described below). + +The first week of the year is week 1. This is the week that contains +the first Thursday of the year. Equivalently, this is the first week +that has more than 4 of its days falling within the calendar year. + +The value 0 is never returned by this function. Days contained +within a year but occurring before the first ISO 8601 week of that +year are considered as being contained in the last week of the +previous year. Similarly, the final days of a calendar year may be +considered as being part of the first ISO 8601 week of the next year +if 4 or more days of that week are contained within the new year. + + the ISO 8601 week number for @datetime. + + + + + a #GDateTime + + + + + + Retrieves the year represented by @datetime in the Gregorian calendar. + + the year represented by @datetime + + + + + A #GDateTime + + + + + + Retrieves the Gregorian day, month, and year of a given #GDateTime. + + + + + + a #GDateTime. + + + + the return location for the gregorian year, or %NULL. + + + + the return location for the month of the year, or %NULL. + + + + the return location for the day of the month, or %NULL. + + + + + + Determines if daylight savings time is in effect at the time and in +the time zone of @datetime. + + %TRUE if daylight savings time is in effect + + + + + a #GDateTime + + + + + + Atomically increments the reference count of @datetime by one. + + the #GDateTime with the reference count increased + + + + + a #GDateTime + + + + + + Creates a new #GDateTime corresponding to the same instant in time as +@datetime, but in the local time zone. + +This call is equivalent to calling g_date_time_to_timezone() with the +time zone returned by g_time_zone_new_local(). + + the newly created #GDateTime + + + + + a #GDateTime + + + + + + Stores the instant in time that @datetime represents into @tv. + +The time contained in a #GTimeVal is always stored in the form of +seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time +zone associated with @datetime. + +On systems where 'long' is 32bit (ie: all 32bit systems and all +Windows systems), a #GTimeVal is incapable of storing the entire +range of values that #GDateTime is capable of expressing. On those +systems, this function returns %FALSE to indicate that the time is +out of range. + +On systems where 'long' is 64bit, this function never fails. + + %TRUE if successful, else %FALSE + + + + + a #GDateTime + + + + a #GTimeVal to modify + + + + + + Create a new #GDateTime corresponding to the same instant in time as +@datetime, but in the time zone @tz. + +This call can fail in the case that the time goes out of bounds. For +example, converting 0001-01-01 00:00:00 UTC to a time zone west of +Greenwich will fail (due to the year 0 being out of range). + +You should release the return value by calling g_date_time_unref() +when you are done with it. + + a new #GDateTime, or %NULL + + + + + a #GDateTime + + + + the new #GTimeZone + + + + + + Gives the Unix time corresponding to @datetime, rounding down to the +nearest second. + +Unix time is the number of seconds that have elapsed since 1970-01-01 +00:00:00 UTC, regardless of the time zone associated with @datetime. + + the Unix time corresponding to @datetime + + + + + a #GDateTime + + + + + + Creates a new #GDateTime corresponding to the same instant in time as +@datetime, but in UTC. + +This call is equivalent to calling g_date_time_to_timezone() with the +time zone returned by g_time_zone_new_utc(). + + the newly created #GDateTime + + + + + a #GDateTime + + + + + + Atomically decrements the reference count of @datetime by one. + +When the reference count reaches zero, the resources allocated by +@datetime are freed + + + + + + a #GDateTime + + + + + + A comparison function for #GDateTimes that is suitable +as a #GCompareFunc. Both #GDateTimes must be non-%NULL. + + -1, 0 or 1 if @dt1 is less than, equal to or greater + than @dt2. + + + + + first #GDateTime to compare + + + + second #GDateTime to compare + + + + + + Checks to see if @dt1 and @dt2 are equal. + +Equal here means that they represent the same moment after converting +them to the same time zone. + + %TRUE if @dt1 and @dt2 are equal + + + + + a #GDateTime + + + + a #GDateTime + + + + + + Hashes @datetime into a #guint, suitable for use within #GHashTable. + + a #guint containing the hash + + + + + a #GDateTime + + + + + + + Enumeration representing a day of the week; #G_DATE_MONDAY, +#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday. + + invalid value + + + Monday + + + Tuesday + + + Wednesday + + + Thursday + + + Friday + + + Saturday + + + Sunday + + + + Associates a string with a bit flag. +Used in g_parse_debug_string(). + + the string + + + + the flag + + + + + Specifies the type of function which is called when a data element +is destroyed. It is passed the pointer to the data element and +should free any memory and resources allocated for it. + + + + + + the data element. + + + + + + An opaque structure representing an opened directory. + + Closes the directory and deallocates all related resources. + + + + + + a #GDir* created by g_dir_open() + + + + + + Retrieves the name of another entry in the directory, or %NULL. +The order of entries returned from this function is not defined, +and may vary by file system or other operating-system dependent +factors. + +%NULL may also be returned in case of errors. On Unix, you can +check `errno` to find out if %NULL was returned because of an error. + +On Unix, the '.' and '..' entries are omitted, and the returned +name is in the on-disk encoding. + +On Windows, as is true of all GLib functions which operate on +filenames, the returned name is in UTF-8. + + The entry's name or %NULL if there are no + more entries. The return value is owned by GLib and + must not be modified or freed. + + + + + a #GDir* created by g_dir_open() + + + + + + Resets the given directory. The next call to g_dir_read_name() +will return the first entry again. + + + + + + a #GDir* created by g_dir_open() + + + + + + Creates a subdirectory in the preferred directory for temporary +files (as returned by g_get_tmp_dir()). + +@tmpl should be a string in the GLib file name encoding containing +a sequence of six 'X' characters, as the parameter to g_mkstemp(). +However, unlike these functions, the template should only be a +basename, no directory components are allowed. If template is +%NULL, a default template is used. + +Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not +modified, and might thus be a read-only literal string. + + The actual name used. This string + should be freed with g_free() when not needed any longer and is + is in the GLib file name encoding. In case of errors, %NULL is + returned and @error will be set. + + + + + Template for directory name, + as in g_mkdtemp(), basename only, or %NULL for a default template + + + + + + Opens a directory for reading. The names of the files in the +directory can then be retrieved using g_dir_read_name(). Note +that the ordering is not defined. + + a newly allocated #GDir on success, %NULL on failure. + If non-%NULL, you must free the result with g_dir_close() + when you are finished with it. + + + + + the path to the directory you are interested in. On Unix + in the on-disk encoding. On Windows in UTF-8 + + + + Currently must be set to 0. Reserved for future use. + + + + + + + The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, +mantissa and exponent of IEEE floats and doubles. These unions are defined +as appropriate for a given platform. IEEE floats and doubles are supported +(used for storage) by at least Intel, PPC and Sparc. + + the double value + + + + + + + + + + + + + + + + + + + The type of functions that are used to 'duplicate' an object. +What this means depends on the context, it could just be +incrementing the reference count, if @data is a ref-counted +object. + + a duplicate of data + + + + + the data to duplicate + + + + user data that was specified in g_datalist_id_dup_data() + + + + + + The base of natural logarithms. + + + + Specifies the type of a function used to test two values for +equality. The function should return %TRUE if both values are equal +and %FALSE otherwise. + + %TRUE if @a = @b; %FALSE otherwise + + + + + a value + + + + a value to compare with + + + + + + The `GError` structure contains information about +an error that has occurred. + + error domain, e.g. #G_FILE_ERROR + + + + error code, e.g. %G_FILE_ERROR_NOENT + + + + human-readable informative error message + + + + Creates a new #GError with the given @domain and @code, +and a message formatted with @format. + + a new #GError + + + + + error domain + + + + error code + + + + printf()-style format for error message + + + + parameters for message format + + + + + + Creates a new #GError; unlike g_error_new(), @message is +not a printf()-style format string. Use this function if +@message contains text you don't have control over, +that could include printf() escape sequences. + + a new #GError + + + + + error domain + + + + error code + + + + error message + + + + + + Creates a new #GError with the given @domain and @code, +and a message formatted with @format. + + a new #GError + + + + + error domain + + + + error code + + + + printf()-style format for error message + + + + #va_list of parameters for the message format + + + + + + Makes a copy of @error. + + a new #GError + + + + + a #GError + + + + + + Frees a #GError and associated resources. + + + + + + a #GError + + + + + + Returns %TRUE if @error matches @domain and @code, %FALSE +otherwise. In particular, when @error is %NULL, %FALSE will +be returned. + +If @domain contains a `FAILED` (or otherwise generic) error code, +you should generally not check for it explicitly, but should +instead treat any not-explicitly-recognized error code as being +equivalent to the `FAILED` code. This way, if the domain is +extended in the future to provide a more specific error code for +a certain case, your code will still work. + + whether @error has @domain and @code + + + + + a #GError + + + + an error domain + + + + an error code + + + + + + + The possible errors, used in the @v_error field +of #GTokenValue, when the token is a %G_TOKEN_ERROR. + + unknown error + + + unexpected end of file + + + unterminated string constant + + + unterminated comment + + + non-digit character in a number + + + digit beyond radix in a number + + + non-decimal floating point number + + + malformed floating point number + + + + Values corresponding to @errno codes returned from file operations +on UNIX. Unlike @errno codes, GFileError values are available on +all systems, even Windows. The exact meaning of each code depends +on what sort of file operation you were performing; the UNIX +documentation gives more details. The following error code descriptions +come from the GNU C Library manual, and are under the copyright +of that manual. + +It's not very portable to make detailed assumptions about exactly +which errors will be returned from a given operation. Some errors +don't occur on some systems, etc., sometimes there are subtle +differences in when a system will report a given error, etc. + + Operation not permitted; only the owner of + the file (or other resource) or processes with special privileges + can perform the operation. + + + File is a directory; you cannot open a directory + for writing, or create or remove hard links to it. + + + Permission denied; the file permissions do not + allow the attempted operation. + + + Filename too long. + + + No such file or directory. This is a "file + doesn't exist" error for ordinary files that are referenced in + contexts where they are expected to already exist. + + + A file that isn't a directory was specified when + a directory is required. + + + No such device or address. The system tried to + use the device represented by a file you specified, and it + couldn't find the device. This can mean that the device file was + installed incorrectly, or that the physical device is missing or + not correctly attached to the computer. + + + The underlying file system of the specified file + does not support memory mapping. + + + The directory containing the new link can't be + modified because it's on a read-only file system. + + + Text file busy. + + + You passed in a pointer to bad memory. + (GLib won't reliably return this, don't pass in pointers to bad + memory.) + + + Too many levels of symbolic links were encountered + in looking up a file name. This often indicates a cycle of symbolic + links. + + + No space left on device; write operation on a + file failed because the disk is full. + + + No memory available. The system cannot allocate + more virtual memory because its capacity is full. + + + The current process has too many files open and + can't open any more. Duplicate descriptors do count toward this + limit. + + + There are too many distinct file openings in the + entire system. + + + Bad file descriptor; for example, I/O on a + descriptor that has been closed or reading from a descriptor open + only for writing (or vice versa). + + + Invalid argument. This is used to indicate + various kinds of problems with passing the wrong argument to a + library function. + + + Broken pipe; there is no process reading from the + other end of a pipe. Every library function that returns this + error code also generates a 'SIGPIPE' signal; this signal + terminates the program if not handled or blocked. Thus, your + program will never actually see this code unless it has handled + or blocked 'SIGPIPE'. + + + Resource temporarily unavailable; the call might + work if you try again later. + + + Interrupted function call; an asynchronous signal + occurred and prevented completion of the call. When this + happens, you should try the call again. + + + Input/output error; usually used for physical read + or write errors. i.e. the disk or other physical device hardware + is returning errors. + + + Operation not permitted; only the owner of the + file (or other resource) or processes with special privileges can + perform the operation. + + + Function not implemented; this indicates that + the system is missing some functionality. + + + Does not correspond to a UNIX error code; this + is the standard "failed for unspecified reason" error code present + in all #GError error code enumerations. Returned if no specific + code applies. + + + + A test to perform on a file using g_file_test(). + + %TRUE if the file is a regular file + (not a directory). Note that this test will also return %TRUE + if the tested file is a symlink to a regular file. + + + %TRUE if the file is a symlink. + + + %TRUE if the file is a directory. + + + %TRUE if the file is executable. + + + %TRUE if the file exists. It may or may not + be a regular file. + + + + The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, +mantissa and exponent of IEEE floats and doubles. These unions are defined +as appropriate for a given platform. IEEE floats and doubles are supported +(used for storage) by at least Intel, PPC and Sparc. + + the double value + + + + + + + + + + + + + + + + Flags to modify the format of the string returned by g_format_size_full(). + + behave the same as g_format_size() + + + include the exact number of bytes as part + of the returned string. For example, "45.6 kB (45,612 bytes)". + + + use IEC (base 1024) units with "KiB"-style + suffixes. IEC units should only be used for reporting things with + a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. + Network and storage sizes should be reported in the normal SI units. + + + + Declares a type of function which takes an arbitrary +data pointer argument and has no return value. It is +not currently used in GLib or GTK+. + + + + + + a data pointer + + + + + + Specifies the type of functions passed to g_list_foreach() and +g_slist_foreach(). + + + + + + the element's data + + + + user data passed to g_list_foreach() or g_slist_foreach() + + + + + + This is the platform dependent conversion specifier for scanning and +printing values of type #gint16. It is a string literal, but doesn't +include the percent-sign, such that you can add precision and length +modifiers between percent-sign and conversion specifier. + +|[<!-- language="C" --> +gint16 in; +gint32 out; +sscanf ("42", "%" G_GINT16_FORMAT, &in) +out = in * 1000; +g_print ("%" G_GINT32_FORMAT, out); +]| + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gint16 or #guint16. It +is a string literal, but doesn't include the percent-sign, such +that you can add precision and length modifiers between percent-sign +and conversion specifier and append a conversion specifier. + +The following example prints "0x7b"; +|[<!-- language="C" --> +gint16 value = 123; +g_print ("%#" G_GINT16_MODIFIER "x", value); +]| + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #gint32. See also #G_GINT16_FORMAT. + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gint32 or #guint32. It +is a string literal. See also #G_GINT16_MODIFIER. + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #gint64. See also #G_GINT16_FORMAT. + +Some platforms do not support scanning and printing 64-bit integers, +even though the types are supported. On such platforms %G_GINT64_FORMAT +is not defined. Note that scanf() may not support 64-bit integers, even +if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() +is not recommended for parsing anyway; consider using g_ascii_strtoull() +instead. + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gint64 or #guint64. +It is a string literal. + +Some platforms do not support printing 64-bit integers, even +though the types are supported. On such platforms %G_GINT64_MODIFIER +is not defined. + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #gintptr. + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gintptr or #guintptr. +It is a string literal. + + + + Expands to "" on all modern compilers, and to __FUNCTION__ on gcc +version 2.x. Don't use it. + Use G_STRFUNC() instead + + + + Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__ +on gcc version 2.x. Don't use it. + Use G_STRFUNC() instead + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #gsize. See also #G_GINT16_FORMAT. + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gsize. It +is a string literal. + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #gssize. See also #G_GINT16_FORMAT. + + + + The platform dependent length modifier for conversion specifiers +for scanning and printing values of type #gssize. It +is a string literal. + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #guint16. See also #G_GINT16_FORMAT + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #guint32. See also #G_GINT16_FORMAT. + + + + This is the platform dependent conversion specifier for scanning +and printing values of type #guint64. See also #G_GINT16_FORMAT. + +Some platforms do not support scanning and printing 64-bit integers, +even though the types are supported. On such platforms %G_GUINT64_FORMAT +is not defined. Note that scanf() may not support 64-bit integers, even +if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() +is not recommended for parsing anyway; consider using g_ascii_strtoull() +instead. + + + + This is the platform dependent conversion specifier +for scanning and printing values of type #guintptr. + + + + + + + + + + Defined to 1 if gcc-style visibility handling is supported. + + + + + + + + + + Specifies the type of the function passed to g_hash_table_foreach(). +It is called with each key/value pair, together with the @user_data +parameter which is passed to g_hash_table_foreach(). + + + + + + a key + + + + the value corresponding to the key + + + + user data passed to g_hash_table_foreach() + + + + + + The position of the first bit which is not reserved for internal +use be the #GHook implementation, i.e. +`1 << G_HOOK_FLAG_USER_SHIFT` is the first +bit which can be used for application-defined flags. + + + + Specifies the type of the function passed to +g_hash_table_foreach_remove(). It is called with each key/value +pair, together with the @user_data parameter passed to +g_hash_table_foreach_remove(). It should return %TRUE if the +key/value pair should be removed from the #GHashTable. + + %TRUE if the key/value pair should be removed from the + #GHashTable + + + + + a key + + + + the value associated with the key + + + + user data passed to g_hash_table_remove() + + + + + + Specifies the type of the hash function which is passed to +g_hash_table_new() when a #GHashTable is created. + +The function is passed a key and should return a #guint hash value. +The functions g_direct_hash(), g_int_hash() and g_str_hash() provide +hash functions which can be used when the key is a #gpointer, #gint*, +and #gchar* respectively. + +g_direct_hash() is also the appropriate hash function for keys +of the form `GINT_TO_POINTER (n)` (or similar macros). + +<!-- FIXME: Need more here. --> A good hash functions should produce +hash values that are evenly distributed over a fairly large range. +The modulus is taken with the hash table size (a prime number) to +find the 'bucket' to place each key into. The function should also +be very fast, since it is called for each key lookup. + +Note that the hash functions provided by GLib have these qualities, +but are not particularly robust against manufactured keys that +cause hash collisions. Therefore, you should consider choosing +a more secure hash function when using a GHashTable with keys +that originate in untrusted data (such as HTTP requests). +Using g_str_hash() in that situation might make your application +vulerable to +[Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/). + +The key to choosing a good hash is unpredictability. Even +cryptographic hashes are very easy to find collisions for when the +remainder is taken modulo a somewhat predictable prime number. There +must be an element of randomness that an attacker is unable to guess. + + the hash value corresponding to the key + + + + + a key + + + + + + The #GHashTable struct is an opaque data structure to represent a +[Hash Table][glib-Hash-Tables]. It should only be accessed via the +following functions. + + This is a convenience function for using a #GHashTable as a set. It +is equivalent to calling g_hash_table_replace() with @key as both the +key and the value. + +When a hash table only ever contains keys that have themselves as the +corresponding value it is able to be stored more efficiently. See +the discussion in the section description. + + %TRUE if the key did not exist yet + + + + + a #GHashTable + + + + + + + a key to insert + + + + + + Checks if @key is in @hash_table. + + %TRUE if @key is in @hash_table, %FALSE otherwise. + + + + + a #GHashTable + + + + + + + a key to check + + + + + + Destroys all keys and values in the #GHashTable and decrements its +reference count by 1. If keys and/or values are dynamically allocated, +you should either free them first or create the #GHashTable with destroy +notifiers using g_hash_table_new_full(). In the latter case the destroy +functions you supplied will be called on all keys and values during the +destruction phase. + + + + + + a #GHashTable + + + + + + + + + Calls the given function for key/value pairs in the #GHashTable +until @predicate returns %TRUE. The function is passed the key +and value of each pair, and the given @user_data parameter. The +hash table may not be modified while iterating over it (you can't +add/remove items). + +Note, that hash tables are really only optimized for forward +lookups, i.e. g_hash_table_lookup(). So code that frequently issues +g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of +once per every entry in a hash table) should probably be reworked +to use additional or different data structures for reverse lookups +(keep in mind that an O(n) find/foreach operation issued for all n +values in a hash table ends up needing O(n*n) operations). + + The value of the first key/value pair is returned, + for which @predicate evaluates to %TRUE. If no pair with the + requested property is found, %NULL is returned. + + + + + a #GHashTable + + + + + + + function to test the key/value pairs for a certain property + + + + user data to pass to the function + + + + + + Calls the given function for each of the key/value pairs in the +#GHashTable. The function is passed the key and value of each +pair, and the given @user_data parameter. The hash table may not +be modified while iterating over it (you can't add/remove +items). To remove all items matching a predicate, use +g_hash_table_foreach_remove(). + +See g_hash_table_find() for performance caveats for linear +order searches in contrast to g_hash_table_lookup(). + + + + + + a #GHashTable + + + + + + + the function to call for each key/value pair + + + + user data to pass to the function + + + + + + Calls the given function for each key/value pair in the +#GHashTable. If the function returns %TRUE, then the key/value +pair is removed from the #GHashTable. If you supplied key or +value destroy functions when creating the #GHashTable, they are +used to free the memory allocated for the removed keys and values. + +See #GHashTableIter for an alternative way to loop over the +key/value pairs in the hash table. + + the number of key/value pairs removed + + + + + a #GHashTable + + + + + + + the function to call for each key/value pair + + + + user data to pass to the function + + + + + + Calls the given function for each key/value pair in the +#GHashTable. If the function returns %TRUE, then the key/value +pair is removed from the #GHashTable, but no key or value +destroy functions are called. + +See #GHashTableIter for an alternative way to loop over the +key/value pairs in the hash table. + + the number of key/value pairs removed. + + + + + a #GHashTable + + + + + + + the function to call for each key/value pair + + + + user data to pass to the function + + + + + + Retrieves every key inside @hash_table. The returned data is valid +until changes to the hash release those keys. + +This iterates over every entry in the hash table to build its return value. +To iterate over the entries in a #GHashTable more efficiently, use a +#GHashTableIter. + + a #GList containing all the keys + inside the hash table. The content of the list is owned by the + hash table and should not be modified or freed. Use g_list_free() + when done using the list. + + + + + + + a #GHashTable + + + + + + + + + Retrieves every key inside @hash_table, as an array. + +The returned array is %NULL-terminated but may contain %NULL as a +key. Use @length to determine the true length if it's possible that +%NULL was used as the value for a key. + +Note: in the common case of a string-keyed #GHashTable, the return +value of this function can be conveniently cast to (const gchar **). + +This iterates over every entry in the hash table to build its return value. +To iterate over the entries in a #GHashTable more efficiently, use a +#GHashTableIter. + +You should always free the return result with g_free(). In the +above-mentioned case of a string-keyed hash table, it may be +appropriate to use g_strfreev() if you call g_hash_table_steal_all() +first to transfer ownership of the keys. + + a + %NULL-terminated array containing each key from the table. + + + + + + + a #GHashTable + + + + + + + the length of the returned array + + + + + + Retrieves every value inside @hash_table. The returned data +is valid until @hash_table is modified. + +This iterates over every entry in the hash table to build its return value. +To iterate over the entries in a #GHashTable more efficiently, use a +#GHashTableIter. + + a #GList containing all the values + inside the hash table. The content of the list is owned by the + hash table and should not be modified or freed. Use g_list_free() + when done using the list. + + + + + + + a #GHashTable + + + + + + + + + Inserts a new key and value into a #GHashTable. + +If the key already exists in the #GHashTable its current +value is replaced with the new value. If you supplied a +@value_destroy_func when creating the #GHashTable, the old +value is freed using that function. If you supplied a +@key_destroy_func when creating the #GHashTable, the passed +key is freed using that function. + + %TRUE if the key did not exist yet + + + + + a #GHashTable + + + + + + + a key to insert + + + + the value to associate with the key + + + + + + Looks up a key in a #GHashTable. Note that this function cannot +distinguish between a key that is not present and one which is present +and has the value %NULL. If you need this distinction, use +g_hash_table_lookup_extended(). + + the associated value, or %NULL if the key is not found + + + + + a #GHashTable + + + + + + + the key to look up + + + + + + Looks up a key in the #GHashTable, returning the original key and the +associated value and a #gboolean which is %TRUE if the key was found. This +is useful if you need to free the memory allocated for the original key, +for example before calling g_hash_table_remove(). + +You can actually pass %NULL for @lookup_key to test +whether the %NULL key exists, provided the hash and equal functions +of @hash_table are %NULL-safe. + + %TRUE if the key was found in the #GHashTable + + + + + a #GHashTable + + + + + + + the key to look up + + + + return location for the original key + + + + return location for the value associated +with the key + + + + + + Creates a new #GHashTable with a reference count of 1. + +Hash values returned by @hash_func are used to determine where keys +are stored within the #GHashTable data structure. The g_direct_hash(), +g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash() +functions are provided for some common types of keys. +If @hash_func is %NULL, g_direct_hash() is used. + +@key_equal_func is used when looking up keys in the #GHashTable. +The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal() +and g_str_equal() functions are provided for the most common types +of keys. If @key_equal_func is %NULL, keys are compared directly in +a similar fashion to g_direct_equal(), but without the overhead of +a function call. + + a new #GHashTable + + + + + + + + a function to create a hash value from a key + + + + a function to check two keys for equality + + + + + + Creates a new #GHashTable like g_hash_table_new() with a reference +count of 1 and allows to specify functions to free the memory +allocated for the key and value that get called when removing the +entry from the #GHashTable. + +Since version 2.42 it is permissible for destroy notify functions to +recursively remove further items from the hash table. This is only +permissible if the application still holds a reference to the hash table. +This means that you may need to ensure that the hash table is empty by +calling g_hash_table_remove_all before releasing the last reference using +g_hash_table_unref(). + + a new #GHashTable + + + + + + + + a function to create a hash value from a key + + + + a function to check two keys for equality + + + + a function to free the memory allocated for the key + used when removing the entry from the #GHashTable, or %NULL + if you don't want to supply such a function. + + + + a function to free the memory allocated for the + value used when removing the entry from the #GHashTable, or %NULL + if you don't want to supply such a function. + + + + + + Atomically increments the reference count of @hash_table by one. +This function is MT-safe and may be called from any thread. + + the passed in #GHashTable + + + + + + + + a valid #GHashTable + + + + + + + + + Removes a key and its associated value from a #GHashTable. + +If the #GHashTable was created using g_hash_table_new_full(), the +key and value are freed using the supplied destroy functions, otherwise +you have to make sure that any dynamically allocated values are freed +yourself. + + %TRUE if the key was found and removed from the #GHashTable + + + + + a #GHashTable + + + + + + + the key to remove + + + + + + Removes all keys and their associated values from a #GHashTable. + +If the #GHashTable was created using g_hash_table_new_full(), +the keys and values are freed using the supplied destroy functions, +otherwise you have to make sure that any dynamically allocated +values are freed yourself. + + + + + + a #GHashTable + + + + + + + + + Inserts a new key and value into a #GHashTable similar to +g_hash_table_insert(). The difference is that if the key +already exists in the #GHashTable, it gets replaced by the +new key. If you supplied a @value_destroy_func when creating +the #GHashTable, the old value is freed using that function. +If you supplied a @key_destroy_func when creating the +#GHashTable, the old key is freed using that function. + + %TRUE if the key did not exist yet + + + + + a #GHashTable + + + + + + + a key to insert + + + + the value to associate with the key + + + + + + Returns the number of elements contained in the #GHashTable. + + the number of key/value pairs in the #GHashTable. + + + + + a #GHashTable + + + + + + + + + Removes a key and its associated value from a #GHashTable without +calling the key and value destroy functions. + + %TRUE if the key was found and removed from the #GHashTable + + + + + a #GHashTable + + + + + + + the key to remove + + + + + + Removes all keys and their associated values from a #GHashTable +without calling the key and value destroy functions. + + + + + + a #GHashTable + + + + + + + + + Atomically decrements the reference count of @hash_table by one. +If the reference count drops to 0, all keys and values will be +destroyed, and all memory allocated by the hash table is released. +This function is MT-safe and may be called from any thread. + + + + + + a valid #GHashTable + + + + + + + + + + A GHashTableIter structure represents an iterator that can be used +to iterate over the elements of a #GHashTable. GHashTableIter +structures are typically allocated on the stack and then initialized +with g_hash_table_iter_init(). + + + + + + + + + + + + + + + + + + + + Returns the #GHashTable associated with @iter. + + the #GHashTable associated with @iter. + + + + + + + + an initialized #GHashTableIter + + + + + + Initializes a key/value pair iterator and associates it with +@hash_table. Modifying the hash table after calling this function +invalidates the returned iterator. +|[<!-- language="C" --> +GHashTableIter iter; +gpointer key, value; + +g_hash_table_iter_init (&iter, hash_table); +while (g_hash_table_iter_next (&iter, &key, &value)) + { + // do something with key and value + } +]| + + + + + + an uninitialized #GHashTableIter + + + + a #GHashTable + + + + + + + + + Advances @iter and retrieves the key and/or value that are now +pointed to as a result of this advancement. If %FALSE is returned, +@key and @value are not set, and the iterator becomes invalid. + + %FALSE if the end of the #GHashTable has been reached. + + + + + an initialized #GHashTableIter + + + + a location to store the key + + + + a location to store the value + + + + + + Removes the key/value pair currently pointed to by the iterator +from its associated #GHashTable. Can only be called after +g_hash_table_iter_next() returned %TRUE, and cannot be called +more than once for the same key/value pair. + +If the #GHashTable was created using g_hash_table_new_full(), +the key and value are freed using the supplied destroy functions, +otherwise you have to make sure that any dynamically allocated +values are freed yourself. + +It is safe to continue iterating the #GHashTable afterward: +|[<!-- language="C" --> +while (g_hash_table_iter_next (&iter, &key, &value)) + { + if (condition) + g_hash_table_iter_remove (&iter); + } +]| + + + + + + an initialized #GHashTableIter + + + + + + Replaces the value currently pointed to by the iterator +from its associated #GHashTable. Can only be called after +g_hash_table_iter_next() returned %TRUE. + +If you supplied a @value_destroy_func when creating the +#GHashTable, the old value is freed using that function. + + + + + + an initialized #GHashTableIter + + + + the value to replace with + + + + + + Removes the key/value pair currently pointed to by the +iterator from its associated #GHashTable, without calling +the key and value destroy functions. Can only be called +after g_hash_table_iter_next() returned %TRUE, and cannot +be called more than once for the same key/value pair. + + + + + + an initialized #GHashTableIter + + + + + + + An opaque structure representing a HMAC operation. +To create a new GHmac, use g_hmac_new(). To free +a GHmac, use g_hmac_unref(). + + Copies a #GHmac. If @hmac has been closed, by calling +g_hmac_get_string() or g_hmac_get_digest(), the copied +HMAC will be closed as well. + + the copy of the passed #GHmac. Use g_hmac_unref() + when finished using it. + + + + + the #GHmac to copy + + + + + + Gets the digest from @checksum as a raw binary array and places it +into @buffer. The size of the digest depends on the type of checksum. + +Once this function has been called, the #GHmac is closed and can +no longer be updated with g_checksum_update(). + + + + + + a #GHmac + + + + output buffer + + + + an inout parameter. The caller initializes it to the + size of @buffer. After the call it contains the length of the digest + + + + + + Gets the HMAC as an hexadecimal string. + +Once this function has been called the #GHmac can no longer be +updated with g_hmac_update(). + +The hexadecimal characters will be lower case. + + the hexadecimal representation of the HMAC. The + returned string is owned by the HMAC and should not be modified + or freed. + + + + + a #GHmac + + + + + + Atomically increments the reference count of @hmac by one. + +This function is MT-safe and may be called from any thread. + + the passed in #GHmac. + + + + + a valid #GHmac + + + + + + Atomically decrements the reference count of @hmac by one. + +If the reference count drops to 0, all keys and values will be +destroyed, and all memory allocated by the hash table is released. +This function is MT-safe and may be called from any thread. +Frees the memory allocated for @hmac. + + + + + + a #GHmac + + + + + + Feeds @data into an existing #GHmac. + +The HMAC must still be open, that is g_hmac_get_string() or +g_hmac_get_digest() must not have been called on @hmac. + + + + + + a #GHmac + + + + buffer used to compute the checksum + + + + + + size of the buffer, or -1 if it is a nul-terminated string + + + + + + Creates a new #GHmac, using the digest algorithm @digest_type. +If the @digest_type is not known, %NULL is returned. +A #GHmac can be used to compute the HMAC of a key and an +arbitrary binary blob, using different hashing algorithms. + +A #GHmac works by feeding a binary blob through g_hmac_update() +until the data is complete; the digest can then be extracted +using g_hmac_get_string(), which will return the checksum as a +hexadecimal string; or g_hmac_get_digest(), which will return a +array of raw bytes. Once either g_hmac_get_string() or +g_hmac_get_digest() have been called on a #GHmac, the HMAC +will be closed and it won't be possible to call g_hmac_update() +on it anymore. + +Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42. + + the newly created #GHmac, or %NULL. + Use g_hmac_unref() to free the memory allocated by it. + + + + + the desired type of digest + + + + the key for the HMAC + + + + + + the length of the keys + + + + + + + The #GHook struct represents a single hook function in a #GHookList. + + data which is passed to func when this hook is invoked + + + + pointer to the next hook in the list + + + + pointer to the previous hook in the list + + + + the reference count of this hook + + + + the id of this hook, which is unique within its list + + + + flags which are set for this hook. See #GHookFlagMask for + predefined flags + + + + the function to call when this hook is invoked. The possible + signatures for this function are #GHookFunc and #GHookCheckFunc + + + + the default @finalize_hook function of a #GHookList calls + this member of the hook that is being finalized + + + + Compares the ids of two #GHook elements, returning a negative value +if the second id is greater than the first. + + a value <= 0 if the id of @sibling is >= the id of @new_hook + + + + + a #GHook + + + + a #GHook to compare with @new_hook + + + + + + Allocates space for a #GHook and initializes it. + + a new #GHook + + + + + a #GHookList + + + + + + Destroys a #GHook, given its ID. + + %TRUE if the #GHook was found in the #GHookList and destroyed + + + + + a #GHookList + + + + a hook ID + + + + + + Removes one #GHook from a #GHookList, marking it +inactive and calling g_hook_unref() on it. + + + + + + a #GHookList + + + + the #GHook to remove + + + + + + Finds a #GHook in a #GHookList using the given function to +test for a match. + + the found #GHook or %NULL if no matching #GHook is found + + + + + a #GHookList + + + + %TRUE if #GHook elements which have been destroyed + should be skipped + + + + the function to call for each #GHook, which should return + %TRUE when the #GHook has been found + + + + the data to pass to @func + + + + + + Finds a #GHook in a #GHookList with the given data. + + the #GHook with the given @data or %NULL if no matching + #GHook is found + + + + + a #GHookList + + + + %TRUE if #GHook elements which have been destroyed + should be skipped + + + + the data to find + + + + + + Finds a #GHook in a #GHookList with the given function. + + the #GHook with the given @func or %NULL if no matching + #GHook is found + + + + + a #GHookList + + + + %TRUE if #GHook elements which have been destroyed + should be skipped + + + + the function to find + + + + + + Finds a #GHook in a #GHookList with the given function and data. + + the #GHook with the given @func and @data or %NULL if + no matching #GHook is found + + + + + a #GHookList + + + + %TRUE if #GHook elements which have been destroyed + should be skipped + + + + the function to find + + + + the data to find + + + + + + Returns the first #GHook in a #GHookList which has not been destroyed. +The reference count for the #GHook is incremented, so you must call +g_hook_unref() to restore it when no longer needed. (Or call +g_hook_next_valid() if you are stepping through the #GHookList.) + + the first valid #GHook, or %NULL if none are valid + + + + + a #GHookList + + + + %TRUE if hooks which are currently running + (e.g. in another thread) are considered valid. If set to %FALSE, + these are skipped + + + + + + Calls the #GHookList @finalize_hook function if it exists, +and frees the memory allocated for the #GHook. + + + + + + a #GHookList + + + + the #GHook to free + + + + + + Returns the #GHook with the given id, or %NULL if it is not found. + + the #GHook with the given id, or %NULL if it is not found + + + + + a #GHookList + + + + a hook id + + + + + + Inserts a #GHook into a #GHookList, before a given #GHook. + + + + + + a #GHookList + + + + the #GHook to insert the new #GHook before + + + + the #GHook to insert + + + + + + Inserts a #GHook into a #GHookList, sorted by the given function. + + + + + + a #GHookList + + + + the #GHook to insert + + + + the comparison function used to sort the #GHook elements + + + + + + Returns the next #GHook in a #GHookList which has not been destroyed. +The reference count for the #GHook is incremented, so you must call +g_hook_unref() to restore it when no longer needed. (Or continue to call +g_hook_next_valid() until %NULL is returned.) + + the next valid #GHook, or %NULL if none are valid + + + + + a #GHookList + + + + the current #GHook + + + + %TRUE if hooks which are currently running + (e.g. in another thread) are considered valid. If set to %FALSE, + these are skipped + + + + + + Prepends a #GHook on the start of a #GHookList. + + + + + + a #GHookList + + + + the #GHook to add to the start of @hook_list + + + + + + Increments the reference count for a #GHook. + + the @hook that was passed in (since 2.6) + + + + + a #GHookList + + + + the #GHook to increment the reference count of + + + + + + Decrements the reference count of a #GHook. +If the reference count falls to 0, the #GHook is removed +from the #GHookList and g_hook_free() is called to free it. + + + + + + a #GHookList + + + + the #GHook to unref + + + + + + + Defines the type of a hook function that can be invoked +by g_hook_list_invoke_check(). + + %FALSE if the #GHook should be destroyed + + + + + the data field of the #GHook is passed to the hook function here + + + + + + Defines the type of function used by g_hook_list_marshal_check(). + + %FALSE if @hook should be destroyed + + + + + a #GHook + + + + user data + + + + + + Defines the type of function used to compare #GHook elements in +g_hook_insert_sorted(). + + a value <= 0 if @new_hook should be before @sibling + + + + + the #GHook being inserted + + + + the #GHook to compare with @new_hook + + + + + + Defines the type of function to be called when a hook in a +list of hooks gets finalized. + + + + + + a #GHookList + + + + the hook in @hook_list that gets finalized + + + + + + Defines the type of the function passed to g_hook_find(). + + %TRUE if the required #GHook has been found + + + + + a #GHook + + + + user data passed to g_hook_find_func() + + + + + + Flags used internally in the #GHook implementation. + + set if the hook has not been destroyed + + + set if the hook is currently being run + + + A mask covering all bits reserved for + hook flags; see %G_HOOK_FLAG_USER_SHIFT + + + + Defines the type of a hook function that can be invoked +by g_hook_list_invoke(). + + + + + + the data field of the #GHook is passed to the hook function here + + + + + + The #GHookList struct represents a list of hook functions. + + the next free #GHook id + + + + the size of the #GHookList elements, in bytes + + + + 1 if the #GHookList has been initialized + + + + the first #GHook element in the list + + + + unused + + + + the function to call to finalize a #GHook element. + The default behaviour is to call the hooks @destroy function + + + + unused + + + + + + Removes all the #GHook elements from a #GHookList. + + + + + + a #GHookList + + + + + + Initializes a #GHookList. +This must be called before the #GHookList is used. + + + + + + a #GHookList + + + + the size of each element in the #GHookList, + typically `sizeof (GHook)`. + + + + + + Calls all of the #GHook functions in a #GHookList. + + + + + + a #GHookList + + + + %TRUE if functions which are already running + (e.g. in another thread) can be called. If set to %FALSE, + these are skipped + + + + + + Calls all of the #GHook functions in a #GHookList. +Any function which returns %FALSE is removed from the #GHookList. + + + + + + a #GHookList + + + + %TRUE if functions which are already running + (e.g. in another thread) can be called. If set to %FALSE, + these are skipped + + + + + + Calls a function on each valid #GHook. + + + + + + a #GHookList + + + + %TRUE if hooks which are currently running + (e.g. in another thread) are considered valid. If set to %FALSE, + these are skipped + + + + the function to call for each #GHook + + + + data to pass to @marshaller + + + + + + Calls a function on each valid #GHook and destroys it if the +function returns %FALSE. + + + + + + a #GHookList + + + + %TRUE if hooks which are currently running + (e.g. in another thread) are considered valid. If set to %FALSE, + these are skipped + + + + the function to call for each #GHook + + + + data to pass to @marshaller + + + + + + + Defines the type of function used by g_hook_list_marshal(). + + + + + + a #GHook + + + + user data + + + + + + The GIConv struct wraps an iconv() conversion descriptor. It contains +private data and should only be accessed using the following functions. + + Same as the standard UNIX routine iconv(), but +may be implemented via libiconv on UNIX flavors that lack +a native implementation. + +GLib provides g_convert() and g_locale_to_utf8() which are likely +more convenient than the raw iconv wrappers. + + count of non-reversible conversions, or -1 on error + + + + + conversion descriptor from g_iconv_open() + + + + bytes to convert + + + + inout parameter, bytes remaining to convert in @inbuf + + + + converted output bytes + + + + inout parameter, bytes available to fill in @outbuf + + + + + + Same as the standard UNIX routine iconv_close(), but +may be implemented via libiconv on UNIX flavors that lack +a native implementation. Should be called to clean up +the conversion descriptor from g_iconv_open() when +you are done converting things. + +GLib provides g_convert() and g_locale_to_utf8() which are likely +more convenient than the raw iconv wrappers. + + -1 on error, 0 on success + + + + + a conversion descriptor from g_iconv_open() + + + + + + Same as the standard UNIX routine iconv_open(), but +may be implemented via libiconv on UNIX flavors that lack +a native implementation. + +GLib provides g_convert() and g_locale_to_utf8() which are likely +more convenient than the raw iconv wrappers. + + a "conversion descriptor", or (GIConv)-1 if + opening the converter failed. + + + + + destination codeset + + + + source codeset + + + + + + + The bias by which exponents in double-precision floats are offset. + + + + The bias by which exponents in single-precision floats are offset. + + + + A data structure representing an IO Channel. The fields should be +considered private and should only be accessed with the following +functions. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Open a file @filename as a #GIOChannel using mode @mode. This +channel will be closed when the last reference to it is dropped, +so there is no need to call g_io_channel_close() (though doing +so will not cause problems, as long as no attempt is made to +access the channel after it is closed). + + A #GIOChannel on success, %NULL on failure. + + + + + A string containing the name of a file + + + + One of "r", "w", "a", "r+", "w+", "a+". These have + the same meaning as in fopen() + + + + + + Creates a new #GIOChannel given a file descriptor. On UNIX systems +this works for plain files, pipes, and sockets. + +The returned #GIOChannel has a reference count of 1. + +The default encoding for #GIOChannel is UTF-8. If your application +is reading output from a command using via pipe, you may need to set +the encoding to the encoding of the current locale (see +g_get_charset()) with the g_io_channel_set_encoding() function. + +If you want to read raw binary data without interpretation, then +call the g_io_channel_set_encoding() function with %NULL for the +encoding argument. + +This function is available in GLib on Windows, too, but you should +avoid using it on Windows. The domain of file descriptors and +sockets overlap. There is no way for GLib to know which one you mean +in case the argument you pass to this function happens to be both a +valid file descriptor and socket. If that happens a warning is +issued, and GLib assumes that it is the file descriptor you mean. + + a new #GIOChannel. + + + + + a file descriptor. + + + + + + Close an IO channel. Any pending data to be written will be +flushed, ignoring errors. The channel will not be freed until the +last reference is dropped using g_io_channel_unref(). + Use g_io_channel_shutdown() instead. + + + + + + A #GIOChannel + + + + + + Flushes the write buffer for the GIOChannel. + + the status of the operation: One of + #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or + #G_IO_STATUS_ERROR. + + + + + a #GIOChannel + + + + + + This function returns a #GIOCondition depending on whether there +is data to be read/space to write data in the internal buffers in +the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set. + + A #GIOCondition + + + + + A #GIOChannel + + + + + + Gets the buffer size. + + the size of the buffer. + + + + + a #GIOChannel + + + + + + Returns whether @channel is buffered. + + %TRUE if the @channel is buffered. + + + + + a #GIOChannel + + + + + + Returns whether the file/socket/whatever associated with @channel +will be closed when @channel receives its final unref and is +destroyed. The default value of this is %TRUE for channels created +by g_io_channel_new_file (), and %FALSE for all other channels. + + Whether the channel will be closed on the final unref of + the GIOChannel data structure. + + + + + a #GIOChannel. + + + + + + Gets the encoding for the input/output of the channel. +The internal encoding is always UTF-8. The encoding %NULL +makes the channel safe for binary data. + + A string containing the encoding, this string is + owned by GLib and must not be freed. + + + + + a #GIOChannel + + + + + + Gets the current flags for a #GIOChannel, including read-only +flags such as %G_IO_FLAG_IS_READABLE. + +The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE +are cached for internal use by the channel when it is created. +If they should change at some later point (e.g. partial shutdown +of a socket with the UNIX shutdown() function), the user +should immediately call g_io_channel_get_flags() to update +the internal values of these flags. + + the flags which are set on the channel + + + + + a #GIOChannel + + + + + + This returns the string that #GIOChannel uses to determine +where in the file a line break occurs. A value of %NULL +indicates autodetection. + + The line termination string. This value + is owned by GLib and must not be freed. + + + + + a #GIOChannel + + + + a location to return the length of the line terminator + + + + + + Initializes a #GIOChannel struct. + +This is called by each of the above functions when creating a +#GIOChannel, and so is not often needed by the application +programmer (unless you are creating a new type of #GIOChannel). + + + + + + a #GIOChannel + + + + + + Reads data from a #GIOChannel. + Use g_io_channel_read_chars() instead. + + %G_IO_ERROR_NONE if the operation was successful. + + + + + a #GIOChannel + + + + a buffer to read the data into (which should be at least + count bytes long) + + + + the number of bytes to read from the #GIOChannel + + + + returns the number of bytes actually read + + + + + + Replacement for g_io_channel_read() with the new API. + + the status of the operation. + + + + + a #GIOChannel + + + + + a buffer to read data into + + + + + + the size of the buffer. Note that the buffer may not be + complelely filled even if there is data in the buffer if the + remaining data is not a complete character. + + + + The number of bytes read. This may be + zero even on success if count < 6 and the channel's encoding + is non-%NULL. This indicates that the next UTF-8 character is + too wide for the buffer. + + + + + + Reads a line, including the terminating character(s), +from a #GIOChannel into a newly-allocated string. +@str_return will contain allocated memory if the return +is %G_IO_STATUS_NORMAL. + + the status of the operation. + + + + + a #GIOChannel + + + + The line read from the #GIOChannel, including the + line terminator. This data should be freed with g_free() + when no longer needed. This is a nul-terminated string. + If a @length of zero is returned, this will be %NULL instead. + + + + location to store length of the read data, or %NULL + + + + location to store position of line terminator, or %NULL + + + + + + Reads a line from a #GIOChannel, using a #GString as a buffer. + + the status of the operation. + + + + + a #GIOChannel + + + + a #GString into which the line will be written. + If @buffer already contains data, the old data will + be overwritten. + + + + location to store position of line terminator, or %NULL + + + + + + Reads all the remaining data from the file. + + %G_IO_STATUS_NORMAL on success. + This function never returns %G_IO_STATUS_EOF. + + + + + a #GIOChannel + + + + Location to + store a pointer to a string holding the remaining data in the + #GIOChannel. This data should be freed with g_free() when no + longer needed. This data is terminated by an extra nul + character, but there may be other nuls in the intervening data. + + + + + + location to store length of the data + + + + + + Reads a Unicode character from @channel. +This function cannot be called on a channel with %NULL encoding. + + a #GIOStatus + + + + + a #GIOChannel + + + + a location to return a character + + + + + + Increments the reference count of a #GIOChannel. + + the @channel that was passed in (since 2.6) + + + + + a #GIOChannel + + + + + + Sets the current position in the #GIOChannel, similar to the standard +library function fseek(). + Use g_io_channel_seek_position() instead. + + %G_IO_ERROR_NONE if the operation was successful. + + + + + a #GIOChannel + + + + an offset, in bytes, which is added to the position specified + by @type + + + + the position in the file, which can be %G_SEEK_CUR (the current + position), %G_SEEK_SET (the start of the file), or %G_SEEK_END + (the end of the file) + + + + + + Replacement for g_io_channel_seek() with the new API. + + the status of the operation. + + + + + a #GIOChannel + + + + The offset in bytes from the position specified by @type + + + + a #GSeekType. The type %G_SEEK_CUR is only allowed in those + cases where a call to g_io_channel_set_encoding () + is allowed. See the documentation for + g_io_channel_set_encoding () for details. + + + + + + Sets the buffer size. + + + + + + a #GIOChannel + + + + the size of the buffer, or 0 to let GLib pick a good size + + + + + + The buffering state can only be set if the channel's encoding +is %NULL. For any other encoding, the channel must be buffered. + +A buffered channel can only be set unbuffered if the channel's +internal buffers have been flushed. Newly created channels or +channels which have returned %G_IO_STATUS_EOF +not require such a flush. For write-only channels, a call to +g_io_channel_flush () is sufficient. For all other channels, +the buffers may be flushed by a call to g_io_channel_seek_position (). +This includes the possibility of seeking with seek type %G_SEEK_CUR +and an offset of zero. Note that this means that socket-based +channels cannot be set unbuffered once they have had data +read from them. + +On unbuffered channels, it is safe to mix read and write +calls from the new and old APIs, if this is necessary for +maintaining old code. + +The default state of the channel is buffered. + + + + + + a #GIOChannel + + + + whether to set the channel buffered or unbuffered + + + + + + Setting this flag to %TRUE for a channel you have already closed +can cause problems. + + + + + + a #GIOChannel + + + + Whether to close the channel on the final unref of + the GIOChannel data structure. The default value of + this is %TRUE for channels created by g_io_channel_new_file (), + and %FALSE for all other channels. + + + + + + Sets the encoding for the input/output of the channel. +The internal encoding is always UTF-8. The default encoding +for the external file is UTF-8. + +The encoding %NULL is safe to use with binary data. + +The encoding can only be set if one of the following conditions +is true: + +- The channel was just created, and has not been written to or read from yet. + +- The channel is write-only. + +- The channel is a file, and the file pointer was just repositioned + by a call to g_io_channel_seek_position(). (This flushes all the + internal buffers.) + +- The current encoding is %NULL or UTF-8. + +- One of the (new API) read functions has just returned %G_IO_STATUS_EOF + (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL). + +- One of the functions g_io_channel_read_chars() or + g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or + %G_IO_STATUS_ERROR. This may be useful in the case of + %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. + Returning one of these statuses from g_io_channel_read_line(), + g_io_channel_read_line_string(), or g_io_channel_read_to_end() + does not guarantee that the encoding can be changed. + +Channels which do not meet one of the above conditions cannot call +g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if +they are "seekable", cannot call g_io_channel_write_chars() after +calling one of the API "read" functions. + + %G_IO_STATUS_NORMAL if the encoding was successfully set + + + + + a #GIOChannel + + + + the encoding type + + + + + + Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK). + + the status of the operation. + + + + + a #GIOChannel + + + + the flags to set on the IO channel + + + + + + This sets the string that #GIOChannel uses to determine +where in the file a line break occurs. + + + + + + a #GIOChannel + + + + The line termination string. Use %NULL for + autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", + and the Unicode paragraph separator. Autodetection should not be + used for anything other than file-based channels. + + + + The length of the termination string. If -1 is passed, the + string is assumed to be nul-terminated. This option allows + termination strings with embedded nuls. + + + + + + Close an IO channel. Any pending data to be written will be +flushed if @flush is %TRUE. The channel will not be freed until the +last reference is dropped using g_io_channel_unref(). + + the status of the operation. + + + + + a #GIOChannel + + + + if %TRUE, flush pending + + + + + + Returns the file descriptor of the #GIOChannel. + +On Windows this function returns the file descriptor or socket of +the #GIOChannel. + + the file descriptor of the #GIOChannel. + + + + + a #GIOChannel, created with g_io_channel_unix_new(). + + + + + + Decrements the reference count of a #GIOChannel. + + + + + + a #GIOChannel + + + + + + Writes data to a #GIOChannel. + Use g_io_channel_write_chars() instead. + + %G_IO_ERROR_NONE if the operation was successful. + + + + + a #GIOChannel + + + + the buffer containing the data to write + + + + the number of bytes to write + + + + the number of bytes actually written + + + + + + Replacement for g_io_channel_write() with the new API. + +On seekable channels with encodings other than %NULL or UTF-8, generic +mixing of reading and writing is not allowed. A call to g_io_channel_write_chars () +may only be made on a channel from which data has been read in the +cases described in the documentation for g_io_channel_set_encoding (). + + the status of the operation. + + + + + a #GIOChannel + + + + a buffer to write data from + + + + + + the size of the buffer. If -1, the buffer + is taken to be a nul-terminated string. + + + + The number of bytes written. This can be nonzero + even if the return value is not %G_IO_STATUS_NORMAL. + If the return value is %G_IO_STATUS_NORMAL and the + channel is blocking, this will always be equal + to @count if @count >= 0. + + + + + + Writes a Unicode character to @channel. +This function cannot be called on a channel with %NULL encoding. + + a #GIOStatus + + + + + a #GIOChannel + + + + a character + + + + + + Converts an `errno` error number to a #GIOChannelError. + + a #GIOChannelError error number, e.g. + %G_IO_CHANNEL_ERROR_INVAL. + + + + + an `errno` error number, e.g. `EINVAL` + + + + + + + + + + + + Error codes returned by #GIOChannel operations. + + File too large. + + + Invalid argument. + + + IO error. + + + File is a directory. + + + No space left on device. + + + No such device or address. + + + Value too large for defined datatype. + + + Broken pipe. + + + Some other error. + + + + A bitwise combination representing a condition to watch for on an +event source. + + There is data to read. + + + Data can be written (without blocking). + + + There is urgent data to read. + + + Error condition. + + + Hung up (the connection has been broken, usually for + pipes and sockets). + + + Invalid request. The file descriptor is not open. + + + + #GIOError is only used by the deprecated functions +g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek(). + + no error + + + an EAGAIN error occurred + + + an EINVAL error occurred + + + another error occurred + + + + Specifies properties of a #GIOChannel. Some of the flags can only be +read with g_io_channel_get_flags(), but not changed with +g_io_channel_set_flags(). + + turns on append mode, corresponds to %O_APPEND + (see the documentation of the UNIX open() syscall) + + + turns on nonblocking mode, corresponds to + %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() + syscall) + + + indicates that the io channel is readable. + This flag cannot be changed. + + + indicates that the io channel is writable. + This flag cannot be changed. + + + a misspelled version of @G_IO_FLAG_IS_WRITABLE + that existed before the spelling was fixed in GLib 2.30. It is kept + here for compatibility reasons. Deprecated since 2.30 + + + indicates that the io channel is seekable, + i.e. that g_io_channel_seek_position() can be used on it. + This flag cannot be changed. + + + the mask that specifies all the valid flags. + + + the mask of the flags that are returned from + g_io_channel_get_flags() + + + the mask of the flags that the user can modify + with g_io_channel_set_flags() + + + + Specifies the type of function passed to g_io_add_watch() or +g_io_add_watch_full(), which is called when the requested condition +on a #GIOChannel is satisfied. + + the function should return %FALSE if the event source + should be removed + + + + + the #GIOChannel event source + + + + the condition which has been satisfied + + + + user data set in g_io_add_watch() or g_io_add_watch_full() + + + + + + A table of functions used to handle different types of #GIOChannel +in a generic way. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Stati returned by most of the #GIOFuncs functions. + + An error occurred. + + + Success. + + + End of file. + + + Resource temporarily unavailable. + + + + The name of the main group of a desktop entry file, as defined in the +[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec). +Consult the specification for more +details about the meanings of the keys below. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list +giving the available application actions. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list +of strings giving the categories in which the desktop entry +should be shown in a menu. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized +string giving the tooltip for the desktop entry. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true +if the application is D-Bus activatable. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string +giving the command line to execute. It is only valid for desktop +entries with the `Application` type. + + + + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized +string giving the generic name of the desktop entry. + + + + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean +stating whether the desktop entry has been deleted by the user. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized +string giving the name of the icon to be displayed for the desktop +entry. + + + + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list +of strings giving the MIME types supported by this desktop entry. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized +string giving the specific name of the desktop entry. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of +strings identifying the environments that should not display the +desktop entry. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean +stating whether the desktop entry should be shown in menus. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of +strings identifying the environments that should display the +desktop entry. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string +containing the working directory to run the program in. It is only +valid for desktop entries with the `Application` type. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean +stating whether the application supports the +[Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string +identifying the WM class or name hint of a window that the application +will create, which can be used to emulate Startup Notification with +older applications. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean +stating whether the program should be run in a terminal window. +It is only valid for desktop entries with the +`Application` type. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string +giving the file name of a binary on disk used to determine if the +program is actually installed. It is only valid for desktop entries +with the `Application` type. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string +giving the type of the desktop entry. Usually +#G_KEY_FILE_DESKTOP_TYPE_APPLICATION, +#G_KEY_FILE_DESKTOP_TYPE_LINK, or +#G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string +giving the URL to access. It is only valid for desktop entries +with the `Link` type. + + + + A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string +giving the version of the Desktop Entry Specification used for +the desktop entry file. + + + + The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop +entries representing applications. + + + + The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop +entries representing directories. + + + + The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop +entries representing links to documents. + + + + The GKeyFile struct contains only private data +and should not be accessed directly. + + Creates a new empty #GKeyFile object. Use +g_key_file_load_from_file(), g_key_file_load_from_data(), +g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to +read an existing key file. + + an empty #GKeyFile. + + + + + Clears all keys and groups from @key_file, and decreases the +reference count by 1. If the reference count reaches zero, +frees the key file and all its allocated memory. + + + + + + a #GKeyFile + + + + + + Returns the value associated with @key under @group_name as a +boolean. + +If @key cannot be found then %FALSE is returned and @error is set +to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value +associated with @key cannot be interpreted as a boolean then %FALSE +is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + the value associated with the key as a boolean, + or %FALSE if the key was not found or could not be parsed. + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + + + Returns the values associated with @key under @group_name as +booleans. + +If @key cannot be found then %NULL is returned and @error is set to +#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated +with @key cannot be interpreted as booleans then %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + + the values associated with the key as a list of booleans, or %NULL if the + key was not found or could not be parsed. The returned list of booleans + should be freed with g_free() when no longer needed. + + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + the number of booleans returned + + + + + + Retrieves a comment above @key from @group_name. +If @key is %NULL then @comment will be read from above +@group_name. If both @key and @group_name are %NULL, then +@comment will be read from above the first group in the file. + +Note that the returned string includes the '#' comment markers. + + a comment that should be freed with g_free() + + + + + a #GKeyFile + + + + a group name, or %NULL + + + + a key + + + + + + Returns the value associated with @key under @group_name as a +double. If @group_name is %NULL, the start_group is used. + +If @key cannot be found then 0.0 is returned and @error is set to +#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated +with @key cannot be interpreted as a double then 0.0 is returned +and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + the value associated with the key as a double, or + 0.0 if the key was not found or could not be parsed. + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + + + Returns the values associated with @key under @group_name as +doubles. + +If @key cannot be found then %NULL is returned and @error is set to +#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated +with @key cannot be interpreted as doubles then %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + + the values associated with the key as a list of doubles, or %NULL if the + key was not found or could not be parsed. The returned list of doubles + should be freed with g_free() when no longer needed. + + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + the number of doubles returned + + + + + + Returns all groups in the key file loaded with @key_file. +The array of returned groups will be %NULL-terminated, so +@length may optionally be %NULL. + + a newly-allocated %NULL-terminated array of strings. + Use g_strfreev() to free it. + + + + + + + a #GKeyFile + + + + return location for the number of returned groups, or %NULL + + + + + + Returns the value associated with @key under @group_name as a signed +64-bit integer. This is similar to g_key_file_get_integer() but can return +64-bit results without truncation. + + the value associated with the key as a signed 64-bit integer, or +0 if the key was not found or could not be parsed. + + + + + a non-%NULL #GKeyFile + + + + a non-%NULL group name + + + + a non-%NULL key + + + + + + Returns the value associated with @key under @group_name as an +integer. + +If @key cannot be found then 0 is returned and @error is set to +#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated +with @key cannot be interpreted as an integer then 0 is returned +and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + the value associated with the key as an integer, or + 0 if the key was not found or could not be parsed. + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + + + Returns the values associated with @key under @group_name as +integers. + +If @key cannot be found then %NULL is returned and @error is set to +#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated +with @key cannot be interpreted as integers then %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. + + + the values associated with the key as a list of integers, or %NULL if + the key was not found or could not be parsed. The returned list of + integers should be freed with g_free() when no longer needed. + + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + the number of integers returned + + + + + + Returns all keys for the group name @group_name. The array of +returned keys will be %NULL-terminated, so @length may +optionally be %NULL. In the event that the @group_name cannot +be found, %NULL is returned and @error is set to +#G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + + a newly-allocated %NULL-terminated array of strings. + Use g_strfreev() to free it. + + + + + + + a #GKeyFile + + + + a group name + + + + return location for the number of keys returned, or %NULL + + + + + + Returns the value associated with @key under @group_name +translated in the given @locale if available. If @locale is +%NULL then the current locale is assumed. + +If @key cannot be found then %NULL is returned and @error is set +to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated +with @key cannot be interpreted or no suitable translation can +be found then the untranslated value is returned. + + a newly allocated string or %NULL if the specified + key cannot be found. + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + a locale identifier or %NULL + + + + + + Returns the values associated with @key under @group_name +translated in the given @locale if available. If @locale is +%NULL then the current locale is assumed. + +If @key cannot be found then %NULL is returned and @error is set +to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated +with @key cannot be interpreted or no suitable translations +can be found then the untranslated values are returned. The +returned array is %NULL-terminated, so @length may optionally +be %NULL. + + a newly allocated %NULL-terminated string array + or %NULL if the key isn't found. The string array should be freed + with g_strfreev(). + + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + a locale identifier or %NULL + + + + return location for the number of returned strings or %NULL + + + + + + Returns the name of the start group of the file. + + The start group of the key file. + + + + + a #GKeyFile + + + + + + Returns the string value associated with @key under @group_name. +Unlike g_key_file_get_value(), this function handles escape sequences +like \s. + +In the event the key cannot be found, %NULL is returned and +@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the +event that the @group_name cannot be found, %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + + a newly allocated string or %NULL if the specified + key cannot be found. + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + + + Returns the values associated with @key under @group_name. + +In the event the key cannot be found, %NULL is returned and +@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the +event that the @group_name cannot be found, %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + + + a %NULL-terminated string array or %NULL if the specified + key cannot be found. The array should be freed with g_strfreev(). + + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + return location for the number of returned strings, or %NULL + + + + + + Returns the value associated with @key under @group_name as an unsigned +64-bit integer. This is similar to g_key_file_get_integer() but can return +large positive results without truncation. + + the value associated with the key as an unsigned 64-bit integer, +or 0 if the key was not found or could not be parsed. + + + + + a non-%NULL #GKeyFile + + + + a non-%NULL group name + + + + a non-%NULL key + + + + + + Returns the raw value associated with @key under @group_name. +Use g_key_file_get_string() to retrieve an unescaped UTF-8 string. + +In the event the key cannot be found, %NULL is returned and +@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the +event that the @group_name cannot be found, %NULL is returned +and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. + + a newly allocated string or %NULL if the specified + key cannot be found. + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + + + Looks whether the key file has the group @group_name. + + %TRUE if @group_name is a part of @key_file, %FALSE +otherwise. + + + + + a #GKeyFile + + + + a group name + + + + + + Looks whether the key file has the key @key in the group +@group_name. + +Note that this function does not follow the rules for #GError strictly; +the return value both carries meaning and signals an error. To use +this function, you must pass a #GError pointer in @error, and check +whether it is not %NULL to see if an error occurred. + +Language bindings should use g_key_file_get_value() to test whether +or not a key exists. + + %TRUE if @key is a part of @group_name, %FALSE otherwise + + + + + a #GKeyFile + + + + a group name + + + + a key name + + + + + + Loads a key file from the data in @bytes into an empty #GKeyFile structure. +If the object cannot be created then %error is set to a #GKeyFileError. + + %TRUE if a key file could be loaded, %FALSE otherwise + + + + + an empty #GKeyFile struct + + + + a #GBytes + + + + flags from #GKeyFileFlags + + + + + + Loads a key file from memory into an empty #GKeyFile structure. +If the object cannot be created then %error is set to a #GKeyFileError. + + %TRUE if a key file could be loaded, %FALSE otherwise + + + + + an empty #GKeyFile struct + + + + key file loaded in memory + + + + the length of @data in bytes (or (gsize)-1 if data is nul-terminated) + + + + flags from #GKeyFileFlags + + + + + + This function looks for a key file named @file in the paths +returned from g_get_user_data_dir() and g_get_system_data_dirs(), +loads the file into @key_file and returns the file's full path in +@full_path. If the file could not be loaded then an %error is +set to either a #GFileError or #GKeyFileError. + + %TRUE if a key file could be loaded, %FALSE othewise + + + + + an empty #GKeyFile struct + + + + a relative path to a filename to open and parse + + + + return location for a string containing the full path + of the file, or %NULL + + + + flags from #GKeyFileFlags + + + + + + This function looks for a key file named @file in the paths +specified in @search_dirs, loads the file into @key_file and +returns the file's full path in @full_path. If the file could not +be loaded then an %error is set to either a #GFileError or +#GKeyFileError. + + %TRUE if a key file could be loaded, %FALSE otherwise + + + + + an empty #GKeyFile struct + + + + a relative path to a filename to open and parse + + + + %NULL-terminated array of directories to search + + + + + + return location for a string containing the full path + of the file, or %NULL + + + + flags from #GKeyFileFlags + + + + + + Loads a key file into an empty #GKeyFile structure. +If the file could not be loaded then @error is set to +either a #GFileError or #GKeyFileError. + + %TRUE if a key file could be loaded, %FALSE otherwise + + + + + an empty #GKeyFile struct + + + + the path of a filename to load, in the GLib filename encoding + + + + flags from #GKeyFileFlags + + + + + + Increases the reference count of @key_file. + + the same @key_file. + + + + + a #GKeyFile + + + + + + Removes a comment above @key from @group_name. +If @key is %NULL then @comment will be removed above @group_name. +If both @key and @group_name are %NULL, then @comment will +be removed above the first group in the file. + + %TRUE if the comment was removed, %FALSE otherwise + + + + + a #GKeyFile + + + + a group name, or %NULL + + + + a key + + + + + + Removes the specified group, @group_name, +from the key file. + + %TRUE if the group was removed, %FALSE otherwise + + + + + a #GKeyFile + + + + a group name + + + + + + Removes @key in @group_name from the key file. + + %TRUE if the key was removed, %FALSE otherwise + + + + + a #GKeyFile + + + + a group name + + + + a key name to remove + + + + + + Writes the contents of @key_file to @filename using +g_file_set_contents(). + +This function can fail for any of the reasons that +g_file_set_contents() may fail. + + %TRUE if successful, else %FALSE with @error set + + + + + a #GKeyFile + + + + the name of the file to write to + + + + + + Associates a new boolean value with @key under @group_name. +If @key cannot be found then it is created. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + %TRUE or %FALSE + + + + + + Associates a list of boolean values with @key under @group_name. +If @key cannot be found then it is created. +If @group_name is %NULL, the start_group is used. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + an array of boolean values + + + + + + length of @list + + + + + + Places a comment above @key from @group_name. + +If @key is %NULL then @comment will be written above @group_name. +If both @key and @group_name are %NULL, then @comment will be +written above the first group in the file. + +Note that this function prepends a '#' comment marker to +each line of @comment. + + %TRUE if the comment was written, %FALSE otherwise + + + + + a #GKeyFile + + + + a group name, or %NULL + + + + a key + + + + a comment + + + + + + Associates a new double value with @key under @group_name. +If @key cannot be found then it is created. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + an double value + + + + + + Associates a list of double values with @key under +@group_name. If @key cannot be found then it is created. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + an array of double values + + + + + + number of double values in @list + + + + + + Associates a new integer value with @key under @group_name. +If @key cannot be found then it is created. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + an integer value + + + + + + Associates a new integer value with @key under @group_name. +If @key cannot be found then it is created. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + an integer value + + + + + + Associates a list of integer values with @key under @group_name. +If @key cannot be found then it is created. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + an array of integer values + + + + + + number of integer values in @list + + + + + + Sets the character which is used to separate +values in lists. Typically ';' or ',' are used +as separators. The default list separator is ';'. + + + + + + a #GKeyFile + + + + the separator + + + + + + Associates a string value for @key and @locale under @group_name. +If the translation for @key cannot be found then it is created. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + a locale identifier + + + + a string + + + + + + Associates a list of string values for @key and @locale under +@group_name. If the translation for @key cannot be found then +it is created. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + a locale identifier + + + + a %NULL-terminated array of locale string values + + + + + + the length of @list + + + + + + Associates a new string value with @key under @group_name. +If @key cannot be found then it is created. +If @group_name cannot be found then it is created. +Unlike g_key_file_set_value(), this function handles characters +that need escaping, such as newlines. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + a string + + + + + + Associates a list of string values for @key under @group_name. +If @key cannot be found then it is created. +If @group_name cannot be found then it is created. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + an array of string values + + + + + + number of string values in @list + + + + + + Associates a new integer value with @key under @group_name. +If @key cannot be found then it is created. + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + an integer value + + + + + + Associates a new value with @key under @group_name. + +If @key cannot be found then it is created. If @group_name cannot +be found then it is created. To set an UTF-8 string which may contain +characters that need escaping (such as newlines or spaces), use +g_key_file_set_string(). + + + + + + a #GKeyFile + + + + a group name + + + + a key + + + + a string + + + + + + This function outputs @key_file as a string. + +Note that this function never reports an error, +so it is safe to pass %NULL as @error. + + a newly allocated string holding + the contents of the #GKeyFile + + + + + a #GKeyFile + + + + return location for the length of the + returned string, or %NULL + + + + + + Decreases the reference count of @key_file by 1. If the reference count +reaches zero, frees the key file and all its allocated memory. + + + + + + a #GKeyFile + + + + + + + + + + + + Error codes returned by key file parsing. + + the text being parsed was in + an unknown encoding + + + document was ill-formed + + + the file was not found + + + a requested key was not found + + + a requested group was not found + + + a value could not be parsed + + + + Flags which influence the parsing. + + No flags, default behaviour + + + Use this flag if you plan to write the + (possibly modified) contents of the key file back to a file; + otherwise all comments will be lost when the key file is + written back. + + + Use this flag if you plan to write the + (possibly modified) contents of the key file back to a file; + otherwise only the translations for the current language will be + written back. + + + + Specifies one of the possible types of byte order. +See #G_BYTE_ORDER. + + + + The natural logarithm of 10. + + + + The natural logarithm of 2. + + + + Multiplying the base 2 exponent by this number yields the base 10 exponent. + + + + Defines the log domain. + +For applications, this is typically left as the default %NULL +(or "") domain. Libraries should define this so that any messages +which they log can be differentiated from messages from other +libraries and application code. But be careful not to define +it in any public header files. + +For example, GTK+ uses this in its Makefile.am: +|[ +AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\" +]| + + + + GLib log levels that are considered fatal by default. + +This is not used if structured logging is enabled; see +[Using Structured Logging][using-structured-logging]. + + + + Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib. +Higher bits can be used for user-defined log levels. + + + + The #GList struct is used for each element in a doubly-linked list. + + holds the element's data, which can be a pointer to any kind + of data, or any integer value using the + [Type Conversion Macros][glib-Type-Conversion-Macros] + + + + contains the link to the next element in the list + + + + + + contains the link to the previous element in the list + + + + + + Allocates space for one #GList element. It is called by +g_list_append(), g_list_prepend(), g_list_insert() and +g_list_insert_sorted() and so is rarely used on its own. + + a pointer to the newly-allocated #GList element + + + + + + + Adds a new element on to the end of the list. + +Note that the return value is the new start of the list, +if @list was empty; make sure you store the new value. + +g_list_append() has to traverse the entire list to find the end, +which is inefficient when adding multiple elements. A common idiom +to avoid the inefficiency is to use g_list_prepend() and reverse +the list with g_list_reverse() when all elements have been added. + +|[<!-- language="C" --> +// Notice that these are initialized to the empty list. +GList *string_list = NULL, *number_list = NULL; + +// This is a list of strings. +string_list = g_list_append (string_list, "first"); +string_list = g_list_append (string_list, "second"); + +// This is a list of integers. +number_list = g_list_append (number_list, GINT_TO_POINTER (27)); +number_list = g_list_append (number_list, GINT_TO_POINTER (14)); +]| + + either @list or the new start of the #GList if @list was %NULL + + + + + + + a pointer to a #GList + + + + + + the data for the new element + + + + + + Adds the second #GList onto the end of the first #GList. +Note that the elements of the second #GList are not copied. +They are used directly. + +This function is for example used to move an element in the list. +The following example moves an element to the top of the list: +|[<!-- language="C" --> +list = g_list_remove_link (list, llink); +list = g_list_concat (llink, list); +]| + + the start of the new #GList, which equals @list1 if not %NULL + + + + + + + a #GList, this must point to the top of the list + + + + + + the #GList to add to the end of the first #GList, + this must point to the top of the list + + + + + + + + Copies a #GList. + +Note that this is a "shallow" copy. If the list elements +consist of pointers to data, the pointers are copied but +the actual data is not. See g_list_copy_deep() if you need +to copy the data as well. + + the start of the new list that holds the same data as @list + + + + + + + a #GList, this must point to the top of the list + + + + + + + + Makes a full (deep) copy of a #GList. + +In contrast with g_list_copy(), this function uses @func to make +a copy of each list element, in addition to copying the list +container itself. + +@func, as a #GCopyFunc, takes two arguments, the data to be copied +and a @user_data pointer. It's safe to pass %NULL as user_data, +if the copy function takes only one argument. + +For instance, if @list holds a list of GObjects, you can do: +|[<!-- language="C" --> +another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL); +]| + +And, to entirely free the new list, you could do: +|[<!-- language="C" --> +g_list_free_full (another_list, g_object_unref); +]| + + the start of the new list that holds a full copy of @list, + use g_list_free_full() to free it + + + + + + + a #GList, this must point to the top of the list + + + + + + a copy function used to copy every element in the list + + + + user data passed to the copy function @func, or %NULL + + + + + + Removes the node link_ from the list and frees it. +Compare this to g_list_remove_link() which removes the node +without freeing it. + + the (possibly changed) start of the #GList + + + + + + + a #GList, this must point to the top of the list + + + + + + node to delete from @list + + + + + + + + Finds the element in a #GList which contains the given data. + + the found #GList element, or %NULL if it is not found + + + + + + + a #GList, this must point to the top of the list + + + + + + the element data to find + + + + + + Finds an element in a #GList, using a supplied function to +find the desired element. It iterates over the list, calling +the given function which should return 0 when the desired +element is found. The function takes two #gconstpointer arguments, +the #GList element's data as the first argument and the +given user data. + + the found #GList element, or %NULL if it is not found + + + + + + + a #GList, this must point to the top of the list + + + + + + user data passed to the function + + + + the function to call for each element. + It should return 0 when the desired element is found + + + + + + Gets the first element in a #GList. + + the first element in the #GList, + or %NULL if the #GList has no elements + + + + + + + any #GList element + + + + + + + + Calls a function for each element of a #GList. + + + + + + a #GList, this must point to the top of the list + + + + + + the function to call with each element's data + + + + user data to pass to the function + + + + + + Frees all of the memory used by a #GList. +The freed elements are returned to the slice allocator. + +If list elements contain dynamically-allocated memory, you should +either use g_list_free_full() or free them manually first. + + + + + + a #GList + + + + + + + + Frees one #GList element, but does not update links from the next and +previous elements in the list, so you should not call this function on an +element that is currently part of a list. + +It is usually used after g_list_remove_link(). + + + + + + a #GList element + + + + + + + + Convenience method, which frees all the memory used by a #GList, +and calls @free_func on every element's data. + + + + + + a pointer to a #GList + + + + + + the function to be called to free each element's data + + + + + + Gets the position of the element containing +the given data (starting from 0). + + the index of the element containing the data, + or -1 if the data is not found + + + + + a #GList, this must point to the top of the list + + + + + + the data to find + + + + + + Inserts a new element into the list at the given position. + + the (possibly changed) start of the #GList + + + + + + + a pointer to a #GList, this must point to the top of the list + + + + + + the data for the new element + + + + the position to insert the element. If this is + negative, or is larger than the number of elements in the + list, the new element is added on to the end of the list. + + + + + + Inserts a new element into the list before the given position. + + the (possibly changed) start of the #GList + + + + + + + a pointer to a #GList, this must point to the top of the list + + + + + + the list element before which the new element + is inserted or %NULL to insert at the end of the list + + + + + + the data for the new element + + + + + + Inserts a new element into the list, using the given comparison +function to determine its position. + +If you are adding many new elements to a list, and the number of +new elements is much larger than the length of the list, use +g_list_prepend() to add the new items and sort the list afterwards +with g_list_sort(). + + the (possibly changed) start of the #GList + + + + + + + a pointer to a #GList, this must point to the top of the + already sorted list + + + + + + the data for the new element + + + + the function to compare elements in the list. It should + return a number > 0 if the first parameter comes after the + second parameter in the sort order. + + + + + + Inserts a new element into the list, using the given comparison +function to determine its position. + +If you are adding many new elements to a list, and the number of +new elements is much larger than the length of the list, use +g_list_prepend() to add the new items and sort the list afterwards +with g_list_sort(). + + the (possibly changed) start of the #GList + + + + + + + a pointer to a #GList, this must point to the top of the + already sorted list + + + + + + the data for the new element + + + + the function to compare elements in the list. It should + return a number > 0 if the first parameter comes after the + second parameter in the sort order. + + + + user data to pass to comparison function + + + + + + Gets the last element in a #GList. + + the last element in the #GList, + or %NULL if the #GList has no elements + + + + + + + any #GList element + + + + + + + + Gets the number of elements in a #GList. + +This function iterates over the whole list to count its elements. +Use a #GQueue instead of a GList if you regularly need the number +of items. To check whether the list is non-empty, it is faster to check +@list against %NULL. + + the number of elements in the #GList + + + + + a #GList, this must point to the top of the list + + + + + + + + Gets the element at the given position in a #GList. + +This iterates over the list until it reaches the @n-th position. If you +intend to iterate over every element, it is better to use a for-loop as +described in the #GList introduction. + + the element, or %NULL if the position is off + the end of the #GList + + + + + + + a #GList, this must point to the top of the list + + + + + + the position of the element, counting from 0 + + + + + + Gets the data of the element at the given position. + +This iterates over the list until it reaches the @n-th position. If you +intend to iterate over every element, it is better to use a for-loop as +described in the #GList introduction. + + the element's data, or %NULL if the position + is off the end of the #GList + + + + + a #GList, this must point to the top of the list + + + + + + the position of the element + + + + + + Gets the element @n places before @list. + + the element, or %NULL if the position is + off the end of the #GList + + + + + + + a #GList + + + + + + the position of the element, counting from 0 + + + + + + Gets the position of the given element +in the #GList (starting from 0). + + the position of the element in the #GList, + or -1 if the element is not found + + + + + a #GList, this must point to the top of the list + + + + + + an element in the #GList + + + + + + + + Prepends a new element on to the start of the list. + +Note that the return value is the new start of the list, +which will have changed, so make sure you store the new value. + +|[<!-- language="C" --> +// Notice that it is initialized to the empty list. +GList *list = NULL; + +list = g_list_prepend (list, "last"); +list = g_list_prepend (list, "first"); +]| + +Do not use this function to prepend a new element to a different +element than the start of the list. Use g_list_insert_before() instead. + + a pointer to the newly prepended element, which is the new + start of the #GList + + + + + + + a pointer to a #GList, this must point to the top of the list + + + + + + the data for the new element + + + + + + Removes an element from a #GList. +If two elements contain the same data, only the first is removed. +If none of the elements contain the data, the #GList is unchanged. + + the (possibly changed) start of the #GList + + + + + + + a #GList, this must point to the top of the list + + + + + + the data of the element to remove + + + + + + Removes all list nodes with data equal to @data. +Returns the new head of the list. Contrast with +g_list_remove() which removes only the first node +matching the given data. + + the (possibly changed) start of the #GList + + + + + + + a #GList, this must point to the top of the list + + + + + + data to remove + + + + + + Removes an element from a #GList, without freeing the element. +The removed element's prev and next links are set to %NULL, so +that it becomes a self-contained list with one element. + +This function is for example used to move an element in the list +(see the example for g_list_concat()) or to remove an element in +the list before freeing its data: +|[<!-- language="C" --> +list = g_list_remove_link (list, llink); +free_some_data_that_may_access_the_list_again (llink->data); +g_list_free (llink); +]| + + the (possibly changed) start of the #GList + + + + + + + a #GList, this must point to the top of the list + + + + + + an element in the #GList + + + + + + + + Reverses a #GList. +It simply switches the next and prev pointers of each element. + + the start of the reversed #GList + + + + + + + a #GList, this must point to the top of the list + + + + + + + + Sorts a #GList using the given comparison function. The algorithm +used is a stable sort. + + the (possibly changed) start of the #GList + + + + + + + a #GList, this must point to the top of the list + + + + + + the comparison function used to sort the #GList. + This function is passed the data from 2 elements of the #GList + and should return 0 if they are equal, a negative value if the + first element comes before the second, or a positive value if + the first element comes after the second. + + + + + + Like g_list_sort(), but the comparison function accepts +a user data argument. + + the (possibly changed) start of the #GList + + + + + + + a #GList, this must point to the top of the list + + + + + + comparison function + + + + user data to pass to comparison function + + + + + + + Structure representing a single field in a structured log entry. See +g_log_structured() for details. + +Log fields may contain arbitrary values, including binary with embedded nul +bytes. If the field contains a string, the string must be UTF-8 encoded and +have a trailing nul byte. Otherwise, @length must be set to a non-negative +value. + + field name (UTF-8 string) + + + + field value (arbitrary bytes) + + + + length of @value, in bytes, or -1 if it is nul-terminated + + + + + Specifies the prototype of log handler functions. + +The default log handler, g_log_default_handler(), automatically appends a +new-line character to @message when printing it. It is advised that any +custom log handler functions behave similarly, so that logging calls in user +code do not need modifying to add a new-line character to the message if the +log handler is changed. + +This is not used if structured logging is enabled; see +[Using Structured Logging][using-structured-logging]. + + + + + + the log domain of the message + + + + the log level of the message (including the + fatal and recursion flags) + + + + the message to process + + + + user data, set in g_log_set_handler() + + + + + + Flags specifying the level of log messages. + +It is possible to change how GLib treats messages of the various +levels using g_log_set_handler() and g_log_set_fatal_mask(). + + internal flag + + + internal flag + + + log level for errors, see g_error(). + This level is also used for messages produced by g_assert(). + + + log level for critical warning messages, see + g_critical(). + This level is also used for messages produced by g_return_if_fail() + and g_return_val_if_fail(). + + + log level for warnings, see g_warning() + + + log level for messages, see g_message() + + + log level for informational messages, see g_info() + + + log level for debug messages, see g_debug() + + + a mask including all log levels + + + + Writer function for log entries. A log entry is a collection of one or more +#GLogFields, using the standard [field names from journal +specification](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html). +See g_log_structured() for more information. + +Writer functions must ignore fields which they do not recognise, unless they +can write arbitrary binary output, as field values may be arbitrary binary. + +@log_level is guaranteed to be included in @fields as the `PRIORITY` field, +but is provided separately for convenience of deciding whether or where to +output the log entry. + + %G_LOG_WRITER_HANDLED if the log entry was handled successfully; + %G_LOG_WRITER_UNHANDLED otherwise + + + + + log level of the message + + + + fields forming the message + + + + + + number of @fields + + + + user data passed to g_log_set_writer_func() + + + + + + Return values from #GLogWriterFuncs to indicate whether the given log entry +was successfully handled by the writer, or whether there was an error in +handling it (and hence a fallback writer should be used). + +If a #GLogWriterFunc ignores a log entry, it should return +%G_LOG_WRITER_HANDLED. + + Log writer has handled the log entry. + + + Log writer could not handle the log entry. + + + + The major version number of the GLib library. + +Like #glib_major_version, but from the headers used at +application compile time, rather than from the library +linked against at application run time. + + + + The maximum value which can be held in a #gint16. + + + + The maximum value which can be held in a #gint32. + + + + The maximum value which can be held in a #gint64. + + + + The maximum value which can be held in a #gint8. + + + + The maximum value which can be held in a #guint16. + + + + The maximum value which can be held in a #guint32. + + + + The maximum value which can be held in a #guint64. + + + + The maximum value which can be held in a #guint8. + + + + The micro version number of the GLib library. + +Like #gtk_micro_version, but from the headers used at +application compile time, rather than from the library +linked against at application run time. + + + + The minimum value which can be held in a #gint16. + + + + The minimum value which can be held in a #gint32. + + + + The minimum value which can be held in a #gint64. + + + + The minimum value which can be held in a #gint8. + + + + The minor version number of the GLib library. + +Like #gtk_minor_version, but from the headers used at +application compile time, rather than from the library +linked against at application run time. + + + + + + + The `GMainContext` struct is an opaque data +type representing a set of sources to be handled in a main loop. + + Creates a new #GMainContext structure. + + the new #GMainContext + + + + + Tries to become the owner of the specified context. +If some other thread is the owner of the context, +returns %FALSE immediately. Ownership is properly +recursive: the owner can require ownership again +and will release ownership when g_main_context_release() +is called as many times as g_main_context_acquire(). + +You must be the owner of a context before you +can call g_main_context_prepare(), g_main_context_query(), +g_main_context_check(), g_main_context_dispatch(). + + %TRUE if the operation succeeded, and + this thread is now the owner of @context. + + + + + a #GMainContext + + + + + + Adds a file descriptor to the set of file descriptors polled for +this context. This will very seldom be used directly. Instead +a typical event source will use g_source_add_unix_fd() instead. + + + + + + a #GMainContext (or %NULL for the default context) + + + + a #GPollFD structure holding information about a file + descriptor to watch. + + + + the priority for this file descriptor which should be + the same as the priority used for g_source_attach() to ensure that the + file descriptor is polled whenever the results may be needed. + + + + + + Passes the results of polling back to the main loop. + +You must have successfully acquired the context with +g_main_context_acquire() before you may call this function. + + %TRUE if some sources are ready to be dispatched. + + + + + a #GMainContext + + + + the maximum numerical priority of sources to check + + + + array of #GPollFD's that was passed to + the last call to g_main_context_query() + + + + + + return value of g_main_context_query() + + + + + + Dispatches all pending sources. + +You must have successfully acquired the context with +g_main_context_acquire() before you may call this function. + + + + + + a #GMainContext + + + + + + Finds a source with the given source functions and user data. If +multiple sources exist with the same source function and user data, +the first one found will be returned. + + the source, if one was found, otherwise %NULL + + + + + a #GMainContext (if %NULL, the default context will be used). + + + + the @source_funcs passed to g_source_new(). + + + + the user data from the callback. + + + + + + Finds a #GSource given a pair of context and ID. + +It is a programmer error to attempt to lookup a non-existent source. + +More specifically: source IDs can be reissued after a source has been +destroyed and therefore it is never valid to use this function with a +source ID which may have already been removed. An example is when +scheduling an idle to run in another thread with g_idle_add(): the +idle may already have run and been removed by the time this function +is called on its (now invalid) source ID. This source ID may have +been reissued, leading to the operation being performed against the +wrong source. + + the #GSource + + + + + a #GMainContext (if %NULL, the default context will be used) + + + + the source ID, as returned by g_source_get_id(). + + + + + + Finds a source with the given user data for the callback. If +multiple sources exist with the same user data, the first +one found will be returned. + + the source, if one was found, otherwise %NULL + + + + + a #GMainContext + + + + the user_data for the callback. + + + + + + Gets the poll function set by g_main_context_set_poll_func(). + + the poll function + + + + + a #GMainContext + + + + + + Invokes a function in such a way that @context is owned during the +invocation of @function. + +If @context is %NULL then the global default main context — as +returned by g_main_context_default() — is used. + +If @context is owned by the current thread, @function is called +directly. Otherwise, if @context is the thread-default main context +of the current thread and g_main_context_acquire() succeeds, then +@function is called and g_main_context_release() is called +afterwards. + +In any other case, an idle source is created to call @function and +that source is attached to @context (presumably to be run in another +thread). The idle source is attached with #G_PRIORITY_DEFAULT +priority. If you want a different priority, use +g_main_context_invoke_full(). + +Note that, as with normal idle functions, @function should probably +return %FALSE. If it returns %TRUE, it will be continuously run in a +loop (and may prevent this call from returning). + + + + + + a #GMainContext, or %NULL + + + + function to call + + + + data to pass to @function + + + + + + Invokes a function in such a way that @context is owned during the +invocation of @function. + +This function is the same as g_main_context_invoke() except that it +lets you specify the priority incase @function ends up being +scheduled as an idle and also lets you give a #GDestroyNotify for @data. + +@notify should not assume that it is called from any particular +thread or with any particular context acquired. + + + + + + a #GMainContext, or %NULL + + + + the priority at which to run @function + + + + function to call + + + + data to pass to @function + + + + a function to call when @data is no longer in use, or %NULL. + + + + + + Determines whether this thread holds the (recursive) +ownership of this #GMainContext. This is useful to +know before waiting on another thread that may be +blocking to get ownership of @context. + + %TRUE if current thread is owner of @context. + + + + + a #GMainContext + + + + + + Runs a single iteration for the given main loop. This involves +checking to see if any event sources are ready to be processed, +then if no events sources are ready and @may_block is %TRUE, waiting +for a source to become ready, then dispatching the highest priority +events sources that are ready. Otherwise, if @may_block is %FALSE +sources are not waited to become ready, only those highest priority +events sources will be dispatched (if any), that are ready at this +given moment without further waiting. + +Note that even when @may_block is %TRUE, it is still possible for +g_main_context_iteration() to return %FALSE, since the wait may +be interrupted for other reasons than an event source becoming ready. + + %TRUE if events were dispatched. + + + + + a #GMainContext (if %NULL, the default context will be used) + + + + whether the call may block. + + + + + + Checks if any sources have pending events for the given context. + + %TRUE if events are pending. + + + + + a #GMainContext (if %NULL, the default context will be used) + + + + + + Pops @context off the thread-default context stack (verifying that +it was on the top of the stack). + + + + + + a #GMainContext object, or %NULL + + + + + + Prepares to poll sources within a main loop. The resulting information +for polling is determined by calling g_main_context_query (). + +You must have successfully acquired the context with +g_main_context_acquire() before you may call this function. + + %TRUE if some source is ready to be dispatched + prior to polling. + + + + + a #GMainContext + + + + location to store priority of highest priority + source already ready. + + + + + + Acquires @context and sets it as the thread-default context for the +current thread. This will cause certain asynchronous operations +(such as most [gio][gio]-based I/O) which are +started in this thread to run under @context and deliver their +results to its main loop, rather than running under the global +default context in the main thread. Note that calling this function +changes the context returned by g_main_context_get_thread_default(), +not the one returned by g_main_context_default(), so it does not affect +the context used by functions like g_idle_add(). + +Normally you would call this function shortly after creating a new +thread, passing it a #GMainContext which will be run by a +#GMainLoop in that thread, to set a new default context for all +async operations in that thread. In this case you may not need to +ever call g_main_context_pop_thread_default(), assuming you want the +new #GMainContext to be the default for the whole lifecycle of the +thread. + +If you don't have control over how the new thread was created (e.g. +in the new thread isn't newly created, or if the thread life +cycle is managed by a #GThreadPool), it is always suggested to wrap +the logic that needs to use the new #GMainContext inside a +g_main_context_push_thread_default() / g_main_context_pop_thread_default() +pair, otherwise threads that are re-used will end up never explicitly +releasing the #GMainContext reference they hold. + +In some cases you may want to schedule a single operation in a +non-default context, or temporarily use a non-default context in +the main thread. In that case, you can wrap the call to the +asynchronous operation inside a +g_main_context_push_thread_default() / +g_main_context_pop_thread_default() pair, but it is up to you to +ensure that no other asynchronous operations accidentally get +started while the non-default context is active. + +Beware that libraries that predate this function may not correctly +handle being used from a thread with a thread-default context. Eg, +see g_file_supports_thread_contexts(). + + + + + + a #GMainContext, or %NULL for the global default context + + + + + + Determines information necessary to poll this main loop. + +You must have successfully acquired the context with +g_main_context_acquire() before you may call this function. + + the number of records actually stored in @fds, + or, if more than @n_fds records need to be stored, the number + of records that need to be stored. + + + + + a #GMainContext + + + + maximum priority source to check + + + + location to store timeout to be used in polling + + + + location to + store #GPollFD records that need to be polled. + + + + + + length of @fds. + + + + + + Increases the reference count on a #GMainContext object by one. + + the @context that was passed in (since 2.6) + + + + + a #GMainContext + + + + + + Releases ownership of a context previously acquired by this thread +with g_main_context_acquire(). If the context was acquired multiple +times, the ownership will be released only when g_main_context_release() +is called as many times as it was acquired. + + + + + + a #GMainContext + + + + + + Removes file descriptor from the set of file descriptors to be +polled for a particular context. + + + + + + a #GMainContext + + + + a #GPollFD descriptor previously added with g_main_context_add_poll() + + + + + + Sets the function to use to handle polling of file descriptors. It +will be used instead of the poll() system call +(or GLib's replacement function, which is used where +poll() isn't available). + +This function could possibly be used to integrate the GLib event +loop with an external event loop. + + + + + + a #GMainContext + + + + the function to call to poll all file descriptors + + + + + + Decreases the reference count on a #GMainContext object by one. If +the result is zero, free the context and free all associated memory. + + + + + + a #GMainContext + + + + + + Tries to become the owner of the specified context, +as with g_main_context_acquire(). But if another thread +is the owner, atomically drop @mutex and wait on @cond until +that owner releases ownership or until @cond is signaled, then +try again (once) to become the owner. + + %TRUE if the operation succeeded, and + this thread is now the owner of @context. + + + + + a #GMainContext + + + + a condition variable + + + + a mutex, currently held + + + + + + If @context is currently blocking in g_main_context_iteration() +waiting for a source to become ready, cause it to stop blocking +and return. Otherwise, cause the next invocation of +g_main_context_iteration() to return without blocking. + +This API is useful for low-level control over #GMainContext; for +example, integrating it with main loop implementations such as +#GMainLoop. + +Another related use for this function is when implementing a main +loop with a termination condition, computed from multiple threads: + +|[<!-- language="C" --> + #define NUM_TASKS 10 + static volatile gint tasks_remaining = NUM_TASKS; + ... + + while (g_atomic_int_get (&tasks_remaining) != 0) + g_main_context_iteration (NULL, TRUE); +]| + +Then in a thread: +|[<!-- language="C" --> + perform_work(); + + if (g_atomic_int_dec_and_test (&tasks_remaining)) + g_main_context_wakeup (NULL); +]| + + + + + + a #GMainContext + + + + + + Returns the global default main context. This is the main context +used for main loop functions when a main loop is not explicitly +specified, and corresponds to the "main" main loop. See also +g_main_context_get_thread_default(). + + the global default main context. + + + + + Gets the thread-default #GMainContext for this thread. Asynchronous +operations that want to be able to be run in contexts other than +the default one should call this method or +g_main_context_ref_thread_default() to get a #GMainContext to add +their #GSources to. (Note that even in single-threaded +programs applications may sometimes want to temporarily push a +non-default context, so it is not safe to assume that this will +always return %NULL if you are running in the default thread.) + +If you need to hold a reference on the context, use +g_main_context_ref_thread_default() instead. + + the thread-default #GMainContext, or +%NULL if the thread-default context is the global default context. + + + + + Gets the thread-default #GMainContext for this thread, as with +g_main_context_get_thread_default(), but also adds a reference to +it with g_main_context_ref(). In addition, unlike +g_main_context_get_thread_default(), if the thread-default context +is the global default context, this will return that #GMainContext +(with a ref added to it) rather than returning %NULL. + + the thread-default #GMainContext. Unref + with g_main_context_unref() when you are done with it. + + + + + + The `GMainLoop` struct is an opaque data type +representing the main event loop of a GLib or GTK+ application. + + Creates a new #GMainLoop structure. + + a new #GMainLoop. + + + + + a #GMainContext (if %NULL, the default context will be used). + + + + set to %TRUE to indicate that the loop is running. This +is not very important since calling g_main_loop_run() will set this to +%TRUE anyway. + + + + + + Returns the #GMainContext of @loop. + + the #GMainContext of @loop + + + + + a #GMainLoop. + + + + + + Checks to see if the main loop is currently being run via g_main_loop_run(). + + %TRUE if the mainloop is currently being run. + + + + + a #GMainLoop. + + + + + + Stops a #GMainLoop from running. Any calls to g_main_loop_run() +for the loop will return. + +Note that sources that have already been dispatched when +g_main_loop_quit() is called will still be executed. + + + + + + a #GMainLoop + + + + + + Increases the reference count on a #GMainLoop object by one. + + @loop + + + + + a #GMainLoop + + + + + + Runs a main loop until g_main_loop_quit() is called on the loop. +If this is called for the thread of the loop's #GMainContext, +it will process events from the loop, otherwise it will +simply wait. + + + + + + a #GMainLoop + + + + + + Decreases the reference count on a #GMainLoop object by one. If +the result is zero, free the loop and free all associated memory. + + + + + + a #GMainLoop + + + + + + + The #GMappedFile represents a file mapping created with +g_mapped_file_new(). It has only private members and should +not be accessed directly. + + Maps a file into memory. On UNIX, this is using the mmap() function. + +If @writable is %TRUE, the mapped buffer may be modified, otherwise +it is an error to modify the mapped buffer. Modifications to the buffer +are not visible to other processes mapping the same file, and are not +written back to the file. + +Note that modifications of the underlying file might affect the contents +of the #GMappedFile. Therefore, mapping should only be used if the file +will not be modified, or if all modifications of the file are done +atomically (e.g. using g_file_set_contents()). + +If @filename is the name of an empty, regular file, the function +will successfully return an empty #GMappedFile. In other cases of +size 0 (e.g. device files such as /dev/null), @error will be set +to the #GFileError value #G_FILE_ERROR_INVAL. + + a newly allocated #GMappedFile which must be unref'd + with g_mapped_file_unref(), or %NULL if the mapping failed. + + + + + The path of the file to load, in the GLib + filename encoding + + + + whether the mapping should be writable + + + + + + Maps a file into memory. On UNIX, this is using the mmap() function. + +If @writable is %TRUE, the mapped buffer may be modified, otherwise +it is an error to modify the mapped buffer. Modifications to the buffer +are not visible to other processes mapping the same file, and are not +written back to the file. + +Note that modifications of the underlying file might affect the contents +of the #GMappedFile. Therefore, mapping should only be used if the file +will not be modified, or if all modifications of the file are done +atomically (e.g. using g_file_set_contents()). + + a newly allocated #GMappedFile which must be unref'd + with g_mapped_file_unref(), or %NULL if the mapping failed. + + + + + The file descriptor of the file to load + + + + whether the mapping should be writable + + + + + + This call existed before #GMappedFile had refcounting and is currently +exactly the same as g_mapped_file_unref(). + Use g_mapped_file_unref() instead. + + + + + + a #GMappedFile + + + + + + Creates a new #GBytes which references the data mapped from @file. +The mapped contents of the file must not be modified after creating this +bytes object, because a #GBytes should be immutable. + + A newly allocated #GBytes referencing data + from @file + + + + + a #GMappedFile + + + + + + Returns the contents of a #GMappedFile. + +Note that the contents may not be zero-terminated, +even if the #GMappedFile is backed by a text file. + +If the file is empty then %NULL is returned. + + the contents of @file, or %NULL. + + + + + a #GMappedFile + + + + + + Returns the length of the contents of a #GMappedFile. + + the length of the contents of @file. + + + + + a #GMappedFile + + + + + + Increments the reference count of @file by one. It is safe to call +this function from any thread. + + the passed in #GMappedFile. + + + + + a #GMappedFile + + + + + + Decrements the reference count of @file by one. If the reference count +drops to 0, unmaps the buffer of @file and frees it. + +It is safe to call this function from any thread. + +Since 2.22 + + + + + + a #GMappedFile + + + + + + + A mixed enumerated type and flags field. You must specify one type +(string, strdup, boolean, tristate). Additionally, you may optionally +bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL. + +It is likely that this enum will be extended in the future to +support other types. + + used to terminate the list of attributes + to collect + + + collect the string pointer directly from + the attribute_values[] array. Expects a parameter of type (const + char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the + attribute isn't present then the pointer will be set to %NULL + + + as with %G_MARKUP_COLLECT_STRING, but + expects a parameter of type (char **) and g_strdup()s the + returned pointer. The pointer must be freed with g_free() + + + expects a parameter of type (gboolean *) + and parses the attribute value as a boolean. Sets %FALSE if the + attribute isn't present. Valid boolean values consist of + (case-insensitive) "false", "f", "no", "n", "0" and "true", "t", + "yes", "y", "1" + + + as with %G_MARKUP_COLLECT_BOOLEAN, but + in the case of a missing attribute a value is set that compares + equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is + implied + + + can be bitwise ORed with the other fields. + If present, allows the attribute not to appear. A default value + is set depending on what value type is used + + + + Error codes returned by markup parsing. + + text being parsed was not valid UTF-8 + + + document contained nothing, or only whitespace + + + document was ill-formed + + + error should be set by #GMarkupParser + functions; element wasn't known + + + error should be set by #GMarkupParser + functions; attribute wasn't known + + + error should be set by #GMarkupParser + functions; content was invalid + + + error should be set by #GMarkupParser + functions; a required attribute was missing + + + + A parse context is used to parse a stream of bytes that +you expect to contain marked-up text. + +See g_markup_parse_context_new(), #GMarkupParser, and so +on for more details. + + Creates a new parse context. A parse context is used to parse +marked-up documents. You can feed any number of documents into +a context, as long as no errors occur; once an error occurs, +the parse context can't continue to parse text (you have to +free it and create a new parse context). + + a new #GMarkupParseContext + + + + + a #GMarkupParser + + + + one or more #GMarkupParseFlags + + + + user data to pass to #GMarkupParser functions + + + + user data destroy notifier called when + the parse context is freed + + + + + + Signals to the #GMarkupParseContext that all data has been +fed into the parse context with g_markup_parse_context_parse(). + +This function reports an error if the document isn't complete, +for example if elements are still open. + + %TRUE on success, %FALSE if an error was set + + + + + a #GMarkupParseContext + + + + + + Frees a #GMarkupParseContext. + +This function can't be called from inside one of the +#GMarkupParser functions or while a subparser is pushed. + + + + + + a #GMarkupParseContext + + + + + + Retrieves the name of the currently open element. + +If called from the start_element or end_element handlers this will +give the element_name as passed to those functions. For the parent +elements, see g_markup_parse_context_get_element_stack(). + + the name of the currently open element, or %NULL + + + + + a #GMarkupParseContext + + + + + + Retrieves the element stack from the internal state of the parser. + +The returned #GSList is a list of strings where the first item is +the currently open tag (as would be returned by +g_markup_parse_context_get_element()) and the next item is its +immediate parent. + +This function is intended to be used in the start_element and +end_element handlers where g_markup_parse_context_get_element() +would merely return the name of the element that is being +processed. + + the element stack, which must not be modified + + + + + + + a #GMarkupParseContext + + + + + + Retrieves the current line number and the number of the character on +that line. Intended for use in error messages; there are no strict +semantics for what constitutes the "current" line number other than +"the best number we could come up with for error messages." + + + + + + a #GMarkupParseContext + + + + return location for a line number, or %NULL + + + + return location for a char-on-line number, or %NULL + + + + + + Returns the user_data associated with @context. + +This will either be the user_data that was provided to +g_markup_parse_context_new() or to the most recent call +of g_markup_parse_context_push(). + + the provided user_data. The returned data belongs to + the markup context and will be freed when + g_markup_parse_context_free() is called. + + + + + a #GMarkupParseContext + + + + + + Feed some data to the #GMarkupParseContext. + +The data need not be valid UTF-8; an error will be signaled if +it's invalid. The data need not be an entire document; you can +feed a document into the parser incrementally, via multiple calls +to this function. Typically, as you receive data from a network +connection or file, you feed each received chunk of data into this +function, aborting the process if an error occurs. Once an error +is reported, no further data may be fed to the #GMarkupParseContext; +all errors are fatal. + + %FALSE if an error occurred, %TRUE on success + + + + + a #GMarkupParseContext + + + + chunk of text to parse + + + + length of @text in bytes + + + + + + Completes the process of a temporary sub-parser redirection. + +This function exists to collect the user_data allocated by a +matching call to g_markup_parse_context_push(). It must be called +in the end_element handler corresponding to the start_element +handler during which g_markup_parse_context_push() was called. +You must not call this function from the error callback -- the +@user_data is provided directly to the callback in that case. + +This function is not intended to be directly called by users +interested in invoking subparsers. Instead, it is intended to +be used by the subparsers themselves to implement a higher-level +interface. + + the user data passed to g_markup_parse_context_push() + + + + + a #GMarkupParseContext + + + + + + Temporarily redirects markup data to a sub-parser. + +This function may only be called from the start_element handler of +a #GMarkupParser. It must be matched with a corresponding call to +g_markup_parse_context_pop() in the matching end_element handler +(except in the case that the parser aborts due to an error). + +All tags, text and other data between the matching tags is +redirected to the subparser given by @parser. @user_data is used +as the user_data for that parser. @user_data is also passed to the +error callback in the event that an error occurs. This includes +errors that occur in subparsers of the subparser. + +The end tag matching the start tag for which this call was made is +handled by the previous parser (which is given its own user_data) +which is why g_markup_parse_context_pop() is provided to allow "one +last access" to the @user_data provided to this function. In the +case of error, the @user_data provided here is passed directly to +the error callback of the subparser and g_markup_parse_context_pop() +should not be called. In either case, if @user_data was allocated +then it ought to be freed from both of these locations. + +This function is not intended to be directly called by users +interested in invoking subparsers. Instead, it is intended to be +used by the subparsers themselves to implement a higher-level +interface. + +As an example, see the following implementation of a simple +parser that counts the number of tags encountered. + +|[<!-- language="C" --> +typedef struct +{ + gint tag_count; +} CounterData; + +static void +counter_start_element (GMarkupParseContext *context, + const gchar *element_name, + const gchar **attribute_names, + const gchar **attribute_values, + gpointer user_data, + GError **error) +{ + CounterData *data = user_data; + + data->tag_count++; +} + +static void +counter_error (GMarkupParseContext *context, + GError *error, + gpointer user_data) +{ + CounterData *data = user_data; + + g_slice_free (CounterData, data); +} + +static GMarkupParser counter_subparser = +{ + counter_start_element, + NULL, + NULL, + NULL, + counter_error +}; +]| + +In order to allow this parser to be easily used as a subparser, the +following interface is provided: + +|[<!-- language="C" --> +void +start_counting (GMarkupParseContext *context) +{ + CounterData *data = g_slice_new (CounterData); + + data->tag_count = 0; + g_markup_parse_context_push (context, &counter_subparser, data); +} + +gint +end_counting (GMarkupParseContext *context) +{ + CounterData *data = g_markup_parse_context_pop (context); + int result; + + result = data->tag_count; + g_slice_free (CounterData, data); + + return result; +} +]| + +The subparser would then be used as follows: + +|[<!-- language="C" --> +static void start_element (context, element_name, ...) +{ + if (strcmp (element_name, "count-these") == 0) + start_counting (context); + + // else, handle other tags... +} + +static void end_element (context, element_name, ...) +{ + if (strcmp (element_name, "count-these") == 0) + g_print ("Counted %d tags\n", end_counting (context)); + + // else, handle other tags... +} +]| + + + + + + a #GMarkupParseContext + + + + a #GMarkupParser + + + + user data to pass to #GMarkupParser functions + + + + + + Increases the reference count of @context. + + the same @context + + + + + a #GMarkupParseContext + + + + + + Decreases the reference count of @context. When its reference count +drops to 0, it is freed. + + + + + + a #GMarkupParseContext + + + + + + + Flags that affect the behaviour of the parser. + + flag you should not use + + + When this flag is set, CDATA marked + sections are not passed literally to the @passthrough function of + the parser. Instead, the content of the section (without the + `<![CDATA[` and `]]>`) is + passed to the @text function. This flag was added in GLib 2.12 + + + Normally errors caught by GMarkup + itself have line/column information prefixed to them to let the + caller know the location of the error. When this flag is set the + location information is also prefixed to errors generated by the + #GMarkupParser implementation functions + + + Ignore (don't report) qualified + attributes and tags, along with their contents. A qualified + attribute or tag is one that contains ':' in its name (ie: is in + another namespace). Since: 2.40. + + + + Any of the fields in #GMarkupParser can be %NULL, in which case they +will be ignored. Except for the @error function, any of these callbacks +can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT, +%G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT +errors are intended to be set from these callbacks. If you set an error +from a callback, g_markup_parse_context_parse() will report that error +back to its caller. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A GMatchInfo is an opaque struct used to return information about +matches. + + Returns a new string containing the text in @string_to_expand with +references and escape sequences expanded. References refer to the last +match done with @string against @regex and have the same syntax used by +g_regex_replace(). + +The @string_to_expand must be UTF-8 encoded even if #G_REGEX_RAW was +passed to g_regex_new(). + +The backreferences are extracted from the string passed to the match +function, so you cannot call this function after freeing the string. + +@match_info may be %NULL in which case @string_to_expand must not +contain references. For instance "foo\n" does not refer to an actual +pattern and '\n' merely will be replaced with \n character, +while to expand "\0" (whole match) one needs the result of a match. +Use g_regex_check_replacement() to find out whether @string_to_expand +contains references. + + the expanded string, or %NULL if an error occurred + + + + + a #GMatchInfo or %NULL + + + + the string to expand + + + + + + Retrieves the text matching the @match_num'th capturing +parentheses. 0 is the full text of the match, 1 is the first paren +set, 2 the second, and so on. + +If @match_num is a valid sub pattern but it didn't match anything +(e.g. sub pattern 1, matching "b" against "(a)?b") then an empty +string is returned. + +If the match was obtained using the DFA algorithm, that is using +g_regex_match_all() or g_regex_match_all_full(), the retrieved +string is not that of a set of parentheses but that of a matched +substring. Substrings are matched in reverse order of length, so +0 is the longest match. + +The string is fetched from the string passed to the match function, +so you cannot call this function after freeing the string. + + The matched substring, or %NULL if an error + occurred. You have to free the string yourself + + + + + #GMatchInfo structure + + + + number of the sub expression + + + + + + Bundles up pointers to each of the matching substrings from a match +and stores them in an array of gchar pointers. The first element in +the returned array is the match number 0, i.e. the entire matched +text. + +If a sub pattern didn't match anything (e.g. sub pattern 1, matching +"b" against "(a)?b") then an empty string is inserted. + +If the last match was obtained using the DFA algorithm, that is using +g_regex_match_all() or g_regex_match_all_full(), the retrieved +strings are not that matched by sets of parentheses but that of the +matched substring. Substrings are matched in reverse order of length, +so the first one is the longest match. + +The strings are fetched from the string passed to the match function, +so you cannot call this function after freeing the string. + + a %NULL-terminated array of gchar * + pointers. It must be freed using g_strfreev(). If the previous + match failed %NULL is returned + + + + + + + a #GMatchInfo structure + + + + + + Retrieves the text matching the capturing parentheses named @name. + +If @name is a valid sub pattern name but it didn't match anything +(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") +then an empty string is returned. + +The string is fetched from the string passed to the match function, +so you cannot call this function after freeing the string. + + The matched substring, or %NULL if an error + occurred. You have to free the string yourself + + + + + #GMatchInfo structure + + + + name of the subexpression + + + + + + Retrieves the position in bytes of the capturing parentheses named @name. + +If @name is a valid sub pattern name but it didn't match anything +(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") +then @start_pos and @end_pos are set to -1 and %TRUE is returned. + + %TRUE if the position was fetched, %FALSE otherwise. + If the position cannot be fetched, @start_pos and @end_pos + are left unchanged. + + + + + #GMatchInfo structure + + + + name of the subexpression + + + + pointer to location where to store + the start position, or %NULL + + + + pointer to location where to store + the end position, or %NULL + + + + + + Retrieves the position in bytes of the @match_num'th capturing +parentheses. 0 is the full text of the match, 1 is the first +paren set, 2 the second, and so on. + +If @match_num is a valid sub pattern but it didn't match anything +(e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos +and @end_pos are set to -1 and %TRUE is returned. + +If the match was obtained using the DFA algorithm, that is using +g_regex_match_all() or g_regex_match_all_full(), the retrieved +position is not that of a set of parentheses but that of a matched +substring. Substrings are matched in reverse order of length, so +0 is the longest match. + + %TRUE if the position was fetched, %FALSE otherwise. If + the position cannot be fetched, @start_pos and @end_pos are left + unchanged + + + + + #GMatchInfo structure + + + + number of the sub expression + + + + pointer to location where to store + the start position, or %NULL + + + + pointer to location where to store + the end position, or %NULL + + + + + + If @match_info is not %NULL, calls g_match_info_unref(); otherwise does +nothing. + + + + + + a #GMatchInfo, or %NULL + + + + + + Retrieves the number of matched substrings (including substring 0, +that is the whole matched text), so 1 is returned if the pattern +has no substrings in it and 0 is returned if the match failed. + +If the last match was obtained using the DFA algorithm, that is +using g_regex_match_all() or g_regex_match_all_full(), the retrieved +count is not that of the number of capturing parentheses but that of +the number of matched substrings. + + Number of matched substrings, or -1 if an error occurred + + + + + a #GMatchInfo structure + + + + + + Returns #GRegex object used in @match_info. It belongs to Glib +and must not be freed. Use g_regex_ref() if you need to keep it +after you free @match_info object. + + #GRegex object used in @match_info + + + + + a #GMatchInfo + + + + + + Returns the string searched with @match_info. This is the +string passed to g_regex_match() or g_regex_replace() so +you may not free it before calling this function. + + the string searched with @match_info + + + + + a #GMatchInfo + + + + + + Usually if the string passed to g_regex_match*() matches as far as +it goes, but is too short to match the entire pattern, %FALSE is +returned. There are circumstances where it might be helpful to +distinguish this case from other cases in which there is no match. + +Consider, for example, an application where a human is required to +type in data for a field with specific formatting requirements. An +example might be a date in the form ddmmmyy, defined by the pattern +"^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$". +If the application sees the user’s keystrokes one by one, and can +check that what has been typed so far is potentially valid, it is +able to raise an error as soon as a mistake is made. + +GRegex supports the concept of partial matching by means of the +#G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD flags. +When they are used, the return code for +g_regex_match() or g_regex_match_full() is, as usual, %TRUE +for a complete match, %FALSE otherwise. But, when these functions +return %FALSE, you can check if the match was partial calling +g_match_info_is_partial_match(). + +The difference between #G_REGEX_MATCH_PARTIAL_SOFT and +#G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered +with #G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a +possible complete match, while with #G_REGEX_MATCH_PARTIAL_HARD matching +stops at the partial match. +When both #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD +are set, the latter takes precedence. + +There were formerly some restrictions on the pattern for partial matching. +The restrictions no longer apply. + +See pcrepartial(3) for more information on partial matching. + + %TRUE if the match was partial, %FALSE otherwise + + + + + a #GMatchInfo structure + + + + + + Returns whether the previous match operation succeeded. + + %TRUE if the previous match operation succeeded, + %FALSE otherwise + + + + + a #GMatchInfo structure + + + + + + Scans for the next match using the same parameters of the previous +call to g_regex_match_full() or g_regex_match() that returned +@match_info. + +The match is done on the string passed to the match function, so you +cannot free it before calling this function. + + %TRUE is the string matched, %FALSE otherwise + + + + + a #GMatchInfo structure + + + + + + Increases reference count of @match_info by 1. + + @match_info + + + + + a #GMatchInfo + + + + + + Decreases reference count of @match_info by 1. When reference count drops +to zero, it frees all the memory associated with the match_info structure. + + + + + + a #GMatchInfo + + + + + + + A set of functions used to perform memory allocation. The same #GMemVTable must +be used for all allocations in the same program; a call to g_mem_set_vtable(), +if it exists, should be prior to any use of GLib. + +This functions related to this has been deprecated in 2.46, and no longer work. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The #GMutex struct is an opaque data structure to represent a mutex +(mutual exclusion). It can be used to protect data against shared +access. + +Take for example the following function: +|[<!-- language="C" --> + int + give_me_next_number (void) + { + static int current_number = 0; + + // now do a very complicated calculation to calculate the new + // number, this might for example be a random number generator + current_number = calc_next_number (current_number); + + return current_number; + } +]| +It is easy to see that this won't work in a multi-threaded +application. There current_number must be protected against shared +access. A #GMutex can be used as a solution to this problem: +|[<!-- language="C" --> + int + give_me_next_number (void) + { + static GMutex mutex; + static int current_number = 0; + int ret_val; + + g_mutex_lock (&mutex); + ret_val = current_number = calc_next_number (current_number); + g_mutex_unlock (&mutex); + + return ret_val; + } +]| +Notice that the #GMutex is not initialised to any particular value. +Its placement in static storage ensures that it will be initialised +to all-zeros, which is appropriate. + +If a #GMutex is placed in other contexts (eg: embedded in a struct) +then it must be explicitly initialised using g_mutex_init(). + +A #GMutex should only be accessed via g_mutex_ functions. + + + + + + + + + + Frees the resources allocated to a mutex with g_mutex_init(). + +This function should not be used with a #GMutex that has been +statically allocated. + +Calling g_mutex_clear() on a locked mutex leads to undefined +behaviour. + +Sine: 2.32 + + + + + + an initialized #GMutex + + + + + + Initializes a #GMutex so that it can be used. + +This function is useful to initialize a mutex that has been +allocated on the stack, or as part of a larger structure. +It is not necessary to initialize a mutex that has been +statically allocated. + +|[<!-- language="C" --> + typedef struct { + GMutex m; + ... + } Blob; + +Blob *b; + +b = g_new (Blob, 1); +g_mutex_init (&b->m); +]| + +To undo the effect of g_mutex_init() when a mutex is no longer +needed, use g_mutex_clear(). + +Calling g_mutex_init() on an already initialized #GMutex leads +to undefined behaviour. + + + + + + an uninitialized #GMutex + + + + + + Locks @mutex. If @mutex is already locked by another thread, the +current thread will block until @mutex is unlocked by the other +thread. + +#GMutex is neither guaranteed to be recursive nor to be +non-recursive. As such, calling g_mutex_lock() on a #GMutex that has +already been locked by the same thread results in undefined behaviour +(including but not limited to deadlocks). + + + + + + a #GMutex + + + + + + Tries to lock @mutex. If @mutex is already locked by another thread, +it immediately returns %FALSE. Otherwise it locks @mutex and returns +%TRUE. + +#GMutex is neither guaranteed to be recursive nor to be +non-recursive. As such, calling g_mutex_lock() on a #GMutex that has +already been locked by the same thread results in undefined behaviour +(including but not limited to deadlocks or arbitrary return values). + + %TRUE if @mutex could be locked + + + + + a #GMutex + + + + + + Unlocks @mutex. If another thread is blocked in a g_mutex_lock() +call for @mutex, it will become unblocked and can lock @mutex itself. + +Calling g_mutex_unlock() on a mutex that is not locked by the +current thread leads to undefined behaviour. + + + + + + a #GMutex + + + + + + + The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees]. + + contains the actual data of the node. + + + + points to the node's next sibling (a sibling is another + #GNode with the same parent). + + + + points to the node's previous sibling. + + + + points to the parent of the #GNode, or is %NULL if the + #GNode is the root of the tree. + + + + points to the first child of the #GNode. The other + children are accessed by using the @next pointer of each + child. + + + + Gets the position of the first child of a #GNode +which contains the given data. + + the index of the child of @node which contains + @data, or -1 if the data is not found + + + + + a #GNode + + + + the data to find + + + + + + Gets the position of a #GNode with respect to its siblings. +@child must be a child of @node. The first child is numbered 0, +the second 1, and so on. + + the position of @child with respect to its siblings + + + + + a #GNode + + + + a child of @node + + + + + + Calls a function for each of the children of a #GNode. +Note that it doesn't descend beneath the child nodes. + + + + + + a #GNode + + + + which types of children are to be visited, one of + %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + + + + the function to call for each visited node + + + + user data to pass to the function + + + + + + Recursively copies a #GNode (but does not deep-copy the data inside the +nodes, see g_node_copy_deep() if you need that). + + a new #GNode containing the same data pointers + + + + + a #GNode + + + + + + Recursively copies a #GNode and its data. + + a new #GNode containing copies of the data in @node. + + + + + a #GNode + + + + the function which is called to copy the data inside each node, + or %NULL to use the original data. + + + + data to pass to @copy_func + + + + + + Gets the depth of a #GNode. + +If @node is %NULL the depth is 0. The root node has a depth of 1. +For the children of the root node the depth is 2. And so on. + + the depth of the #GNode + + + + + a #GNode + + + + + + Removes @root and its children from the tree, freeing any memory +allocated. + + + + + + the root of the tree/subtree to destroy + + + + + + Finds a #GNode in a tree. + + the found #GNode, or %NULL if the data is not found + + + + + the root #GNode of the tree to search + + + + the order in which nodes are visited - %G_IN_ORDER, + %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER + + + + which types of children are to be searched, one of + %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + + + + the data to find + + + + + + Finds the first child of a #GNode with the given data. + + the found child #GNode, or %NULL if the data is not found + + + + + a #GNode + + + + which types of children are to be searched, one of + %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + + + + the data to find + + + + + + Gets the first sibling of a #GNode. +This could possibly be the node itself. + + the first sibling of @node + + + + + a #GNode + + + + + + Gets the root of a tree. + + the root of the tree + + + + + a #GNode + + + + + + Inserts a #GNode beneath the parent at the given position. + + the inserted #GNode + + + + + the #GNode to place @node under + + + + the position to place @node at, with respect to its siblings + If position is -1, @node is inserted as the last child of @parent + + + + the #GNode to insert + + + + + + Inserts a #GNode beneath the parent after the given sibling. + + the inserted #GNode + + + + + the #GNode to place @node under + + + + the sibling #GNode to place @node after. + If sibling is %NULL, the node is inserted as the first child of @parent. + + + + the #GNode to insert + + + + + + Inserts a #GNode beneath the parent before the given sibling. + + the inserted #GNode + + + + + the #GNode to place @node under + + + + the sibling #GNode to place @node before. + If sibling is %NULL, the node is inserted as the last child of @parent. + + + + the #GNode to insert + + + + + + Returns %TRUE if @node is an ancestor of @descendant. +This is true if node is the parent of @descendant, +or if node is the grandparent of @descendant etc. + + %TRUE if @node is an ancestor of @descendant + + + + + a #GNode + + + + a #GNode + + + + + + Gets the last child of a #GNode. + + the last child of @node, or %NULL if @node has no children + + + + + a #GNode (must not be %NULL) + + + + + + Gets the last sibling of a #GNode. +This could possibly be the node itself. + + the last sibling of @node + + + + + a #GNode + + + + + + Gets the maximum height of all branches beneath a #GNode. +This is the maximum distance from the #GNode to all leaf nodes. + +If @root is %NULL, 0 is returned. If @root has no children, +1 is returned. If @root has children, 2 is returned. And so on. + + the maximum height of the tree beneath @root + + + + + a #GNode + + + + + + Gets the number of children of a #GNode. + + the number of children of @node + + + + + a #GNode + + + + + + Gets the number of nodes in a tree. + + the number of nodes in the tree + + + + + a #GNode + + + + which types of children are to be counted, one of + %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + + + + + + Gets a child of a #GNode, using the given index. +The first child is at index 0. If the index is +too big, %NULL is returned. + + the child of @node at index @n + + + + + a #GNode + + + + the index of the desired child + + + + + + Inserts a #GNode as the first child of the given parent. + + the inserted #GNode + + + + + the #GNode to place the new #GNode under + + + + the #GNode to insert + + + + + + Reverses the order of the children of a #GNode. +(It doesn't change the order of the grandchildren.) + + + + + + a #GNode. + + + + + + Traverses a tree starting at the given root #GNode. +It calls the given function for each node visited. +The traversal can be halted at any point by returning %TRUE from @func. + + + + + + the root #GNode of the tree to traverse + + + + the order in which nodes are visited - %G_IN_ORDER, + %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER. + + + + which types of children are to be visited, one of + %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + + + + the maximum depth of the traversal. Nodes below this + depth will not be visited. If max_depth is -1 all nodes in + the tree are visited. If depth is 1, only the root is visited. + If depth is 2, the root and its children are visited. And so on. + + + + the function to call for each visited #GNode + + + + user data to pass to the function + + + + + + Unlinks a #GNode from a tree, resulting in two separate trees. + + + + + + the #GNode to unlink, which becomes the root of a new tree + + + + + + Creates a new #GNode containing the given data. +Used to create the first node in a tree. + + a new #GNode + + + + + the data of the new node + + + + + + + Specifies the type of function passed to g_node_children_foreach(). +The function is called with each child node, together with the user +data passed to g_node_children_foreach(). + + + + + + a #GNode. + + + + user data passed to g_node_children_foreach(). + + + + + + Specifies the type of function passed to g_node_traverse(). The +function is called with each of the nodes visited, together with the +user data passed to g_node_traverse(). If the function returns +%TRUE, then the traversal is stopped. + + %TRUE to stop the traversal. + + + + + a #GNode. + + + + user data passed to g_node_traverse(). + + + + + + Defines how a Unicode string is transformed in a canonical +form, standardizing such issues as whether a character with +an accent is represented as a base character and combining +accent or as a single precomposed character. Unicode strings +should generally be normalized before comparing them. + + standardize differences that do not affect the + text content, such as the above-mentioned accent representation + + + another name for %G_NORMALIZE_DEFAULT + + + like %G_NORMALIZE_DEFAULT, but with + composed forms rather than a maximally decomposed form + + + another name for %G_NORMALIZE_DEFAULT_COMPOSE + + + beyond %G_NORMALIZE_DEFAULT also standardize the + "compatibility" characters in Unicode, such as SUPERSCRIPT THREE + to the standard forms (in this case DIGIT THREE). Formatting + information may be lost but for most text operations such + characters should be considered the same + + + another name for %G_NORMALIZE_ALL + + + like %G_NORMALIZE_ALL, but with composed + forms rather than a maximally decomposed form + + + another name for %G_NORMALIZE_ALL_COMPOSE + + + + If a long option in the main group has this name, it is not treated as a +regular option. Instead it collects all non-option arguments which would +otherwise be left in `argv`. The option must be of type +%G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY +or %G_OPTION_ARG_FILENAME_ARRAY. + + +Using #G_OPTION_REMAINING instead of simply scanning `argv` +for leftover arguments has the advantage that GOption takes care of +necessary encoding conversions for strings or filenames. + + + + A #GOnce struct controls a one-time initialization function. Any +one-time initialization function must have its own unique #GOnce +struct. + + the status of the #GOnce + + + + the value returned by the call to the function, if @status + is %G_ONCE_STATUS_READY + + + + + + + + + + + + + + + + + + + + Function to be called when starting a critical initialization +section. The argument @location must point to a static +0-initialized variable that will be set to a value other than 0 at +the end of the initialization section. In combination with +g_once_init_leave() and the unique address @value_location, it can +be ensured that an initialization section will be executed only once +during a program's life time, and that concurrent threads are +blocked until initialization completed. To be used in constructs +like this: + +|[<!-- language="C" --> + static gsize initialization_value = 0; + + if (g_once_init_enter (&initialization_value)) + { + gsize setup_value = 42; // initialization code here + + g_once_init_leave (&initialization_value, setup_value); + } + + // use initialization_value here +]| + + %TRUE if the initialization section should be entered, + %FALSE and blocks otherwise + + + + + location of a static initializable variable + containing 0 + + + + + + Counterpart to g_once_init_enter(). Expects a location of a static +0-initialized initialization variable, and an initialization value +other than 0. Sets the variable to the initialization value, and +releases concurrent threads blocking in g_once_init_enter() on this +initialization variable. + + + + + + location of a static initializable variable + containing 0 + + + + new non-0 value for *@value_location + + + + + + + The possible statuses of a one-time initialization function +controlled by a #GOnce struct. + + the function has not been called yet. + + + the function call is currently in progress. + + + the function has been called. + + + + The #GOptionArg enum values determine which type of extra argument the +options expect to find. If an option expects an extra argument, it can +be specified in several ways; with a short option: `-x arg`, with a long +option: `--name arg` or combined in a single argument: `--name=arg`. + + No extra argument. This is useful for simple flags. + + + The option takes a string argument. + + + The option takes an integer argument. + + + The option provides a callback (of type + #GOptionArgFunc) to parse the extra argument. + + + The option takes a filename as argument. + + + The option takes a string argument, multiple + uses of the option are collected into an array of strings. + + + The option takes a filename as argument, + multiple uses of the option are collected into an array of strings. + + + The option takes a double argument. The argument + can be formatted either for the user's locale or for the "C" locale. + Since 2.12 + + + The option takes a 64-bit integer. Like + %G_OPTION_ARG_INT but for larger numbers. The number can be in + decimal base, or in hexadecimal (when prefixed with `0x`, for + example, `0xffffffff`). Since 2.12 + + + + The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK +options. + + %TRUE if the option was successfully parsed, %FALSE if an error + occurred, in which case @error should be set with g_set_error() + + + + + The name of the option being parsed. This will be either a + single dash followed by a single letter (for a short name) or two dashes + followed by a long option name. + + + + The value to be parsed. + + + + User data added to the #GOptionGroup containing the option when it + was created with g_option_group_new() + + + + + + A `GOptionContext` struct defines which options +are accepted by the commandline option parser. The struct has only private +fields and should not be directly accessed. + + Adds a #GOptionGroup to the @context, so that parsing with @context +will recognize the options in the group. Note that this will take +ownership of the @group and thus the @group should not be freed. + + + + + + a #GOptionContext + + + + the group to add + + + + + + A convenience function which creates a main group if it doesn't +exist, adds the @entries to it and sets the translation domain. + + + + + + a #GOptionContext + + + + a %NULL-terminated array of #GOptionEntrys + + + + a translation domain to use for translating + the `--help` output for the options in @entries + with gettext(), or %NULL + + + + + + Frees context and all the groups which have been +added to it. + +Please note that parsed arguments need to be freed separately (see +#GOptionEntry). + + + + + + a #GOptionContext + + + + + + Returns the description. See g_option_context_set_description(). + + the description + + + + + a #GOptionContext + + + + + + Returns a formatted, translated help text for the given context. +To obtain the text produced by `--help`, call +`g_option_context_get_help (context, TRUE, NULL)`. +To obtain the text produced by `--help-all`, call +`g_option_context_get_help (context, FALSE, NULL)`. +To obtain the help text for an option group, call +`g_option_context_get_help (context, FALSE, group)`. + + A newly allocated string containing the help text + + + + + a #GOptionContext + + + + if %TRUE, only include the main group + + + + the #GOptionGroup to create help for, or %NULL + + + + + + Returns whether automatic `--help` generation +is turned on for @context. See g_option_context_set_help_enabled(). + + %TRUE if automatic help generation is turned on. + + + + + a #GOptionContext + + + + + + Returns whether unknown options are ignored or not. See +g_option_context_set_ignore_unknown_options(). + + %TRUE if unknown options are ignored. + + + + + a #GOptionContext + + + + + + Returns a pointer to the main group of @context. + + the main group of @context, or %NULL if + @context doesn't have a main group. Note that group belongs to + @context and should not be modified or freed. + + + + + a #GOptionContext + + + + + + Returns whether strict POSIX code is enabled. + +See g_option_context_set_strict_posix() for more information. + + %TRUE if strict POSIX is enabled, %FALSE otherwise. + + + + + a #GoptionContext + + + + + + Returns the summary. See g_option_context_set_summary(). + + the summary + + + + + a #GOptionContext + + + + + + Parses the command line arguments, recognizing options +which have been added to @context. A side-effect of +calling this function is that g_set_prgname() will be +called. + +If the parsing is successful, any parsed arguments are +removed from the array and @argc and @argv are updated +accordingly. A '--' option is stripped from @argv +unless there are unparsed options before and after it, +or some of the options after it start with '-'. In case +of an error, @argc and @argv are left unmodified. + +If automatic `--help` support is enabled +(see g_option_context_set_help_enabled()), and the +@argv array contains one of the recognized help options, +this function will produce help output to stdout and +call `exit (0)`. + +Note that function depends on the [current locale][setlocale] for +automatic character set conversion of string and filename +arguments. + + %TRUE if the parsing was successful, + %FALSE if an error occurred + + + + + a #GOptionContext + + + + a pointer to the number of command line arguments + + + + a pointer to the array of command line arguments + + + + + + + + Parses the command line arguments. + +This function is similar to g_option_context_parse() except that it +respects the normal memory rules when dealing with a strv instead of +assuming that the passed-in array is the argv of the main function. + +In particular, strings that are removed from the arguments list will +be freed using g_free(). + +On Windows, the strings are expected to be in UTF-8. This is in +contrast to g_option_context_parse() which expects them to be in the +system codepage, which is how they are passed as @argv to main(). +See g_win32_get_command_line() for a solution. + +This function is useful if you are trying to use #GOptionContext with +#GApplication. + + %TRUE if the parsing was successful, + %FALSE if an error occurred + + + + + a #GOptionContext + + + + a pointer to the + command line arguments (which must be in UTF-8 on Windows) + + + + + + + + Adds a string to be displayed in `--help` output after the list +of options. This text often includes a bug reporting address. + +Note that the summary is translated (see +g_option_context_set_translate_func()). + + + + + + a #GOptionContext + + + + a string to be shown in `--help` output + after the list of options, or %NULL + + + + + + Enables or disables automatic generation of `--help` output. +By default, g_option_context_parse() recognizes `--help`, `-h`, +`-?`, `--help-all` and `--help-groupname` and creates suitable +output to stdout. + + + + + + a #GOptionContext + + + + %TRUE to enable `--help`, %FALSE to disable it + + + + + + Sets whether to ignore unknown options or not. If an argument is +ignored, it is left in the @argv array after parsing. By default, +g_option_context_parse() treats unknown options as error. + +This setting does not affect non-option arguments (i.e. arguments +which don't start with a dash). But note that GOption cannot reliably +determine whether a non-option belongs to a preceding unknown option. + + + + + + a #GOptionContext + + + + %TRUE to ignore unknown options, %FALSE to produce + an error when unknown options are met + + + + + + Sets a #GOptionGroup as main group of the @context. +This has the same effect as calling g_option_context_add_group(), +the only difference is that the options in the main group are +treated differently when generating `--help` output. + + + + + + a #GOptionContext + + + + the group to set as main group + + + + + + Sets strict POSIX mode. + +By default, this mode is disabled. + +In strict POSIX mode, the first non-argument parameter encountered +(eg: filename) terminates argument processing. Remaining arguments +are treated as non-options and are not attempted to be parsed. + +If strict POSIX mode is disabled then parsing is done in the GNU way +where option arguments can be freely mixed with non-options. + +As an example, consider "ls foo -l". With GNU style parsing, this +will list "foo" in long mode. In strict POSIX style, this will list +the files named "foo" and "-l". + +It may be useful to force strict POSIX mode when creating "verb +style" command line tools. For example, the "gsettings" command line +tool supports the global option "--schemadir" as well as many +subcommands ("get", "set", etc.) which each have their own set of +arguments. Using strict POSIX mode will allow parsing the global +options up to the verb name while leaving the remaining options to be +parsed by the relevant subcommand (which can be determined by +examining the verb name, which should be present in argv[1] after +parsing). + + + + + + a #GoptionContext + + + + the new value + + + + + + Adds a string to be displayed in `--help` output before the list +of options. This is typically a summary of the program functionality. + +Note that the summary is translated (see +g_option_context_set_translate_func() and +g_option_context_set_translation_domain()). + + + + + + a #GOptionContext + + + + a string to be shown in `--help` output + before the list of options, or %NULL + + + + + + Sets the function which is used to translate the contexts +user-visible strings, for `--help` output. If @func is %NULL, +strings are not translated. + +Note that option groups have their own translation functions, +this function only affects the @parameter_string (see g_option_context_new()), +the summary (see g_option_context_set_summary()) and the description +(see g_option_context_set_description()). + +If you are using gettext(), you only need to set the translation +domain, see g_option_context_set_translation_domain(). + + + + + + a #GOptionContext + + + + the #GTranslateFunc, or %NULL + + + + user data to pass to @func, or %NULL + + + + a function which gets called to free @data, or %NULL + + + + + + A convenience function to use gettext() for translating +user-visible strings. + + + + + + a #GOptionContext + + + + the domain to use + + + + + + Creates a new option context. + +The @parameter_string can serve multiple purposes. It can be used +to add descriptions for "rest" arguments, which are not parsed by +the #GOptionContext, typically something like "FILES" or +"FILE1 FILE2...". If you are using #G_OPTION_REMAINING for +collecting "rest" arguments, GLib handles this automatically by +using the @arg_description of the corresponding #GOptionEntry in +the usage summary. + +Another usage is to give a short summary of the program +functionality, like " - frob the strings", which will be displayed +in the same line as the usage. For a longer description of the +program functionality that should be displayed as a paragraph +below the usage line, use g_option_context_set_summary(). + +Note that the @parameter_string is translated using the +function set with g_option_context_set_translate_func(), so +it should normally be passed untranslated. + + a newly created #GOptionContext, which must be + freed with g_option_context_free() after use. + + + + + a string which is displayed in + the first line of `--help` output, after the usage summary + `programname [OPTION...]` + + + + + + + A GOptionEntry struct defines a single option. To have an effect, they +must be added to a #GOptionGroup with g_option_context_add_main_entries() +or g_option_group_add_entries(). + + The long name of an option can be used to specify it + in a commandline as `--long_name`. Every option must have a + long name. To resolve conflicts if multiple option groups contain + the same long name, it is also possible to specify the option as + `--groupname-long_name`. + + + + If an option has a short name, it can be specified + `-short_name` in a commandline. @short_name must be a printable + ASCII character different from '-', or zero if the option has no + short name. + + + + Flags from #GOptionFlags + + + + The type of the option, as a #GOptionArg + + + + If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data + must point to a #GOptionArgFunc callback function, which will be + called to handle the extra argument. Otherwise, @arg_data is a + pointer to a location to store the value, the required type of + the location depends on the @arg type: + - %G_OPTION_ARG_NONE: %gboolean + - %G_OPTION_ARG_STRING: %gchar* + - %G_OPTION_ARG_INT: %gint + - %G_OPTION_ARG_FILENAME: %gchar* + - %G_OPTION_ARG_STRING_ARRAY: %gchar** + - %G_OPTION_ARG_FILENAME_ARRAY: %gchar** + - %G_OPTION_ARG_DOUBLE: %gdouble + If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME, + the location will contain a newly allocated string if the option + was given. That string needs to be freed by the callee using g_free(). + Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or + %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). + + + + the description for the option in `--help` + output. The @description is translated using the @translate_func + of the group, see g_option_group_set_translation_domain(). + + + + The placeholder to use for the extra argument parsed + by the option in `--help` output. The @arg_description is translated + using the @translate_func of the group, see + g_option_group_set_translation_domain(). + + + + + Error codes returned by option parsing. + + An option was not known to the parser. + This error will only be reported, if the parser hasn't been instructed + to ignore unknown options, see g_option_context_set_ignore_unknown_options(). + + + A value couldn't be parsed. + + + A #GOptionArgFunc callback failed. + + + + The type of function to be used as callback when a parse error occurs. + + + + + + The active #GOptionContext + + + + The group to which the function belongs + + + + User data added to the #GOptionGroup containing the option when it + was created with g_option_group_new() + + + + + + Flags which modify individual options. + + No flags. Since: 2.42. + + + The option doesn't appear in `--help` output. + + + The option appears in the main section of the + `--help` output, even if it is defined in a group. + + + For options of the %G_OPTION_ARG_NONE kind, this + flag indicates that the sense of the option is reversed. + + + For options of the %G_OPTION_ARG_CALLBACK kind, + this flag indicates that the callback does not take any argument + (like a %G_OPTION_ARG_NONE option). Since 2.8 + + + For options of the %G_OPTION_ARG_CALLBACK + kind, this flag indicates that the argument should be passed to the + callback in the GLib filename encoding rather than UTF-8. Since 2.8 + + + For options of the %G_OPTION_ARG_CALLBACK + kind, this flag indicates that the argument supply is optional. + If no argument is given then data of %GOptionParseFunc will be + set to NULL. Since 2.8 + + + This flag turns off the automatic conflict + resolution which prefixes long option names with `groupname-` if + there is a conflict. This option should only be used in situations + where aliasing is necessary to model some legacy commandline interface. + It is not safe to use this option, unless all option groups are under + your direct control. Since 2.8. + + + + A `GOptionGroup` struct defines the options in a single +group. The struct has only private fields and should not be directly accessed. + +All options in a group share the same translation function. Libraries which +need to parse commandline options are expected to provide a function for +getting a `GOptionGroup` holding their options, which +the application can then add to its #GOptionContext. + + Creates a new #GOptionGroup. + + a newly created option group. It should be added + to a #GOptionContext or freed with g_option_group_unref(). + + + + + the name for the option group, this is used to provide + help for the options in this group with `--help-`@name + + + + a description for this group to be shown in + `--help`. This string is translated using the translation + domain or translation function of the group + + + + a description for the `--help-`@name option. + This string is translated using the translation domain or translation function + of the group + + + + user data that will be passed to the pre- and post-parse hooks, + the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL + + + + a function that will be called to free @user_data, or %NULL + + + + + + Adds the options specified in @entries to @group. + + + + + + a #GOptionGroup + + + + a %NULL-terminated array of #GOptionEntrys + + + + + + Frees a #GOptionGroup. Note that you must not free groups +which have been added to a #GOptionContext. + Use g_option_group_unref() instead. + + + + + + a #GOptionGroup + + + + + + Increments the reference count of @group by one. + + a #GoptionGroup + + + + + a #GOptionGroup + + + + + + Associates a function with @group which will be called +from g_option_context_parse() when an error occurs. + +Note that the user data to be passed to @error_func can be +specified when constructing the group with g_option_group_new(). + + + + + + a #GOptionGroup + + + + a function to call when an error occurs + + + + + + Associates two functions with @group which will be called +from g_option_context_parse() before the first option is parsed +and after the last option has been parsed, respectively. + +Note that the user data to be passed to @pre_parse_func and +@post_parse_func can be specified when constructing the group +with g_option_group_new(). + + + + + + a #GOptionGroup + + + + a function to call before parsing, or %NULL + + + + a function to call after parsing, or %NULL + + + + + + Sets the function which is used to translate user-visible strings, +for `--help` output. Different groups can use different +#GTranslateFuncs. If @func is %NULL, strings are not translated. + +If you are using gettext(), you only need to set the translation +domain, see g_option_group_set_translation_domain(). + + + + + + a #GOptionGroup + + + + the #GTranslateFunc, or %NULL + + + + user data to pass to @func, or %NULL + + + + a function which gets called to free @data, or %NULL + + + + + + A convenience function to use gettext() for translating +user-visible strings. + + + + + + a #GOptionGroup + + + + the domain to use + + + + + + Decrements the reference count of @group by one. +If the reference count drops to 0, the @group will be freed. +and all memory allocated by the @group is released. + + + + + + a #GOptionGroup + + + + + + + The type of function that can be called before and after parsing. + + %TRUE if the function completed successfully, %FALSE if an error + occurred, in which case @error should be set with g_set_error() + + + + + The active #GOptionContext + + + + The group to which the function belongs + + + + User data added to the #GOptionGroup containing the option when it + was created with g_option_group_new() + + + + + + Specifies one of the possible types of byte order +(currently unused). See #G_BYTE_ORDER. + + + + The value of pi (ratio of circle's circumference to its diameter). + + + + A format specifier that can be used in printf()-style format strings +when printing a #GPid. + + + + Pi divided by 2. + + + + Pi divided by 4. + + + + A format specifier that can be used in printf()-style format strings +when printing the @fd member of a #GPollFD. + + + + Use this for default priority event sources. + +In GLib this priority is used when adding timeout functions +with g_timeout_add(). In GDK this priority is used for events +from the X server. + + + + Use this for default priority idle functions. + +In GLib this priority is used when adding idle functions with +g_idle_add(). + + + + Use this for high priority event sources. + +It is not used within GLib or GTK+. + + + + Use this for high priority idle functions. + +GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, +and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is +done to ensure that any pending resizes are processed before any +pending redraws, so that widgets are not redrawn twice unnecessarily.) + + + + Use this for very low priority background tasks. + +It is not used within GLib or GTK+. + + + + A GPatternSpec struct is the 'compiled' form of a pattern. This +structure is opaque and its fields cannot be accessed directly. + + Compares two compiled pattern specs and returns whether they will +match the same set of strings. + + Whether the compiled patterns are equal + + + + + a #GPatternSpec + + + + another #GPatternSpec + + + + + + Frees the memory allocated for the #GPatternSpec. + + + + + + a #GPatternSpec + + + + + + Compiles a pattern to a #GPatternSpec. + + a newly-allocated #GPatternSpec + + + + + a zero-terminated UTF-8 encoded string + + + + + + + Represents a file descriptor, which events to poll for, and which events +occurred. + + the file descriptor to poll (or a HANDLE on Win32) + + + + a bitwise combination from #GIOCondition, specifying which + events should be polled for. Typically for reading from a file + descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and + for writing you would use %G_IO_OUT | %G_IO_ERR. + + + + a bitwise combination of flags from #GIOCondition, returned + from the poll() function to indicate which events occurred. + + + + + Specifies the type of function passed to g_main_context_set_poll_func(). +The semantics of the function should match those of the poll() system call. + + the number of #GPollFD elements which have events or errors + reported, or -1 if an error occurred. + + + + + an array of #GPollFD elements + + + + the number of elements in @ufds + + + + the maximum time to wait for an event of the file descriptors. + A negative value indicates an infinite timeout. + + + + + + Specifies the type of the print handler functions. +These are called with the complete formatted string to output. + + + + + + the message to output + + + + + + The #GPrivate struct is an opaque data structure to represent a +thread-local data key. It is approximately equivalent to the +pthread_setspecific()/pthread_getspecific() APIs on POSIX and to +TlsSetValue()/TlsGetValue() on Windows. + +If you don't already know why you might want this functionality, +then you probably don't need it. + +#GPrivate is a very limited resource (as far as 128 per program, +shared between all libraries). It is also not possible to destroy a +#GPrivate after it has been used. As such, it is only ever acceptable +to use #GPrivate in static scope, and even then sparingly so. + +See G_PRIVATE_INIT() for a couple of examples. + +The #GPrivate structure should be considered opaque. It should only +be accessed via the g_private_ functions. + + + + + + + + + + + + + Returns the current value of the thread local variable @key. + +If the value has not yet been set in this thread, %NULL is returned. +Values are never copied between threads (when a new thread is +created, for example). + + the thread-local value + + + + + a #GPrivate + + + + + + Sets the thread local variable @key to have the value @value in the +current thread. + +This function differs from g_private_set() in the following way: if +the previous value was non-%NULL then the #GDestroyNotify handler for +@key is run on it. + + + + + + a #GPrivate + + + + the new value + + + + + + Sets the thread local variable @key to have the value @value in the +current thread. + +This function differs from g_private_replace() in the following way: +the #GDestroyNotify for @key is not called on the old value. + + + + + + a #GPrivate + + + + the new value + + + + + + + Contains the public fields of a pointer array. + + points to the array of pointers, which may be moved when the + array grows + + + + number of pointers in the array + + + + Adds a pointer to the end of the pointer array. The array will grow +in size automatically if necessary. + + + + + + a #GPtrArray + + + + + + the pointer to add + + + + + + Calls a function for each element of a #GPtrArray. + + + + + + a #GPtrArray + + + + + + the function to call for each array element + + + + user data to pass to the function + + + + + + Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE +it frees the memory block holding the elements as well. Pass %FALSE +if you want to free the #GPtrArray wrapper but preserve the +underlying array for use elsewhere. If the reference count of @array +is greater than one, the #GPtrArray wrapper is preserved but the +size of @array will be set to zero. + +If array contents point to dynamically-allocated memory, they should +be freed separately if @free_seg is %TRUE and no #GDestroyNotify +function has been set for @array. + + the pointer array if @free_seg is %FALSE, otherwise %NULL. + The pointer array should be freed using g_free(). + + + + + a #GPtrArray + + + + + + if %TRUE the actual pointer array is freed as well + + + + + + Inserts an element into the pointer array at the given index. The +array will grow in size automatically if necessary. + + + + + + a #GPtrArray + + + + + + the index to place the new element at, or -1 to append + + + + the pointer to add. + + + + + + Creates a new #GPtrArray with a reference count of 1. + + the new #GPtrArray + + + + + + + Creates a new #GPtrArray with @reserved_size pointers preallocated +and a reference count of 1. This avoids frequent reallocation, if +you are going to add many pointers to the array. Note however that +the size of the array is still 0. It also set @element_free_func +for freeing each element when the array is destroyed either via +g_ptr_array_unref(), when g_ptr_array_free() is called with +@free_segment set to %TRUE or when removing elements. + + A new #GPtrArray + + + + + + + number of pointers preallocated + + + + A function to free elements with + destroy @array or %NULL + + + + + + Creates a new #GPtrArray with a reference count of 1 and use +@element_free_func for freeing each element when the array is destroyed +either via g_ptr_array_unref(), when g_ptr_array_free() is called with +@free_segment set to %TRUE or when removing elements. + + A new #GPtrArray + + + + + + + A function to free elements with + destroy @array or %NULL + + + + + + Atomically increments the reference count of @array by one. +This function is thread-safe and may be called from any thread. + + The passed in #GPtrArray + + + + + + + a #GPtrArray + + + + + + + + Removes the first occurrence of the given pointer from the pointer +array. The following elements are moved down one place. If @array +has a non-%NULL #GDestroyNotify function it is called for the +removed element. + +It returns %TRUE if the pointer was removed, or %FALSE if the +pointer was not found. + + %TRUE if the pointer is removed, %FALSE if the pointer + is not found in the array + + + + + a #GPtrArray + + + + + + the pointer to remove + + + + + + Removes the first occurrence of the given pointer from the pointer +array. The last element in the array is used to fill in the space, +so this function does not preserve the order of the array. But it +is faster than g_ptr_array_remove(). If @array has a non-%NULL +#GDestroyNotify function it is called for the removed element. + +It returns %TRUE if the pointer was removed, or %FALSE if the +pointer was not found. + + %TRUE if the pointer was found in the array + + + + + a #GPtrArray + + + + + + the pointer to remove + + + + + + Removes the pointer at the given index from the pointer array. +The following elements are moved down one place. If @array has +a non-%NULL #GDestroyNotify function it is called for the removed +element. + + the pointer which was removed + + + + + a #GPtrArray + + + + + + the index of the pointer to remove + + + + + + Removes the pointer at the given index from the pointer array. +The last element in the array is used to fill in the space, so +this function does not preserve the order of the array. But it +is faster than g_ptr_array_remove_index(). If @array has a non-%NULL +#GDestroyNotify function it is called for the removed element. + + the pointer which was removed + + + + + a #GPtrArray + + + + + + the index of the pointer to remove + + + + + + Removes the given number of pointers starting at the given index +from a #GPtrArray. The following elements are moved to close the +gap. If @array has a non-%NULL #GDestroyNotify function it is +called for the removed elements. + + the @array + + + + + + + a @GPtrArray + + + + + + the index of the first pointer to remove + + + + the number of pointers to remove + + + + + + Sets a function for freeing each element when @array is destroyed +either via g_ptr_array_unref(), when g_ptr_array_free() is called +with @free_segment set to %TRUE or when removing elements. + + + + + + A #GPtrArray + + + + + + A function to free elements with + destroy @array or %NULL + + + + + + Sets the size of the array. When making the array larger, +newly-added elements will be set to %NULL. When making it smaller, +if @array has a non-%NULL #GDestroyNotify function then it will be +called for the removed elements. + + + + + + a #GPtrArray + + + + + + the new length of the pointer array + + + + + + Creates a new #GPtrArray with @reserved_size pointers preallocated +and a reference count of 1. This avoids frequent reallocation, if +you are going to add many pointers to the array. Note however that +the size of the array is still 0. + + the new #GPtrArray + + + + + + + number of pointers preallocated + + + + + + Sorts the array, using @compare_func which should be a qsort()-style +comparison function (returns less than zero for first arg is less +than second arg, zero for equal, greater than zero if irst arg is +greater than second arg). + +Note that the comparison function for g_ptr_array_sort() doesn't +take the pointers from the array as arguments, it takes pointers to +the pointers in the array. + +This is guaranteed to be a stable sort since version 2.32. + + + + + + a #GPtrArray + + + + + + comparison function + + + + + + Like g_ptr_array_sort(), but the comparison function has an extra +user data argument. + +Note that the comparison function for g_ptr_array_sort_with_data() +doesn't take the pointers from the array as arguments, it takes +pointers to the pointers in the array. + +This is guaranteed to be a stable sort since version 2.32. + + + + + + a #GPtrArray + + + + + + comparison function + + + + data to pass to @compare_func + + + + + + Atomically decrements the reference count of @array by one. If the +reference count drops to 0, the effect is the same as calling +g_ptr_array_free() with @free_segment set to %TRUE. This function +is MT-safe and may be called from any thread. + + + + + + A #GPtrArray + + + + + + + + + Contains the public fields of a +[Queue][glib-Double-ended-Queues]. + + a pointer to the first element of the queue + + + + + + a pointer to the last element of the queue + + + + + + the number of elements in the queue + + + + Removes all the elements in @queue. If queue elements contain +dynamically-allocated memory, they should be freed first. + + + + + + a #GQueue + + + + + + Copies a @queue. Note that is a shallow copy. If the elements in the +queue consist of pointers to data, the pointers are copied, but the +actual data is not. + + a copy of @queue + + + + + a #GQueue + + + + + + Removes @link_ from @queue and frees it. + +@link_ must be part of @queue. + + + + + + a #GQueue + + + + a #GList link that must be part of @queue + + + + + + + + Finds the first link in @queue which contains @data. + + the first link in @queue which contains @data + + + + + + + a #GQueue + + + + data to find + + + + + + Finds an element in a #GQueue, using a supplied function to find the +desired element. It iterates over the queue, calling the given function +which should return 0 when the desired element is found. The function +takes two gconstpointer arguments, the #GQueue element's data as the +first argument and the given user data as the second argument. + + the found link, or %NULL if it wasn't found + + + + + + + a #GQueue + + + + user data passed to @func + + + + a #GCompareFunc to call for each element. It should return 0 + when the desired element is found + + + + + + Calls @func for each element in the queue passing @user_data to the +function. + + + + + + a #GQueue + + + + the function to call for each element's data + + + + user data to pass to @func + + + + + + Frees the memory allocated for the #GQueue. Only call this function +if @queue was created with g_queue_new(). If queue elements contain +dynamically-allocated memory, they should be freed first. + +If queue elements contain dynamically-allocated memory, you should +either use g_queue_free_full() or free them manually first. + + + + + + a #GQueue + + + + + + Convenience method, which frees all the memory used by a #GQueue, +and calls the specified destroy function on every element's data. + + + + + + a pointer to a #GQueue + + + + the function to be called to free each element's data + + + + + + Returns the number of items in @queue. + + the number of items in @queue + + + + + a #GQueue + + + + + + Returns the position of the first element in @queue which contains @data. + + the position of the first element in @queue which + contains @data, or -1 if no element in @queue contains @data + + + + + a #GQueue + + + + the data to find + + + + + + A statically-allocated #GQueue must be initialized with this function +before it can be used. Alternatively you can initialize it with +#G_QUEUE_INIT. It is not necessary to initialize queues created with +g_queue_new(). + + + + + + an uninitialized #GQueue + + + + + + Inserts @data into @queue after @sibling. + +@sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the +data at the head of the queue. + + + + + + a #GQueue + + + + a #GList link that must be part of @queue, or %NULL to + push at the head of the queue. + + + + + + the data to insert + + + + + + Inserts @data into @queue before @sibling. + +@sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the +data at the tail of the queue. + + + + + + a #GQueue + + + + a #GList link that must be part of @queue, or %NULL to + push at the tail of the queue. + + + + + + the data to insert + + + + + + Inserts @data into @queue using @func to determine the new position. + + + + + + a #GQueue + + + + the data to insert + + + + the #GCompareDataFunc used to compare elements in the queue. It is + called with two elements of the @queue and @user_data. It should + return 0 if the elements are equal, a negative value if the first + element comes before the second, and a positive value if the second + element comes before the first. + + + + user data passed to @func + + + + + + Returns %TRUE if the queue is empty. + + %TRUE if the queue is empty + + + + + a #GQueue. + + + + + + Returns the position of @link_ in @queue. + + the position of @link_, or -1 if the link is + not part of @queue + + + + + a #GQueue + + + + a #GList link + + + + + + + + Returns the first element of the queue. + + the data of the first element in the queue, or %NULL + if the queue is empty + + + + + a #GQueue + + + + + + Returns the first link in @queue. + + the first link in @queue, or %NULL if @queue is empty + + + + + + + a #GQueue + + + + + + Returns the @n'th element of @queue. + + the data for the @n'th element of @queue, + or %NULL if @n is off the end of @queue + + + + + a #GQueue + + + + the position of the element + + + + + + Returns the link at the given position + + the link at the @n'th position, or %NULL + if @n is off the end of the list + + + + + + + a #GQueue + + + + the position of the link + + + + + + Returns the last element of the queue. + + the data of the last element in the queue, or %NULL + if the queue is empty + + + + + a #GQueue + + + + + + Returns the last link in @queue. + + the last link in @queue, or %NULL if @queue is empty + + + + + + + a #GQueue + + + + + + Removes the first element of the queue and returns its data. + + the data of the first element in the queue, or %NULL + if the queue is empty + + + + + a #GQueue + + + + + + Removes and returns the first element of the queue. + + the #GList element at the head of the queue, or %NULL + if the queue is empty + + + + + + + a #GQueue + + + + + + Removes the @n'th element of @queue and returns its data. + + the element's data, or %NULL if @n is off the end of @queue + + + + + a #GQueue + + + + the position of the element + + + + + + Removes and returns the link at the given position. + + the @n'th link, or %NULL if @n is off the end of @queue + + + + + + + a #GQueue + + + + the link's position + + + + + + Removes the last element of the queue and returns its data. + + the data of the last element in the queue, or %NULL + if the queue is empty + + + + + a #GQueue + + + + + + Removes and returns the last element of the queue. + + the #GList element at the tail of the queue, or %NULL + if the queue is empty + + + + + + + a #GQueue + + + + + + Adds a new element at the head of the queue. + + + + + + a #GQueue. + + + + the data for the new element. + + + + + + Adds a new element at the head of the queue. + + + + + + a #GQueue + + + + a single #GList element, not a list with more than one element + + + + + + + + Inserts a new element into @queue at the given position. + + + + + + a #GQueue + + + + the data for the new element + + + + the position to insert the new element. If @n is negative or + larger than the number of elements in the @queue, the element is + added to the end of the queue. + + + + + + Inserts @link into @queue at the given position. + + + + + + a #GQueue + + + + the position to insert the link. If this is negative or larger than + the number of elements in @queue, the link is added to the end of + @queue. + + + + the link to add to @queue + + + + + + + + Adds a new element at the tail of the queue. + + + + + + a #GQueue + + + + the data for the new element + + + + + + Adds a new element at the tail of the queue. + + + + + + a #GQueue + + + + a single #GList element, not a list with more than one element + + + + + + + + Removes the first element in @queue that contains @data. + + %TRUE if @data was found and removed from @queue + + + + + a #GQueue + + + + the data to remove + + + + + + Remove all elements whose data equals @data from @queue. + + the number of elements removed from @queue + + + + + a #GQueue + + + + the data to remove + + + + + + Reverses the order of the items in @queue. + + + + + + a #GQueue + + + + + + Sorts @queue using @compare_func. + + + + + + a #GQueue + + + + the #GCompareDataFunc used to sort @queue. This function + is passed two elements of the queue and should return 0 if they are + equal, a negative value if the first comes before the second, and + a positive value if the second comes before the first. + + + + user data passed to @compare_func + + + + + + Unlinks @link_ so that it will no longer be part of @queue. +The link is not freed. + +@link_ must be part of @queue. + + + + + + a #GQueue + + + + a #GList link that must be part of @queue + + + + + + + + Creates a new #GQueue. + + a newly allocated #GQueue + + + + + + The GRWLock struct is an opaque data structure to represent a +reader-writer lock. It is similar to a #GMutex in that it allows +multiple threads to coordinate access to a shared resource. + +The difference to a mutex is that a reader-writer lock discriminates +between read-only ('reader') and full ('writer') access. While only +one thread at a time is allowed write access (by holding the 'writer' +lock via g_rw_lock_writer_lock()), multiple threads can gain +simultaneous read-only access (by holding the 'reader' lock via +g_rw_lock_reader_lock()). + +Here is an example for an array with access functions: +|[<!-- language="C" --> + GRWLock lock; + GPtrArray *array; + + gpointer + my_array_get (guint index) + { + gpointer retval = NULL; + + if (!array) + return NULL; + + g_rw_lock_reader_lock (&lock); + if (index < array->len) + retval = g_ptr_array_index (array, index); + g_rw_lock_reader_unlock (&lock); + + return retval; + } + + void + my_array_set (guint index, gpointer data) + { + g_rw_lock_writer_lock (&lock); + + if (!array) + array = g_ptr_array_new (); + + if (index >= array->len) + g_ptr_array_set_size (array, index+1); + g_ptr_array_index (array, index) = data; + + g_rw_lock_writer_unlock (&lock); + } + ]| +This example shows an array which can be accessed by many readers +(the my_array_get() function) simultaneously, whereas the writers +(the my_array_set() function) will only be allowed one at a time +and only if no readers currently access the array. This is because +of the potentially dangerous resizing of the array. Using these +functions is fully multi-thread safe now. + +If a #GRWLock is allocated in static storage then it can be used +without initialisation. Otherwise, you should call +g_rw_lock_init() on it and g_rw_lock_clear() when done. + +A GRWLock should only be accessed with the g_rw_lock_ functions. + + + + + + + + + + Frees the resources allocated to a lock with g_rw_lock_init(). + +This function should not be used with a #GRWLock that has been +statically allocated. + +Calling g_rw_lock_clear() when any thread holds the lock +leads to undefined behaviour. + +Sine: 2.32 + + + + + + an initialized #GRWLock + + + + + + Initializes a #GRWLock so that it can be used. + +This function is useful to initialize a lock that has been +allocated on the stack, or as part of a larger structure. It is not +necessary to initialise a reader-writer lock that has been statically +allocated. + +|[<!-- language="C" --> + typedef struct { + GRWLock l; + ... + } Blob; + +Blob *b; + +b = g_new (Blob, 1); +g_rw_lock_init (&b->l); +]| + +To undo the effect of g_rw_lock_init() when a lock is no longer +needed, use g_rw_lock_clear(). + +Calling g_rw_lock_init() on an already initialized #GRWLock leads +to undefined behaviour. + + + + + + an uninitialized #GRWLock + + + + + + Obtain a read lock on @rw_lock. If another thread currently holds +the write lock on @rw_lock or blocks waiting for it, the current +thread will block. Read locks can be taken recursively. + +It is implementation-defined how many threads are allowed to +hold read locks on the same lock simultaneously. + + + + + + a #GRWLock + + + + + + Tries to obtain a read lock on @rw_lock and returns %TRUE if +the read lock was successfully obtained. Otherwise it +returns %FALSE. + + %TRUE if @rw_lock could be locked + + + + + a #GRWLock + + + + + + Release a read lock on @rw_lock. + +Calling g_rw_lock_reader_unlock() on a lock that is not held +by the current thread leads to undefined behaviour. + + + + + + a #GRWLock + + + + + + Obtain a write lock on @rw_lock. If any thread already holds +a read or write lock on @rw_lock, the current thread will block +until all other threads have dropped their locks on @rw_lock. + + + + + + a #GRWLock + + + + + + Tries to obtain a write lock on @rw_lock. If any other thread holds +a read or write lock on @rw_lock, it immediately returns %FALSE. +Otherwise it locks @rw_lock and returns %TRUE. + + %TRUE if @rw_lock could be locked + + + + + a #GRWLock + + + + + + Release a write lock on @rw_lock. + +Calling g_rw_lock_writer_unlock() on a lock that is not held +by the current thread leads to undefined behaviour. + + + + + + a #GRWLock + + + + + + + The GRand struct is an opaque data structure. It should only be +accessed through the g_rand_* functions. + + Copies a #GRand into a new one with the same exact state as before. +This way you can take a snapshot of the random number generator for +replaying later. + + the new #GRand + + + + + a #GRand + + + + + + Returns the next random #gdouble from @rand_ equally distributed over +the range [0..1). + + a random number + + + + + a #GRand + + + + + + Returns the next random #gdouble from @rand_ equally distributed over +the range [@begin..@end). + + a random number + + + + + a #GRand + + + + lower closed bound of the interval + + + + upper open bound of the interval + + + + + + Frees the memory allocated for the #GRand. + + + + + + a #GRand + + + + + + Returns the next random #guint32 from @rand_ equally distributed over +the range [0..2^32-1]. + + a random number + + + + + a #GRand + + + + + + Returns the next random #gint32 from @rand_ equally distributed over +the range [@begin..@end-1]. + + a random number + + + + + a #GRand + + + + lower closed bound of the interval + + + + upper open bound of the interval + + + + + + Sets the seed for the random number generator #GRand to @seed. + + + + + + a #GRand + + + + a value to reinitialize the random number generator + + + + + + Initializes the random number generator by an array of longs. +Array can be of arbitrary size, though only the first 624 values +are taken. This function is useful if you have many low entropy +seeds, or if you require more then 32 bits of actual entropy for +your application. + + + + + + a #GRand + + + + array to initialize with + + + + length of array + + + + + + Creates a new random number generator initialized with a seed taken +either from `/dev/urandom` (if existing) or from the current time +(as a fallback). + +On Windows, the seed is taken from rand_s(). + + the new #GRand + + + + + Creates a new random number generator initialized with @seed. + + the new #GRand + + + + + a value to initialize the random number generator + + + + + + Creates a new random number generator initialized with @seed. + + the new #GRand + + + + + an array of seeds to initialize the random number generator + + + + an array of seeds to initialize the random number + generator + + + + + + + The GRecMutex struct is an opaque data structure to represent a +recursive mutex. It is similar to a #GMutex with the difference +that it is possible to lock a GRecMutex multiple times in the same +thread without deadlock. When doing so, care has to be taken to +unlock the recursive mutex as often as it has been locked. + +If a #GRecMutex is allocated in static storage then it can be used +without initialisation. Otherwise, you should call +g_rec_mutex_init() on it and g_rec_mutex_clear() when done. + +A GRecMutex should only be accessed with the +g_rec_mutex_ functions. + + + + + + + + + + Frees the resources allocated to a recursive mutex with +g_rec_mutex_init(). + +This function should not be used with a #GRecMutex that has been +statically allocated. + +Calling g_rec_mutex_clear() on a locked recursive mutex leads +to undefined behaviour. + +Sine: 2.32 + + + + + + an initialized #GRecMutex + + + + + + Initializes a #GRecMutex so that it can be used. + +This function is useful to initialize a recursive mutex +that has been allocated on the stack, or as part of a larger +structure. + +It is not necessary to initialise a recursive mutex that has been +statically allocated. + +|[<!-- language="C" --> + typedef struct { + GRecMutex m; + ... + } Blob; + +Blob *b; + +b = g_new (Blob, 1); +g_rec_mutex_init (&b->m); +]| + +Calling g_rec_mutex_init() on an already initialized #GRecMutex +leads to undefined behaviour. + +To undo the effect of g_rec_mutex_init() when a recursive mutex +is no longer needed, use g_rec_mutex_clear(). + + + + + + an uninitialized #GRecMutex + + + + + + Locks @rec_mutex. If @rec_mutex is already locked by another +thread, the current thread will block until @rec_mutex is +unlocked by the other thread. If @rec_mutex is already locked +by the current thread, the 'lock count' of @rec_mutex is increased. +The mutex will only become available again when it is unlocked +as many times as it has been locked. + + + + + + a #GRecMutex + + + + + + Tries to lock @rec_mutex. If @rec_mutex is already locked +by another thread, it immediately returns %FALSE. Otherwise +it locks @rec_mutex and returns %TRUE. + + %TRUE if @rec_mutex could be locked + + + + + a #GRecMutex + + + + + + Unlocks @rec_mutex. If another thread is blocked in a +g_rec_mutex_lock() call for @rec_mutex, it will become unblocked +and can lock @rec_mutex itself. + +Calling g_rec_mutex_unlock() on a recursive mutex that is not +locked by the current thread leads to undefined behaviour. + + + + + + a #GRecMutex + + + + + + + The g_regex_*() functions implement regular +expression pattern matching using syntax and semantics similar to +Perl regular expression. + +Some functions accept a @start_position argument, setting it differs +from just passing over a shortened string and setting #G_REGEX_MATCH_NOTBOL +in the case of a pattern that begins with any kind of lookbehind assertion. +For example, consider the pattern "\Biss\B" which finds occurrences of "iss" +in the middle of words. ("\B" matches only if the current position in the +subject is not a word boundary.) When applied to the string "Mississipi" +from the fourth byte, namely "issipi", it does not match, because "\B" is +always false at the start of the subject, which is deemed to be a word +boundary. However, if the entire string is passed , but with +@start_position set to 4, it finds the second occurrence of "iss" because +it is able to look behind the starting point to discover that it is +preceded by a letter. + +Note that, unless you set the #G_REGEX_RAW flag, all the strings passed +to these functions must be encoded in UTF-8. The lengths and the positions +inside the strings are in bytes and not in characters, so, for instance, +"\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a +single character. If you set #G_REGEX_RAW the strings can be non-valid +UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two +bytes and two characters long. + +When matching a pattern, "\n" matches only against a "\n" character in +the string, and "\r" matches only a "\r" character. To match any newline +sequence use "\R". This particular group matches either the two-character +sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed, +U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"), +CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line +separator, U+2028), or PS (paragraph separator, U+2029). + +The behaviour of the dot, circumflex, and dollar metacharacters are +affected by newline characters, the default is to recognize any newline +character (the same characters recognized by "\R"). This can be changed +with #G_REGEX_NEWLINE_CR, #G_REGEX_NEWLINE_LF and #G_REGEX_NEWLINE_CRLF +compile options, and with #G_REGEX_MATCH_NEWLINE_ANY, +#G_REGEX_MATCH_NEWLINE_CR, #G_REGEX_MATCH_NEWLINE_LF and +#G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also +relevant when compiling a pattern if #G_REGEX_EXTENDED is set, and an +unescaped "#" outside a character class is encountered. This indicates +a comment that lasts until after the next newline. + +When setting the %G_REGEX_JAVASCRIPT_COMPAT flag, pattern syntax and pattern +matching is changed to be compatible with the way that regular expressions +work in JavaScript. More precisely, a lonely ']' character in the pattern +is a syntax error; the '\x' escape only allows 0 to 2 hexadecimal digits, and +you must use the '\u' escape sequence with 4 hex digits to specify a unicode +codepoint instead of '\x' or 'x{....}'. If '\x' or '\u' are not followed by +the specified number of hex digits, they match 'x' and 'u' literally; also +'\U' always matches 'U' instead of being an error in the pattern. Finally, +pattern matching is modified so that back references to an unset subpattern +group produces a match with the empty string instead of an error. See +pcreapi(3) for more information. + +Creating and manipulating the same #GRegex structure from different +threads is not a problem as #GRegex does not modify its internal +state between creation and destruction, on the other hand #GMatchInfo +is not threadsafe. + +The regular expressions low-level functionalities are obtained through +the excellent +[PCRE](http://www.pcre.org/) +library written by Philip Hazel. + + Compiles the regular expression to an internal form, and does +the initial setup of the #GRegex structure. + + a #GRegex structure or %NULL if an error occured. Call + g_regex_unref() when you are done with it + + + + + the regular expression + + + + compile options for the regular expression, or 0 + + + + match options for the regular expression, or 0 + + + + + + Returns the number of capturing subpatterns in the pattern. + + the number of capturing subpatterns + + + + + a #GRegex + + + + + + Returns the compile options that @regex was created with. + +Depending on the version of PCRE that is used, this may or may not +include flags set by option expressions such as `(?i)` found at the +top-level within the compiled pattern. + + flags from #GRegexCompileFlags + + + + + a #GRegex + + + + + + Checks whether the pattern contains explicit CR or LF references. + + %TRUE if the pattern contains explicit CR or LF references + + + + + a #GRegex structure + + + + + + Returns the match options that @regex was created with. + + flags from #GRegexMatchFlags + + + + + a #GRegex + + + + + + Returns the number of the highest back reference +in the pattern, or 0 if the pattern does not contain +back references. + + the number of the highest back reference + + + + + a #GRegex + + + + + + Gets the number of characters in the longest lookbehind assertion in the +pattern. This information is useful when doing multi-segment matching using +the partial matching facilities. + + the number of characters in the longest lookbehind assertion. + + + + + a #GRegex structure + + + + + + Gets the pattern string associated with @regex, i.e. a copy of +the string passed to g_regex_new(). + + the pattern of @regex + + + + + a #GRegex structure + + + + + + Retrieves the number of the subexpression named @name. + + The number of the subexpression or -1 if @name + does not exists + + + + + #GRegex structure + + + + name of the subexpression + + + + + + Scans for a match in string for the pattern in @regex. +The @match_options are combined with the match options specified +when the @regex structure was created, letting you have more +flexibility in reusing #GRegex structures. + +A #GMatchInfo structure, used to get information on the match, +is stored in @match_info if not %NULL. Note that if @match_info +is not %NULL then it is created even if the function returns %FALSE, +i.e. you must free it regardless if regular expression actually matched. + +To retrieve all the non-overlapping matches of the pattern in +string you can use g_match_info_next(). + +|[<!-- language="C" --> +static void +print_uppercase_words (const gchar *string) +{ + // Print all uppercase-only words. + GRegex *regex; + GMatchInfo *match_info; + + regex = g_regex_new ("[A-Z]+", 0, 0, NULL); + g_regex_match (regex, string, 0, &match_info); + while (g_match_info_matches (match_info)) + { + gchar *word = g_match_info_fetch (match_info, 0); + g_print ("Found: %s\n", word); + g_free (word); + g_match_info_next (match_info, NULL); + } + g_match_info_free (match_info); + g_regex_unref (regex); +} +]| + +@string is not copied and is used in #GMatchInfo internally. If +you use any #GMatchInfo method (except g_match_info_free()) after +freeing or modifying @string then the behaviour is undefined. + + %TRUE is the string matched, %FALSE otherwise + + + + + a #GRegex structure from g_regex_new() + + + + the string to scan for matches + + + + match options + + + + pointer to location where to store + the #GMatchInfo, or %NULL if you do not need it + + + + + + Using the standard algorithm for regular expression matching only +the longest match in the string is retrieved. This function uses +a different algorithm so it can retrieve all the possible matches. +For more documentation see g_regex_match_all_full(). + +A #GMatchInfo structure, used to get information on the match, is +stored in @match_info if not %NULL. Note that if @match_info is +not %NULL then it is created even if the function returns %FALSE, +i.e. you must free it regardless if regular expression actually +matched. + +@string is not copied and is used in #GMatchInfo internally. If +you use any #GMatchInfo method (except g_match_info_free()) after +freeing or modifying @string then the behaviour is undefined. + + %TRUE is the string matched, %FALSE otherwise + + + + + a #GRegex structure from g_regex_new() + + + + the string to scan for matches + + + + match options + + + + pointer to location where to store + the #GMatchInfo, or %NULL if you do not need it + + + + + + Using the standard algorithm for regular expression matching only +the longest match in the string is retrieved, it is not possible +to obtain all the available matches. For instance matching +"<a> <b> <c>" against the pattern "<.*>" +you get "<a> <b> <c>". + +This function uses a different algorithm (called DFA, i.e. deterministic +finite automaton), so it can retrieve all the possible matches, all +starting at the same point in the string. For instance matching +"<a> <b> <c>" against the pattern "<.*>;" +you would obtain three matches: "<a> <b> <c>", +"<a> <b>" and "<a>". + +The number of matched strings is retrieved using +g_match_info_get_match_count(). To obtain the matched strings and +their position you can use, respectively, g_match_info_fetch() and +g_match_info_fetch_pos(). Note that the strings are returned in +reverse order of length; that is, the longest matching string is +given first. + +Note that the DFA algorithm is slower than the standard one and it +is not able to capture substrings, so backreferences do not work. + +Setting @start_position differs from just passing over a shortened +string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern +that begins with any kind of lookbehind assertion, such as "\b". + +A #GMatchInfo structure, used to get information on the match, is +stored in @match_info if not %NULL. Note that if @match_info is +not %NULL then it is created even if the function returns %FALSE, +i.e. you must free it regardless if regular expression actually +matched. + +@string is not copied and is used in #GMatchInfo internally. If +you use any #GMatchInfo method (except g_match_info_free()) after +freeing or modifying @string then the behaviour is undefined. + + %TRUE is the string matched, %FALSE otherwise + + + + + a #GRegex structure from g_regex_new() + + + + the string to scan for matches + + + + + + the length of @string, or -1 if @string is nul-terminated + + + + starting index of the string to match, in bytes + + + + match options + + + + pointer to location where to store + the #GMatchInfo, or %NULL if you do not need it + + + + + + Scans for a match in string for the pattern in @regex. +The @match_options are combined with the match options specified +when the @regex structure was created, letting you have more +flexibility in reusing #GRegex structures. + +Setting @start_position differs from just passing over a shortened +string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern +that begins with any kind of lookbehind assertion, such as "\b". + +A #GMatchInfo structure, used to get information on the match, is +stored in @match_info if not %NULL. Note that if @match_info is +not %NULL then it is created even if the function returns %FALSE, +i.e. you must free it regardless if regular expression actually +matched. + +@string is not copied and is used in #GMatchInfo internally. If +you use any #GMatchInfo method (except g_match_info_free()) after +freeing or modifying @string then the behaviour is undefined. + +To retrieve all the non-overlapping matches of the pattern in +string you can use g_match_info_next(). + +|[<!-- language="C" --> +static void +print_uppercase_words (const gchar *string) +{ + // Print all uppercase-only words. + GRegex *regex; + GMatchInfo *match_info; + GError *error = NULL; + + regex = g_regex_new ("[A-Z]+", 0, 0, NULL); + g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error); + while (g_match_info_matches (match_info)) + { + gchar *word = g_match_info_fetch (match_info, 0); + g_print ("Found: %s\n", word); + g_free (word); + g_match_info_next (match_info, &error); + } + g_match_info_free (match_info); + g_regex_unref (regex); + if (error != NULL) + { + g_printerr ("Error while matching: %s\n", error->message); + g_error_free (error); + } +} +]| + + %TRUE is the string matched, %FALSE otherwise + + + + + a #GRegex structure from g_regex_new() + + + + the string to scan for matches + + + + + + the length of @string, or -1 if @string is nul-terminated + + + + starting index of the string to match, in bytes + + + + match options + + + + pointer to location where to store + the #GMatchInfo, or %NULL if you do not need it + + + + + + Increases reference count of @regex by 1. + + @regex + + + + + a #GRegex + + + + + + Replaces all occurrences of the pattern in @regex with the +replacement text. Backreferences of the form '\number' or +'\g<number>' in the replacement text are interpolated by the +number-th captured subexpression of the match, '\g<name>' refers +to the captured subexpression with the given name. '\0' refers +to the complete match, but '\0' followed by a number is the octal +representation of a character. To include a literal '\' in the +replacement, write '\\'. + +There are also escapes that changes the case of the following text: + +- \l: Convert to lower case the next character +- \u: Convert to upper case the next character +- \L: Convert to lower case till \E +- \U: Convert to upper case till \E +- \E: End case modification + +If you do not need to use backreferences use g_regex_replace_literal(). + +The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was +passed to g_regex_new(). If you want to use not UTF-8 encoded stings +you can use g_regex_replace_literal(). + +Setting @start_position differs from just passing over a shortened +string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that +begins with any kind of lookbehind assertion, such as "\b". + + a newly allocated string containing the replacements + + + + + a #GRegex structure + + + + the string to perform matches against + + + + + + the length of @string, or -1 if @string is nul-terminated + + + + starting index of the string to match, in bytes + + + + text to replace each match with + + + + options for the match + + + + + + Replaces occurrences of the pattern in regex with the output of +@eval for that occurrence. + +Setting @start_position differs from just passing over a shortened +string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern +that begins with any kind of lookbehind assertion, such as "\b". + +The following example uses g_regex_replace_eval() to replace multiple +strings at once: +|[<!-- language="C" --> +static gboolean +eval_cb (const GMatchInfo *info, + GString *res, + gpointer data) +{ + gchar *match; + gchar *r; + + match = g_match_info_fetch (info, 0); + r = g_hash_table_lookup ((GHashTable *)data, match); + g_string_append (res, r); + g_free (match); + + return FALSE; +} + +... + +GRegex *reg; +GHashTable *h; +gchar *res; + +h = g_hash_table_new (g_str_hash, g_str_equal); + +g_hash_table_insert (h, "1", "ONE"); +g_hash_table_insert (h, "2", "TWO"); +g_hash_table_insert (h, "3", "THREE"); +g_hash_table_insert (h, "4", "FOUR"); + +reg = g_regex_new ("1|2|3|4", 0, 0, NULL); +res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL); +g_hash_table_destroy (h); + +... +]| + + a newly allocated string containing the replacements + + + + + a #GRegex structure from g_regex_new() + + + + string to perform matches against + + + + + + the length of @string, or -1 if @string is nul-terminated + + + + starting index of the string to match, in bytes + + + + options for the match + + + + a function to call for each match + + + + user data to pass to the function + + + + + + Replaces all occurrences of the pattern in @regex with the +replacement text. @replacement is replaced literally, to +include backreferences use g_regex_replace(). + +Setting @start_position differs from just passing over a +shortened string and setting #G_REGEX_MATCH_NOTBOL in the +case of a pattern that begins with any kind of lookbehind +assertion, such as "\b". + + a newly allocated string containing the replacements + + + + + a #GRegex structure + + + + the string to perform matches against + + + + + + the length of @string, or -1 if @string is nul-terminated + + + + starting index of the string to match, in bytes + + + + text to replace each match with + + + + options for the match + + + + + + Breaks the string on the pattern, and returns an array of the tokens. +If the pattern contains capturing parentheses, then the text for each +of the substrings will also be returned. If the pattern does not match +anywhere in the string, then the whole string is returned as the first +token. + +As a special case, the result of splitting the empty string "" is an +empty vector, not a vector containing a single string. The reason for +this special case is that being able to represent a empty vector is +typically more useful than consistent handling of empty elements. If +you do need to represent empty elements, you'll need to check for the +empty string before calling this function. + +A pattern that can match empty strings splits @string into separate +characters wherever it matches the empty string between characters. +For example splitting "ab c" using as a separator "\s*", you will get +"a", "b" and "c". + + a %NULL-terminated gchar ** array. Free +it using g_strfreev() + + + + + + + a #GRegex structure + + + + the string to split with the pattern + + + + match time option flags + + + + + + Breaks the string on the pattern, and returns an array of the tokens. +If the pattern contains capturing parentheses, then the text for each +of the substrings will also be returned. If the pattern does not match +anywhere in the string, then the whole string is returned as the first +token. + +As a special case, the result of splitting the empty string "" is an +empty vector, not a vector containing a single string. The reason for +this special case is that being able to represent a empty vector is +typically more useful than consistent handling of empty elements. If +you do need to represent empty elements, you'll need to check for the +empty string before calling this function. + +A pattern that can match empty strings splits @string into separate +characters wherever it matches the empty string between characters. +For example splitting "ab c" using as a separator "\s*", you will get +"a", "b" and "c". + +Setting @start_position differs from just passing over a shortened +string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern +that begins with any kind of lookbehind assertion, such as "\b". + + a %NULL-terminated gchar ** array. Free +it using g_strfreev() + + + + + + + a #GRegex structure + + + + the string to split with the pattern + + + + + + the length of @string, or -1 if @string is nul-terminated + + + + starting index of the string to match, in bytes + + + + match time option flags + + + + the maximum number of tokens to split @string into. + If this is less than 1, the string is split completely + + + + + + Decreases reference count of @regex by 1. When reference count drops +to zero, it frees all the memory associated with the regex structure. + + + + + + a #GRegex + + + + + + Checks whether @replacement is a valid replacement string +(see g_regex_replace()), i.e. that all escape sequences in +it are valid. + +If @has_references is not %NULL then @replacement is checked +for pattern references. For instance, replacement text 'foo\n' +does not contain references and may be evaluated without information +about actual match, but '\0\1' (whole match followed by first +subpattern) requires valid #GMatchInfo object. + + whether @replacement is a valid replacement string + + + + + the replacement string + + + + location to store information about + references in @replacement or %NULL + + + + + + + + + + + Escapes the nul characters in @string to "\x00". It can be used +to compile a regex with embedded nul characters. + +For completeness, @length can be -1 for a nul-terminated string. +In this case the output string will be of course equal to @string. + + a newly-allocated escaped string + + + + + the string to escape + + + + the length of @string + + + + + + Escapes the special characters used for regular expressions +in @string, for instance "a.b*c" becomes "a\.b\*c". This +function is useful to dynamically generate regular expressions. + +@string can contain nul characters that are replaced with "\0", +in this case remember to specify the correct length of @string +in @length. + + a newly-allocated escaped string + + + + + the string to escape + + + + + + the length of @string, or -1 if @string is nul-terminated + + + + + + Scans for a match in @string for @pattern. + +This function is equivalent to g_regex_match() but it does not +require to compile the pattern with g_regex_new(), avoiding some +lines of code when you need just to do a match without extracting +substrings, capture counts, and so on. + +If this function is to be called on the same @pattern more than +once, it's more efficient to compile the pattern once with +g_regex_new() and then use g_regex_match(). + + %TRUE if the string matched, %FALSE otherwise + + + + + the regular expression + + + + the string to scan for matches + + + + compile options for the regular expression, or 0 + + + + match options, or 0 + + + + + + Breaks the string on the pattern, and returns an array of +the tokens. If the pattern contains capturing parentheses, +then the text for each of the substrings will also be returned. +If the pattern does not match anywhere in the string, then the +whole string is returned as the first token. + +This function is equivalent to g_regex_split() but it does +not require to compile the pattern with g_regex_new(), avoiding +some lines of code when you need just to do a split without +extracting substrings, capture counts, and so on. + +If this function is to be called on the same @pattern more than +once, it's more efficient to compile the pattern once with +g_regex_new() and then use g_regex_split(). + +As a special case, the result of splitting the empty string "" +is an empty vector, not a vector containing a single string. +The reason for this special case is that being able to represent +a empty vector is typically more useful than consistent handling +of empty elements. If you do need to represent empty elements, +you'll need to check for the empty string before calling this +function. + +A pattern that can match empty strings splits @string into +separate characters wherever it matches the empty string between +characters. For example splitting "ab c" using as a separator +"\s*", you will get "a", "b" and "c". + + a %NULL-terminated array of strings. Free +it using g_strfreev() + + + + + + + the regular expression + + + + the string to scan for matches + + + + compile options for the regular expression, or 0 + + + + match options, or 0 + + + + + + + Flags specifying compile-time options. + + Letters in the pattern match both upper- and + lowercase letters. This option can be changed within a pattern + by a "(?i)" option setting. + + + By default, GRegex treats the strings as consisting + of a single line of characters (even if it actually contains + newlines). The "start of line" metacharacter ("^") matches only + at the start of the string, while the "end of line" metacharacter + ("$") matches only at the end of the string, or before a terminating + newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When + #G_REGEX_MULTILINE is set, the "start of line" and "end of line" + constructs match immediately following or immediately before any + newline in the string, respectively, as well as at the very start + and end. This can be changed within a pattern by a "(?m)" option + setting. + + + A dot metacharater (".") in the pattern matches all + characters, including newlines. Without it, newlines are excluded. + This option can be changed within a pattern by a ("?s") option setting. + + + Whitespace data characters in the pattern are + totally ignored except when escaped or inside a character class. + Whitespace does not include the VT character (code 11). In addition, + characters between an unescaped "#" outside a character class and + the next newline character, inclusive, are also ignored. This can + be changed within a pattern by a "(?x)" option setting. + + + The pattern is forced to be "anchored", that is, + it is constrained to match only at the first matching point in the + string that is being searched. This effect can also be achieved by + appropriate constructs in the pattern itself such as the "^" + metacharater. + + + A dollar metacharacter ("$") in the pattern + matches only at the end of the string. Without this option, a + dollar also matches immediately before the final character if + it is a newline (but not before any other newlines). This option + is ignored if #G_REGEX_MULTILINE is set. + + + Inverts the "greediness" of the quantifiers so that + they are not greedy by default, but become greedy if followed by "?". + It can also be set by a "(?U)" option setting within the pattern. + + + Usually strings must be valid UTF-8 strings, using this + flag they are considered as a raw sequence of bytes. + + + Disables the use of numbered capturing + parentheses in the pattern. Any opening parenthesis that is not + followed by "?" behaves as if it were followed by "?:" but named + parentheses can still be used for capturing (and they acquire numbers + in the usual way). + + + Optimize the regular expression. If the pattern will + be used many times, then it may be worth the effort to optimize it + to improve the speed of matches. + + + Limits an unanchored pattern to match before (or at) the + first newline. Since: 2.34 + + + Names used to identify capturing subpatterns need not + be unique. This can be helpful for certain types of pattern when it + is known that only one instance of the named subpattern can ever be + matched. + + + Usually any newline character or character sequence is + recognized. If this option is set, the only recognized newline character + is '\r'. + + + Usually any newline character or character sequence is + recognized. If this option is set, the only recognized newline character + is '\n'. + + + Usually any newline character or character sequence is + recognized. If this option is set, the only recognized newline character + sequence is '\r\n'. + + + Usually any newline character or character sequence + is recognized. If this option is set, the only recognized newline character + sequences are '\r', '\n', and '\r\n'. Since: 2.34 + + + Usually any newline character or character sequence + is recognised. If this option is set, then "\R" only recognizes the newline + characters '\r', '\n' and '\r\n'. Since: 2.34 + + + Changes behaviour so that it is compatible with + JavaScript rather than PCRE. Since: 2.34 + + + + Error codes returned by regular expressions functions. + + Compilation of the regular expression failed. + + + Optimization of the regular expression failed. + + + Replacement failed due to an ill-formed replacement + string. + + + The match process failed. + + + Internal error of the regular expression engine. + Since 2.16 + + + "\\" at end of pattern. Since 2.16 + + + "\\c" at end of pattern. Since 2.16 + + + Unrecognized character follows "\\". + Since 2.16 + + + Numbers out of order in "{}" + quantifier. Since 2.16 + + + Number too big in "{}" quantifier. + Since 2.16 + + + Missing terminating "]" for + character class. Since 2.16 + + + Invalid escape sequence + in character class. Since 2.16 + + + Range out of order in character class. + Since 2.16 + + + Nothing to repeat. Since 2.16 + + + Unrecognized character after "(?", + "(?<" or "(?P". Since 2.16 + + + POSIX named classes are + supported only within a class. Since 2.16 + + + Missing terminating ")" or ")" + without opening "(". Since 2.16 + + + Reference to non-existent + subpattern. Since 2.16 + + + Missing terminating ")" after comment. + Since 2.16 + + + Regular expression too large. + Since 2.16 + + + Failed to get memory. Since 2.16 + + + Lookbehind assertion is not + fixed length. Since 2.16 + + + Malformed number or name after "(?(". + Since 2.16 + + + Conditional group contains + more than two branches. Since 2.16 + + + Assertion expected after "(?(". + Since 2.16 + + + Unknown POSIX class name. + Since 2.16 + + + POSIX collating + elements are not supported. Since 2.16 + + + Character value in "\\x{...}" sequence + is too large. Since 2.16 + + + Invalid condition "(?(0)". Since 2.16 + + + \\C not allowed in + lookbehind assertion. Since 2.16 + + + Recursive call could loop indefinitely. + Since 2.16 + + + Missing terminator + in subpattern name. Since 2.16 + + + Two named subpatterns have + the same name. Since 2.16 + + + Malformed "\\P" or "\\p" sequence. + Since 2.16 + + + Unknown property name after "\\P" or + "\\p". Since 2.16 + + + Subpattern name is too long + (maximum 32 characters). Since 2.16 + + + Too many named subpatterns (maximum + 10,000). Since 2.16 + + + Octal value is greater than "\\377". + Since 2.16 + + + "DEFINE" group contains more + than one branch. Since 2.16 + + + Repeating a "DEFINE" group is not allowed. + This error is never raised. Since: 2.16 Deprecated: 2.34 + + + Inconsistent newline options. + Since 2.16 + + + "\\g" is not followed by a braced, + angle-bracketed, or quoted name or number, or by a plain number. Since: 2.16 + + + relative reference must not be zero. Since: 2.34 + + + the backtracing + control verb used does not allow an argument. Since: 2.34 + + + unknown backtracing + control verb. Since: 2.34 + + + number is too big in escape sequence. Since: 2.34 + + + Missing subpattern name. Since: 2.34 + + + Missing digit. Since 2.34 + + + In JavaScript compatibility mode, + "[" is an invalid data character. Since: 2.34 + + + different names for subpatterns of the + same number are not allowed. Since: 2.34 + + + the backtracing control + verb requires an argument. Since: 2.34 + + + "\\c" must be followed by an ASCII + character. Since: 2.34 + + + "\\k" is not followed by a braced, angle-bracketed, or + quoted name. Since: 2.34 + + + "\\N" is not supported in a class. Since: 2.34 + + + too many forward references. Since: 2.34 + + + the name is too long in "(*MARK)", "(*PRUNE)", + "(*SKIP)", or "(*THEN)". Since: 2.34 + + + the character value in the \\u sequence is + too large. Since: 2.34 + + + + Specifies the type of the function passed to g_regex_replace_eval(). +It is called for each occurrence of the pattern in the string passed +to g_regex_replace_eval(), and it should append the replacement to +@result. + + %FALSE to continue the replacement process, %TRUE to stop it + + + + + the #GMatchInfo generated by the match. + Use g_match_info_get_regex() and g_match_info_get_string() if you + need the #GRegex or the matched string. + + + + a #GString containing the new string + + + + user data passed to g_regex_replace_eval() + + + + + + Flags specifying match-time options. + + The pattern is forced to be "anchored", that is, + it is constrained to match only at the first matching point in the + string that is being searched. This effect can also be achieved by + appropriate constructs in the pattern itself such as the "^" + metacharater. + + + Specifies that first character of the string is + not the beginning of a line, so the circumflex metacharacter should + not match before it. Setting this without #G_REGEX_MULTILINE (at + compile time) causes circumflex never to match. This option affects + only the behaviour of the circumflex metacharacter, it does not + affect "\A". + + + Specifies that the end of the subject string is + not the end of a line, so the dollar metacharacter should not match + it nor (except in multiline mode) a newline immediately before it. + Setting this without #G_REGEX_MULTILINE (at compile time) causes + dollar never to match. This option affects only the behaviour of + the dollar metacharacter, it does not affect "\Z" or "\z". + + + An empty string is not considered to be a valid + match if this option is set. If there are alternatives in the pattern, + they are tried. If all the alternatives match the empty string, the + entire match fails. For example, if the pattern "a?b?" is applied to + a string not beginning with "a" or "b", it matches the empty string + at the start of the string. With this flag set, this match is not + valid, so GRegex searches further into the string for occurrences + of "a" or "b". + + + Turns on the partial matching feature, for more + documentation on partial matching see g_match_info_is_partial_match(). + + + Overrides the newline definition set when + creating a new #GRegex, setting the '\r' character as line terminator. + + + Overrides the newline definition set when + creating a new #GRegex, setting the '\n' character as line terminator. + + + Overrides the newline definition set when + creating a new #GRegex, setting the '\r\n' characters sequence as line terminator. + + + Overrides the newline definition set when + creating a new #GRegex, any Unicode newline sequence + is recognised as a newline. These are '\r', '\n' and '\rn', and the + single characters U+000B LINE TABULATION, U+000C FORM FEED (FF), + U+0085 NEXT LINE (NEL), U+2028 LINE SEPARATOR and + U+2029 PARAGRAPH SEPARATOR. + + + Overrides the newline definition set when + creating a new #GRegex; any '\r', '\n', or '\r\n' character sequence + is recognized as a newline. Since: 2.34 + + + Overrides the newline definition for "\R" set when + creating a new #GRegex; only '\r', '\n', or '\r\n' character sequences + are recognized as a newline by "\R". Since: 2.34 + + + Overrides the newline definition for "\R" set when + creating a new #GRegex; any Unicode newline character or character sequence + are recognized as a newline by "\R". These are '\r', '\n' and '\rn', and the + single characters U+000B LINE TABULATION, U+000C FORM FEED (FF), + U+0085 NEXT LINE (NEL), U+2028 LINE SEPARATOR and + U+2029 PARAGRAPH SEPARATOR. Since: 2.34 + + + An alias for #G_REGEX_MATCH_PARTIAL. Since: 2.34 + + + Turns on the partial matching feature. In contrast to + to #G_REGEX_MATCH_PARTIAL_SOFT, this stops matching as soon as a partial match + is found, without continuing to search for a possible complete match. See + g_match_info_is_partial_match() for more information. Since: 2.34 + + + Like #G_REGEX_MATCH_NOTEMPTY, but only applied to + the start of the matched string. For anchored + patterns this can only happen for pattern containing "\K". Since: 2.34 + + + + The search path separator character. +This is ':' on UNIX machines and ';' under Windows. + + + + The search path separator as a string. +This is ":" on UNIX machines and ";" under Windows. + + + + + + + + + + + + + + + + The #GSList struct is used for each element in the singly-linked +list. + + holds the element's data, which can be a pointer to any kind + of data, or any integer value using the + [Type Conversion Macros][glib-Type-Conversion-Macros] + + + + contains the link to the next element in the list. + + + + + + Allocates space for one #GSList element. It is called by the +g_slist_append(), g_slist_prepend(), g_slist_insert() and +g_slist_insert_sorted() functions and so is rarely used on its own. + + a pointer to the newly-allocated #GSList element. + + + + + + + Adds a new element on to the end of the list. + +The return value is the new start of the list, which may +have changed, so make sure you store the new value. + +Note that g_slist_append() has to traverse the entire list +to find the end, which is inefficient when adding multiple +elements. A common idiom to avoid the inefficiency is to prepend +the elements and reverse the list when all elements have been added. + +|[<!-- language="C" --> +// Notice that these are initialized to the empty list. +GSList *list = NULL, *number_list = NULL; + +// This is a list of strings. +list = g_slist_append (list, "first"); +list = g_slist_append (list, "second"); + +// This is a list of integers. +number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); +number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); +]| + + the new start of the #GSList + + + + + + + a #GSList + + + + + + the data for the new element + + + + + + Adds the second #GSList onto the end of the first #GSList. +Note that the elements of the second #GSList are not copied. +They are used directly. + + the start of the new #GSList + + + + + + + a #GSList + + + + + + the #GSList to add to the end of the first #GSList + + + + + + + + Copies a #GSList. + +Note that this is a "shallow" copy. If the list elements +consist of pointers to data, the pointers are copied but +the actual data isn't. See g_slist_copy_deep() if you need +to copy the data as well. + + a copy of @list + + + + + + + a #GSList + + + + + + + + Makes a full (deep) copy of a #GSList. + +In contrast with g_slist_copy(), this function uses @func to make a copy of +each list element, in addition to copying the list container itself. + +@func, as a #GCopyFunc, takes two arguments, the data to be copied and a user +pointer. It's safe to pass #NULL as user_data, if the copy function takes only +one argument. + +For instance, if @list holds a list of GObjects, you can do: +|[<!-- language="C" --> +another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL); +]| + +And, to entirely free the new list, you could do: +|[<!-- language="C" --> +g_slist_free_full (another_list, g_object_unref); +]| + + a full copy of @list, use #g_slist_free_full to free it + + + + + + + a #GSList + + + + + + a copy function used to copy every element in the list + + + + user data passed to the copy function @func, or #NULL + + + + + + Removes the node link_ from the list and frees it. +Compare this to g_slist_remove_link() which removes the node +without freeing it. + +Removing arbitrary nodes from a singly-linked list requires time +that is proportional to the length of the list (ie. O(n)). If you +find yourself using g_slist_delete_link() frequently, you should +consider a different data structure, such as the doubly-linked +#GList. + + the new head of @list + + + + + + + a #GSList + + + + + + node to delete + + + + + + + + Finds the element in a #GSList which +contains the given data. + + the found #GSList element, + or %NULL if it is not found + + + + + + + a #GSList + + + + + + the element data to find + + + + + + Finds an element in a #GSList, using a supplied function to +find the desired element. It iterates over the list, calling +the given function which should return 0 when the desired +element is found. The function takes two #gconstpointer arguments, +the #GSList element's data as the first argument and the +given user data. + + the found #GSList element, or %NULL if it is not found + + + + + + + a #GSList + + + + + + user data passed to the function + + + + the function to call for each element. + It should return 0 when the desired element is found + + + + + + Calls a function for each element of a #GSList. + + + + + + a #GSList + + + + + + the function to call with each element's data + + + + user data to pass to the function + + + + + + Frees all of the memory used by a #GSList. +The freed elements are returned to the slice allocator. + +If list elements contain dynamically-allocated memory, +you should either use g_slist_free_full() or free them manually +first. + + + + + + a #GSList + + + + + + + + Frees one #GSList element. +It is usually used after g_slist_remove_link(). + + + + + + a #GSList element + + + + + + + + Convenience method, which frees all the memory used by a #GSList, and +calls the specified destroy function on every element's data. + + + + + + a pointer to a #GSList + + + + + + the function to be called to free each element's data + + + + + + Gets the position of the element containing +the given data (starting from 0). + + the index of the element containing the data, + or -1 if the data is not found + + + + + a #GSList + + + + + + the data to find + + + + + + Inserts a new element into the list at the given position. + + the new start of the #GSList + + + + + + + a #GSList + + + + + + the data for the new element + + + + the position to insert the element. + If this is negative, or is larger than the number + of elements in the list, the new element is added on + to the end of the list. + + + + + + Inserts a node before @sibling containing @data. + + the new head of the list. + + + + + + + a #GSList + + + + + + node to insert @data before + + + + + + data to put in the newly-inserted node + + + + + + Inserts a new element into the list, using the given +comparison function to determine its position. + + the new start of the #GSList + + + + + + + a #GSList + + + + + + the data for the new element + + + + the function to compare elements in the list. + It should return a number > 0 if the first parameter + comes after the second parameter in the sort order. + + + + + + Inserts a new element into the list, using the given +comparison function to determine its position. + + the new start of the #GSList + + + + + + + a #GSList + + + + + + the data for the new element + + + + the function to compare elements in the list. + It should return a number > 0 if the first parameter + comes after the second parameter in the sort order. + + + + data to pass to comparison function + + + + + + Gets the last element in a #GSList. + +This function iterates over the whole list. + + the last element in the #GSList, + or %NULL if the #GSList has no elements + + + + + + + a #GSList + + + + + + + + Gets the number of elements in a #GSList. + +This function iterates over the whole list to +count its elements. To check whether the list is non-empty, it is faster to +check @list against %NULL. + + the number of elements in the #GSList + + + + + a #GSList + + + + + + + + Gets the element at the given position in a #GSList. + + the element, or %NULL if the position is off + the end of the #GSList + + + + + + + a #GSList + + + + + + the position of the element, counting from 0 + + + + + + Gets the data of the element at the given position. + + the element's data, or %NULL if the position + is off the end of the #GSList + + + + + a #GSList + + + + + + the position of the element + + + + + + Gets the position of the given element +in the #GSList (starting from 0). + + the position of the element in the #GSList, + or -1 if the element is not found + + + + + a #GSList + + + + + + an element in the #GSList + + + + + + + + Adds a new element on to the start of the list. + +The return value is the new start of the list, which +may have changed, so make sure you store the new value. + +|[<!-- language="C" --> +// Notice that it is initialized to the empty list. +GSList *list = NULL; +list = g_slist_prepend (list, "last"); +list = g_slist_prepend (list, "first"); +]| + + the new start of the #GSList + + + + + + + a #GSList + + + + + + the data for the new element + + + + + + Removes an element from a #GSList. +If two elements contain the same data, only the first is removed. +If none of the elements contain the data, the #GSList is unchanged. + + the new start of the #GSList + + + + + + + a #GSList + + + + + + the data of the element to remove + + + + + + Removes all list nodes with data equal to @data. +Returns the new head of the list. Contrast with +g_slist_remove() which removes only the first node +matching the given data. + + new head of @list + + + + + + + a #GSList + + + + + + data to remove + + + + + + Removes an element from a #GSList, without +freeing the element. The removed element's next +link is set to %NULL, so that it becomes a +self-contained list with one element. + +Removing arbitrary nodes from a singly-linked list +requires time that is proportional to the length of the list +(ie. O(n)). If you find yourself using g_slist_remove_link() +frequently, you should consider a different data structure, +such as the doubly-linked #GList. + + the new start of the #GSList, without the element + + + + + + + a #GSList + + + + + + an element in the #GSList + + + + + + + + Reverses a #GSList. + + the start of the reversed #GSList + + + + + + + a #GSList + + + + + + + + Sorts a #GSList using the given comparison function. + + the start of the sorted #GSList + + + + + + + a #GSList + + + + + + the comparison function used to sort the #GSList. + This function is passed the data from 2 elements of the #GSList + and should return 0 if they are equal, a negative value if the + first element comes before the second, or a positive value if + the first element comes after the second. + + + + + + Like g_slist_sort(), but the sort function accepts a user data argument. + + new head of the list + + + + + + + a #GSList + + + + + + comparison function + + + + data to pass to comparison function + + + + + + + Use this macro as the return value of a #GSourceFunc to leave +the #GSource in the main loop. + + + + Use this macro as the return value of a #GSourceFunc to remove +the #GSource from the main loop. + + + + The square root of two. + + + + The standard delimiters, used in g_strdelimit(). + + + + + + + + + + + + + + + + + + + + + + The data structure representing a lexical scanner. + +You should set @input_name after creating the scanner, since +it is used by the default message handler when displaying +warnings and errors. If you are scanning a file, the filename +would be a good choice. + +The @user_data and @max_parse_errors fields are not used. +If you need to associate extra data with the scanner you +can place them here. + +If you want to use your own message handler you can set the +@msg_handler field. The type of the message handler function +is declared by #GScannerMsgFunc. + + unused + + + + unused + + + + g_scanner_error() increments this field + + + + name of input stream, featured by the default message handler + + + + quarked data + + + + link into the scanner configuration + + + + token parsed by the last g_scanner_get_next_token() + + + + value of the last token from g_scanner_get_next_token() + + + + line number of the last token from g_scanner_get_next_token() + + + + char number of the last token from g_scanner_get_next_token() + + + + token parsed by the last g_scanner_peek_next_token() + + + + value of the last token from g_scanner_peek_next_token() + + + + line number of the last token from g_scanner_peek_next_token() + + + + char number of the last token from g_scanner_peek_next_token() + + + + + + + + + + + + + + + + + + + + + + + + + handler function for _warn and _error + + + + Returns the current line in the input stream (counting +from 1). This is the line of the last token parsed via +g_scanner_get_next_token(). + + the current line + + + + + a #GScanner + + + + + + Returns the current position in the current line (counting +from 0). This is the position of the last token parsed via +g_scanner_get_next_token(). + + the current position on the line + + + + + a #GScanner + + + + + + Gets the current token type. This is simply the @token +field in the #GScanner structure. + + the current token type + + + + + a #GScanner + + + + + + Gets the current token value. This is simply the @value +field in the #GScanner structure. + + the current token value + + + + + a #GScanner + + + + + + Frees all memory used by the #GScanner. + + + + + + a #GScanner + + + + + + Returns %TRUE if the scanner has reached the end of +the file or text buffer. + + %TRUE if the scanner has reached the end of + the file or text buffer + + + + + a #GScanner + + + + + + Outputs an error message, via the #GScanner message handler. + + + + + + a #GScanner + + + + the message format. See the printf() documentation + + + + the parameters to insert into the format string + + + + + + Parses the next token just like g_scanner_peek_next_token() +and also removes it from the input stream. The token data is +placed in the @token, @value, @line, and @position fields of +the #GScanner structure. + + the type of the token + + + + + a #GScanner + + + + + + Prepares to scan a file. + + + + + + a #GScanner + + + + a file descriptor + + + + + + Prepares to scan a text buffer. + + + + + + a #GScanner + + + + the text buffer to scan + + + + the length of the text buffer + + + + + + Looks up a symbol in the current scope and return its value. +If the symbol is not bound in the current scope, %NULL is +returned. + + the value of @symbol in the current scope, or %NULL + if @symbol is not bound in the current scope + + + + + a #GScanner + + + + the symbol to look up + + + + + + Parses the next token, without removing it from the input stream. +The token data is placed in the @next_token, @next_value, @next_line, +and @next_position fields of the #GScanner structure. + +Note that, while the token is not removed from the input stream +(i.e. the next call to g_scanner_get_next_token() will return the +same token), it will not be reevaluated. This can lead to surprising +results when changing scope or the scanner configuration after peeking +the next token. Getting the next token after switching the scope or +configuration will return whatever was peeked before, regardless of +any symbols that may have been added or removed in the new scope. + + the type of the token + + + + + a #GScanner + + + + + + Adds a symbol to the given scope. + + + + + + a #GScanner + + + + the scope id + + + + the symbol to add + + + + the value of the symbol + + + + + + Calls the given function for each of the symbol/value pairs +in the given scope of the #GScanner. The function is passed +the symbol and value of each pair, and the given @user_data +parameter. + + + + + + a #GScanner + + + + the scope id + + + + the function to call for each symbol/value pair + + + + user data to pass to the function + + + + + + Looks up a symbol in a scope and return its value. If the +symbol is not bound in the scope, %NULL is returned. + + the value of @symbol in the given scope, or %NULL + if @symbol is not bound in the given scope. + + + + + a #GScanner + + + + the scope id + + + + the symbol to look up + + + + + + Removes a symbol from a scope. + + + + + + a #GScanner + + + + the scope id + + + + the symbol to remove + + + + + + Sets the current scope. + + the old scope id + + + + + a #GScanner + + + + the new scope id + + + + + + Rewinds the filedescriptor to the current buffer position +and blows the file read ahead buffer. This is useful for +third party uses of the scanners filedescriptor, which hooks +onto the current scanning position. + + + + + + a #GScanner + + + + + + Outputs a message through the scanner's msg_handler, +resulting from an unexpected token in the input stream. +Note that you should not call g_scanner_peek_next_token() +followed by g_scanner_unexp_token() without an intermediate +call to g_scanner_get_next_token(), as g_scanner_unexp_token() +evaluates the scanner's current token (not the peeked token) +to construct part of the message. + + + + + + a #GScanner + + + + the expected token + + + + a string describing how the scanner's user + refers to identifiers (%NULL defaults to "identifier"). + This is used if @expected_token is %G_TOKEN_IDENTIFIER or + %G_TOKEN_IDENTIFIER_NULL. + + + + a string describing how the scanner's user refers + to symbols (%NULL defaults to "symbol"). This is used if + @expected_token is %G_TOKEN_SYMBOL or any token value greater + than %G_TOKEN_LAST. + + + + the name of the symbol, if the scanner's current + token is a symbol. + + + + a message string to output at the end of the + warning/error, or %NULL. + + + + if %TRUE it is output as an error. If %FALSE it is + output as a warning. + + + + + + Outputs a warning message, via the #GScanner message handler. + + + + + + a #GScanner + + + + the message format. See the printf() documentation + + + + the parameters to insert into the format string + + + + + + Creates a new #GScanner. + +The @config_templ structure specifies the initial settings +of the scanner, which are copied into the #GScanner +@config field. If you pass %NULL then the default settings +are used. + + the new #GScanner + + + + + the initial scanner settings + + + + + + + Specifies the #GScanner parser configuration. Most settings can +be changed during the parsing phase and will affect the lexical +parsing of the next unpeeked token. + + specifies which characters should be skipped + by the scanner (the default is the whitespace characters: space, + tab, carriage-return and line-feed). + + + + specifies the characters which can start + identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). + + + + specifies the characters which can be used + in identifiers, after the first character (the default is + #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, + #G_CSET_LATINC). + + + + specifies the characters at the start and + end of single-line comments. The default is "#\n" which means + that single-line comments start with a '#' and continue until + a '\n' (end of line). + + + + specifies if symbols are case sensitive (the + default is %FALSE). + + + + specifies if multi-line comments are skipped + and not returned as tokens (the default is %TRUE). + + + + specifies if single-line comments are skipped + and not returned as tokens (the default is %TRUE). + + + + specifies if multi-line comments are recognized + (the default is %TRUE). + + + + specifies if identifiers are recognized (the + default is %TRUE). + + + + specifies if single-character + identifiers are recognized (the default is %FALSE). + + + + specifies if %NULL is reported as + %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE). + + + + specifies if symbols are recognized (the default + is %TRUE). + + + + specifies if binary numbers are recognized (the + default is %FALSE). + + + + specifies if octal numbers are recognized (the + default is %TRUE). + + + + specifies if floating point numbers are recognized + (the default is %TRUE). + + + + specifies if hexadecimal numbers are recognized (the + default is %TRUE). + + + + specifies if '$' is recognized as a prefix for + hexadecimal numbers (the default is %FALSE). + + + + specifies if strings can be enclosed in single + quotes (the default is %TRUE). + + + + specifies if strings can be enclosed in double + quotes (the default is %TRUE). + + + + specifies if binary, octal and hexadecimal numbers + are reported as #G_TOKEN_INT (the default is %TRUE). + + + + specifies if all numbers are reported as %G_TOKEN_FLOAT + (the default is %FALSE). + + + + specifies if identifiers are reported as strings + (the default is %FALSE). + + + + specifies if characters are reported by setting + `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE). + + + + specifies if symbols are reported by setting + `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE). + + + + specifies if a symbol is searched for in the + default scope in addition to the current scope (the default is %FALSE). + + + + use value.v_int64 rather than v_int + + + + + + + + Specifies the type of the message handler function. + + + + + + a #GScanner + + + + the message + + + + %TRUE if the message signals an error, + %FALSE if it signals a warning. + + + + + + An enumeration specifying the base position for a +g_io_channel_seek_position() operation. + + the current position in the file. + + + the start of the file. + + + the end of the file. + + + + The #GSequence struct is an opaque data type representing a +[sequence][glib-Sequences] data type. + + Adds a new item to the end of @seq. + + an iterator pointing to the new item + + + + + a #GSequence + + + + the data for the new item + + + + + + Calls @func for each item in the sequence passing @user_data +to the function. + + + + + + a #GSequence + + + + the function to call for each item in @seq + + + + user data passed to @func + + + + + + Frees the memory allocated for @seq. If @seq has a data destroy +function associated with it, that function is called on all items +in @seq. + + + + + + a #GSequence + + + + + + Returns the begin iterator for @seq. + + the begin iterator for @seq. + + + + + a #GSequence + + + + + + Returns the end iterator for @seg + + the end iterator for @seq + + + + + a #GSequence + + + + + + Returns the iterator at position @pos. If @pos is negative or larger +than the number of items in @seq, the end iterator is returned. + + The #GSequenceIter at position @pos + + + + + a #GSequence + + + + a position in @seq, or -1 for the end + + + + + + Returns the length of @seq. Note that this method is O(h) where `h' is the +height of the tree. It is thus more efficient to use g_sequence_is_empty() +when comparing the length to zero. + + the length of @seq + + + + + a #GSequence + + + + + + Inserts @data into @sequence using @func to determine the new +position. The sequence must already be sorted according to @cmp_func; +otherwise the new position of @data is undefined. + +@cmp_func is called with two items of the @seq and @user_data. +It should return 0 if the items are equal, a negative value +if the first item comes before the second, and a positive value +if the second item comes before the first. + + a #GSequenceIter pointing to the new item. + + + + + a #GSequence + + + + the data to insert + + + + the function used to compare items in the sequence + + + + user data passed to @cmp_func. + + + + + + Like g_sequence_insert_sorted(), but uses +a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as +the compare function. + +@iter_cmp is called with two iterators pointing into @seq. +It should return 0 if the iterators are equal, a negative +value if the first iterator comes before the second, and a +positive value if the second iterator comes before the first. + +It is called with two iterators pointing into @seq. It should +return 0 if the iterators are equal, a negative value if the +first iterator comes before the second, and a positive value +if the second iterator comes before the first. + + a #GSequenceIter pointing to the new item + + + + + a #GSequence + + + + data for the new item + + + + the function used to compare iterators in the sequence + + + + user data passed to @cmp_func + + + + + + Returns %TRUE if the sequence contains zero items. + +This function is functionally identical to checking the result of +g_sequence_get_length() being equal to zero. However this function is +implemented in O(1) running time. + + %TRUE if the sequence is empty, otherwise %FALSE. + + + + + a #GSequence + + + + + + Returns an iterator pointing to the position of the first item found +equal to @data according to @cmp_func and @cmp_data. If more than one +item is equal, it is not guaranteed that it is the first which is +returned. In that case, you can use g_sequence_iter_next() and +g_sequence_iter_prev() to get others. + +@cmp_func is called with two items of the @seq and @user_data. +It should return 0 if the items are equal, a negative value if +the first item comes before the second, and a positive value if +the second item comes before the first. + +This function will fail if the data contained in the sequence is +unsorted. Use g_sequence_insert_sorted() or +g_sequence_insert_sorted_iter() to add data to your sequence or, if +you want to add a large amount of data, call g_sequence_sort() after +doing unsorted insertions. + + an #GSequenceIter pointing to the position of the + first item found equal to @data according to @cmp_func and + @cmp_data, or %NULL if no such item exists + + + + + a #GSequence + + + + data to lookup + + + + the function used to compare items in the sequence + + + + user data passed to @cmp_func + + + + + + Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc +instead of a #GCompareDataFunc as the compare function. + +@iter_cmp is called with two iterators pointing into @seq. +It should return 0 if the iterators are equal, a negative value +if the first iterator comes before the second, and a positive +value if the second iterator comes before the first. + +This function will fail if the data contained in the sequence is +unsorted. Use g_sequence_insert_sorted() or +g_sequence_insert_sorted_iter() to add data to your sequence or, if +you want to add a large amount of data, call g_sequence_sort() after +doing unsorted insertions. + + an #GSequenceIter pointing to the position of + the first item found equal to @data according to @cmp_func + and @cmp_data, or %NULL if no such item exists + + + + + a #GSequence + + + + data to lookup + + + + the function used to compare iterators in the sequence + + + + user data passed to @iter_cmp + + + + + + Adds a new item to the front of @seq + + an iterator pointing to the new item + + + + + a #GSequence + + + + the data for the new item + + + + + + Returns an iterator pointing to the position where @data would +be inserted according to @cmp_func and @cmp_data. + +@cmp_func is called with two items of the @seq and @user_data. +It should return 0 if the items are equal, a negative value if +the first item comes before the second, and a positive value if +the second item comes before the first. + +If you are simply searching for an existing element of the sequence, +consider using g_sequence_lookup(). + +This function will fail if the data contained in the sequence is +unsorted. Use g_sequence_insert_sorted() or +g_sequence_insert_sorted_iter() to add data to your sequence or, if +you want to add a large amount of data, call g_sequence_sort() after +doing unsorted insertions. + + an #GSequenceIter pointing to the position where @data + would have been inserted according to @cmp_func and @cmp_data + + + + + a #GSequence + + + + data for the new item + + + + the function used to compare items in the sequence + + + + user data passed to @cmp_func + + + + + + Like g_sequence_search(), but uses a #GSequenceIterCompareFunc +instead of a #GCompareDataFunc as the compare function. + +@iter_cmp is called with two iterators pointing into @seq. +It should return 0 if the iterators are equal, a negative value +if the first iterator comes before the second, and a positive +value if the second iterator comes before the first. + +If you are simply searching for an existing element of the sequence, +consider using g_sequence_lookup_iter(). + +This function will fail if the data contained in the sequence is +unsorted. Use g_sequence_insert_sorted() or +g_sequence_insert_sorted_iter() to add data to your sequence or, if +you want to add a large amount of data, call g_sequence_sort() after +doing unsorted insertions. + + a #GSequenceIter pointing to the position in @seq + where @data would have been inserted according to @iter_cmp + and @cmp_data + + + + + a #GSequence + + + + data for the new item + + + + the function used to compare iterators in the sequence + + + + user data passed to @iter_cmp + + + + + + Sorts @seq using @cmp_func. + +@cmp_func is passed two items of @seq and should +return 0 if they are equal, a negative value if the +first comes before the second, and a positive value +if the second comes before the first. + + + + + + a #GSequence + + + + the function used to sort the sequence + + + + user data passed to @cmp_func + + + + + + Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead +of a GCompareDataFunc as the compare function + +@cmp_func is called with two iterators pointing into @seq. It should +return 0 if the iterators are equal, a negative value if the first +iterator comes before the second, and a positive value if the second +iterator comes before the first. + + + + + + a #GSequence + + + + the function used to compare iterators in the sequence + + + + user data passed to @cmp_func + + + + + + Calls @func for each item in the range (@begin, @end) passing +@user_data to the function. + + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + a #GFunc + + + + user data passed to @func + + + + + + Returns the data that @iter points to. + + the data that @iter points to + + + + + a #GSequenceIter + + + + + + Inserts a new item just before the item pointed to by @iter. + + an iterator pointing to the new item + + + + + a #GSequenceIter + + + + the data for the new item + + + + + + Moves the item pointed to by @src to the position indicated by @dest. +After calling this function @dest will point to the position immediately +after @src. It is allowed for @src and @dest to point into different +sequences. + + + + + + a #GSequenceIter pointing to the item to move + + + + a #GSequenceIter pointing to the position to which + the item is moved + + + + + + Inserts the (@begin, @end) range at the destination pointed to by ptr. +The @begin and @end iters must point into the same sequence. It is +allowed for @dest to point to a different sequence than the one pointed +into by @begin and @end. + +If @dest is NULL, the range indicated by @begin and @end is +removed from the sequence. If @dest iter points to a place within +the (@begin, @end) range, the range does not move. + + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + + + Creates a new GSequence. The @data_destroy function, if non-%NULL will +be called on all items when the sequence is destroyed and on items that +are removed from the sequence. + + a new #GSequence + + + + + a #GDestroyNotify function, or %NULL + + + + + + Finds an iterator somewhere in the range (@begin, @end). This +iterator will be close to the middle of the range, but is not +guaranteed to be exactly in the middle. + +The @begin and @end iterators must both point to the same sequence +and @begin must come before or be equal to @end in the sequence. + + a #GSequenceIter pointing somewhere in the + (@begin, @end) range + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + + + Removes the item pointed to by @iter. It is an error to pass the +end iterator to this function. + +If the sequence has a data destroy function associated with it, this +function is called on the data for the removed item. + + + + + + a #GSequenceIter + + + + + + Removes all items in the (@begin, @end) range. + +If the sequence has a data destroy function associated with it, this +function is called on the data for the removed items. + + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + + + Changes the data for the item pointed to by @iter to be @data. If +the sequence has a data destroy function associated with it, that +function is called on the existing data that @iter pointed to. + + + + + + a #GSequenceIter + + + + new data for the item + + + + + + Moves the data pointed to a new position as indicated by @cmp_func. This +function should be called for items in a sequence already sorted according +to @cmp_func whenever some aspect of an item changes so that @cmp_func +may return different values for that item. + +@cmp_func is called with two items of the @seq and @user_data. +It should return 0 if the items are equal, a negative value if +the first item comes before the second, and a positive value if +the second item comes before the first. + + + + + + A #GSequenceIter + + + + the function used to compare items in the sequence + + + + user data passed to @cmp_func. + + + + + + Like g_sequence_sort_changed(), but uses +a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as +the compare function. + +@iter_cmp is called with two iterators pointing into @seq. It should +return 0 if the iterators are equal, a negative value if the first +iterator comes before the second, and a positive value if the second +iterator comes before the first. + + + + + + a #GSequenceIter + + + + the function used to compare iterators in the sequence + + + + user data passed to @cmp_func + + + + + + Swaps the items pointed to by @a and @b. It is allowed for @a and @b +to point into difference sequences. + + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + + + + The #GSequenceIter struct is an opaque data type representing an +iterator pointing into a #GSequence. + + Returns a negative number if @a comes before @b, 0 if they are equal, +and a positive number if @a comes after @b. + +The @a and @b iterators must point into the same sequence. + + a negative number if @a comes before @b, 0 if they are + equal, and a positive number if @a comes after @b + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + + + Returns the position of @iter + + the position of @iter + + + + + a #GSequenceIter + + + + + + Returns the #GSequence that @iter points into. + + the #GSequence that @iter points into + + + + + a #GSequenceIter + + + + + + Returns whether @iter is the begin iterator + + whether @iter is the begin iterator + + + + + a #GSequenceIter + + + + + + Returns whether @iter is the end iterator + + Whether @iter is the end iterator + + + + + a #GSequenceIter + + + + + + Returns the #GSequenceIter which is @delta positions away from @iter. +If @iter is closer than -@delta positions to the beginning of the sequence, +the begin iterator is returned. If @iter is closer than @delta positions +to the end of the sequence, the end iterator is returned. + + a #GSequenceIter which is @delta positions away from @iter + + + + + a #GSequenceIter + + + + A positive or negative number indicating how many positions away + from @iter the returned #GSequenceIter will be + + + + + + Returns an iterator pointing to the next position after @iter. +If @iter is the end iterator, the end iterator is returned. + + a #GSequenceIter pointing to the next position after @iter + + + + + a #GSequenceIter + + + + + + Returns an iterator pointing to the previous position before @iter. +If @iter is the begin iterator, the begin iterator is returned. + + a #GSequenceIter pointing to the previous position + before @iter + + + + + a #GSequenceIter + + + + + + + A #GSequenceIterCompareFunc is a function used to compare iterators. +It must return zero if the iterators compare equal, a negative value +if @a comes before @b, and a positive value if @b comes before @a. + + zero if the iterators are equal, a negative value if @a + comes before @b, and a positive value if @b comes before @a. + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + user data + + + + + + Error codes returned by shell functions. + + Mismatched or otherwise mangled quoting. + + + String to be parsed was empty. + + + Some other error. + + + + + + + + + + + + + + + + + + The `GSource` struct is an opaque data type +representing an event source. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Creates a new #GSource structure. The size is specified to +allow creating structures derived from #GSource that contain +additional data. The size passed in must be at least +`sizeof (GSource)`. + +The source will not initially be associated with any #GMainContext +and must be added to one with g_source_attach() before it will be +executed. + + the newly-created #GSource. + + + + + structure containing functions that implement + the sources behavior. + + + + size of the #GSource structure to create. + + + + + + Adds @child_source to @source as a "polled" source; when @source is +added to a #GMainContext, @child_source will be automatically added +with the same priority, when @child_source is triggered, it will +cause @source to dispatch (in addition to calling its own +callback), and when @source is destroyed, it will destroy +@child_source as well. (@source will also still be dispatched if +its own prepare/check functions indicate that it is ready.) + +If you don't need @child_source to do anything on its own when it +triggers, you can call g_source_set_dummy_callback() on it to set a +callback that does nothing (except return %TRUE if appropriate). + +@source will hold a reference on @child_source while @child_source +is attached to it. + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + + + + + + a #GSource + + + + a second #GSource that @source should "poll" + + + + + + Adds a file descriptor to the set of file descriptors polled for +this source. This is usually combined with g_source_new() to add an +event source. The event source's check function will typically test +the @revents field in the #GPollFD struct and return %TRUE if events need +to be processed. + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + +Using this API forces the linear scanning of event sources on each +main loop iteration. Newly-written event sources should try to use +g_source_add_unix_fd() instead of this API. + + + + + + a #GSource + + + + a #GPollFD structure holding information about a file + descriptor to watch. + + + + + + Monitors @fd for the IO events in @events. + +The tag returned by this function can be used to remove or modify the +monitoring of the fd using g_source_remove_unix_fd() or +g_source_modify_unix_fd(). + +It is not necessary to remove the fd before destroying the source; it +will be cleaned up automatically. + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + +As the name suggests, this function is not available on Windows. + + an opaque tag + + + + + a #GSource + + + + the fd to monitor + + + + an event mask + + + + + + Adds a #GSource to a @context so that it will be executed within +that context. Remove it by calling g_source_destroy(). + + the ID (greater than 0) for the source within the + #GMainContext. + + + + + a #GSource + + + + a #GMainContext (if %NULL, the default context will be used) + + + + + + Removes a source from its #GMainContext, if any, and mark it as +destroyed. The source cannot be subsequently added to another +context. It is safe to call this on sources which have already been +removed from their context. + + + + + + a #GSource + + + + + + Checks whether a source is allowed to be called recursively. +see g_source_set_can_recurse(). + + whether recursion is allowed. + + + + + a #GSource + + + + + + Gets the #GMainContext with which the source is associated. + +You can call this on a source that has been destroyed, provided +that the #GMainContext it was attached to still exists (in which +case it will return that #GMainContext). In particular, you can +always call this function on the source returned from +g_main_current_source(). But calling this function on a source +whose #GMainContext has been destroyed is an error. + + the #GMainContext with which the + source is associated, or %NULL if the context has not + yet been added to a source. + + + + + a #GSource + + + + + + This function ignores @source and is otherwise the same as +g_get_current_time(). + use g_source_get_time() instead + + + + + + a #GSource + + + + #GTimeVal structure in which to store current time. + + + + + + Returns the numeric ID for a particular source. The ID of a source +is a positive integer which is unique within a particular main loop +context. The reverse +mapping from ID to source is done by g_main_context_find_source_by_id(). + + the ID (greater than 0) for the source + + + + + a #GSource + + + + + + Gets a name for the source, used in debugging and profiling. The +name may be #NULL if it has never been set with g_source_set_name(). + + the name of the source + + + + + a #GSource + + + + + + Gets the priority of a source. + + the priority of the source + + + + + a #GSource + + + + + + Gets the "ready time" of @source, as set by +g_source_set_ready_time(). + +Any time before the current monotonic time (including 0) is an +indication that the source will fire immediately. + + the monotonic ready time, -1 for "never" + + + + + a #GSource + + + + + + Gets the time to be used when checking this source. The advantage of +calling this function over calling g_get_monotonic_time() directly is +that when checking multiple sources, GLib can cache a single value +instead of having to repeatedly get the system monotonic time. + +The time here is the system monotonic time, if available, or some +other reasonable alternative otherwise. See g_get_monotonic_time(). + + the monotonic time in microseconds + + + + + a #GSource + + + + + + Returns whether @source has been destroyed. + +This is important when you operate upon your objects +from within idle handlers, but may have freed the object +before the dispatch of your idle handler. + +|[<!-- language="C" --> +static gboolean +idle_callback (gpointer data) +{ + SomeWidget *self = data; + + GDK_THREADS_ENTER (); + // do stuff with self + self->idle_id = 0; + GDK_THREADS_LEAVE (); + + return G_SOURCE_REMOVE; +} + +static void +some_widget_do_stuff_later (SomeWidget *self) +{ + self->idle_id = g_idle_add (idle_callback, self); +} + +static void +some_widget_finalize (GObject *object) +{ + SomeWidget *self = SOME_WIDGET (object); + + if (self->idle_id) + g_source_remove (self->idle_id); + + G_OBJECT_CLASS (parent_class)->finalize (object); +} +]| + +This will fail in a multi-threaded application if the +widget is destroyed before the idle handler fires due +to the use after free in the callback. A solution, to +this particular problem, is to check to if the source +has already been destroy within the callback. + +|[<!-- language="C" --> +static gboolean +idle_callback (gpointer data) +{ + SomeWidget *self = data; + + GDK_THREADS_ENTER (); + if (!g_source_is_destroyed (g_main_current_source ())) + { + // do stuff with self + } + GDK_THREADS_LEAVE (); + + return FALSE; +} +]| + + %TRUE if the source has been destroyed + + + + + a #GSource + + + + + + Updates the event mask to watch for the fd identified by @tag. + +@tag is the tag returned from g_source_add_unix_fd(). + +If you want to remove a fd, don't set its event mask to zero. +Instead, call g_source_remove_unix_fd(). + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + +As the name suggests, this function is not available on Windows. + + + + + + a #GSource + + + + the tag from g_source_add_unix_fd() + + + + the new event mask to watch + + + + + + Queries the events reported for the fd corresponding to @tag on +@source during the last poll. + +The return value of this function is only defined when the function +is called from the check or dispatch functions for @source. + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + +As the name suggests, this function is not available on Windows. + + the conditions reported on the fd + + + + + a #GSource + + + + the tag from g_source_add_unix_fd() + + + + + + Increases the reference count on a source by one. + + @source + + + + + a #GSource + + + + + + Detaches @child_source from @source and destroys it. + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + + + + + + a #GSource + + + + a #GSource previously passed to + g_source_add_child_source(). + + + + + + Removes a file descriptor from the set of file descriptors polled for +this source. + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + + + + + + a #GSource + + + + a #GPollFD structure previously passed to g_source_add_poll(). + + + + + + Reverses the effect of a previous call to g_source_add_unix_fd(). + +You only need to call this if you want to remove an fd from being +watched while keeping the same source around. In the normal case you +will just want to destroy the source. + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + +As the name suggests, this function is not available on Windows. + + + + + + a #GSource + + + + the tag from g_source_add_unix_fd() + + + + + + Sets the callback function for a source. The callback for a source is +called from the source's dispatch function. + +The exact type of @func depends on the type of source; ie. you +should not count on @func being called with @data as its first +parameter. + +See [memory management of sources][mainloop-memory-management] for details +on how to handle memory management of @data. + +Typically, you won't use this function. Instead use functions specific +to the type of source you are using. + + + + + + the source + + + + a callback function + + + + the data to pass to callback function + + + + a function to call when @data is no longer in use, or %NULL. + + + + + + Sets the callback function storing the data as a refcounted callback +"object". This is used internally. Note that calling +g_source_set_callback_indirect() assumes +an initial reference count on @callback_data, and thus +@callback_funcs->unref will eventually be called once more +than @callback_funcs->ref. + + + + + + the source + + + + pointer to callback data "object" + + + + functions for reference counting @callback_data + and getting the callback and data + + + + + + Sets whether a source can be called recursively. If @can_recurse is +%TRUE, then while the source is being dispatched then this source +will be processed normally. Otherwise, all processing of this +source is blocked until the dispatch function returns. + + + + + + a #GSource + + + + whether recursion is allowed for this source + + + + + + Sets the source functions (can be used to override +default implementations) of an unattached source. + + + + + + a #GSource + + + + the new #GSourceFuncs + + + + + + Sets a name for the source, used in debugging and profiling. +The name defaults to #NULL. + +The source name should describe in a human-readable way +what the source does. For example, "X11 event queue" +or "GTK+ repaint idle handler" or whatever it is. + +It is permitted to call this function multiple times, but is not +recommended due to the potential performance impact. For example, +one could change the name in the "check" function of a #GSourceFuncs +to include details like the event type in the source name. + +Use caution if changing the name while another thread may be +accessing it with g_source_get_name(); that function does not copy +the value, and changing the value will free it while the other thread +may be attempting to use it. + + + + + + a #GSource + + + + debug name for the source + + + + + + Sets the priority of a source. While the main loop is being run, a +source will be dispatched if it is ready to be dispatched and no +sources at a higher (numerically smaller) priority are ready to be +dispatched. + +A child source always has the same priority as its parent. It is not +permitted to change the priority of a source once it has been added +as a child of another source. + + + + + + a #GSource + + + + the new priority. + + + + + + Sets a #GSource to be dispatched when the given monotonic time is +reached (or passed). If the monotonic time is in the past (as it +always will be if @ready_time is 0) then the source will be +dispatched immediately. + +If @ready_time is -1 then the source is never woken up on the basis +of the passage of time. + +Dispatching the source does not reset the ready time. You should do +so yourself, from the source dispatch function. + +Note that if you have a pair of sources where the ready time of one +suggests that it will be delivered first but the priority for the +other suggests that it would be delivered first, and the ready time +for both sources is reached during the same main context iteration +then the order of dispatch is undefined. + +This API is only intended to be used by implementations of #GSource. +Do not call this API on a #GSource that you did not create. + + + + + + a #GSource + + + + the monotonic time at which the source will be ready, + 0 for "immediately", -1 for "never" + + + + + + Decreases the reference count of a source by one. If the +resulting reference count is zero the source and associated +memory will be destroyed. + + + + + + a #GSource + + + + + + Removes the source with the given id from the default main context. + +The id of a #GSource is given by g_source_get_id(), or will be +returned by the functions g_source_attach(), g_idle_add(), +g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), +g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and +g_io_add_watch_full(). + +See also g_source_destroy(). You must use g_source_destroy() for sources +added to a non-default main context. + +It is a programmer error to attempt to remove a non-existent source. + +More specifically: source IDs can be reissued after a source has been +destroyed and therefore it is never valid to use this function with a +source ID which may have already been removed. An example is when +scheduling an idle to run in another thread with g_idle_add(): the +idle may already have run and been removed by the time this function +is called on its (now invalid) source ID. This source ID may have +been reissued, leading to the operation being performed against the +wrong source. + + For historical reasons, this function always returns %TRUE + + + + + the ID of the source to remove. + + + + + + Removes a source from the default main loop context given the +source functions and user data. If multiple sources exist with the +same source functions and user data, only one will be destroyed. + + %TRUE if a source was found and removed. + + + + + The @source_funcs passed to g_source_new() + + + + the user data for the callback + + + + + + Removes a source from the default main loop context given the user +data for the callback. If multiple sources exist with the same user +data, only one will be destroyed. + + %TRUE if a source was found and removed. + + + + + the user_data for the callback. + + + + + + Sets the name of a source using its ID. + +This is a convenience utility to set source names from the return +value of g_idle_add(), g_timeout_add(), etc. + +It is a programmer error to attempt to set the name of a non-existent +source. + +More specifically: source IDs can be reissued after a source has been +destroyed and therefore it is never valid to use this function with a +source ID which may have already been removed. An example is when +scheduling an idle to run in another thread with g_idle_add(): the +idle may already have run and been removed by the time this function +is called on its (now invalid) source ID. This source ID may have +been reissued, leading to the operation being performed against the +wrong source. + + + + + + a #GSource ID + + + + debug name for the source + + + + + + + The `GSourceCallbackFuncs` struct contains +functions for managing callback objects. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This is just a placeholder for #GClosureMarshal, +which cannot be used here for dependency reasons. + + + + + + Specifies the type of function passed to g_timeout_add(), +g_timeout_add_full(), g_idle_add(), and g_idle_add_full(). + + %FALSE if the source should be removed. #G_SOURCE_CONTINUE and +#G_SOURCE_REMOVE are more memorable names for the return value. + + + + + data passed to the function, set when the source was + created with one of the above functions + + + + + + The `GSourceFuncs` struct contains a table of +functions used to handle event sources in a generic manner. + +For idle sources, the prepare and check functions always return %TRUE +to indicate that the source is always ready to be processed. The prepare +function also returns a timeout value of 0 to ensure that the poll() call +doesn't block (since that would be time wasted which could have been spent +running the idle function). + +For timeout sources, the prepare and check functions both return %TRUE +if the timeout interval has expired. The prepare function also returns +a timeout value to ensure that the poll() call doesn't block too long +and miss the next timeout. + +For file descriptor sources, the prepare function typically returns %FALSE, +since it must wait until poll() has been called before it knows whether +any events need to be processed. It sets the returned timeout to -1 to +indicate that it doesn't mind how long the poll() call blocks. In the +check function, it tests the results of the poll() call to see if the +required condition has been met, and returns %TRUE if so. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specifies the type of the setup function passed to g_spawn_async(), +g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very +limited ways, be used to affect the child's execution. + +On POSIX platforms, the function is called in the child after GLib +has performed all the setup it plans to perform, but before calling +exec(). Actions taken in this function will only affect the child, +not the parent. + +On Windows, the function is called in the parent. Its usefulness on +Windows is thus questionable. In many cases executing the child setup +function in the parent can have ill effects, and you should be very +careful when porting software to Windows that uses child setup +functions. + +However, even on POSIX, you are extremely limited in what you can +safely do from a #GSpawnChildSetupFunc, because any mutexes that were +held by other threads in the parent process at the time of the fork() +will still be locked in the child process, and they will never be +unlocked (since the threads that held them don't exist in the child). +POSIX allows only async-signal-safe functions (see signal(7)) to be +called in the child between fork() and exec(), which drastically limits +the usefulness of child setup functions. + +In particular, it is not safe to call any function which may +call malloc(), which includes POSIX functions such as setenv(). +If you need to set up the child environment differently from +the parent, you should use g_get_environ(), g_environ_setenv(), +and g_environ_unsetenv(), and then pass the complete environment +list to the `g_spawn...` function. + + + + + + user data to pass to the function. + + + + + + Error codes returned by spawning processes. + + Fork failed due to lack of memory. + + + Read or select on pipes failed. + + + Changing to working directory failed. + + + execv() returned `EACCES` + + + execv() returned `EPERM` + + + execv() returned `E2BIG` + + + deprecated alias for %G_SPAWN_ERROR_TOO_BIG + + + execv() returned `ENOEXEC` + + + execv() returned `ENAMETOOLONG` + + + execv() returned `ENOENT` + + + execv() returned `ENOMEM` + + + execv() returned `ENOTDIR` + + + execv() returned `ELOOP` + + + execv() returned `ETXTBUSY` + + + execv() returned `EIO` + + + execv() returned `ENFILE` + + + execv() returned `EMFILE` + + + execv() returned `EINVAL` + + + execv() returned `EISDIR` + + + execv() returned `ELIBBAD` + + + Some other fatal failure, + `error->message` should explain. + + + + Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes(). + + no flags, default behaviour + + + the parent's open file descriptors will + be inherited by the child; otherwise all descriptors except stdin, + stdout and stderr will be closed before calling exec() in the child. + + + the child will not be automatically reaped; + you must use g_child_watch_add() yourself (or call waitpid() or handle + `SIGCHLD` yourself), or the child will become a zombie. + + + `argv[0]` need not be an absolute path, it will be + looked for in the user's `PATH`. + + + the child's standard output will be discarded, + instead of going to the same location as the parent's standard output. + + + the child's standard error will be discarded. + + + the child will inherit the parent's standard + input (by default, the child's standard input is attached to `/dev/null`). + + + the first element of `argv` is the file to + execute, while the remaining elements are the actual argument vector + to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]` + as the file to execute, and passes all of `argv` to the child. + + + if `argv[0]` is not an abolute path, + it will be looked for in the `PATH` from the passed child environment. + Since: 2.34 + + + create all pipes with the `O_CLOEXEC` flag set. + Since: 2.40 + + + + A type corresponding to the appropriate struct type for the stat() +system call, depending on the platform and/or compiler being used. + +See g_stat() for more information. + + + The GString struct contains the public fields of a GString. + + points to the character data. It may move as text is added. + The @str field is null-terminated and so + can be used as an ordinary C string. + + + + contains the length of the string, not including the + terminating nul byte. + + + + the number of bytes that can be stored in the + string before it needs to be reallocated. May be larger than @len. + + + + Adds a string onto the end of a #GString, expanding +it if necessary. + + @string + + + + + a #GString + + + + the string to append onto the end of @string + + + + + + Adds a byte onto the end of a #GString, expanding +it if necessary. + + @string + + + + + a #GString + + + + the byte to append onto the end of @string + + + + + + Appends @len bytes of @val to @string. Because @len is +provided, @val may contain embedded nuls and need not +be nul-terminated. + +Since this function does not stop at nul bytes, it is +the caller's responsibility to ensure that @val has at +least @len addressable bytes. + + @string + + + + + a #GString + + + + bytes to append + + + + number of bytes of @val to use + + + + + + Appends a formatted string onto the end of a #GString. +This function is similar to g_string_printf() except +that the text is appended to the #GString. + + + + + + a #GString + + + + the string format. See the printf() documentation + + + + the parameters to insert into the format string + + + + + + Converts a Unicode character into UTF-8, and appends it +to the string. + + @string + + + + + a #GString + + + + a Unicode character + + + + + + Appends @unescaped to @string, escaped any characters that +are reserved in URIs using URI-style escape sequences. + + @string + + + + + a #GString + + + + a string + + + + a string of reserved characters allowed + to be used, or %NULL + + + + set %TRUE if the escaped string may include UTF8 characters + + + + + + Appends a formatted string onto the end of a #GString. +This function is similar to g_string_append_printf() +except that the arguments to the format string are passed +as a va_list. + + + + + + a #GString + + + + the string format. See the printf() documentation + + + + the list of arguments to insert in the output + + + + + + Converts all uppercase ASCII letters to lowercase ASCII letters. + + passed-in @string pointer, with all the + uppercase characters converted to lowercase in place, + with semantics that exactly match g_ascii_tolower(). + + + + + a GString + + + + + + Converts all lowercase ASCII letters to uppercase ASCII letters. + + passed-in @string pointer, with all the + lowercase characters converted to uppercase in place, + with semantics that exactly match g_ascii_toupper(). + + + + + a GString + + + + + + Copies the bytes from a string into a #GString, +destroying any previous contents. It is rather like +the standard strcpy() function, except that you do not +have to worry about having enough space to copy the string. + + @string + + + + + the destination #GString. Its current contents + are destroyed. + + + + the string to copy into @string + + + + + + Converts a #GString to lowercase. + This function uses the locale-specific + tolower() function, which is almost never the right thing. + Use g_string_ascii_down() or g_utf8_strdown() instead. + + the #GString + + + + + a #GString + + + + + + Compares two strings for equality, returning %TRUE if they are equal. +For use with #GHashTable. + + %TRUE if the strings are the same length and contain the + same bytes + + + + + a #GString + + + + another #GString + + + + + + Removes @len bytes from a #GString, starting at position @pos. +The rest of the #GString is shifted down to fill the gap. + + @string + + + + + a #GString + + + + the position of the content to remove + + + + the number of bytes to remove, or -1 to remove all + following bytes + + + + + + Frees the memory allocated for the #GString. +If @free_segment is %TRUE it also frees the character data. If +it's %FALSE, the caller gains ownership of the buffer and must +free it after use with g_free(). + + the character data of @string + (i.e. %NULL if @free_segment is %TRUE) + + + + + a #GString + + + + if %TRUE, the actual character data is freed as well + + + + + + Transfers ownership of the contents of @string to a newly allocated +#GBytes. The #GString structure itself is deallocated, and it is +therefore invalid to use @string after invoking this function. + +Note that while #GString ensures that its buffer always has a +trailing nul character (not reflected in its "len"), the returned +#GBytes does not include this extra nul; i.e. it has length exactly +equal to the "len" member. + + A newly allocated #GBytes containing contents of @string; @string itself is freed + + + + + a #GString + + + + + + Creates a hash code for @str; for use with #GHashTable. + + hash code for @str + + + + + a string to hash + + + + + + Inserts a copy of a string into a #GString, +expanding it if necessary. + + @string + + + + + a #GString + + + + the position to insert the copy of the string + + + + the string to insert + + + + + + Inserts a byte into a #GString, expanding it if necessary. + + @string + + + + + a #GString + + + + the position to insert the byte + + + + the byte to insert + + + + + + Inserts @len bytes of @val into @string at @pos. +Because @len is provided, @val may contain embedded +nuls and need not be nul-terminated. If @pos is -1, +bytes are inserted at the end of the string. + +Since this function does not stop at nul bytes, it is +the caller's responsibility to ensure that @val has at +least @len addressable bytes. + + @string + + + + + a #GString + + + + position in @string where insertion should + happen, or -1 for at the end + + + + bytes to insert + + + + number of bytes of @val to insert + + + + + + Converts a Unicode character into UTF-8, and insert it +into the string at the given position. + + @string + + + + + a #GString + + + + the position at which to insert character, or -1 + to append at the end of the string + + + + a Unicode character + + + + + + Overwrites part of a string, lengthening it if necessary. + + @string + + + + + a #GString + + + + the position at which to start overwriting + + + + the string that will overwrite the @string starting at @pos + + + + + + Overwrites part of a string, lengthening it if necessary. +This function will work with embedded nuls. + + @string + + + + + a #GString + + + + the position at which to start overwriting + + + + the string that will overwrite the @string starting at @pos + + + + the number of bytes to write from @val + + + + + + Adds a string on to the start of a #GString, +expanding it if necessary. + + @string + + + + + a #GString + + + + the string to prepend on the start of @string + + + + + + Adds a byte onto the start of a #GString, +expanding it if necessary. + + @string + + + + + a #GString + + + + the byte to prepend on the start of the #GString + + + + + + Prepends @len bytes of @val to @string. +Because @len is provided, @val may contain +embedded nuls and need not be nul-terminated. + +Since this function does not stop at nul bytes, +it is the caller's responsibility to ensure that +@val has at least @len addressable bytes. + + @string + + + + + a #GString + + + + bytes to prepend + + + + number of bytes in @val to prepend + + + + + + Converts a Unicode character into UTF-8, and prepends it +to the string. + + @string + + + + + a #GString + + + + a Unicode character + + + + + + Writes a formatted string into a #GString. +This is similar to the standard sprintf() function, +except that the #GString buffer automatically expands +to contain the results. The previous contents of the +#GString are destroyed. + + + + + + a #GString + + + + the string format. See the printf() documentation + + + + the parameters to insert into the format string + + + + + + Sets the length of a #GString. If the length is less than +the current length, the string will be truncated. If the +length is greater than the current length, the contents +of the newly added area are undefined. (However, as +always, string->str[string->len] will be a nul byte.) + + @string + + + + + a #GString + + + + the new length + + + + + + Cuts off the end of the GString, leaving the first @len bytes. + + @string + + + + + a #GString + + + + the new size of @string + + + + + + Converts a #GString to uppercase. + This function uses the locale-specific + toupper() function, which is almost never the right thing. + Use g_string_ascii_up() or g_utf8_strup() instead. + + @string + + + + + a #GString + + + + + + Writes a formatted string into a #GString. +This function is similar to g_string_printf() except that +the arguments to the format string are passed as a va_list. + + + + + + a #GString + + + + the string format. See the printf() documentation + + + + the parameters to insert into the format string + + + + + + + An opaque data structure representing String Chunks. +It should only be accessed by using the following functions. + + Frees all strings contained within the #GStringChunk. +After calling g_string_chunk_clear() it is not safe to +access any of the strings which were contained within it. + + + + + + a #GStringChunk + + + + + + Frees all memory allocated by the #GStringChunk. +After calling g_string_chunk_free() it is not safe to +access any of the strings which were contained within it. + + + + + + a #GStringChunk + + + + + + Adds a copy of @string to the #GStringChunk. +It returns a pointer to the new copy of the string +in the #GStringChunk. The characters in the string +can be changed, if necessary, though you should not +change anything after the end of the string. + +Unlike g_string_chunk_insert_const(), this function +does not check for duplicates. Also strings added +with g_string_chunk_insert() will not be searched +by g_string_chunk_insert_const() when looking for +duplicates. + + a pointer to the copy of @string within + the #GStringChunk + + + + + a #GStringChunk + + + + the string to add + + + + + + Adds a copy of @string to the #GStringChunk, unless the same +string has already been added to the #GStringChunk with +g_string_chunk_insert_const(). + +This function is useful if you need to copy a large number +of strings but do not want to waste space storing duplicates. +But you must remember that there may be several pointers to +the same string, and so any changes made to the strings +should be done very carefully. + +Note that g_string_chunk_insert_const() will not return a +pointer to a string added with g_string_chunk_insert(), even +if they do match. + + a pointer to the new or existing copy of @string + within the #GStringChunk + + + + + a #GStringChunk + + + + the string to add + + + + + + Adds a copy of the first @len bytes of @string to the #GStringChunk. +The copy is nul-terminated. + +Since this function does not stop at nul bytes, it is the caller's +responsibility to ensure that @string has at least @len addressable +bytes. + +The characters in the returned string can be changed, if necessary, +though you should not change anything after the end of the string. + + a pointer to the copy of @string within the #GStringChunk + + + + + a #GStringChunk + + + + bytes to insert + + + + number of bytes of @string to insert, or -1 to insert a + nul-terminated string + + + + + + Creates a new #GStringChunk. + + a new #GStringChunk + + + + + the default size of the blocks of memory which are + allocated to store the strings. If a particular string + is larger than this default size, a larger block of + memory will be allocated for it. + + + + + + + Evaluates to a time span of one day. + + + + Evaluates to a time span of one hour. + + + + Evaluates to a time span of one millisecond. + + + + Evaluates to a time span of one minute. + + + + Evaluates to a time span of one second. + + + + An opaque structure representing a test case. + + + + + + + + + + + + + + + + + + + + + + + The type used for test case functions that take an extra pointer +argument. + + + + + + the data provided when registering the test + + + + + + The type of file to return the filename for, when used with +g_test_build_filename(). + +These two options correspond rather directly to the 'dist' and +'built' terminology that automake uses and are explicitly used to +distinguish between the 'srcdir' and 'builddir' being separate. All +files in your project should either be dist (in the +`DIST_EXTRA` or `dist_schema_DATA` +sense, in which case they will always be in the srcdir) or built (in +the `BUILT_SOURCES` sense, in which case they will +always be in the builddir). + +Note: as a general rule of automake, files that are generated only as +part of the build-from-git process (but then are distributed with the +tarball) always go in srcdir (even if doing a srcdir != builddir +build from git) and are considered as distributed files. + + a file that was included in the distribution tarball + + + a file that was built on the compiling machine + + + + The type used for functions that operate on test fixtures. This is +used for the fixture setup and teardown functions as well as for the +testcases themselves. + +@user_data is a pointer to the data that was given when registering +the test case. + +@fixture will be a pointer to the area of memory allocated by the +test framework, of the size requested. If the requested size was +zero then @fixture will be equal to @user_data. + + + + + + the test fixture + + + + the data provided when registering the test + + + + + + The type used for test case functions. + + + + + + + + + + + + + + + Internal function for gtester to free test log messages, no ABI guarantees provided. + + + + + + + + + + + Internal function for gtester to retrieve test log messages, no ABI guarantees provided. + + + + + + + + + + + Internal function for gtester to decode test log messages, no ABI guarantees provided. + + + + + + + + + + + + + + + + + Internal function for gtester to decode test log messages, no ABI guarantees provided. + + + + + + + Specifies the prototype of fatal log handler functions. + + %TRUE if the program should abort, %FALSE otherwise + + + + + the log domain of the message + + + + the log level of the message (including the fatal and recursion flags) + + + + the message to process + + + + user data, set in g_test_log_set_fatal_handler() + + + + + + + + + + + + + + + + + + + + + + Internal function for gtester to free test log messages, no ABI guarantees provided. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Flags to pass to g_test_trap_subprocess() to control input and output. + +Note that in contrast with g_test_trap_fork(), the default is to +not show stdout and stderr. + + If this flag is given, the child + process will inherit the parent's stdin. Otherwise, the child's + stdin is redirected to `/dev/null`. + + + If this flag is given, the child + process will inherit the parent's stdout. Otherwise, the child's + stdout will not be visible, but it will be captured to allow + later tests with g_test_trap_assert_stdout(). + + + If this flag is given, the child + process will inherit the parent's stderr. Otherwise, the child's + stderr will not be visible, but it will be captured to allow + later tests with g_test_trap_assert_stderr(). + + + + An opaque structure representing a test suite. + + Adds @test_case to @suite. + + + + + + a #GTestSuite + + + + a #GTestCase + + + + + + Adds @nestedsuite to @suite. + + + + + + a #GTestSuite + + + + another #GTestSuite + + + + + + + Test traps are guards around forked tests. +These flags determine what traps to set. + #GTestTrapFlags is used only with g_test_trap_fork(), +which is deprecated. g_test_trap_subprocess() uses +#GTestTrapSubprocessFlags. + + Redirect stdout of the test child to + `/dev/null` so it cannot be observed on the console during test + runs. The actual output is still captured though to allow later + tests with g_test_trap_assert_stdout(). + + + Redirect stderr of the test child to + `/dev/null` so it cannot be observed on the console during test + runs. The actual output is still captured though to allow later + tests with g_test_trap_assert_stderr(). + + + If this flag is given, stdin of the + child process is shared with stdin of its parent process. + It is redirected to `/dev/null` otherwise. + + + + The #GThread struct represents a running thread. This struct +is returned by g_thread_new() or g_thread_try_new(). You can +obtain the #GThread struct representing the current thread by +calling g_thread_self(). + +GThread is refcounted, see g_thread_ref() and g_thread_unref(). +The thread represented by it holds a reference while it is running, +and g_thread_join() consumes the reference that it is given, so +it is normally not necessary to manage GThread references +explicitly. + +The structure is opaque -- none of its fields may be directly +accessed. + + This function creates a new thread. The new thread starts by invoking +@func with the argument data. The thread will run until @func returns +or until g_thread_exit() is called from the new thread. The return value +of @func becomes the return value of the thread, which can be obtained +with g_thread_join(). + +The @name can be useful for discriminating threads in a debugger. +It is not used for other purposes and does not have to be unique. +Some systems restrict the length of @name to 16 bytes. + +If the thread can not be created the program aborts. See +g_thread_try_new() if you want to attempt to deal with failures. + +If you are using threads to offload (potentially many) short-lived tasks, +#GThreadPool may be more appropriate than manually spawning and tracking +multiple #GThreads. + +To free the struct returned by this function, use g_thread_unref(). +Note that g_thread_join() implicitly unrefs the #GThread as well. + + the new #GThread + + + + + an (optional) name for the new thread + + + + a function to execute in the new thread + + + + an argument to supply to the new thread + + + + + + This function is the same as g_thread_new() except that +it allows for the possibility of failure. + +If a thread can not be created (due to resource limits), +@error is set and %NULL is returned. + + the new #GThread, or %NULL if an error occurred + + + + + an (optional) name for the new thread + + + + a function to execute in the new thread + + + + an argument to supply to the new thread + + + + + + Waits until @thread finishes, i.e. the function @func, as +given to g_thread_new(), returns or g_thread_exit() is called. +If @thread has already terminated, then g_thread_join() +returns immediately. + +Any thread can wait for any other thread by calling g_thread_join(), +not just its 'creator'. Calling g_thread_join() from multiple threads +for the same @thread leads to undefined behaviour. + +The value returned by @func or given to g_thread_exit() is +returned by this function. + +g_thread_join() consumes the reference to the passed-in @thread. +This will usually cause the #GThread struct and associated resources +to be freed. Use g_thread_ref() to obtain an extra reference if you +want to keep the GThread alive beyond the g_thread_join() call. + + the return value of the thread + + + + + a #GThread + + + + + + Increase the reference count on @thread. + + a new reference to @thread + + + + + a #GThread + + + + + + Decrease the reference count on @thread, possibly freeing all +resources associated with it. + +Note that each thread holds a reference to its #GThread while +it is running, so it is safe to drop your own reference to it +if you don't need it anymore. + + + + + + a #GThread + + + + + + + + + + + Terminates the current thread. + +If another thread is waiting for us using g_thread_join() then the +waiting thread will be woken up and get @retval as the return value +of g_thread_join(). + +Calling g_thread_exit() with a parameter @retval is equivalent to +returning @retval from the function @func, as given to g_thread_new(). + +You must only call g_thread_exit() from a thread that you created +yourself with g_thread_new() or related APIs. You must not call +this function from a thread created with another threading library +or or from within a #GThreadPool. + + + + + + the return value of this thread + + + + + + This function returns the #GThread corresponding to the +current thread. Note that this function does not increase +the reference count of the returned struct. + +This function will return a #GThread even for threads that +were not created by GLib (i.e. those created by other threading +APIs). This may be useful for thread identification purposes +(i.e. comparisons) but you must not use GLib functions (such +as g_thread_join()) on these threads. + + the #GThread representing the current thread + + + + + Causes the calling thread to voluntarily relinquish the CPU, so +that other threads can run. + +This function is often used as a method to make busy wait less evil. + + + + + + + Possible errors of thread related functions. + + a thread couldn't be created due to resource + shortage. Try again later. + + + + Specifies the type of the @func functions passed to g_thread_new() +or g_thread_try_new(). + + the return value of the thread + + + + + data passed to the thread + + + + + + The #GThreadPool struct represents a thread pool. It has three +public read-only members, but the underlying struct is bigger, +so you must not copy this struct. + + the function to execute in the threads of this pool + + + + the user data for the threads of this pool + + + + are all threads exclusive to this pool + + + + Frees all resources allocated for @pool. + +If @immediate is %TRUE, no new task is processed for @pool. +Otherwise @pool is not freed before the last task is processed. +Note however, that no thread of this pool is interrupted while +processing a task. Instead at least all still running threads +can finish their tasks before the @pool is freed. + +If @wait_ is %TRUE, the functions does not return before all +tasks to be processed (dependent on @immediate, whether all +or only the currently running) are ready. +Otherwise the function returns immediately. + +After calling this function @pool must not be used anymore. + + + + + + a #GThreadPool + + + + should @pool shut down immediately? + + + + should the function wait for all tasks to be finished? + + + + + + Returns the maximal number of threads for @pool. + + the maximal number of threads + + + + + a #GThreadPool + + + + + + Returns the number of threads currently running in @pool. + + the number of threads currently running + + + + + a #GThreadPool + + + + + + Moves the item to the front of the queue of unprocessed +items, so that it will be processed next. + + %TRUE if the item was found and moved + + + + + a #GThreadPool + + + + an unprocessed item in the pool + + + + + + Inserts @data into the list of tasks to be executed by @pool. + +When the number of currently running threads is lower than the +maximal allowed number of threads, a new thread is started (or +reused) with the properties given to g_thread_pool_new(). +Otherwise, @data stays in the queue until a thread in this pool +finishes its previous task and processes @data. + +@error can be %NULL to ignore errors, or non-%NULL to report +errors. An error can only occur when a new thread couldn't be +created. In that case @data is simply appended to the queue of +work to do. + +Before version 2.32, this function did not return a success status. + + %TRUE on success, %FALSE if an error occurred + + + + + a #GThreadPool + + + + a new task for @pool + + + + + + Sets the maximal allowed number of threads for @pool. +A value of -1 means that the maximal number of threads +is unlimited. If @pool is an exclusive thread pool, setting +the maximal number of threads to -1 is not allowed. + +Setting @max_threads to 0 means stopping all work for @pool. +It is effectively frozen until @max_threads is set to a non-zero +value again. + +A thread is never terminated while calling @func, as supplied by +g_thread_pool_new(). Instead the maximal number of threads only +has effect for the allocation of new threads in g_thread_pool_push(). +A new thread is allocated, whenever the number of currently +running threads in @pool is smaller than the maximal number. + +@error can be %NULL to ignore errors, or non-%NULL to report +errors. An error can only occur when a new thread couldn't be +created. + +Before version 2.32, this function did not return a success status. + + %TRUE on success, %FALSE if an error occurred + + + + + a #GThreadPool + + + + a new maximal number of threads for @pool, + or -1 for unlimited + + + + + + Sets the function used to sort the list of tasks. This allows the +tasks to be processed by a priority determined by @func, and not +just in the order in which they were added to the pool. + +Note, if the maximum number of threads is more than 1, the order +that threads are executed cannot be guaranteed 100%. Threads are +scheduled by the operating system and are executed at random. It +cannot be assumed that threads are executed in the order they are +created. + + + + + + a #GThreadPool + + + + the #GCompareDataFunc used to sort the list of tasks. + This function is passed two tasks. It should return + 0 if the order in which they are handled does not matter, + a negative value if the first task should be processed before + the second or a positive value if the second task should be + processed first. + + + + user data passed to @func + + + + + + Returns the number of tasks still unprocessed in @pool. + + the number of unprocessed tasks + + + + + a #GThreadPool + + + + + + This function will return the maximum @interval that a +thread will wait in the thread pool for new tasks before +being stopped. + +If this function returns 0, threads waiting in the thread +pool for new work are not stopped. + + the maximum @interval (milliseconds) to wait + for new tasks in the thread pool before stopping the + thread + + + + + Returns the maximal allowed number of unused threads. + + the maximal number of unused threads + + + + + Returns the number of currently unused threads. + + the number of currently unused threads + + + + + This function creates a new thread pool. + +Whenever you call g_thread_pool_push(), either a new thread is +created or an unused one is reused. At most @max_threads threads +are running concurrently for this thread pool. @max_threads = -1 +allows unlimited threads to be created for this thread pool. The +newly created or reused thread now executes the function @func +with the two arguments. The first one is the parameter to +g_thread_pool_push() and the second one is @user_data. + +The parameter @exclusive determines whether the thread pool owns +all threads exclusive or shares them with other thread pools. +If @exclusive is %TRUE, @max_threads threads are started +immediately and they will run exclusively for this thread pool +until it is destroyed by g_thread_pool_free(). If @exclusive is +%FALSE, threads are created when needed and shared between all +non-exclusive thread pools. This implies that @max_threads may +not be -1 for exclusive thread pools. Besides, exclusive thread +pools are not affected by g_thread_pool_set_max_idle_time() +since their threads are never considered idle and returned to the +global pool. + +@error can be %NULL to ignore errors, or non-%NULL to report +errors. An error can only occur when @exclusive is set to %TRUE +and not all @max_threads threads could be created. +See #GThreadError for possible errors that may occur. +Note, even in case of error a valid #GThreadPool is returned. + + the new #GThreadPool + + + + + a function to execute in the threads of the new thread pool + + + + user data that is handed over to @func every time it + is called + + + + the maximal number of threads to execute concurrently + in the new thread pool, -1 means no limit + + + + should this thread pool be exclusive? + + + + + + This function will set the maximum @interval that a thread +waiting in the pool for new tasks can be idle for before +being stopped. This function is similar to calling +g_thread_pool_stop_unused_threads() on a regular timeout, +except this is done on a per thread basis. + +By setting @interval to 0, idle threads will not be stopped. + +The default value is 15000 (15 seconds). + + + + + + the maximum @interval (in milliseconds) + a thread can be idle + + + + + + Sets the maximal number of unused threads to @max_threads. +If @max_threads is -1, no limit is imposed on the number +of unused threads. + +The default value is 2. + + + + + + maximal number of unused threads + + + + + + Stops all currently unused threads. This does not change the +maximal number of unused threads. This function can be used to +regularly stop all unused threads e.g. from g_timeout_add(). + + + + + + + Disambiguates a given time in two ways. + +First, specifies if the given time is in universal or local time. + +Second, if the time is in local time, specifies if it is local +standard time or local daylight time. This is important for the case +where the same local time occurs twice (during daylight savings time +transitions, for example). + + the time is in local standard time + + + the time is in local daylight time + + + the time is in UTC + + + + Represents a precise time, with seconds and microseconds. +Similar to the struct timeval returned by the gettimeofday() +UNIX system call. + +GLib is attempting to unify around the use of 64bit integers to +represent microsecond-precision time. As such, this type will be +removed from a future version of GLib. + + seconds + + + + microseconds + + + + Adds the given number of microseconds to @time_. @microseconds can +also be negative to decrease the value of @time_. + + + + + + a #GTimeVal + + + + number of microseconds to add to @time + + + + + + Converts @time_ into an RFC 3339 encoded string, relative to the +Coordinated Universal Time (UTC). This is one of the many formats +allowed by ISO 8601. + +ISO 8601 allows a large number of date/time formats, with or without +punctuation and optional elements. The format returned by this function +is a complete date and time, with optional punctuation included, the +UTC time zone represented as "Z", and the @tv_usec part included if +and only if it is nonzero, i.e. either +"YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ". + +This corresponds to the Internet date/time format defined by +[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt), +and to either of the two most-precise formats defined by +the W3C Note +[Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827). +Both of these documents are profiles of ISO 8601. + +Use g_date_time_format() or g_strdup_printf() if a different +variation of ISO 8601 format is required. + + a newly allocated string containing an ISO 8601 date + + + + + a #GTimeVal + + + + + + Converts a string containing an ISO 8601 encoded date and time +to a #GTimeVal and puts it into @time_. + +@iso_date must include year, month, day, hours, minutes, and +seconds. It can optionally include fractions of a second and a time +zone indicator. (In the absence of any time zone indication, the +timestamp is assumed to be in local time.) + + %TRUE if the conversion was successful. + + + + + an ISO 8601 encoded date string + + + + a #GTimeVal + + + + + + + #GTimeZone is an opaque structure whose members cannot be accessed +directly. + + Creates a #GTimeZone corresponding to @identifier. + +@identifier can either be an RFC3339/ISO 8601 time offset or +something that would pass as a valid value for the `TZ` environment +variable (including %NULL). + +In Windows, @identifier can also be the unlocalized name of a time +zone for standard time, for example "Pacific Standard Time". + +Valid RFC3339 time offsets are `"Z"` (for UTC) or +`"±hh:mm"`. ISO 8601 additionally specifies +`"±hhmm"` and `"±hh"`. Offsets are +time values to be added to Coordinated Universal Time (UTC) to get +the local time. + +In UNIX, the `TZ` environment variable typically corresponds +to the name of a file in the zoneinfo database, or string in +"std offset [dst [offset],start[/time],end[/time]]" (POSIX) format. +There are no spaces in the specification. The name of standard +and daylight savings time zone must be three or more alphabetic +characters. Offsets are time values to be added to local time to +get Coordinated Universal Time (UTC) and should be +`"[±]hh[[:]mm[:ss]]"`. Dates are either +`"Jn"` (Julian day with n between 1 and 365, leap +years not counted), `"n"` (zero-based Julian day +with n between 0 and 365) or `"Mm.w.d"` (day d +(0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day +0 is a Sunday). Times are in local wall clock time, the default is +02:00:00. + +In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also +accepts POSIX format. The Windows format uses US rules for all time +zones; daylight savings time is 60 minutes behind the standard time +with date and time of change taken from Pacific Standard Time. +Offsets are time values to be added to the local time to get +Coordinated Universal Time (UTC). + +g_time_zone_new_local() calls this function with the value of the +`TZ` environment variable. This function itself is independent of +the value of `TZ`, but if @identifier is %NULL then `/etc/localtime` +will be consulted to discover the correct time zone on UNIX and the +registry will be consulted or GetTimeZoneInformation() will be used +to get the local time zone on Windows. + +If intervals are not available, only time zone rules from `TZ` +environment variable or other means, then they will be computed +from year 1900 to 2037. If the maximum year for the rules is +available and it is greater than 2037, then it will followed +instead. + +See +[RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6) +for a precise definition of valid RFC3339 time offsets +(the `time-offset` expansion) and ISO 8601 for the +full list of valid time offsets. See +[The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html) +for an explanation of the possible +values of the `TZ` environment variable. See +[Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx) +for the list of time zones on Windows. + +You should release the return value by calling g_time_zone_unref() +when you are done with it. + + the requested timezone + + + + + a timezone identifier + + + + + + Creates a #GTimeZone corresponding to local time. The local time +zone may change between invocations to this function; for example, +if the system administrator changes it. + +This is equivalent to calling g_time_zone_new() with the value of +the `TZ` environment variable (including the possibility of %NULL). + +You should release the return value by calling g_time_zone_unref() +when you are done with it. + + the local timezone + + + + + Creates a #GTimeZone corresponding to UTC. + +This is equivalent to calling g_time_zone_new() with a value like +"Z", "UTC", "+00", etc. + +You should release the return value by calling g_time_zone_unref() +when you are done with it. + + the universal timezone + + + + + Finds an interval within @tz that corresponds to the given @time_, +possibly adjusting @time_ if required to fit into an interval. +The meaning of @time_ depends on @type. + +This function is similar to g_time_zone_find_interval(), with the +difference that it always succeeds (by making the adjustments +described below). + +In any of the cases where g_time_zone_find_interval() succeeds then +this function returns the same value, without modifying @time_. + +This function may, however, modify @time_ in order to deal with +non-existent times. If the non-existent local @time_ of 02:30 were +requested on March 14th 2010 in Toronto then this function would +adjust @time_ to be 03:00 and return the interval containing the +adjusted time. + + the interval containing @time_, never -1 + + + + + a #GTimeZone + + + + the #GTimeType of @time_ + + + + a pointer to a number of seconds since January 1, 1970 + + + + + + Finds an the interval within @tz that corresponds to the given @time_. +The meaning of @time_ depends on @type. + +If @type is %G_TIME_TYPE_UNIVERSAL then this function will always +succeed (since universal time is monotonic and continuous). + +Otherwise @time_ is treated as local time. The distinction between +%G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in +the case that the given @time_ is ambiguous. In Toronto, for example, +01:30 on November 7th 2010 occurred twice (once inside of daylight +savings time and the next, an hour later, outside of daylight savings +time). In this case, the different value of @type would result in a +different interval being returned. + +It is still possible for this function to fail. In Toronto, for +example, 02:00 on March 14th 2010 does not exist (due to the leap +forward to begin daylight savings time). -1 is returned in that +case. + + the interval containing @time_, or -1 in case of failure + + + + + a #GTimeZone + + + + the #GTimeType of @time_ + + + + a number of seconds since January 1, 1970 + + + + + + Determines the time zone abbreviation to be used during a particular +@interval of time in the time zone @tz. + +For example, in Toronto this is currently "EST" during the winter +months and "EDT" during the summer months when daylight savings time +is in effect. + + the time zone abbreviation, which belongs to @tz + + + + + a #GTimeZone + + + + an interval within the timezone + + + + + + Determines the offset to UTC in effect during a particular @interval +of time in the time zone @tz. + +The offset is the number of seconds that you add to UTC time to +arrive at local time for @tz (ie: negative numbers for time zones +west of GMT, positive numbers for east). + + the number of seconds that should be added to UTC to get the + local time in @tz + + + + + a #GTimeZone + + + + an interval within the timezone + + + + + + Determines if daylight savings time is in effect during a particular +@interval of time in the time zone @tz. + + %TRUE if daylight savings time is in effect + + + + + a #GTimeZone + + + + an interval within the timezone + + + + + + Increases the reference count on @tz. + + a new reference to @tz. + + + + + a #GTimeZone + + + + + + Decreases the reference count on @tz. + + + + + + a #GTimeZone + + + + + + + Opaque datatype that records a start time. + + Resumes a timer that has previously been stopped with +g_timer_stop(). g_timer_stop() must be called before using this +function. + + + + + + a #GTimer. + + + + + + Destroys a timer, freeing associated resources. + + + + + + a #GTimer to destroy. + + + + + + If @timer has been started but not stopped, obtains the time since +the timer was started. If @timer has been stopped, obtains the +elapsed time between the time it was started and the time it was +stopped. The return value is the number of seconds elapsed, +including any fractional part. The @microseconds out parameter is +essentially useless. + + seconds elapsed as a floating point value, including any + fractional part. + + + + + a #GTimer. + + + + return location for the fractional part of seconds + elapsed, in microseconds (that is, the total number + of microseconds elapsed, modulo 1000000), or %NULL + + + + + + This function is useless; it's fine to call g_timer_start() on an +already-started timer to reset the start time, so g_timer_reset() +serves no purpose. + + + + + + a #GTimer. + + + + + + Marks a start time, so that future calls to g_timer_elapsed() will +report the time since g_timer_start() was called. g_timer_new() +automatically marks the start time, so no need to call +g_timer_start() immediately after creating the timer. + + + + + + a #GTimer. + + + + + + Marks an end time, so calls to g_timer_elapsed() will return the +difference between this end time and the start time. + + + + + + a #GTimer. + + + + + + Creates a new timer, and starts timing (i.e. g_timer_start() is +implicitly called for you). + + a new #GTimer. + + + + + + The possible types of token returned from each +g_scanner_get_next_token() call. + + the end of the file + + + a '(' character + + + a ')' character + + + a '{' character + + + a '}' character + + + a '[' character + + + a ']' character + + + a '=' character + + + a ',' character + + + not a token + + + an error occurred + + + a character + + + a binary integer + + + an octal integer + + + an integer + + + a hex integer + + + a floating point number + + + a string + + + a symbol + + + an identifier + + + a null identifier + + + one line comment + + + multi line comment + + + + A union holding the value of the token. + + token symbol value + + + + token identifier value + + + + token binary integer value + + + + octal integer value + + + + integer value + + + + 64-bit integer value + + + + floating point value + + + + hex integer value + + + + string value + + + + comment value + + + + character value + + + + error value + + + + + The type of functions which are used to translate user-visible +strings, for <option>--help</option> output. + + a translation of the string for the current locale. + The returned string is owned by GLib and must not be freed. + + + + + the untranslated string + + + + user data specified when installing the function, e.g. + in g_option_group_set_translate_func() + + + + + + Each piece of memory that is pushed onto the stack +is cast to a GTrashStack*. + #GTrashStack is deprecated without replacement + + pointer to the previous element of the stack, + gets stored in the first `sizeof (gpointer)` + bytes of the element + + + + Returns the height of a #GTrashStack. + +Note that execution of this function is of O(N) complexity +where N denotes the number of items on the stack. + #GTrashStack is deprecated without replacement + + the height of the stack + + + + + a #GTrashStack + + + + + + Returns the element at the top of a #GTrashStack +which may be %NULL. + #GTrashStack is deprecated without replacement + + the element at the top of the stack + + + + + a #GTrashStack + + + + + + Pops a piece of memory off a #GTrashStack. + #GTrashStack is deprecated without replacement + + the element at the top of the stack + + + + + a #GTrashStack + + + + + + Pushes a piece of memory onto a #GTrashStack. + #GTrashStack is deprecated without replacement + + + + + + a #GTrashStack + + + + the piece of memory to push on the stack + + + + + + + Specifies which nodes are visited during several of the tree +functions, including g_node_traverse() and g_node_find(). + + only leaf nodes should be visited. This name has + been introduced in 2.6, for older version use + %G_TRAVERSE_LEAFS. + + + only non-leaf nodes should be visited. This + name has been introduced in 2.6, for older + version use %G_TRAVERSE_NON_LEAFS. + + + all nodes should be visited. + + + a mask of all traverse flags. + + + identical to %G_TRAVERSE_LEAVES. + + + identical to %G_TRAVERSE_NON_LEAVES. + + + + Specifies the type of function passed to g_tree_traverse(). It is +passed the key and value of each node, together with the @user_data +parameter passed to g_tree_traverse(). If the function returns +%TRUE, the traversal is stopped. + + %TRUE to stop the traversal + + + + + a key of a #GTree node + + + + the value corresponding to the key + + + + user data passed to g_tree_traverse() + + + + + + Specifies the type of traveral performed by g_tree_traverse(), +g_node_traverse() and g_node_find(). The different orders are +illustrated here: +- In order: A, B, C, D, E, F, G, H, I + ![](Sorted_binary_tree_inorder.svg) +- Pre order: F, B, A, D, C, E, G, I, H + ![](Sorted_binary_tree_preorder.svg) +- Post order: A, C, E, D, B, H, I, G, F + ![](Sorted_binary_tree_postorder.svg) +- Level order: F, B, G, A, D, I, C, E, H + ![](Sorted_binary_tree_breadth-first_traversal.svg) + + vists a node's left child first, then the node itself, + then its right child. This is the one to use if you + want the output sorted according to the compare + function. + + + visits a node, then its children. + + + visits the node's children, then the node itself. + + + is not implemented for + [balanced binary trees][glib-Balanced-Binary-Trees]. + For [n-ary trees][glib-N-ary-Trees], it + vists the root node first, then its children, then + its grandchildren, and so on. Note that this is less + efficient than the other orders. + + + + The GTree struct is an opaque data structure representing a +[balanced binary tree][glib-Balanced-Binary-Trees]. It should be +accessed only by using the following functions. + + Removes all keys and values from the #GTree and decreases its +reference count by one. If keys and/or values are dynamically +allocated, you should either free them first or create the #GTree +using g_tree_new_full(). In the latter case the destroy functions +you supplied will be called on all keys and values before destroying +the #GTree. + + + + + + a #GTree + + + + + + Calls the given function for each of the key/value pairs in the #GTree. +The function is passed the key and value of each pair, and the given +@data parameter. The tree is traversed in sorted order. + +The tree may not be modified while iterating over it (you can't +add/remove items). To remove all items matching a predicate, you need +to add each item to a list in your #GTraverseFunc as you walk over +the tree, then walk the list and remove each item. + + + + + + a #GTree + + + + the function to call for each node visited. + If this function returns %TRUE, the traversal is stopped. + + + + user data to pass to the function + + + + + + Gets the height of a #GTree. + +If the #GTree contains no nodes, the height is 0. +If the #GTree contains only one root node the height is 1. +If the root node has children the height is 2, etc. + + the height of @tree + + + + + a #GTree + + + + + + Inserts a key/value pair into a #GTree. + +If the given key already exists in the #GTree its corresponding value +is set to the new value. If you supplied a @value_destroy_func when +creating the #GTree, the old value is freed using that function. If +you supplied a @key_destroy_func when creating the #GTree, the passed +key is freed using that function. + +The tree is automatically 'balanced' as new key/value pairs are added, +so that the distance from the root to every leaf is as small as possible. + + + + + + a #GTree + + + + the key to insert + + + + the value corresponding to the key + + + + + + Gets the value corresponding to the given key. Since a #GTree is +automatically balanced as key/value pairs are added, key lookup +is O(log n) (where n is the number of key/value pairs in the tree). + + the value corresponding to the key, or %NULL + if the key was not found + + + + + a #GTree + + + + the key to look up + + + + + + Looks up a key in the #GTree, returning the original key and the +associated value. This is useful if you need to free the memory +allocated for the original key, for example before calling +g_tree_remove(). + + %TRUE if the key was found in the #GTree + + + + + a #GTree + + + + the key to look up + + + + returns the original key + + + + returns the value associated with the key + + + + + + Gets the number of nodes in a #GTree. + + the number of nodes in @tree + + + + + a #GTree + + + + + + Increments the reference count of @tree by one. + +It is safe to call this function from any thread. + + the passed in #GTree + + + + + a #GTree + + + + + + Removes a key/value pair from a #GTree. + +If the #GTree was created using g_tree_new_full(), the key and value +are freed using the supplied destroy functions, otherwise you have to +make sure that any dynamically allocated values are freed yourself. +If the key does not exist in the #GTree, the function does nothing. + + %TRUE if the key was found (prior to 2.8, this function + returned nothing) + + + + + a #GTree + + + + the key to remove + + + + + + Inserts a new key and value into a #GTree similar to g_tree_insert(). +The difference is that if the key already exists in the #GTree, it gets +replaced by the new key. If you supplied a @value_destroy_func when +creating the #GTree, the old value is freed using that function. If you +supplied a @key_destroy_func when creating the #GTree, the old key is +freed using that function. + +The tree is automatically 'balanced' as new key/value pairs are added, +so that the distance from the root to every leaf is as small as possible. + + + + + + a #GTree + + + + the key to insert + + + + the value corresponding to the key + + + + + + Searches a #GTree using @search_func. + +The @search_func is called with a pointer to the key of a key/value +pair in the tree, and the passed in @user_data. If @search_func returns +0 for a key/value pair, then the corresponding value is returned as +the result of g_tree_search(). If @search_func returns -1, searching +will proceed among the key/value pairs that have a smaller key; if +@search_func returns 1, searching will proceed among the key/value +pairs that have a larger key. + + the value corresponding to the found key, or %NULL + if the key was not found + + + + + a #GTree + + + + a function used to search the #GTree + + + + the data passed as the second argument to @search_func + + + + + + Removes a key and its associated value from a #GTree without calling +the key and value destroy functions. + +If the key does not exist in the #GTree, the function does nothing. + + %TRUE if the key was found (prior to 2.8, this function + returned nothing) + + + + + a #GTree + + + + the key to remove + + + + + + Calls the given function for each node in the #GTree. + The order of a balanced tree is somewhat arbitrary. + If you just want to visit all nodes in sorted order, use + g_tree_foreach() instead. If you really need to visit nodes in + a different order, consider using an [n-ary tree][glib-N-ary-Trees]. + + + + + + a #GTree + + + + the function to call for each node visited. If this + function returns %TRUE, the traversal is stopped. + + + + the order in which nodes are visited, one of %G_IN_ORDER, + %G_PRE_ORDER and %G_POST_ORDER + + + + user data to pass to the function + + + + + + Decrements the reference count of @tree by one. +If the reference count drops to 0, all keys and values will +be destroyed (if destroy functions were specified) and all +memory allocated by @tree will be released. + +It is safe to call this function from any thread. + + + + + + a #GTree + + + + + + Creates a new #GTree. + + a newly allocated #GTree + + + + + the function used to order the nodes in the #GTree. + It should return values similar to the standard strcmp() function - + 0 if the two arguments are equal, a negative value if the first argument + comes before the second, or a positive value if the first argument comes + after the second. + + + + + + Creates a new #GTree like g_tree_new() and allows to specify functions +to free the memory allocated for the key and value that get called when +removing the entry from the #GTree. + + a newly allocated #GTree + + + + + qsort()-style comparison function + + + + data to pass to comparison function + + + + a function to free the memory allocated for the key + used when removing the entry from the #GTree or %NULL if you don't + want to supply such a function + + + + a function to free the memory allocated for the + value used when removing the entry from the #GTree or %NULL if you + don't want to supply such a function + + + + + + Creates a new #GTree with a comparison function that accepts user data. +See g_tree_new() for more details. + + a newly allocated #GTree + + + + + qsort()-style comparison function + + + + data to pass to comparison function + + + + + + + The maximum length (in codepoints) of a compatibility or canonical +decomposition of a single Unicode character. + +This is as defined by Unicode 6.1. + + + + Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@". + + + + Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=". + + + + Number of microseconds in one second (1 million). +This macro is provided for code readability. + + + + These are the possible line break classifications. + +Since new unicode versions may add new types here, applications should be ready +to handle unknown values. They may be regarded as %G_UNICODE_BREAK_UNKNOWN. + +See <ulink url="http://www.unicode.org/unicode/reports/tr14/">http://www.unicode.org/unicode/reports/tr14/</ulink>. + + Mandatory Break (BK) + + + Carriage Return (CR) + + + Line Feed (LF) + + + Attached Characters and Combining Marks (CM) + + + Surrogates (SG) + + + Zero Width Space (ZW) + + + Inseparable (IN) + + + Non-breaking ("Glue") (GL) + + + Contingent Break Opportunity (CB) + + + Space (SP) + + + Break Opportunity After (BA) + + + Break Opportunity Before (BB) + + + Break Opportunity Before and After (B2) + + + Hyphen (HY) + + + Nonstarter (NS) + + + Opening Punctuation (OP) + + + Closing Punctuation (CL) + + + Ambiguous Quotation (QU) + + + Exclamation/Interrogation (EX) + + + Ideographic (ID) + + + Numeric (NU) + + + Infix Separator (Numeric) (IS) + + + Symbols Allowing Break After (SY) + + + Ordinary Alphabetic and Symbol Characters (AL) + + + Prefix (Numeric) (PR) + + + Postfix (Numeric) (PO) + + + Complex Content Dependent (South East Asian) (SA) + + + Ambiguous (Alphabetic or Ideographic) (AI) + + + Unknown (XX) + + + Next Line (NL) + + + Word Joiner (WJ) + + + Hangul L Jamo (JL) + + + Hangul V Jamo (JV) + + + Hangul T Jamo (JT) + + + Hangul LV Syllable (H2) + + + Hangul LVT Syllable (H3) + + + Closing Parenthesis (CP). Since 2.28 + + + Conditional Japanese Starter (CJ). Since: 2.32 + + + Hebrew Letter (HL). Since: 2.32 + + + Regional Indicator (RI). Since: 2.36 + + + Emoji Base (EB). Since: 2.50 + + + Emoji Modifier (EM). Since: 2.50 + + + Zero Width Joiner (ZWJ). Since: 2.50 + + + + The #GUnicodeScript enumeration identifies different writing +systems. The values correspond to the names as defined in the +Unicode standard. The enumeration has been added in GLib 2.14, +and is interchangeable with #PangoScript. + +Note that new types may be added in the future. Applications +should be ready to handle unknown values. +See <ulink +url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex +#24: Script names</ulink>. + + a value never returned from g_unichar_get_script() + + + a character used by multiple different scripts + + + a mark glyph that takes its script from the + base glyph to which it is attached + + + Arabic + + + Armenian + + + Bengali + + + Bopomofo + + + Cherokee + + + Coptic + + + Cyrillic + + + Deseret + + + Devanagari + + + Ethiopic + + + Georgian + + + Gothic + + + Greek + + + Gujarati + + + Gurmukhi + + + Han + + + Hangul + + + Hebrew + + + Hiragana + + + Kannada + + + Katakana + + + Khmer + + + Lao + + + Latin + + + Malayalam + + + Mongolian + + + Myanmar + + + Ogham + + + Old Italic + + + Oriya + + + Runic + + + Sinhala + + + Syriac + + + Tamil + + + Telugu + + + Thaana + + + Thai + + + Tibetan + + + Canadian Aboriginal + + + Yi + + + Tagalog + + + Hanunoo + + + Buhid + + + Tagbanwa + + + Braille + + + Cypriot + + + Limbu + + + Osmanya + + + Shavian + + + Linear B + + + Tai Le + + + Ugaritic + + + New Tai Lue + + + Buginese + + + Glagolitic + + + Tifinagh + + + Syloti Nagri + + + Old Persian + + + Kharoshthi + + + an unassigned code point + + + Balinese + + + Cuneiform + + + Phoenician + + + Phags-pa + + + N'Ko + + + Kayah Li. Since 2.16.3 + + + Lepcha. Since 2.16.3 + + + Rejang. Since 2.16.3 + + + Sundanese. Since 2.16.3 + + + Saurashtra. Since 2.16.3 + + + Cham. Since 2.16.3 + + + Ol Chiki. Since 2.16.3 + + + Vai. Since 2.16.3 + + + Carian. Since 2.16.3 + + + Lycian. Since 2.16.3 + + + Lydian. Since 2.16.3 + + + Avestan. Since 2.26 + + + Bamum. Since 2.26 + + + Egyptian Hieroglpyhs. Since 2.26 + + + Imperial Aramaic. Since 2.26 + + + Inscriptional Pahlavi. Since 2.26 + + + Inscriptional Parthian. Since 2.26 + + + Javanese. Since 2.26 + + + Kaithi. Since 2.26 + + + Lisu. Since 2.26 + + + Meetei Mayek. Since 2.26 + + + Old South Arabian. Since 2.26 + + + Old Turkic. Since 2.28 + + + Samaritan. Since 2.26 + + + Tai Tham. Since 2.26 + + + Tai Viet. Since 2.26 + + + Batak. Since 2.28 + + + Brahmi. Since 2.28 + + + Mandaic. Since 2.28 + + + Chakma. Since: 2.32 + + + Meroitic Cursive. Since: 2.32 + + + Meroitic Hieroglyphs. Since: 2.32 + + + Miao. Since: 2.32 + + + Sharada. Since: 2.32 + + + Sora Sompeng. Since: 2.32 + + + Takri. Since: 2.32 + + + Bassa. Since: 2.42 + + + Caucasian Albanian. Since: 2.42 + + + Duployan. Since: 2.42 + + + Elbasan. Since: 2.42 + + + Grantha. Since: 2.42 + + + Kjohki. Since: 2.42 + + + Khudawadi, Sindhi. Since: 2.42 + + + Linear A. Since: 2.42 + + + Mahajani. Since: 2.42 + + + Manichaean. Since: 2.42 + + + Mende Kikakui. Since: 2.42 + + + Modi. Since: 2.42 + + + Mro. Since: 2.42 + + + Nabataean. Since: 2.42 + + + Old North Arabian. Since: 2.42 + + + Old Permic. Since: 2.42 + + + Pahawh Hmong. Since: 2.42 + + + Palmyrene. Since: 2.42 + + + Pau Cin Hau. Since: 2.42 + + + Psalter Pahlavi. Since: 2.42 + + + Siddham. Since: 2.42 + + + Tirhuta. Since: 2.42 + + + Warang Citi. Since: 2.42 + + + Ahom. Since: 2.48 + + + Anatolian Hieroglyphs. Since: 2.48 + + + Hatran. Since: 2.48 + + + Multani. Since: 2.48 + + + Old Hungarian. Since: 2.48 + + + Signwriting. Since: 2.48 + + + Adlam. Since: 2.50 + + + Bhaiksuki. Since: 2.50 + + + Marchen. Since: 2.50 + + + Newa. Since: 2.50 + + + Osage. Since: 2.50 + + + Tangut. Since: 2.50 + + + + These are the possible character classifications from the +Unicode specification. +See <ulink url="http://www.unicode.org/reports/tr44/#General_Category_Values">Unicode Character Database</unlink>. + + General category "Other, Control" (Cc) + + + General category "Other, Format" (Cf) + + + General category "Other, Not Assigned" (Cn) + + + General category "Other, Private Use" (Co) + + + General category "Other, Surrogate" (Cs) + + + General category "Letter, Lowercase" (Ll) + + + General category "Letter, Modifier" (Lm) + + + General category "Letter, Other" (Lo) + + + General category "Letter, Titlecase" (Lt) + + + General category "Letter, Uppercase" (Lu) + + + General category "Mark, Spacing" (Mc) + + + General category "Mark, Enclosing" (Me) + + + General category "Mark, Nonspacing" (Mn) + + + General category "Number, Decimal Digit" (Nd) + + + General category "Number, Letter" (Nl) + + + General category "Number, Other" (No) + + + General category "Punctuation, Connector" (Pc) + + + General category "Punctuation, Dash" (Pd) + + + General category "Punctuation, Close" (Pe) + + + General category "Punctuation, Final quote" (Pf) + + + General category "Punctuation, Initial quote" (Pi) + + + General category "Punctuation, Other" (Po) + + + General category "Punctuation, Open" (Ps) + + + General category "Symbol, Currency" (Sc) + + + General category "Symbol, Modifier" (Sk) + + + General category "Symbol, Math" (Sm) + + + General category "Symbol, Other" (So) + + + General category "Separator, Line" (Zl) + + + General category "Separator, Paragraph" (Zp) + + + General category "Separator, Space" (Zs) + + + + The type of functions to be called when a UNIX fd watch source +triggers. + + %FALSE if the source should be removed + + + + + the fd that triggered the event + + + + the IO conditions reported on @fd + + + + user data passed to g_unix_fd_add() + + + + + + These are logical ids for special directories which are defined +depending on the platform used. You should use g_get_user_special_dir() +to retrieve the full path associated to the logical id. + +The #GUserDirectory enumeration can be extended at later date. Not +every platform has a directory for every logical id in this +enumeration. + + the user's Desktop directory + + + the user's Documents directory + + + the user's Downloads directory + + + the user's Music directory + + + the user's Pictures directory + + + the user's shared directory + + + the user's Templates directory + + + the user's Movies directory + + + the number of enum values + + + + + + + A macro that should be defined by the user prior to including +the glib.h header. +The definition should be one of the predefined GLib version +macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,... + +This macro defines the earliest version of GLib that the package is +required to be able to compile against. + +If the compiler is configured to warn about the use of deprecated +functions, then using functions that were deprecated in version +%GLIB_VERSION_MIN_REQUIRED or earlier will cause warnings (but +using functions deprecated in later releases will not). + + + + #GVariant is a variant datatype; it can contain one or more values +along with information about the type of the values. + +A #GVariant may contain simple types, like an integer, or a boolean value; +or complex types, like an array of two strings, or a dictionary of key +value pairs. A #GVariant is also immutable: once it's been created neither +its type nor its content can be modified further. + +GVariant is useful whenever data needs to be serialized, for example when +sending method parameters in DBus, or when saving settings using GSettings. + +When creating a new #GVariant, you pass the data you want to store in it +along with a string representing the type of data you wish to pass to it. + +For instance, if you want to create a #GVariant holding an integer value you +can use: + +|[<!-- language="C" --> + GVariant *v = g_variant_new ('u', 40); +]| + +The string 'u' in the first argument tells #GVariant that the data passed to +the constructor (40) is going to be an unsigned integer. + +More advanced examples of #GVariant in use can be found in documentation for +[GVariant format strings][gvariant-format-strings-pointers]. + +The range of possible values is determined by the type. + +The type system used by #GVariant is #GVariantType. + +#GVariant instances always have a type and a value (which are given +at construction time). The type and value of a #GVariant instance +can never change other than by the #GVariant itself being +destroyed. A #GVariant cannot contain a pointer. + +#GVariant is reference counted using g_variant_ref() and +g_variant_unref(). #GVariant also has floating reference counts -- +see g_variant_ref_sink(). + +#GVariant is completely threadsafe. A #GVariant instance can be +concurrently accessed in any way from any number of threads without +problems. + +#GVariant is heavily optimised for dealing with data in serialised +form. It works particularly well with data located in memory-mapped +files. It can perform nearly all deserialisation operations in a +small constant time, usually touching only a single memory page. +Serialised #GVariant data can also be sent over the network. + +#GVariant is largely compatible with D-Bus. Almost all types of +#GVariant instances can be sent over D-Bus. See #GVariantType for +exceptions. (However, #GVariant's serialisation format is not the same +as the serialisation format of a D-Bus message body: use #GDBusMessage, +in the gio library, for those.) + +For space-efficiency, the #GVariant serialisation format does not +automatically include the variant's length, type or endianness, +which must either be implied from context (such as knowledge that a +particular file format always contains a little-endian +%G_VARIANT_TYPE_VARIANT which occupies the whole length of the file) +or supplied out-of-band (for instance, a length, type and/or endianness +indicator could be placed at the beginning of a file, network message +or network stream). + +A #GVariant's size is limited mainly by any lower level operating +system constraints, such as the number of bits in #gsize. For +example, it is reasonable to have a 2GB file mapped into memory +with #GMappedFile, and call g_variant_new_from_data() on it. + +For convenience to C programmers, #GVariant features powerful +varargs-based value construction and destruction. This feature is +designed to be embedded in other libraries. + +There is a Python-inspired text language for describing #GVariant +values. #GVariant includes a printer for this language and a parser +with type inferencing. + +## Memory Use + +#GVariant tries to be quite efficient with respect to memory use. +This section gives a rough idea of how much memory is used by the +current implementation. The information here is subject to change +in the future. + +The memory allocated by #GVariant can be grouped into 4 broad +purposes: memory for serialised data, memory for the type +information cache, buffer management memory and memory for the +#GVariant structure itself. + +## Serialised Data Memory + +This is the memory that is used for storing GVariant data in +serialised form. This is what would be sent over the network or +what would end up on disk, not counting any indicator of the +endianness, or of the length or type of the top-level variant. + +The amount of memory required to store a boolean is 1 byte. 16, +32 and 64 bit integers and double precision floating point numbers +use their "natural" size. Strings (including object path and +signature strings) are stored with a nul terminator, and as such +use the length of the string plus 1 byte. + +Maybe types use no space at all to represent the null value and +use the same amount of space (sometimes plus one byte) as the +equivalent non-maybe-typed value to represent the non-null case. + +Arrays use the amount of space required to store each of their +members, concatenated. Additionally, if the items stored in an +array are not of a fixed-size (ie: strings, other arrays, etc) +then an additional framing offset is stored for each item. The +size of this offset is either 1, 2 or 4 bytes depending on the +overall size of the container. Additionally, extra padding bytes +are added as required for alignment of child values. + +Tuples (including dictionary entries) use the amount of space +required to store each of their members, concatenated, plus one +framing offset (as per arrays) for each non-fixed-sized item in +the tuple, except for the last one. Additionally, extra padding +bytes are added as required for alignment of child values. + +Variants use the same amount of space as the item inside of the +variant, plus 1 byte, plus the length of the type string for the +item inside the variant. + +As an example, consider a dictionary mapping strings to variants. +In the case that the dictionary is empty, 0 bytes are required for +the serialisation. + +If we add an item "width" that maps to the int32 value of 500 then +we will use 4 byte to store the int32 (so 6 for the variant +containing it) and 6 bytes for the string. The variant must be +aligned to 8 after the 6 bytes of the string, so that's 2 extra +bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used +for the dictionary entry. An additional 1 byte is added to the +array as a framing offset making a total of 15 bytes. + +If we add another entry, "title" that maps to a nullable string +that happens to have a value of null, then we use 0 bytes for the +null value (and 3 bytes for the variant to contain it along with +its type string) plus 6 bytes for the string. Again, we need 2 +padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. + +We now require extra padding between the two items in the array. +After the 14 bytes of the first item, that's 2 bytes required. +We now require 2 framing offsets for an extra two +bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item +dictionary. + +## Type Information Cache + +For each GVariant type that currently exists in the program a type +information structure is kept in the type information cache. The +type information structure is required for rapid deserialisation. + +Continuing with the above example, if a #GVariant exists with the +type "a{sv}" then a type information struct will exist for +"a{sv}", "{sv}", "s", and "v". Multiple uses of the same type +will share the same type information. Additionally, all +single-digit types are stored in read-only static memory and do +not contribute to the writable memory footprint of a program using +#GVariant. + +Aside from the type information structures stored in read-only +memory, there are two forms of type information. One is used for +container types where there is a single element type: arrays and +maybe types. The other is used for container types where there +are multiple element types: tuples and dictionary entries. + +Array type info structures are 6 * sizeof (void *), plus the +memory required to store the type string itself. This means that +on 32-bit systems, the cache entry for "a{sv}" would require 30 +bytes of memory (plus malloc overhead). + +Tuple type info structures are 6 * sizeof (void *), plus 4 * +sizeof (void *) for each item in the tuple, plus the memory +required to store the type string itself. A 2-item tuple, for +example, would have a type information structure that consumed +writable memory in the size of 14 * sizeof (void *) (plus type +string) This means that on 32-bit systems, the cache entry for +"{sv}" would require 61 bytes of memory (plus malloc overhead). + +This means that in total, for our "a{sv}" example, 91 bytes of +type information would be allocated. + +The type information cache, additionally, uses a #GHashTable to +store and lookup the cached items and stores a pointer to this +hash table in static storage. The hash table is freed when there +are zero items in the type cache. + +Although these sizes may seem large it is important to remember +that a program will probably only have a very small number of +different types of values in it and that only one type information +structure is required for many different values of the same type. + +## Buffer Management Memory + +#GVariant uses an internal buffer management structure to deal +with the various different possible sources of serialised data +that it uses. The buffer is responsible for ensuring that the +correct call is made when the data is no longer in use by +#GVariant. This may involve a g_free() or a g_slice_free() or +even g_mapped_file_unref(). + +One buffer management structure is used for each chunk of +serialised data. The size of the buffer management structure +is 4 * (void *). On 32-bit systems, that's 16 bytes. + +## GVariant structure + +The size of a #GVariant structure is 6 * (void *). On 32-bit +systems, that's 24 bytes. + +#GVariant structures only exist if they are explicitly created +with API calls. For example, if a #GVariant is constructed out of +serialised data for the example given above (with the dictionary) +then although there are 9 individual values that comprise the +entire dictionary (two keys, two values, two variants containing +the values, two dictionary entries, plus the dictionary itself), +only 1 #GVariant instance exists -- the one referring to the +dictionary. + +If calls are made to start accessing the other values then +#GVariant instances will exist for those values only for as long +as they are in use (ie: until you call g_variant_unref()). The +type information is shared. The serialised data and the buffer +management structure for that serialised data is shared by the +child. + +## Summary + +To put the entire example together, for our dictionary mapping +strings to variants (with two entries, as given above), we are +using 91 bytes of memory for type information, 29 byes of memory +for the serialised data, 16 bytes for buffer management and 24 +bytes for the #GVariant instance, or a total of 160 bytes, plus +malloc overhead. If we were to use g_variant_get_child_value() to +access the two dictionary entries, we would use an additional 48 +bytes. If we were to have other dictionaries of the same type, we +would use more memory for the serialised data and buffer +management for those dictionaries, but the type information would +be shared. + + Creates a new #GVariant instance. + +Think of this function as an analogue to g_strdup_printf(). + +The type of the created instance and the arguments that are expected +by this function are determined by @format_string. See the section on +[GVariant format strings][gvariant-format-strings]. Please note that +the syntax of the format string is very likely to be extended in the +future. + +The first character of the format string must not be '*' '?' '@' or +'r'; in essence, a new #GVariant must always be constructed by this +function (and not merely passed through it unmodified). + +Note that the arguments must be of the correct width for their types +specified in @format_string. This can be achieved by casting them. See +the [GVariant varargs documentation][gvariant-varargs]. + +|[<!-- language="C" --> +MyFlags some_flags = FLAG_ONE | FLAG_TWO; +const gchar *some_strings[] = { "a", "b", "c", NULL }; +GVariant *new_variant; + +new_variant = g_variant_new ("(t^as)", + /<!-- -->* This cast is required. *<!-- -->/ + (guint64) some_flags, + some_strings); +]| + + a new floating #GVariant instance + + + + + a #GVariant format string + + + + arguments, as per @format_string + + + + + + Creates a new #GVariant array from @children. + +@child_type must be non-%NULL if @n_children is zero. Otherwise, the +child type is determined by inspecting the first element of the +@children array. If @child_type is non-%NULL then it must be a +definite type. + +The items of the array are taken from the @children array. No entry +in the @children array may be %NULL. + +All items in the array must have the same type, which must be the +same as @child_type, if given. + +If the @children are floating references (see g_variant_ref_sink()), the +new instance takes ownership of them as if via g_variant_ref_sink(). + + a floating reference to a new #GVariant array + + + + + the element type of the new array + + + + an array of + #GVariant pointers, the children + + + + + + the length of @children + + + + + + Creates a new boolean #GVariant instance -- either %TRUE or %FALSE. + + a floating reference to a new boolean #GVariant instance + + + + + a #gboolean value + + + + + + Creates a new byte #GVariant instance. + + a floating reference to a new byte #GVariant instance + + + + + a #guint8 value + + + + + + Creates an array-of-bytes #GVariant with the contents of @string. +This function is just like g_variant_new_string() except that the +string need not be valid UTF-8. + +The nul terminator character at the end of the string is stored in +the array. + + a floating reference to a new bytestring #GVariant instance + + + + + a normal + nul-terminated string in no particular encoding + + + + + + + + Constructs an array of bytestring #GVariant from the given array of +strings. + +If @length is -1 then @strv is %NULL-terminated. + + a new floating #GVariant instance + + + + + an array of strings + + + + + + the length of @strv, or -1 + + + + + + Creates a new dictionary entry #GVariant. @key and @value must be +non-%NULL. @key must be a value of a basic type (ie: not a container). + +If the @key or @value are floating references (see g_variant_ref_sink()), +the new instance takes ownership of them as if via g_variant_ref_sink(). + + a floating reference to a new dictionary entry #GVariant + + + + + a basic #GVariant, the key + + + + a #GVariant, the value + + + + + + Creates a new double #GVariant instance. + + a floating reference to a new double #GVariant instance + + + + + a #gdouble floating point value + + + + + + Provides access to the serialised data for an array of fixed-sized +items. + +@value must be an array with fixed-sized elements. Numeric types are +fixed-size as are tuples containing only other fixed-sized types. + +@element_size must be the size of a single element in the array. +For example, if calling this function for an array of 32-bit integers, +you might say sizeof(gint32). This value isn't used except for the purpose +of a double-check that the form of the serialised data matches the caller's +expectation. + +@n_elements, which must be non-%NULL is set equal to the number of +items in the array. + + a floating reference to a new array #GVariant instance + + + + + the #GVariantType of each element + + + + a pointer to the fixed array of contiguous elements + + + + the number of elements + + + + the size of each element + + + + + + Constructs a new serialised-mode #GVariant instance. This is the +inner interface for creation of new serialised values that gets +called from various functions in gvariant.c. + +A reference is taken on @bytes. + + a new #GVariant with a floating reference + + + + + a #GVariantType + + + + a #GBytes + + + + if the contents of @bytes are trusted + + + + + + Creates a new #GVariant instance from serialised data. + +@type is the type of #GVariant instance that will be constructed. +The interpretation of @data depends on knowing the type. + +@data is not modified by this function and must remain valid with an +unchanging value until such a time as @notify is called with +@user_data. If the contents of @data change before that time then +the result is undefined. + +If @data is trusted to be serialised data in normal form then +@trusted should be %TRUE. This applies to serialised data created +within this process or read from a trusted location on the disk (such +as a file installed in /usr/lib alongside your application). You +should set trusted to %FALSE if @data is read from the network, a +file in the user's home directory, etc. + +If @data was not stored in this machine's native endianness, any multi-byte +numeric values in the returned variant will also be in non-native +endianness. g_variant_byteswap() can be used to recover the original values. + +@notify will be called with @user_data when @data is no longer +needed. The exact time of this call is unspecified and might even be +before this function returns. + + a new floating #GVariant of type @type + + + + + a definite #GVariantType + + + + the serialised data + + + + + + the size of @data + + + + %TRUE if @data is definitely in normal form + + + + function to call when @data is no longer needed + + + + data for @notify + + + + + + Creates a new handle #GVariant instance. + +By convention, handles are indexes into an array of file descriptors +that are sent alongside a D-Bus message. If you're not interacting +with D-Bus, you probably don't need them. + + a floating reference to a new handle #GVariant instance + + + + + a #gint32 value + + + + + + Creates a new int16 #GVariant instance. + + a floating reference to a new int16 #GVariant instance + + + + + a #gint16 value + + + + + + Creates a new int32 #GVariant instance. + + a floating reference to a new int32 #GVariant instance + + + + + a #gint32 value + + + + + + Creates a new int64 #GVariant instance. + + a floating reference to a new int64 #GVariant instance + + + + + a #gint64 value + + + + + + Depending on if @child is %NULL, either wraps @child inside of a +maybe container or creates a Nothing instance for the given @type. + +At least one of @child_type and @child must be non-%NULL. +If @child_type is non-%NULL then it must be a definite type. +If they are both non-%NULL then @child_type must be the type +of @child. + +If @child is a floating reference (see g_variant_ref_sink()), the new +instance takes ownership of @child. + + a floating reference to a new #GVariant maybe instance + + + + + the #GVariantType of the child, or %NULL + + + + the child value, or %NULL + + + + + + Creates a D-Bus object path #GVariant with the contents of @string. +@string must be a valid D-Bus object path. Use +g_variant_is_object_path() if you're not sure. + + a floating reference to a new object path #GVariant instance + + + + + a normal C nul-terminated string + + + + + + Constructs an array of object paths #GVariant from the given array of +strings. + +Each string must be a valid #GVariant object path; see +g_variant_is_object_path(). + +If @length is -1 then @strv is %NULL-terminated. + + a new floating #GVariant instance + + + + + an array of strings + + + + + + the length of @strv, or -1 + + + + + + Parses @format and returns the result. + +@format must be a text format #GVariant with one extension: at any +point that a value may appear in the text, a '%' character followed +by a GVariant format string (as per g_variant_new()) may appear. In +that case, the same arguments are collected from the argument list as +g_variant_new() would have collected. + +Note that the arguments must be of the correct width for their types +specified in @format. This can be achieved by casting them. See +the [GVariant varargs documentation][gvariant-varargs]. + +Consider this simple example: +|[<!-- language="C" --> + g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three"); +]| + +In the example, the variable argument parameters are collected and +filled in as if they were part of the original string to produce the +result of +|[<!-- language="C" --> +[('one', 1), ('two', 2), ('three', 3)] +]| + +This function is intended only to be used with @format as a string +literal. Any parse error is fatal to the calling process. If you +want to parse data from untrusted sources, use g_variant_parse(). + +You may not use this function to return, unmodified, a single +#GVariant pointer from the argument list. ie: @format may not solely +be anything along the lines of "%*", "%?", "\%r", or anything starting +with "%@". + + a new floating #GVariant instance + + + + + a text format #GVariant + + + + arguments as per @format + + + + + + Parses @format and returns the result. + +This is the version of g_variant_new_parsed() intended to be used +from libraries. + +The return value will be floating if it was a newly created GVariant +instance. In the case that @format simply specified the collection +of a #GVariant pointer (eg: @format was "%*") then the collected +#GVariant pointer will be returned unmodified, without adding any +additional references. + +Note that the arguments in @app must be of the correct width for their types +specified in @format when collected into the #va_list. See +the [GVariant varargs documentation][gvariant-varargs]. + +In order to behave correctly in all cases it is necessary for the +calling function to g_variant_ref_sink() the return result before +returning control to the user that originally provided the pointer. +At this point, the caller will have their own full reference to the +result. This can also be done by adding the result to a container, +or by passing it to another g_variant_new() call. + + a new, usually floating, #GVariant + + + + + a text format #GVariant + + + + a pointer to a #va_list + + + + + + Creates a string-type GVariant using printf formatting. + +This is similar to calling g_strdup_printf() and then +g_variant_new_string() but it saves a temporary variable and an +unnecessary copy. + + a floating reference to a new string + #GVariant instance + + + + + a printf-style format string + + + + arguments for @format_string + + + + + + Creates a D-Bus type signature #GVariant with the contents of +@string. @string must be a valid D-Bus type signature. Use +g_variant_is_signature() if you're not sure. + + a floating reference to a new signature #GVariant instance + + + + + a normal C nul-terminated string + + + + + + Creates a string #GVariant with the contents of @string. + +@string must be valid UTF-8, and must not be %NULL. To encode +potentially-%NULL strings, use g_variant_new() with `ms` as the +[format string][gvariant-format-strings-maybe-types]. + + a floating reference to a new string #GVariant instance + + + + + a normal UTF-8 nul-terminated string + + + + + + Constructs an array of strings #GVariant from the given array of +strings. + +If @length is -1 then @strv is %NULL-terminated. + + a new floating #GVariant instance + + + + + an array of strings + + + + + + the length of @strv, or -1 + + + + + + Creates a string #GVariant with the contents of @string. + +@string must be valid UTF-8, and must not be %NULL. To encode +potentially-%NULL strings, use this with g_variant_new_maybe(). + +This function consumes @string. g_free() will be called on @string +when it is no longer required. + +You must not modify or access @string in any other way after passing +it to this function. It is even possible that @string is immediately +freed. + + a floating reference to a new string + #GVariant instance + + + + + a normal UTF-8 nul-terminated string + + + + + + Creates a new tuple #GVariant out of the items in @children. The +type is determined from the types of @children. No entry in the +@children array may be %NULL. + +If @n_children is 0 then the unit tuple is constructed. + +If the @children are floating references (see g_variant_ref_sink()), the +new instance takes ownership of them as if via g_variant_ref_sink(). + + a floating reference to a new #GVariant tuple + + + + + the items to make the tuple out of + + + + + + the length of @children + + + + + + Creates a new uint16 #GVariant instance. + + a floating reference to a new uint16 #GVariant instance + + + + + a #guint16 value + + + + + + Creates a new uint32 #GVariant instance. + + a floating reference to a new uint32 #GVariant instance + + + + + a #guint32 value + + + + + + Creates a new uint64 #GVariant instance. + + a floating reference to a new uint64 #GVariant instance + + + + + a #guint64 value + + + + + + This function is intended to be used by libraries based on +#GVariant that want to provide g_variant_new()-like functionality +to their users. + +The API is more general than g_variant_new() to allow a wider range +of possible uses. + +@format_string must still point to a valid format string, but it only +needs to be nul-terminated if @endptr is %NULL. If @endptr is +non-%NULL then it is updated to point to the first character past the +end of the format string. + +@app is a pointer to a #va_list. The arguments, according to +@format_string, are collected from this #va_list and the list is left +pointing to the argument following the last. + +Note that the arguments in @app must be of the correct width for their +types specified in @format_string when collected into the #va_list. +See the [GVariant varargs documentation][gvariant-varargs. + +These two generalisations allow mixing of multiple calls to +g_variant_new_va() and g_variant_get_va() within a single actual +varargs call by the user. + +The return value will be floating if it was a newly created GVariant +instance (for example, if the format string was "(ii)"). In the case +that the format_string was '*', '?', 'r', or a format starting with +'@' then the collected #GVariant pointer will be returned unmodified, +without adding any additional references. + +In order to behave correctly in all cases it is necessary for the +calling function to g_variant_ref_sink() the return result before +returning control to the user that originally provided the pointer. +At this point, the caller will have their own full reference to the +result. This can also be done by adding the result to a container, +or by passing it to another g_variant_new() call. + + a new, usually floating, #GVariant + + + + + a string that is prefixed with a format string + + + + location to store the end pointer, + or %NULL + + + + a pointer to a #va_list + + + + + + Boxes @value. The result is a #GVariant instance representing a +variant containing the original value. + +If @child is a floating reference (see g_variant_ref_sink()), the new +instance takes ownership of @child. + + a floating reference to a new variant #GVariant instance + + + + + a #GVariant instance + + + + + + Performs a byteswapping operation on the contents of @value. The +result is that all multi-byte numeric data contained in @value is +byteswapped. That includes 16, 32, and 64bit signed and unsigned +integers as well as file handles and double precision floating point +values. + +This function is an identity mapping on any value that does not +contain multi-byte numeric data. That include strings, booleans, +bytes and containers containing only these things (recursively). + +The returned value is always in normal form and is marked as trusted. + + the byteswapped form of @value + + + + + a #GVariant + + + + + + Checks if calling g_variant_get() with @format_string on @value would +be valid from a type-compatibility standpoint. @format_string is +assumed to be a valid format string (from a syntactic standpoint). + +If @copy_only is %TRUE then this function additionally checks that it +would be safe to call g_variant_unref() on @value immediately after +the call to g_variant_get() without invalidating the result. This is +only possible if deep copies are made (ie: there are no pointers to +the data inside of the soon-to-be-freed #GVariant instance). If this +check fails then a g_critical() is printed and %FALSE is returned. + +This function is meant to be used by functions that wish to provide +varargs accessors to #GVariant values of uncertain values (eg: +g_variant_lookup() or g_menu_model_get_item_attribute()). + + %TRUE if @format_string is safe to use + + + + + a #GVariant + + + + a valid #GVariant format string + + + + %TRUE to ensure the format string makes deep copies + + + + + + Classifies @value according to its top-level type. + + the #GVariantClass of @value + + + + + a #GVariant + + + + + + Compares @one and @two. + +The types of @one and @two are #gconstpointer only to allow use of +this function with #GTree, #GPtrArray, etc. They must each be a +#GVariant. + +Comparison is only defined for basic types (ie: booleans, numbers, +strings). For booleans, %FALSE is less than %TRUE. Numbers are +ordered in the usual way. Strings are in ASCII lexographical order. + +It is a programmer error to attempt to compare container values or +two values that have types that are not exactly equal. For example, +you cannot compare a 32-bit signed integer with a 32-bit unsigned +integer. Also note that this function is not particularly +well-behaved when it comes to comparison of doubles; in particular, +the handling of incomparable values (ie: NaN) is undefined. + +If you only require an equality comparison, g_variant_equal() is more +general. + + negative value if a < b; + zero if a = b; + positive value if a > b. + + + + + a basic-typed #GVariant instance + + + + a #GVariant instance of the same type + + + + + + Similar to g_variant_get_bytestring() except that instead of +returning a constant string, the string is duplicated. + +The return value must be freed using g_free(). + + + a newly allocated string + + + + + + + an array-of-bytes #GVariant instance + + + + a pointer to a #gsize, to store + the length (not including the nul terminator) + + + + + + Gets the contents of an array of array of bytes #GVariant. This call +makes a deep copy; the return result should be released with +g_strfreev(). + +If @length is non-%NULL then the number of elements in the result is +stored there. In any case, the resulting array will be +%NULL-terminated. + +For an empty array, @length will be set to 0 and a pointer to a +%NULL pointer will be returned. + + an array of strings + + + + + + + an array of array of bytes #GVariant ('aay') + + + + the length of the result, or %NULL + + + + + + Gets the contents of an array of object paths #GVariant. This call +makes a deep copy; the return result should be released with +g_strfreev(). + +If @length is non-%NULL then the number of elements in the result +is stored there. In any case, the resulting array will be +%NULL-terminated. + +For an empty array, @length will be set to 0 and a pointer to a +%NULL pointer will be returned. + + an array of strings + + + + + + + an array of object paths #GVariant + + + + the length of the result, or %NULL + + + + + + Similar to g_variant_get_string() except that instead of returning +a constant string, the string is duplicated. + +The string will always be UTF-8 encoded. + +The return value must be freed using g_free(). + + a newly allocated string, UTF-8 encoded + + + + + a string #GVariant instance + + + + a pointer to a #gsize, to store the length + + + + + + Gets the contents of an array of strings #GVariant. This call +makes a deep copy; the return result should be released with +g_strfreev(). + +If @length is non-%NULL then the number of elements in the result +is stored there. In any case, the resulting array will be +%NULL-terminated. + +For an empty array, @length will be set to 0 and a pointer to a +%NULL pointer will be returned. + + an array of strings + + + + + + + an array of strings #GVariant + + + + the length of the result, or %NULL + + + + + + Checks if @one and @two have the same type and value. + +The types of @one and @two are #gconstpointer only to allow use of +this function with #GHashTable. They must each be a #GVariant. + + %TRUE if @one and @two are equal + + + + + a #GVariant instance + + + + a #GVariant instance + + + + + + Deconstructs a #GVariant instance. + +Think of this function as an analogue to scanf(). + +The arguments that are expected by this function are entirely +determined by @format_string. @format_string also restricts the +permissible types of @value. It is an error to give a value with +an incompatible type. See the section on +[GVariant format strings][gvariant-format-strings]. +Please note that the syntax of the format string is very likely to be +extended in the future. + +@format_string determines the C types that are used for unpacking +the values and also determines if the values are copied or borrowed, +see the section on +[GVariant format strings][gvariant-format-strings-pointers]. + + + + + + a #GVariant instance + + + + a #GVariant format string + + + + arguments, as per @format_string + + + + + + Returns the boolean value of @value. + +It is an error to call this function with a @value of any type +other than %G_VARIANT_TYPE_BOOLEAN. + + %TRUE or %FALSE + + + + + a boolean #GVariant instance + + + + + + Returns the byte value of @value. + +It is an error to call this function with a @value of any type +other than %G_VARIANT_TYPE_BYTE. + + a #guchar + + + + + a byte #GVariant instance + + + + + + Returns the string value of a #GVariant instance with an +array-of-bytes type. The string has no particular encoding. + +If the array does not end with a nul terminator character, the empty +string is returned. For this reason, you can always trust that a +non-%NULL nul-terminated string will be returned by this function. + +If the array contains a nul terminator character somewhere other than +the last byte then the returned string is the string, up to the first +such nul character. + +g_variant_get_fixed_array() should be used instead if the array contains +arbitrary data that could not be nul-terminated or could contain nul bytes. + +It is an error to call this function with a @value that is not an +array of bytes. + +The return value remains valid as long as @value exists. + + + the constant string + + + + + + + an array-of-bytes #GVariant instance + + + + + + Gets the contents of an array of array of bytes #GVariant. This call +makes a shallow copy; the return result should be released with +g_free(), but the individual strings must not be modified. + +If @length is non-%NULL then the number of elements in the result is +stored there. In any case, the resulting array will be +%NULL-terminated. + +For an empty array, @length will be set to 0 and a pointer to a +%NULL pointer will be returned. + + an array of constant strings + + + + + + + an array of array of bytes #GVariant ('aay') + + + + the length of the result, or %NULL + + + + + + Reads a child item out of a container #GVariant instance and +deconstructs it according to @format_string. This call is +essentially a combination of g_variant_get_child_value() and +g_variant_get(). + +@format_string determines the C types that are used for unpacking +the values and also determines if the values are copied or borrowed, +see the section on +[GVariant format strings][gvariant-format-strings-pointers]. + + + + + + a container #GVariant + + + + the index of the child to deconstruct + + + + a #GVariant format string + + + + arguments, as per @format_string + + + + + + Reads a child item out of a container #GVariant instance. This +includes variants, maybes, arrays, tuples and dictionary +entries. It is an error to call this function on any other type of +#GVariant. + +It is an error if @index_ is greater than the number of child items +in the container. See g_variant_n_children(). + +The returned value is never floating. You should free it with +g_variant_unref() when you're done with it. + +This function is O(1). + + the child at the specified index + + + + + a container #GVariant + + + + the index of the child to fetch + + + + + + Returns a pointer to the serialised form of a #GVariant instance. +The returned data may not be in fully-normalised form if read from an +untrusted source. The returned data must not be freed; it remains +valid for as long as @value exists. + +If @value is a fixed-sized value that was deserialised from a +corrupted serialised container then %NULL may be returned. In this +case, the proper thing to do is typically to use the appropriate +number of nul bytes in place of @value. If @value is not fixed-sized +then %NULL is never returned. + +In the case that @value is already in serialised form, this function +is O(1). If the value is not already in serialised form, +serialisation occurs implicitly and is approximately O(n) in the size +of the result. + +To deserialise the data returned by this function, in addition to the +serialised data, you must know the type of the #GVariant, and (if the +machine might be different) the endianness of the machine that stored +it. As a result, file formats or network messages that incorporate +serialised #GVariants must include this information either +implicitly (for instance "the file always contains a +%G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or +explicitly (by storing the type and/or endianness in addition to the +serialised data). + + the serialised form of @value, or %NULL + + + + + a #GVariant instance + + + + + + Returns a pointer to the serialised form of a #GVariant instance. +The semantics of this function are exactly the same as +g_variant_get_data(), except that the returned #GBytes holds +a reference to the variant data. + + A new #GBytes representing the variant data + + + + + a #GVariant + + + + + + Returns the double precision floating point value of @value. + +It is an error to call this function with a @value of any type +other than %G_VARIANT_TYPE_DOUBLE. + + a #gdouble + + + + + a double #GVariant instance + + + + + + Provides access to the serialised data for an array of fixed-sized +items. + +@value must be an array with fixed-sized elements. Numeric types are +fixed-size, as are tuples containing only other fixed-sized types. + +@element_size must be the size of a single element in the array, +as given by the section on +[serialized data memory][gvariant-serialised-data-memory]. + +In particular, arrays of these fixed-sized types can be interpreted +as an array of the given C type, with @element_size set to the size +the appropriate type: +- %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.) +- %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!) +- %G_VARIANT_TYPE_BYTE: #guchar +- %G_VARIANT_TYPE_HANDLE: #guint32 +- %G_VARIANT_TYPE_DOUBLE: #gdouble + +For example, if calling this function for an array of 32-bit integers, +you might say sizeof(gint32). This value isn't used except for the purpose +of a double-check that the form of the serialised data matches the caller's +expectation. + +@n_elements, which must be non-%NULL is set equal to the number of +items in the array. + + a pointer to + the fixed array + + + + + + + a #GVariant array with fixed-sized elements + + + + a pointer to the location to store the number of items + + + + the size of each element + + + + + + Returns the 32-bit signed integer value of @value. + +It is an error to call this function with a @value of any type other +than %G_VARIANT_TYPE_HANDLE. + +By convention, handles are indexes into an array of file descriptors +that are sent alongside a D-Bus message. If you're not interacting +with D-Bus, you probably don't need them. + + a #gint32 + + + + + a handle #GVariant instance + + + + + + Returns the 16-bit signed integer value of @value. + +It is an error to call this function with a @value of any type +other than %G_VARIANT_TYPE_INT16. + + a #gint16 + + + + + a int16 #GVariant instance + + + + + + Returns the 32-bit signed integer value of @value. + +It is an error to call this function with a @value of any type +other than %G_VARIANT_TYPE_INT32. + + a #gint32 + + + + + a int32 #GVariant instance + + + + + + Returns the 64-bit signed integer value of @value. + +It is an error to call this function with a @value of any type +other than %G_VARIANT_TYPE_INT64. + + a #gint64 + + + + + a int64 #GVariant instance + + + + + + Given a maybe-typed #GVariant instance, extract its value. If the +value is Nothing, then this function returns %NULL. + + the contents of @value, or %NULL + + + + + a maybe-typed value + + + + + + Gets a #GVariant instance that has the same value as @value and is +trusted to be in normal form. + +If @value is already trusted to be in normal form then a new +reference to @value is returned. + +If @value is not already trusted, then it is scanned to check if it +is in normal form. If it is found to be in normal form then it is +marked as trusted and a new reference to it is returned. + +If @value is found not to be in normal form then a new trusted +#GVariant is created with the same value as @value. + +It makes sense to call this function if you've received #GVariant +data from untrusted sources and you want to ensure your serialised +output is definitely in normal form. + + a trusted #GVariant + + + + + a #GVariant + + + + + + Gets the contents of an array of object paths #GVariant. This call +makes a shallow copy; the return result should be released with +g_free(), but the individual strings must not be modified. + +If @length is non-%NULL then the number of elements in the result +is stored there. In any case, the resulting array will be +%NULL-terminated. + +For an empty array, @length will be set to 0 and a pointer to a +%NULL pointer will be returned. + + an array of constant strings + + + + + + + an array of object paths #GVariant + + + + the length of the result, or %NULL + + + + + + Determines the number of bytes that would be required to store @value +with g_variant_store(). + +If @value has a fixed-sized type then this function always returned +that fixed size. + +In the case that @value is already in serialised form or the size has +already been calculated (ie: this function has been called before) +then this function is O(1). Otherwise, the size is calculated, an +operation which is approximately O(n) in the number of values +involved. + + the serialised size of @value + + + + + a #GVariant instance + + + + + + Returns the string value of a #GVariant instance with a string +type. This includes the types %G_VARIANT_TYPE_STRING, +%G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. + +The string will always be UTF-8 encoded, and will never be %NULL. + +If @length is non-%NULL then the length of the string (in bytes) is +returned there. For trusted values, this information is already +known. For untrusted values, a strlen() will be performed. + +It is an error to call this function with a @value of any type +other than those three. + +The return value remains valid as long as @value exists. + + the constant string, UTF-8 encoded + + + + + a string #GVariant instance + + + + a pointer to a #gsize, + to store the length + + + + + + Gets the contents of an array of strings #GVariant. This call +makes a shallow copy; the return result should be released with +g_free(), but the individual strings must not be modified. + +If @length is non-%NULL then the number of elements in the result +is stored there. In any case, the resulting array will be +%NULL-terminated. + +For an empty array, @length will be set to 0 and a pointer to a +%NULL pointer will be returned. + + an array of constant strings + + + + + + + an array of strings #GVariant + + + + the length of the result, or %NULL + + + + + + Determines the type of @value. + +The return value is valid for the lifetime of @value and must not +be freed. + + a #GVariantType + + + + + a #GVariant + + + + + + Returns the type string of @value. Unlike the result of calling +g_variant_type_peek_string(), this string is nul-terminated. This +string belongs to #GVariant and must not be freed. + + the type string for the type of @value + + + + + a #GVariant + + + + + + Returns the 16-bit unsigned integer value of @value. + +It is an error to call this function with a @value of any type +other than %G_VARIANT_TYPE_UINT16. + + a #guint16 + + + + + a uint16 #GVariant instance + + + + + + Returns the 32-bit unsigned integer value of @value. + +It is an error to call this function with a @value of any type +other than %G_VARIANT_TYPE_UINT32. + + a #guint32 + + + + + a uint32 #GVariant instance + + + + + + Returns the 64-bit unsigned integer value of @value. + +It is an error to call this function with a @value of any type +other than %G_VARIANT_TYPE_UINT64. + + a #guint64 + + + + + a uint64 #GVariant instance + + + + + + This function is intended to be used by libraries based on #GVariant +that want to provide g_variant_get()-like functionality to their +users. + +The API is more general than g_variant_get() to allow a wider range +of possible uses. + +@format_string must still point to a valid format string, but it only +need to be nul-terminated if @endptr is %NULL. If @endptr is +non-%NULL then it is updated to point to the first character past the +end of the format string. + +@app is a pointer to a #va_list. The arguments, according to +@format_string, are collected from this #va_list and the list is left +pointing to the argument following the last. + +These two generalisations allow mixing of multiple calls to +g_variant_new_va() and g_variant_get_va() within a single actual +varargs call by the user. + +@format_string determines the C types that are used for unpacking +the values and also determines if the values are copied or borrowed, +see the section on +[GVariant format strings][gvariant-format-strings-pointers]. + + + + + + a #GVariant + + + + a string that is prefixed with a format string + + + + location to store the end pointer, + or %NULL + + + + a pointer to a #va_list + + + + + + Unboxes @value. The result is the #GVariant instance that was +contained in @value. + + the item contained in the variant + + + + + a variant #GVariant instance + + + + + + Generates a hash value for a #GVariant instance. + +The output of this function is guaranteed to be the same for a given +value only per-process. It may change between different processor +architectures or even different versions of GLib. Do not use this +function as a basis for building protocols or file formats. + +The type of @value is #gconstpointer only to allow use of this +function with #GHashTable. @value must be a #GVariant. + + a hash value corresponding to @value + + + + + a basic #GVariant value as a #gconstpointer + + + + + + Checks if @value is a container. + + %TRUE if @value is a container + + + + + a #GVariant instance + + + + + + Checks whether @value has a floating reference count. + +This function should only ever be used to assert that a given variant +is or is not floating, or for debug purposes. To acquire a reference +to a variant that might be floating, always use g_variant_ref_sink() +or g_variant_take_ref(). + +See g_variant_ref_sink() for more information about floating reference +counts. + + whether @value is floating + + + + + a #GVariant + + + + + + Checks if @value is in normal form. + +The main reason to do this is to detect if a given chunk of +serialised data is in normal form: load the data into a #GVariant +using g_variant_new_from_data() and then use this function to +check. + +If @value is found to be in normal form then it will be marked as +being trusted. If the value was already marked as being trusted then +this function will immediately return %TRUE. + + %TRUE if @value is in normal form + + + + + a #GVariant instance + + + + + + Checks if a value has a type matching the provided type. + + %TRUE if the type of @value matches @type + + + + + a #GVariant instance + + + + a #GVariantType + + + + + + Creates a heap-allocated #GVariantIter for iterating over the items +in @value. + +Use g_variant_iter_free() to free the return value when you no longer +need it. + +A reference is taken to @value and will be released only when +g_variant_iter_free() is called. + + a new heap-allocated #GVariantIter + + + + + a container #GVariant + + + + + + Looks up a value in a dictionary #GVariant. + +This function is a wrapper around g_variant_lookup_value() and +g_variant_get(). In the case that %NULL would have been returned, +this function returns %FALSE. Otherwise, it unpacks the returned +value and returns %TRUE. + +@format_string determines the C types that are used for unpacking +the values and also determines if the values are copied or borrowed, +see the section on +[GVariant format strings][gvariant-format-strings-pointers]. + +This function is currently implemented with a linear scan. If you +plan to do many lookups then #GVariantDict may be more efficient. + + %TRUE if a value was unpacked + + + + + a dictionary #GVariant + + + + the key to lookup in the dictionary + + + + a GVariant format string + + + + the arguments to unpack the value into + + + + + + Looks up a value in a dictionary #GVariant. + +This function works with dictionaries of the type a{s*} (and equally +well with type a{o*}, but we only further discuss the string case +for sake of clarity). + +In the event that @dictionary has the type a{sv}, the @expected_type +string specifies what type of value is expected to be inside of the +variant. If the value inside the variant has a different type then +%NULL is returned. In the event that @dictionary has a value type other +than v then @expected_type must directly match the key type and it is +used to unpack the value directly or an error occurs. + +In either case, if @key is not found in @dictionary, %NULL is returned. + +If the key is found and the value has the correct type, it is +returned. If @expected_type was specified then any non-%NULL return +value will have this type. + +This function is currently implemented with a linear scan. If you +plan to do many lookups then #GVariantDict may be more efficient. + + the value of the dictionary key, or %NULL + + + + + a dictionary #GVariant + + + + the key to lookup in the dictionary + + + + a #GVariantType, or %NULL + + + + + + Determines the number of children in a container #GVariant instance. +This includes variants, maybes, arrays, tuples and dictionary +entries. It is an error to call this function on any other type of +#GVariant. + +For variants, the return value is always 1. For values with maybe +types, it is always zero or one. For arrays, it is the length of the +array. For tuples it is the number of tuple items (which depends +only on the type). For dictionary entries, it is always 2 + +This function is O(1). + + the number of children in the container + + + + + a container #GVariant + + + + + + Pretty-prints @value in the format understood by g_variant_parse(). + +The format is described [here][gvariant-text]. + +If @type_annotate is %TRUE, then type information is included in +the output. + + a newly-allocated string holding the result. + + + + + a #GVariant + + + + %TRUE if type information should be included in + the output + + + + + + Behaves as g_variant_print(), but operates on a #GString. + +If @string is non-%NULL then it is appended to and returned. Else, +a new empty #GString is allocated and it is returned. + + a #GString containing the string + + + + + a #GVariant + + + + a #GString, or %NULL + + + + %TRUE if type information should be included in + the output + + + + + + Increases the reference count of @value. + + the same @value + + + + + a #GVariant + + + + + + #GVariant uses a floating reference count system. All functions with +names starting with `g_variant_new_` return floating +references. + +Calling g_variant_ref_sink() on a #GVariant with a floating reference +will convert the floating reference into a full reference. Calling +g_variant_ref_sink() on a non-floating #GVariant results in an +additional normal reference being added. + +In other words, if the @value is floating, then this call "assumes +ownership" of the floating reference, converting it to a normal +reference. If the @value is not floating, then this call adds a +new normal reference increasing the reference count by one. + +All calls that result in a #GVariant instance being inserted into a +container will call g_variant_ref_sink() on the instance. This means +that if the value was just created (and has only its floating +reference) then the container will assume sole ownership of the value +at that point and the caller will not need to unreference it. This +makes certain common styles of programming much easier while still +maintaining normal refcounting semantics in situations where values +are not floating. + + the same @value + + + + + a #GVariant + + + + + + Stores the serialised form of @value at @data. @data should be +large enough. See g_variant_get_size(). + +The stored data is in machine native byte order but may not be in +fully-normalised form if read from an untrusted source. See +g_variant_get_normal_form() for a solution. + +As with g_variant_get_data(), to be able to deserialise the +serialised variant successfully, its type and (if the destination +machine might be different) its endianness must also be available. + +This function is approximately O(n) in the size of @data. + + + + + + the #GVariant to store + + + + the location to store the serialised data at + + + + + + If @value is floating, sink it. Otherwise, do nothing. + +Typically you want to use g_variant_ref_sink() in order to +automatically do the correct thing with respect to floating or +non-floating references, but there is one specific scenario where +this function is helpful. + +The situation where this function is helpful is when creating an API +that allows the user to provide a callback function that returns a +#GVariant. We certainly want to allow the user the flexibility to +return a non-floating reference from this callback (for the case +where the value that is being returned already exists). + +At the same time, the style of the #GVariant API makes it likely that +for newly-created #GVariant instances, the user can be saved some +typing if they are allowed to return a #GVariant with a floating +reference. + +Using this function on the return value of the user's callback allows +the user to do whichever is more convenient for them. The caller +will alway receives exactly one full reference to the value: either +the one that was returned in the first place, or a floating reference +that has been converted to a full reference. + +This function has an odd interaction when combined with +g_variant_ref_sink() running at the same time in another thread on +the same #GVariant instance. If g_variant_ref_sink() runs first then +the result will be that the floating reference is converted to a hard +reference. If g_variant_take_ref() runs first then the result will +be that the floating reference is converted to a hard reference and +an additional reference on top of that one is added. It is best to +avoid this situation. + + the same @value + + + + + a #GVariant + + + + + + Decreases the reference count of @value. When its reference count +drops to 0, the memory used by the variant is freed. + + + + + + a #GVariant + + + + + + Determines if a given string is a valid D-Bus object path. You +should ensure that a string is a valid D-Bus object path before +passing it to g_variant_new_object_path(). + +A valid object path starts with '/' followed by zero or more +sequences of characters separated by '/' characters. Each sequence +must contain only the characters "[A-Z][a-z][0-9]_". No sequence +(including the one following the final '/' character) may be empty. + + %TRUE if @string is a D-Bus object path + + + + + a normal C nul-terminated string + + + + + + Determines if a given string is a valid D-Bus type signature. You +should ensure that a string is a valid D-Bus type signature before +passing it to g_variant_new_signature(). + +D-Bus type signatures consist of zero or more definite #GVariantType +strings in sequence. + + %TRUE if @string is a D-Bus type signature + + + + + a normal C nul-terminated string + + + + + + Parses a #GVariant from a text representation. + +A single #GVariant is parsed from the content of @text. + +The format is described [here][gvariant-text]. + +The memory at @limit will never be accessed and the parser behaves as +if the character at @limit is the nul terminator. This has the +effect of bounding @text. + +If @endptr is non-%NULL then @text is permitted to contain data +following the value that this function parses and @endptr will be +updated to point to the first character past the end of the text +parsed by this function. If @endptr is %NULL and there is extra data +then an error is returned. + +If @type is non-%NULL then the value will be parsed to have that +type. This may result in additional parse errors (in the case that +the parsed value doesn't fit the type) but may also result in fewer +errors (in the case that the type would have been ambiguous, such as +with empty arrays). + +In the event that the parsing is successful, the resulting #GVariant +is returned. It is never floating, and must be freed with +g_variant_unref(). + +In case of any error, %NULL will be returned. If @error is non-%NULL +then it will be set to reflect the error that occurred. + +Officially, the language understood by the parser is "any string +produced by g_variant_print()". + + a non-floating reference to a #GVariant, or %NULL + + + + + a #GVariantType, or %NULL + + + + a string containing a GVariant in text form + + + + a pointer to the end of @text, or %NULL + + + + a location to store the end pointer, or %NULL + + + + + + Pretty-prints a message showing the context of a #GVariant parse +error within the string for which parsing was attempted. + +The resulting string is suitable for output to the console or other +monospace media where newlines are treated in the usual way. + +The message will typically look something like one of the following: + +|[ +unterminated string constant: + (1, 2, 3, 'abc + ^^^^ +]| + +or + +|[ +unable to find a common type: + [1, 2, 3, 'str'] + ^ ^^^^^ +]| + +The format of the message may change in a future version. + +@error must have come from a failed attempt to g_variant_parse() and +@source_str must be exactly the same string that caused the error. +If @source_str was not nul-terminated when you passed it to +g_variant_parse() then you must add nul termination before using this +function. + + the printed message + + + + + a #GError from the #GVariantParseError domain + + + + the string that was given to the parser + + + + + + + + + + + Same as g_variant_error_quark(). + Use g_variant_parse_error_quark() instead. + + + + + + + A utility type for constructing container-type #GVariant instances. + +This is an opaque structure and may only be accessed using the +following functions. + +#GVariantBuilder is not threadsafe in any way. Do not attempt to +access it from more than one thread. + + + + + + + + + + + + + + + + + + + + + + Allocates and initialises a new #GVariantBuilder. + +You should call g_variant_builder_unref() on the return value when it +is no longer needed. The memory will not be automatically freed by +any other call. + +In most cases it is easier to place a #GVariantBuilder directly on +the stack of the calling function and initialise it with +g_variant_builder_init(). + + a #GVariantBuilder + + + + + a container type + + + + + + Adds to a #GVariantBuilder. + +This call is a convenience wrapper that is exactly equivalent to +calling g_variant_new() followed by g_variant_builder_add_value(). + +Note that the arguments must be of the correct width for their types +specified in @format_string. This can be achieved by casting them. See +the [GVariant varargs documentation][gvariant-varargs]. + +This function might be used as follows: + +|[<!-- language="C" --> +GVariant * +make_pointless_dictionary (void) +{ + GVariantBuilder builder; + int i; + + g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); + for (i = 0; i < 16; i++) + { + gchar buf[3]; + + sprintf (buf, "%d", i); + g_variant_builder_add (&builder, "{is}", i, buf); + } + + return g_variant_builder_end (&builder); +} +]| + + + + + + a #GVariantBuilder + + + + a #GVariant varargs format string + + + + arguments, as per @format_string + + + + + + Adds to a #GVariantBuilder. + +This call is a convenience wrapper that is exactly equivalent to +calling g_variant_new_parsed() followed by +g_variant_builder_add_value(). + +Note that the arguments must be of the correct width for their types +specified in @format_string. This can be achieved by casting them. See +the [GVariant varargs documentation][gvariant-varargs]. + +This function might be used as follows: + +|[<!-- language="C" --> +GVariant * +make_pointless_dictionary (void) +{ + GVariantBuilder builder; + int i; + + g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); + g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600); + g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo"); + g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}"); + return g_variant_builder_end (&builder); +} +]| + + + + + + a #GVariantBuilder + + + + a text format #GVariant + + + + arguments as per @format + + + + + + Adds @value to @builder. + +It is an error to call this function in any way that would create an +inconsistent value to be constructed. Some examples of this are +putting different types of items into an array, putting the wrong +types or number of items in a tuple, putting more than one value into +a variant, etc. + +If @value is a floating reference (see g_variant_ref_sink()), +the @builder instance takes ownership of @value. + + + + + + a #GVariantBuilder + + + + a #GVariant + + + + + + Releases all memory associated with a #GVariantBuilder without +freeing the #GVariantBuilder structure itself. + +It typically only makes sense to do this on a stack-allocated +#GVariantBuilder if you want to abort building the value part-way +through. This function need not be called if you call +g_variant_builder_end() and it also doesn't need to be called on +builders allocated with g_variant_builder_new (see +g_variant_builder_unref() for that). + +This function leaves the #GVariantBuilder structure set to all-zeros. +It is valid to call this function on either an initialised +#GVariantBuilder or one that is set to all-zeros but it is not valid +to call this function on uninitialised memory. + + + + + + a #GVariantBuilder + + + + + + Closes the subcontainer inside the given @builder that was opened by +the most recent call to g_variant_builder_open(). + +It is an error to call this function in any way that would create an +inconsistent value to be constructed (ie: too few values added to the +subcontainer). + + + + + + a #GVariantBuilder + + + + + + Ends the builder process and returns the constructed value. + +It is not permissible to use @builder in any way after this call +except for reference counting operations (in the case of a +heap-allocated #GVariantBuilder) or by reinitialising it with +g_variant_builder_init() (in the case of stack-allocated). This +means that for the stack-allocated builders there is no need to +call g_variant_builder_clear() after the call to +g_variant_builder_end(). + +It is an error to call this function in any way that would create an +inconsistent value to be constructed (ie: insufficient number of +items added to a container with a specific number of children +required). It is also an error to call this function if the builder +was created with an indefinite array or maybe type and no children +have been added; in this case it is impossible to infer the type of +the empty array. + + a new, floating, #GVariant + + + + + a #GVariantBuilder + + + + + + Initialises a #GVariantBuilder structure. + +@type must be non-%NULL. It specifies the type of container to +construct. It can be an indefinite type such as +%G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)". +Maybe, array, tuple, dictionary entry and variant-typed values may be +constructed. + +After the builder is initialised, values are added using +g_variant_builder_add_value() or g_variant_builder_add(). + +After all the child values are added, g_variant_builder_end() frees +the memory associated with the builder and returns the #GVariant that +was created. + +This function completely ignores the previous contents of @builder. +On one hand this means that it is valid to pass in completely +uninitialised memory. On the other hand, this means that if you are +initialising over top of an existing #GVariantBuilder you need to +first call g_variant_builder_clear() in order to avoid leaking +memory. + +You must not call g_variant_builder_ref() or +g_variant_builder_unref() on a #GVariantBuilder that was initialised +with this function. If you ever pass a reference to a +#GVariantBuilder outside of the control of your own code then you +should assume that the person receiving that reference may try to use +reference counting; you should use g_variant_builder_new() instead of +this function. + + + + + + a #GVariantBuilder + + + + a container type + + + + + + Opens a subcontainer inside the given @builder. When done adding +items to the subcontainer, g_variant_builder_close() must be called. + +It is an error to call this function in any way that would cause an +inconsistent value to be constructed (ie: adding too many values or +a value of an incorrect type). + + + + + + a #GVariantBuilder + + + + a #GVariantType + + + + + + Increases the reference count on @builder. + +Don't call this on stack-allocated #GVariantBuilder instances or bad +things will happen. + + a new reference to @builder + + + + + a #GVariantBuilder allocated by g_variant_builder_new() + + + + + + Decreases the reference count on @builder. + +In the event that there are no more references, releases all memory +associated with the #GVariantBuilder. + +Don't call this on stack-allocated #GVariantBuilder instances or bad +things will happen. + + + + + + a #GVariantBuilder allocated by g_variant_builder_new() + + + + + + + The range of possible top-level types of #GVariant instances. + + The #GVariant is a boolean. + + + The #GVariant is a byte. + + + The #GVariant is a signed 16 bit integer. + + + The #GVariant is an unsigned 16 bit integer. + + + The #GVariant is a signed 32 bit integer. + + + The #GVariant is an unsigned 32 bit integer. + + + The #GVariant is a signed 64 bit integer. + + + The #GVariant is an unsigned 64 bit integer. + + + The #GVariant is a file handle index. + + + The #GVariant is a double precision floating + point value. + + + The #GVariant is a normal string. + + + The #GVariant is a D-Bus object path + string. + + + The #GVariant is a D-Bus signature string. + + + The #GVariant is a variant. + + + The #GVariant is a maybe-typed value. + + + The #GVariant is an array. + + + The #GVariant is a tuple. + + + The #GVariant is a dictionary entry. + + + + #GVariantDict is a mutable interface to #GVariant dictionaries. + +It can be used for doing a sequence of dictionary lookups in an +efficient way on an existing #GVariant dictionary or it can be used +to construct new dictionaries with a hashtable-like interface. It +can also be used for taking existing dictionaries and modifying them +in order to create new ones. + +#GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT +dictionaries. + +It is possible to use #GVariantDict allocated on the stack or on the +heap. When using a stack-allocated #GVariantDict, you begin with a +call to g_variant_dict_init() and free the resources with a call to +g_variant_dict_clear(). + +Heap-allocated #GVariantDict follows normal refcounting rules: you +allocate it with g_variant_dict_new() and use g_variant_dict_ref() +and g_variant_dict_unref(). + +g_variant_dict_end() is used to convert the #GVariantDict back into a +dictionary-type #GVariant. When used with stack-allocated instances, +this also implicitly frees all associated memory, but for +heap-allocated instances, you must still call g_variant_dict_unref() +afterwards. + +You will typically want to use a heap-allocated #GVariantDict when +you expose it as part of an API. For most other uses, the +stack-allocated form will be more convenient. + +Consider the following two examples that do the same thing in each +style: take an existing dictionary and look up the "count" uint32 +key, adding 1 to it if it is found, or returning an error if the +key is not found. Each returns the new dictionary as a floating +#GVariant. + +## Using a stack-allocated GVariantDict + +|[<!-- language="C" --> + GVariant * + add_to_count (GVariant *orig, + GError **error) + { + GVariantDict dict; + guint32 count; + + g_variant_dict_init (&dict, orig); + if (!g_variant_dict_lookup (&dict, "count", "u", &count)) + { + g_set_error (...); + g_variant_dict_clear (&dict); + return NULL; + } + + g_variant_dict_insert (&dict, "count", "u", count + 1); + + return g_variant_dict_end (&dict); + } +]| + +## Using heap-allocated GVariantDict + +|[<!-- language="C" --> + GVariant * + add_to_count (GVariant *orig, + GError **error) + { + GVariantDict *dict; + GVariant *result; + guint32 count; + + dict = g_variant_dict_new (orig); + + if (g_variant_dict_lookup (dict, "count", "u", &count)) + { + g_variant_dict_insert (dict, "count", "u", count + 1); + result = g_variant_dict_end (dict); + } + else + { + g_set_error (...); + result = NULL; + } + + g_variant_dict_unref (dict); + + return result; + } +]| + + + + + + + + + + + + + + + + + + + + + + Allocates and initialises a new #GVariantDict. + +You should call g_variant_dict_unref() on the return value when it +is no longer needed. The memory will not be automatically freed by +any other call. + +In some cases it may be easier to place a #GVariantDict directly on +the stack of the calling function and initialise it with +g_variant_dict_init(). This is particularly useful when you are +using #GVariantDict to construct a #GVariant. + + a #GVariantDict + + + + + the #GVariant with which to initialise the + dictionary + + + + + + Releases all memory associated with a #GVariantDict without freeing +the #GVariantDict structure itself. + +It typically only makes sense to do this on a stack-allocated +#GVariantDict if you want to abort building the value part-way +through. This function need not be called if you call +g_variant_dict_end() and it also doesn't need to be called on dicts +allocated with g_variant_dict_new (see g_variant_dict_unref() for +that). + +It is valid to call this function on either an initialised +#GVariantDict or one that was previously cleared by an earlier call +to g_variant_dict_clear() but it is not valid to call this function +on uninitialised memory. + + + + + + a #GVariantDict + + + + + + Checks if @key exists in @dict. + + %TRUE if @key is in @dict + + + + + a #GVariantDict + + + + the key to lookup in the dictionary + + + + + + Returns the current value of @dict as a #GVariant of type +%G_VARIANT_TYPE_VARDICT, clearing it in the process. + +It is not permissible to use @dict in any way after this call except +for reference counting operations (in the case of a heap-allocated +#GVariantDict) or by reinitialising it with g_variant_dict_init() (in +the case of stack-allocated). + + a new, floating, #GVariant + + + + + a #GVariantDict + + + + + + Initialises a #GVariantDict structure. + +If @from_asv is given, it is used to initialise the dictionary. + +This function completely ignores the previous contents of @dict. On +one hand this means that it is valid to pass in completely +uninitialised memory. On the other hand, this means that if you are +initialising over top of an existing #GVariantDict you need to first +call g_variant_dict_clear() in order to avoid leaking memory. + +You must not call g_variant_dict_ref() or g_variant_dict_unref() on a +#GVariantDict that was initialised with this function. If you ever +pass a reference to a #GVariantDict outside of the control of your +own code then you should assume that the person receiving that +reference may try to use reference counting; you should use +g_variant_dict_new() instead of this function. + + + + + + a #GVariantDict + + + + the initial value for @dict + + + + + + Inserts a value into a #GVariantDict. + +This call is a convenience wrapper that is exactly equivalent to +calling g_variant_new() followed by g_variant_dict_insert_value(). + + + + + + a #GVariantDict + + + + the key to insert a value for + + + + a #GVariant varargs format string + + + + arguments, as per @format_string + + + + + + Inserts (or replaces) a key in a #GVariantDict. + +@value is consumed if it is floating. + + + + + + a #GVariantDict + + + + the key to insert a value for + + + + the value to insert + + + + + + Looks up a value in a #GVariantDict. + +This function is a wrapper around g_variant_dict_lookup_value() and +g_variant_get(). In the case that %NULL would have been returned, +this function returns %FALSE. Otherwise, it unpacks the returned +value and returns %TRUE. + +@format_string determines the C types that are used for unpacking the +values and also determines if the values are copied or borrowed, see the +section on [GVariant format strings][gvariant-format-strings-pointers]. + + %TRUE if a value was unpacked + + + + + a #GVariantDict + + + + the key to lookup in the dictionary + + + + a GVariant format string + + + + the arguments to unpack the value into + + + + + + Looks up a value in a #GVariantDict. + +If @key is not found in @dictionary, %NULL is returned. + +The @expected_type string specifies what type of value is expected. +If the value associated with @key has a different type then %NULL is +returned. + +If the key is found and the value has the correct type, it is +returned. If @expected_type was specified then any non-%NULL return +value will have this type. + + the value of the dictionary key, or %NULL + + + + + a #GVariantDict + + + + the key to lookup in the dictionary + + + + a #GVariantType, or %NULL + + + + + + Increases the reference count on @dict. + +Don't call this on stack-allocated #GVariantDict instances or bad +things will happen. + + a new reference to @dict + + + + + a heap-allocated #GVariantDict + + + + + + Removes a key and its associated value from a #GVariantDict. + + %TRUE if the key was found and removed + + + + + a #GVariantDict + + + + the key to remove + + + + + + Decreases the reference count on @dict. + +In the event that there are no more references, releases all memory +associated with the #GVariantDict. + +Don't call this on stack-allocated #GVariantDict instances or bad +things will happen. + + + + + + a heap-allocated #GVariantDict + + + + + + + #GVariantIter is an opaque data structure and can only be accessed +using the following functions. + + + + + + + Creates a new heap-allocated #GVariantIter to iterate over the +container that was being iterated over by @iter. Iteration begins on +the new iterator from the current position of the old iterator but +the two copies are independent past that point. + +Use g_variant_iter_free() to free the return value when you no longer +need it. + +A reference is taken to the container that @iter is iterating over +and will be releated only when g_variant_iter_free() is called. + + a new heap-allocated #GVariantIter + + + + + a #GVariantIter + + + + + + Frees a heap-allocated #GVariantIter. Only call this function on +iterators that were returned by g_variant_iter_new() or +g_variant_iter_copy(). + + + + + + a heap-allocated #GVariantIter + + + + + + Initialises (without allocating) a #GVariantIter. @iter may be +completely uninitialised prior to this call; its old value is +ignored. + +The iterator remains valid for as long as @value exists, and need not +be freed in any way. + + the number of items in @value + + + + + a pointer to a #GVariantIter + + + + a container #GVariant + + + + + + Gets the next item in the container and unpacks it into the variable +argument list according to @format_string, returning %TRUE. + +If no more items remain then %FALSE is returned. + +On the first call to this function, the pointers appearing on the +variable argument list are assumed to point at uninitialised memory. +On the second and later calls, it is assumed that the same pointers +will be given and that they will point to the memory as set by the +previous call to this function. This allows the previous values to +be freed, as appropriate. + +This function is intended to be used with a while loop as +demonstrated in the following example. This function can only be +used when iterating over an array. It is only valid to call this +function with a string constant for the format string and the same +string constant must be used each time. Mixing calls to this +function and g_variant_iter_next() or g_variant_iter_next_value() on +the same iterator causes undefined behavior. + +If you break out of a such a while loop using g_variant_iter_loop() then +you must free or unreference all the unpacked values as you would with +g_variant_get(). Failure to do so will cause a memory leak. + +Here is an example for memory management with g_variant_iter_loop(): +|[<!-- language="C" --> + // Iterates a dictionary of type 'a{sv}' + void + iterate_dictionary (GVariant *dictionary) + { + GVariantIter iter; + GVariant *value; + gchar *key; + + g_variant_iter_init (&iter, dictionary); + while (g_variant_iter_loop (&iter, "{sv}", &key, &value)) + { + g_print ("Item '%s' has type '%s'\n", key, + g_variant_get_type_string (value)); + + // no need to free 'key' and 'value' here + // unless breaking out of this loop + } + } +]| + +For most cases you should use g_variant_iter_next(). + +This function is really only useful when unpacking into #GVariant or +#GVariantIter in order to allow you to skip the call to +g_variant_unref() or g_variant_iter_free(). + +For example, if you are only looping over simple integer and string +types, g_variant_iter_next() is definitely preferred. For string +types, use the '&' prefix to avoid allocating any memory at all (and +thereby avoiding the need to free anything as well). + +@format_string determines the C types that are used for unpacking +the values and also determines if the values are copied or borrowed. + +See the section on +[GVariant format strings][gvariant-format-strings-pointers]. + + %TRUE if a value was unpacked, or %FALSE if there was no + value + + + + + a #GVariantIter + + + + a GVariant format string + + + + the arguments to unpack the value into + + + + + + Queries the number of child items in the container that we are +iterating over. This is the total number of items -- not the number +of items remaining. + +This function might be useful for preallocation of arrays. + + the number of children in the container + + + + + a #GVariantIter + + + + + + Gets the next item in the container and unpacks it into the variable +argument list according to @format_string, returning %TRUE. + +If no more items remain then %FALSE is returned. + +All of the pointers given on the variable arguments list of this +function are assumed to point at uninitialised memory. It is the +responsibility of the caller to free all of the values returned by +the unpacking process. + +Here is an example for memory management with g_variant_iter_next(): +|[<!-- language="C" --> + // Iterates a dictionary of type 'a{sv}' + void + iterate_dictionary (GVariant *dictionary) + { + GVariantIter iter; + GVariant *value; + gchar *key; + + g_variant_iter_init (&iter, dictionary); + while (g_variant_iter_next (&iter, "{sv}", &key, &value)) + { + g_print ("Item '%s' has type '%s'\n", key, + g_variant_get_type_string (value)); + + // must free data for ourselves + g_variant_unref (value); + g_free (key); + } + } +]| + +For a solution that is likely to be more convenient to C programmers +when dealing with loops, see g_variant_iter_loop(). + +@format_string determines the C types that are used for unpacking +the values and also determines if the values are copied or borrowed. + +See the section on +[GVariant format strings][gvariant-format-strings-pointers]. + + %TRUE if a value was unpacked, or %FALSE if there as no value + + + + + a #GVariantIter + + + + a GVariant format string + + + + the arguments to unpack the value into + + + + + + Gets the next item in the container. If no more items remain then +%NULL is returned. + +Use g_variant_unref() to drop your reference on the return value when +you no longer need it. + +Here is an example for iterating with g_variant_iter_next_value(): +|[<!-- language="C" --> + // recursively iterate a container + void + iterate_container_recursive (GVariant *container) + { + GVariantIter iter; + GVariant *child; + + g_variant_iter_init (&iter, container); + while ((child = g_variant_iter_next_value (&iter))) + { + g_print ("type '%s'\n", g_variant_get_type_string (child)); + + if (g_variant_is_container (child)) + iterate_container_recursive (child); + + g_variant_unref (child); + } + } +]| + + a #GVariant, or %NULL + + + + + a #GVariantIter + + + + + + + Error codes returned by parsing text-format GVariants. + + generic error (unused) + + + a non-basic #GVariantType was given where a basic type was expected + + + cannot infer the #GVariantType + + + an indefinite #GVariantType was given where a definite type was expected + + + extra data after parsing finished + + + invalid character in number or unicode escape + + + not a valid #GVariant format string + + + not a valid object path + + + not a valid type signature + + + not a valid #GVariant type string + + + could not find a common type for array entries + + + the numerical value is out of range of the given type + + + the numerical value is out of range for any type + + + cannot parse as variant of the specified type + + + an unexpected token was encountered + + + an unknown keyword was encountered + + + unterminated string constant + + + no value given + + + + This section introduces the GVariant type system. It is based, in +large part, on the D-Bus type system, with two major changes and +some minor lifting of restrictions. The +[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html), +therefore, provides a significant amount of +information that is useful when working with GVariant. + +The first major change with respect to the D-Bus type system is the +introduction of maybe (or "nullable") types. Any type in GVariant can be +converted to a maybe type, in which case, "nothing" (or "null") becomes a +valid value. Maybe types have been added by introducing the +character "m" to type strings. + +The second major change is that the GVariant type system supports the +concept of "indefinite types" -- types that are less specific than +the normal types found in D-Bus. For example, it is possible to speak +of "an array of any type" in GVariant, where the D-Bus type system +would require you to speak of "an array of integers" or "an array of +strings". Indefinite types have been added by introducing the +characters "*", "?" and "r" to type strings. + +Finally, all arbitrary restrictions relating to the complexity of +types are lifted along with the restriction that dictionary entries +may only appear nested inside of arrays. + +Just as in D-Bus, GVariant types are described with strings ("type +strings"). Subject to the differences mentioned above, these strings +are of the same form as those found in DBus. Note, however: D-Bus +always works in terms of messages and therefore individual type +strings appear nowhere in its interface. Instead, "signatures" +are a concatenation of the strings of the type of each argument in a +message. GVariant deals with single values directly so GVariant type +strings always describe the type of exactly one value. This means +that a D-Bus signature string is generally not a valid GVariant type +string -- except in the case that it is the signature of a message +containing exactly one argument. + +An indefinite type is similar in spirit to what may be called an +abstract type in other type systems. No value can exist that has an +indefinite type as its type, but values can exist that have types +that are subtypes of indefinite types. That is to say, +g_variant_get_type() will never return an indefinite type, but +calling g_variant_is_of_type() with an indefinite type may return +%TRUE. For example, you cannot have a value that represents "an +array of no particular type", but you can have an "array of integers" +which certainly matches the type of "an array of no particular type", +since "array of integers" is a subtype of "array of no particular +type". + +This is similar to how instances of abstract classes may not +directly exist in other type systems, but instances of their +non-abstract subtypes may. For example, in GTK, no object that has +the type of #GtkBin can exist (since #GtkBin is an abstract class), +but a #GtkWindow can certainly be instantiated, and you would say +that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of +#GtkBin). + +## GVariant Type Strings + +A GVariant type string can be any of the following: + +- any basic type string (listed below) + +- "v", "r" or "*" + +- one of the characters 'a' or 'm', followed by another type string + +- the character '(', followed by a concatenation of zero or more other + type strings, followed by the character ')' + +- the character '{', followed by a basic type string (see below), + followed by another type string, followed by the character '}' + +A basic type string describes a basic type (as per +g_variant_type_is_basic()) and is always a single character in length. +The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t", +"h", "d", "s", "o", "g" and "?". + +The above definition is recursive to arbitrary depth. "aaaaai" and +"(ui(nq((y)))s)" are both valid type strings, as is +"a(aa(ui)(qna{ya(yd)}))". + +The meaning of each of the characters is as follows: +- `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. +- `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte. +- `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer. +- `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer. +- `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer. +- `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer. +- `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer. +- `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer. +- `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value + that, by convention, is used as an index into an array of file + descriptors that are sent alongside a D-Bus message. +- `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision + floating point value. +- `s`: the type string of %G_VARIANT_TYPE_STRING; a string. +- `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form + of a D-Bus object path. +- `g`: the type string of %G_VARIANT_TYPE_STRING; a string in the form of + a D-Bus type signature. +- `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that + is a supertype of any of the basic types. +- `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that + contain any other type of value. +- `a`: used as a prefix on another type string to mean an array of that + type; the type string "ai", for example, is the type of an array of + signed 32-bit integers. +- `m`: used as a prefix on another type string to mean a "maybe", or + "nullable", version of that type; the type string "ms", for example, + is the type of a value that maybe contains a string, or maybe contains + nothing. +- `()`: used to enclose zero or more other concatenated type strings to + create a tuple type; the type string "(is)", for example, is the type of + a pair of an integer and a string. +- `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is + a supertype of any tuple type, regardless of the number of items. +- `{}`: used to enclose a basic type string concatenated with another type + string to create a dictionary entry type, which usually appears inside of + an array to form a dictionary; the type string "a{sd}", for example, is + the type of a dictionary that maps strings to double precision floating + point values. + + The first type (the basic type) is the key type and the second type is + the value type. The reason that the first type is restricted to being a + basic type is so that it can easily be hashed. +- `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is + a supertype of all types. Note that, as with all type strings, this + character represents exactly one type. It cannot be used inside of tuples + to mean "any number of items". + +Any type string of a container that contains an indefinite type is, +itself, an indefinite type. For example, the type string "a*" +(corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type +that is a supertype of every array type. "(*s)" is a supertype +of all tuples that contain exactly two items where the second +item is a string. + +"a{?*}" is an indefinite type that is a supertype of all arrays +containing dictionary entries where the key is any basic type and +the value is any type at all. This is, by definition, a dictionary, +so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note +that, due to the restriction that the key of a dictionary entry must +be a basic type, "{**}" is not a valid type string. + + Creates a new #GVariantType corresponding to the type string given +by @type_string. It is appropriate to call g_variant_type_free() on +the return value. + +It is a programmer error to call this function with an invalid type +string. Use g_variant_type_string_is_valid() if you are unsure. + + a new #GVariantType + + + + + a valid GVariant type string + + + + + + Constructs the type corresponding to an array of elements of the +type @type. + +It is appropriate to call g_variant_type_free() on the return value. + + a new array #GVariantType + +Since 2.24 + + + + + a #GVariantType + + + + + + Constructs the type corresponding to a dictionary entry with a key +of type @key and a value of type @value. + +It is appropriate to call g_variant_type_free() on the return value. + + a new dictionary entry #GVariantType + +Since 2.24 + + + + + a basic #GVariantType + + + + a #GVariantType + + + + + + Constructs the type corresponding to a maybe instance containing +type @type or Nothing. + +It is appropriate to call g_variant_type_free() on the return value. + + a new maybe #GVariantType + +Since 2.24 + + + + + a #GVariantType + + + + + + Constructs a new tuple type, from @items. + +@length is the number of items in @items, or -1 to indicate that +@items is %NULL-terminated. + +It is appropriate to call g_variant_type_free() on the return value. + + a new tuple #GVariantType + +Since 2.24 + + + + + an array of #GVariantTypes, one for each item + + + + + + the length of @items, or -1 + + + + + + Makes a copy of a #GVariantType. It is appropriate to call +g_variant_type_free() on the return value. @type may not be %NULL. + + a new #GVariantType + +Since 2.24 + + + + + a #GVariantType + + + + + + Returns a newly-allocated copy of the type string corresponding to +@type. The returned string is nul-terminated. It is appropriate to +call g_free() on the return value. + + the corresponding type string + +Since 2.24 + + + + + a #GVariantType + + + + + + Determines the element type of an array or maybe type. + +This function may only be used with array or maybe types. + + the element type of @type + +Since 2.24 + + + + + an array or maybe #GVariantType + + + + + + Compares @type1 and @type2 for equality. + +Only returns %TRUE if the types are exactly equal. Even if one type +is an indefinite type and the other is a subtype of it, %FALSE will +be returned if they are not exactly equal. If you want to check for +subtypes, use g_variant_type_is_subtype_of(). + +The argument types of @type1 and @type2 are only #gconstpointer to +allow use with #GHashTable without function pointer casting. For +both arguments, a valid #GVariantType must be provided. + + %TRUE if @type1 and @type2 are exactly equal + +Since 2.24 + + + + + a #GVariantType + + + + a #GVariantType + + + + + + Determines the first item type of a tuple or dictionary entry +type. + +This function may only be used with tuple or dictionary entry types, +but must not be used with the generic tuple type +%G_VARIANT_TYPE_TUPLE. + +In the case of a dictionary entry type, this returns the type of +the key. + +%NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT. + +This call, together with g_variant_type_next() provides an iterator +interface over tuple and dictionary entry types. + + the first item type of @type, or %NULL + +Since 2.24 + + + + + a tuple or dictionary entry #GVariantType + + + + + + Frees a #GVariantType that was allocated with +g_variant_type_copy(), g_variant_type_new() or one of the container +type constructor functions. + +In the case that @type is %NULL, this function does nothing. + +Since 2.24 + + + + + + a #GVariantType, or %NULL + + + + + + Returns the length of the type string corresponding to the given +@type. This function must be used to determine the valid extent of +the memory region returned by g_variant_type_peek_string(). + + the length of the corresponding type string + +Since 2.24 + + + + + a #GVariantType + + + + + + Hashes @type. + +The argument type of @type is only #gconstpointer to allow use with +#GHashTable without function pointer casting. A valid +#GVariantType must be provided. + + the hash value + +Since 2.24 + + + + + a #GVariantType + + + + + + Determines if the given @type is an array type. This is true if the +type string for @type starts with an 'a'. + +This function returns %TRUE for any indefinite type for which every +definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for +example. + + %TRUE if @type is an array type + +Since 2.24 + + + + + a #GVariantType + + + + + + Determines if the given @type is a basic type. + +Basic types are booleans, bytes, integers, doubles, strings, object +paths and signatures. + +Only a basic type may be used as the key of a dictionary entry. + +This function returns %FALSE for all indefinite types except +%G_VARIANT_TYPE_BASIC. + + %TRUE if @type is a basic type + +Since 2.24 + + + + + a #GVariantType + + + + + + Determines if the given @type is a container type. + +Container types are any array, maybe, tuple, or dictionary +entry types plus the variant type. + +This function returns %TRUE for any indefinite type for which every +definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for +example. + + %TRUE if @type is a container type + +Since 2.24 + + + + + a #GVariantType + + + + + + Determines if the given @type is definite (ie: not indefinite). + +A type is definite if its type string does not contain any indefinite +type characters ('*', '?', or 'r'). + +A #GVariant instance may not have an indefinite type, so calling +this function on the result of g_variant_get_type() will always +result in %TRUE being returned. Calling this function on an +indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in +%FALSE being returned. + + %TRUE if @type is definite + +Since 2.24 + + + + + a #GVariantType + + + + + + Determines if the given @type is a dictionary entry type. This is +true if the type string for @type starts with a '{'. + +This function returns %TRUE for any indefinite type for which every +definite subtype is a dictionary entry type -- +%G_VARIANT_TYPE_DICT_ENTRY, for example. + + %TRUE if @type is a dictionary entry type + +Since 2.24 + + + + + a #GVariantType + + + + + + Determines if the given @type is a maybe type. This is true if the +type string for @type starts with an 'm'. + +This function returns %TRUE for any indefinite type for which every +definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for +example. + + %TRUE if @type is a maybe type + +Since 2.24 + + + + + a #GVariantType + + + + + + Checks if @type is a subtype of @supertype. + +This function returns %TRUE if @type is a subtype of @supertype. All +types are considered to be subtypes of themselves. Aside from that, +only indefinite types can have subtypes. + + %TRUE if @type is a subtype of @supertype + +Since 2.24 + + + + + a #GVariantType + + + + a #GVariantType + + + + + + Determines if the given @type is a tuple type. This is true if the +type string for @type starts with a '(' or if @type is +%G_VARIANT_TYPE_TUPLE. + +This function returns %TRUE for any indefinite type for which every +definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for +example. + + %TRUE if @type is a tuple type + +Since 2.24 + + + + + a #GVariantType + + + + + + Determines if the given @type is the variant type. + + %TRUE if @type is the variant type + +Since 2.24 + + + + + a #GVariantType + + + + + + Determines the key type of a dictionary entry type. + +This function may only be used with a dictionary entry type. Other +than the additional restriction, this call is equivalent to +g_variant_type_first(). + + the key type of the dictionary entry + +Since 2.24 + + + + + a dictionary entry #GVariantType + + + + + + Determines the number of items contained in a tuple or +dictionary entry type. + +This function may only be used with tuple or dictionary entry types, +but must not be used with the generic tuple type +%G_VARIANT_TYPE_TUPLE. + +In the case of a dictionary entry type, this function will always +return 2. + + the number of items in @type + +Since 2.24 + + + + + a tuple or dictionary entry #GVariantType + + + + + + Determines the next item type of a tuple or dictionary entry +type. + +@type must be the result of a previous call to +g_variant_type_first() or g_variant_type_next(). + +If called on the key type of a dictionary entry then this call +returns the value type. If called on the value type of a dictionary +entry then this call returns %NULL. + +For tuples, %NULL is returned when @type is the last item in a tuple. + + the next #GVariantType after @type, or %NULL + +Since 2.24 + + + + + a #GVariantType from a previous call + + + + + + Returns the type string corresponding to the given @type. The +result is not nul-terminated; in order to determine its length you +must call g_variant_type_get_string_length(). + +To get a nul-terminated string, see g_variant_type_dup_string(). + + the corresponding type string (not nul-terminated) + +Since 2.24 + + + + + a #GVariantType + + + + + + Determines the value type of a dictionary entry type. + +This function may only be used with a dictionary entry type. + + the value type of the dictionary entry + +Since 2.24 + + + + + a dictionary entry #GVariantType + + + + + + + + + + + + + + + + Checks if @type_string is a valid GVariant type string. This call is +equivalent to calling g_variant_type_string_scan() and confirming +that the following character is a nul terminator. + + %TRUE if @type_string is exactly one valid type string + +Since 2.24 + + + + + a pointer to any string + + + + + + Scan for a single complete and valid GVariant type string in @string. +The memory pointed to by @limit (or bytes beyond it) is never +accessed. + +If a valid type string is found, @endptr is updated to point to the +first character past the end of the string that was found and %TRUE +is returned. + +If there is no valid type string starting at @string, or if the type +string does not end before @limit then %FALSE is returned. + +For the simple case of checking if a string is a valid type string, +see g_variant_type_string_is_valid(). + + %TRUE if a valid type string was found + + + + + a pointer to any string + + + + the end of @string, or %NULL + + + + location to store the end pointer, or %NULL + + + + + + + Declares a type of function which takes no arguments +and has no return value. It is used to specify the type +function passed to g_atexit(). + + + + + + + + + A wrapper for the POSIX access() function. This function is used to +test a pathname for one or several of read, write or execute +permissions, or just existence. + +On Windows, the file protection mechanism is not at all POSIX-like, +and the underlying function in the C library only checks the +FAT-style READONLY attribute, and does not look at the ACL of a +file at all. This function is this in practise almost useless on +Windows. Software that needs to handle file permissions on Windows +more exactly should use the Win32 API. + +See your C library manual for more details about access(). + + zero if the pathname refers to an existing file system + object that has all the tested permissions, or -1 otherwise + or on error. + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + as in access() + + + + + + Determines the numeric value of a character as a decimal digit. +Differs from g_unichar_digit_value() because it takes a char, so +there's no worry about sign extension if characters are signed. + + If @c is a decimal digit (according to g_ascii_isdigit()), + its numeric value. Otherwise, -1. + + + + + an ASCII character + + + + + + Converts a #gdouble to a string, using the '.' as +decimal point. + +This function generates enough precision that converting +the string back using g_ascii_strtod() gives the same machine-number +(on machines with IEEE compatible 64bit doubles). It is +guaranteed that the size of the resulting string will never +be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating +nul character, which is always added. + + The pointer to the buffer with the converted string. + + + + + A buffer to place the resulting string in + + + + The length of the buffer. + + + + The #gdouble to convert + + + + + + Converts a #gdouble to a string, using the '.' as +decimal point. To format the number you pass in +a printf()-style format string. Allowed conversion +specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'. + +The returned buffer is guaranteed to be nul-terminated. + +If you just want to want to serialize the value into a +string, use g_ascii_dtostr(). + + The pointer to the buffer with the converted string. + + + + + A buffer to place the resulting string in + + + + The length of the buffer. + + + + The printf()-style format to use for the + code to use for converting. + + + + The #gdouble to convert + + + + + + Compare two strings, ignoring the case of ASCII characters. + +Unlike the BSD strcasecmp() function, this only recognizes standard +ASCII letters and ignores the locale, treating all non-ASCII +bytes as if they are not letters. + +This function should be used only on strings that are known to be +in encodings where the bytes corresponding to ASCII letters always +represent themselves. This includes UTF-8 and the ISO-8859-* +charsets, but not for instance double-byte encodings like the +Windows Codepage 932, where the trailing bytes of double-byte +characters include all ASCII letters. If you compare two CP932 +strings using this function, you will get false matches. + +Both @s1 and @s2 must be non-%NULL. + + 0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2. + + + + + string to compare with @s2 + + + + string to compare with @s1 + + + + + + Converts all upper case ASCII letters to lower case ASCII letters. + + a newly-allocated string, with all the upper case + characters in @str converted to lower case, with semantics that + exactly match g_ascii_tolower(). (Note that this is unlike the + old g_strdown(), which modified the string in place.) + + + + + a string + + + + length of @str in bytes, or -1 if @str is nul-terminated + + + + + + Compare @s1 and @s2, ignoring the case of ASCII characters and any +characters after the first @n in each string. + +Unlike the BSD strcasecmp() function, this only recognizes standard +ASCII letters and ignores the locale, treating all non-ASCII +characters as if they are not letters. + +The same warning as in g_ascii_strcasecmp() applies: Use this +function only on strings known to be in encodings where bytes +corresponding to ASCII letters always represent themselves. + + 0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2. + + + + + string to compare with @s2 + + + + string to compare with @s1 + + + + number of characters to compare + + + + + + Converts a string to a #gdouble value. + +This function behaves like the standard strtod() function +does in the C locale. It does this without actually changing +the current locale, since that would not be thread-safe. +A limitation of the implementation is that this function +will still accept localized versions of infinities and NANs. + +This function is typically used when reading configuration +files or other non-user input that should be locale independent. +To handle input from the user you should normally use the +locale-sensitive system strtod() function. + +To convert from a #gdouble to a string in a locale-insensitive +way, use g_ascii_dtostr(). + +If the correct value would cause overflow, plus or minus %HUGE_VAL +is returned (according to the sign of the value), and %ERANGE is +stored in %errno. If the correct value would cause underflow, +zero is returned and %ERANGE is stored in %errno. + +This function resets %errno before calling strtod() so that +you can reliably detect overflow and underflow. + + the #gdouble value. + + + + + the string to convert to a numeric value. + + + + if non-%NULL, it returns the + character after the last character used in the conversion. + + + + + + Converts a string to a #gint64 value. +This function behaves like the standard strtoll() function +does in the C locale. It does this without actually +changing the current locale, since that would not be +thread-safe. + +This function is typically used when reading configuration +files or other non-user input that should be locale independent. +To handle input from the user you should normally use the +locale-sensitive system strtoll() function. + +If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64 +is returned, and `ERANGE` is stored in `errno`. +If the base is outside the valid range, zero is returned, and +`EINVAL` is stored in `errno`. If the +string conversion fails, zero is returned, and @endptr returns @nptr +(if @endptr is non-%NULL). + + the #gint64 value or zero on error. + + + + + the string to convert to a numeric value. + + + + if non-%NULL, it returns the + character after the last character used in the conversion. + + + + to be used for the conversion, 2..36 or 0 + + + + + + Converts a string to a #guint64 value. +This function behaves like the standard strtoull() function +does in the C locale. It does this without actually +changing the current locale, since that would not be +thread-safe. + +This function is typically used when reading configuration +files or other non-user input that should be locale independent. +To handle input from the user you should normally use the +locale-sensitive system strtoull() function. + +If the correct value would cause overflow, %G_MAXUINT64 +is returned, and `ERANGE` is stored in `errno`. +If the base is outside the valid range, zero is returned, and +`EINVAL` is stored in `errno`. +If the string conversion fails, zero is returned, and @endptr returns +@nptr (if @endptr is non-%NULL). + + the #guint64 value or zero on error. + + + + + the string to convert to a numeric value. + + + + if non-%NULL, it returns the + character after the last character used in the conversion. + + + + to be used for the conversion, 2..36 or 0 + + + + + + Converts all lower case ASCII letters to upper case ASCII letters. + + a newly allocated string, with all the lower case + characters in @str converted to upper case, with semantics that + exactly match g_ascii_toupper(). (Note that this is unlike the + old g_strup(), which modified the string in place.) + + + + + a string + + + + length of @str in bytes, or -1 if @str is nul-terminated + + + + + + Convert a character to ASCII lower case. + +Unlike the standard C library tolower() function, this only +recognizes standard ASCII letters and ignores the locale, returning +all non-ASCII characters unchanged, even if they are lower case +letters in a particular character set. Also unlike the standard +library function, this takes and returns a char, not an int, so +don't call it on %EOF but no need to worry about casting to #guchar +before passing a possibly non-ASCII character in. + + the result of converting @c to lower case. If @c is + not an ASCII upper case letter, @c is returned unchanged. + + + + + any character + + + + + + Convert a character to ASCII upper case. + +Unlike the standard C library toupper() function, this only +recognizes standard ASCII letters and ignores the locale, returning +all non-ASCII characters unchanged, even if they are upper case +letters in a particular character set. Also unlike the standard +library function, this takes and returns a char, not an int, so +don't call it on %EOF but no need to worry about casting to #guchar +before passing a possibly non-ASCII character in. + + the result of converting @c to upper case. If @c is not + an ASCII lower case letter, @c is returned unchanged. + + + + + any character + + + + + + Determines the numeric value of a character as a hexidecimal +digit. Differs from g_unichar_xdigit_value() because it takes +a char, so there's no worry about sign extension if characters +are signed. + + If @c is a hex digit (according to g_ascii_isxdigit()), + its numeric value. Otherwise, -1. + + + + + an ASCII character. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specifies a function to be called at normal program termination. + +Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor +macro that maps to a call to the atexit() function in the C +library. This means that in case the code that calls g_atexit(), +i.e. atexit(), is in a DLL, the function will be called when the +DLL is detached from the program. This typically makes more sense +than that the function is called when the GLib DLL is detached, +which happened earlier when g_atexit() was a function in the GLib +DLL. + +The behaviour of atexit() in the context of dynamically loaded +modules is not formally specified and varies wildly. + +On POSIX systems, calling g_atexit() (or atexit()) in a dynamically +loaded module which is unloaded before the program terminates might +well cause a crash at program exit. + +Some POSIX systems implement atexit() like Windows, and have each +dynamically loaded module maintain an own atexit chain that is +called when the module is unloaded. + +On other POSIX systems, before a dynamically loaded module is +unloaded, the registered atexit functions (if any) residing in that +module are called, regardless where the code that registered them +resided. This is presumably the most robust approach. + +As can be seen from the above, for portability it's best to avoid +calling g_atexit() (or atexit()) except in the main executable of a +program. + It is best to avoid g_atexit(). + + + + + + the function to call on normal program termination. + + + + + + Atomically adds @val to the value of @atomic. + +Think of this operation as an atomic version of +`{ tmp = *atomic; *atomic += val; return tmp; }`. + +This call acts as a full compiler and hardware memory barrier. + +Before version 2.30, this function did not return a value +(but g_atomic_int_exchange_and_add() did, and had the same meaning). + + the value of @atomic before the add, signed + + + + + a pointer to a #gint or #guint + + + + the value to add + + + + + + Performs an atomic bitwise 'and' of the value of @atomic and @val, +storing the result back in @atomic. + +This call acts as a full compiler and hardware memory barrier. + +Think of this operation as an atomic version of +`{ tmp = *atomic; *atomic &= val; return tmp; }`. + + the value of @atomic before the operation, unsigned + + + + + a pointer to a #gint or #guint + + + + the value to 'and' + + + + + + Compares @atomic to @oldval and, if equal, sets it to @newval. +If @atomic was not equal to @oldval then no change occurs. + +This compare and exchange is done atomically. + +Think of this operation as an atomic version of +`{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. + +This call acts as a full compiler and hardware memory barrier. + + %TRUE if the exchange took place + + + + + a pointer to a #gint or #guint + + + + the value to compare with + + + + the value to conditionally replace with + + + + + + Decrements the value of @atomic by 1. + +Think of this operation as an atomic version of +`{ *atomic -= 1; return (*atomic == 0); }`. + +This call acts as a full compiler and hardware memory barrier. + + %TRUE if the resultant value is zero + + + + + a pointer to a #gint or #guint + + + + + + This function existed before g_atomic_int_add() returned the prior +value of the integer (which it now does). It is retained only for +compatibility reasons. Don't use this function in new code. + Use g_atomic_int_add() instead. + + the value of @atomic before the add, signed + + + + + a pointer to a #gint + + + + the value to add + + + + + + Gets the current value of @atomic. + +This call acts as a full compiler and hardware +memory barrier (before the get). + + the value of the integer + + + + + a pointer to a #gint or #guint + + + + + + Increments the value of @atomic by 1. + +Think of this operation as an atomic version of `{ *atomic += 1; }`. + +This call acts as a full compiler and hardware memory barrier. + + + + + + a pointer to a #gint or #guint + + + + + + Performs an atomic bitwise 'or' of the value of @atomic and @val, +storing the result back in @atomic. + +Think of this operation as an atomic version of +`{ tmp = *atomic; *atomic |= val; return tmp; }`. + +This call acts as a full compiler and hardware memory barrier. + + the value of @atomic before the operation, unsigned + + + + + a pointer to a #gint or #guint + + + + the value to 'or' + + + + + + Sets the value of @atomic to @newval. + +This call acts as a full compiler and hardware +memory barrier (after the set). + + + + + + a pointer to a #gint or #guint + + + + a new value to store + + + + + + Performs an atomic bitwise 'xor' of the value of @atomic and @val, +storing the result back in @atomic. + +Think of this operation as an atomic version of +`{ tmp = *atomic; *atomic ^= val; return tmp; }`. + +This call acts as a full compiler and hardware memory barrier. + + the value of @atomic before the operation, unsigned + + + + + a pointer to a #gint or #guint + + + + the value to 'xor' + + + + + + Atomically adds @val to the value of @atomic. + +Think of this operation as an atomic version of +`{ tmp = *atomic; *atomic += val; return tmp; }`. + +This call acts as a full compiler and hardware memory barrier. + + the value of @atomic before the add, signed + + + + + a pointer to a #gpointer-sized value + + + + the value to add + + + + + + Performs an atomic bitwise 'and' of the value of @atomic and @val, +storing the result back in @atomic. + +Think of this operation as an atomic version of +`{ tmp = *atomic; *atomic &= val; return tmp; }`. + +This call acts as a full compiler and hardware memory barrier. + + the value of @atomic before the operation, unsigned + + + + + a pointer to a #gpointer-sized value + + + + the value to 'and' + + + + + + Compares @atomic to @oldval and, if equal, sets it to @newval. +If @atomic was not equal to @oldval then no change occurs. + +This compare and exchange is done atomically. + +Think of this operation as an atomic version of +`{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. + +This call acts as a full compiler and hardware memory barrier. + + %TRUE if the exchange took place + + + + + a pointer to a #gpointer-sized value + + + + the value to compare with + + + + the value to conditionally replace with + + + + + + Gets the current value of @atomic. + +This call acts as a full compiler and hardware +memory barrier (before the get). + + the value of the pointer + + + + + a pointer to a #gpointer-sized value + + + + + + Performs an atomic bitwise 'or' of the value of @atomic and @val, +storing the result back in @atomic. + +Think of this operation as an atomic version of +`{ tmp = *atomic; *atomic |= val; return tmp; }`. + +This call acts as a full compiler and hardware memory barrier. + + the value of @atomic before the operation, unsigned + + + + + a pointer to a #gpointer-sized value + + + + the value to 'or' + + + + + + Sets the value of @atomic to @newval. + +This call acts as a full compiler and hardware +memory barrier (after the set). + + + + + + a pointer to a #gpointer-sized value + + + + a new value to store + + + + + + Performs an atomic bitwise 'xor' of the value of @atomic and @val, +storing the result back in @atomic. + +Think of this operation as an atomic version of +`{ tmp = *atomic; *atomic ^= val; return tmp; }`. + +This call acts as a full compiler and hardware memory barrier. + + the value of @atomic before the operation, unsigned + + + + + a pointer to a #gpointer-sized value + + + + the value to 'xor' + + + + + + Decode a sequence of Base-64 encoded text into binary data. Note +that the returned binary data is not necessarily zero-terminated, +so it should not be used as a character string. + + + newly allocated buffer containing the binary data + that @text represents. The returned buffer must + be freed with g_free(). + + + + + + + zero-terminated string with base64 text to decode + + + + The length of the decoded data is written here + + + + + + Decode a sequence of Base-64 encoded text into binary data +by overwriting the input data. + + The binary data that @text responds. This pointer + is the same as the input @text. + + + + + zero-terminated + string with base64 text to decode + + + + + + The length of the decoded data is written here + + + + + + Incrementally decode a sequence of binary data from its Base-64 stringified +representation. By calling this function multiple times you can convert +data in chunks to avoid having to have the full encoded data in memory. + +The output buffer must be large enough to fit all the data that will +be written to it. Since base64 encodes 3 bytes in 4 chars you need +at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero +state). + + The number of bytes of output that was written + + + + + binary input data + + + + + + max length of @in data to decode + + + + output buffer + + + + + + Saved state between steps, initialize to 0 + + + + Saved state between steps, initialize to 0 + + + + + + Encode a sequence of binary data into its Base-64 stringified +representation. + + a newly allocated, zero-terminated Base-64 + encoded string representing @data. The returned string must + be freed with g_free(). + + + + + the binary data to encode + + + + + + the length of @data + + + + + + Flush the status from a sequence of calls to g_base64_encode_step(). + +The output buffer must be large enough to fit all the data that will +be written to it. It will need up to 4 bytes, or up to 5 bytes if +line-breaking is enabled. + + The number of bytes of output that was written + + + + + whether to break long lines + + + + pointer to destination buffer + + + + + + Saved state from g_base64_encode_step() + + + + Saved state from g_base64_encode_step() + + + + + + Incrementally encode a sequence of binary data into its Base-64 stringified +representation. By calling this function multiple times you can convert +data in chunks to avoid having to have the full encoded data in memory. + +When all of the data has been converted you must call +g_base64_encode_close() to flush the saved state. + +The output buffer must be large enough to fit all the data that will +be written to it. Due to the way base64 encodes you will need +at least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of +non-zero state). If you enable line-breaking you will need at least: +((@len / 3 + 1) * 4 + 4) / 72 + 1 bytes of extra space. + +@break_lines is typically used when putting base64-encoded data in emails. +It breaks the lines at 72 columns instead of putting all of the text on +the same line. This avoids problems with long lines in the email system. +Note however that it breaks the lines with `LF` characters, not +`CR LF` sequences, so the result cannot be passed directly to SMTP +or certain other protocols. + + The number of bytes of output that was written + + + + + the binary data to encode + + + + + + the length of @in + + + + whether to break long lines + + + + pointer to destination buffer + + + + + + Saved state between steps, initialize to 0 + + + + Saved state between steps, initialize to 0 + + + + + + Gets the name of the file without any leading directory +components. It returns a pointer into the given file name +string. + Use g_path_get_basename() instead, but notice + that g_path_get_basename() allocates new memory for the + returned string, unlike this function which returns a pointer + into the argument. + + the name of the file without any leading + directory components + + + + + the name of the file + + + + + + Sets the indicated @lock_bit in @address. If the bit is already +set, this call will block until g_bit_unlock() unsets the +corresponding bit. + +Attempting to lock on two different bits within the same integer is +not supported and will very probably cause deadlocks. + +The value of the bit that is set is (1u << @bit). If @bit is not +between 0 and 31 then the result is undefined. + +This function accesses @address atomically. All other accesses to +@address must be atomic in order for this function to work +reliably. + + + + + + a pointer to an integer + + + + a bit value between 0 and 31 + + + + + + Find the position of the first bit set in @mask, searching +from (but not including) @nth_bit upwards. Bits are numbered +from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, +usually). To start searching from the 0th bit, set @nth_bit to -1. + + the index of the first bit set which is higher than @nth_bit, or -1 + if no higher bits are set + + + + + a #gulong containing flags + + + + the index of the bit to start the search from + + + + + + Find the position of the first bit set in @mask, searching +from (but not including) @nth_bit downwards. Bits are numbered +from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, +usually). To start searching from the last bit, set @nth_bit to +-1 or GLIB_SIZEOF_LONG * 8. + + the index of the first bit set which is lower than @nth_bit, or -1 + if no lower bits are set + + + + + a #gulong containing flags + + + + the index of the bit to start the search from + + + + + + Gets the number of bits used to hold @number, +e.g. if @number is 4, 3 bits are needed. + + the number of bits used to hold @number + + + + + a #guint + + + + + + Sets the indicated @lock_bit in @address, returning %TRUE if +successful. If the bit is already set, returns %FALSE immediately. + +Attempting to lock on two different bits within the same integer is +not supported. + +The value of the bit that is set is (1u << @bit). If @bit is not +between 0 and 31 then the result is undefined. + +This function accesses @address atomically. All other accesses to +@address must be atomic in order for this function to work +reliably. + + %TRUE if the lock was acquired + + + + + a pointer to an integer + + + + a bit value between 0 and 31 + + + + + + Clears the indicated @lock_bit in @address. If another thread is +currently blocked in g_bit_lock() on this same bit then it will be +woken up. + +This function accesses @address atomically. All other accesses to +@address must be atomic in order for this function to work +reliably. + + + + + + a pointer to an integer + + + + a bit value between 0 and 31 + + + + + + + + + + + Creates a filename from a series of elements using the correct +separator for filenames. + +On Unix, this function behaves identically to `g_build_path +(G_DIR_SEPARATOR_S, first_element, ....)`. + +On Windows, it takes into account that either the backslash +(`\` or slash (`/`) can be used as separator in filenames, but +otherwise behaves as on UNIX. When file pathname separators need +to be inserted, the one that last previously occurred in the +parameters (reading from left to right) is used. + +No attempt is made to force the resulting filename to be an absolute +path. If the first element is a relative path, the result will +be a relative path. + + a newly-allocated string that must be freed with + g_free(). + + + + + the first element in the path + + + + remaining elements in path, terminated by %NULL + + + + + + Behaves exactly like g_build_filename(), but takes the path elements +as a string array, instead of varargs. This function is mainly +meant for language bindings. + + a newly-allocated string that must be freed + with g_free(). + + + + + %NULL-terminated + array of strings containing the path elements. + + + + + + + + Creates a path from a series of elements using @separator as the +separator between elements. At the boundary between two elements, +any trailing occurrences of separator in the first element, or +leading occurrences of separator in the second element are removed +and exactly one copy of the separator is inserted. + +Empty elements are ignored. + +The number of leading copies of the separator on the result is +the same as the number of leading copies of the separator on +the first non-empty element. + +The number of trailing copies of the separator on the result is +the same as the number of trailing copies of the separator on +the last non-empty element. (Determination of the number of +trailing copies is done without stripping leading copies, so +if the separator is `ABA`, then `ABABA` has 1 trailing copy.) + +However, if there is only a single non-empty element, and there +are no characters in that element not part of the leading or +trailing separators, then the result is exactly the original value +of that element. + +Other than for determination of the number of leading and trailing +copies of the separator, elements consisting only of copies +of the separator are ignored. + + a newly-allocated string that must be freed with + g_free(). + + + + + a string used to separator the elements of the path. + + + + the first element in the path + + + + remaining elements in path, terminated by %NULL + + + + + + Behaves exactly like g_build_path(), but takes the path elements +as a string array, instead of varargs. This function is mainly +meant for language bindings. + + a newly-allocated string that must be freed + with g_free(). + + + + + a string used to separator the elements of the path. + + + + %NULL-terminated + array of strings containing the path elements. + + + + + + + + Frees the memory allocated by the #GByteArray. If @free_segment is +%TRUE it frees the actual byte data. If the reference count of +@array is greater than one, the #GByteArray wrapper is preserved but +the size of @array will be set to zero. + + the element data if @free_segment is %FALSE, otherwise + %NULL. The element data should be freed using g_free(). + + + + + a #GByteArray + + + + + + if %TRUE the actual byte data is freed as well + + + + + + Transfers the data from the #GByteArray into a new immutable #GBytes. + +The #GByteArray is freed unless the reference count of @array is greater +than one, the #GByteArray wrapper is preserved but the size of @array +will be set to zero. + +This is identical to using g_bytes_new_take() and g_byte_array_free() +together. + + a new immutable #GBytes representing same + byte data that was in the array + + + + + a #GByteArray + + + + + + + + Creates a new #GByteArray with a reference count of 1. + + the new #GByteArray + + + + + + + Create byte array containing the data. The data will be owned by the array +and will be freed with g_free(), i.e. it could be allocated using g_strdup(). + + a new #GByteArray + + + + + + + byte data for the array + + + + + + length of @data + + + + + + Atomically decrements the reference count of @array by one. If the +reference count drops to 0, all memory allocated by the array is +released. This function is thread-safe and may be called from any +thread. + + + + + + A #GByteArray + + + + + + + + A wrapper for the POSIX chdir() function. The function changes the +current directory of the process to @path. + +See your C library manual for more details about chdir(). + + 0 on success, -1 if an error occurred. + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + + + Checks that the GLib library in use is compatible with the +given version. Generally you would pass in the constants +#GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION +as the three arguments to this function; that produces +a check that the library in use is compatible with +the version of GLib the application or module was compiled +against. + +Compatibility is defined by two things: first the version +of the running library is newer than the version +@required_major.required_minor.@required_micro. Second +the running library must be binary compatible with the +version @required_major.required_minor.@required_micro +(same major version.) + + %NULL if the GLib library is compatible with the + given version, or a string describing the version mismatch. + The returned string is owned by GLib and must not be modified + or freed. + + + + + the required major version + + + + the required minor version + + + + the required micro version + + + + + + Gets the length in bytes of digests of type @checksum_type + + the checksum length, or -1 if @checksum_type is +not supported. + + + + + a #GChecksumType + + + + + + Sets a function to be called when the child indicated by @pid +exits, at a default priority, #G_PRIORITY_DEFAULT. + +If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() +you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to +the spawn function for the child watching to work. + +Note that on platforms where #GPid must be explicitly closed +(see g_spawn_close_pid()) @pid must not be closed while the +source is still active. Typically, you will want to call +g_spawn_close_pid() in the callback function for the source. + +GLib supports only a single callback per process id. + +This internally creates a main loop source using +g_child_watch_source_new() and attaches it to the main loop context +using g_source_attach(). You can do these steps manually if you +need greater control. + + the ID (greater than 0) of the event source. + + + + + process id to watch. On POSIX the positive pid of a child +process. On Windows a handle for a process (which doesn't have to be +a child). + + + + function to call + + + + data to pass to @function + + + + + + Sets a function to be called when the child indicated by @pid +exits, at the priority @priority. + +If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() +you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to +the spawn function for the child watching to work. + +In many programs, you will want to call g_spawn_check_exit_status() +in the callback to determine whether or not the child exited +successfully. + +Also, note that on platforms where #GPid must be explicitly closed +(see g_spawn_close_pid()) @pid must not be closed while the source +is still active. Typically, you should invoke g_spawn_close_pid() +in the callback function for the source. + +GLib supports only a single callback per process id. + +This internally creates a main loop source using +g_child_watch_source_new() and attaches it to the main loop context +using g_source_attach(). You can do these steps manually if you +need greater control. + + the ID (greater than 0) of the event source. + + + + + the priority of the idle source. Typically this will be in the + range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + + + + process to watch. On POSIX the positive pid of a child process. On +Windows a handle for a process (which doesn't have to be a child). + + + + function to call + + + + data to pass to @function + + + + function to call when the idle is removed, or %NULL + + + + + + Creates a new child_watch source. + +The source will not initially be associated with any #GMainContext +and must be added to one with g_source_attach() before it will be +executed. + +Note that child watch sources can only be used in conjunction with +`g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used. + +Note that on platforms where #GPid must be explicitly closed +(see g_spawn_close_pid()) @pid must not be closed while the +source is still active. Typically, you will want to call +g_spawn_close_pid() in the callback function for the source. + +Note further that using g_child_watch_source_new() is not +compatible with calling `waitpid` with a nonpositive first +argument in the application. Calling waitpid() for individual +pids will still work fine. + +Similarly, on POSIX platforms, the @pid passed to this function must +be greater than 0 (i.e. this function must wait for a specific child, +and cannot wait for one of many children by using a nonpositive argument). + + the newly-created child watch source + + + + + process to watch. On POSIX the positive pid of a child process. On +Windows a handle for a process (which doesn't have to be a child). + + + + + + If @err or *@err is %NULL, does nothing. Otherwise, +calls g_error_free() on *@err and sets *@err to %NULL. + + + + + + Clears a reference to a variable. + +@pp must not be %NULL. + +If the reference is %NULL then this function does nothing. +Otherwise, the variable is destroyed using @destroy and the +pointer is set to %NULL. + +A macro is also included that allows this function to be used without +pointer casts. + + + + + + a pointer to a variable, struct member etc. holding a + pointer + + + + a function to which a gpointer can be passed, to destroy *@pp + + + + + + This wraps the close() call; in case of error, %errno will be +preserved, but the error will also be stored as a #GError in @error. + +Besides using #GError, there is another major reason to prefer this +function over the call provided by the system; on Unix, it will +attempt to correctly handle %EINTR, which has platform-specific +semantics. + + %TRUE on success, %FALSE if there was an error. + + + + + A file descriptor + + + + + + Computes the checksum for a binary @data. This is a +convenience wrapper for g_checksum_new(), g_checksum_get_string() +and g_checksum_free(). + +The hexadecimal string returned will be in lower case. + + the digest of the binary data as a string in hexadecimal. + The returned string should be freed with g_free() when done using it. + + + + + a #GChecksumType + + + + binary blob to compute the digest of + + + + + + Computes the checksum for a binary @data of @length. This is a +convenience wrapper for g_checksum_new(), g_checksum_get_string() +and g_checksum_free(). + +The hexadecimal string returned will be in lower case. + + the digest of the binary data as a string in hexadecimal. + The returned string should be freed with g_free() when done using it. + + + + + a #GChecksumType + + + + binary blob to compute the digest of + + + + + + length of @data + + + + + + Computes the checksum of a string. + +The hexadecimal string returned will be in lower case. + + the checksum as a hexadecimal string. The returned string + should be freed with g_free() when done using it. + + + + + a #GChecksumType + + + + the string to compute the checksum of + + + + the length of the string, or -1 if the string is null-terminated. + + + + + + Computes the HMAC for a binary @data. This is a +convenience wrapper for g_hmac_new(), g_hmac_get_string() +and g_hmac_unref(). + +The hexadecimal string returned will be in lower case. + + the HMAC of the binary data as a string in hexadecimal. + The returned string should be freed with g_free() when done using it. + + + + + a #GChecksumType to use for the HMAC + + + + the key to use in the HMAC + + + + binary blob to compute the HMAC of + + + + + + Computes the HMAC for a binary @data of @length. This is a +convenience wrapper for g_hmac_new(), g_hmac_get_string() +and g_hmac_unref(). + +The hexadecimal string returned will be in lower case. + + the HMAC of the binary data as a string in hexadecimal. + The returned string should be freed with g_free() when done using it. + + + + + a #GChecksumType to use for the HMAC + + + + the key to use in the HMAC + + + + + + the length of the key + + + + binary blob to compute the HMAC of + + + + + + length of @data + + + + + + Computes the HMAC for a string. + +The hexadecimal string returned will be in lower case. + + the HMAC as a hexadecimal string. + The returned string should be freed with g_free() + when done using it. + + + + + a #GChecksumType to use for the HMAC + + + + the key to use in the HMAC + + + + + + the length of the key + + + + the string to compute the HMAC for + + + + the length of the string, or -1 if the string is nul-terminated + + + + + + Converts a string from one character set to another. + +Note that you should use g_iconv() for streaming conversions. +Despite the fact that @byes_read can return information about partial +characters, the g_convert_... functions are not generally suitable +for streaming. If the underlying converter maintains internal state, +then this won't be preserved across successive calls to g_convert(), +g_convert_with_iconv() or g_convert_with_fallback(). (An example of +this is the GNU C converter for CP1255 which does not emit a base +character until it knows that the next character is not a mark that +could combine with the base character.) + +Using extensions such as "//TRANSLIT" may not work (or may not work +well) on many platforms. Consider using g_str_to_ascii() instead. + + If the conversion was successful, a newly allocated + nul-terminated string, which must be freed with + g_free(). Otherwise %NULL and @error will be set. + + + + + the string to convert + + + + the length of the string in bytes, or -1 if the string is + nul-terminated (Note that some encodings may allow nul + bytes to occur inside strings. In that case, using -1 + for the @len parameter is unsafe) + + + + name of character set into which to convert @str + + + + character set of @str. + + + + location to store the number of bytes in the + input string that were successfully converted, or %NULL. + Even if the conversion was successful, this may be + less than @len if there were partial characters + at the end of the input. If the error + #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + stored will the byte offset after the last valid + input sequence. + + + + the number of bytes stored in the output buffer (not + including the terminating nul). + + + + + + + + + + + Converts a string from one character set to another, possibly +including fallback sequences for characters not representable +in the output. Note that it is not guaranteed that the specification +for the fallback sequences in @fallback will be honored. Some +systems may do an approximate conversion from @from_codeset +to @to_codeset in their iconv() functions, +in which case GLib will simply return that approximate conversion. + +Note that you should use g_iconv() for streaming conversions. +Despite the fact that @byes_read can return information about partial +characters, the g_convert_... functions are not generally suitable +for streaming. If the underlying converter maintains internal state, +then this won't be preserved across successive calls to g_convert(), +g_convert_with_iconv() or g_convert_with_fallback(). (An example of +this is the GNU C converter for CP1255 which does not emit a base +character until it knows that the next character is not a mark that +could combine with the base character.) + + If the conversion was successful, a newly allocated + nul-terminated string, which must be freed with + g_free(). Otherwise %NULL and @error will be set. + + + + + the string to convert + + + + the length of the string in bytes, or -1 if the string is + nul-terminated (Note that some encodings may allow nul + bytes to occur inside strings. In that case, using -1 + for the @len parameter is unsafe) + + + + name of character set into which to convert @str + + + + character set of @str. + + + + UTF-8 string to use in place of character not + present in the target encoding. (The string must be + representable in the target encoding). + If %NULL, characters not in the target encoding will + be represented as Unicode escapes \uxxxx or \Uxxxxyyyy. + + + + location to store the number of bytes in the + input string that were successfully converted, or %NULL. + Even if the conversion was successful, this may be + less than @len if there were partial characters + at the end of the input. + + + + the number of bytes stored in the output buffer (not + including the terminating nul). + + + + + + Converts a string from one character set to another. + +Note that you should use g_iconv() for streaming conversions. +Despite the fact that @byes_read can return information about partial +characters, the g_convert_... functions are not generally suitable +for streaming. If the underlying converter maintains internal state, +then this won't be preserved across successive calls to g_convert(), +g_convert_with_iconv() or g_convert_with_fallback(). (An example of +this is the GNU C converter for CP1255 which does not emit a base +character until it knows that the next character is not a mark that +could combine with the base character.) + + If the conversion was successful, a newly allocated + nul-terminated string, which must be freed with + g_free(). Otherwise %NULL and @error will be set. + + + + + the string to convert + + + + the length of the string in bytes, or -1 if the string is + nul-terminated (Note that some encodings may allow nul + bytes to occur inside strings. In that case, using -1 + for the @len parameter is unsafe) + + + + conversion descriptor from g_iconv_open() + + + + location to store the number of bytes in the + input string that were successfully converted, or %NULL. + Even if the conversion was successful, this may be + less than @len if there were partial characters + at the end of the input. If the error + #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + stored will the byte offset after the last valid + input sequence. + + + + the number of bytes stored in the output buffer (not + including the terminating nul). + + + + + + Frees all the data elements of the datalist. +The data elements' destroy functions are called +if they have been set. + + + + + + a datalist. + + + + + + Calls the given function for each data element of the datalist. The +function is called with each data element's #GQuark id and data, +together with the given @user_data parameter. Note that this +function is NOT thread-safe. So unless @datalist can be protected +from any modifications during invocation of this function, it should +not be called. + + + + + + a datalist. + + + + the function to call for each data element. + + + + user data to pass to the function. + + + + + + Gets a data element, using its string identifier. This is slower than +g_datalist_id_get_data() because it compares strings. + + the data element, or %NULL if it is not found. + + + + + a datalist. + + + + the string identifying a data element. + + + + + + Gets flags values packed in together with the datalist. +See g_datalist_set_flags(). + + the flags of the datalist + + + + + pointer to the location that holds a list + + + + + + This is a variant of g_datalist_id_get_data() which +returns a 'duplicate' of the value. @dup_func defines the +meaning of 'duplicate' in this context, it could e.g. +take a reference on a ref-counted object. + +If the @key_id is not set in the datalist then @dup_func +will be called with a %NULL argument. + +Note that @dup_func is called while the datalist is locked, so it +is not allowed to read or modify the datalist. + +This function can be useful to avoid races when multiple +threads are using the same datalist and the same key. + + the result of calling @dup_func on the value + associated with @key_id in @datalist, or %NULL if not set. + If @dup_func is %NULL, the value is returned unmodified. + + + + + location of a datalist + + + + the #GQuark identifying a data element + + + + function to duplicate the old value + + + + passed as user_data to @dup_func + + + + + + Retrieves the data element corresponding to @key_id. + + the data element, or %NULL if it is not found. + + + + + a datalist. + + + + the #GQuark identifying a data element. + + + + + + Removes an element, without calling its destroy notification +function. + + the data previously stored at @key_id, or %NULL if none. + + + + + a datalist. + + + + the #GQuark identifying a data element. + + + + + + Compares the member that is associated with @key_id in +@datalist to @oldval, and if they are the same, replace +@oldval with @newval. + +This is like a typical atomic compare-and-exchange +operation, for a member of @datalist. + +If the previous value was replaced then ownership of the +old value (@oldval) is passed to the caller, including +the registred destroy notify for it (passed out in @old_destroy). +Its up to the caller to free this as he wishes, which may +or may not include using @old_destroy as sometimes replacement +should not destroy the object in the normal way. + + %TRUE if the existing value for @key_id was replaced + by @newval, %FALSE otherwise. + + + + + location of a datalist + + + + the #GQuark identifying a data element + + + + the old value to compare against + + + + the new value to replace it with + + + + destroy notify for the new value + + + + destroy notify for the existing value + + + + + + Sets the data corresponding to the given #GQuark id, and the +function to be called when the element is removed from the datalist. +Any previous data with the same key is removed, and its destroy +function is called. + + + + + + a datalist. + + + + the #GQuark to identify the data element. + + + + the data element or %NULL to remove any previous element + corresponding to @key_id. + + + + the function to call when the data element is + removed. This function will be called with the data + element and can be used to free any memory allocated + for it. If @data is %NULL, then @destroy_func must + also be %NULL. + + + + + + Resets the datalist to %NULL. It does not free any memory or call +any destroy functions. + + + + + + a pointer to a pointer to a datalist. + + + + + + Turns on flag values for a data list. This function is used +to keep a small number of boolean flags in an object with +a data list without using any additional space. It is +not generally useful except in circumstances where space +is very tight. (It is used in the base #GObject type, for +example.) + + + + + + pointer to the location that holds a list + + + + the flags to turn on. The values of the flags are + restricted by %G_DATALIST_FLAGS_MASK (currently + 3; giving two possible boolean flags). + A value for @flags that doesn't fit within the mask is + an error. + + + + + + Turns off flag values for a data list. See g_datalist_unset_flags() + + + + + + pointer to the location that holds a list + + + + the flags to turn off. The values of the flags are + restricted by %G_DATALIST_FLAGS_MASK (currently + 3: giving two possible boolean flags). + A value for @flags that doesn't fit within the mask is + an error. + + + + + + Destroys the dataset, freeing all memory allocated, and calling any +destroy functions set for data elements. + + + + + + the location identifying the dataset. + + + + + + Calls the given function for each data element which is associated +with the given location. Note that this function is NOT thread-safe. +So unless @datalist can be protected from any modifications during +invocation of this function, it should not be called. + + + + + + the location identifying the dataset. + + + + the function to call for each data element. + + + + user data to pass to the function. + + + + + + Gets the data element corresponding to a #GQuark. + + the data element corresponding to the #GQuark, or %NULL if + it is not found. + + + + + the location identifying the dataset. + + + + the #GQuark id to identify the data element. + + + + + + Removes an element, without calling its destroy notification +function. + + the data previously stored at @key_id, or %NULL if none. + + + + + the location identifying the dataset. + + + + the #GQuark ID identifying the data element. + + + + + + Sets the data element associated with the given #GQuark id, and also +the function to call when the data element is destroyed. Any +previous data with the same key is removed, and its destroy function +is called. + + + + + + the location identifying the dataset. + + + + the #GQuark id to identify the data element. + + + + the data element. + + + + the function to call when the data element is + removed. This function will be called with the data + element and can be used to free any memory allocated + for it. + + + + + + Returns the number of days in a month, taking leap +years into account. + + number of days in @month during the @year + + + + + month + + + + year + + + + + + Returns the number of weeks in the year, where weeks +are taken to start on Monday. Will be 52 or 53. The +date must be valid. (Years always have 52 7-day periods, +plus 1 or 2 extra days depending on whether it's a leap +year. This function is basically telling you how many +Mondays are in the year, i.e. there are 53 Mondays if +one of the extra days happens to be a Monday.) + + number of Mondays in the year + + + + + a year + + + + + + Returns the number of weeks in the year, where weeks +are taken to start on Sunday. Will be 52 or 53. The +date must be valid. (Years always have 52 7-day periods, +plus 1 or 2 extra days depending on whether it's a leap +year. This function is basically telling you how many +Sundays are in the year, i.e. there are 53 Sundays if +one of the extra days happens to be a Sunday.) + + the number of weeks in @year + + + + + year to count weeks in + + + + + + Returns %TRUE if the year is a leap year. + +For the purposes of this function, leap year is every year +divisible by 4 unless that year is divisible by 100. If it +is divisible by 100 it would be a leap year only if that year +is also divisible by 400. + + %TRUE if the year is a leap year + + + + + year to check + + + + + + Generates a printed representation of the date, in a +[locale][setlocale]-specific way. +Works just like the platform's C library strftime() function, +but only accepts date-related formats; time-related formats +give undefined results. Date must be valid. Unlike strftime() +(which uses the locale encoding), works on a UTF-8 format +string and stores a UTF-8 result. + +This function does not provide any conversion specifiers in +addition to those implemented by the platform's C library. +For example, don't expect that using g_date_strftime() would +make the \%F provided by the C99 strftime() work on Windows +where the C library only complies to C89. + + number of characters written to the buffer, or 0 the buffer was too small + + + + + destination buffer + + + + buffer size + + + + format string + + + + valid #GDate + + + + + + A comparison function for #GDateTimes that is suitable +as a #GCompareFunc. Both #GDateTimes must be non-%NULL. + + -1, 0 or 1 if @dt1 is less than, equal to or greater + than @dt2. + + + + + first #GDateTime to compare + + + + second #GDateTime to compare + + + + + + Checks to see if @dt1 and @dt2 are equal. + +Equal here means that they represent the same moment after converting +them to the same time zone. + + %TRUE if @dt1 and @dt2 are equal + + + + + a #GDateTime + + + + a #GDateTime + + + + + + Hashes @datetime into a #guint, suitable for use within #GHashTable. + + a #guint containing the hash + + + + + a #GDateTime + + + + + + Returns %TRUE if the day of the month is valid (a day is valid if it's +between 1 and 31 inclusive). + + %TRUE if the day is valid + + + + + day to check + + + + + + Returns %TRUE if the day-month-year triplet forms a valid, existing day +in the range of days #GDate understands (Year 1 or later, no more than +a few thousand years in the future). + + %TRUE if the date is a valid one + + + + + day + + + + month + + + + year + + + + + + Returns %TRUE if the Julian day is valid. Anything greater than zero +is basically a valid Julian, though there is a 32-bit limit. + + %TRUE if the Julian day is valid + + + + + Julian day to check + + + + + + Returns %TRUE if the month value is valid. The 12 #GDateMonth +enumeration values are the only valid months. + + %TRUE if the month is valid + + + + + month + + + + + + Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration +values are the only valid weekdays. + + %TRUE if the weekday is valid + + + + + weekday + + + + + + Returns %TRUE if the year is valid. Any year greater than 0 is valid, +though there is a 16-bit limit to what #GDate will understand. + + %TRUE if the year is valid + + + + + year + + + + + + This is a variant of g_dgettext() that allows specifying a locale +category instead of always using `LC_MESSAGES`. See g_dgettext() for +more information about how this functions differs from calling +dcgettext() directly. + + the translated string for the given locale category + + + + + the translation domain to use, or %NULL to use + the domain set with textdomain() + + + + message to translate + + + + a locale category + + + + + + This function is a wrapper of dgettext() which does not translate +the message if the default domain as set with textdomain() has no +translations for the current locale. + +The advantage of using this function over dgettext() proper is that +libraries using this function (like GTK+) will not use translations +if the application using the library does not have translations for +the current locale. This results in a consistent English-only +interface instead of one having partial translations. For this +feature to work, the call to textdomain() and setlocale() should +precede any g_dgettext() invocations. For GTK+, it means calling +textdomain() before gtk_init or its variants. + +This function disables translations if and only if upon its first +call all the following conditions hold: + +- @domain is not %NULL + +- textdomain() has been called to set a default text domain + +- there is no translations available for the default text domain + and the current locale + +- current locale is not "C" or any English locales (those + starting with "en_") + +Note that this behavior may not be desired for example if an application +has its untranslated messages in a language other than English. In those +cases the application should call textdomain() after initializing GTK+. + +Applications should normally not use this function directly, +but use the _() macro for translations. + + The translated string + + + + + the translation domain to use, or %NULL to use + the domain set with textdomain() + + + + message to translate + + + + + + Creates a subdirectory in the preferred directory for temporary +files (as returned by g_get_tmp_dir()). + +@tmpl should be a string in the GLib file name encoding containing +a sequence of six 'X' characters, as the parameter to g_mkstemp(). +However, unlike these functions, the template should only be a +basename, no directory components are allowed. If template is +%NULL, a default template is used. + +Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not +modified, and might thus be a read-only literal string. + + The actual name used. This string + should be freed with g_free() when not needed any longer and is + is in the GLib file name encoding. In case of errors, %NULL is + returned and @error will be set. + + + + + Template for directory name, + as in g_mkdtemp(), basename only, or %NULL for a default template + + + + + + Compares two #gpointer arguments and returns %TRUE if they are equal. +It can be passed to g_hash_table_new() as the @key_equal_func +parameter, when using opaque pointers compared by pointer value as +keys in a #GHashTable. + +This equality function is also appropriate for keys that are integers +stored in pointers, such as `GINT_TO_POINTER (n)`. + + %TRUE if the two keys match. + + + + + a key + + + + a key to compare with @v1 + + + + + + Converts a gpointer to a hash value. +It can be passed to g_hash_table_new() as the @hash_func parameter, +when using opaque pointers compared by pointer value as keys in a +#GHashTable. + +This hash function is also appropriate for keys that are integers +stored in pointers, such as `GINT_TO_POINTER (n)`. + + a hash value corresponding to the key. + + + + + a #gpointer key + + + + + + This function is a wrapper of dngettext() which does not translate +the message if the default domain as set with textdomain() has no +translations for the current locale. + +See g_dgettext() for details of how this differs from dngettext() +proper. + + The translated string + + + + + the translation domain to use, or %NULL to use + the domain set with textdomain() + + + + message to translate + + + + plural form of the message + + + + the quantity for which translation is needed + + + + + + Compares the two #gdouble values being pointed to and returns +%TRUE if they are equal. +It can be passed to g_hash_table_new() as the @key_equal_func +parameter, when using non-%NULL pointers to doubles as keys in a +#GHashTable. + + %TRUE if the two keys match. + + + + + a pointer to a #gdouble key + + + + a pointer to a #gdouble key to compare with @v1 + + + + + + Converts a pointer to a #gdouble to a hash value. +It can be passed to g_hash_table_new() as the @hash_func parameter, +It can be passed to g_hash_table_new() as the @hash_func parameter, +when using non-%NULL pointers to doubles as keys in a #GHashTable. + + a hash value corresponding to the key. + + + + + a pointer to a #gdouble key + + + + + + This function is a variant of g_dgettext() which supports +a disambiguating message context. GNU gettext uses the +'\004' character to separate the message context and +message id in @msgctxtid. +If 0 is passed as @msgidoffset, this function will fall back to +trying to use the deprecated convention of using "|" as a separation +character. + +This uses g_dgettext() internally. See that functions for differences +with dgettext() proper. + +Applications should normally not use this function directly, +but use the C_() macro for translations with context. + + The translated string + + + + + the translation domain to use, or %NULL to use + the domain set with textdomain() + + + + a combined message context and message id, separated + by a \004 character + + + + the offset of the message id in @msgctxid + + + + + + This function is a variant of g_dgettext() which supports +a disambiguating message context. GNU gettext uses the +'\004' character to separate the message context and +message id in @msgctxtid. + +This uses g_dgettext() internally. See that functions for differences +with dgettext() proper. + +This function differs from C_() in that it is not a macro and +thus you may use non-string-literals as context and msgid arguments. + + The translated string + + + + + the translation domain to use, or %NULL to use + the domain set with textdomain() + + + + the message context + + + + the message + + + + + + Returns the value of the environment variable @variable in the +provided list @envp. + + the value of the environment variable, or %NULL if + the environment variable is not set in @envp. The returned + string is owned by @envp, and will be freed if @variable is + set or unset again. + + + + + an environment + list (eg, as returned from g_get_environ()), or %NULL + for an empty environment list + + + + + + the environment variable to get + + + + + + Sets the environment variable @variable in the provided list +@envp to @value. + + the + updated environment list. Free it using g_strfreev(). + + + + + + + an + environment list that can be freed using g_strfreev() (e.g., as + returned from g_get_environ()), or %NULL for an empty + environment list + + + + + + the environment variable to set, must not contain '=' + + + + the value for to set the variable to + + + + whether to change the variable if it already exists + + + + + + Removes the environment variable @variable from the provided +environment @envp. + + the + updated environment list. Free it using g_strfreev(). + + + + + + + an environment + list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), + or %NULL for an empty environment list + + + + + + the environment variable to remove, must not contain '=' + + + + + + Gets a #GFileError constant based on the passed-in @err_no. +For example, if you pass in `EEXIST` this function returns +#G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably +assume that all #GFileError values will exist. + +Normally a #GFileError value goes into a #GError returned +from a function that manipulates files. So you would use +g_file_error_from_errno() when constructing a #GError. + + #GFileError corresponding to the given @errno + + + + + an "errno" value + + + + + + + + + + + Reads an entire file into allocated memory, with good error +checking. + +If the call was successful, it returns %TRUE and sets @contents to the file +contents and @length to the length of the file contents in bytes. The string +stored in @contents will be nul-terminated, so for text files you can pass +%NULL for the @length argument. If the call was not successful, it returns +%FALSE and sets @error. The error domain is #G_FILE_ERROR. Possible error +codes are those in the #GFileError enumeration. In the error case, +@contents is set to %NULL and @length is set to zero. + + %TRUE on success, %FALSE if an error occurred + + + + + name of a file to read contents from, in the GLib file name encoding + + + + location to store an allocated string, use g_free() to free + the returned string + + + + + + location to store length in bytes of the contents, or %NULL + + + + + + Opens a file for writing in the preferred directory for temporary +files (as returned by g_get_tmp_dir()). + +@tmpl should be a string in the GLib file name encoding containing +a sequence of six 'X' characters, as the parameter to g_mkstemp(). +However, unlike these functions, the template should only be a +basename, no directory components are allowed. If template is +%NULL, a default template is used. + +Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not +modified, and might thus be a read-only literal string. + +Upon success, and if @name_used is non-%NULL, the actual name used +is returned in @name_used. This string should be freed with g_free() +when not needed any longer. The returned name is in the GLib file +name encoding. + + A file handle (as from open()) to the file opened for + reading and writing. The file is opened in binary mode on platforms + where there is a difference. The file handle should be closed with + close(). In case of errors, -1 is returned and @error will be set. + + + + + Template for file name, as in + g_mkstemp(), basename only, or %NULL for a default template + + + + location to store actual name used, + or %NULL + + + + + + Reads the contents of the symbolic link @filename like the POSIX +readlink() function. The returned string is in the encoding used +for filenames. Use g_filename_to_utf8() to convert it to UTF-8. + + A newly-allocated string with the contents of + the symbolic link, or %NULL if an error occurred. + + + + + the symbolic link + + + + + + Writes all of @contents to a file named @filename, with good error checking. +If a file called @filename already exists it will be overwritten. + +This write is atomic in the sense that it is first written to a temporary +file which is then renamed to the final name. Notes: + +- On UNIX, if @filename already exists hard links to @filename will break. + Also since the file is recreated, existing permissions, access control + lists, metadata etc. may be lost. If @filename is a symbolic link, + the link itself will be replaced, not the linked file. + +- On Windows renaming a file will not remove an existing file with the + new name, so on Windows there is a race condition between the existing + file being removed and the temporary file being renamed. + +- On Windows there is no way to remove a file that is open to some + process, or mapped into memory. Thus, this function will fail if + @filename already exists and is open. + +If the call was successful, it returns %TRUE. If the call was not successful, +it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR. +Possible error codes are those in the #GFileError enumeration. + +Note that the name for the temporary file is constructed by appending up +to 7 characters to @filename. + + %TRUE on success, %FALSE if an error occurred + + + + + name of a file to write @contents to, in the GLib file name + encoding + + + + string to write to the file + + + + + + length of @contents, or -1 if @contents is a nul-terminated string + + + + + + Returns %TRUE if any of the tests in the bitfield @test are +%TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)` +will return %TRUE if the file exists; the check whether it's a +directory doesn't matter since the existence test is %TRUE. With +the current set of available tests, there's no point passing in +more than one test at a time. + +Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links, +so for a symbolic link to a regular file g_file_test() will return +%TRUE for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR. + +Note, that for a dangling symbolic link g_file_test() will return +%TRUE for %G_FILE_TEST_IS_SYMLINK and %FALSE for all other flags. + +You should never use g_file_test() to test whether it is safe +to perform an operation, because there is always the possibility +of the condition changing before you actually perform the operation. +For example, you might think you could use %G_FILE_TEST_IS_SYMLINK +to know whether it is safe to write to a file without being +tricked into writing into a different location. It doesn't work! +|[<!-- language="C" --> + // DON'T DO THIS + if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) + { + fd = g_open (filename, O_WRONLY); + // write to fd + } +]| + +Another thing to note is that %G_FILE_TEST_EXISTS and +%G_FILE_TEST_IS_EXECUTABLE are implemented using the access() +system call. This usually doesn't matter, but if your program +is setuid or setgid it means that these tests will give you +the answer for the real user ID and group ID, rather than the +effective user ID and group ID. + +On Windows, there are no symlinks, so testing for +%G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for +%G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and +its name indicates that it is executable, checking for well-known +extensions and those listed in the `PATHEXT` environment variable. + + whether a test was %TRUE + + + + + a filename to test in the + GLib file name encoding + + + + bitfield of #GFileTest flags + + + + + + Returns the display basename for the particular filename, guaranteed +to be valid UTF-8. The display name might not be identical to the filename, +for instance there might be problems converting it to UTF-8, and some files +can be translated in the display. + +If GLib cannot make sense of the encoding of @filename, as a last resort it +replaces unknown characters with U+FFFD, the Unicode replacement character. +You can search the result for the UTF-8 encoding of this character (which is +"\357\277\275" in octal notation) to find out if @filename was in an invalid +encoding. + +You must pass the whole absolute pathname to this functions so that +translation of well known locations can be done. + +This function is preferred over g_filename_display_name() if you know the +whole path, as it allows translation. + + a newly allocated string containing + a rendition of the basename of the filename in valid UTF-8 + + + + + an absolute pathname in the + GLib file name encoding + + + + + + Converts a filename into a valid UTF-8 string. The conversion is +not necessarily reversible, so you should keep the original around +and use the return value of this function only for display purposes. +Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL +even if the filename actually isn't in the GLib file name encoding. + +If GLib cannot make sense of the encoding of @filename, as a last resort it +replaces unknown characters with U+FFFD, the Unicode replacement character. +You can search the result for the UTF-8 encoding of this character (which is +"\357\277\275" in octal notation) to find out if @filename was in an invalid +encoding. + +If you know the whole pathname of the file you should use +g_filename_display_basename(), since that allows location-based +translation of filenames. + + a newly allocated string containing + a rendition of the filename in valid UTF-8 + + + + + a pathname hopefully in the + GLib file name encoding + + + + + + Converts an escaped ASCII-encoded URI to a local filename in the +encoding used for filenames. + + a newly-allocated string holding + the resulting filename, or %NULL on an error. + + + + + a uri describing a filename (escaped, encoded in ASCII). + + + + Location to store hostname for the + URI. + If there is no hostname in the URI, %NULL will be + stored in this location. + + + + + + Converts a string from UTF-8 to the encoding GLib uses for +filenames. Note that on Windows GLib uses UTF-8 for filenames; +on other platforms, this function indirectly depends on the +[current locale][setlocale]. + + + The converted string, or %NULL on an error. + + + + + + + a UTF-8 encoded string. + + + + the length of the string, or -1 if the string is + nul-terminated. + + + + location to store the number of bytes in + the input string that were successfully converted, or %NULL. + Even if the conversion was successful, this may be + less than @len if there were partial characters + at the end of the input. If the error + #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + stored will the byte offset after the last valid + input sequence. + + + + the number of bytes stored in the output buffer (not + including the terminating nul). + + + + + + Converts an absolute filename to an escaped ASCII-encoded URI, with the path +component following Section 3.3. of RFC 2396. + + a newly-allocated string holding the resulting + URI, or %NULL on an error. + + + + + an absolute filename specified in the GLib file + name encoding, which is the on-disk file name bytes on Unix, and UTF-8 + on Windows + + + + A UTF-8 encoded hostname, or %NULL for none. + + + + + + Converts a string which is in the encoding used by GLib for +filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8 +for filenames; on other platforms, this function indirectly depends on +the [current locale][setlocale]. + + The converted string, or %NULL on an error. + + + + + a string in the encoding for filenames + + + + the length of the string, or -1 if the string is + nul-terminated (Note that some encodings may allow nul + bytes to occur inside strings. In that case, using -1 + for the @len parameter is unsafe) + + + + location to store the number of bytes in the + input string that were successfully converted, or %NULL. + Even if the conversion was successful, this may be + less than @len if there were partial characters + at the end of the input. If the error + #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + stored will the byte offset after the last valid + input sequence. + + + + the number of bytes stored in the output + buffer (not including the terminating nul). + + + + + + Locates the first executable named @program in the user's path, in the +same way that execvp() would locate it. Returns an allocated string +with the absolute path name, or %NULL if the program is not found in +the path. If @program is already an absolute path, returns a copy of +@program if @program exists and is executable, and %NULL otherwise. + +On Windows, if @program does not have a file type suffix, tries +with the suffixes .exe, .cmd, .bat and .com, and the suffixes in +the `PATHEXT` environment variable. + +On Windows, it looks for the file in the same way as CreateProcess() +would. This means first in the directory where the executing +program was loaded from, then in the current directory, then in the +Windows 32-bit system directory, then in the Windows directory, and +finally in the directories in the `PATH` environment variable. If +the program is found, the return value contains the full name +including the type suffix. + + a newly-allocated string with the absolute path, + or %NULL + + + + + a program name in the GLib file name encoding + + + + + + Formats a size (for example the size of a file) into a human readable +string. Sizes are rounded to the nearest size prefix (kB, MB, GB) +and are displayed rounded to the nearest tenth. E.g. the file size +3292528 bytes will be converted into the string "3.2 MB". + +The prefix units base is 1000 (i.e. 1 kB is 1000 bytes). + +This string should be freed with g_free() when not needed any longer. + +See g_format_size_full() for more options about how the size might be +formatted. + + a newly-allocated formatted string containing a human readable + file size + + + + + a size in bytes + + + + + + Formats a size (for example the size of a file) into a human +readable string. Sizes are rounded to the nearest size prefix +(KB, MB, GB) and are displayed rounded to the nearest tenth. +E.g. the file size 3292528 bytes will be converted into the +string "3.1 MB". + +The prefix units base is 1024 (i.e. 1 KB is 1024 bytes). + +This string should be freed with g_free() when not needed any longer. + This function is broken due to its use of SI + suffixes to denote IEC units. Use g_format_size() instead. + + a newly-allocated formatted string containing a human + readable file size + + + + + a size in bytes + + + + + + Formats a size. + +This function is similar to g_format_size() but allows for flags +that modify the output. See #GFormatSizeFlags. + + a newly-allocated formatted string containing a human + readable file size + + + + + a size in bytes + + + + #GFormatSizeFlags to modify the output + + + + + + An implementation of the standard fprintf() function which supports +positional parameters, as specified in the Single Unix Specification. + + the number of bytes printed. + + + + + the stream to write to. + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + the arguments to insert in the output. + + + + + + Frees the memory pointed to by @mem. + +If @mem is %NULL it simply returns, so there is no need to check @mem +against %NULL before calling this function. + + + + + + the memory to free + + + + + + Gets a human-readable name for the application, as set by +g_set_application_name(). This name should be localized if +possible, and is intended for display to the user. Contrast with +g_get_prgname(), which gets a non-localized name. If +g_set_application_name() has not been called, returns the result of +g_get_prgname() (which may be %NULL if g_set_prgname() has also not +been called). + + human-readable application name. may return %NULL + + + + + Obtains the character set for the [current locale][setlocale]; you +might use this character set as an argument to g_convert(), to convert +from the current locale's encoding to some other encoding. (Frequently +g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.) + +On Windows the character set returned by this function is the +so-called system default ANSI code-page. That is the character set +used by the "narrow" versions of C library and Win32 functions that +handle file names. It might be different from the character set +used by the C library's current locale. + +The return value is %TRUE if the locale's encoding is UTF-8, in that +case you can perhaps avoid calling g_convert(). + +The string returned in @charset is not allocated, and should not be +freed. + + %TRUE if the returned charset is UTF-8 + + + + + return location for character set + name, or %NULL. + + + + + + Gets the character set for the current locale. + + a newly allocated string containing the name + of the character set. This string must be freed with g_free(). + + + + + Gets the current directory. + +The returned string should be freed when no longer needed. +The encoding of the returned string is system defined. +On Windows, it is always UTF-8. + +Since GLib 2.40, this function will return the value of the "PWD" +environment variable if it is set and it happens to be the same as +the current directory. This can make a difference in the case that +the current directory is the target of a symbolic link. + + the current directory + + + + + Equivalent to the UNIX gettimeofday() function, but portable. + +You may find g_get_real_time() to be more convenient. + + + + + + #GTimeVal structure in which to store current time. + + + + + + Gets the list of environment variables for the current process. + +The list is %NULL terminated and each item in the list is of the +form 'NAME=VALUE'. + +This is equivalent to direct access to the 'environ' global variable, +except portable. + +The return value is freshly allocated and it should be freed with +g_strfreev() when it is no longer needed. + + the list of + environment variables + + + + + + + Determines the preferred character sets used for filenames. +The first character set from the @charsets is the filename encoding, the +subsequent character sets are used when trying to generate a displayable +representation of a filename, see g_filename_display_name(). + +On Unix, the character sets are determined by consulting the +environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`. +On Windows, the character set used in the GLib API is always UTF-8 +and said environment variables have no effect. + +`G_FILENAME_ENCODING` may be set to a comma-separated list of +character set names. The special token "\@locale" is taken +to mean the character set for the [current locale][setlocale]. +If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is, +the character set of the current locale is taken as the filename +encoding. If neither environment variable is set, UTF-8 is taken +as the filename encoding, but the character set of the current locale +is also put in the list of encodings. + +The returned @charsets belong to GLib and must not be freed. + +Note that on Unix, regardless of the locale character set or +`G_FILENAME_ENCODING` value, the actual file names present +on a system might be in any random encoding or just gibberish. + + %TRUE if the filename encoding is UTF-8. + + + + + return location for the %NULL-terminated list of encoding names + + + + + + Gets the current user's home directory. + +As with most UNIX tools, this function will return the value of the +`HOME` environment variable if it is set to an existing absolute path +name, falling back to the `passwd` file in the case that it is unset. + +If the path given in `HOME` is non-absolute, does not exist, or is +not a directory, the result is undefined. + +Before version 2.36 this function would ignore the `HOME` environment +variable, taking the value from the `passwd` database instead. This was +changed to increase the compatibility of GLib with other programs (and +the XDG basedir specification) and to increase testability of programs +based on GLib (by making it easier to run them from test frameworks). + +If your program has a strong requirement for either the new or the +old behaviour (and if you don't wish to increase your GLib +dependency to ensure that the new behaviour is in effect) then you +should either directly check the `HOME` environment variable yourself +or unset it before calling any functions in GLib. + + the current user's home directory + + + + + Return a name for the machine. + +The returned name is not necessarily a fully-qualified domain name, +or even present in DNS or some other name service at all. It need +not even be unique on your local network or site, but usually it +is. Callers should not rely on the return value having any specific +properties like uniqueness for security purposes. Even if the name +of the machine is changed while an application is running, the +return value from this function does not change. The returned +string is owned by GLib and should not be modified or freed. If no +name can be determined, a default fixed string "localhost" is +returned. + + the host name of the machine. + + + + + Computes a list of applicable locale names, which can be used to +e.g. construct locale-dependent filenames or search paths. The returned +list is sorted from most desirable to least desirable and always contains +the default locale "C". + +For example, if LANGUAGE=de:en_US, then the returned list is +"de", "en_US", "en", "C". + +This function consults the environment variables `LANGUAGE`, `LC_ALL`, +`LC_MESSAGES` and `LANG` to find the list of locales specified by the +user. + + a %NULL-terminated array of strings owned by GLib + that must not be modified or freed. + + + + + + + Returns a list of derived variants of @locale, which can be used to +e.g. construct locale-dependent filenames or search paths. The returned +list is sorted from most desirable to least desirable. +This function handles territory, charset and extra locale modifiers. + +For example, if @locale is "fr_BE", then the returned list +is "fr_BE", "fr". + +If you need the list of variants for the current locale, +use g_get_language_names(). + + a newly + allocated array of newly allocated strings with the locale variants. Free with + g_strfreev(). + + + + + + + a locale identifier + + + + + + Queries the system monotonic time. + +The monotonic clock will always increase and doesn't suffer +discontinuities when the user (or NTP) changes the system time. It +may or may not continue to tick during times where the machine is +suspended. + +We try to use the clock that corresponds as closely as possible to +the passage of time as measured by system calls such as poll() but it +may not always be possible to do this. + + the monotonic time, in microseconds + + + + + Determine the approximate number of threads that the system will +schedule simultaneously for this process. This is intended to be +used as a parameter to g_thread_pool_new() for CPU bound tasks and +similar cases. + + Number of schedulable threads, always greater than 0 + + + + + Gets the name of the program. This name should not be localized, +in contrast to g_get_application_name(). + +If you are using GDK or GTK+ the program name is set in gdk_init(), +which is called by gtk_init(). The program name is found by taking +the last component of @argv[0]. + + the name of the program. The returned string belongs + to GLib and must not be modified or freed. + + + + + Gets the real name of the user. This usually comes from the user's +entry in the `passwd` file. The encoding of the returned string is +system-defined. (On Windows, it is, however, always UTF-8.) If the +real user name cannot be determined, the string "Unknown" is +returned. + + the user's real name. + + + + + Queries the system wall-clock time. + +This call is functionally equivalent to g_get_current_time() except +that the return value is often more convenient than dealing with a +#GTimeVal. + +You should only use this call if you are actually interested in the real +wall-clock time. g_get_monotonic_time() is probably more useful for +measuring intervals. + + the number of microseconds since January 1, 1970 UTC. + + + + + Returns an ordered list of base directories in which to access +system-wide configuration information. + +On UNIX platforms this is determined using the mechanisms described +in the +[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). +In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`. + +On Windows is the directory that contains application data for all users. +A typical path is C:\Documents and Settings\All Users\Application Data. +This folder is used for application data that is not user specific. +For example, an application can store a spell-check dictionary, a database +of clip art, or a log file in the CSIDL_COMMON_APPDATA folder. +This information will not roam and is available to anyone using the computer. + + + a %NULL-terminated array of strings owned by GLib that must not be + modified or freed. + + + + + + + Returns an ordered list of base directories in which to access +system-wide application data. + +On UNIX platforms this is determined using the mechanisms described +in the +[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec) +In this case the list of directories retrieved will be XDG_DATA_DIRS. + +On Windows the first elements in the list are the Application Data +and Documents folders for All Users. (These can be determined only +on Windows 2000 or later and are not present in the list on other +Windows versions.) See documentation for CSIDL_COMMON_APPDATA and +CSIDL_COMMON_DOCUMENTS. + +Then follows the "share" subfolder in the installation folder for +the package containing the DLL that calls this function, if it can +be determined. + +Finally the list contains the "share" subfolder in the installation +folder for GLib, and in the installation folder for the package the +application's .exe file belongs to. + +The installation folders above are determined by looking up the +folder where the module (DLL or EXE) in question is located. If the +folder's name is "bin", its parent is used, otherwise the folder +itself. + +Note that on Windows the returned list can vary depending on where +this function is called. + + + a %NULL-terminated array of strings owned by GLib that must not be + modified or freed. + + + + + + + Gets the directory to use for temporary files. + +On UNIX, this is taken from the `TMPDIR` environment variable. +If the variable is not set, `P_tmpdir` is +used, as defined by the system C library. Failing that, a +hard-coded default of "/tmp" is returned. + +On Windows, the `TEMP` environment variable is used, with the +root directory of the Windows installation (eg: "C:\") used +as a default. + +The encoding of the returned string is system-defined. On Windows, +it is always UTF-8. The return value is never %NULL or the empty +string. + + the directory to use for temporary files. + + + + + Returns a base directory in which to store non-essential, cached +data specific to particular user. + +On UNIX platforms this is determined using the mechanisms described +in the +[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). +In this case the directory retrieved will be XDG_CACHE_HOME. + +On Windows is the directory that serves as a common repository for +temporary Internet files. A typical path is +C:\Documents and Settings\username\Local Settings\Temporary Internet Files. +See documentation for CSIDL_INTERNET_CACHE. + + a string owned by GLib that must not be modified + or freed. + + + + + Returns a base directory in which to store user-specific application +configuration information such as user preferences and settings. + +On UNIX platforms this is determined using the mechanisms described +in the +[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). +In this case the directory retrieved will be `XDG_CONFIG_HOME`. + +On Windows this is the folder to use for local (as opposed to +roaming) application data. See documentation for +CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as +what g_get_user_data_dir() returns. + + a string owned by GLib that must not be modified + or freed. + + + + + Returns a base directory in which to access application data such +as icons that is customized for a particular user. + +On UNIX platforms this is determined using the mechanisms described +in the +[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). +In this case the directory retrieved will be `XDG_DATA_HOME`. + +On Windows this is the folder to use for local (as opposed to +roaming) application data. See documentation for +CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as +what g_get_user_config_dir() returns. + + a string owned by GLib that must not be modified + or freed. + + + + + Gets the user name of the current user. The encoding of the returned +string is system-defined. On UNIX, it might be the preferred file name +encoding, or something else, and there is no guarantee that it is even +consistent on a machine. On Windows, it is always UTF-8. + + the user name of the current user. + + + + + Returns a directory that is unique to the current user on the local +system. + +On UNIX platforms this is determined using the mechanisms described +in the +[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). +This is the directory +specified in the `XDG_RUNTIME_DIR` environment variable. +In the case that this variable is not set, we return the value of +g_get_user_cache_dir(), after verifying that it exists. + +On Windows this is the folder to use for local (as opposed to +roaming) application data. See documentation for +CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as +what g_get_user_config_dir() returns. + + a string owned by GLib that must not be + modified or freed. + + + + + Returns the full path of a special directory using its logical id. + +On UNIX this is done using the XDG special user directories. +For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP +falls back to `$HOME/Desktop` when XDG special user directories have +not been set up. + +Depending on the platform, the user might be able to change the path +of the special directory without requiring the session to restart; GLib +will not reflect any change once the special directories are loaded. + + the path to the specified special directory, or + %NULL if the logical id was not found. The returned string is owned by + GLib and should not be modified or freed. + + + + + the logical id of special directory + + + + + + Returns the value of an environment variable. + +On UNIX, the name and value are byte strings which might or might not +be in some consistent character set and encoding. On Windows, they are +in UTF-8. +On Windows, in case the environment variable's value contains +references to other environment variables, they are expanded. + + the value of the environment variable, or %NULL if + the environment variable is not found. The returned string + may be overwritten by the next call to g_getenv(), g_setenv() + or g_unsetenv(). + + + + + the environment variable to get + + + + + + This is a convenience function for using a #GHashTable as a set. It +is equivalent to calling g_hash_table_replace() with @key as both the +key and the value. + +When a hash table only ever contains keys that have themselves as the +corresponding value it is able to be stored more efficiently. See +the discussion in the section description. + + %TRUE if the key did not exist yet + + + + + a #GHashTable + + + + + + + a key to insert + + + + + + Checks if @key is in @hash_table. + + %TRUE if @key is in @hash_table, %FALSE otherwise. + + + + + a #GHashTable + + + + + + + a key to check + + + + + + Destroys all keys and values in the #GHashTable and decrements its +reference count by 1. If keys and/or values are dynamically allocated, +you should either free them first or create the #GHashTable with destroy +notifiers using g_hash_table_new_full(). In the latter case the destroy +functions you supplied will be called on all keys and values during the +destruction phase. + + + + + + a #GHashTable + + + + + + + + + Inserts a new key and value into a #GHashTable. + +If the key already exists in the #GHashTable its current +value is replaced with the new value. If you supplied a +@value_destroy_func when creating the #GHashTable, the old +value is freed using that function. If you supplied a +@key_destroy_func when creating the #GHashTable, the passed +key is freed using that function. + + %TRUE if the key did not exist yet + + + + + a #GHashTable + + + + + + + a key to insert + + + + the value to associate with the key + + + + + + Looks up a key in a #GHashTable. Note that this function cannot +distinguish between a key that is not present and one which is present +and has the value %NULL. If you need this distinction, use +g_hash_table_lookup_extended(). + + the associated value, or %NULL if the key is not found + + + + + a #GHashTable + + + + + + + the key to look up + + + + + + Looks up a key in the #GHashTable, returning the original key and the +associated value and a #gboolean which is %TRUE if the key was found. This +is useful if you need to free the memory allocated for the original key, +for example before calling g_hash_table_remove(). + +You can actually pass %NULL for @lookup_key to test +whether the %NULL key exists, provided the hash and equal functions +of @hash_table are %NULL-safe. + + %TRUE if the key was found in the #GHashTable + + + + + a #GHashTable + + + + + + + the key to look up + + + + return location for the original key + + + + return location for the value associated +with the key + + + + + + Removes a key and its associated value from a #GHashTable. + +If the #GHashTable was created using g_hash_table_new_full(), the +key and value are freed using the supplied destroy functions, otherwise +you have to make sure that any dynamically allocated values are freed +yourself. + + %TRUE if the key was found and removed from the #GHashTable + + + + + a #GHashTable + + + + + + + the key to remove + + + + + + Removes all keys and their associated values from a #GHashTable. + +If the #GHashTable was created using g_hash_table_new_full(), +the keys and values are freed using the supplied destroy functions, +otherwise you have to make sure that any dynamically allocated +values are freed yourself. + + + + + + a #GHashTable + + + + + + + + + Inserts a new key and value into a #GHashTable similar to +g_hash_table_insert(). The difference is that if the key +already exists in the #GHashTable, it gets replaced by the +new key. If you supplied a @value_destroy_func when creating +the #GHashTable, the old value is freed using that function. +If you supplied a @key_destroy_func when creating the +#GHashTable, the old key is freed using that function. + + %TRUE if the key did not exist yet + + + + + a #GHashTable + + + + + + + a key to insert + + + + the value to associate with the key + + + + + + Returns the number of elements contained in the #GHashTable. + + the number of key/value pairs in the #GHashTable. + + + + + a #GHashTable + + + + + + + + + Removes a key and its associated value from a #GHashTable without +calling the key and value destroy functions. + + %TRUE if the key was found and removed from the #GHashTable + + + + + a #GHashTable + + + + + + + the key to remove + + + + + + Removes all keys and their associated values from a #GHashTable +without calling the key and value destroy functions. + + + + + + a #GHashTable + + + + + + + + + Atomically decrements the reference count of @hash_table by one. +If the reference count drops to 0, all keys and values will be +destroyed, and all memory allocated by the hash table is released. +This function is MT-safe and may be called from any thread. + + + + + + a valid #GHashTable + + + + + + + + + Destroys a #GHook, given its ID. + + %TRUE if the #GHook was found in the #GHookList and destroyed + + + + + a #GHookList + + + + a hook ID + + + + + + Removes one #GHook from a #GHookList, marking it +inactive and calling g_hook_unref() on it. + + + + + + a #GHookList + + + + the #GHook to remove + + + + + + Calls the #GHookList @finalize_hook function if it exists, +and frees the memory allocated for the #GHook. + + + + + + a #GHookList + + + + the #GHook to free + + + + + + Inserts a #GHook into a #GHookList, before a given #GHook. + + + + + + a #GHookList + + + + the #GHook to insert the new #GHook before + + + + the #GHook to insert + + + + + + Prepends a #GHook on the start of a #GHookList. + + + + + + a #GHookList + + + + the #GHook to add to the start of @hook_list + + + + + + Decrements the reference count of a #GHook. +If the reference count falls to 0, the #GHook is removed +from the #GHookList and g_hook_free() is called to free it. + + + + + + a #GHookList + + + + the #GHook to unref + + + + + + Tests if @hostname contains segments with an ASCII-compatible +encoding of an Internationalized Domain Name. If this returns +%TRUE, you should decode the hostname with g_hostname_to_unicode() +before displaying it to the user. + +Note that a hostname might contain a mix of encoded and unencoded +segments, and so it is possible for g_hostname_is_non_ascii() and +g_hostname_is_ascii_encoded() to both return %TRUE for a name. + + %TRUE if @hostname contains any ASCII-encoded +segments. + + + + + a hostname + + + + + + Tests if @hostname is the string form of an IPv4 or IPv6 address. +(Eg, "192.168.0.1".) + + %TRUE if @hostname is an IP address + + + + + a hostname (or IP address in string form) + + + + + + Tests if @hostname contains Unicode characters. If this returns +%TRUE, you need to encode the hostname with g_hostname_to_ascii() +before using it in non-IDN-aware contexts. + +Note that a hostname might contain a mix of encoded and unencoded +segments, and so it is possible for g_hostname_is_non_ascii() and +g_hostname_is_ascii_encoded() to both return %TRUE for a name. + + %TRUE if @hostname contains any non-ASCII characters + + + + + a hostname + + + + + + Converts @hostname to its canonical ASCII form; an ASCII-only +string containing no uppercase letters and not ending with a +trailing dot. + + an ASCII hostname, which must be freed, or %NULL if +@hostname is in some way invalid. + + + + + a valid UTF-8 or ASCII hostname + + + + + + Converts @hostname to its canonical presentation form; a UTF-8 +string in Unicode normalization form C, containing no uppercase +letters, no forbidden characters, and no ASCII-encoded segments, +and not ending with a trailing dot. + +Of course if @hostname is not an internationalized hostname, then +the canonical presentation form will be entirely ASCII. + + a UTF-8 hostname, which must be freed, or %NULL if +@hostname is in some way invalid. + + + + + a valid UTF-8 or ASCII hostname + + + + + + Same as the standard UNIX routine iconv(), but +may be implemented via libiconv on UNIX flavors that lack +a native implementation. + +GLib provides g_convert() and g_locale_to_utf8() which are likely +more convenient than the raw iconv wrappers. + + count of non-reversible conversions, or -1 on error + + + + + conversion descriptor from g_iconv_open() + + + + bytes to convert + + + + inout parameter, bytes remaining to convert in @inbuf + + + + converted output bytes + + + + inout parameter, bytes available to fill in @outbuf + + + + + + Adds a function to be called whenever there are no higher priority +events pending to the default main loop. The function is given the +default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function +returns %FALSE it is automatically removed from the list of event +sources and will not be called again. + +See [memory management of sources][mainloop-memory-management] for details +on how to handle the return value and memory management of @data. + +This internally creates a main loop source using g_idle_source_new() +and attaches it to the global #GMainContext using g_source_attach(), so +the callback will be invoked in whichever thread is running that main +context. You can do these steps manually if you need greater control or to +use a custom main context. + + the ID (greater than 0) of the event source. + + + + + function to call + + + + data to pass to @function. + + + + + + Adds a function to be called whenever there are no higher priority +events pending. If the function returns %FALSE it is automatically +removed from the list of event sources and will not be called again. + +See [memory management of sources][mainloop-memory-management] for details +on how to handle the return value and memory management of @data. + +This internally creates a main loop source using g_idle_source_new() +and attaches it to the global #GMainContext using g_source_attach(), so +the callback will be invoked in whichever thread is running that main +context. You can do these steps manually if you need greater control or to +use a custom main context. + + the ID (greater than 0) of the event source. + + + + + the priority of the idle source. Typically this will be in the + range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + + + + function to call + + + + data to pass to @function + + + + function to call when the idle is removed, or %NULL + + + + + + Removes the idle function with the given data. + + %TRUE if an idle source was found and removed. + + + + + the data for the idle source's callback. + + + + + + Creates a new idle source. + +The source will not initially be associated with any #GMainContext +and must be added to one with g_source_attach() before it will be +executed. Note that the default priority for idle sources is +%G_PRIORITY_DEFAULT_IDLE, as compared to other sources which +have a default priority of %G_PRIORITY_DEFAULT. + + the newly-created idle source + + + + + Compares the two #gint64 values being pointed to and returns +%TRUE if they are equal. +It can be passed to g_hash_table_new() as the @key_equal_func +parameter, when using non-%NULL pointers to 64-bit integers as keys in a +#GHashTable. + + %TRUE if the two keys match. + + + + + a pointer to a #gint64 key + + + + a pointer to a #gint64 key to compare with @v1 + + + + + + Converts a pointer to a #gint64 to a hash value. + +It can be passed to g_hash_table_new() as the @hash_func parameter, +when using non-%NULL pointers to 64-bit integer values as keys in a +#GHashTable. + + a hash value corresponding to the key. + + + + + a pointer to a #gint64 key + + + + + + Compares the two #gint values being pointed to and returns +%TRUE if they are equal. +It can be passed to g_hash_table_new() as the @key_equal_func +parameter, when using non-%NULL pointers to integers as keys in a +#GHashTable. + +Note that this function acts on pointers to #gint, not on #gint +directly: if your hash table's keys are of the form +`GINT_TO_POINTER (n)`, use g_direct_equal() instead. + + %TRUE if the two keys match. + + + + + a pointer to a #gint key + + + + a pointer to a #gint key to compare with @v1 + + + + + + Converts a pointer to a #gint to a hash value. +It can be passed to g_hash_table_new() as the @hash_func parameter, +when using non-%NULL pointers to integer values as keys in a #GHashTable. + +Note that this function acts on pointers to #gint, not on #gint +directly: if your hash table's keys are of the form +`GINT_TO_POINTER (n)`, use g_direct_hash() instead. + + a hash value corresponding to the key. + + + + + a pointer to a #gint key + + + + + + Returns a canonical representation for @string. Interned strings +can be compared for equality by comparing the pointers, instead of +using strcmp(). g_intern_static_string() does not copy the string, +therefore @string must not be freed or modified. + + a canonical representation for the string + + + + + a static string + + + + + + Returns a canonical representation for @string. Interned strings +can be compared for equality by comparing the pointers, instead of +using strcmp(). + + a canonical representation for the string + + + + + a string + + + + + + Adds the #GIOChannel into the default main loop context +with the default priority. + + the event source id + + + + + a #GIOChannel + + + + the condition to watch for + + + + the function to call when the condition is satisfied + + + + user data to pass to @func + + + + + + Adds the #GIOChannel into the default main loop context +with the given priority. + +This internally creates a main loop source using g_io_create_watch() +and attaches it to the main loop context with g_source_attach(). +You can do these steps manually if you need greater control. + + the event source id + + + + + a #GIOChannel + + + + the priority of the #GIOChannel source + + + + the condition to watch for + + + + the function to call when the condition is satisfied + + + + user data to pass to @func + + + + the function to call when the source is removed + + + + + + Converts an `errno` error number to a #GIOChannelError. + + a #GIOChannelError error number, e.g. + %G_IO_CHANNEL_ERROR_INVAL. + + + + + an `errno` error number, e.g. `EINVAL` + + + + + + + + + + + Creates a #GSource that's dispatched when @condition is met for the +given @channel. For example, if condition is #G_IO_IN, the source will +be dispatched when there's data available for reading. + +g_io_add_watch() is a simpler interface to this same functionality, for +the case where you want to add the source to the default main loop context +at the default priority. + +On Windows, polling a #GSource created to watch a channel for a socket +puts the socket in non-blocking mode. This is a side-effect of the +implementation and unavoidable. + + a new #GSource + + + + + a #GIOChannel to watch + + + + conditions to watch for + + + + + + + + + + + Gets the names of all variables set in the environment. + +Programs that want to be portable to Windows should typically use +this function and g_getenv() instead of using the environ array +from the C library directly. On Windows, the strings in the environ +array are in system codepage encoding, while in most of the typical +use cases for environment variables in GLib-using programs you want +the UTF-8 encoding that this function and g_getenv() provide. + + a %NULL-terminated + list of strings which must be freed with g_strfreev(). + + + + + + + Converts a string from UTF-8 to the encoding used for strings by +the C runtime (usually the same as that used by the operating +system) in the [current locale][setlocale]. On Windows this means +the system codepage. + + A newly-allocated buffer containing the converted string, + or %NULL on an error, and error will be set. + + + + + a UTF-8 encoded string + + + + the length of the string, or -1 if the string is + nul-terminated (Note that some encodings may allow nul + bytes to occur inside strings. In that case, using -1 + for the @len parameter is unsafe) + + + + location to store the number of bytes in the + input string that were successfully converted, or %NULL. + Even if the conversion was successful, this may be + less than @len if there were partial characters + at the end of the input. If the error + #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + stored will the byte offset after the last valid + input sequence. + + + + the number of bytes stored in the output + buffer (not including the terminating nul). + + + + + + Converts a string which is in the encoding used for strings by +the C runtime (usually the same as that used by the operating +system) in the [current locale][setlocale] into a UTF-8 string. + + A newly-allocated buffer containing the converted string, + or %NULL on an error, and error will be set. + + + + + a string in the encoding of the current locale. On Windows + this means the system codepage. + + + + the length of the string, or -1 if the string is + nul-terminated (Note that some encodings may allow nul + bytes to occur inside strings. In that case, using -1 + for the @len parameter is unsafe) + + + + location to store the number of bytes in the + input string that were successfully converted, or %NULL. + Even if the conversion was successful, this may be + less than @len if there were partial characters + at the end of the input. If the error + #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + stored will the byte offset after the last valid + input sequence. + + + + the number of bytes stored in the output + buffer (not including the terminating nul). + + + + + + Logs an error or debugging message. + +If the log level has been set as fatal, the abort() +function is called to terminate the program. + +If g_log_default_handler() is used as the log handler function, a new-line +character will automatically be appended to @..., and need not be entered +manually. + +If [structured logging is enabled][using-structured-logging] this will +output via the structured log writer function (see g_log_set_writer_func()). + + + + + + the log domain, usually #G_LOG_DOMAIN, or %NULL +for the default + + + + the log level, either from #GLogLevelFlags + or a user-defined level + + + + the message format. See the printf() documentation + + + + the parameters to insert into the format string + + + + + + The default log handler set up by GLib; g_log_set_default_handler() +allows to install an alternate default log handler. +This is used if no log handler has been set for the particular log +domain and log level combination. It outputs the message to stderr +or stdout and if the log level is fatal it calls abort(). It automatically +prints a new-line character after the message, so one does not need to be +manually included in @message. + +The behavior of this log handler can be influenced by a number of +environment variables: + +- `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which + messages should be prefixed by the program name and PID of the + aplication. + +- `G_MESSAGES_DEBUG`: A space-separated list of log domains for + which debug and informational messages are printed. By default + these messages are not printed. + +stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, +%G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for +the rest. + +This has no effect if structured logging is enabled; see +[Using Structured Logging][using-structured-logging]. + + + + + + the log domain of the message, or %NULL for the +default "" application domain + + + + the level of the message + + + + the message + + + + data passed from g_log() which is unused + + + + + + Removes the log handler. + +This has no effect if structured logging is enabled; see +[Using Structured Logging][using-structured-logging]. + + + + + + the log domain + + + + the id of the handler, which was returned + in g_log_set_handler() + + + + + + Sets the message levels which are always fatal, in any log domain. +When a message with any of these levels is logged the program terminates. +You can only set the levels defined by GLib to be fatal. +%G_LOG_LEVEL_ERROR is always fatal. + +You can also make some message levels fatal at runtime by setting +the `G_DEBUG` environment variable (see +[Running GLib Applications](glib-running.html)). + +Libraries should not call this function, as it affects all messages logged +by a process, including those from other libraries. + +Structured log messages (using g_log_structured() and +g_log_structured_array()) are fatal only if the default log writer is used; +otherwise it is up to the writer function to determine which log messages +are fatal. See [Using Structured Logging][using-structured-logging]. + + the old fatal mask + + + + + the mask containing bits set for each level + of error which is to be fatal + + + + + + Installs a default log handler which is used if no +log handler has been set for the particular log domain +and log level combination. By default, GLib uses +g_log_default_handler() as default log handler. + +This has no effect if structured logging is enabled; see +[Using Structured Logging][using-structured-logging]. + + the previous default log handler + + + + + the log handler function + + + + data passed to the log handler + + + + + + Sets the log levels which are fatal in the given domain. +%G_LOG_LEVEL_ERROR is always fatal. + +This has no effect on structured log messages (using g_log_structured() or +g_log_structured_array()). To change the fatal behaviour for specific log +messages, programs must install a custom log writer function using +g_log_set_writer_func(). See +[Using Structured Logging][using-structured-logging]. + + the old fatal mask for the log domain + + + + + the log domain + + + + the new fatal mask + + + + + + Sets the log handler for a domain and a set of log levels. +To handle fatal and recursive messages the @log_levels parameter +must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION +bit flags. + +Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if +you want to set a handler for this log level you must combine it with +#G_LOG_FLAG_FATAL. + +This has no effect if structured logging is enabled; see +[Using Structured Logging][using-structured-logging]. + +Here is an example for adding a log handler for all warning messages +in the default domain: +|[<!-- language="C" --> +g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL + | G_LOG_FLAG_RECURSION, my_log_handler, NULL); +]| + +This example adds a log handler for all critical messages from GTK+: +|[<!-- language="C" --> +g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL + | G_LOG_FLAG_RECURSION, my_log_handler, NULL); +]| + +This example adds a log handler for all messages from GLib: +|[<!-- language="C" --> +g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL + | G_LOG_FLAG_RECURSION, my_log_handler, NULL); +]| + + the id of the new handler + + + + + the log domain, or %NULL for the default "" + application domain + + + + the log levels to apply the log handler for. + To handle fatal and recursive messages as well, combine + the log levels with the #G_LOG_FLAG_FATAL and + #G_LOG_FLAG_RECURSION bit flags. + + + + the log handler function + + + + data passed to the log handler + + + + + + Like g_log_sets_handler(), but takes a destroy notify for the @user_data. + +This has no effect if structured logging is enabled; see +[Using Structured Logging][using-structured-logging]. + + the id of the new handler + + + + + the log domain, or %NULL for the default "" + application domain + + + + the log levels to apply the log handler for. + To handle fatal and recursive messages as well, combine + the log levels with the #G_LOG_FLAG_FATAL and + #G_LOG_FLAG_RECURSION bit flags. + + + + the log handler function + + + + data passed to the log handler + + + + destroy notify for @user_data, or %NULL + + + + + + Set a writer function which will be called to format and write out each log +message. Each program should set a writer function, or the default writer +(g_log_writer_default()) will be used. + +Libraries **must not** call this function — only programs are allowed to +install a writer function, as there must be a single, central point where +log messages are formatted and outputted. + +There can only be one writer function. It is an error to set more than one. + + + + + + log writer function, which must not be %NULL + + + + user data to pass to @func + + + + function to free @user_data once it’s + finished with, if non-%NULL + + + + + + Log a message with structured data. The message will be passed through to +the log writer set by the application using g_log_set_writer_func(). If the +message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will +be aborted at the end of this function. + +The structured data is provided as key–value pairs, where keys are UTF-8 +strings, and values are arbitrary pointers — typically pointing to UTF-8 +strings, but that is not a requirement. To pass binary (non-nul-terminated) +structured data, use g_log_structured_array(). The keys for structured data +should follow the [systemd journal +fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html) +specification. It is suggested that custom keys are namespaced according to +the code which sets them. For example, custom keys from GLib all have a +`GLIB_` prefix. + +The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will +be converted into a +[`PRIORITY`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#PRIORITY=) +field. The format string will have its placeholders substituted for the provided +values and be converted into a +[`MESSAGE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE=) +field. + +Other fields you may commonly want to pass into this function: + + * [`MESSAGE_ID`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=) + * [`CODE_FILE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=) + * [`CODE_LINE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_LINE=) + * [`CODE_FUNC`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FUNC=) + * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=) + +Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by +the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), +g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including +glib.h. + +For example: +|[<!-- language="C" --> +g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, + "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", + "MY_APPLICATION_CUSTOM_FIELD", "some debug string", + "MESSAGE", "This is a debug message about pointer %p and integer %u.", + some_pointer, some_integer); +]| + +Note that each `MESSAGE_ID` must be [uniquely and randomly +generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=). +If adding a `MESSAGE_ID`, consider shipping a [message +catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with +your software. + +To pass a user data pointer to the log writer function which is specific to +this logging call, you must use g_log_structured_array() and pass the pointer +as a field with #GLogField.length set to zero, otherwise it will be +interpreted as a string. + +For example: +|[<!-- language="C" --> +const GLogField fields[] = { + { "MESSAGE", "This is a debug message.", -1 }, + { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 }, + { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 }, + { "MY_APPLICATION_STATE", state_object, 0 }, +}; +g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields)); +]| + +Note also that, even if no other structured fields are specified, there +must always be a "MESSAGE" key before the format string. The "MESSAGE"-format +pair has to be the last of the key-value pairs, and "MESSAGE" is the only +field for which printf()-style formatting is supported. + +The default writer function for `stdout` and `stderr` will automatically +append a new-line character after the message, so you should not add one +manually to the format string. + + + + + + log domain, usually %G_LOG_DOMAIN + + + + log level, either from #GLogLevelFlags, or a user-defined + level + + + + key-value pairs of structured data to add to the log entry, followed + by the key "MESSAGE", followed by a printf()-style message format, + followed by parameters to insert in the format string + + + + + + Log a message with structured data. The message will be passed through to the +log writer set by the application using g_log_set_writer_func(). If the +message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will +be aborted at the end of this function. + +See g_log_structured() for more documentation. + +This assumes that @log_level is already present in @fields (typically as the +`PRIORITY` field). + + + + + + log level, either from #GLogLevelFlags, or a user-defined + level + + + + key–value pairs of structured data to add + to the log message + + + + + + number of elements in the @fields array + + + + + + Log a message with structured data, accepting the data within a #GVariant. This +version is especially useful for use in other languages, via introspection. + +The only mandatory item in the @fields dictionary is the "MESSAGE" which must +contain the text shown to the user. + +The values in the @fields dictionary are likely to be of type String +(#G_VARIANT_TYPE_STRING). Array of bytes (#G_VARIANT_TYPE_BYTESTRING) is also +supported. In this case the message is handled as binary and will be forwarded +to the log writer as such. The size of the array should not be higher than +%G_MAXSSIZE. Otherwise it will be truncated to this size. For other types +g_variant_print() will be used to convert the value into a string. + +For more details on its usage and about the parameters, see g_log_structured(). + + + + + + log domain, usually %G_LOG_DOMAIN + + + + log level, either from #GLogLevelFlags, or a user-defined + level + + + + a dictionary (#GVariant of the type %G_VARIANT_TYPE_VARDICT) +containing the key-value pairs of message data. + + + + + + Format a structured log message and output it to the default log destination +for the platform. On Linux, this is typically the systemd journal, falling +back to `stdout` or `stderr` if running from the terminal or if output is +being redirected to a file. + +Support for other platform-specific logging mechanisms may be added in +future. Distributors of GLib may modify this function to impose their own +(documented) platform-specific log writing policies. + +This is suitable for use as a #GLogWriterFunc, and is the default writer used +if no other is set using g_log_set_writer_func(). + +As with g_log_default_handler(), this function drops debug and informational +messages unless their log domain (or `all`) is listed in the space-separated +`G_MESSAGES_DEBUG` environment variable. + + %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + + + + + log level, either from #GLogLevelFlags, or a user-defined + level + + + + key–value pairs of structured data forming + the log message + + + + + + number of elements in the @fields array + + + + user data passed to g_log_set_writer_func() + + + + + + Format a structured log message as a string suitable for outputting to the +terminal (or elsewhere). This will include the values of all fields it knows +how to interpret, which includes `MESSAGE` and `GLIB_DOMAIN` (see the +documentation for g_log_structured()). It does not include values from +unknown fields. + +The returned string does **not** have a trailing new-line character. It is +encoded in the character set of the current locale, which is not necessarily +UTF-8. + + string containing the formatted log message, in + the character set of the current locale + + + + + log level, either from #GLogLevelFlags, or a user-defined + level + + + + key–value pairs of structured data forming + the log message + + + + + + number of elements in the @fields array + + + + %TRUE to use ANSI color escape sequences when formatting the + message, %FALSE to not + + + + + + Check whether the given @output_fd file descriptor is a connection to the +systemd journal, or something else (like a log file or `stdout` or +`stderr`). + + %TRUE if @output_fd points to the journal, %FALSE otherwise + + + + + output file descriptor to check + + + + + + Format a structured log message and send it to the systemd journal as a set +of key–value pairs. All fields are sent to the journal, but if a field has +length zero (indicating program-specific data) then only its key will be +sent. + +This is suitable for use as a #GLogWriterFunc. + +If GLib has been compiled without systemd support, this function is still +defined, but will always return %G_LOG_WRITER_UNHANDLED. + + %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + + + + + log level, either from #GLogLevelFlags, or a user-defined + level + + + + key–value pairs of structured data forming + the log message + + + + + + number of elements in the @fields array + + + + user data passed to g_log_set_writer_func() + + + + + + Format a structured log message and print it to either `stdout` or `stderr`, +depending on its log level. %G_LOG_LEVEL_INFO and %G_LOG_LEVEL_DEBUG messages +are sent to `stdout`; all other log levels are sent to `stderr`. Only fields +which are understood by this function are included in the formatted string +which is printed. + +If the output stream supports ANSI color escape sequences, they will be used +in the output. + +A trailing new-line character is added to the log message when it is printed. + +This is suitable for use as a #GLogWriterFunc. + + %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + + + + + log level, either from #GLogLevelFlags, or a user-defined + level + + + + key–value pairs of structured data forming + the log message + + + + + + number of elements in the @fields array + + + + user data passed to g_log_set_writer_func() + + + + + + Check whether the given @output_fd file descriptor supports ANSI color +escape sequences. If so, they can safely be used when formatting log +messages. + + %TRUE if ANSI color escapes are supported, %FALSE otherwise + + + + + output file descriptor to check + + + + + + Logs an error or debugging message. + +If the log level has been set as fatal, the abort() +function is called to terminate the program. + +If g_log_default_handler() is used as the log handler function, a new-line +character will automatically be appended to @..., and need not be entered +manually. + +If [structured logging is enabled][using-structured-logging] this will +output via the structured log writer function (see g_log_set_writer_func()). + + + + + + the log domain, or %NULL for the default "" +application domain + + + + the log level + + + + the message format. See the printf() documentation + + + + the parameters to insert into the format string + + + + + + Returns the global default main context. This is the main context +used for main loop functions when a main loop is not explicitly +specified, and corresponds to the "main" main loop. See also +g_main_context_get_thread_default(). + + the global default main context. + + + + + Gets the thread-default #GMainContext for this thread. Asynchronous +operations that want to be able to be run in contexts other than +the default one should call this method or +g_main_context_ref_thread_default() to get a #GMainContext to add +their #GSources to. (Note that even in single-threaded +programs applications may sometimes want to temporarily push a +non-default context, so it is not safe to assume that this will +always return %NULL if you are running in the default thread.) + +If you need to hold a reference on the context, use +g_main_context_ref_thread_default() instead. + + the thread-default #GMainContext, or +%NULL if the thread-default context is the global default context. + + + + + Gets the thread-default #GMainContext for this thread, as with +g_main_context_get_thread_default(), but also adds a reference to +it with g_main_context_ref(). In addition, unlike +g_main_context_get_thread_default(), if the thread-default context +is the global default context, this will return that #GMainContext +(with a ref added to it) rather than returning %NULL. + + the thread-default #GMainContext. Unref + with g_main_context_unref() when you are done with it. + + + + + Returns the currently firing source for this thread. + + The currently firing source or %NULL. + + + + + Returns the depth of the stack of calls to +g_main_context_dispatch() on any #GMainContext in the current thread. + That is, when called from the toplevel, it gives 0. When +called from within a callback from g_main_context_iteration() +(or g_main_loop_run(), etc.) it returns 1. When called from within +a callback to a recursive call to g_main_context_iteration(), +it returns 2. And so forth. + +This function is useful in a situation like the following: +Imagine an extremely simple "garbage collected" system. + +|[<!-- language="C" --> +static GList *free_list; + +gpointer +allocate_memory (gsize size) +{ + gpointer result = g_malloc (size); + free_list = g_list_prepend (free_list, result); + return result; +} + +void +free_allocated_memory (void) +{ + GList *l; + for (l = free_list; l; l = l->next); + g_free (l->data); + g_list_free (free_list); + free_list = NULL; + } + +[...] + +while (TRUE); + { + g_main_context_iteration (NULL, TRUE); + free_allocated_memory(); + } +]| + +This works from an application, however, if you want to do the same +thing from a library, it gets more difficult, since you no longer +control the main loop. You might think you can simply use an idle +function to make the call to free_allocated_memory(), but that +doesn't work, since the idle function could be called from a +recursive callback. This can be fixed by using g_main_depth() + +|[<!-- language="C" --> +gpointer +allocate_memory (gsize size) +{ + FreeListBlock *block = g_new (FreeListBlock, 1); + block->mem = g_malloc (size); + block->depth = g_main_depth (); + free_list = g_list_prepend (free_list, block); + return block->mem; +} + +void +free_allocated_memory (void) +{ + GList *l; + + int depth = g_main_depth (); + for (l = free_list; l; ); + { + GList *next = l->next; + FreeListBlock *block = l->data; + if (block->depth > depth) + { + g_free (block->mem); + g_free (block); + free_list = g_list_delete_link (free_list, l); + } + + l = next; + } + } +]| + +There is a temptation to use g_main_depth() to solve +problems with reentrancy. For instance, while waiting for data +to be received from the network in response to a menu item, +the menu item might be selected again. It might seem that +one could make the menu item's callback return immediately +and do nothing if g_main_depth() returns a value greater than 1. +However, this should be avoided since the user then sees selecting +the menu item do nothing. Furthermore, you'll find yourself adding +these checks all over your code, since there are doubtless many, +many things that the user could do. Instead, you can use the +following techniques: + +1. Use gtk_widget_set_sensitive() or modal dialogs to prevent + the user from interacting with elements while the main + loop is recursing. + +2. Avoid main loop recursion in situations where you can't handle + arbitrary callbacks. Instead, structure your code so that you + simply return to the main loop and then get called again when + there is more work to do. + + The main loop recursion level in the current thread + + + + + Allocates @n_bytes bytes of memory. +If @n_bytes is 0 it returns %NULL. + + a pointer to the allocated memory + + + + + the number of bytes to allocate + + + + + + Allocates @n_bytes bytes of memory, initialized to 0's. +If @n_bytes is 0 it returns %NULL. + + a pointer to the allocated memory + + + + + the number of bytes to allocate + + + + + + This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, +but care is taken to detect possible overflow during multiplication. + + a pointer to the allocated memory + + + + + the number of blocks to allocate + + + + the size of each block in bytes + + + + + + This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, +but care is taken to detect possible overflow during multiplication. + + a pointer to the allocated memory + + + + + the number of blocks to allocate + + + + the size of each block in bytes + + + + + + Collects the attributes of the element from the data passed to the +#GMarkupParser start_element function, dealing with common error +conditions and supporting boolean values. + +This utility function is not required to write a parser but can save +a lot of typing. + +The @element_name, @attribute_names, @attribute_values and @error +parameters passed to the start_element callback should be passed +unmodified to this function. + +Following these arguments is a list of "supported" attributes to collect. +It is an error to specify multiple attributes with the same name. If any +attribute not in the list appears in the @attribute_names array then an +unknown attribute error will result. + +The #GMarkupCollectType field allows specifying the type of collection +to perform and if a given attribute must appear or is optional. + +The attribute name is simply the name of the attribute to collect. + +The pointer should be of the appropriate type (see the descriptions +under #GMarkupCollectType) and may be %NULL in case a particular +attribute is to be allowed but ignored. + +This function deals with issuing errors for missing attributes +(of type %G_MARKUP_ERROR_MISSING_ATTRIBUTE), unknown attributes +(of type %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE) and duplicate +attributes (of type %G_MARKUP_ERROR_INVALID_CONTENT) as well +as parse errors for boolean-valued attributes (again of type +%G_MARKUP_ERROR_INVALID_CONTENT). In all of these cases %FALSE +will be returned and @error will be set as appropriate. + + %TRUE if successful + + + + + the current tag name + + + + the attribute names + + + + the attribute values + + + + a pointer to a #GError or %NULL + + + + the #GMarkupCollectType of the first attribute + + + + the name of the first attribute + + + + a pointer to the storage location of the first attribute + (or %NULL), followed by more types names and pointers, ending + with %G_MARKUP_COLLECT_INVALID + + + + + + + + + + + Escapes text so that the markup parser will parse it verbatim. +Less than, greater than, ampersand, etc. are replaced with the +corresponding entities. This function would typically be used +when writing out a file to be parsed with the markup parser. + +Note that this function doesn't protect whitespace and line endings +from being processed according to the XML rules for normalization +of line endings and attribute values. + +Note also that this function will produce character references in +the range of &#x1; ... &#x1f; for all control sequences +except for tabstop, newline and carriage return. The character +references in this range are not valid XML 1.0, but they are +valid XML 1.1 and will be accepted by the GMarkup parser. + + a newly allocated string with the escaped text + + + + + some valid UTF-8 text + + + + length of @text in bytes, or -1 if the text is nul-terminated + + + + + + Formats arguments according to @format, escaping +all string and character arguments in the fashion +of g_markup_escape_text(). This is useful when you +want to insert literal strings into XML-style markup +output, without having to worry that the strings +might themselves contain markup. + +|[<!-- language="C" --> +const char *store = "Fortnum & Mason"; +const char *item = "Tea"; +char *output; + +output = g_markup_printf_escaped ("<purchase>" + "<store>%s</store>" + "<item>%s</item>" + "</purchase>", + store, item); +]| + + newly allocated result from formatting + operation. Free with g_free(). + + + + + printf() style format string + + + + the arguments to insert in the format string + + + + + + Formats the data in @args according to @format, escaping +all string and character arguments in the fashion +of g_markup_escape_text(). See g_markup_printf_escaped(). + + newly allocated result from formatting + operation. Free with g_free(). + + + + + printf() style format string + + + + variable argument list, similar to vprintf() + + + + + + Checks whether the allocator used by g_malloc() is the system's +malloc implementation. If it returns %TRUE memory allocated with +malloc() can be used interchangeable with memory allocated using g_malloc(). +This function is useful for avoiding an extra copy of allocated memory returned +by a non-GLib-based API. + GLib always uses the system malloc, so this function always +returns %TRUE. + + if %TRUE, malloc() and g_malloc() can be mixed. + + + + + GLib used to support some tools for memory profiling, but this +no longer works. There are many other useful tools for memory +profiling these days which can be used instead. + Use other memory profiling tools instead + + + + + + This function used to let you override the memory allocation function. +However, its use was incompatible with the use of global constructors +in GLib and GIO, because those use the GLib allocators before main is +reached. Therefore this function is now deprecated and is just a stub. + Use other memory profiling tools instead + + + + + + table of memory allocation routines. + + + + + + Allocates @byte_size bytes of memory, and copies @byte_size bytes into it +from @mem. If @mem is %NULL it returns %NULL. + + a pointer to the newly-allocated copy of the memory, or %NULL if @mem + is %NULL. + + + + + the memory to copy. + + + + the number of bytes to copy. + + + + + + Create a directory if it doesn't already exist. Create intermediate +parent directories as needed, too. + + 0 if the directory already exists, or was successfully +created. Returns -1 if an error occurred, with errno set. + + + + + a pathname in the GLib file name encoding + + + + permissions to use for newly created directories + + + + + + Creates a temporary directory. See the mkdtemp() documentation +on most UNIX-like systems. + +The parameter is a string that should follow the rules for +mkdtemp() templates, i.e. contain the string "XXXXXX". +g_mkdtemp() is slightly more flexible than mkdtemp() in that the +sequence does not have to occur at the very end of the template +and you can pass a @mode and additional @flags. The X string will +be modified to form the name of a directory that didn't exist. +The string should be in the GLib file name encoding. Most importantly, +on Windows it should be in UTF-8. + + A pointer to @tmpl, which has been + modified to hold the directory name. In case of errors, %NULL is + returned and %errno will be set. + + + + + template directory name + + + + + + Creates a temporary directory. See the mkdtemp() documentation +on most UNIX-like systems. + +The parameter is a string that should follow the rules for +mkdtemp() templates, i.e. contain the string "XXXXXX". +g_mkdtemp() is slightly more flexible than mkdtemp() in that the +sequence does not have to occur at the very end of the template +and you can pass a @mode. The X string will be modified to form +the name of a directory that didn't exist. The string should be +in the GLib file name encoding. Most importantly, on Windows it +should be in UTF-8. + + A pointer to @tmpl, which has been + modified to hold the directory name. In case of errors, %NULL is + returned, and %errno will be set. + + + + + template directory name + + + + permissions to create the temporary directory with + + + + + + Opens a temporary file. See the mkstemp() documentation +on most UNIX-like systems. + +The parameter is a string that should follow the rules for +mkstemp() templates, i.e. contain the string "XXXXXX". +g_mkstemp() is slightly more flexible than mkstemp() in that the +sequence does not have to occur at the very end of the template. +The X string will be modified to form the name of a file that +didn't exist. The string should be in the GLib file name encoding. +Most importantly, on Windows it should be in UTF-8. + + A file handle (as from open()) to the file + opened for reading and writing. The file is opened in binary + mode on platforms where there is a difference. The file handle + should be closed with close(). In case of errors, -1 is + returned and %errno will be set. + + + + + template filename + + + + + + Opens a temporary file. See the mkstemp() documentation +on most UNIX-like systems. + +The parameter is a string that should follow the rules for +mkstemp() templates, i.e. contain the string "XXXXXX". +g_mkstemp_full() is slightly more flexible than mkstemp() +in that the sequence does not have to occur at the very end of the +template and you can pass a @mode and additional @flags. The X +string will be modified to form the name of a file that didn't exist. +The string should be in the GLib file name encoding. Most importantly, +on Windows it should be in UTF-8. + + A file handle (as from open()) to the file + opened for reading and writing. The file handle should be + closed with close(). In case of errors, -1 is returned + and %errno will be set. + + + + + template filename + + + + flags to pass to an open() call in addition to O_EXCL + and O_CREAT, which are passed automatically + + + + permissions to create the temporary file with + + + + + + Set the pointer at the specified location to %NULL. + + + + + + the memory address of the pointer. + + + + + + Prompts the user with +`[E]xit, [H]alt, show [S]tack trace or [P]roceed`. +This function is intended to be used for debugging use only. +The following example shows how it can be used together with +the g_log() functions. + +|[<!-- language="C" --> +#include <glib.h> + +static void +log_handler (const gchar *log_domain, + GLogLevelFlags log_level, + const gchar *message, + gpointer user_data) +{ + g_log_default_handler (log_domain, log_level, message, user_data); + + g_on_error_query (MY_PROGRAM_NAME); +} + +int +main (int argc, char *argv[]) +{ + g_log_set_handler (MY_LOG_DOMAIN, + G_LOG_LEVEL_WARNING | + G_LOG_LEVEL_ERROR | + G_LOG_LEVEL_CRITICAL, + log_handler, + NULL); + ... +]| + +If "[E]xit" is selected, the application terminates with a call +to _exit(0). + +If "[S]tack" trace is selected, g_on_error_stack_trace() is called. +This invokes gdb, which attaches to the current process and shows +a stack trace. The prompt is then shown again. + +If "[P]roceed" is selected, the function returns. + +This function may cause different actions on non-UNIX platforms. + + + + + + the program name, needed by gdb for the "[S]tack trace" + option. If @prg_name is %NULL, g_get_prgname() is called to get + the program name (which will work correctly if gdk_init() or + gtk_init() has been called) + + + + + + Invokes gdb, which attaches to the current process and shows a +stack trace. Called by g_on_error_query() when the "[S]tack trace" +option is selected. You can get the current process's program name +with g_get_prgname(), assuming that you have called gtk_init() or +gdk_init(). + +This function may cause different actions on non-UNIX platforms. + + + + + + the program name, needed by gdb for the "[S]tack trace" + option + + + + + + Function to be called when starting a critical initialization +section. The argument @location must point to a static +0-initialized variable that will be set to a value other than 0 at +the end of the initialization section. In combination with +g_once_init_leave() and the unique address @value_location, it can +be ensured that an initialization section will be executed only once +during a program's life time, and that concurrent threads are +blocked until initialization completed. To be used in constructs +like this: + +|[<!-- language="C" --> + static gsize initialization_value = 0; + + if (g_once_init_enter (&initialization_value)) + { + gsize setup_value = 42; // initialization code here + + g_once_init_leave (&initialization_value, setup_value); + } + + // use initialization_value here +]| + + %TRUE if the initialization section should be entered, + %FALSE and blocks otherwise + + + + + location of a static initializable variable + containing 0 + + + + + + Counterpart to g_once_init_enter(). Expects a location of a static +0-initialized initialization variable, and an initialization value +other than 0. Sets the variable to the initialization value, and +releases concurrent threads blocking in g_once_init_enter() on this +initialization variable. + + + + + + location of a static initializable variable + containing 0 + + + + new non-0 value for *@value_location + + + + + + + + + + + Parses a string containing debugging options +into a %guint containing bit flags. This is used +within GDK and GTK+ to parse the debug options passed on the +command line or through environment variables. + +If @string is equal to "all", all flags are set. Any flags +specified along with "all" in @string are inverted; thus, +"all,foo,bar" or "foo,bar,all" sets all flags except those +corresponding to "foo" and "bar". + +If @string is equal to "help", all the available keys in @keys +are printed out to standard error. + + the combined set of bit flags. + + + + + a list of debug options separated by colons, spaces, or +commas, or %NULL. + + + + pointer to an array of #GDebugKey which associate + strings with bit flags. + + + + + + the number of #GDebugKeys in the array. + + + + + + Gets the last component of the filename. + +If @file_name ends with a directory separator it gets the component +before the last slash. If @file_name consists only of directory +separators (and on Windows, possibly a drive letter), a single +separator is returned. If @file_name is empty, it gets ".". + + a newly allocated string containing the last + component of the filename + + + + + the name of the file + + + + + + Gets the directory components of a file name. + +If the file name has no directory components "." is returned. +The returned string should be freed when no longer needed. + + the directory components of the file + + + + + the name of the file + + + + + + Returns %TRUE if the given @file_name is an absolute file name. +Note that this is a somewhat vague concept on Windows. + +On POSIX systems, an absolute file name is well-defined. It always +starts from the single root directory. For example "/usr/local". + +On Windows, the concepts of current drive and drive-specific +current directory introduce vagueness. This function interprets as +an absolute file name one that either begins with a directory +separator such as "\Users\tml" or begins with the root on a drive, +for example "C:\Windows". The first case also includes UNC paths +such as "\\myserver\docs\foo". In all cases, either slashes or +backslashes are accepted. + +Note that a file name relative to the current drive root does not +truly specify a file uniquely over time and across processes, as +the current drive is a per-process value and can be changed. + +File names relative the current directory on some specific drive, +such as "D:foo/bar", are not interpreted as absolute by this +function, but they obviously are not relative to the normal current +directory as returned by getcwd() or g_get_current_dir() +either. Such paths should be avoided, or need to be handled using +Windows-specific code. + + %TRUE if @file_name is absolute + + + + + a file name + + + + + + Returns a pointer into @file_name after the root component, +i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name +is not an absolute path it returns %NULL. + + a pointer into @file_name after the + root component + + + + + a file name + + + + + + Matches a string against a compiled pattern. Passing the correct +length of the string given is mandatory. The reversed string can be +omitted by passing %NULL, this is more efficient if the reversed +version of the string to be matched is not at hand, as +g_pattern_match() will only construct it if the compiled pattern +requires reverse matches. + +Note that, if the user code will (possibly) match a string against a +multitude of patterns containing wildcards, chances are high that +some patterns will require a reversed string. In this case, it's +more efficient to provide the reversed string to avoid multiple +constructions thereof in the various calls to g_pattern_match(). + +Note also that the reverse of a UTF-8 encoded string can in general +not be obtained by g_strreverse(). This works only if the string +does not contain any multibyte characters. GLib offers the +g_utf8_strreverse() function to reverse UTF-8 encoded strings. + + %TRUE if @string matches @pspec + + + + + a #GPatternSpec + + + + the length of @string (in bytes, i.e. strlen(), + not g_utf8_strlen()) + + + + the UTF-8 encoded string to match + + + + the reverse of @string or %NULL + + + + + + Matches a string against a pattern given as a string. If this +function is to be called in a loop, it's more efficient to compile +the pattern once with g_pattern_spec_new() and call +g_pattern_match_string() repeatedly. + + %TRUE if @string matches @pspec + + + + + the UTF-8 encoded pattern + + + + the UTF-8 encoded string to match + + + + + + Matches a string against a compiled pattern. If the string is to be +matched against more than one pattern, consider using +g_pattern_match() instead while supplying the reversed string. + + %TRUE if @string matches @pspec + + + + + a #GPatternSpec + + + + the UTF-8 encoded string to match + + + + + + This is equivalent to g_bit_lock, but working on pointers (or other +pointer-sized values). + +For portability reasons, you may only lock on the bottom 32 bits of +the pointer. + + + + + + a pointer to a #gpointer-sized value + + + + a bit value between 0 and 31 + + + + + + This is equivalent to g_bit_trylock, but working on pointers (or +other pointer-sized values). + +For portability reasons, you may only lock on the bottom 32 bits of +the pointer. + + %TRUE if the lock was acquired + + + + + a pointer to a #gpointer-sized value + + + + a bit value between 0 and 31 + + + + + + This is equivalent to g_bit_unlock, but working on pointers (or other +pointer-sized values). + +For portability reasons, you may only lock on the bottom 32 bits of +the pointer. + + + + + + a pointer to a #gpointer-sized value + + + + a bit value between 0 and 31 + + + + + + Polls @fds, as with the poll() system call, but portably. (On +systems that don't have poll(), it is emulated using select().) +This is used internally by #GMainContext, but it can be called +directly if you need to block until a file descriptor is ready, but +don't want to run the full main loop. + +Each element of @fds is a #GPollFD describing a single file +descriptor to poll. The %fd field indicates the file descriptor, +and the %events field indicates the events to poll for. On return, +the %revents fields will be filled with the events that actually +occurred. + +On POSIX systems, the file descriptors in @fds can be any sort of +file descriptor, but the situation is much more complicated on +Windows. If you need to use g_poll() in code that has to run on +Windows, the easiest solution is to construct all of your +#GPollFDs with g_io_channel_win32_make_pollfd(). + + the number of entries in @fds whose %revents fields +were filled in, or 0 if the operation timed out, or -1 on error or +if the call was interrupted. + + + + + file descriptors to poll + + + + the number of file descriptors in @fds + + + + amount of time to wait, in milliseconds, or -1 to wait forever + + + + + + Formats a string according to @format and prefix it to an existing +error message. If @err is %NULL (ie: no error variable) then do +nothing. + +If *@err is %NULL (ie: an error variable is present but there is no +error condition) then also do nothing. Whether or not it makes sense +to take advantage of this feature is up to you. + + + + + + a return location for a #GError + + + + printf()-style format string + + + + arguments to @format + + + + + + Outputs a formatted message via the print handler. +The default print handler simply outputs the message to stdout, without +appending a trailing new-line character. Typically, @format should end with +its own new-line character. + +g_print() should not be used from within libraries for debugging +messages, since it may be redirected by applications to special +purpose message windows or even files. Instead, libraries should +use g_log(), g_log_structured(), or the convenience macros g_message(), +g_warning() and g_error(). + + + + + + the message format. See the printf() documentation + + + + the parameters to insert into the format string + + + + + + Outputs a formatted message via the error message handler. +The default handler simply outputs the message to stderr, without appending +a trailing new-line character. Typically, @format should end with its own +new-line character. + +g_printerr() should not be used from within libraries. +Instead g_log() or g_log_structured() should be used, or the convenience +macros g_message(), g_warning() and g_error(). + + + + + + the message format. See the printf() documentation + + + + the parameters to insert into the format string + + + + + + An implementation of the standard printf() function which supports +positional parameters, as specified in the Single Unix Specification. + +As with the standard printf(), this does not automatically append a trailing +new-line character to the message, so typically @format should end with its +own new-line character. + + the number of bytes printed. + + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + the arguments to insert in the output. + + + + + + Calculates the maximum space needed to store the output +of the sprintf() function. + + the maximum space needed to store the formatted string + + + + + the format string. See the printf() documentation + + + + the parameters to be inserted into the format string + + + + + + If @dest is %NULL, free @src; otherwise, moves @src into *@dest. +The error variable @dest points to must be %NULL. + +@src must be non-%NULL. + +Note that @src is no longer valid after this call. If you want +to keep using the same GError*, you need to set it to %NULL +after calling this function on it. + + + + + + error return location + + + + error to move into the return location + + + + + + If @dest is %NULL, free @src; otherwise, moves @src into *@dest. +*@dest must be %NULL. After the move, add a prefix as with +g_prefix_error(). + + + + + + error return location + + + + error to move into the return location + + + + printf()-style format string + + + + arguments to @format + + + + + + This is just like the standard C qsort() function, but +the comparison routine accepts a user data argument. + +This is guaranteed to be a stable sort since version 2.32. + + + + + + start of array to sort + + + + elements in the array + + + + size of each element + + + + function to compare elements + + + + data to pass to @compare_func + + + + + + Gets the #GQuark identifying the given (static) string. If the +string does not currently have an associated #GQuark, a new #GQuark +is created, linked to the given string. + +Note that this function is identical to g_quark_from_string() except +that if a new #GQuark is created the string itself is used rather +than a copy. This saves memory, but can only be used if the string +will continue to exist until the program terminates. It can be used +with statically allocated strings in the main program, but not with +statically allocated memory in dynamically loaded modules, if you +expect to ever unload the module again (e.g. do not use this +function in GTK+ theme engines). + + the #GQuark identifying the string, or 0 if @string is %NULL + + + + + a string + + + + + + Gets the #GQuark identifying the given string. If the string does +not currently have an associated #GQuark, a new #GQuark is created, +using a copy of the string. + + the #GQuark identifying the string, or 0 if @string is %NULL + + + + + a string + + + + + + Gets the string associated with the given #GQuark. + + the string associated with the #GQuark + + + + + a #GQuark. + + + + + + Gets the #GQuark associated with the given string, or 0 if string is +%NULL or it has no associated #GQuark. + +If you want the GQuark to be created if it doesn't already exist, +use g_quark_from_string() or g_quark_from_static_string(). + + the #GQuark associated with the string, or 0 if @string is + %NULL or there is no #GQuark associated with it + + + + + a string + + + + + + Returns a random #gdouble equally distributed over the range [0..1). + + a random number + + + + + Returns a random #gdouble equally distributed over the range +[@begin..@end). + + a random number + + + + + lower closed bound of the interval + + + + upper open bound of the interval + + + + + + Return a random #guint32 equally distributed over the range +[0..2^32-1]. + + a random number + + + + + Returns a random #gint32 equally distributed over the range +[@begin..@end-1]. + + a random number + + + + + lower closed bound of the interval + + + + upper open bound of the interval + + + + + + Sets the seed for the global random number generator, which is used +by the g_random_* functions, to @seed. + + + + + + a value to reinitialize the global random number generator + + + + + + Reallocates the memory pointed to by @mem, so that it now has space for +@n_bytes bytes of memory. It returns the new address of the memory, which may +have been moved. @mem may be %NULL, in which case it's considered to +have zero-length. @n_bytes may be 0, in which case %NULL will be returned +and @mem will be freed unless it is %NULL. + + the new address of the allocated memory + + + + + the memory to reallocate + + + + new size of the memory in bytes + + + + + + This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, +but care is taken to detect possible overflow during multiplication. + + the new address of the allocated memory + + + + + the memory to reallocate + + + + the number of blocks to allocate + + + + the size of each block in bytes + + + + + + Checks whether @replacement is a valid replacement string +(see g_regex_replace()), i.e. that all escape sequences in +it are valid. + +If @has_references is not %NULL then @replacement is checked +for pattern references. For instance, replacement text 'foo\n' +does not contain references and may be evaluated without information +about actual match, but '\0\1' (whole match followed by first +subpattern) requires valid #GMatchInfo object. + + whether @replacement is a valid replacement string + + + + + the replacement string + + + + location to store information about + references in @replacement or %NULL + + + + + + + + + + + Escapes the nul characters in @string to "\x00". It can be used +to compile a regex with embedded nul characters. + +For completeness, @length can be -1 for a nul-terminated string. +In this case the output string will be of course equal to @string. + + a newly-allocated escaped string + + + + + the string to escape + + + + the length of @string + + + + + + Escapes the special characters used for regular expressions +in @string, for instance "a.b*c" becomes "a\.b\*c". This +function is useful to dynamically generate regular expressions. + +@string can contain nul characters that are replaced with "\0", +in this case remember to specify the correct length of @string +in @length. + + a newly-allocated escaped string + + + + + the string to escape + + + + + + the length of @string, or -1 if @string is nul-terminated + + + + + + Scans for a match in @string for @pattern. + +This function is equivalent to g_regex_match() but it does not +require to compile the pattern with g_regex_new(), avoiding some +lines of code when you need just to do a match without extracting +substrings, capture counts, and so on. + +If this function is to be called on the same @pattern more than +once, it's more efficient to compile the pattern once with +g_regex_new() and then use g_regex_match(). + + %TRUE if the string matched, %FALSE otherwise + + + + + the regular expression + + + + the string to scan for matches + + + + compile options for the regular expression, or 0 + + + + match options, or 0 + + + + + + Breaks the string on the pattern, and returns an array of +the tokens. If the pattern contains capturing parentheses, +then the text for each of the substrings will also be returned. +If the pattern does not match anywhere in the string, then the +whole string is returned as the first token. + +This function is equivalent to g_regex_split() but it does +not require to compile the pattern with g_regex_new(), avoiding +some lines of code when you need just to do a split without +extracting substrings, capture counts, and so on. + +If this function is to be called on the same @pattern more than +once, it's more efficient to compile the pattern once with +g_regex_new() and then use g_regex_split(). + +As a special case, the result of splitting the empty string "" +is an empty vector, not a vector containing a single string. +The reason for this special case is that being able to represent +a empty vector is typically more useful than consistent handling +of empty elements. If you do need to represent empty elements, +you'll need to check for the empty string before calling this +function. + +A pattern that can match empty strings splits @string into +separate characters wherever it matches the empty string between +characters. For example splitting "ab c" using as a separator +"\s*", you will get "a", "b" and "c". + + a %NULL-terminated array of strings. Free +it using g_strfreev() + + + + + + + the regular expression + + + + the string to scan for matches + + + + compile options for the regular expression, or 0 + + + + match options, or 0 + + + + + + Resets the cache used for g_get_user_special_dir(), so +that the latest on-disk version is used. Call this only +if you just changed the data on disk yourself. + +Due to threadsafety issues this may cause leaking of strings +that were previously returned from g_get_user_special_dir() +that can't be freed. We ensure to only leak the data for +the directories that actually changed value though. + + + + + + + + + + + + + + + + + + + + + + A wrapper for the POSIX rmdir() function. The rmdir() function +deletes a directory from the filesystem. + +See your C library manual for more details about how rmdir() works +on your system. + + 0 if the directory was successfully removed, -1 if an error + occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + + + Returns the data that @iter points to. + + the data that @iter points to + + + + + a #GSequenceIter + + + + + + Moves the item pointed to by @src to the position indicated by @dest. +After calling this function @dest will point to the position immediately +after @src. It is allowed for @src and @dest to point into different +sequences. + + + + + + a #GSequenceIter pointing to the item to move + + + + a #GSequenceIter pointing to the position to which + the item is moved + + + + + + Inserts the (@begin, @end) range at the destination pointed to by ptr. +The @begin and @end iters must point into the same sequence. It is +allowed for @dest to point to a different sequence than the one pointed +into by @begin and @end. + +If @dest is NULL, the range indicated by @begin and @end is +removed from the sequence. If @dest iter points to a place within +the (@begin, @end) range, the range does not move. + + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + + + Removes the item pointed to by @iter. It is an error to pass the +end iterator to this function. + +If the sequence has a data destroy function associated with it, this +function is called on the data for the removed item. + + + + + + a #GSequenceIter + + + + + + Removes all items in the (@begin, @end) range. + +If the sequence has a data destroy function associated with it, this +function is called on the data for the removed items. + + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + + + Changes the data for the item pointed to by @iter to be @data. If +the sequence has a data destroy function associated with it, that +function is called on the existing data that @iter pointed to. + + + + + + a #GSequenceIter + + + + new data for the item + + + + + + Swaps the items pointed to by @a and @b. It is allowed for @a and @b +to point into difference sequences. + + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + + + Sets a human-readable name for the application. This name should be +localized if possible, and is intended for display to the user. +Contrast with g_set_prgname(), which sets a non-localized name. +g_set_prgname() will be called automatically by gtk_init(), +but g_set_application_name() will not. + +Note that for thread safety reasons, this function can only +be called once. + +The application name will be used in contexts such as error messages, +or when displaying an application's name in the task list. + + + + + + localized name of the application + + + + + + Does nothing if @err is %NULL; if @err is non-%NULL, then *@err +must be %NULL. A new #GError is created and assigned to *@err. + + + + + + a return location for a #GError + + + + error domain + + + + error code + + + + printf()-style format + + + + args for @format + + + + + + Does nothing if @err is %NULL; if @err is non-%NULL, then *@err +must be %NULL. A new #GError is created and assigned to *@err. +Unlike g_set_error(), @message is not a printf()-style format string. +Use this function if @message contains text you don't have control over, +that could include printf() escape sequences. + + + + + + a return location for a #GError + + + + error domain + + + + error code + + + + error message + + + + + + Sets the name of the program. This name should not be localized, +in contrast to g_set_application_name(). + +Note that for thread-safety reasons this function can only be called once. + + + + + + the name of the program. + + + + + + Sets the print handler. + +Any messages passed to g_print() will be output via +the new handler. The default handler simply outputs +the message to stdout. By providing your own handler +you can redirect the output, to a GTK+ widget or a +log file for example. + + the old print handler + + + + + the new print handler + + + + + + Sets the handler for printing error messages. + +Any messages passed to g_printerr() will be output via +the new handler. The default handler simply outputs the +message to stderr. By providing your own handler you can +redirect the output, to a GTK+ widget or a log file for +example. + + the old error message handler + + + + + the new error message handler + + + + + + Sets an environment variable. On UNIX, both the variable's name and +value can be arbitrary byte strings, except that the variable's name +cannot contain '='. On Windows, they should be in UTF-8. + +Note that on some systems, when variables are overwritten, the memory +used for the previous variables and its value isn't reclaimed. + +You should be mindful of the fact that environment variable handling +in UNIX is not thread-safe, and your program may crash if one thread +calls g_setenv() while another thread is calling getenv(). (And note +that many functions, such as gettext(), call getenv() internally.) +This function is only safe to use at the very start of your program, +before creating any other threads (or creating objects that create +worker threads of their own). + +If you need to set up the environment for a child process, you can +use g_get_environ() to get an environment array, modify that with +g_environ_setenv() and g_environ_unsetenv(), and then pass that +array directly to execvpe(), g_spawn_async(), or the like. + + %FALSE if the environment variable couldn't be set. + + + + + the environment variable to set, must not contain '='. + + + + the value for to set the variable to. + + + + whether to change the variable if it already exists. + + + + + + + + + + + Parses a command line into an argument vector, in much the same way +the shell would, but without many of the expansions the shell would +perform (variable expansion, globs, operators, filename expansion, +etc. are not supported). The results are defined to be the same as +those you would get from a UNIX98 /bin/sh, as long as the input +contains none of the unsupported shell expansions. If the input +does contain such expansions, they are passed through +literally. Possible errors are those from the #G_SHELL_ERROR +domain. Free the returned vector with g_strfreev(). + + %TRUE on success, %FALSE if error set + + + + + command line to parse + + + + return location for number of args + + + + return + location for array of args + + + + + + + + Quotes a string so that the shell (/bin/sh) will interpret the +quoted string to mean @unquoted_string. If you pass a filename to +the shell, for example, you should first quote it with this +function. The return value must be freed with g_free(). The +quoting style used is undefined (single or double quotes may be +used). + + quoted string + + + + + a literal string + + + + + + Unquotes a string as the shell (/bin/sh) would. Only handles +quotes; if a string contains file globs, arithmetic operators, +variables, backticks, redirections, or other special-to-the-shell +features, the result will be different from the result a real shell +would produce (the variables, backticks, etc. will be passed +through literally instead of being expanded). This function is +guaranteed to succeed if applied to the result of +g_shell_quote(). If it fails, it returns %NULL and sets the +error. The @quoted_string need not actually contain quoted or +escaped text; g_shell_unquote() simply goes through the string and +unquotes/unescapes anything that the shell would. Both single and +double quotes are handled, as are escapes including escaped +newlines. The return value must be freed with g_free(). Possible +errors are in the #G_SHELL_ERROR domain. + +Shell quoting rules are a bit strange. Single quotes preserve the +literal string exactly. escape sequences are not allowed; not even +\' - if you want a ' in the quoted text, you have to do something +like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to +be escaped with backslash. Otherwise double quotes preserve things +literally. + + an unquoted string + + + + + shell-quoted string + + + + + + Allocates a block of memory from the slice allocator. +The block adress handed out can be expected to be aligned +to at least 1 * sizeof (void*), +though in general slices are 2 * sizeof (void*) bytes aligned, +if a malloc() fallback implementation is used instead, +the alignment may be reduced in a libc dependent fashion. +Note that the underlying slice allocation mechanism can +be changed with the [`G_SLICE=always-malloc`][G_SLICE] +environment variable. + + a pointer to the allocated memory block, which will be %NULL if and + only if @mem_size is 0 + + + + + the number of bytes to allocate + + + + + + Allocates a block of memory via g_slice_alloc() and initializes +the returned memory to 0. Note that the underlying slice allocation +mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] +environment variable. + + a pointer to the allocated block, which will be %NULL if and only + if @mem_size is 0 + + + + + the number of bytes to allocate + + + + + + Allocates a block of memory from the slice allocator +and copies @block_size bytes into it from @mem_block. + +@mem_block must be non-%NULL if @block_size is non-zero. + + a pointer to the allocated memory block, which will be %NULL if and + only if @mem_size is 0 + + + + + the number of bytes to allocate + + + + the memory to copy + + + + + + Frees a block of memory. + +The memory must have been allocated via g_slice_alloc() or +g_slice_alloc0() and the @block_size has to match the size +specified upon allocation. Note that the exact release behaviour +can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment +variable, also see [`G_SLICE`][G_SLICE] for related debugging options. + +If @mem_block is %NULL, this function does nothing. + + + + + + the size of the block + + + + a pointer to the block to free + + + + + + Frees a linked list of memory blocks of structure type @type. + +The memory blocks must be equal-sized, allocated via +g_slice_alloc() or g_slice_alloc0() and linked together by a +@next pointer (similar to #GSList). The offset of the @next +field in each block is passed as third argument. +Note that the exact release behaviour can be changed with the +[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see +[`G_SLICE`][G_SLICE] for related debugging options. + +If @mem_chain is %NULL, this function does nothing. + + + + + + the size of the blocks + + + + a pointer to the first block of the chain + + + + the offset of the @next field in the blocks + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A safer form of the standard sprintf() function. The output is guaranteed +to not exceed @n characters (including the terminating nul character), so +it is easy to ensure that a buffer overflow cannot occur. + +See also g_strdup_printf(). + +In versions of GLib prior to 1.2.3, this function may return -1 if the +output was truncated, and the truncated string may not be nul-terminated. +In versions prior to 1.3.12, this function returns the length of the output +string. + +The return value of g_snprintf() conforms to the snprintf() +function as standardized in ISO C99. Note that this is different from +traditional snprintf(), which returns the length of the output string. + +The format string may contain positional parameters, as specified in +the Single Unix Specification. + + the number of bytes which would be produced if the buffer + was large enough. + + + + + the buffer to hold the output. + + + + the maximum number of bytes to produce (including the + terminating nul character). + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + the arguments to insert in the output. + + + + + + Removes the source with the given id from the default main context. + +The id of a #GSource is given by g_source_get_id(), or will be +returned by the functions g_source_attach(), g_idle_add(), +g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), +g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and +g_io_add_watch_full(). + +See also g_source_destroy(). You must use g_source_destroy() for sources +added to a non-default main context. + +It is a programmer error to attempt to remove a non-existent source. + +More specifically: source IDs can be reissued after a source has been +destroyed and therefore it is never valid to use this function with a +source ID which may have already been removed. An example is when +scheduling an idle to run in another thread with g_idle_add(): the +idle may already have run and been removed by the time this function +is called on its (now invalid) source ID. This source ID may have +been reissued, leading to the operation being performed against the +wrong source. + + For historical reasons, this function always returns %TRUE + + + + + the ID of the source to remove. + + + + + + Removes a source from the default main loop context given the +source functions and user data. If multiple sources exist with the +same source functions and user data, only one will be destroyed. + + %TRUE if a source was found and removed. + + + + + The @source_funcs passed to g_source_new() + + + + the user data for the callback + + + + + + Removes a source from the default main loop context given the user +data for the callback. If multiple sources exist with the same user +data, only one will be destroyed. + + %TRUE if a source was found and removed. + + + + + the user_data for the callback. + + + + + + Sets the name of a source using its ID. + +This is a convenience utility to set source names from the return +value of g_idle_add(), g_timeout_add(), etc. + +It is a programmer error to attempt to set the name of a non-existent +source. + +More specifically: source IDs can be reissued after a source has been +destroyed and therefore it is never valid to use this function with a +source ID which may have already been removed. An example is when +scheduling an idle to run in another thread with g_idle_add(): the +idle may already have run and been removed by the time this function +is called on its (now invalid) source ID. This source ID may have +been reissued, leading to the operation being performed against the +wrong source. + + + + + + a #GSource ID + + + + debug name for the source + + + + + + Gets the smallest prime number from a built-in array of primes which +is larger than @num. This is used within GLib to calculate the optimum +size of a #GHashTable. + +The built-in array of primes ranges from 11 to 13845163 such that +each prime is approximately 1.5-2 times the previous prime. + + the smallest prime number from a built-in array of primes + which is larger than @num + + + + + a #guint + + + + + + See g_spawn_async_with_pipes() for a full description; this function +simply calls the g_spawn_async_with_pipes() without any pipes. + +You should call g_spawn_close_pid() on the returned child process +reference when you don't need it any more. + +If you are writing a GTK+ application, and the program you are +spawning is a graphical application, too, then you may want to +use gdk_spawn_on_screen() instead to ensure that the spawned program +opens its windows on the right screen. + +Note that the returned @child_pid on Windows is a handle to the child +process and not its identifier. Process handles and process identifiers +are different concepts on Windows. + + %TRUE on success, %FALSE if error is set + + + + + child's current working directory, or %NULL to inherit parent's + + + + child's argument vector + + + + + + child's environment, or %NULL to inherit parent's + + + + + + flags from #GSpawnFlags + + + + function to run in the child just before exec() + + + + user data for @child_setup + + + + return location for child process reference, or %NULL + + + + + + Executes a child program asynchronously (your program will not +block waiting for the child to exit). The child program is +specified by the only argument that must be provided, @argv. +@argv should be a %NULL-terminated array of strings, to be passed +as the argument vector for the child. The first string in @argv +is of course the name of the program to execute. By default, the +name of the program must be a full path. If @flags contains the +%G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is +used to search for the executable. If @flags contains the +%G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from +@envp is used to search for the executable. If both the +%G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags +are set, the `PATH` variable from @envp takes precedence over +the environment variable. + +If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not +used, then the program will be run from the current directory (or +@working_directory, if specified); this might be unexpected or even +dangerous in some cases when the current directory is world-writable. + +On Windows, note that all the string or string vector arguments to +this function and the other g_spawn*() functions are in UTF-8, the +GLib file name encoding. Unicode characters that are not part of +the system codepage passed in these arguments will be correctly +available in the spawned program only if it uses wide character API +to retrieve its command line. For C programs built with Microsoft's +tools it is enough to make the program have a wmain() instead of +main(). wmain() has a wide character argument vector as parameter. + +At least currently, mingw doesn't support wmain(), so if you use +mingw to develop the spawned program, it should call +g_win32_get_command_line() to get arguments in UTF-8. + +On Windows the low-level child process creation API CreateProcess() +doesn't use argument vectors, but a command line. The C runtime +library's spawn*() family of functions (which g_spawn_async_with_pipes() +eventually calls) paste the argument vector elements together into +a command line, and the C runtime startup code does a corresponding +reconstruction of an argument vector from the command line, to be +passed to main(). Complications arise when you have argument vector +elements that contain spaces of double quotes. The spawn*() functions +don't do any quoting or escaping, but on the other hand the startup +code does do unquoting and unescaping in order to enable receiving +arguments with embedded spaces or double quotes. To work around this +asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on +argument vector elements that need it before calling the C runtime +spawn() function. + +The returned @child_pid on Windows is a handle to the child +process, not its identifier. Process handles and process +identifiers are different concepts on Windows. + +@envp is a %NULL-terminated array of strings, where each string +has the form `KEY=VALUE`. This will become the child's environment. +If @envp is %NULL, the child inherits its parent's environment. + +@flags should be the bitwise OR of any flags you want to affect the +function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the +child will not automatically be reaped; you must use a child watch to +be notified about the death of the child process. Eventually you must +call g_spawn_close_pid() on the @child_pid, in order to free +resources which may be associated with the child process. (On Unix, +using a child watch is equivalent to calling waitpid() or handling +the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid() +is equivalent to calling CloseHandle() on the process handle returned +in @child_pid). See g_child_watch_add(). + +%G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file +descriptors will be inherited by the child; otherwise all descriptors +except stdin/stdout/stderr will be closed before calling exec() in +the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an +absolute path, it will be looked for in the `PATH` environment +variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an +absolute path, it will be looked for in the `PATH` variable from +@envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP +are used, the value from @envp takes precedence over the environment. +%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output +will be discarded, instead of going to the same location as the parent's +standard output. If you use this flag, @standard_output must be %NULL. +%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error +will be discarded, instead of going to the same location as the parent's +standard error. If you use this flag, @standard_error must be %NULL. +%G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's +standard input (by default, the child's standard input is attached to +/dev/null). If you use this flag, @standard_input must be %NULL. +%G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is +the file to execute, while the remaining elements are the actual +argument vector to pass to the file. Normally g_spawn_async_with_pipes() +uses @argv[0] as the file to execute, and passes all of @argv to the child. + +@child_setup and @user_data are a function and user data. On POSIX +platforms, the function is called in the child after GLib has +performed all the setup it plans to perform (including creating +pipes, closing file descriptors, etc.) but before calling exec(). +That is, @child_setup is called just before calling exec() in the +child. Obviously actions taken in this function will only affect +the child, not the parent. + +On Windows, there is no separate fork() and exec() functionality. +Child processes are created and run with a single API call, +CreateProcess(). There is no sensible thing @child_setup +could be used for on Windows so it is ignored and not called. + +If non-%NULL, @child_pid will on Unix be filled with the child's +process ID. You can use the process ID to send signals to the child, +or to use g_child_watch_add() (or waitpid()) if you specified the +%G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be +filled with a handle to the child process only if you specified the +%G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child +process using the Win32 API, for example wait for its termination +with the WaitFor*() functions, or examine its exit code with +GetExitCodeProcess(). You should close the handle with CloseHandle() +or g_spawn_close_pid() when you no longer need it. + +If non-%NULL, the @standard_input, @standard_output, @standard_error +locations will be filled with file descriptors for writing to the child's +standard input or reading from its standard output or standard error. +The caller of g_spawn_async_with_pipes() must close these file descriptors +when they are no longer in use. If these parameters are %NULL, the +corresponding pipe won't be created. + +If @standard_input is NULL, the child's standard input is attached to +/dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set. + +If @standard_error is NULL, the child's standard error goes to the same +location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL +is set. + +If @standard_output is NULL, the child's standard output goes to the same +location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL +is set. + +@error can be %NULL to ignore errors, or non-%NULL to report errors. +If an error is set, the function returns %FALSE. Errors are reported +even if they occur in the child (for example if the executable in +@argv[0] is not found). Typically the `message` field of returned +errors should be displayed to users. Possible errors are those from +the #G_SPAWN_ERROR domain. + +If an error occurs, @child_pid, @standard_input, @standard_output, +and @standard_error will not be filled with valid values. + +If @child_pid is not %NULL and an error does not occur then the returned +process reference must be closed using g_spawn_close_pid(). + +If you are writing a GTK+ application, and the program you +are spawning is a graphical application, too, then you may +want to use gdk_spawn_on_screen_with_pipes() instead to ensure that +the spawned program opens its windows on the right screen. + + %TRUE on success, %FALSE if an error was set + + + + + child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding + + + + child's argument vector, in the GLib file name encoding + + + + + + child's environment, or %NULL to inherit parent's, in the GLib file name encoding + + + + + + flags from #GSpawnFlags + + + + function to run in the child just before exec() + + + + user data for @child_setup + + + + return location for child process ID, or %NULL + + + + return location for file descriptor to write to child's stdin, or %NULL + + + + return location for file descriptor to read child's stdout, or %NULL + + + + return location for file descriptor to read child's stderr, or %NULL + + + + + + Set @error if @exit_status indicates the child exited abnormally +(e.g. with a nonzero exit code, or via a fatal signal). + +The g_spawn_sync() and g_child_watch_add() family of APIs return an +exit status for subprocesses encoded in a platform-specific way. +On Unix, this is guaranteed to be in the same format waitpid() returns, +and on Windows it is guaranteed to be the result of GetExitCodeProcess(). + +Prior to the introduction of this function in GLib 2.34, interpreting +@exit_status required use of platform-specific APIs, which is problematic +for software using GLib as a cross-platform layer. + +Additionally, many programs simply want to determine whether or not +the child exited successfully, and either propagate a #GError or +print a message to standard error. In that common case, this function +can be used. Note that the error message in @error will contain +human-readable information about the exit status. + +The @domain and @code of @error have special semantics in the case +where the process has an "exit code", as opposed to being killed by +a signal. On Unix, this happens if WIFEXITED() would be true of +@exit_status. On Windows, it is always the case. + +The special semantics are that the actual exit code will be the +code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR. +This allows you to differentiate between different exit codes. + +If the process was terminated by some means other than an exit +status, the domain will be %G_SPAWN_ERROR, and the code will be +%G_SPAWN_ERROR_FAILED. + +This function just offers convenience; you can of course also check +the available platform via a macro such as %G_OS_UNIX, and use +WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt +to scan or parse the error message string; it may be translated and/or +change in future versions of GLib. + + %TRUE if child exited successfully, %FALSE otherwise (and + @error will be set) + + + + + An exit code as returned from g_spawn_sync() + + + + + + On some platforms, notably Windows, the #GPid type represents a resource +which must be closed to prevent resource leaking. g_spawn_close_pid() +is provided for this purpose. It should be used on all platforms, even +though it doesn't do anything under UNIX. + + + + + + The process reference to close + + + + + + A simple version of g_spawn_async() that parses a command line with +g_shell_parse_argv() and passes it to g_spawn_async(). Runs a +command line in the background. Unlike g_spawn_async(), the +%G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note +that %G_SPAWN_SEARCH_PATH can have security implications, so +consider using g_spawn_async() directly if appropriate. Possible +errors are those from g_shell_parse_argv() and g_spawn_async(). + +The same concerns on Windows apply as for g_spawn_command_line_sync(). + + %TRUE on success, %FALSE if error is set + + + + + a command line + + + + + + A simple version of g_spawn_sync() with little-used parameters +removed, taking a command line instead of an argument vector. See +g_spawn_sync() for full details. @command_line will be parsed by +g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag +is enabled. Note that %G_SPAWN_SEARCH_PATH can have security +implications, so consider using g_spawn_sync() directly if +appropriate. Possible errors are those from g_spawn_sync() and those +from g_shell_parse_argv(). + +If @exit_status is non-%NULL, the platform-specific exit status of +the child is stored there; see the documentation of +g_spawn_check_exit_status() for how to use and interpret this. + +On Windows, please note the implications of g_shell_parse_argv() +parsing @command_line. Parsing is done according to Unix shell rules, not +Windows command interpreter rules. +Space is a separator, and backslashes are +special. Thus you cannot simply pass a @command_line containing +canonical Windows paths, like "c:\\program files\\app\\app.exe", as +the backslashes will be eaten, and the space will act as a +separator. You need to enclose such paths with single quotes, like +"'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'". + + %TRUE on success, %FALSE if an error was set + + + + + a command line + + + + return location for child output + + + + + + return location for child errors + + + + + + return location for child exit status, as returned by waitpid() + + + + + + + + + + + + + + + + Executes a child synchronously (waits for the child to exit before returning). +All output from the child is stored in @standard_output and @standard_error, +if those parameters are non-%NULL. Note that you must set the +%G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when +passing %NULL for @standard_output and @standard_error. + +If @exit_status is non-%NULL, the platform-specific exit status of +the child is stored there; see the documentation of +g_spawn_check_exit_status() for how to use and interpret this. +Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in +@flags. + +If an error occurs, no data is returned in @standard_output, +@standard_error, or @exit_status. + +This function calls g_spawn_async_with_pipes() internally; see that +function for full details on the other parameters and details on +how these functions work on Windows. + + %TRUE on success, %FALSE if an error was set + + + + + child's current working directory, or %NULL to inherit parent's + + + + child's argument vector + + + + + + child's environment, or %NULL to inherit parent's + + + + + + flags from #GSpawnFlags + + + + function to run in the child just before exec() + + + + user data for @child_setup + + + + return location for child output, or %NULL + + + + + + return location for child error messages, or %NULL + + + + + + return location for child exit status, as returned by waitpid(), or %NULL + + + + + + An implementation of the standard sprintf() function which supports +positional parameters, as specified in the Single Unix Specification. + +Note that it is usually better to use g_snprintf(), to avoid the +risk of buffer overflow. + +See also g_strdup_printf(). + + the number of bytes printed. + + + + + A pointer to a memory buffer to contain the resulting string. It + is up to the caller to ensure that the allocated buffer is large + enough to hold the formatted result + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + the arguments to insert in the output. + + + + + + Copies a nul-terminated string into the dest buffer, include the +trailing nul, and return a pointer to the trailing nul byte. +This is useful for concatenating multiple strings together +without having to repeatedly scan for the end. + + a pointer to trailing nul byte. + + + + + destination buffer. + + + + source string. + + + + + + Compares two strings for byte-by-byte equality and returns %TRUE +if they are equal. It can be passed to g_hash_table_new() as the +@key_equal_func parameter, when using non-%NULL strings as keys in a +#GHashTable. + +Note that this function is primarily meant as a hash table comparison +function. For a general-purpose, %NULL-safe string comparison function, +see g_strcmp0(). + + %TRUE if the two keys match + + + + + a key + + + + a key to compare with @v1 + + + + + + Looks whether the string @str begins with @prefix. + + %TRUE if @str begins with @prefix, %FALSE otherwise. + + + + + a nul-terminated string + + + + the nul-terminated prefix to look for + + + + + + Looks whether the string @str ends with @suffix. + + %TRUE if @str end with @suffix, %FALSE otherwise. + + + + + a nul-terminated string + + + + the nul-terminated suffix to look for + + + + + + Converts a string to a hash value. + +This function implements the widely used "djb" hash apparently +posted by Daniel Bernstein to comp.lang.c some time ago. The 32 +bit unsigned hash value starts at 5381 and for each byte 'c' in +the string, is updated: `hash = hash * 33 + c`. This function +uses the signed value of each byte. + +It can be passed to g_hash_table_new() as the @hash_func parameter, +when using non-%NULL strings as keys in a #GHashTable. + +Note that this function may not be a perfect fit for all use cases. +For example, it produces some hash collisions with strings as short +as 2. + + a hash value corresponding to the key + + + + + a string key + + + + + + Determines if a string is pure ASCII. A string is pure ASCII if it +contains no bytes with the high bit set. + + %TRUE if @str is ASCII + + + + + a string + + + + + + Checks if a search conducted for @search_term should match +@potential_hit. + +This function calls g_str_tokenize_and_fold() on both +@search_term and @potential_hit. ASCII alternates are never taken +for @search_term but will be taken for @potential_hit according to +the value of @accept_alternates. + +A hit occurs when each folded token in @search_term is a prefix of a +folded token from @potential_hit. + +Depending on how you're performing the search, it will typically be +faster to call g_str_tokenize_and_fold() on each string in +your corpus and build an index on the returned folded tokens, then +call g_str_tokenize_and_fold() on the search term and +perform lookups into that index. + +As some examples, searching for "fred" would match the potential hit +"Smith, Fred" and also "Frédéric". Searching for "Fréd" would match +"Frédéric" but not "Frederic" (due to the one-directional nature of +accent matching). Searching "fo" would match "Foo" and "Bar Foo +Baz", but not "SFO" (because no word as "fo" as a prefix). + + %TRUE if @potential_hit is a hit + + + + + the search term from the user + + + + the text that may be a hit + + + + %TRUE to accept ASCII alternates + + + + + + Transliterate @str to plain ASCII. + +For best results, @str should be in composed normalised form. + +This function performs a reasonably good set of character +replacements. The particular set of replacements that is done may +change by version or even by runtime environment. + +If the source language of @str is known, it can used to improve the +accuracy of the translation by passing it as @from_locale. It should +be a valid POSIX locale string (of the form +"language[_territory][.codeset][@modifier]"). + +If @from_locale is %NULL then the current locale is used. + +If you want to do translation for no specific locale, and you want it +to be done independently of the currently locale, specify "C" for +@from_locale. + + a string in plain ASCII + + + + + a string, in UTF-8 + + + + the source locale, if known + + + + + + Tokenises @string and performs folding on each token. + +A token is a non-empty sequence of alphanumeric characters in the +source string, separated by non-alphanumeric characters. An +"alphanumeric" character for this purpose is one that matches +g_unichar_isalnum() or g_unichar_ismark(). + +Each token is then (Unicode) normalised and case-folded. If +@ascii_alternates is non-%NULL and some of the returned tokens +contain non-ASCII characters, ASCII alternatives will be generated. + +The number of ASCII alternatives that are generated and the method +for doing so is unspecified, but @translit_locale (if specified) may +improve the transliteration if the language of the source string is +known. + + the folded tokens + + + + + + + a string + + + + the language code (like 'de' or + 'en_GB') from which @string originates + + + + a + return location for ASCII alternates + + + + + + + + For each character in @string, if the character is not in @valid_chars, +replaces the character with @substitutor. Modifies @string in place, +and return @string itself, not a copy. The return value is to allow +nesting such as +|[<!-- language="C" --> + g_ascii_strup (g_strcanon (str, "abc", '?')) +]| + + @string + + + + + a nul-terminated array of bytes + + + + bytes permitted in @string + + + + replacement character for disallowed bytes + + + + + + A case-insensitive string comparison, corresponding to the standard +strcasecmp() function on platforms which support it. + See g_strncasecmp() for a discussion of why this + function is deprecated and how to replace it. + + 0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2. + + + + + a string + + + + a string to compare with @s1 + + + + + + Removes trailing whitespace from a string. + +This function doesn't allocate or reallocate any memory; +it modifies @string in place. Therefore, it cannot be used +on statically allocated strings. + +The pointer to @string is returned to allow the nesting of functions. + +Also see g_strchug() and g_strstrip(). + + @string + + + + + a string to remove the trailing whitespace from + + + + + + Removes leading whitespace from a string, by moving the rest +of the characters forward. + +This function doesn't allocate or reallocate any memory; +it modifies @string in place. Therefore, it cannot be used on +statically allocated strings. + +The pointer to @string is returned to allow the nesting of functions. + +Also see g_strchomp() and g_strstrip(). + + @string + + + + + a string to remove the leading whitespace from + + + + + + Compares @str1 and @str2 like strcmp(). Handles %NULL +gracefully by sorting it before non-%NULL strings. +Comparing two %NULL pointers returns 0. + + an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2. + + + + + a C string or %NULL + + + + another C string or %NULL + + + + + + Replaces all escaped characters with their one byte equivalent. + +This function does the reverse conversion of g_strescape(). + + a newly-allocated copy of @source with all escaped + character compressed + + + + + a string to compress + + + + + + Concatenates all of the given strings into one long string. The +returned string should be freed with g_free() when no longer needed. + +The variable argument list must end with %NULL. If you forget the %NULL, +g_strconcat() will start appending random memory junk to your string. + +Note that this function is usually not the right function to use to +assemble a translated message from pieces, since proper translation +often requires the pieces to be reordered. + + a newly-allocated string containing all the string arguments + + + + + the first string to add, which must not be %NULL + + + + a %NULL-terminated list of strings to append to the string + + + + + + Converts any delimiter characters in @string to @new_delimiter. +Any characters in @string which are found in @delimiters are +changed to the @new_delimiter character. Modifies @string in place, +and returns @string itself, not a copy. The return value is to +allow nesting such as +|[<!-- language="C" --> + g_ascii_strup (g_strdelimit (str, "abc", '?')) +]| + + @string + + + + + the string to convert + + + + a string containing the current delimiters, + or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS + + + + the new delimiter character + + + + + + Converts a string to lower case. + This function is totally broken for the reasons discussed +in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() +instead. + + the string + + + + + the string to convert. + + + + + + Duplicates a string. If @str is %NULL it returns %NULL. +The returned string should be freed with g_free() +when no longer needed. + + a newly-allocated copy of @str + + + + + the string to duplicate + + + + + + Similar to the standard C sprintf() function but safer, since it +calculates the maximum space required and allocates memory to hold +the result. The returned string should be freed with g_free() when no +longer needed. + + a newly-allocated string holding the result + + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + the parameters to insert into the format string + + + + + + Similar to the standard C vsprintf() function but safer, since it +calculates the maximum space required and allocates memory to hold +the result. The returned string should be freed with g_free() when +no longer needed. + +See also g_vasprintf(), which offers the same functionality, but +additionally returns the length of the allocated string. + + a newly-allocated string holding the result + + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + the list of parameters to insert into the format string + + + + + + Copies %NULL-terminated array of strings. The copy is a deep copy; +the new array should be freed by first freeing each string, then +the array itself. g_strfreev() does this for you. If called +on a %NULL value, g_strdupv() simply returns %NULL. + + a new %NULL-terminated array of strings. + + + + + + + a %NULL-terminated array of strings + + + + + + Returns a string corresponding to the given error code, e.g. "no +such process". Unlike strerror(), this always returns a string in +UTF-8 encoding, and the pointer is guaranteed to remain valid for +the lifetime of the process. + +Note that the string may be translated according to the current locale. + +The value of %errno will not be changed by this function. + + a UTF-8 string describing the error code. If the error code + is unknown, it returns a string like "unknown error (<code>)". + + + + + the system error number. See the standard C %errno + documentation + + + + + + Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\' +and '"' in the string @source by inserting a '\' before +them. Additionally all characters in the range 0x01-0x1F (everything +below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are +replaced with a '\' followed by their octal representation. +Characters supplied in @exceptions are not escaped. + +g_strcompress() does the reverse conversion. + + a newly-allocated copy of @source with certain + characters escaped. See above. + + + + + a string to escape + + + + a string of characters not to escape in @source + + + + + + Frees a %NULL-terminated array of strings, as well as each +string it contains. + +If @str_array is %NULL, this function simply returns. + + + + + + a %NULL-terminated array of strings to free + + + + + + Creates a new #GString, initialized with the given string. + + the new #GString + + + + + the initial text to copy into the string, or %NULL to +start with an empty string + + + + + + Creates a new #GString with @len bytes of the @init buffer. +Because a length is provided, @init need not be nul-terminated, +and can contain embedded nul bytes. + +Since this function does not stop at nul bytes, it is the caller's +responsibility to ensure that @init has at least @len addressable +bytes. + + a new #GString + + + + + initial contents of the string + + + + length of @init to use + + + + + + Creates a new #GString, with enough space for @dfl_size +bytes. This is useful if you are going to add a lot of +text to the string and don't want it to be reallocated +too often. + + the new #GString + + + + + the default size of the space allocated to + hold the string + + + + + + An auxiliary function for gettext() support (see Q_()). + + @msgval, unless @msgval is identical to @msgid + and contains a '|' character, in which case a pointer to + the substring of msgid after the first '|' character is returned. + + + + + a string + + + + another string + + + + + + Joins a number of strings together to form one long string, with the +optional @separator inserted between each of them. The returned string +should be freed with g_free(). + + a newly-allocated string containing all of the strings joined + together, with @separator between them + + + + + a string to insert between each of the + strings, or %NULL + + + + a %NULL-terminated list of strings to join + + + + + + Joins a number of strings together to form one long string, with the +optional @separator inserted between each of them. The returned string +should be freed with g_free(). + +If @str_array has no items, the return value will be an +empty string. If @str_array contains a single item, @separator will not +appear in the resulting string. + + a newly-allocated string containing all of the strings joined + together, with @separator between them + + + + + a string to insert between each of the + strings, or %NULL + + + + a %NULL-terminated array of strings to join + + + + + + Portability wrapper that calls strlcat() on systems which have it, +and emulates it otherwise. Appends nul-terminated @src string to @dest, +guaranteeing nul-termination for @dest. The total size of @dest won't +exceed @dest_size. + +At most @dest_size - 1 characters will be copied. Unlike strncat(), +@dest_size is the full size of dest, not the space left over. This +function does not allocate memory. It always nul-terminates (unless +@dest_size == 0 or there were no nul characters in the @dest_size +characters of dest to start with). + +Caveat: this is supposedly a more secure alternative to strcat() or +strncat(), but for real security g_strconcat() is harder to mess up. + + size of attempted result, which is MIN (dest_size, strlen + (original dest)) + strlen (src), so if retval >= dest_size, + truncation occurred. + + + + + destination buffer, already containing one nul-terminated string + + + + source buffer + + + + length of @dest buffer in bytes (not length of existing string + inside @dest) + + + + + + Portability wrapper that calls strlcpy() on systems which have it, +and emulates strlcpy() otherwise. Copies @src to @dest; @dest is +guaranteed to be nul-terminated; @src must be nul-terminated; +@dest_size is the buffer size, not the number of bytes to copy. + +At most @dest_size - 1 characters will be copied. Always nul-terminates +(unless @dest_size is 0). This function does not allocate memory. Unlike +strncpy(), this function doesn't pad @dest (so it's often faster). It +returns the size of the attempted result, strlen (src), so if +@retval >= @dest_size, truncation occurred. + +Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(), +but if you really want to avoid screwups, g_strdup() is an even better +idea. + + length of @src + + + + + destination buffer + + + + source buffer + + + + length of @dest in bytes + + + + + + A case-insensitive string comparison, corresponding to the standard +strncasecmp() function on platforms which support it. It is similar +to g_strcasecmp() except it only compares the first @n characters of +the strings. + The problem with g_strncasecmp() is that it does + the comparison by calling toupper()/tolower(). These functions + are locale-specific and operate on single bytes. However, it is + impossible to handle things correctly from an internationalization + standpoint by operating on bytes, since characters may be multibyte. + Thus g_strncasecmp() is broken if your string is guaranteed to be + ASCII, since it is locale-sensitive, and it's broken if your string + is localized, since it doesn't work on many encodings at all, + including UTF-8, EUC-JP, etc. + + There are therefore two replacement techniques: g_ascii_strncasecmp(), + which only works on ASCII and is not locale-sensitive, and + g_utf8_casefold() followed by strcmp() on the resulting strings, + which is good for case-insensitive sorting of UTF-8. + + 0 if the strings match, a negative value if @s1 < @s2, + or a positive value if @s1 > @s2. + + + + + a string + + + + a string to compare with @s1 + + + + the maximum number of characters to compare + + + + + + Duplicates the first @n bytes of a string, returning a newly-allocated +buffer @n + 1 bytes long which will always be nul-terminated. If @str +is less than @n bytes long the buffer is padded with nuls. If @str is +%NULL it returns %NULL. The returned value should be freed when no longer +needed. + +To copy a number of characters from a UTF-8 encoded string, +use g_utf8_strncpy() instead. + + a newly-allocated buffer containing the first @n bytes + of @str, nul-terminated + + + + + the string to duplicate + + + + the maximum number of bytes to copy from @str + + + + + + Creates a new string @length bytes long filled with @fill_char. +The returned string should be freed when no longer needed. + + a newly-allocated string filled the @fill_char + + + + + the length of the new string + + + + the byte to fill the string with + + + + + + Reverses all of the bytes in a string. For example, +`g_strreverse ("abcdef")` will result in "fedcba". + +Note that g_strreverse() doesn't work on UTF-8 strings +containing multibyte characters. For that purpose, use +g_utf8_strreverse(). + + the same pointer passed in as @string + + + + + the string to reverse + + + + + + Searches the string @haystack for the last occurrence +of the string @needle. + + a pointer to the found occurrence, or + %NULL if not found. + + + + + a nul-terminated string + + + + the nul-terminated string to search for + + + + + + Searches the string @haystack for the last occurrence +of the string @needle, limiting the length of the search +to @haystack_len. + + a pointer to the found occurrence, or + %NULL if not found. + + + + + a nul-terminated string + + + + the maximum length of @haystack + + + + the nul-terminated string to search for + + + + + + Returns a string describing the given signal, e.g. "Segmentation fault". +You should use this function in preference to strsignal(), because it +returns a string in UTF-8 encoding, and since not all platforms support +the strsignal() function. + + a UTF-8 string describing the signal. If the signal is unknown, + it returns "unknown signal (<signum>)". + + + + + the signal number. See the `signal` documentation + + + + + + Splits a string into a maximum of @max_tokens pieces, using the given +@delimiter. If @max_tokens is reached, the remainder of @string is +appended to the last token. + +As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a +%NULL-terminated vector containing the six strings "", "a", "bc", "", "d" +and "". + +As a special case, the result of splitting the empty string "" is an empty +vector, not a vector containing a single string. The reason for this +special case is that being able to represent a empty vector is typically +more useful than consistent handling of empty elements. If you do need +to represent empty elements, you'll need to check for the empty string +before calling g_strsplit(). + + a newly-allocated %NULL-terminated array of strings. Use + g_strfreev() to free it. + + + + + + + a string to split + + + + a string which specifies the places at which to split + the string. The delimiter is not included in any of the resulting + strings, unless @max_tokens is reached. + + + + the maximum number of pieces to split @string into. + If this is less than 1, the string is split completely. + + + + + + Splits @string into a number of tokens not containing any of the characters +in @delimiter. A token is the (possibly empty) longest string that does not +contain any of the characters in @delimiters. If @max_tokens is reached, the +remainder is appended to the last token. + +For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a +%NULL-terminated vector containing the three strings "abc", "def", +and "ghi". + +The result of g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated +vector containing the four strings "", "def", "ghi", and "". + +As a special case, the result of splitting the empty string "" is an empty +vector, not a vector containing a single string. The reason for this +special case is that being able to represent a empty vector is typically +more useful than consistent handling of empty elements. If you do need +to represent empty elements, you'll need to check for the empty string +before calling g_strsplit_set(). + +Note that this function works on bytes not characters, so it can't be used +to delimit UTF-8 strings for anything but ASCII characters. + + a newly-allocated %NULL-terminated array of strings. Use + g_strfreev() to free it. + + + + + + + The string to be tokenized + + + + A nul-terminated string containing bytes that are used + to split the string. + + + + The maximum number of tokens to split @string into. + If this is less than 1, the string is split completely + + + + + + Searches the string @haystack for the first occurrence +of the string @needle, limiting the length of the search +to @haystack_len. + + a pointer to the found occurrence, or + %NULL if not found. + + + + + a string + + + + the maximum length of @haystack. Note that -1 is + a valid length, if @haystack is nul-terminated, meaning it will + search through the whole string. + + + + the string to search for + + + + + + Converts a string to a #gdouble value. +It calls the standard strtod() function to handle the conversion, but +if the string is not completely converted it attempts the conversion +again with g_ascii_strtod(), and returns the best match. + +This function should seldom be used. The normal situation when reading +numbers not for human consumption is to use g_ascii_strtod(). Only when +you know that you must expect both locale formatted and C formatted numbers +should you use this. Make sure that you don't pass strings such as comma +separated lists of values, since the commas may be interpreted as a decimal +point in some locales, causing unexpected results. + + the #gdouble value. + + + + + the string to convert to a numeric value. + + + + if non-%NULL, it returns the + character after the last character used in the conversion. + + + + + + Converts a string to upper case. + This function is totally broken for the reasons + discussed in the g_strncasecmp() docs - use g_ascii_strup() + or g_utf8_strup() instead. + + the string + + + + + the string to convert + + + + + + Checks if @strv contains @str. @strv must not be %NULL. + + %TRUE if @str is an element of @strv, according to g_str_equal(). + + + + + a %NULL-terminated array of strings + + + + a string + + + + + + + + + + + Returns the length of the given %NULL-terminated +string array @str_array. + + length of @str_array. + + + + + a %NULL-terminated array of strings + + + + + + Create a new test case, similar to g_test_create_case(). However +the test is assumed to use no fixture, and test suites are automatically +created on the fly and added to the root fixture, based on the +slash-separated portions of @testpath. The @test_data argument +will be passed as first argument to @test_func. + +If @testpath includes the component "subprocess" anywhere in it, +the test will be skipped by default, and only run if explicitly +required via the `-p` command-line option or g_test_trap_subprocess(). + + + + + + /-separated test case path name for the test. + + + + Test data argument for the test function. + + + + The test function to invoke for this test. + + + + + + Create a new test case, as with g_test_add_data_func(), but freeing +@test_data after the test run is complete. + + + + + + /-separated test case path name for the test. + + + + Test data argument for the test function. + + + + The test function to invoke for this test. + + + + #GDestroyNotify for @test_data. + + + + + + Create a new test case, similar to g_test_create_case(). However +the test is assumed to use no fixture, and test suites are automatically +created on the fly and added to the root fixture, based on the +slash-separated portions of @testpath. + +If @testpath includes the component "subprocess" anywhere in it, +the test will be skipped by default, and only run if explicitly +required via the `-p` command-line option or g_test_trap_subprocess(). + + + + + + /-separated test case path name for the test. + + + + The test function to invoke for this test. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This function adds a message to test reports that +associates a bug URI with a test case. +Bug URIs are constructed from a base URI set with g_test_bug_base() +and @bug_uri_snippet. + + + + + + Bug specific bug tracker URI portion. + + + + + + Specify the base URI for bug reports. + +The base URI is used to construct bug report messages for +g_test_message() when g_test_bug() is called. +Calling this function outside of a test case sets the +default base URI for all test cases. Calling it from within +a test case changes the base URI for the scope of the test +case only. +Bug URIs are constructed by appending a bug specific URI +portion to @uri_pattern, or by replacing the special string +'\%s' within @uri_pattern if that is present. + + + + + + the base pattern for bug URIs + + + + + + Creates the pathname to a data file that is required for a test. + +This function is conceptually similar to g_build_filename() except +that the first argument has been replaced with a #GTestFileType +argument. + +The data file should either have been distributed with the module +containing the test (%G_TEST_DIST) or built as part of the build +system of that module (%G_TEST_BUILT). + +In order for this function to work in srcdir != builddir situations, +the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to +have been defined. As of 2.38, this is done by the glib.mk +included in GLib. Please ensure that your copy is up to date before +using this function. + +In case neither variable is set, this function will fall back to +using the dirname portion of argv[0], possibly removing ".libs". +This allows for casual running of tests directly from the commandline +in the srcdir == builddir case and should also support running of +installed tests, assuming the data files have been installed in the +same relative path as the test binary. + + the path of the file, to be freed using g_free() + + + + + the type of file (built vs. distributed) + + + + the first segment of the pathname + + + + %NULL-terminated additional path segments + + + + + + Create a new #GTestCase, named @test_name, this API is fairly +low level, calling g_test_add() or g_test_add_func() is preferable. +When this test is executed, a fixture structure of size @data_size +will be automatically allocated and filled with zeros. Then @data_setup is +called to initialize the fixture. After fixture setup, the actual test +function @data_test is called. Once the test run completes, the +fixture structure is torn down by calling @data_teardown and +after that the memory is automatically released by the test framework. + +Splitting up a test run into fixture setup, test function and +fixture teardown is most useful if the same fixture is used for +multiple tests. In this cases, g_test_create_case() will be +called with the same fixture, but varying @test_name and +@data_test arguments. + + a newly allocated #GTestCase. + + + + + the name for the test case + + + + the size of the fixture data structure + + + + test data argument for the test functions + + + + the function to set up the fixture data + + + + the actual test function + + + + the function to teardown the fixture data + + + + + + Create a new test suite with the name @suite_name. + + A newly allocated #GTestSuite instance. + + + + + a name for the suite + + + + + + Indicates that a message with the given @log_domain and @log_level, +with text matching @pattern, is expected to be logged. When this +message is logged, it will not be printed, and the test case will +not abort. + +This API may only be used with the old logging API (g_log() without +%G_LOG_USE_STRUCTURED defined). It will not work with the structured logging +API. See [Testing for Messages][testing-for-messages]. + +Use g_test_assert_expected_messages() to assert that all +previously-expected messages have been seen and suppressed. + +You can call this multiple times in a row, if multiple messages are +expected as a result of a single call. (The messages must appear in +the same order as the calls to g_test_expect_message().) + +For example: + +|[<!-- language="C" --> + // g_main_context_push_thread_default() should fail if the + // context is already owned by another thread. + g_test_expect_message (G_LOG_DOMAIN, + G_LOG_LEVEL_CRITICAL, + "assertion*acquired_context*failed"); + g_main_context_push_thread_default (bad_context); + g_test_assert_expected_messages (); +]| + +Note that you cannot use this to test g_error() messages, since +g_error() intentionally never returns even if the program doesn't +abort; use g_test_trap_subprocess() in this case. + +If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly +expected via g_test_expect_message() then they will be ignored. + + + + + + the log domain of the message + + + + the log level of the message + + + + a glob-style [pattern][glib-Glob-style-pattern-matching] + + + + + + Indicates that a test failed. This function can be called +multiple times from the same test. You can use this function +if your test failed in a recoverable way. + +Do not use this function if the failure of a test could cause +other tests to malfunction. + +Calling this function will not stop the test from running, you +need to return from the test function yourself. So you can +produce additional diagnostic messages or even continue running +the test. + +If not called from inside a test, this function does nothing. + + + + + + Returns whether a test has already failed. This will +be the case when g_test_fail(), g_test_incomplete() +or g_test_skip() have been called, but also if an +assertion has failed. + +This can be useful to return early from a test if +continuing after a failed assertion might be harmful. + +The return value of this function is only meaningful +if it is called from inside a test function. + + %TRUE if the test has failed + + + + + Gets the pathname of the directory containing test files of the type +specified by @file_type. + +This is approximately the same as calling g_test_build_filename("."), +but you don't need to free the return value. + + the path of the directory, owned by GLib + + + + + the type of file (built vs. distributed) + + + + + + Gets the pathname to a data file that is required for a test. + +This is the same as g_test_build_filename() with two differences. +The first difference is that must only use this function from within +a testcase function. The second difference is that you need not free +the return value -- it will be automatically freed when the testcase +finishes running. + +It is safe to use this function from a thread inside of a testcase +but you must ensure that all such uses occur before the main testcase +function returns (ie: it is best to ensure that all threads have been +joined). + + the path, automatically freed at the end of the testcase + + + + + the type of file (built vs. distributed) + + + + the first segment of the pathname + + + + %NULL-terminated additional path segments + + + + + + Get the toplevel test suite for the test path API. + + the toplevel #GTestSuite + + + + + Indicates that a test failed because of some incomplete +functionality. This function can be called multiple times +from the same test. + +Calling this function will not stop the test from running, you +need to return from the test function yourself. So you can +produce additional diagnostic messages or even continue running +the test. + +If not called from inside a test, this function does nothing. + + + + + + explanation + + + + + + Initialize the GLib testing framework, e.g. by seeding the +test random number generator, the name for g_get_prgname() +and parsing test related command line args. + +So far, the following arguments are understood: + +- `-l`: List test cases available in a test executable. +- `--seed=SEED`: Provide a random seed to reproduce test + runs using random numbers. +- `--verbose`: Run tests verbosely. +- `-q`, `--quiet`: Run tests quietly. +- `-p PATH`: Execute all tests matching the given path. + This can also be used to force a test to run that would otherwise + be skipped (ie, a test whose name contains "/subprocess"). +- `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes: + + `perf`: Performance tests, may take long and report results. + + `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage. + + `quick`: Quick tests, should run really quickly and give good coverage. + + `undefined`: Tests for undefined behaviour, may provoke programming errors + under g_test_trap_subprocess() or g_test_expect_message() to check + that appropriate assertions or warnings are given + + `no-undefined`: Avoid tests for undefined behaviour + +- `--debug-log`: Debug test logging output. + + + + + + Address of the @argc parameter of the main() function. + Changed if any arguments were handled. + + + + Address of the @argv parameter of main(). + Any parameters understood by g_test_init() stripped before return. + + + + %NULL-terminated list of special options. Currently the only + defined option is `"no_g_set_prgname"`, which + will cause g_test_init() to not call g_set_prgname(). + + + + + + Installs a non-error fatal log handler which can be +used to decide whether log messages which are counted +as fatal abort the program. + +The use case here is that you are running a test case +that depends on particular libraries or circumstances +and cannot prevent certain known critical or warning +messages. So you install a handler that compares the +domain and message to precisely not abort in such a case. + +Note that the handler is reset at the beginning of +any test case, so you have to set it inside each test +function which needs the special behavior. + +This handler has no effect on g_error messages. + +This handler also has no effect on structured log messages (using +g_log_structured() or g_log_structured_array()). To change the fatal +behaviour for specific log messages, programs must install a custom log +writer function using g_log_set_writer_func().See +[Using Structured Logging][using-structured-logging]. + + + + + + the log handler function. + + + + data passed to the log handler. + + + + + + + + + + + + + + + + Report the result of a performance or measurement test. +The test should generally strive to maximize the reported +quantities (larger values are better than smaller ones), +this and @maximized_quantity can determine sorting +order for test result reports. + + + + + + the reported value + + + + the format string of the report message + + + + arguments to pass to the printf() function + + + + + + Add a message to the test report. + + + + + + the format string + + + + printf-like arguments to @format + + + + + + Report the result of a performance or measurement test. +The test should generally strive to minimize the reported +quantities (smaller values are better than larger ones), +this and @minimized_quantity can determine sorting +order for test result reports. + + + + + + the reported value + + + + the format string of the report message + + + + arguments to pass to the printf() function + + + + + + This function enqueus a callback @destroy_func to be executed +during the next test case teardown phase. This is most useful +to auto destruct allocted test resources at the end of a test run. +Resources are released in reverse queue order, that means enqueueing +callback A before callback B will cause B() to be called before +A() during teardown. + + + + + + Destroy callback for teardown phase. + + + + Destroy callback data. + + + + + + Enqueue a pointer to be released with g_free() during the next +teardown phase. This is equivalent to calling g_test_queue_destroy() +with a destroy callback of g_free(). + + + + + + the pointer to be stored. + + + + + + Get a reproducible random floating point number, +see g_test_rand_int() for details on test case random numbers. + + a random number from the seeded random number generator. + + + + + Get a reproducible random floating pointer number out of a specified range, +see g_test_rand_int() for details on test case random numbers. + + a number with @range_start <= number < @range_end. + + + + + the minimum value returned by this function + + + + the minimum value not returned by this function + + + + + + Get a reproducible random integer number. + +The random numbers generated by the g_test_rand_*() family of functions +change with every new test program start, unless the --seed option is +given when starting test programs. + +For individual test cases however, the random number generator is +reseeded, to avoid dependencies between tests and to make --seed +effective for all test cases. + + a random number from the seeded random number generator. + + + + + Get a reproducible random integer number out of a specified range, +see g_test_rand_int() for details on test case random numbers. + + a number with @begin <= number < @end. + + + + + the minimum value returned by this function + + + + the smallest value not to be returned by this function + + + + + + Runs all tests under the toplevel suite which can be retrieved +with g_test_get_root(). Similar to g_test_run_suite(), the test +cases to be run are filtered according to test path arguments +(`-p testpath`) as parsed by g_test_init(). g_test_run_suite() +or g_test_run() may only be called once in a program. + +In general, the tests and sub-suites within each suite are run in +the order in which they are defined. However, note that prior to +GLib 2.36, there was a bug in the `g_test_add_*` +functions which caused them to create multiple suites with the same +name, meaning that if you created tests "/foo/simple", +"/bar/simple", and "/foo/using-bar" in that order, they would get +run in that order (since g_test_run() would run the first "/foo" +suite, then the "/bar" suite, then the second "/foo" suite). As of +2.36, this bug is fixed, and adding the tests in that order would +result in a running order of "/foo/simple", "/foo/using-bar", +"/bar/simple". If this new ordering is sub-optimal (because it puts +more-complicated tests before simpler ones, making it harder to +figure out exactly what has failed), you can fix it by changing the +test paths to group tests by suite in a way that will result in the +desired running order. Eg, "/simple/foo", "/simple/bar", +"/complex/foo-using-bar". + +However, you should never make the actual result of a test depend +on the order that tests are run in. If you need to ensure that some +particular code runs before or after a given test case, use +g_test_add(), which lets you specify setup and teardown functions. + +If all tests are skipped, this function will return 0 if +producing TAP output, or 77 (treated as "skip test" by Automake) otherwise. + + 0 on success, 1 on failure (assuming it returns at all), + 0 or 77 if all tests were skipped with g_test_skip() + + + + + Execute the tests within @suite and all nested #GTestSuites. +The test suites to be executed are filtered according to +test path arguments (`-p testpath`) as parsed by g_test_init(). +See the g_test_run() documentation for more information on the +order that tests are run in. + +g_test_run_suite() or g_test_run() may only be called once +in a program. + + 0 on success + + + + + a #GTestSuite + + + + + + Changes the behaviour of g_assert_cmpstr(), g_assert_cmpint(), +g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpfloat(), +g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(), +g_assert_error(), g_test_assert_expected_messages() and the various +g_test_trap_assert_*() macros to not abort to program, but instead +call g_test_fail() and continue. (This also changes the behavior of +g_test_fail() so that it will not cause the test program to abort +after completing the failed test.) + +Note that the g_assert_not_reached() and g_assert() are not +affected by this. + +This function can only be called after g_test_init(). + + + + + + Indicates that a test was skipped. + +Calling this function will not stop the test from running, you +need to return from the test function yourself. So you can +produce additional diagnostic messages or even continue running +the test. + +If not called from inside a test, this function does nothing. + + + + + + explanation + + + + + + Returns %TRUE (after g_test_init() has been called) if the test +program is running under g_test_trap_subprocess(). + + %TRUE if the test program is running under +g_test_trap_subprocess(). + + + + + Get the time since the last start of the timer with g_test_timer_start(). + + the time since the last start of the timer, as a double + + + + + Report the last result of g_test_timer_elapsed(). + + the last result of g_test_timer_elapsed(), as a double + + + + + Start a timing test. Call g_test_timer_elapsed() when the task is supposed +to be done. Call this function again to restart the timer. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Fork the current test program to execute a test case that might +not return or that might abort. + +If @usec_timeout is non-0, the forked test case is aborted and +considered failing if its run time exceeds it. + +The forking behavior can be configured with the #GTestTrapFlags flags. + +In the following example, the test code forks, the forked child +process produces some sample output and exits successfully. +The forking parent process then asserts successful child program +termination and validates child program outputs. + +|[<!-- language="C" --> + static void + test_fork_patterns (void) + { + if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR)) + { + g_print ("some stdout text: somagic17\n"); + g_printerr ("some stderr text: semagic43\n"); + exit (0); // successful test run + } + g_test_trap_assert_passed (); + g_test_trap_assert_stdout ("*somagic17*"); + g_test_trap_assert_stderr ("*semagic43*"); + } +]| + This function is implemented only on Unix platforms, +and is not always reliable due to problems inherent in +fork-without-exec. Use g_test_trap_subprocess() instead. + + %TRUE for the forked child and %FALSE for the executing parent process. + + + + + Timeout for the forked test in micro seconds. + + + + Flags to modify forking behaviour. + + + + + + Check the result of the last g_test_trap_subprocess() call. + + %TRUE if the last test subprocess terminated successfully. + + + + + Check the result of the last g_test_trap_subprocess() call. + + %TRUE if the last test subprocess got killed due to a timeout. + + + + + Respawns the test program to run only @test_path in a subprocess. +This can be used for a test case that might not return, or that +might abort. + +If @test_path is %NULL then the same test is re-run in a subprocess. +You can use g_test_subprocess() to determine whether the test is in +a subprocess or not. + +@test_path can also be the name of the parent test, followed by +"`/subprocess/`" and then a name for the specific subtest (or just +ending with "`/subprocess`" if the test only has one child test); +tests with names of this form will automatically be skipped in the +parent process. + +If @usec_timeout is non-0, the test subprocess is aborted and +considered failing if its run time exceeds it. + +The subprocess behavior can be configured with the +#GTestSubprocessFlags flags. + +You can use methods such as g_test_trap_assert_passed(), +g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to +check the results of the subprocess. (But note that +g_test_trap_assert_stdout() and g_test_trap_assert_stderr() +cannot be used if @test_flags specifies that the child should +inherit the parent stdout/stderr.) + +If your `main ()` needs to behave differently in +the subprocess, you can call g_test_subprocess() (after calling +g_test_init()) to see whether you are in a subprocess. + +The following example tests that calling +`my_object_new(1000000)` will abort with an error +message. + +|[<!-- language="C" --> + static void + test_create_large_object (void) + { + if (g_test_subprocess ()) + { + my_object_new (1000000); + return; + } + + // Reruns this same test in a subprocess + g_test_trap_subprocess (NULL, 0, 0); + g_test_trap_assert_failed (); + g_test_trap_assert_stderr ("*ERROR*too large*"); + } + + int + main (int argc, char **argv) + { + g_test_init (&argc, &argv, NULL); + + g_test_add_func ("/myobject/create_large_object", + test_create_large_object); + return g_test_run (); + } +]| + + + + + + Test to run in a subprocess + + + + Timeout for the subprocess test in micro seconds. + + + + Flags to modify subprocess behaviour. + + + + + + + + + + + Terminates the current thread. + +If another thread is waiting for us using g_thread_join() then the +waiting thread will be woken up and get @retval as the return value +of g_thread_join(). + +Calling g_thread_exit() with a parameter @retval is equivalent to +returning @retval from the function @func, as given to g_thread_new(). + +You must only call g_thread_exit() from a thread that you created +yourself with g_thread_new() or related APIs. You must not call +this function from a thread created with another threading library +or or from within a #GThreadPool. + + + + + + the return value of this thread + + + + + + This function will return the maximum @interval that a +thread will wait in the thread pool for new tasks before +being stopped. + +If this function returns 0, threads waiting in the thread +pool for new work are not stopped. + + the maximum @interval (milliseconds) to wait + for new tasks in the thread pool before stopping the + thread + + + + + Returns the maximal allowed number of unused threads. + + the maximal number of unused threads + + + + + Returns the number of currently unused threads. + + the number of currently unused threads + + + + + This function will set the maximum @interval that a thread +waiting in the pool for new tasks can be idle for before +being stopped. This function is similar to calling +g_thread_pool_stop_unused_threads() on a regular timeout, +except this is done on a per thread basis. + +By setting @interval to 0, idle threads will not be stopped. + +The default value is 15000 (15 seconds). + + + + + + the maximum @interval (in milliseconds) + a thread can be idle + + + + + + Sets the maximal number of unused threads to @max_threads. +If @max_threads is -1, no limit is imposed on the number +of unused threads. + +The default value is 2. + + + + + + maximal number of unused threads + + + + + + Stops all currently unused threads. This does not change the +maximal number of unused threads. This function can be used to +regularly stop all unused threads e.g. from g_timeout_add(). + + + + + + This function returns the #GThread corresponding to the +current thread. Note that this function does not increase +the reference count of the returned struct. + +This function will return a #GThread even for threads that +were not created by GLib (i.e. those created by other threading +APIs). This may be useful for thread identification purposes +(i.e. comparisons) but you must not use GLib functions (such +as g_thread_join()) on these threads. + + the #GThread representing the current thread + + + + + Causes the calling thread to voluntarily relinquish the CPU, so +that other threads can run. + +This function is often used as a method to make busy wait less evil. + + + + + + Converts a string containing an ISO 8601 encoded date and time +to a #GTimeVal and puts it into @time_. + +@iso_date must include year, month, day, hours, minutes, and +seconds. It can optionally include fractions of a second and a time +zone indicator. (In the absence of any time zone indication, the +timestamp is assumed to be in local time.) + + %TRUE if the conversion was successful. + + + + + an ISO 8601 encoded date string + + + + a #GTimeVal + + + + + + Sets a function to be called at regular intervals, with the default +priority, #G_PRIORITY_DEFAULT. The function is called repeatedly +until it returns %FALSE, at which point the timeout is automatically +destroyed and the function will not be called again. The first call +to the function will be at the end of the first @interval. + +Note that timeout functions may be delayed, due to the processing of other +event sources. Thus they should not be relied on for precise timing. +After each call to the timeout function, the time of the next +timeout is recalculated based on the current time and the given interval +(it does not try to 'catch up' time lost in delays). + +See [memory management of sources][mainloop-memory-management] for details +on how to handle the return value and memory management of @data. + +If you want to have a timer in the "seconds" range and do not care +about the exact time of the first call of the timer, use the +g_timeout_add_seconds() function; this function allows for more +optimizations and more efficient system power usage. + +This internally creates a main loop source using g_timeout_source_new() +and attaches it to the global #GMainContext using g_source_attach(), so +the callback will be invoked in whichever thread is running that main +context. You can do these steps manually if you need greater control or to +use a custom main context. + +The interval given is in terms of monotonic time, not wall clock +time. See g_get_monotonic_time(). + + the ID (greater than 0) of the event source. + + + + + the time between calls to the function, in milliseconds + (1/1000ths of a second) + + + + function to call + + + + data to pass to @function + + + + + + Sets a function to be called at regular intervals, with the given +priority. The function is called repeatedly until it returns +%FALSE, at which point the timeout is automatically destroyed and +the function will not be called again. The @notify function is +called when the timeout is destroyed. The first call to the +function will be at the end of the first @interval. + +Note that timeout functions may be delayed, due to the processing of other +event sources. Thus they should not be relied on for precise timing. +After each call to the timeout function, the time of the next +timeout is recalculated based on the current time and the given interval +(it does not try to 'catch up' time lost in delays). + +See [memory management of sources][mainloop-memory-management] for details +on how to handle the return value and memory management of @data. + +This internally creates a main loop source using g_timeout_source_new() +and attaches it to the global #GMainContext using g_source_attach(), so +the callback will be invoked in whichever thread is running that main +context. You can do these steps manually if you need greater control or to +use a custom main context. + +The interval given in terms of monotonic time, not wall clock time. +See g_get_monotonic_time(). + + the ID (greater than 0) of the event source. + + + + + the priority of the timeout source. Typically this will be in + the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + + + + the time between calls to the function, in milliseconds + (1/1000ths of a second) + + + + function to call + + + + data to pass to @function + + + + function to call when the timeout is removed, or %NULL + + + + + + Sets a function to be called at regular intervals with the default +priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until +it returns %FALSE, at which point the timeout is automatically destroyed +and the function will not be called again. + +This internally creates a main loop source using +g_timeout_source_new_seconds() and attaches it to the main loop context +using g_source_attach(). You can do these steps manually if you need +greater control. Also see g_timeout_add_seconds_full(). + +Note that the first call of the timer may not be precise for timeouts +of one second. If you need finer precision and have such a timeout, +you may want to use g_timeout_add() instead. + +See [memory management of sources][mainloop-memory-management] for details +on how to handle the return value and memory management of @data. + +The interval given is in terms of monotonic time, not wall clock +time. See g_get_monotonic_time(). + + the ID (greater than 0) of the event source. + + + + + the time between calls to the function, in seconds + + + + function to call + + + + data to pass to @function + + + + + + Sets a function to be called at regular intervals, with @priority. +The function is called repeatedly until it returns %FALSE, at which +point the timeout is automatically destroyed and the function will +not be called again. + +Unlike g_timeout_add(), this function operates at whole second granularity. +The initial starting point of the timer is determined by the implementation +and the implementation is expected to group multiple timers together so that +they fire all at the same time. +To allow this grouping, the @interval to the first timer is rounded +and can deviate up to one second from the specified interval. +Subsequent timer iterations will generally run at the specified interval. + +Note that timeout functions may be delayed, due to the processing of other +event sources. Thus they should not be relied on for precise timing. +After each call to the timeout function, the time of the next +timeout is recalculated based on the current time and the given @interval + +See [memory management of sources][mainloop-memory-management] for details +on how to handle the return value and memory management of @data. + +If you want timing more precise than whole seconds, use g_timeout_add() +instead. + +The grouping of timers to fire at the same time results in a more power +and CPU efficient behavior so if your timer is in multiples of seconds +and you don't require the first timer exactly one second from now, the +use of g_timeout_add_seconds() is preferred over g_timeout_add(). + +This internally creates a main loop source using +g_timeout_source_new_seconds() and attaches it to the main loop context +using g_source_attach(). You can do these steps manually if you need +greater control. + +The interval given is in terms of monotonic time, not wall clock +time. See g_get_monotonic_time(). + + the ID (greater than 0) of the event source. + + + + + the priority of the timeout source. Typically this will be in + the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + + + + the time between calls to the function, in seconds + + + + function to call + + + + data to pass to @function + + + + function to call when the timeout is removed, or %NULL + + + + + + Creates a new timeout source. + +The source will not initially be associated with any #GMainContext +and must be added to one with g_source_attach() before it will be +executed. + +The interval given is in terms of monotonic time, not wall clock +time. See g_get_monotonic_time(). + + the newly-created timeout source + + + + + the timeout interval in milliseconds. + + + + + + Creates a new timeout source. + +The source will not initially be associated with any #GMainContext +and must be added to one with g_source_attach() before it will be +executed. + +The scheduling granularity/accuracy of this timeout source will be +in seconds. + +The interval given in terms of monotonic time, not wall clock time. +See g_get_monotonic_time(). + + the newly-created timeout source + + + + + the timeout interval in seconds + + + + + + Returns the height of a #GTrashStack. + +Note that execution of this function is of O(N) complexity +where N denotes the number of items on the stack. + #GTrashStack is deprecated without replacement + + the height of the stack + + + + + a #GTrashStack + + + + + + Returns the element at the top of a #GTrashStack +which may be %NULL. + #GTrashStack is deprecated without replacement + + the element at the top of the stack + + + + + a #GTrashStack + + + + + + Pops a piece of memory off a #GTrashStack. + #GTrashStack is deprecated without replacement + + the element at the top of the stack + + + + + a #GTrashStack + + + + + + Pushes a piece of memory onto a #GTrashStack. + #GTrashStack is deprecated without replacement + + + + + + a #GTrashStack + + + + the piece of memory to push on the stack + + + + + + Attempts to allocate @n_bytes, and returns %NULL on failure. +Contrast with g_malloc(), which aborts the program on failure. + + the allocated memory, or %NULL. + + + + + number of bytes to allocate. + + + + + + Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on +failure. Contrast with g_malloc0(), which aborts the program on failure. + + the allocated memory, or %NULL + + + + + number of bytes to allocate + + + + + + This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, +but care is taken to detect possible overflow during multiplication. + + the allocated memory, or %NULL + + + + + the number of blocks to allocate + + + + the size of each block in bytes + + + + + + This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, +but care is taken to detect possible overflow during multiplication. + + the allocated memory, or %NULL. + + + + + the number of blocks to allocate + + + + the size of each block in bytes + + + + + + Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL +on failure. Contrast with g_realloc(), which aborts the program +on failure. + +If @mem is %NULL, behaves the same as g_try_malloc(). + + the allocated memory, or %NULL. + + + + + previously-allocated memory, or %NULL. + + + + number of bytes to allocate. + + + + + + This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, +but care is taken to detect possible overflow during multiplication. + + the allocated memory, or %NULL. + + + + + previously-allocated memory, or %NULL. + + + + the number of blocks to allocate + + + + the size of each block in bytes + + + + + + Convert a string from UCS-4 to UTF-16. A 0 character will be +added to the result after the converted text. + + a pointer to a newly allocated UTF-16 string. + This value must be freed with g_free(). If an error occurs, + %NULL will be returned and @error set. + + + + + a UCS-4 encoded string + + + + the maximum length (number of characters) of @str to use. + If @len < 0, then the string is nul-terminated. + + + + location to store number of + bytes read, or %NULL. If an error occurs then the index of the invalid + input is stored here. + + + + location to store number + of #gunichar2 written, or %NULL. The value stored here does not include + the trailing 0. + + + + + + Convert a string from a 32-bit fixed width representation as UCS-4. +to UTF-8. The result will be terminated with a 0 byte. + + a pointer to a newly allocated UTF-8 string. + This value must be freed with g_free(). If an error occurs, + %NULL will be returned and @error set. In that case, @items_read + will be set to the position of the first invalid input character. + + + + + a UCS-4 encoded string + + + + the maximum length (number of characters) of @str to use. + If @len < 0, then the string is nul-terminated. + + + + location to store number of + characters read, or %NULL. + + + + location to store number + of bytes written or %NULL. The value here stored does not include the + trailing 0 byte. + + + + + + Determines the break type of @c. @c should be a Unicode character +(to derive a character from UTF-8 encoded text, use +g_utf8_get_char()). The break type is used to find word and line +breaks ("text boundaries"), Pango implements the Unicode boundary +resolution algorithms and normally you would use a function such +as pango_break() instead of caring about break types yourself. + + the break type of @c + + + + + a Unicode character + + + + + + Determines the canonical combining class of a Unicode character. + + the combining class of the character + + + + + a Unicode character + + + + + + Performs a single composition step of the +Unicode canonical composition algorithm. + +This function includes algorithmic Hangul Jamo composition, +but it is not exactly the inverse of g_unichar_decompose(). +No composition can have either of @a or @b equal to zero. +To be precise, this function composes if and only if +there exists a Primary Composite P which is canonically +equivalent to the sequence <@a,@b>. See the Unicode +Standard for the definition of Primary Composite. + +If @a and @b do not compose a new character, @ch is set to zero. + +See +[UAX#15](http://unicode.org/reports/tr15/) +for details. + + %TRUE if the characters could be composed + + + + + a Unicode character + + + + a Unicode character + + + + return location for the composed character + + + + + + Performs a single decomposition step of the +Unicode canonical decomposition algorithm. + +This function does not include compatibility +decompositions. It does, however, include algorithmic +Hangul Jamo decomposition, as well as 'singleton' +decompositions which replace a character by a single +other character. In the case of singletons *@b will +be set to zero. + +If @ch is not decomposable, *@a is set to @ch and *@b +is set to zero. + +Note that the way Unicode decomposition pairs are +defined, it is guaranteed that @b would not decompose +further, but @a may itself decompose. To get the full +canonical decomposition for @ch, one would need to +recursively call this function on @a. Or use +g_unichar_fully_decompose(). + +See +[UAX#15](http://unicode.org/reports/tr15/) +for details. + + %TRUE if the character could be decomposed + + + + + a Unicode character + + + + return location for the first component of @ch + + + + return location for the second component of @ch + + + + + + Determines the numeric value of a character as a decimal +digit. + + If @c is a decimal digit (according to +g_unichar_isdigit()), its numeric value. Otherwise, -1. + + + + + a Unicode character + + + + + + Computes the canonical or compatibility decomposition of a +Unicode character. For compatibility decomposition, +pass %TRUE for @compat; for canonical decomposition +pass %FALSE for @compat. + +The decomposed sequence is placed in @result. Only up to +@result_len characters are written into @result. The length +of the full decomposition (irrespective of @result_len) is +returned by the function. For canonical decomposition, +currently all decompositions are of length at most 4, but +this may change in the future (very unlikely though). +At any rate, Unicode does guarantee that a buffer of length +18 is always enough for both compatibility and canonical +decompositions, so that is the size recommended. This is provided +as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH. + +See +[UAX#15](http://unicode.org/reports/tr15/) +for details. + + the length of the full decomposition. + + + + + a Unicode character. + + + + whether perform canonical or compatibility decomposition + + + + location to store decomposed result, or %NULL + + + + length of @result + + + + + + In Unicode, some characters are "mirrored". This means that their +images are mirrored horizontally in text that is laid out from right +to left. For instance, "(" would become its mirror image, ")", in +right-to-left text. + +If @ch has the Unicode mirrored property and there is another unicode +character that typically has a glyph that is the mirror image of @ch's +glyph and @mirrored_ch is set, it puts that character in the address +pointed to by @mirrored_ch. Otherwise the original character is put. + + %TRUE if @ch has a mirrored character, %FALSE otherwise + + + + + a Unicode character + + + + location to store the mirrored character + + + + + + Looks up the #GUnicodeScript for a particular character (as defined +by Unicode Standard Annex \#24). No check is made for @ch being a +valid Unicode character; if you pass in invalid character, the +result is undefined. + +This function is equivalent to pango_script_for_unichar() and the +two are interchangeable. + + the #GUnicodeScript for the character. + + + + + a Unicode character + + + + + + Determines whether a character is alphanumeric. +Given some UTF-8 text, obtain a character value +with g_utf8_get_char(). + + %TRUE if @c is an alphanumeric character + + + + + a Unicode character + + + + + + Determines whether a character is alphabetic (i.e. a letter). +Given some UTF-8 text, obtain a character value with +g_utf8_get_char(). + + %TRUE if @c is an alphabetic character + + + + + a Unicode character + + + + + + Determines whether a character is a control character. +Given some UTF-8 text, obtain a character value with +g_utf8_get_char(). + + %TRUE if @c is a control character + + + + + a Unicode character + + + + + + Determines if a given character is assigned in the Unicode +standard. + + %TRUE if the character has an assigned value + + + + + a Unicode character + + + + + + Determines whether a character is numeric (i.e. a digit). This +covers ASCII 0-9 and also digits in other languages/scripts. Given +some UTF-8 text, obtain a character value with g_utf8_get_char(). + + %TRUE if @c is a digit + + + + + a Unicode character + + + + + + Determines whether a character is printable and not a space +(returns %FALSE for control characters, format characters, and +spaces). g_unichar_isprint() is similar, but returns %TRUE for +spaces. Given some UTF-8 text, obtain a character value with +g_utf8_get_char(). + + %TRUE if @c is printable unless it's a space + + + + + a Unicode character + + + + + + Determines whether a character is a lowercase letter. +Given some UTF-8 text, obtain a character value with +g_utf8_get_char(). + + %TRUE if @c is a lowercase letter + + + + + a Unicode character + + + + + + Determines whether a character is a mark (non-spacing mark, +combining mark, or enclosing mark in Unicode speak). +Given some UTF-8 text, obtain a character value +with g_utf8_get_char(). + +Note: in most cases where isalpha characters are allowed, +ismark characters should be allowed to as they are essential +for writing most European languages as well as many non-Latin +scripts. + + %TRUE if @c is a mark character + + + + + a Unicode character + + + + + + Determines whether a character is printable. +Unlike g_unichar_isgraph(), returns %TRUE for spaces. +Given some UTF-8 text, obtain a character value with +g_utf8_get_char(). + + %TRUE if @c is printable + + + + + a Unicode character + + + + + + Determines whether a character is punctuation or a symbol. +Given some UTF-8 text, obtain a character value with +g_utf8_get_char(). + + %TRUE if @c is a punctuation or symbol character + + + + + a Unicode character + + + + + + Determines whether a character is a space, tab, or line separator +(newline, carriage return, etc.). Given some UTF-8 text, obtain a +character value with g_utf8_get_char(). + +(Note: don't use this to do word breaking; you have to use +Pango or equivalent to get word breaking right, the algorithm +is fairly complex.) + + %TRUE if @c is a space character + + + + + a Unicode character + + + + + + Determines if a character is titlecase. Some characters in +Unicode which are composites, such as the DZ digraph +have three case variants instead of just two. The titlecase +form is used at the beginning of a word where only the +first letter is capitalized. The titlecase form of the DZ +digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z. + + %TRUE if the character is titlecase + + + + + a Unicode character + + + + + + Determines if a character is uppercase. + + %TRUE if @c is an uppercase character + + + + + a Unicode character + + + + + + Determines if a character is typically rendered in a double-width +cell. + + %TRUE if the character is wide + + + + + a Unicode character + + + + + + Determines if a character is typically rendered in a double-width +cell under legacy East Asian locales. If a character is wide according to +g_unichar_iswide(), then it is also reported wide with this function, but +the converse is not necessarily true. See the +[Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/) +for details. + +If a character passes the g_unichar_iswide() test then it will also pass +this test, but not the other way around. Note that some characters may +pass both this test and g_unichar_iszerowidth(). + + %TRUE if the character is wide in legacy East Asian locales + + + + + a Unicode character + + + + + + Determines if a character is a hexidecimal digit. + + %TRUE if the character is a hexadecimal digit + + + + + a Unicode character. + + + + + + Determines if a given character typically takes zero width when rendered. +The return value is %TRUE for all non-spacing and enclosing marks +(e.g., combining accents), format characters, zero-width +space, but not U+00AD SOFT HYPHEN. + +A typical use of this function is with one of g_unichar_iswide() or +g_unichar_iswide_cjk() to determine the number of cells a string occupies +when displayed on a grid display (terminals). However, note that not all +terminals support zero-width rendering of zero-width marks. + + %TRUE if the character has zero width + + + + + a Unicode character + + + + + + Converts a single character to UTF-8. + + number of bytes written + + + + + a Unicode character code + + + + output buffer, must have at + least 6 bytes of space. If %NULL, the length will be computed and + returned and nothing will be written to @outbuf. + + + + + + Converts a character to lower case. + + the result of converting @c to lower case. + If @c is not an upperlower or titlecase character, + or has no lowercase equivalent @c is returned unchanged. + + + + + a Unicode character. + + + + + + Converts a character to the titlecase. + + the result of converting @c to titlecase. + If @c is not an uppercase or lowercase character, + @c is returned unchanged. + + + + + a Unicode character + + + + + + Converts a character to uppercase. + + the result of converting @c to uppercase. + If @c is not an lowercase or titlecase character, + or has no upper case equivalent @c is returned unchanged. + + + + + a Unicode character + + + + + + Classifies a Unicode character by type. + + the type of the character. + + + + + a Unicode character + + + + + + Checks whether @ch is a valid Unicode character. Some possible +integer values of @ch will not be valid. 0 is considered a valid +character, though it's normally a string terminator. + + %TRUE if @ch is a valid Unicode character + + + + + a Unicode character + + + + + + Determines the numeric value of a character as a hexidecimal +digit. + + If @c is a hex digit (according to +g_unichar_isxdigit()), its numeric value. Otherwise, -1. + + + + + a Unicode character + + + + + + Computes the canonical decomposition of a Unicode character. + Use the more flexible g_unichar_fully_decompose() + instead. + + a newly allocated string of Unicode characters. + @result_len is set to the resulting length of the string. + + + + + a Unicode character. + + + + location to store the length of the return value. + + + + + + Computes the canonical ordering of a string in-place. +This rearranges decomposed characters in the string +according to their combining classes. See the Unicode +manual for more information. + + + + + + a UCS-4 encoded string. + + + + the maximum length of @string to use. + + + + + + Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter +codes to scripts. For example, the code for Arabic is 'Arab'. +This function accepts four letter codes encoded as a @guint32 in a +big-endian fashion. That is, the code expected for Arabic is +0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). + +See +[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) +for details. + + the Unicode script for @iso15924, or + of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and + %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown. + + + + + a Unicode script + + + + + + Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter +codes to scripts. For example, the code for Arabic is 'Arab'. The +four letter codes are encoded as a @guint32 by this function in a +big-endian fashion. That is, the code returned for Arabic is +0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). + +See +[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) +for details. + + the ISO 15924 code for @script, encoded as an integer, + of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or + ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood. + + + + + a Unicode script + + + + + + + + + + + Sets a function to be called when the IO condition, as specified by +@condition becomes true for @fd. + +@function will be called when the specified IO condition becomes +%TRUE. The function is expected to clear whatever event caused the +IO condition to become true and return %TRUE in order to be notified +when it happens again. If @function returns %FALSE then the watch +will be cancelled. + +The return value of this function can be passed to g_source_remove() +to cancel the watch at any time that it exists. + +The source will never close the fd -- you must do it yourself. + + the ID (greater than 0) of the event source + + + + + a file descriptor + + + + IO conditions to watch for on @fd + + + + a #GPollFDFunc + + + + data to pass to @function + + + + + + Sets a function to be called when the IO condition, as specified by +@condition becomes true for @fd. + +This is the same as g_unix_fd_add(), except that it allows you to +specify a non-default priority and a provide a #GDestroyNotify for +@user_data. + + the ID (greater than 0) of the event source + + + + + the priority of the source + + + + a file descriptor + + + + IO conditions to watch for on @fd + + + + a #GUnixFDSourceFunc + + + + data to pass to @function + + + + function to call when the idle is removed, or %NULL + + + + + + Creates a #GSource to watch for a particular IO condition on a file +descriptor. + +The source will never close the fd -- you must do it yourself. + + the newly created #GSource + + + + + a file descriptor + + + + IO conditions to watch for on @fd + + + + + + Similar to the UNIX pipe() call, but on modern systems like Linux +uses the pipe2() system call, which atomically creates a pipe with +the configured flags. The only supported flag currently is +%FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that +must still be done separately with fcntl(). + +This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if +for fcntl(); these are different on Linux/glibc. + + %TRUE on success, %FALSE if not (and errno will be set). + + + + + Array of two integers + + + + Bitfield of file descriptor flags, as for fcntl() + + + + + + Control the non-blocking state of the given file descriptor, +according to @nonblock. On most systems this uses %O_NONBLOCK, but +on some older ones may use %O_NDELAY. + + %TRUE if successful + + + + + A file descriptor + + + + If %TRUE, set the descriptor to be non-blocking + + + + + + A convenience function for g_unix_signal_source_new(), which +attaches to the default #GMainContext. You can remove the watch +using g_source_remove(). + + An ID (greater than 0) for the event source + + + + + Signal number + + + + Callback + + + + Data for @handler + + + + + + A convenience function for g_unix_signal_source_new(), which +attaches to the default #GMainContext. You can remove the watch +using g_source_remove(). + + An ID (greater than 0) for the event source + + + + + the priority of the signal source. Typically this will be in + the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + + + + Signal number + + + + Callback + + + + Data for @handler + + + + #GDestroyNotify for @handler + + + + + + Create a #GSource that will be dispatched upon delivery of the UNIX +signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`, +`SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2` +were added. + +Note that unlike the UNIX default, all sources which have created a +watch will be dispatched, regardless of which underlying thread +invoked g_unix_signal_source_new(). + +For example, an effective use of this function is to handle `SIGTERM` +cleanly; flushing any outstanding files, and then calling +g_main_loop_quit (). It is not safe to do any of this a regular +UNIX signal handler; your handler may be invoked while malloc() or +another library function is running, causing reentrancy if you +attempt to use it from the handler. None of the GLib/GObject API +is safe against this kind of reentrancy. + +The interaction of this source when combined with native UNIX +functions like sigprocmask() is not defined. + +The source will not initially be associated with any #GMainContext +and must be added to one with g_source_attach() before it will be +executed. + + A newly created #GSource + + + + + A signal number + + + + + + A wrapper for the POSIX unlink() function. The unlink() function +deletes a name from the filesystem. If this was the last link to the +file and no processes have it opened, the diskspace occupied by the +file is freed. + +See your C library manual for more details about unlink(). Note +that on Windows, it is in general not possible to delete files that +are open to some process, or mapped into memory. + + 0 if the name was successfully deleted, -1 if an error + occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + + + Removes an environment variable from the environment. + +Note that on some systems, when variables are overwritten, the +memory used for the previous variables and its value isn't reclaimed. + +You should be mindful of the fact that environment variable handling +in UNIX is not thread-safe, and your program may crash if one thread +calls g_unsetenv() while another thread is calling getenv(). (And note +that many functions, such as gettext(), call getenv() internally.) This +function is only safe to use at the very start of your program, before +creating any other threads (or creating objects that create worker +threads of their own). + +If you need to set up the environment for a child process, you can +use g_get_environ() to get an environment array, modify that with +g_environ_setenv() and g_environ_unsetenv(), and then pass that +array directly to execvpe(), g_spawn_async(), or the like. + + + + + + the environment variable to remove, must not contain '=' + + + + + + Escapes a string for use in a URI. + +Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical +characters plus dash, dot, underscore and tilde) are escaped. +But if you specify characters in @reserved_chars_allowed they are not +escaped. This is useful for the "reserved" characters in the URI +specification, since those are allowed unescaped in some portions of +a URI. + + an escaped version of @unescaped. The returned string should be +freed when no longer needed. + + + + + the unescaped input string. + + + + a string of reserved characters that + are allowed to be used, or %NULL. + + + + %TRUE if the result can include UTF-8 characters. + + + + + + Splits an URI list conforming to the text/uri-list +mime type defined in RFC 2483 into individual URIs, +discarding any comments. The URIs are not validated. + + a newly allocated %NULL-terminated list + of strings holding the individual URIs. The array should be freed + with g_strfreev(). + + + + + + + an URI list + + + + + + Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as: +|[ +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +]| +Common schemes include "file", "http", "svn+ssh", etc. + + The "Scheme" component of the URI, or %NULL on error. +The returned string should be freed when no longer needed. + + + + + a valid URI. + + + + + + Unescapes a segment of an escaped string. + +If any of the characters in @illegal_characters or the character zero appears +as an escaped character in @escaped_string then that is an error and %NULL +will be returned. This is useful it you want to avoid for instance having a +slash being expanded in an escaped path element, which might confuse pathname +handling. + + an unescaped version of @escaped_string or %NULL on error. +The returned string should be freed when no longer needed. As a +special case if %NULL is given for @escaped_string, this function +will return %NULL. + + + + + A string, may be %NULL + + + + Pointer to end of @escaped_string, may be %NULL + + + + An optional string of illegal characters not to be allowed, may be %NULL + + + + + + Unescapes a whole escaped string. + +If any of the characters in @illegal_characters or the character zero appears +as an escaped character in @escaped_string then that is an error and %NULL +will be returned. This is useful it you want to avoid for instance having a +slash being expanded in an escaped path element, which might confuse pathname +handling. + + an unescaped version of @escaped_string. The returned string +should be freed when no longer needed. + + + + + an escaped string to be unescaped. + + + + a string of illegal characters not to be + allowed, or %NULL. + + + + + + Pauses the current thread for the given number of microseconds. + +There are 1 million microseconds per second (represented by the +#G_USEC_PER_SEC macro). g_usleep() may have limited precision, +depending on hardware and operating system; don't rely on the exact +length of the sleep. + + + + + + number of microseconds to pause + + + + + + Convert a string from UTF-16 to UCS-4. The result will be +nul-terminated. + + a pointer to a newly allocated UCS-4 string. + This value must be freed with g_free(). If an error occurs, + %NULL will be returned and @error set. + + + + + a UTF-16 encoded string + + + + the maximum length (number of #gunichar2) of @str to use. + If @len < 0, then the string is nul-terminated. + + + + location to store number of + words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will + be returned in case @str contains a trailing partial character. If + an error occurs then the index of the invalid input is stored here. + + + + location to store number + of characters written, or %NULL. The value stored here does not include + the trailing 0 character. + + + + + + Convert a string from UTF-16 to UTF-8. The result will be +terminated with a 0 byte. + +Note that the input is expected to be already in native endianness, +an initial byte-order-mark character is not handled specially. +g_convert() can be used to convert a byte buffer of UTF-16 data of +ambiguous endianess. + +Further note that this function does not validate the result +string; it may e.g. include embedded NUL characters. The only +validation done by this function is to ensure that the input can +be correctly interpreted as UTF-16, i.e. it doesn't contain +things unpaired surrogates. + + a pointer to a newly allocated UTF-8 string. + This value must be freed with g_free(). If an error occurs, + %NULL will be returned and @error set. + + + + + a UTF-16 encoded string + + + + the maximum length (number of #gunichar2) of @str to use. + If @len < 0, then the string is nul-terminated. + + + + location to store number of + words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will + be returned in case @str contains a trailing partial character. If + an error occurs then the index of the invalid input is stored here. + + + + location to store number + of bytes written, or %NULL. The value stored here does not include the + trailing 0 byte. + + + + + + Converts a string into a form that is independent of case. The +result will not correspond to any particular case, but can be +compared for equality or ordered with the results of calling +g_utf8_casefold() on other strings. + +Note that calling g_utf8_casefold() followed by g_utf8_collate() is +only an approximation to the correct linguistic case insensitive +ordering, though it is a fairly good one. Getting this exactly +right would require a more sophisticated collation function that +takes case sensitivity into account. GLib does not currently +provide such a function. + + a newly allocated string, that is a + case independent form of @str. + + + + + a UTF-8 encoded string + + + + length of @str, in bytes, or -1 if @str is nul-terminated. + + + + + + Compares two strings for ordering using the linguistically +correct rules for the [current locale][setlocale]. +When sorting a large number of strings, it will be significantly +faster to obtain collation keys with g_utf8_collate_key() and +compare the keys with strcmp() when sorting instead of sorting +the original strings. + + < 0 if @str1 compares before @str2, + 0 if they compare equal, > 0 if @str1 compares after @str2. + + + + + a UTF-8 encoded string + + + + a UTF-8 encoded string + + + + + + Converts a string into a collation key that can be compared +with other collation keys produced by the same function using +strcmp(). + +The results of comparing the collation keys of two strings +with strcmp() will always be the same as comparing the two +original keys with g_utf8_collate(). + +Note that this function depends on the [current locale][setlocale]. + + a newly allocated string. This string should + be freed with g_free() when you are done with it. + + + + + a UTF-8 encoded string. + + + + length of @str, in bytes, or -1 if @str is nul-terminated. + + + + + + Converts a string into a collation key that can be compared +with other collation keys produced by the same function using strcmp(). + +In order to sort filenames correctly, this function treats the dot '.' +as a special case. Most dictionary orderings seem to consider it +insignificant, thus producing the ordering "event.c" "eventgenerator.c" +"event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we +would like to treat numbers intelligently so that "file1" "file10" "file5" +is sorted as "file1" "file5" "file10". + +Note that this function depends on the [current locale][setlocale]. + + a newly allocated string. This string should + be freed with g_free() when you are done with it. + + + + + a UTF-8 encoded string. + + + + length of @str, in bytes, or -1 if @str is nul-terminated. + + + + + + Finds the start of the next UTF-8 character in the string after @p. + +@p does not have to be at the beginning of a UTF-8 character. No check +is made to see if the character found is actually valid other than +it starts with an appropriate byte. + + a pointer to the found character or %NULL + + + + + a pointer to a position within a UTF-8 encoded string + + + + a pointer to the byte following the end of the string, + or %NULL to indicate that the string is nul-terminated + + + + + + Given a position @p with a UTF-8 encoded string @str, find the start +of the previous UTF-8 character starting before @p. Returns %NULL if no +UTF-8 characters are present in @str before @p. + +@p does not have to be at the beginning of a UTF-8 character. No check +is made to see if the character found is actually valid other than +it starts with an appropriate byte. + + a pointer to the found character or %NULL. + + + + + pointer to the beginning of a UTF-8 encoded string + + + + pointer to some position within @str + + + + + + Converts a sequence of bytes encoded as UTF-8 to a Unicode character. + +If @p does not point to a valid UTF-8 encoded character, results +are undefined. If you are not sure that the bytes are complete +valid Unicode characters, you should use g_utf8_get_char_validated() +instead. + + the resulting character + + + + + a pointer to Unicode character encoded as UTF-8 + + + + + + Convert a sequence of bytes encoded as UTF-8 to a Unicode character. +This function checks for incomplete characters, for invalid characters +such as characters that are out of the range of Unicode, and for +overlong encodings of valid characters. + + the resulting character. If @p points to a partial + sequence at the end of a string that could begin a valid + character (or if @max_len is zero), returns (gunichar)-2; + otherwise, if @p does not point to a valid UTF-8 encoded + Unicode character, returns (gunichar)-1. + + + + + a pointer to Unicode character encoded as UTF-8 + + + + the maximum number of bytes to read, or -1, for no maximum or + if @p is nul-terminated + + + + + + Converts a string into canonical form, standardizing +such issues as whether a character with an accent +is represented as a base character and combining +accent or as a single precomposed character. The +string has to be valid UTF-8, otherwise %NULL is +returned. You should generally call g_utf8_normalize() +before comparing two Unicode strings. + +The normalization mode %G_NORMALIZE_DEFAULT only +standardizes differences that do not affect the +text content, such as the above-mentioned accent +representation. %G_NORMALIZE_ALL also standardizes +the "compatibility" characters in Unicode, such +as SUPERSCRIPT THREE to the standard forms +(in this case DIGIT THREE). Formatting information +may be lost but for most text operations such +characters should be considered the same. + +%G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE +are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL, +but returned a result with composed forms rather +than a maximally decomposed form. This is often +useful if you intend to convert the string to +a legacy encoding or pass it to a system with +less capable Unicode handling. + + a newly allocated string, that is the + normalized form of @str, or %NULL if @str is not + valid UTF-8. + + + + + a UTF-8 encoded string. + + + + length of @str, in bytes, or -1 if @str is nul-terminated. + + + + the type of normalization to perform. + + + + + + Converts from an integer character offset to a pointer to a position +within the string. + +Since 2.10, this function allows to pass a negative @offset to +step backwards. It is usually worth stepping backwards from the end +instead of forwards if @offset is in the last fourth of the string, +since moving forward is about 3 times faster than moving backward. + +Note that this function doesn't abort when reaching the end of @str. +Therefore you should be sure that @offset is within string boundaries +before calling that function. Call g_utf8_strlen() when unsure. +This limitation exists as this function is called frequently during +text rendering and therefore has to be as fast as possible. + + the resulting pointer + + + + + a UTF-8 encoded string + + + + a character offset within @str + + + + + + Converts from a pointer to position within a string to a integer +character offset. + +Since 2.10, this function allows @pos to be before @str, and returns +a negative offset in this case. + + the resulting character offset + + + + + a UTF-8 encoded string + + + + a pointer to a position within @str + + + + + + Finds the previous UTF-8 character in the string before @p. + +@p does not have to be at the beginning of a UTF-8 character. No check +is made to see if the character found is actually valid other than +it starts with an appropriate byte. If @p might be the first +character of the string, you must use g_utf8_find_prev_char() instead. + + a pointer to the found character + + + + + a pointer to a position within a UTF-8 encoded string + + + + + + Finds the leftmost occurrence of the given Unicode character +in a UTF-8 encoded string, while limiting the search to @len bytes. +If @len is -1, allow unbounded search. + + %NULL if the string does not contain the character, + otherwise, a pointer to the start of the leftmost occurrence + of the character in the string. + + + + + a nul-terminated UTF-8 encoded string + + + + the maximum length of @p + + + + a Unicode character + + + + + + Converts all Unicode characters in the string that have a case +to lowercase. The exact manner that this is done depends +on the current locale, and may result in the number of +characters in the string changing. + + a newly allocated string, with all characters + converted to lowercase. + + + + + a UTF-8 encoded string + + + + length of @str, in bytes, or -1 if @str is nul-terminated. + + + + + + Computes the length of the string in characters, not including +the terminating nul character. If the @max'th byte falls in the +middle of a character, the last (partial) character is not counted. + + the length of the string in characters + + + + + pointer to the start of a UTF-8 encoded string + + + + the maximum number of bytes to examine. If @max + is less than 0, then the string is assumed to be + nul-terminated. If @max is 0, @p will not be examined and + may be %NULL. If @max is greater than 0, up to @max + bytes are examined + + + + + + Like the standard C strncpy() function, but copies a given number +of characters instead of a given number of bytes. The @src string +must be valid UTF-8 encoded text. (Use g_utf8_validate() on all +text before trying to use UTF-8 utility functions with it.) + + @dest + + + + + buffer to fill with characters from @src + + + + UTF-8 encoded string + + + + character count + + + + + + Find the rightmost occurrence of the given Unicode character +in a UTF-8 encoded string, while limiting the search to @len bytes. +If @len is -1, allow unbounded search. + + %NULL if the string does not contain the character, + otherwise, a pointer to the start of the rightmost occurrence + of the character in the string. + + + + + a nul-terminated UTF-8 encoded string + + + + the maximum length of @p + + + + a Unicode character + + + + + + Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. +(Use g_utf8_validate() on all text before trying to use UTF-8 +utility functions with it.) + +This function is intended for programmatic uses of reversed strings. +It pays no attention to decomposed characters, combining marks, byte +order marks, directional indicators (LRM, LRO, etc) and similar +characters which might need special handling when reversing a string +for display purposes. + +Note that unlike g_strreverse(), this function returns +newly-allocated memory, which should be freed with g_free() when +no longer needed. + + a newly-allocated string which is the reverse of @str + + + + + a UTF-8 encoded string + + + + the maximum length of @str to use, in bytes. If @len < 0, + then the string is nul-terminated. + + + + + + Converts all Unicode characters in the string that have a case +to uppercase. The exact manner that this is done depends +on the current locale, and may result in the number of +characters in the string increasing. (For instance, the +German ess-zet will be changed to SS.) + + a newly allocated string, with all characters + converted to uppercase. + + + + + a UTF-8 encoded string + + + + length of @str, in bytes, or -1 if @str is nul-terminated. + + + + + + Copies a substring out of a UTF-8 encoded string. +The substring will contain @end_pos - @start_pos characters. + + a newly allocated copy of the requested + substring. Free with g_free() when no longer needed. + + + + + a UTF-8 encoded string + + + + a character offset within @str + + + + another character offset within @str + + + + + + Convert a string from UTF-8 to a 32-bit fixed width +representation as UCS-4. A trailing 0 character will be added to the +string after the converted text. + + a pointer to a newly allocated UCS-4 string. + This value must be freed with g_free(). If an error occurs, + %NULL will be returned and @error set. + + + + + a UTF-8 encoded string + + + + the maximum length of @str to use, in bytes. If @len < 0, + then the string is nul-terminated. + + + + location to store number of + bytes read, or %NULL. + If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + returned in case @str contains a trailing partial + character. If an error occurs then the index of the + invalid input is stored here. + + + + location to store number + of characters written or %NULL. The value here stored does not include + the trailing 0 character. + + + + + + Convert a string from UTF-8 to a 32-bit fixed width +representation as UCS-4, assuming valid UTF-8 input. +This function is roughly twice as fast as g_utf8_to_ucs4() +but does no error checking on the input. A trailing 0 character +will be added to the string after the converted text. + + a pointer to a newly allocated UCS-4 string. + This value must be freed with g_free(). + + + + + a UTF-8 encoded string + + + + the maximum length of @str to use, in bytes. If @len < 0, + then the string is nul-terminated. + + + + location to store the + number of characters in the result, or %NULL. + + + + + + Convert a string from UTF-8 to UTF-16. A 0 character will be +added to the result after the converted text. + + a pointer to a newly allocated UTF-16 string. + This value must be freed with g_free(). If an error occurs, + %NULL will be returned and @error set. + + + + + a UTF-8 encoded string + + + + the maximum length (number of bytes) of @str to use. + If @len < 0, then the string is nul-terminated. + + + + location to store number of + bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will + be returned in case @str contains a trailing partial character. If + an error occurs then the index of the invalid input is stored here. + + + + location to store number + of #gunichar2 written, or %NULL. The value stored here does not include + the trailing 0. + + + + + + Validates UTF-8 encoded text. @str is the text to validate; +if @str is nul-terminated, then @max_len can be -1, otherwise +@max_len should be the number of bytes to validate. +If @end is non-%NULL, then the end of the valid range +will be stored there (i.e. the start of the first invalid +character if some bytes were invalid, or the end of the text +being validated otherwise). + +Note that g_utf8_validate() returns %FALSE if @max_len is +positive and any of the @max_len bytes are nul. + +Returns %TRUE if all of @str was valid. Many GLib and GTK+ +routines require valid UTF-8 as input; so data read from a file +or the network should be checked with g_utf8_validate() before +doing anything else with it. + + %TRUE if the text was valid UTF-8 + + + + + a pointer to character data + + + + + + max bytes to validate, or -1 to go until NUL + + + + return location for end of valid data + + + + + + + + + + + Determines if a given string is a valid D-Bus object path. You +should ensure that a string is a valid D-Bus object path before +passing it to g_variant_new_object_path(). + +A valid object path starts with '/' followed by zero or more +sequences of characters separated by '/' characters. Each sequence +must contain only the characters "[A-Z][a-z][0-9]_". No sequence +(including the one following the final '/' character) may be empty. + + %TRUE if @string is a D-Bus object path + + + + + a normal C nul-terminated string + + + + + + Determines if a given string is a valid D-Bus type signature. You +should ensure that a string is a valid D-Bus type signature before +passing it to g_variant_new_signature(). + +D-Bus type signatures consist of zero or more definite #GVariantType +strings in sequence. + + %TRUE if @string is a D-Bus type signature + + + + + a normal C nul-terminated string + + + + + + Parses a #GVariant from a text representation. + +A single #GVariant is parsed from the content of @text. + +The format is described [here][gvariant-text]. + +The memory at @limit will never be accessed and the parser behaves as +if the character at @limit is the nul terminator. This has the +effect of bounding @text. + +If @endptr is non-%NULL then @text is permitted to contain data +following the value that this function parses and @endptr will be +updated to point to the first character past the end of the text +parsed by this function. If @endptr is %NULL and there is extra data +then an error is returned. + +If @type is non-%NULL then the value will be parsed to have that +type. This may result in additional parse errors (in the case that +the parsed value doesn't fit the type) but may also result in fewer +errors (in the case that the type would have been ambiguous, such as +with empty arrays). + +In the event that the parsing is successful, the resulting #GVariant +is returned. It is never floating, and must be freed with +g_variant_unref(). + +In case of any error, %NULL will be returned. If @error is non-%NULL +then it will be set to reflect the error that occurred. + +Officially, the language understood by the parser is "any string +produced by g_variant_print()". + + a non-floating reference to a #GVariant, or %NULL + + + + + a #GVariantType, or %NULL + + + + a string containing a GVariant in text form + + + + a pointer to the end of @text, or %NULL + + + + a location to store the end pointer, or %NULL + + + + + + Pretty-prints a message showing the context of a #GVariant parse +error within the string for which parsing was attempted. + +The resulting string is suitable for output to the console or other +monospace media where newlines are treated in the usual way. + +The message will typically look something like one of the following: + +|[ +unterminated string constant: + (1, 2, 3, 'abc + ^^^^ +]| + +or + +|[ +unable to find a common type: + [1, 2, 3, 'str'] + ^ ^^^^^ +]| + +The format of the message may change in a future version. + +@error must have come from a failed attempt to g_variant_parse() and +@source_str must be exactly the same string that caused the error. +If @source_str was not nul-terminated when you passed it to +g_variant_parse() then you must add nul termination before using this +function. + + the printed message + + + + + a #GError from the #GVariantParseError domain + + + + the string that was given to the parser + + + + + + + + + + + Same as g_variant_error_quark(). + Use g_variant_parse_error_quark() instead. + + + + + + + + + + + + + + + + Checks if @type_string is a valid GVariant type string. This call is +equivalent to calling g_variant_type_string_scan() and confirming +that the following character is a nul terminator. + + %TRUE if @type_string is exactly one valid type string + +Since 2.24 + + + + + a pointer to any string + + + + + + Scan for a single complete and valid GVariant type string in @string. +The memory pointed to by @limit (or bytes beyond it) is never +accessed. + +If a valid type string is found, @endptr is updated to point to the +first character past the end of the string that was found and %TRUE +is returned. + +If there is no valid type string starting at @string, or if the type +string does not end before @limit then %FALSE is returned. + +For the simple case of checking if a string is a valid type string, +see g_variant_type_string_is_valid(). + + %TRUE if a valid type string was found + + + + + a pointer to any string + + + + the end of @string, or %NULL + + + + location to store the end pointer, or %NULL + + + + + + An implementation of the GNU vasprintf() function which supports +positional parameters, as specified in the Single Unix Specification. +This function is similar to g_vsprintf(), except that it allocates a +string to hold the output, instead of putting the output in a buffer +you allocate in advance. + + the number of bytes printed. + + + + + the return location for the newly-allocated string. + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + the list of arguments to insert in the output. + + + + + + An implementation of the standard fprintf() function which supports +positional parameters, as specified in the Single Unix Specification. + + the number of bytes printed. + + + + + the stream to write to. + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + the list of arguments to insert in the output. + + + + + + An implementation of the standard vprintf() function which supports +positional parameters, as specified in the Single Unix Specification. + + the number of bytes printed. + + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + the list of arguments to insert in the output. + + + + + + A safer form of the standard vsprintf() function. The output is guaranteed +to not exceed @n characters (including the terminating nul character), so +it is easy to ensure that a buffer overflow cannot occur. + +See also g_strdup_vprintf(). + +In versions of GLib prior to 1.2.3, this function may return -1 if the +output was truncated, and the truncated string may not be nul-terminated. +In versions prior to 1.3.12, this function returns the length of the output +string. + +The return value of g_vsnprintf() conforms to the vsnprintf() function +as standardized in ISO C99. Note that this is different from traditional +vsnprintf(), which returns the length of the output string. + +The format string may contain positional parameters, as specified in +the Single Unix Specification. + + the number of bytes which would be produced if the buffer + was large enough. + + + + + the buffer to hold the output. + + + + the maximum number of bytes to produce (including the + terminating nul character). + + + + a standard printf() format string, but notice + string precision pitfalls][string-precision] + + + + the list of arguments to insert in the output. + + + + + + An implementation of the standard vsprintf() function which supports +positional parameters, as specified in the Single Unix Specification. + + the number of bytes printed. + + + + + the buffer to hold the output. + + + + a standard printf() format string, but notice + [string precision pitfalls][string-precision] + + + + the list of arguments to insert in the output. + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/gir-files/GModule-2.0.gir b/gir-files/GModule-2.0.gir new file mode 100644 index 000000000..7bb974952 --- /dev/null +++ b/gir-files/GModule-2.0.gir @@ -0,0 +1,277 @@ + + + + + + + + + The #GModule struct is an opaque data structure to represent a +[dynamically-loaded module][glib-Dynamic-Loading-of-Modules]. +It should only be accessed via the following functions. + + Closes a module. + + %TRUE on success + + + + + a #GModule to close + + + + + + Ensures that a module will never be unloaded. +Any future g_module_close() calls on the module will be ignored. + + + + + + a #GModule to make permanently resident + + + + + + Returns the filename that the module was opened with. + +If @module refers to the application itself, "main" is returned. + + the filename of the module + + + + + a #GModule + + + + + + Gets a symbol pointer from a module, such as one exported +by #G_MODULE_EXPORT. Note that a valid symbol can be %NULL. + + %TRUE on success + + + + + a #GModule + + + + the name of the symbol to find + + + + returns the pointer to the symbol value + + + + + + A portable way to build the filename of a module. The platform-specific +prefix and suffix are added to the filename, if needed, and the result +is added to the directory, using the correct separator character. + +The directory should specify the directory where the module can be found. +It can be %NULL or an empty string to indicate that the module is in a +standard platform-specific directory, though this is not recommended +since the wrong module may be found. + +For example, calling g_module_build_path() on a Linux system with a +@directory of `/lib` and a @module_name of "mylibrary" will return +`/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the +directory it will return `\Windows\mylibrary.dll`. + + the complete path of the module, including the standard library + prefix and suffix. This should be freed when no longer needed + + + + + the directory where the module is. This can be + %NULL or the empty string to indicate that the standard platform-specific + directories will be used, though that is not recommended + + + + the name of the module + + + + + + Gets a string describing the last module error. + + a string describing the last module error + + + + + Opens a module. If the module has already been opened, +its reference count is incremented. + +First of all g_module_open() tries to open @file_name as a module. +If that fails and @file_name has the ".la"-suffix (and is a libtool +archive) it tries to open the corresponding module. If that fails +and it doesn't have the proper module suffix for the platform +(#G_MODULE_SUFFIX), this suffix will be appended and the corresponding +module will be opended. If that fails and @file_name doesn't have the +".la"-suffix, this suffix is appended and g_module_open() tries to open +the corresponding module. If eventually that fails as well, %NULL is +returned. + + a #GModule on success, or %NULL on failure + + + + + the name of the file containing the module, or %NULL + to obtain a #GModule representing the main program itself + + + + the flags used for opening the module. This can be the + logical OR of any of the #GModuleFlags + + + + + + Checks if modules are supported on the current platform. + + %TRUE if modules are supported + + + + + + Specifies the type of the module initialization function. +If a module contains a function named g_module_check_init() it is called +automatically when the module is loaded. It is passed the #GModule structure +and should return %NULL on success or a string describing the initialization +error. + + %NULL on success, or a string describing the initialization error + + + + + the #GModule corresponding to the module which has just been loaded + + + + + + Flags passed to g_module_open(). +Note that these flags are not supported on all platforms. + + specifies that symbols are only resolved when + needed. The default action is to bind all symbols when the module + is loaded. + + + specifies that symbols in the module should + not be added to the global name space. The default action on most + platforms is to place symbols in the module in the global name space, + which may cause conflicts with existing symbols. + + + mask for all flags. + + + + Specifies the type of the module function called when it is unloaded. +If a module contains a function named g_module_unload() it is called +automatically when the module is unloaded. +It is passed the #GModule structure. + + + + + + the #GModule about to be unloaded + + + + + + A portable way to build the filename of a module. The platform-specific +prefix and suffix are added to the filename, if needed, and the result +is added to the directory, using the correct separator character. + +The directory should specify the directory where the module can be found. +It can be %NULL or an empty string to indicate that the module is in a +standard platform-specific directory, though this is not recommended +since the wrong module may be found. + +For example, calling g_module_build_path() on a Linux system with a +@directory of `/lib` and a @module_name of "mylibrary" will return +`/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the +directory it will return `\Windows\mylibrary.dll`. + + the complete path of the module, including the standard library + prefix and suffix. This should be freed when no longer needed + + + + + the directory where the module is. This can be + %NULL or the empty string to indicate that the standard platform-specific + directories will be used, though that is not recommended + + + + the name of the module + + + + + + Gets a string describing the last module error. + + a string describing the last module error + + + + + Checks if modules are supported on the current platform. + + %TRUE if modules are supported + + + + + diff --git a/gir-files/GObject-2.0.gir b/gir-files/GObject-2.0.gir new file mode 100644 index 000000000..077151556 --- /dev/null +++ b/gir-files/GObject-2.0.gir @@ -0,0 +1,15763 @@ + + + + + + + + + This is the signature of marshaller functions, required to marshall +arrays of parameter values to signal emissions into C language callback +invocations. It is merely an alias to #GClosureMarshal since the #GClosure +mechanism takes over responsibility of actual function invocation for the +signal system. + + + + This is the signature of va_list marshaller functions, an optional +marshaller that can be used in some situations to avoid +marshalling the signal argument into GValues. + + + + A numerical value which represents the unique identifier of a registered +type. + + + + A callback function used by the type system to finalize those portions +of a derived types class structure that were setup from the corresponding +GBaseInitFunc() function. Class finalization basically works the inverse +way in which class initialization is performed. +See GClassInitFunc() for a discussion of the class initialization process. + + + + + + The #GTypeClass structure to finalize + + + + + + A callback function used by the type system to do base initialization +of the class structures of derived types. It is called as part of the +initialization process of all derived classes and should reallocate +or reset all dynamic class members copied over from the parent class. +For example, class members (such as strings) that are not sufficiently +handled by a plain memory copy of the parent class into the derived class +have to be altered. See GClassInitFunc() for a discussion of the class +initialization process. + + + + + + The #GTypeClass structure to initialize + + + + + + #GBinding is the representation of a binding between a property on a +#GObject instance (or source) and another property on another #GObject +instance (or target). Whenever the source property changes, the same +value is applied to the target property; for instance, the following +binding: + +|[<!-- language="C" --> + g_object_bind_property (object1, "property-a", + object2, "property-b", + G_BINDING_DEFAULT); +]| + +will cause the property named "property-b" of @object2 to be updated +every time g_object_set() or the specific accessor changes the value of +the property "property-a" of @object1. + +It is possible to create a bidirectional binding between two properties +of two #GObject instances, so that if either property changes, the +other is updated as well, for instance: + +|[<!-- language="C" --> + g_object_bind_property (object1, "property-a", + object2, "property-b", + G_BINDING_BIDIRECTIONAL); +]| + +will keep the two properties in sync. + +It is also possible to set a custom transformation function (in both +directions, in case of a bidirectional binding) to apply a custom +transformation from the source value to the target value before +applying it; for instance, the following binding: + +|[<!-- language="C" --> + g_object_bind_property_full (adjustment1, "value", + adjustment2, "value", + G_BINDING_BIDIRECTIONAL, + celsius_to_fahrenheit, + fahrenheit_to_celsius, + NULL, NULL); +]| + +will keep the "value" property of the two adjustments in sync; the +@celsius_to_fahrenheit function will be called whenever the "value" +property of @adjustment1 changes and will transform the current value +of the property before applying it to the "value" property of @adjustment2. + +Vice versa, the @fahrenheit_to_celsius function will be called whenever +the "value" property of @adjustment2 changes, and will transform the +current value of the property before applying it to the "value" property +of @adjustment1. + +Note that #GBinding does not resolve cycles by itself; a cycle like + +|[ + object1:propertyA -> object2:propertyB + object2:propertyB -> object3:propertyC + object3:propertyC -> object1:propertyA +]| + +might lead to an infinite loop. The loop, in this particular case, +can be avoided if the objects emit the #GObject::notify signal only +if the value has effectively been changed. A binding is implemented +using the #GObject::notify signal, so it is susceptible to all the +various ways of blocking a signal emission, like g_signal_stop_emission() +or g_signal_handler_block(). + +A binding will be severed, and the resources it allocates freed, whenever +either one of the #GObject instances it refers to are finalized, or when +the #GBinding instance loses its last reference. + +Bindings for languages with garbage collection can use +g_binding_unbind() to explicitly release a binding between the source +and target properties, instead of relying on the last reference on the +binding, source, and target instances to drop. + +#GBinding is available since GObject 2.26 + + Retrieves the flags passed when constructing the #GBinding. + + the #GBindingFlags used by the #GBinding + + + + + a #GBinding + + + + + + Retrieves the #GObject instance used as the source of the binding. + + the source #GObject + + + + + a #GBinding + + + + + + Retrieves the name of the property of #GBinding:source used as the source +of the binding. + + the name of the source property + + + + + a #GBinding + + + + + + Retrieves the #GObject instance used as the target of the binding. + + the target #GObject + + + + + a #GBinding + + + + + + Retrieves the name of the property of #GBinding:target used as the target +of the binding. + + the name of the target property + + + + + a #GBinding + + + + + + Explicitly releases the binding between the source and the target +property expressed by @binding. + +This function will release the reference that is being held on +the @binding instance; if you want to hold on to the #GBinding instance +after calling g_binding_unbind(), you will need to hold a reference +to it. + + + + + + a #GBinding + + + + + + Flags to be used to control the #GBinding + + + + The #GObject that should be used as the source of the binding + + + + The name of the property of #GBinding:source that should be used +as the source of the binding + + + + The #GObject that should be used as the target of the binding + + + + The name of the property of #GBinding:target that should be used +as the target of the binding + + + + + Flags to be passed to g_object_bind_property() or +g_object_bind_property_full(). + +This enumeration can be extended at later date. + + The default binding; if the source property + changes, the target property is updated with its value. + + + Bidirectional binding; if either the + property of the source or the property of the target changes, + the other is updated. + + + Synchronize the values of the source and + target properties when creating the binding; the direction of + the synchronization is always from the source to the target. + + + If the two properties being bound are + booleans, setting one to %TRUE will result in the other being + set to %FALSE and vice versa. This flag will only work for + boolean properties, and cannot be used when passing custom + transformation functions to g_object_bind_property_full(). + + + + A function to be called to transform @from_value to @to_value. If +this is the @transform_to function of a binding, then @from_value +is the @source_property on the @source object, and @to_value is the +@target_property on the @target object. If this is the +@transform_from function of a %G_BINDING_BIDIRECTIONAL binding, +then those roles are reversed. + + %TRUE if the transformation was successful, and %FALSE + otherwise + + + + + a #GBinding + + + + the #GValue containing the value to transform + + + + the #GValue in which to store the transformed value + + + + data passed to the transform function + + + + + + This function is provided by the user and should produce a copy +of the passed in boxed structure. + + The newly created copy of the boxed structure. + + + + + The boxed structure to be copied. + + + + + + This function is provided by the user and should free the boxed +structure passed. + + + + + + The boxed structure to be freed. + + + + + + A #GCClosure is a specialization of #GClosure for C function callbacks. + + the #GClosure + + + + the callback function + + + + A #GClosureMarshal function for use with signals with handlers that +take two boxed pointers as arguments and return a boolean. If you +have such a signal, you will probably also need to use an +accumulator, such as g_signal_accumulator_true_handled(). + + + + + + A #GClosure. + + + + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. + + + + The length of the @param_values array. + + + + An array of #GValues holding the arguments + on which to invoke the callback of closure. + + + + The invocation hint given as the last argument to + g_closure_invoke(). + + + + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__BOXED_BOXED(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter +denotes a flags type. + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue which can store the returned #gboolean + + + + 2 + + + + a #GValue array holding instance and arg1 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__FLAGS(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue, which can store the returned string + + + + 3 + + + + a #GValue array holding instance, arg1 and arg2 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_STRING__OBJECT_POINTER(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gboolean parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOOLEAN(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GBoxed* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOXED(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gchar parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__CHAR(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gdouble parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__DOUBLE(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the enumeration parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ENUM(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the flags parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLAGS(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gfloat parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLOAT(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gint parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__INT(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #glong parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__LONG(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GObject* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__OBJECT(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GParamSpec* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__PARAM(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gpointer parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__POINTER(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gchar* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__STRING(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #guchar parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UCHAR(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #guint parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 3 + + + + a #GValue array holding instance, arg1 and arg2 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT_POINTER(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gulong parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ULONG(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GVariant* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VARIANT(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 1 + + + + a #GValue array holding only the instance + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VOID(). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + A generic marshaller function implemented via +[libffi](http://sourceware.org/libffi/). + +Normally this function is not passed explicitly to g_signal_new(), +but used automatically by GLib when specifying a %NULL marshaller. + + + + + + A #GClosure. + + + + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. + + + + The length of the @param_values array. + + + + An array of #GValues holding the arguments + on which to invoke the callback of closure. + + + + The invocation hint given as the last argument to + g_closure_invoke(). + + + + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + + + A generic #GVaClosureMarshal function implemented via +[libffi](http://sourceware.org/libffi/). + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is + invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args_list. + + + + + + + + Creates a new closure which invokes @callback_func with @user_data as +the last parameter. + + a new #GCClosure + + + + + the function to invoke + + + + user data to pass to @callback_func + + + + destroy notify to be called when @user_data is no longer used + + + + + + A variant of g_cclosure_new() which uses @object as @user_data and +calls g_object_watch_closure() on @object and the created +closure. This function is useful when you have a callback closely +associated with a #GObject, and want the callback to no longer run +after the object is is freed. + + a new #GCClosure + + + + + the function to invoke + + + + a #GObject pointer to pass to @callback_func + + + + + + A variant of g_cclosure_new_swap() which uses @object as @user_data +and calls g_object_watch_closure() on @object and the created +closure. This function is useful when you have a callback closely +associated with a #GObject, and want the callback to no longer run +after the object is is freed. + + a new #GCClosure + + + + + the function to invoke + + + + a #GObject pointer to pass to @callback_func + + + + + + Creates a new closure which invokes @callback_func with @user_data as +the first parameter. + + a new #GCClosure + + + + + the function to invoke + + + + user data to pass to @callback_func + + + + destroy notify to be called when @user_data is no longer used + + + + + + + The type used for callback functions in structure definitions and function +signatures. This doesn't mean that all callback functions must take no +parameters and return void. The required signature of a callback function +is determined by the context in which is used (e.g. the signal to which it +is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. + + + + + + A callback function used by the type system to finalize a class. +This function is rarely needed, as dynamically allocated class resources +should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). +Also, specification of a GClassFinalizeFunc() in the #GTypeInfo +structure of a static type is invalid, because classes of static types +will never be finalized (they are artificially kept alive when their +reference count drops to zero). + + + + + + The #GTypeClass structure to finalize + + + + The @class_data member supplied via the #GTypeInfo structure + + + + + + A callback function used by the type system to initialize the class +of a specific type. This function should initialize all static class +members. + +The initialization process of a class involves: + +- Copying common members from the parent class over to the + derived class structure. +- Zero initialization of the remaining members not copied + over from the parent class. +- Invocation of the GBaseInitFunc() initializers of all parent + types and the class' type. +- Invocation of the class' GClassInitFunc() initializer. + +Since derived classes are partially initialized through a memory copy +of the parent class, the general rule is that GBaseInitFunc() and +GBaseFinalizeFunc() should take care of necessary reinitialization +and release of those class members that were introduced by the type +that specified these GBaseInitFunc()/GBaseFinalizeFunc(). +GClassInitFunc() should only care about initializing static +class members, while dynamic class members (such as allocated strings +or reference counted resources) are better handled by a GBaseInitFunc() +for this type, so proper initialization of the dynamic class members +is performed for class initialization of derived types as well. + +An example may help to correspond the intend of the different class +initializers: + +|[<!-- language="C" --> +typedef struct { + GObjectClass parent_class; + gint static_integer; + gchar *dynamic_string; +} TypeAClass; +static void +type_a_base_class_init (TypeAClass *class) +{ + class->dynamic_string = g_strdup ("some string"); +} +static void +type_a_base_class_finalize (TypeAClass *class) +{ + g_free (class->dynamic_string); +} +static void +type_a_class_init (TypeAClass *class) +{ + class->static_integer = 42; +} + +typedef struct { + TypeAClass parent_class; + gfloat static_float; + GString *dynamic_gstring; +} TypeBClass; +static void +type_b_base_class_init (TypeBClass *class) +{ + class->dynamic_gstring = g_string_new ("some other string"); +} +static void +type_b_base_class_finalize (TypeBClass *class) +{ + g_string_free (class->dynamic_gstring); +} +static void +type_b_class_init (TypeBClass *class) +{ + class->static_float = 3.14159265358979323846; +} +]| +Initialization of TypeBClass will first cause initialization of +TypeAClass (derived classes reference their parent classes, see +g_type_class_ref() on this). + +Initialization of TypeAClass roughly involves zero-initializing its fields, +then calling its GBaseInitFunc() type_a_base_class_init() to allocate +its dynamic members (dynamic_string), and finally calling its GClassInitFunc() +type_a_class_init() to initialize its static members (static_integer). +The first step in the initialization process of TypeBClass is then +a plain memory copy of the contents of TypeAClass into TypeBClass and +zero-initialization of the remaining fields in TypeBClass. +The dynamic members of TypeAClass within TypeBClass now need +reinitialization which is performed by calling type_a_base_class_init() +with an argument of TypeBClass. + +After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init() +is called to allocate the dynamic members of TypeBClass (dynamic_gstring), +and finally the GClassInitFunc() of TypeBClass, type_b_class_init(), +is called to complete the initialization process with the static members +(static_float). + +Corresponding finalization counter parts to the GBaseInitFunc() functions +have to be provided to release allocated resources at class finalization +time. + + + + + + The #GTypeClass structure to initialize. + + + + The @class_data member supplied via the #GTypeInfo structure. + + + + + + A #GClosure represents a callback supplied by the programmer. It +will generally comprise a function of some kind and a marshaller +used to call it. It is the responsibility of the marshaller to +convert the arguments for the invocation from #GValues into +a suitable form, perform the callback on the converted arguments, +and transform the return value back into a #GValue. + +In the case of C programs, a closure usually just holds a pointer +to a function and maybe a data argument, and the marshaller +converts between #GValue and native C types. The GObject +library provides the #GCClosure type for this purpose. Bindings for +other languages need marshallers which convert between #GValue<!-- +-->s and suitable representations in the runtime of the language in +order to use functions written in that languages as callbacks. + +Within GObject, closures play an important role in the +implementation of signals. When a signal is registered, the +@c_marshaller argument to g_signal_new() specifies the default C +marshaller for any closure which is connected to this +signal. GObject provides a number of C marshallers for this +purpose, see the g_cclosure_marshal_*() functions. Additional C +marshallers can be generated with the [glib-genmarshal][glib-genmarshal] +utility. Closures can be explicitly connected to signals with +g_signal_connect_closure(), but it usually more convenient to let +GObject create a closure automatically by using one of the +g_signal_connect_*() functions which take a callback function/user +data pair. + +Using closures has a number of important advantages over a simple +callback function/data pointer combination: + +- Closures allow the callee to get the types of the callback parameters, + which means that language bindings don't have to write individual glue + for each callback type. + +- The reference counting of #GClosure makes it easy to handle reentrancy + right; if a callback is removed while it is being invoked, the closure + and its parameters won't be freed until the invocation finishes. + +- g_closure_invalidate() and invalidation notifiers allow callbacks to be + automatically removed when the objects they point to go away. + + + + + + + + + + + + + + + + + + + + + + + + + + Indicates whether the closure is currently being invoked with + g_closure_invoke() + + + + Indicates whether the closure has been invalidated by + g_closure_invalidate() + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A variant of g_closure_new_simple() which stores @object in the +@data field of the closure and calls g_object_watch_closure() on +@object and the created closure. This function is mainly useful +when implementing new types of closures. + + a newly allocated #GClosure + + + + + the size of the structure to allocate, must be at least + `sizeof (GClosure)` + + + + a #GObject pointer to store in the @data field of the newly + allocated #GClosure + + + + + + Allocates a struct of the given size and initializes the initial +part as a #GClosure. This function is mainly useful when +implementing new types of closures. + +|[<!-- language="C" --> +typedef struct _MyClosure MyClosure; +struct _MyClosure +{ + GClosure closure; + // extra data goes here +}; + +static void +my_closure_finalize (gpointer notify_data, + GClosure *closure) +{ + MyClosure *my_closure = (MyClosure *)closure; + + // free extra data here +} + +MyClosure *my_closure_new (gpointer data) +{ + GClosure *closure; + MyClosure *my_closure; + + closure = g_closure_new_simple (sizeof (MyClosure), data); + my_closure = (MyClosure *) closure; + + // initialize extra data here + + g_closure_add_finalize_notifier (closure, notify_data, + my_closure_finalize); + return my_closure; +} +]| + + a newly allocated #GClosure + + + + + the size of the structure to allocate, must be at least + `sizeof (GClosure)` + + + + data to store in the @data field of the newly allocated #GClosure + + + + + + Registers a finalization notifier which will be called when the +reference count of @closure goes down to 0. Multiple finalization +notifiers on a single closure are invoked in unspecified order. If +a single call to g_closure_unref() results in the closure being +both invalidated and finalized, then the invalidate notifiers will +be run before the finalize notifiers. + + + + + + a #GClosure + + + + data to pass to @notify_func + + + + the callback function to register + + + + + + Registers an invalidation notifier which will be called when the +@closure is invalidated with g_closure_invalidate(). Invalidation +notifiers are invoked before finalization notifiers, in an +unspecified order. + + + + + + a #GClosure + + + + data to pass to @notify_func + + + + the callback function to register + + + + + + Adds a pair of notifiers which get invoked before and after the +closure callback, respectively. This is typically used to protect +the extra arguments for the duration of the callback. See +g_object_watch_closure() for an example of marshal guards. + + + + + + a #GClosure + + + + data to pass + to @pre_marshal_notify + + + + a function to call before the closure callback + + + + data to pass + to @post_marshal_notify + + + + a function to call after the closure callback + + + + + + Sets a flag on the closure to indicate that its calling +environment has become invalid, and thus causes any future +invocations of g_closure_invoke() on this @closure to be +ignored. Also, invalidation notifiers installed on the closure will +be called at this point. Note that unless you are holding a +reference to the closure yourself, the invalidation notifiers may +unref the closure and cause it to be destroyed, so if you need to +access the closure after calling g_closure_invalidate(), make sure +that you've previously called g_closure_ref(). + +Note that g_closure_invalidate() will also be called when the +reference count of a closure drops to zero (unless it has already +been invalidated before). + + + + + + GClosure to invalidate + + + + + + Invokes the closure, i.e. executes the callback represented by the @closure. + + + + + + a #GClosure + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure + doesn't return a value. + + + + the length of the @param_values array + + + + an array of + #GValues holding the arguments on which to + invoke the callback of @closure + + + + + + a context-dependent invocation hint + + + + + + Increments the reference count on a closure to force it staying +alive while the caller holds a pointer to it. + + The @closure passed in, for convenience + + + + + #GClosure to increment the reference count on + + + + + + Removes a finalization notifier. + +Notice that notifiers are automatically removed after they are run. + + + + + + a #GClosure + + + + data which was passed to g_closure_add_finalize_notifier() + when registering @notify_func + + + + the callback function to remove + + + + + + Removes an invalidation notifier. + +Notice that notifiers are automatically removed after they are run. + + + + + + a #GClosure + + + + data which was passed to g_closure_add_invalidate_notifier() + when registering @notify_func + + + + the callback function to remove + + + + + + Sets the marshaller of @closure. The `marshal_data` +of @marshal provides a way for a meta marshaller to provide additional +information to the marshaller. (See g_closure_set_meta_marshal().) For +GObject's C predefined marshallers (the g_cclosure_marshal_*() +functions), what it provides is a callback function to use instead of +@closure->callback. + + + + + + a #GClosure + + + + a #GClosureMarshal function + + + + + + Sets the meta marshaller of @closure. A meta marshaller wraps +@closure->marshal and modifies the way it is called in some +fashion. The most common use of this facility is for C callbacks. +The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), +are used everywhere, but the way that we get the callback function +differs. In most cases we want to use @closure->callback, but in +other cases we want to use some different technique to retrieve the +callback function. + +For example, class closures for signals (see +g_signal_type_cclosure_new()) retrieve the callback function from a +fixed offset in the class structure. The meta marshaller retrieves +the right callback and passes it to the marshaller as the +@marshal_data argument. + + + + + + a #GClosure + + + + context-dependent data to pass + to @meta_marshal + + + + a #GClosureMarshal function + + + + + + Takes over the initial ownership of a closure. Each closure is +initially created in a "floating" state, which means that the initial +reference count is not owned by any caller. g_closure_sink() checks +to see if the object is still floating, and if so, unsets the +floating state and decreases the reference count. If the closure +is not floating, g_closure_sink() does nothing. The reason for the +existence of the floating state is to prevent cumbersome code +sequences like: +|[<!-- language="C" --> +closure = g_cclosure_new (cb_func, cb_data); +g_source_set_closure (source, closure); +g_closure_unref (closure); // GObject doesn't really need this +]| +Because g_source_set_closure() (and similar functions) take ownership of the +initial reference count, if it is unowned, we instead can write: +|[<!-- language="C" --> +g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); +]| + +Generally, this function is used together with g_closure_ref(). Ane example +of storing a closure for later notification looks like: +|[<!-- language="C" --> +static GClosure *notify_closure = NULL; +void +foo_notify_set_closure (GClosure *closure) +{ + if (notify_closure) + g_closure_unref (notify_closure); + notify_closure = closure; + if (notify_closure) + { + g_closure_ref (notify_closure); + g_closure_sink (notify_closure); + } +} +]| + +Because g_closure_sink() may decrement the reference count of a closure +(if it hasn't been called on @closure yet) just like g_closure_unref(), +g_closure_ref() should be called prior to this function. + + + + + + #GClosure to decrement the initial reference count on, if it's + still being held + + + + + + Decrements the reference count of a closure after it was previously +incremented by the same caller. If no other callers are using the +closure, then the closure will be destroyed and freed. + + + + + + #GClosure to decrement the reference count on + + + + + + + The type used for marshaller functions. + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the length of the @param_values array + + + + an array of + #GValues holding the arguments on which to invoke the + callback of @closure + + + + + + the invocation hint given as the + last argument to g_closure_invoke() + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + + + The type used for the various notification callbacks which can be registered +on closures. + + + + + + data specified when registering the notification callback + + + + the #GClosure on which the notification is emitted + + + + + + + + + + + + + + The connection flags are used to specify the behaviour of a signal's +connection. + + whether the handler should be called before or after the + default handler of the signal. + + + whether the instance and data should be swapped when + calling the handler; see g_signal_connect_swapped() for an example. + + + + The class of an enumeration type holds information about its +possible values. + + the parent class + + + + the smallest possible value. + + + + the largest possible value. + + + + the number of possible values. + + + + an array of #GEnumValue structs describing the + individual values. + + + + + A structure which contains a single enum value, its name, and its +nickname. + + the enum value + + + + the name of the value + + + + the nickname of the value + + + + + The class of a flags type holds information about its +possible values. + + the parent class + + + + a mask covering all possible values. + + + + the number of possible values. + + + + an array of #GFlagsValue structs describing the + individual values. + + + + + A structure which contains a single flags value, its name, and its +nickname. + + the flags value + + + + the name of the value + + + + the nickname of the value + + + + + All the fields in the GInitiallyUnowned structure +are private to the #GInitiallyUnowned implementation and should never be +accessed directly. + + + + + + + + + + + + The class structure for the GInitiallyUnowned type. + + the parent class + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GObject + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A callback function used by the type system to initialize a new +instance of a type. This function initializes all instance members and +allocates any resources required by it. + +Initialization of a derived instance involves calling all its parent +types instance initializers, so the class member of the instance +is altered during its initialization to always point to the class that +belongs to the type the current initializer was introduced for. + +The extended members of @instance are guaranteed to have been filled with +zeros before this function is called. + + + + + + The instance to initialize + + + + The class of the type the instance is + created for + + + + + + A callback function used by the type system to finalize an interface. +This function should destroy any internal data and release any resources +allocated by the corresponding GInterfaceInitFunc() function. + + + + + + The interface structure to finalize + + + + The @interface_data supplied via the #GInterfaceInfo structure + + + + + + A structure that provides information to the type system which is +used specifically for managing interface types. + + location of the interface initialization function + + + + location of the interface finalization function + + + + user-supplied data passed to the interface init/finalize functions + + + + + A callback function used by the type system to initialize a new +interface. This function should initialize all internal data and +allocate any resources required by the interface. + +The members of @iface_data are guaranteed to have been filled with +zeros before this function is called. + + + + + + The interface structure to initialize + + + + The @interface_data supplied via the #GInterfaceInfo structure + + + + + + All the fields in the GObject structure are private +to the #GObject implementation and should never be accessed directly. + + Creates a new instance of a #GObject subtype and sets its properties. + +Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) +which are not explicitly specified are set to their default values. + + a new instance of + @object_type + + + + + the type id of the #GObject subtype to instantiate + + + + the name of the first property + + + + the value of the first property, followed optionally by more + name/value pairs, followed by %NULL + + + + + + Creates a new instance of a #GObject subtype and sets its properties. + +Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) +which are not explicitly specified are set to their default values. + + a new instance of @object_type + + + + + the type id of the #GObject subtype to instantiate + + + + the name of the first property + + + + the value of the first property, followed optionally by more + name/value pairs, followed by %NULL + + + + + + Creates a new instance of a #GObject subtype and sets its properties. + +Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) +which are not explicitly specified are set to their default values. + + a new instance of +@object_type + + + + + the type id of the #GObject subtype to instantiate + + + + the length of the @parameters array + + + + an array of #GParameter + + + + + + + + + + + + + + + + + + + + + Find the #GParamSpec with the given name for an +interface. Generally, the interface vtable passed in as @g_iface +will be the default vtable from g_type_default_interface_ref(), or, +if you know the interface has already been loaded, +g_type_default_interface_peek(). + + the #GParamSpec for the property of the + interface with the name @property_name, or %NULL if no + such property exists. + + + + + any interface vtable for the + interface, or the default vtable for the interface + + + + name of a property to lookup. + + + + + + Add a property to an interface; this is only useful for interfaces +that are added to GObject-derived types. Adding a property to an +interface forces all objects classes with that interface to have a +compatible property. The compatible property could be a newly +created #GParamSpec, but normally +g_object_class_override_property() will be used so that the object +class only needs to provide an implementation and inherits the +property description, default value, bounds, and so forth from the +interface property. + +This function is meant to be called from the interface's default +vtable initialization function (the @class_init member of +#GTypeInfo.) It must not be called after after @class_init has +been called for any object types implementing this interface. + + + + + + any interface vtable for the + interface, or the default + vtable for the interface. + + + + the #GParamSpec for the new property + + + + + + Lists the properties of an interface.Generally, the interface +vtable passed in as @g_iface will be the default vtable from +g_type_default_interface_ref(), or, if you know the interface has +already been loaded, g_type_default_interface_peek(). + + a + pointer to an array of pointers to #GParamSpec + structures. The paramspecs are owned by GLib, but the + array should be freed with g_free() when you are done with + it. + + + + + + + any interface vtable for the + interface, or the default vtable for the interface + + + + location to store number of properties returned. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Emits a "notify" signal for the property @property_name on @object. + +When possible, eg. when signaling a property change from within the class +that registered the property, you should use g_object_notify_by_pspec() +instead. + +Note that emission of the notify signal may be blocked with +g_object_freeze_notify(). In this case, the signal emissions are queued +and will be emitted (in reverse order) when g_object_thaw_notify() is +called. + + + + + + a #GObject + + + + + + + + + + + + + + + + + + + + + + + + + + + + Increases the reference count of the object by one and sets a +callback to be called when all other references to the object are +dropped, or when this is already the last reference to the object +and another reference is established. + +This functionality is intended for binding @object to a proxy +object managed by another memory manager. This is done with two +paired references: the strong reference added by +g_object_add_toggle_ref() and a reverse reference to the proxy +object which is either a strong reference or weak reference. + +The setup is that when there are no other references to @object, +only a weak reference is held in the reverse direction from @object +to the proxy object, but when there are other references held to +@object, a strong reference is held. The @notify callback is called +when the reference from @object to the proxy object should be +"toggled" from strong to weak (@is_last_ref true) or weak to strong +(@is_last_ref false). + +Since a (normal) reference must be held to the object before +calling g_object_add_toggle_ref(), the initial state of the reverse +link is always strong. + +Multiple toggle references may be added to the same gobject, +however if there are multiple toggle references to an object, none +of them will ever be notified until all but one are removed. For +this reason, you should only ever use a toggle reference if there +is important state in the proxy object. + + + + + + a #GObject + + + + a function to call when this reference is the + last reference to the object, or is no longer + the last reference. + + + + data to pass to @notify + + + + + + Adds a weak reference from weak_pointer to @object to indicate that +the pointer located at @weak_pointer_location is only valid during +the lifetime of @object. When the @object is finalized, +@weak_pointer will be set to %NULL. + +Note that as with g_object_weak_ref(), the weak references created by +this method are not thread-safe: they cannot safely be used in one +thread if the object's last g_object_unref() might happen in another +thread. Use #GWeakRef if thread-safety is required. + + + + + + The object that should be weak referenced. + + + + The memory address + of a pointer. + + + + + + Creates a binding between @source_property on @source and @target_property +on @target. Whenever the @source_property is changed the @target_property is +updated using the same value. For instance: + +|[ + g_object_bind_property (action, "active", widget, "sensitive", 0); +]| + +Will result in the "sensitive" property of the widget #GObject instance to be +updated with the same value of the "active" property of the action #GObject +instance. + +If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: +if @target_property on @target changes then the @source_property on @source +will be updated as well. + +The binding will automatically be removed when either the @source or the +@target instances are finalized. To remove the binding without affecting the +@source and the @target you can just call g_object_unref() on the returned +#GBinding instance. + +A #GObject can have multiple bindings. + + the #GBinding instance representing the + binding between the two #GObject instances. The binding is released + whenever the #GBinding reference count reaches zero. + + + + + the source #GObject + + + + the property on @source to bind + + + + the target #GObject + + + + the property on @target to bind + + + + flags to pass to #GBinding + + + + + + Complete version of g_object_bind_property(). + +Creates a binding between @source_property on @source and @target_property +on @target, allowing you to set the transformation functions to be used by +the binding. + +If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: +if @target_property on @target changes then the @source_property on @source +will be updated as well. The @transform_from function is only used in case +of bidirectional bindings, otherwise it will be ignored + +The binding will automatically be removed when either the @source or the +@target instances are finalized. To remove the binding without affecting the +@source and the @target you can just call g_object_unref() on the returned +#GBinding instance. + +A #GObject can have multiple bindings. + +The same @user_data parameter will be used for both @transform_to +and @transform_from transformation functions; the @notify function will +be called once, when the binding is removed. If you need different data +for each transformation function, please use +g_object_bind_property_with_closures() instead. + + the #GBinding instance representing the + binding between the two #GObject instances. The binding is released + whenever the #GBinding reference count reaches zero. + + + + + the source #GObject + + + + the property on @source to bind + + + + the target #GObject + + + + the property on @target to bind + + + + flags to pass to #GBinding + + + + the transformation function + from the @source to the @target, or %NULL to use the default + + + + the transformation function + from the @target to the @source, or %NULL to use the default + + + + custom data to be passed to the transformation functions, + or %NULL + + + + function to be called when disposing the binding, to free the + resources used by the transformation functions + + + + + + Creates a binding between @source_property on @source and @target_property +on @target, allowing you to set the transformation functions to be used by +the binding. + +This function is the language bindings friendly version of +g_object_bind_property_full(), using #GClosures instead of +function pointers. + + the #GBinding instance representing the + binding between the two #GObject instances. The binding is released + whenever the #GBinding reference count reaches zero. + + + + + the source #GObject + + + + the property on @source to bind + + + + the target #GObject + + + + the property on @target to bind + + + + flags to pass to #GBinding + + + + a #GClosure wrapping the transformation function + from the @source to the @target, or %NULL to use the default + + + + a #GClosure wrapping the transformation function + from the @target to the @source, or %NULL to use the default + + + + + + A convenience function to connect multiple signals at once. + +The signal specs expected by this function have the form +"modifier::signal_name", where modifier can be one of the following: +* - signal: equivalent to g_signal_connect_data (..., NULL, 0) +- object-signal, object_signal: equivalent to g_signal_connect_object (..., 0) +- swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED) +- swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED) +- signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER) +- object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER) +- swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER) +- swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER) + +|[<!-- language="C" --> + menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, + "type", GTK_WINDOW_POPUP, + "child", menu, + NULL), + "signal::event", gtk_menu_window_event, menu, + "signal::size_request", gtk_menu_window_size_request, menu, + "signal::destroy", gtk_widget_destroyed, &menu->toplevel, + NULL); +]| + + @object + + + + + a #GObject + + + + the spec for the first signal + + + + #GCallback for the first signal, followed by data for the + first signal, followed optionally by more signal + spec/callback/data triples, followed by %NULL + + + + + + A convenience function to disconnect multiple signals at once. + +The signal specs expected by this function have the form +"any_signal", which means to disconnect any signal with matching +callback and data, or "any_signal::signal_name", which only +disconnects the signal named "signal_name". + + + + + + a #GObject + + + + the spec for the first signal + + + + #GCallback for the first signal, followed by data for the first signal, + followed optionally by more signal spec/callback/data triples, + followed by %NULL + + + + + + This is a variant of g_object_get_data() which returns +a 'duplicate' of the value. @dup_func defines the +meaning of 'duplicate' in this context, it could e.g. +take a reference on a ref-counted object. + +If the @key is not set on the object then @dup_func +will be called with a %NULL argument. + +Note that @dup_func is called while user data of @object +is locked. + +This function can be useful to avoid races when multiple +threads are using object data on the same key on the same +object. + + the result of calling @dup_func on the value + associated with @key on @object, or %NULL if not set. + If @dup_func is %NULL, the value is returned + unmodified. + + + + + the #GObject to store user data on + + + + a string, naming the user data pointer + + + + function to dup the value + + + + passed as user_data to @dup_func + + + + + + This is a variant of g_object_get_qdata() which returns +a 'duplicate' of the value. @dup_func defines the +meaning of 'duplicate' in this context, it could e.g. +take a reference on a ref-counted object. + +If the @quark is not set on the object then @dup_func +will be called with a %NULL argument. + +Note that @dup_func is called while user data of @object +is locked. + +This function can be useful to avoid races when multiple +threads are using object data on the same key on the same +object. + + the result of calling @dup_func on the value + associated with @quark on @object, or %NULL if not set. + If @dup_func is %NULL, the value is returned + unmodified. + + + + + the #GObject to store user data on + + + + a #GQuark, naming the user data pointer + + + + function to dup the value + + + + passed as user_data to @dup_func + + + + + + This function is intended for #GObject implementations to re-enforce +a [floating][floating-ref] object reference. Doing this is seldom +required: all #GInitiallyUnowneds are created with a floating reference +which usually just needs to be sunken by calling g_object_ref_sink(). + + + + + + a #GObject + + + + + + Increases the freeze count on @object. If the freeze count is +non-zero, the emission of "notify" signals on @object is +stopped. The signals are queued until the freeze count is decreased +to zero. Duplicate notifications are squashed so that at most one +#GObject::notify signal is emitted for each property modified while the +object is frozen. + +This is necessary for accessors that modify multiple properties to prevent +premature notification while the object is still being modified. + + + + + + a #GObject + + + + + + Gets properties of an object. + +In general, a copy is made of the property contents and the caller +is responsible for freeing the memory in the appropriate manner for +the type, for instance by calling g_free() or g_object_unref(). + +Here is an example of using g_object_get() to get the contents +of three properties: an integer, a string and an object: +|[<!-- language="C" --> + gint intval; + gchar *strval; + GObject *objval; + + g_object_get (my_object, + "int-property", &intval, + "str-property", &strval, + "obj-property", &objval, + NULL); + + // Do something with intval, strval, objval + + g_free (strval); + g_object_unref (objval); + ]| + + + + + + a #GObject + + + + name of the first property to get + + + + return location for the first property, followed optionally by more + name/return location pairs, followed by %NULL + + + + + + Gets a named field from the objects table of associations (see g_object_set_data()). + + the data if found, or %NULL if no such data exists. + + + + + #GObject containing the associations + + + + name of the key for that association + + + + + + Gets a property of an object. @value must have been initialized to the +expected type of the property (or a type to which the expected type can be +transformed) using g_value_init(). + +In general, a copy is made of the property contents and the caller is +responsible for freeing the memory by calling g_value_unset(). + +Note that g_object_get_property() is really intended for language +bindings, g_object_get() is much more convenient for C programming. + + + + + + a #GObject + + + + the name of the property to get + + + + return location for the property value + + + + + + This function gets back user data pointers stored via +g_object_set_qdata(). + + The user data pointer set, or %NULL + + + + + The GObject to get a stored user data pointer from + + + + A #GQuark, naming the user data pointer + + + + + + Gets properties of an object. + +In general, a copy is made of the property contents and the caller +is responsible for freeing the memory in the appropriate manner for +the type, for instance by calling g_free() or g_object_unref(). + +See g_object_get(). + + + + + + a #GObject + + + + name of the first property to get + + + + return location for the first property, followed optionally by more + name/return location pairs, followed by %NULL + + + + + + Checks whether @object has a [floating][floating-ref] reference. + + %TRUE if @object has a floating reference + + + + + a #GObject + + + + + + Emits a "notify" signal for the property @property_name on @object. + +When possible, eg. when signaling a property change from within the class +that registered the property, you should use g_object_notify_by_pspec() +instead. + +Note that emission of the notify signal may be blocked with +g_object_freeze_notify(). In this case, the signal emissions are queued +and will be emitted (in reverse order) when g_object_thaw_notify() is +called. + + + + + + a #GObject + + + + the name of a property installed on the class of @object. + + + + + + Emits a "notify" signal for the property specified by @pspec on @object. + +This function omits the property name lookup, hence it is faster than +g_object_notify(). + +One way to avoid using g_object_notify() from within the +class that registered the properties, and using g_object_notify_by_pspec() +instead, is to store the GParamSpec used with +g_object_class_install_property() inside a static array, e.g.: + +|[<!-- language="C" --> + enum + { + PROP_0, + PROP_FOO, + PROP_LAST + }; + + static GParamSpec *properties[PROP_LAST]; + + static void + my_object_class_init (MyObjectClass *klass) + { + properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", + 0, 100, + 50, + G_PARAM_READWRITE); + g_object_class_install_property (gobject_class, + PROP_FOO, + properties[PROP_FOO]); + } +]| + +and then notify a change on the "foo" property with: + +|[<!-- language="C" --> + g_object_notify_by_pspec (self, properties[PROP_FOO]); +]| + + + + + + a #GObject + + + + the #GParamSpec of a property installed on the class of @object. + + + + + + Increases the reference count of @object. + + the same @object + + + + + a #GObject + + + + + + Increase the reference count of @object, and possibly remove the +[floating][floating-ref] reference, if @object has a floating reference. + +In other words, if the object is floating, then this call "assumes +ownership" of the floating reference, converting it to a normal +reference by clearing the floating flag while leaving the reference +count unchanged. If the object is not floating, then this call +adds a new normal reference increasing the reference count by one. + + @object + + + + + a #GObject + + + + + + Removes a reference added with g_object_add_toggle_ref(). The +reference count of the object is decreased by one. + + + + + + a #GObject + + + + a function to call when this reference is the + last reference to the object, or is no longer + the last reference. + + + + data to pass to @notify + + + + + + Removes a weak reference from @object that was previously added +using g_object_add_weak_pointer(). The @weak_pointer_location has +to match the one used with g_object_add_weak_pointer(). + + + + + + The object that is weak referenced. + + + + The memory address + of a pointer. + + + + + + Compares the user data for the key @key on @object with +@oldval, and if they are the same, replaces @oldval with +@newval. + +This is like a typical atomic compare-and-exchange +operation, for user data on an object. + +If the previous value was replaced then ownership of the +old value (@oldval) is passed to the caller, including +the registered destroy notify for it (passed out in @old_destroy). +Its up to the caller to free this as he wishes, which may +or may not include using @old_destroy as sometimes replacement +should not destroy the object in the normal way. + + %TRUE if the existing value for @key was replaced + by @newval, %FALSE otherwise. + + + + + the #GObject to store user data on + + + + a string, naming the user data pointer + + + + the old value to compare against + + + + the new value + + + + a destroy notify for the new value + + + + destroy notify for the existing value + + + + + + Compares the user data for the key @quark on @object with +@oldval, and if they are the same, replaces @oldval with +@newval. + +This is like a typical atomic compare-and-exchange +operation, for user data on an object. + +If the previous value was replaced then ownership of the +old value (@oldval) is passed to the caller, including +the registered destroy notify for it (passed out in @old_destroy). +Its up to the caller to free this as he wishes, which may +or may not include using @old_destroy as sometimes replacement +should not destroy the object in the normal way. + + %TRUE if the existing value for @quark was replaced + by @newval, %FALSE otherwise. + + + + + the #GObject to store user data on + + + + a #GQuark, naming the user data pointer + + + + the old value to compare against + + + + the new value + + + + a destroy notify for the new value + + + + destroy notify for the existing value + + + + + + Releases all references to other objects. This can be used to break +reference cycles. + +This function should only be called from object system implementations. + + + + + + a #GObject + + + + + + Sets properties on an object. + +Note that the "notify" signals are queued and only emitted (in +reverse order) after all properties have been set. See +g_object_freeze_notify(). + + + + + + a #GObject + + + + name of the first property to set + + + + value for the first property, followed optionally by more + name/value pairs, followed by %NULL + + + + + + Each object carries around a table of associations from +strings to pointers. This function lets you set an association. + +If the object already had an association with that name, +the old association will be destroyed. + + + + + + #GObject containing the associations. + + + + name of the key + + + + data to associate with that key + + + + + + Like g_object_set_data() except it adds notification +for when the association is destroyed, either by setting it +to a different value or when the object is destroyed. + +Note that the @destroy callback is not called if @data is %NULL. + + + + + + #GObject containing the associations + + + + name of the key + + + + data to associate with that key + + + + function to call when the association is destroyed + + + + + + Sets a property on an object. + + + + + + a #GObject + + + + the name of the property to set + + + + the value + + + + + + This sets an opaque, named pointer on an object. +The name is specified through a #GQuark (retrived e.g. via +g_quark_from_static_string()), and the pointer +can be gotten back from the @object with g_object_get_qdata() +until the @object is finalized. +Setting a previously set user data pointer, overrides (frees) +the old pointer set, using #NULL as pointer essentially +removes the data stored. + + + + + + The GObject to set store a user data pointer + + + + A #GQuark, naming the user data pointer + + + + An opaque user data pointer + + + + + + This function works like g_object_set_qdata(), but in addition, +a void (*destroy) (gpointer) function may be specified which is +called with @data as argument when the @object is finalized, or +the data is being overwritten by a call to g_object_set_qdata() +with the same @quark. + + + + + + The GObject to set store a user data pointer + + + + A #GQuark, naming the user data pointer + + + + An opaque user data pointer + + + + Function to invoke with @data as argument, when @data + needs to be freed + + + + + + Sets properties on an object. + + + + + + a #GObject + + + + name of the first property to set + + + + value for the first property, followed optionally by more + name/value pairs, followed by %NULL + + + + + + Remove a specified datum from the object's data associations, +without invoking the association's destroy handler. + + the data if found, or %NULL if no such data exists. + + + + + #GObject containing the associations + + + + name of the key + + + + + + This function gets back user data pointers stored via +g_object_set_qdata() and removes the @data from object +without invoking its destroy() function (if any was +set). +Usually, calling this function is only required to update +user data pointers with a destroy notifier, for example: +|[<!-- language="C" --> +void +object_add_to_user_list (GObject *object, + const gchar *new_string) +{ + // the quark, naming the object data + GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); + // retrive the old string list + GList *list = g_object_steal_qdata (object, quark_string_list); + + // prepend new string + list = g_list_prepend (list, g_strdup (new_string)); + // this changed 'list', so we need to set it again + g_object_set_qdata_full (object, quark_string_list, list, free_string_list); +} +static void +free_string_list (gpointer data) +{ + GList *node, *list = data; + + for (node = list; node; node = node->next) + g_free (node->data); + g_list_free (list); +} +]| +Using g_object_get_qdata() in the above example, instead of +g_object_steal_qdata() would have left the destroy function set, +and thus the partial string list would have been freed upon +g_object_set_qdata_full(). + + The user data pointer set, or %NULL + + + + + The GObject to get a stored user data pointer from + + + + A #GQuark, naming the user data pointer + + + + + + Reverts the effect of a previous call to +g_object_freeze_notify(). The freeze count is decreased on @object +and when it reaches zero, queued "notify" signals are emitted. + +Duplicate notifications for each property are squashed so that at most one +#GObject::notify signal is emitted for each property, in the reverse order +in which they have been queued. + +It is an error to call this function when the freeze count is zero. + + + + + + a #GObject + + + + + + Decreases the reference count of @object. When its reference count +drops to 0, the object is finalized (i.e. its memory is freed). + +If the pointer to the #GObject may be reused in future (for example, if it is +an instance variable of another object), it is recommended to clear the +pointer to %NULL rather than retain a dangling pointer to a potentially +invalid #GObject instance. Use g_clear_object() for this. + + + + + + a #GObject + + + + + + This function essentially limits the life time of the @closure to +the life time of the object. That is, when the object is finalized, +the @closure is invalidated by calling g_closure_invalidate() on +it, in order to prevent invocations of the closure with a finalized +(nonexisting) object. Also, g_object_ref() and g_object_unref() are +added as marshal guards to the @closure, to ensure that an extra +reference count is held on @object during invocation of the +@closure. Usually, this function will be called on closures that +use this @object as closure data. + + + + + + GObject restricting lifetime of @closure + + + + GClosure to watch + + + + + + Adds a weak reference callback to an object. Weak references are +used for notification when an object is finalized. They are called +"weak references" because they allow you to safely hold a pointer +to an object without calling g_object_ref() (g_object_ref() adds a +strong reference, that is, forces the object to stay alive). + +Note that the weak references created by this method are not +thread-safe: they cannot safely be used in one thread if the +object's last g_object_unref() might happen in another thread. +Use #GWeakRef if thread-safety is required. + + + + + + #GObject to reference weakly + + + + callback to invoke before the object is freed + + + + extra data to pass to notify + + + + + + Removes a weak reference callback to an object. + + + + + + #GObject to remove a weak reference from + + + + callback to search for + + + + data to search for + + + + + + + + + + + + + + + The notify signal is emitted on an object when one of its +properties has been changed. Note that getting this signal +doesn't guarantee that the value of the property has actually +changed, it may also be emitted when the setter for the property +is called to reinstate the previous value. + +This signal is typically used to obtain change notification for a +single property, by specifying the property name as a detail in the +g_signal_connect() call, like this: +|[<!-- language="C" --> +g_signal_connect (text_view->buffer, "notify::paste-target-list", + G_CALLBACK (gtk_text_view_target_list_notify), + text_view) +]| +It is important to note that you must use +[canonical][canonical-parameter-name] parameter names as +detail strings for the notify signal. + + + + + + the #GParamSpec of the property which changed. + + + + + + + The class structure for the GObject type. + +<example> +<title>Implementing singletons using a constructor</title> +<programlisting> +static MySingleton *the_singleton = NULL; + +static GObject* +my_singleton_constructor (GType type, + guint n_construct_params, + GObjectConstructParam *construct_params) +{ + GObject *object; + + if (!the_singleton) + { + object = G_OBJECT_CLASS (parent_class)->constructor (type, + n_construct_params, + construct_params); + the_singleton = MY_SINGLETON (object); + } + else + object = g_object_ref (G_OBJECT (the_singleton)); + + return object; +} +</programlisting></example> + + the parent class + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GObject + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Looks up the #GParamSpec for a property of a class. + + the #GParamSpec for the property, or + %NULL if the class doesn't have a property of that name + + + + + a #GObjectClass + + + + the name of the property to look up + + + + + + Installs new properties from an array of #GParamSpecs. + +All properties should be installed during the class initializer. It +is possible to install properties after that, but doing so is not +recommend, and specifically, is not guaranteed to be thread-safe vs. +use of properties on the same type on other threads. + +The property id of each property is the index of each #GParamSpec in +the @pspecs array. + +The property id of 0 is treated specially by #GObject and it should not +be used to store a #GParamSpec. + +This function should be used if you plan to use a static array of +#GParamSpecs and g_object_notify_by_pspec(). For instance, this +class initialization: + +|[<!-- language="C" --> +enum { + PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES +}; + +static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, }; + +static void +my_object_class_init (MyObjectClass *klass) +{ + GObjectClass *gobject_class = G_OBJECT_CLASS (klass); + + obj_properties[PROP_FOO] = + g_param_spec_int ("foo", "Foo", "Foo", + -1, G_MAXINT, + 0, + G_PARAM_READWRITE); + + obj_properties[PROP_BAR] = + g_param_spec_string ("bar", "Bar", "Bar", + NULL, + G_PARAM_READWRITE); + + gobject_class->set_property = my_object_set_property; + gobject_class->get_property = my_object_get_property; + g_object_class_install_properties (gobject_class, + N_PROPERTIES, + obj_properties); +} +]| + +allows calling g_object_notify_by_pspec() to notify of property changes: + +|[<!-- language="C" --> +void +my_object_set_foo (MyObject *self, gint foo) +{ + if (self->foo != foo) + { + self->foo = foo; + g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]); + } + } +]| + + + + + + a #GObjectClass + + + + the length of the #GParamSpecs array + + + + the #GParamSpecs array + defining the new properties + + + + + + + + Installs a new property. + +All properties should be installed during the class initializer. It +is possible to install properties after that, but doing so is not +recommend, and specifically, is not guaranteed to be thread-safe vs. +use of properties on the same type on other threads. + +Note that it is possible to redefine a property in a derived class, +by installing a property with the same name. This can be useful at times, +e.g. to change the range of allowed values or the default value. + + + + + + a #GObjectClass + + + + the id for the new property + + + + the #GParamSpec for the new property + + + + + + Get an array of #GParamSpec* for all properties of a class. + + an array of + #GParamSpec* which should be freed after use + + + + + + + a #GObjectClass + + + + return location for the length of the returned array + + + + + + Registers @property_id as referring to a property with the name +@name in a parent class or in an interface implemented by @oclass. +This allows this class to "override" a property implementation in +a parent class or to provide the implementation of a property from +an interface. + +Internally, overriding is implemented by creating a property of type +#GParamSpecOverride; generally operations that query the properties of +the object class, such as g_object_class_find_property() or +g_object_class_list_properties() will return the overridden +property. However, in one case, the @construct_properties argument of +the @constructor virtual function, the #GParamSpecOverride is passed +instead, so that the @param_id field of the #GParamSpec will be +correct. For virtually all uses, this makes no difference. If you +need to get the overridden property, you can call +g_param_spec_get_redirect_target(). + + + + + + a #GObjectClass + + + + the new property ID + + + + the name of a property registered in a parent class or + in an interface of this class. + + + + + + + The GObjectConstructParam struct is an auxiliary +structure used to hand #GParamSpec/#GValue pairs to the @constructor of +a #GObjectClass. + + the #GParamSpec of the construct parameter + + + + the value to set the parameter to + + + + + The type of the @finalize function of #GObjectClass. + + + + + + the #GObject being finalized + + + + + + The type of the @get_property function of #GObjectClass. + + + + + + a #GObject + + + + the numeric id under which the property was registered with + g_object_class_install_property(). + + + + a #GValue to return the property value in + + + + the #GParamSpec describing the property + + + + + + The type of the @set_property function of #GObjectClass. + + + + + + a #GObject + + + + the numeric id under which the property was registered with + g_object_class_install_property(). + + + + the new value for the property + + + + the #GParamSpec describing the property + + + + + + Mask containing the bits of #GParamSpec.flags which are reserved for GLib. + + + + #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. + +Since 2.13.0 + + + + Minimum shift count to be used for user defined flags, to be stored in +#GParamSpec.flags. The maximum allowed is 10. + + + + Through the #GParamFlags flag values, certain aspects of parameters +can be configured. See also #G_PARAM_STATIC_STRINGS. + + the parameter is readable + + + the parameter is writable + + + alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE + + + the parameter will be set upon object construction + + + the parameter can only be set upon object construction + + + upon parameter conversion (see g_param_value_convert()) + strict validation is not required + + + the string used as name when constructing the + parameter is guaranteed to remain valid and + unmodified for the lifetime of the parameter. + Since 2.8 + + + internal + + + the string used as nick when constructing the + parameter is guaranteed to remain valid and + unmmodified for the lifetime of the parameter. + Since 2.8 + + + the string used as blurb when constructing the + parameter is guaranteed to remain valid and + unmodified for the lifetime of the parameter. + Since 2.8 + + + calls to g_object_set_property() for this + property will not automatically result in a "notify" signal being + emitted: the implementation must call g_object_notify() themselves + in case the property actually changes. Since: 2.42. + + + the parameter is deprecated and will be removed + in a future version. A warning will be generated if it is used + while running with G_ENABLE_DIAGNOSTIC=1. + Since 2.26 + + + + #GParamSpec is an object structure that encapsulates the metadata +required to specify parameters, such as e.g. #GObject properties. + +## Parameter names # {#canonical-parameter-names} + +Parameter names need to start with a letter (a-z or A-Z). +Subsequent characters can be letters, numbers or a '-'. +All other characters are replaced by a '-' during construction. +The result of this replacement is called the canonical name of +the parameter. + + Creates a new #GParamSpec instance. + +A property name consists of segments consisting of ASCII letters and +digits, separated by either the '-' or '_' character. The first +character of a property name must be a letter. Names which violate these +rules lead to undefined behaviour. + +When creating and looking up a #GParamSpec, either separator can be +used, but they cannot be mixed. Using '-' is considerably more +efficient and in fact required when using property names as detail +strings for signals. + +Beyond the name, #GParamSpecs have two more descriptive +strings associated with them, the @nick, which should be suitable +for use as a label for the property in a property editor, and the +@blurb, which should be a somewhat longer description, suitable for +e.g. a tooltip. The @nick and @blurb should ideally be localized. + + a newly allocated #GParamSpec instance + + + + + the #GType for the property; must be derived from #G_TYPE_PARAM + + + + the canonical name of the property + + + + the nickname of the property + + + + a short description of the property + + + + a combination of #GParamFlags + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Get the short description of a #GParamSpec. + + the short description of @pspec. + + + + + a valid #GParamSpec + + + + + + Gets the default value of @pspec as a pointer to a #GValue. + +The #GValue will remain value for the life of @pspec. + + a pointer to a #GValue which must not be modified + + + + + a #GParamSpec + + + + + + Get the name of a #GParamSpec. + +The name is always an "interned" string (as per g_intern_string()). +This allows for pointer-value comparisons. + + the name of @pspec. + + + + + a valid #GParamSpec + + + + + + Gets the GQuark for the name. + + the GQuark for @pspec->name. + + + + + a #GParamSpec + + + + + + Get the nickname of a #GParamSpec. + + the nickname of @pspec. + + + + + a valid #GParamSpec + + + + + + Gets back user data pointers stored via g_param_spec_set_qdata(). + + the user data pointer set, or %NULL + + + + + a valid #GParamSpec + + + + a #GQuark, naming the user data pointer + + + + + + If the paramspec redirects operations to another paramspec, +returns that paramspec. Redirect is used typically for +providing a new implementation of a property in a derived +type while preserving all the properties from the parent +type. Redirection is established by creating a property +of type #GParamSpecOverride. See g_object_class_override_property() +for an example of the use of this capability. + + paramspec to which requests on this + paramspec should be redirected, or %NULL if none. + + + + + a #GParamSpec + + + + + + Increments the reference count of @pspec. + + the #GParamSpec that was passed into this function + + + + + a valid #GParamSpec + + + + + + Convenience function to ref and sink a #GParamSpec. + + the #GParamSpec that was passed into this function + + + + + a valid #GParamSpec + + + + + + Sets an opaque, named pointer on a #GParamSpec. The name is +specified through a #GQuark (retrieved e.g. via +g_quark_from_static_string()), and the pointer can be gotten back +from the @pspec with g_param_spec_get_qdata(). Setting a +previously set user data pointer, overrides (frees) the old pointer +set, using %NULL as pointer essentially removes the data stored. + + + + + + the #GParamSpec to set store a user data pointer + + + + a #GQuark, naming the user data pointer + + + + an opaque user data pointer + + + + + + This function works like g_param_spec_set_qdata(), but in addition, +a `void (*destroy) (gpointer)` function may be +specified which is called with @data as argument when the @pspec is +finalized, or the data is being overwritten by a call to +g_param_spec_set_qdata() with the same @quark. + + + + + + the #GParamSpec to set store a user data pointer + + + + a #GQuark, naming the user data pointer + + + + an opaque user data pointer + + + + function to invoke with @data as argument, when @data needs to + be freed + + + + + + The initial reference count of a newly created #GParamSpec is 1, +even though no one has explicitly called g_param_spec_ref() on it +yet. So the initial reference count is flagged as "floating", until +someone calls `g_param_spec_ref (pspec); g_param_spec_sink +(pspec);` in sequence on it, taking over the initial +reference count (thus ending up with a @pspec that has a reference +count of 1 still, but is not flagged "floating" anymore). + + + + + + a valid #GParamSpec + + + + + + Gets back user data pointers stored via g_param_spec_set_qdata() +and removes the @data from @pspec without invoking its destroy() +function (if any was set). Usually, calling this function is only +required to update user data pointers with a destroy notifier. + + the user data pointer set, or %NULL + + + + + the #GParamSpec to get a stored user data pointer from + + + + a #GQuark, naming the user data pointer + + + + + + Decrements the reference count of a @pspec. + + + + + + a valid #GParamSpec + + + + + + private #GTypeInstance portion + + + + name of this parameter: always an interned string + + + + #GParamFlags flags for this parameter + + + + the #GValue type for this parameter + + + + #GType type that uses (introduces) this parameter + + + + + + + + + + + + + + + + + + + + A #GParamSpec derived structure that contains the meta data for boolean properties. + + private #GParamSpec portion + + + + default value for the property specified + + + + + A #GParamSpec derived structure that contains the meta data for boxed properties. + + private #GParamSpec portion + + + + + A #GParamSpec derived structure that contains the meta data for character properties. + + private #GParamSpec portion + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + + The class structure for the GParamSpec type. +Normally, GParamSpec classes are filled by +g_param_type_register_static(). + + the parent class + + + + the #GValue type for this parameter + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A #GParamSpec derived structure that contains the meta data for double properties. + + private #GParamSpec portion + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + values closer than @epsilon will be considered identical + by g_param_values_cmp(); the default value is 1e-90. + + + + + A #GParamSpec derived structure that contains the meta data for enum +properties. + + private #GParamSpec portion + + + + the #GEnumClass for the enum + + + + default value for the property specified + + + + + A #GParamSpec derived structure that contains the meta data for flags +properties. + + private #GParamSpec portion + + + + the #GFlagsClass for the flags + + + + default value for the property specified + + + + + A #GParamSpec derived structure that contains the meta data for float properties. + + private #GParamSpec portion + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + values closer than @epsilon will be considered identical + by g_param_values_cmp(); the default value is 1e-30. + + + + + A #GParamSpec derived structure that contains the meta data for #GType properties. + + private #GParamSpec portion + + + + a #GType whose subtypes can occur as values + + + + + A #GParamSpec derived structure that contains the meta data for integer properties. + + private #GParamSpec portion + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + + A #GParamSpec derived structure that contains the meta data for 64bit integer properties. + + private #GParamSpec portion + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + + A #GParamSpec derived structure that contains the meta data for long integer properties. + + private #GParamSpec portion + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + + A #GParamSpec derived structure that contains the meta data for object properties. + + private #GParamSpec portion + + + + + This is a type of #GParamSpec type that simply redirects operations to +another paramspec. All operations other than getting or +setting the value are redirected, including accessing the nick and +blurb, validating a value, and so forth. See +g_param_spec_get_redirect_target() for retrieving the overidden +property. #GParamSpecOverride is used in implementing +g_object_class_override_property(), and will not be directly useful +unless you are implementing a new base type similar to GObject. + + + + + + + + + A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM +properties. + + private #GParamSpec portion + + + + + A #GParamSpec derived structure that contains the meta data for pointer properties. + + private #GParamSpec portion + + + + + A #GParamSpecPool maintains a collection of #GParamSpecs which can be +quickly accessed by owner and name. The implementation of the #GObject property +system uses such a pool to store the #GParamSpecs of the properties all object +types. + + Inserts a #GParamSpec in the pool. + + + + + + a #GParamSpecPool. + + + + the #GParamSpec to insert + + + + a #GType identifying the owner of @pspec + + + + + + Gets an array of all #GParamSpecs owned by @owner_type in +the pool. + + a newly + allocated array containing pointers to all #GParamSpecs + owned by @owner_type in the pool + + + + + + + a #GParamSpecPool + + + + the owner to look for + + + + return location for the length of the returned array + + + + + + Gets an #GList of all #GParamSpecs owned by @owner_type in +the pool. + + a + #GList of all #GParamSpecs owned by @owner_type in + the pool#GParamSpecs. + + + + + + + a #GParamSpecPool + + + + the owner to look for + + + + + + Looks up a #GParamSpec in the pool. + + The found #GParamSpec, or %NULL if no +matching #GParamSpec was found. + + + + + a #GParamSpecPool + + + + the name to look for + + + + the owner to look for + + + + If %TRUE, also try to find a #GParamSpec with @param_name + owned by an ancestor of @owner_type. + + + + + + Removes a #GParamSpec from the pool. + + + + + + a #GParamSpecPool + + + + the #GParamSpec to remove + + + + + + Creates a new #GParamSpecPool. + +If @type_prefixing is %TRUE, lookups in the newly created pool will +allow to specify the owner as a colon-separated prefix of the +property name, like "GtkContainer:border-width". This feature is +deprecated, so you should always set @type_prefixing to %FALSE. + + a newly allocated #GParamSpecPool. + + + + + Whether the pool will support type-prefixed property names. + + + + + + + A #GParamSpec derived structure that contains the meta data for string +properties. + + private #GParamSpec portion + + + + default value for the property specified + + + + a string containing the allowed values for the first byte + + + + a string containing the allowed values for the subsequent bytes + + + + the replacement byte for bytes which don't match @cset_first or @cset_nth. + + + + replace empty string by %NULL + + + + replace %NULL strings by an empty string + + + + + This structure is used to provide the type system with the information +required to initialize and destruct (finalize) a parameter's class and +instances thereof. +The initialized structure is passed to the g_param_type_register_static() +The type system will perform a deep copy of this structure, so its memory +does not need to be persistent across invocation of +g_param_type_register_static(). + + Size of the instance (object) structure. + + + + Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the [slice allocator][glib-Memory-Slices] now. + + + + + + + + + + + + + + + + The #GType of values conforming to this #GParamSpec + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A #GParamSpec derived structure that contains the meta data for unsigned character properties. + + private #GParamSpec portion + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + + A #GParamSpec derived structure that contains the meta data for unsigned integer properties. + + private #GParamSpec portion + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + + A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. + + private #GParamSpec portion + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + + A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. + + private #GParamSpec portion + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + + A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. + + private #GParamSpec portion + + + + default value for the property specified + + + + + A #GParamSpec derived structure that contains the meta data for #GValueArray properties. + + private #GParamSpec portion + + + + a #GParamSpec describing the elements contained in arrays of this property, may be %NULL + + + + if greater than 0, arrays of this property will always have this many elements + + + + + A #GParamSpec derived structure that contains the meta data for #GVariant properties. + + private #GParamSpec portion + + + + a #GVariantType, or %NULL + + + + a #GVariant, or %NULL + + + + + + + + + + The GParameter struct is an auxiliary structure used +to hand parameter name/value pairs to g_object_newv(). + + the parameter name + + + + the parameter value + + + + + A mask for all #GSignalFlags bits. + + + + A mask for all #GSignalMatchType bits. + + + + The signal accumulator is a special callback function that can be used +to collect return values of the various callbacks that are called +during a signal emission. The signal accumulator is specified at signal +creation time, if it is left %NULL, no accumulation of callback return +values is performed. The return value of signal emissions is then the +value returned by the last callback. + + The accumulator function returns whether the signal emission + should be aborted. Returning %FALSE means to abort the + current emission and %TRUE is returned for continuation. + + + + + Signal invocation hint, see #GSignalInvocationHint. + + + + Accumulator to collect callback return values in, this + is the return value of the current signal emission. + + + + A #GValue holding the return value of the signal handler. + + + + Callback data that was specified when creating the signal. + + + + + + A simple function pointer to get invoked when the signal is emitted. This +allows you to tie a hook to the signal type, so that it will trap all +emissions of that signal, from any object. + +You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. + + whether it wants to stay connected. If it returns %FALSE, the signal + hook is disconnected (and destroyed). + + + + + Signal invocation hint, see #GSignalInvocationHint. + + + + the number of parameters to the function, including + the instance on which the signal was emitted. + + + + the instance on which + the signal was emitted, followed by the parameters of the emission. + + + + + + user data associated with the hook. + + + + + + The signal flags are used to specify a signal's behaviour, the overall +signal description outlines how especially the RUN flags control the +stages of a signal emission. + + Invoke the object method handler in the first emission stage. + + + Invoke the object method handler in the third emission stage. + + + Invoke the object method handler in the last emission stage. + + + Signals being emitted for an object while currently being in + emission for this very object will not be emitted recursively, + but instead cause the first emission to be restarted. + + + This signal supports "::detail" appendices to the signal name + upon handler connections and emissions. + + + Action signals are signals that may freely be emitted on alive + objects from user code via g_signal_emit() and friends, without + the need of being embedded into extra code that performs pre or + post emission adjustments on the object. They can also be thought + of as object methods which can be called generically by + third-party code. + + + No emissions hooks are supported for this signal. + + + Varargs signal emission will always collect the + arguments, even if there are no signal handlers connected. Since 2.30. + + + The signal is deprecated and will be removed + in a future version. A warning will be generated if it is connected while + running with G_ENABLE_DIAGNOSTIC=1. Since 2.32. + + + + The #GSignalInvocationHint structure is used to pass on additional information +to callbacks during a signal emission. + + The signal id of the signal invoking the callback + + + + The detail passed on for this emission + + + + The stage the signal emission is currently in, this + field will contain one of %G_SIGNAL_RUN_FIRST, + %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. + + + + + The match types specify what g_signal_handlers_block_matched(), +g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() +match signals by. + + The signal id must be equal. + + + The signal detail be equal. + + + The closure must be the same. + + + The C closure callback must be the same. + + + The closure data must be the same. + + + Only unblocked signals may matched. + + + + A structure holding in-depth information for a specific signal. It is +filled in by the g_signal_query() function. + + The signal id of the signal being queried, or 0 if the + signal to be queried was unknown. + + + + The signal name. + + + + The interface/instance type that this signal can be emitted for. + + + + The signal flags as passed in to g_signal_new(). + + + + The return type for user callbacks. + + + + The number of parameters that user callbacks take. + + + + The individual parameter types for + user callbacks, note that the effective callback signature is: + |[<!-- language="C" --> + @return_type callback (#gpointer data1, + [param_types param_names,] + gpointer data2); + ]| + + + + + + + A bit in the type number that's supposed to be left untouched. + + + + An integer constant that represents the number of identifiers reserved +for types that are assigned at compile-time. + + + + Shift value used in converting numbers to type IDs. + + + + First fundamental type number to create a new fundamental type id with +G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. + + + + Last fundamental type number reserved for BSE. + + + + First fundamental type number to create a new fundamental type id with +G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. + + + + Last fundamental type number reserved for GLib. + + + + First available fundamental type number to create new fundamental +type id with G_TYPE_MAKE_FUNDAMENTAL(). + + + + A callback function used for notification when the state +of a toggle reference changes. See g_object_add_toggle_ref(). + + + + + + Callback data passed to g_object_add_toggle_ref() + + + + The object on which g_object_add_toggle_ref() was called. + + + + %TRUE if the toggle reference is now the + last reference to the object. %FALSE if the toggle + reference was the last reference and there are now other + references. + + + + + + A union holding one collected value. + + the field for holding integer values + + + + the field for holding long integer values + + + + the field for holding 64 bit integer values + + + + the field for holding floating point values + + + + the field for holding pointers + + + + + An opaque structure used as the base of all classes. + + + + + Registers a private structure for an instantiatable type. + +When an object is allocated, the private structures for +the type and all of its parent types are allocated +sequentially in the same memory block as the public +structures, and are zero-filled. + +Note that the accumulated size of the private structures of +a type and all its parent types cannot exceed 64 KiB. + +This function should be called in the type's class_init() function. +The private structure can be retrieved using the +G_TYPE_INSTANCE_GET_PRIVATE() macro. + +The following example shows attaching a private structure +MyObjectPrivate to an object MyObject defined in the standard +GObject fashion in the type's class_init() function. + +Note the use of a structure member "priv" to avoid the overhead +of repeatedly calling MY_OBJECT_GET_PRIVATE(). + +|[<!-- language="C" --> +typedef struct _MyObject MyObject; +typedef struct _MyObjectPrivate MyObjectPrivate; + +struct _MyObject { + GObject parent; + + MyObjectPrivate *priv; +}; + +struct _MyObjectPrivate { + int some_field; +}; + +static void +my_object_class_init (MyObjectClass *klass) +{ + g_type_class_add_private (klass, sizeof (MyObjectPrivate)); +} + +static void +my_object_init (MyObject *my_object) +{ + my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object, + MY_TYPE_OBJECT, + MyObjectPrivate); + // my_object->priv->some_field will be automatically initialised to 0 +} + +static int +my_object_get_some_field (MyObject *my_object) +{ + MyObjectPrivate *priv; + + g_return_val_if_fail (MY_IS_OBJECT (my_object), 0); + + priv = my_object->priv; + + return priv->some_field; +} +]| + + + + + + class structure for an instantiatable + type + + + + size of private structure + + + + + + Gets the offset of the private data for instances of @g_class. + +This is how many bytes you should add to the instance pointer of a +class in order to get the private data for the type represented by +@g_class. + +You can only call this function after you have registered a private +data area for @g_class using g_type_class_add_private(). + + the offset, in bytes + + + + + a #GTypeClass + + + + + + + + + + + + + + + + + + + This is a convenience function often needed in class initializers. +It returns the class structure of the immediate parent type of the +class passed in. Since derived classes hold a reference count on +their parent classes as long as they are instantiated, the returned +class will always exist. + +This function is essentially equivalent to: +g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))) + + the parent class + of @g_class + + + + + the #GTypeClass structure to + retrieve the parent class for + + + + + + Decrements the reference count of the class structure being passed in. +Once the last reference count of a class has been released, classes +may be finalized by the type system, so further dereferencing of a +class pointer after g_type_class_unref() are invalid. + + + + + + a #GTypeClass structure to unref + + + + + + A variant of g_type_class_unref() for use in #GTypeClassCacheFunc +implementations. It unreferences a class without consulting the chain +of #GTypeClassCacheFuncs, avoiding the recursion which would occur +otherwise. + + + + + + a #GTypeClass structure to unref + + + + + + + + + + + + + + + + + + + This function is essentially the same as g_type_class_ref(), +except that the classes reference count isn't incremented. +As a consequence, this function may return %NULL if the class +of the type passed in does not currently exist (hasn't been +referenced before). + + the #GTypeClass + structure for the given type ID or %NULL if the class does not + currently exist + + + + + type ID of a classed type + + + + + + A more efficient version of g_type_class_peek() which works only for +static types. + + the #GTypeClass + structure for the given type ID or %NULL if the class does not + currently exist or is dynamically loaded + + + + + type ID of a classed type + + + + + + Increments the reference count of the class structure belonging to +@type. This function will demand-create the class if it doesn't +exist already. + + the #GTypeClass + structure for the given type ID + + + + + type ID of a classed type + + + + + + + A callback function which is called when the reference count of a class +drops to zero. It may use g_type_class_ref() to prevent the class from +being freed. You should not call g_type_class_unref() from a +#GTypeClassCacheFunc function to prevent infinite recursion, use +g_type_class_unref_uncached() instead. + +The functions have to check the class id passed in to figure +whether they actually want to cache the class of this type, since all +classes are routed through the same #GTypeClassCacheFunc chain. + + %TRUE to stop further #GTypeClassCacheFuncs from being + called, %FALSE to continue + + + + + data that was given to the g_type_add_class_cache_func() call + + + + The #GTypeClass structure which is + unreferenced + + + + + + These flags used to be passed to g_type_init_with_debug_flags() which +is now deprecated. + +If you need to enable debugging features, use the GOBJECT_DEBUG +environment variable. + g_type_init() is now done automatically + + Print no messages + + + Print messages about object bookkeeping + + + Print messages about signal emissions + + + Keep a count of instances of each type + + + Mask covering all debug flags + + + + Bit masks used to check or determine characteristics of a type. + + Indicates an abstract type. No instances can be + created for an abstract type + + + Indicates an abstract value type, i.e. a type + that introduces a value table, but can't be used for + g_value_init() + + + + Bit masks used to check or determine specific characteristics of a +fundamental type. + + Indicates a classed type + + + Indicates an instantiable type (implies classed) + + + Indicates a flat derivable type + + + Indicates a deep derivable type (implies derivable) + + + + A structure that provides information to the type system which is +used specifically for managing fundamental types. + + #GTypeFundamentalFlags describing the characteristics of the fundamental type + + + + + This structure is used to provide the type system with the information +required to initialize and destruct (finalize) a type's class and +its instances. + +The initialized structure is passed to the g_type_register_static() function +(or is copied into the provided #GTypeInfo structure in the +g_type_plugin_complete_type_info()). The type system will perform a deep +copy of this structure, so its memory does not need to be persistent +across invocation of g_type_register_static(). + + Size of the class structure (required for interface, classed and instantiatable types) + + + + Location of the base initialization function (optional) + + + + Location of the base finalization function (optional) + + + + Location of the class initialization function for + classed and instantiatable types. Location of the default vtable + inititalization function for interface types. (optional) This function + is used both to fill in virtual functions in the class or default vtable, + and to do type-specific setup such as registering signals and object + properties. + + + + Location of the class finalization function for + classed and instantiatable types. Location of the default vtable + finalization function for interface types. (optional) + + + + User-supplied data passed to the class init/finalize functions + + + + Size of the instance (object) structure (required for instantiatable types only) + + + + Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the [slice allocator][glib-Memory-Slices] now. + + + + Location of the instance initialization function (optional, for instantiatable types only) + + + + A #GTypeValueTable function table for generic handling of GValues + of this type (usually only useful for fundamental types) + + + + + An opaque structure used as the base of all type instances. + + + + + + + + + + + + + + + + + + + An opaque structure used as the base of all interface types. + + + + + + + + Returns the corresponding #GTypeInterface structure of the parent type +of the instance type to which @g_iface belongs. This is useful when +deriving the implementation of an interface from the parent type and +then possibly overriding some methods. + + the + corresponding #GTypeInterface structure of the parent type of the + instance type to which @g_iface belongs, or %NULL if the parent + type doesn't conform to the interface + + + + + a #GTypeInterface structure + + + + + + Adds @prerequisite_type to the list of prerequisites of @interface_type. +This means that any type implementing @interface_type must also implement +@prerequisite_type. Prerequisites can be thought of as an alternative to +interface derivation (which GType doesn't support). An interface can have +at most one instantiatable prerequisite type. + + + + + + #GType value of an interface type + + + + #GType value of an interface or instantiatable type + + + + + + Returns the #GTypePlugin structure for the dynamic interface +@interface_type which has been added to @instance_type, or %NULL +if @interface_type has not been added to @instance_type or does +not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). + + the #GTypePlugin for the dynamic + interface @interface_type of @instance_type + + + + + #GType of an instantiatable type + + + + #GType of an interface type + + + + + + Returns the #GTypeInterface structure of an interface to which the +passed in class conforms. + + the #GTypeInterface + structure of @iface_type if implemented by @instance_class, %NULL + otherwise + + + + + a #GTypeClass structure + + + + an interface ID which this class conforms to + + + + + + Returns the prerequisites of an interfaces type. + + a + newly-allocated zero-terminated array of #GType containing + the prerequisites of @interface_type + + + + + + + an interface type + + + + location to return the number + of prerequisites, or %NULL + + + + + + + A callback called after an interface vtable is initialized. +See g_type_add_interface_check(). + + + + + + data passed to g_type_add_interface_check() + + + + the interface that has been + initialized + + + + + + #GTypeModule provides a simple implementation of the #GTypePlugin +interface. The model of #GTypeModule is a dynamically loaded module +which implements some number of types and interface implementations. +When the module is loaded, it registers its types and interfaces +using g_type_module_register_type() and g_type_module_add_interface(). +As long as any instances of these types and interface implementations +are in use, the module is kept loaded. When the types and interfaces +are gone, the module may be unloaded. If the types and interfaces +become used again, the module will be reloaded. Note that the last +unref cannot happen in module code, since that would lead to the +caller's code being unloaded before g_object_unref() returns to it. + +Keeping track of whether the module should be loaded or not is done by +using a use count - it starts at zero, and whenever it is greater than +zero, the module is loaded. The use count is maintained internally by +the type system, but also can be explicitly controlled by +g_type_module_use() and g_type_module_unuse(). Typically, when loading +a module for the first type, g_type_module_use() will be used to load +it so that it can initialize its types. At some later point, when the +module no longer needs to be loaded except for the type +implementations it contains, g_type_module_unuse() is called. + +#GTypeModule does not actually provide any implementation of module +loading and unloading. To create a particular module type you must +derive from #GTypeModule and implement the load and unload functions +in #GTypeModuleClass. + + + + + + + + + + + + + + + + + + + + + + + Registers an additional interface for a type, whose interface lives +in the given type plugin. If the interface was already registered +for the type in this plugin, nothing will be done. + +As long as any instances of the type exist, the type plugin will +not be unloaded. + + + + + + a #GTypeModule + + + + type to which to add the interface. + + + + interface type to add + + + + type information structure + + + + + + Looks up or registers an enumeration that is implemented with a particular +type plugin. If a type with name @type_name was previously registered, +the #GType identifier for the type is returned, otherwise the type +is newly registered, and the resulting #GType identifier returned. + +As long as any instances of the type exist, the type plugin will +not be unloaded. + + the new or existing type ID + + + + + a #GTypeModule + + + + name for the type + + + + an array of #GEnumValue structs for the + possible enumeration values. The array is + terminated by a struct with all members being + 0. + + + + + + Looks up or registers a flags type that is implemented with a particular +type plugin. If a type with name @type_name was previously registered, +the #GType identifier for the type is returned, otherwise the type +is newly registered, and the resulting #GType identifier returned. + +As long as any instances of the type exist, the type plugin will +not be unloaded. + + the new or existing type ID + + + + + a #GTypeModule + + + + name for the type + + + + an array of #GFlagsValue structs for the + possible flags values. The array is + terminated by a struct with all members being + 0. + + + + + + Looks up or registers a type that is implemented with a particular +type plugin. If a type with name @type_name was previously registered, +the #GType identifier for the type is returned, otherwise the type +is newly registered, and the resulting #GType identifier returned. + +When reregistering a type (typically because a module is unloaded +then reloaded, and reinitialized), @module and @parent_type must +be the same as they were previously. + +As long as any instances of the type exist, the type plugin will +not be unloaded. + + the new or existing type ID + + + + + a #GTypeModule + + + + the type for the parent class + + + + name for the type + + + + type information structure + + + + flags field providing details about the type + + + + + + Sets the name for a #GTypeModule + + + + + + a #GTypeModule. + + + + a human-readable name to use in error messages. + + + + + + Decreases the use count of a #GTypeModule by one. If the +result is zero, the module will be unloaded. (However, the +#GTypeModule will not be freed, and types associated with the +#GTypeModule are not unregistered. Once a #GTypeModule is +initialized, it must exist forever.) + + + + + + a #GTypeModule + + + + + + Increases the use count of a #GTypeModule by one. If the +use count was zero before, the plugin will be loaded. +If loading the plugin fails, the use count is reset to +its prior value. + + %FALSE if the plugin needed to be loaded and + loading the plugin failed. + + + + + a #GTypeModule + + + + + + + + + + + + + + + + + + + + + + the name of the module + + + + + In order to implement dynamic loading of types based on #GTypeModule, +the @load and @unload functions in #GTypeModuleClass must be implemented. + + the parent class + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The GObject type system supports dynamic loading of types. +The #GTypePlugin interface is used to handle the lifecycle +of dynamically loaded types. It goes as follows: + +1. The type is initially introduced (usually upon loading the module + the first time, or by your main application that knows what modules + introduces what types), like this: + |[<!-- language="C" --> + new_type_id = g_type_register_dynamic (parent_type_id, + "TypeName", + new_type_plugin, + type_flags); + ]| + where @new_type_plugin is an implementation of the + #GTypePlugin interface. + +2. The type's implementation is referenced, e.g. through + g_type_class_ref() or through g_type_create_instance() (this is + being called by g_object_new()) or through one of the above done on + a type derived from @new_type_id. + +3. This causes the type system to load the type's implementation by + calling g_type_plugin_use() and g_type_plugin_complete_type_info() + on @new_type_plugin. + +4. At some point the type's implementation isn't required anymore, + e.g. after g_type_class_unref() or g_type_free_instance() (called + when the reference count of an instance drops to zero). + +5. This causes the type system to throw away the information retrieved + from g_type_plugin_complete_type_info() and then it calls + g_type_plugin_unuse() on @new_type_plugin. + +6. Things may repeat from the second step. + +So basically, you need to implement a #GTypePlugin type that +carries a use_count, once use_count goes from zero to one, you need +to load the implementation to successfully handle the upcoming +g_type_plugin_complete_type_info() call. Later, maybe after +succeeding use/unuse calls, once use_count drops to zero, you can +unload the implementation again. The type system makes sure to call +g_type_plugin_use() and g_type_plugin_complete_type_info() again +when the type is needed again. + +#GTypeModule is an implementation of #GTypePlugin that already +implements most of this except for the actual module loading and +unloading. It even handles multiple registered types per module. + + Calls the @complete_interface_info function from the +#GTypePluginClass of @plugin. There should be no need to use this +function outside of the GObject type system itself. + + + + + + the #GTypePlugin + + + + the #GType of an instantiable type to which the interface + is added + + + + the #GType of the interface whose info is completed + + + + the #GInterfaceInfo to fill in + + + + + + Calls the @complete_type_info function from the #GTypePluginClass of @plugin. +There should be no need to use this function outside of the GObject +type system itself. + + + + + + a #GTypePlugin + + + + the #GType whose info is completed + + + + the #GTypeInfo struct to fill in + + + + the #GTypeValueTable to fill in + + + + + + Calls the @unuse_plugin function from the #GTypePluginClass of +@plugin. There should be no need to use this function outside of +the GObject type system itself. + + + + + + a #GTypePlugin + + + + + + Calls the @use_plugin function from the #GTypePluginClass of +@plugin. There should be no need to use this function outside of +the GObject type system itself. + + + + + + a #GTypePlugin + + + + + + + The #GTypePlugin interface is used by the type system in order to handle +the lifecycle of dynamically loaded types. + + + + + Increases the use count of the plugin. + + + + Decreases the use count of the plugin. + + + + Fills in the #GTypeInfo and + #GTypeValueTable structs for the type. The structs are initialized + with `memset(s, 0, sizeof (s))` before calling this function. + + + + Fills in missing parts of the #GInterfaceInfo + for the interface. The structs is initialized with + `memset(s, 0, sizeof (s))` before calling this function. + + + + + The type of the @complete_interface_info function of #GTypePluginClass. + + + + + + the #GTypePlugin + + + + the #GType of an instantiable type to which the interface + is added + + + + the #GType of the interface whose info is completed + + + + the #GInterfaceInfo to fill in + + + + + + The type of the @complete_type_info function of #GTypePluginClass. + + + + + + the #GTypePlugin + + + + the #GType whose info is completed + + + + the #GTypeInfo struct to fill in + + + + the #GTypeValueTable to fill in + + + + + + The type of the @unuse_plugin function of #GTypePluginClass. + + + + + + the #GTypePlugin whose use count should be decreased + + + + + + The type of the @use_plugin function of #GTypePluginClass, which gets called +to increase the use count of @plugin. + + + + + + the #GTypePlugin whose use count should be increased + + + + + + A structure holding information for a specific type. +It is filled in by the g_type_query() function. + + the #GType value of the type + + + + the name of the type + + + + the size of the class structure + + + + the size of the instance structure + + + + + The #GTypeValueTable provides the functions required by the #GValue +implementation, to serve as a container for values of a type. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A string format describing how to collect the contents of + this value bit-by-bit. Each character in the format represents + an argument to be collected, and the characters themselves indicate + the type of the argument. Currently supported arguments are: + - 'i' - Integers. passed as collect_values[].v_int. + - 'l' - Longs. passed as collect_values[].v_long. + - 'd' - Doubles. passed as collect_values[].v_double. + - 'p' - Pointers. passed as collect_values[].v_pointer. + It should be noted that for variable argument list construction, + ANSI C promotes every type smaller than an integer to an int, and + floats to doubles. So for collection of short int or char, 'i' + needs to be used, and for collection of floats 'd'. + + + + + + + + + + + + + + + + + + + + + + + + + Format description of the arguments to collect for @lcopy_value, + analogous to @collect_format. Usually, @lcopy_format string consists + only of 'p's to provide lcopy_value() with pointers to storage locations. + + + + + + + + + + + + + + + + + + + + + + + + + Returns the location of the #GTypeValueTable associated with @type. + +Note that this function should only be used from source code +that implements or has internal knowledge of the implementation of +@type. + + location of the #GTypeValueTable associated with @type or + %NULL if there is no #GTypeValueTable associated with @type + + + + + a #GType + + + + + + + The maximal number of #GTypeCValues which can be collected for a +single #GValue. + + + + If passed to G_VALUE_COLLECT(), allocated data won't be copied +but used verbatim. This does not affect ref-counted types like +objects. + + + + This is the signature of va_list marshaller functions, an optional +marshaller that can be used in some situations to avoid +marshalling the signal argument into GValues. + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue to store the return + value. May be %NULL if the callback of @closure doesn't return a + value. + + + + the instance on which the closure is + invoked. + + + + va_list of arguments to be passed to the closure. + + + + additional data specified when + registering the marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + the length of the @param_types array + + + + the #GType of each argument from + @args. + + + + + + + + An opaque structure used to hold different types of values. +The data within the structure has protected scope: it is accessible only +to functions within a #GTypeValueTable structure, or implementations of +the g_value_*() API. That is, code portions which implement new fundamental +types. +#GValue users cannot make any assumptions about how data is stored +within the 2 element @data union, and the @g_type member should +only be accessed through the G_VALUE_TYPE() macro. + + + + + + + + + + Copies the value of @src_value into @dest_value. + + + + + + An initialized #GValue structure. + + + + An initialized #GValue structure of the same type as @src_value. + + + + + + Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, +the boxed value is duplicated and needs to be later freed with +g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), +return_value); + + boxed contents of @value + + + + + a valid #GValue of %G_TYPE_BOXED derived type + + + + + + Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing +its reference count. If the contents of the #GValue are %NULL, then +%NULL will be returned. + + object content of @value, + should be unreferenced when no longer needed. + + + + + a valid #GValue whose type is derived from %G_TYPE_OBJECT + + + + + + Get the contents of a %G_TYPE_PARAM #GValue, increasing its +reference count. + + #GParamSpec content of @value, should be unreferenced when + no longer needed. + + + + + a valid #GValue whose type is derived from %G_TYPE_PARAM + + + + + + Get a copy the contents of a %G_TYPE_STRING #GValue. + + a newly allocated copy of the string content of @value + + + + + a valid #GValue of type %G_TYPE_STRING + + + + + + Get the contents of a variant #GValue, increasing its refcount. + + variant contents of @value, should be unrefed using + g_variant_unref() when no longer needed + + + + + a valid #GValue of type %G_TYPE_VARIANT + + + + + + Determines if @value will fit inside the size of a pointer value. +This is an internal function introduced mainly for C marshallers. + + %TRUE if @value will fit inside a pointer value. + + + + + An initialized #GValue structure. + + + + + + Get the contents of a %G_TYPE_BOOLEAN #GValue. + + boolean contents of @value + + + + + a valid #GValue of type %G_TYPE_BOOLEAN + + + + + + Get the contents of a %G_TYPE_BOXED derived #GValue. + + boxed contents of @value + + + + + a valid #GValue of %G_TYPE_BOXED derived type + + + + + + Do not use this function; it is broken on platforms where the %char +type is unsigned, such as ARM and PowerPC. See g_value_get_schar(). + +Get the contents of a %G_TYPE_CHAR #GValue. + This function's return type is broken, see g_value_get_schar() + + character contents of @value + + + + + a valid #GValue of type %G_TYPE_CHAR + + + + + + Get the contents of a %G_TYPE_DOUBLE #GValue. + + double contents of @value + + + + + a valid #GValue of type %G_TYPE_DOUBLE + + + + + + Get the contents of a %G_TYPE_ENUM #GValue. + + enum contents of @value + + + + + a valid #GValue whose type is derived from %G_TYPE_ENUM + + + + + + Get the contents of a %G_TYPE_FLAGS #GValue. + + flags contents of @value + + + + + a valid #GValue whose type is derived from %G_TYPE_FLAGS + + + + + + Get the contents of a %G_TYPE_FLOAT #GValue. + + float contents of @value + + + + + a valid #GValue of type %G_TYPE_FLOAT + + + + + + Get the contents of a %G_TYPE_GTYPE #GValue. + + the #GType stored in @value + + + + + a valid #GValue of type %G_TYPE_GTYPE + + + + + + Get the contents of a %G_TYPE_INT #GValue. + + integer contents of @value + + + + + a valid #GValue of type %G_TYPE_INT + + + + + + Get the contents of a %G_TYPE_INT64 #GValue. + + 64bit integer contents of @value + + + + + a valid #GValue of type %G_TYPE_INT64 + + + + + + Get the contents of a %G_TYPE_LONG #GValue. + + long integer contents of @value + + + + + a valid #GValue of type %G_TYPE_LONG + + + + + + Get the contents of a %G_TYPE_OBJECT derived #GValue. + + object contents of @value + + + + + a valid #GValue of %G_TYPE_OBJECT derived type + + + + + + Get the contents of a %G_TYPE_PARAM #GValue. + + #GParamSpec content of @value + + + + + a valid #GValue whose type is derived from %G_TYPE_PARAM + + + + + + Get the contents of a pointer #GValue. + + pointer contents of @value + + + + + a valid #GValue of %G_TYPE_POINTER + + + + + + Get the contents of a %G_TYPE_CHAR #GValue. + + signed 8 bit integer contents of @value + + + + + a valid #GValue of type %G_TYPE_CHAR + + + + + + Get the contents of a %G_TYPE_STRING #GValue. + + string content of @value + + + + + a valid #GValue of type %G_TYPE_STRING + + + + + + Get the contents of a %G_TYPE_UCHAR #GValue. + + unsigned character contents of @value + + + + + a valid #GValue of type %G_TYPE_UCHAR + + + + + + Get the contents of a %G_TYPE_UINT #GValue. + + unsigned integer contents of @value + + + + + a valid #GValue of type %G_TYPE_UINT + + + + + + Get the contents of a %G_TYPE_UINT64 #GValue. + + unsigned 64bit integer contents of @value + + + + + a valid #GValue of type %G_TYPE_UINT64 + + + + + + Get the contents of a %G_TYPE_ULONG #GValue. + + unsigned long integer contents of @value + + + + + a valid #GValue of type %G_TYPE_ULONG + + + + + + Get the contents of a variant #GValue. + + variant contents of @value + + + + + a valid #GValue of type %G_TYPE_VARIANT + + + + + + Initializes @value with the default value of @type. + + the #GValue structure that has been passed in + + + + + A zero-filled (uninitialized) #GValue structure. + + + + Type the #GValue should hold values of. + + + + + + Initializes and sets @value from an instantiatable type via the +value_table's collect_value() function. + +Note: The @value will be initialised with the exact type of +@instance. If you wish to set the @value's type to a different GType +(such as a parent class GType), you need to manually call +g_value_init() and g_value_set_instance(). + + + + + + An uninitialized #GValue structure. + + + + the instance + + + + + + Returns the value contents as pointer. This function asserts that +g_value_fits_pointer() returned %TRUE for the passed in value. +This is an internal function introduced mainly for C marshallers. + + the value contents as pointer + + + + + An initialized #GValue structure + + + + + + Clears the current value in @value and resets it to the default value +(as if the value had just been initialized). + + the #GValue structure that has been passed in + + + + + An initialized #GValue structure. + + + + + + Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. + + + + + + a valid #GValue of type %G_TYPE_BOOLEAN + + + + boolean value to be set + + + + + + Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. + + + + + + a valid #GValue of %G_TYPE_BOXED derived type + + + + boxed value to be set + + + + + + This is an internal function introduced mainly for C marshallers. + Use g_value_take_boxed() instead. + + + + + + a valid #GValue of %G_TYPE_BOXED derived type + + + + duplicated unowned boxed value to be set + + + + + + Set the contents of a %G_TYPE_CHAR #GValue to @v_char. + This function's input type is broken, see g_value_set_schar() + + + + + + a valid #GValue of type %G_TYPE_CHAR + + + + character value to be set + + + + + + Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. + + + + + + a valid #GValue of type %G_TYPE_DOUBLE + + + + double value to be set + + + + + + Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. + + + + + + a valid #GValue whose type is derived from %G_TYPE_ENUM + + + + enum value to be set + + + + + + Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. + + + + + + a valid #GValue whose type is derived from %G_TYPE_FLAGS + + + + flags value to be set + + + + + + Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. + + + + + + a valid #GValue of type %G_TYPE_FLOAT + + + + float value to be set + + + + + + Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. + + + + + + a valid #GValue of type %G_TYPE_GTYPE + + + + #GType to be set + + + + + + Sets @value from an instantiatable type via the +value_table's collect_value() function. + + + + + + An initialized #GValue structure. + + + + the instance + + + + + + Set the contents of a %G_TYPE_INT #GValue to @v_int. + + + + + + a valid #GValue of type %G_TYPE_INT + + + + integer value to be set + + + + + + Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. + + + + + + a valid #GValue of type %G_TYPE_INT64 + + + + 64bit integer value to be set + + + + + + Set the contents of a %G_TYPE_LONG #GValue to @v_long. + + + + + + a valid #GValue of type %G_TYPE_LONG + + + + long integer value to be set + + + + + + Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. + +g_value_set_object() increases the reference count of @v_object +(the #GValue holds a reference to @v_object). If you do not wish +to increase the reference count of the object (i.e. you wish to +pass your current reference to the #GValue because you no longer +need it), use g_value_take_object() instead. + +It is important that your #GValue holds a reference to @v_object (either its +own, or one it has taken) to ensure that the object won't be destroyed while +the #GValue still exists). + + + + + + a valid #GValue of %G_TYPE_OBJECT derived type + + + + object value to be set + + + + + + This is an internal function introduced mainly for C marshallers. + Use g_value_take_object() instead. + + + + + + a valid #GValue of %G_TYPE_OBJECT derived type + + + + object value to be set + + + + + + Set the contents of a %G_TYPE_PARAM #GValue to @param. + + + + + + a valid #GValue of type %G_TYPE_PARAM + + + + the #GParamSpec to be set + + + + + + This is an internal function introduced mainly for C marshallers. + Use g_value_take_param() instead. + + + + + + a valid #GValue of type %G_TYPE_PARAM + + + + the #GParamSpec to be set + + + + + + Set the contents of a pointer #GValue to @v_pointer. + + + + + + a valid #GValue of %G_TYPE_POINTER + + + + pointer value to be set + + + + + + Set the contents of a %G_TYPE_CHAR #GValue to @v_char. + + + + + + a valid #GValue of type %G_TYPE_CHAR + + + + signed 8 bit integer to be set + + + + + + Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. +The boxed value is assumed to be static, and is thus not duplicated +when setting the #GValue. + + + + + + a valid #GValue of %G_TYPE_BOXED derived type + + + + static boxed value to be set + + + + + + Set the contents of a %G_TYPE_STRING #GValue to @v_string. +The string is assumed to be static, and is thus not duplicated +when setting the #GValue. + + + + + + a valid #GValue of type %G_TYPE_STRING + + + + static string to be set + + + + + + Set the contents of a %G_TYPE_STRING #GValue to @v_string. + + + + + + a valid #GValue of type %G_TYPE_STRING + + + + caller-owned string to be duplicated for the #GValue + + + + + + This is an internal function introduced mainly for C marshallers. + Use g_value_take_string() instead. + + + + + + a valid #GValue of type %G_TYPE_STRING + + + + duplicated unowned string to be set + + + + + + Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. + + + + + + a valid #GValue of type %G_TYPE_UCHAR + + + + unsigned character value to be set + + + + + + Set the contents of a %G_TYPE_UINT #GValue to @v_uint. + + + + + + a valid #GValue of type %G_TYPE_UINT + + + + unsigned integer value to be set + + + + + + Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. + + + + + + a valid #GValue of type %G_TYPE_UINT64 + + + + unsigned 64bit integer value to be set + + + + + + Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. + + + + + + a valid #GValue of type %G_TYPE_ULONG + + + + unsigned long integer value to be set + + + + + + Set the contents of a variant #GValue to @variant. +If the variant is floating, it is consumed. + + + + + + a valid #GValue of type %G_TYPE_VARIANT + + + + a #GVariant, or %NULL + + + + + + Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed +and takes over the ownership of the callers reference to @v_boxed; +the caller doesn't have to unref it any more. + + + + + + a valid #GValue of %G_TYPE_BOXED derived type + + + + duplicated unowned boxed value to be set + + + + + + Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object +and takes over the ownership of the callers reference to @v_object; +the caller doesn't have to unref it any more (i.e. the reference +count of the object is not increased). + +If you want the #GValue to hold its own reference to @v_object, use +g_value_set_object() instead. + + + + + + a valid #GValue of %G_TYPE_OBJECT derived type + + + + object value to be set + + + + + + Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes +over the ownership of the callers reference to @param; the caller +doesn't have to unref it any more. + + + + + + a valid #GValue of type %G_TYPE_PARAM + + + + the #GParamSpec to be set + + + + + + Sets the contents of a %G_TYPE_STRING #GValue to @v_string. + + + + + + a valid #GValue of type %G_TYPE_STRING + + + + string to take ownership of + + + + + + Set the contents of a variant #GValue to @variant, and takes over +the ownership of the caller's reference to @variant; +the caller doesn't have to unref it any more (i.e. the reference +count of the variant is not increased). + +If @variant was floating then its floating reference is converted to +a hard reference. + +If you want the #GValue to hold its own reference to @variant, use +g_value_set_variant() instead. + +This is an internal function introduced mainly for C marshallers. + + + + + + a valid #GValue of type %G_TYPE_VARIANT + + + + a #GVariant, or %NULL + + + + + + Tries to cast the contents of @src_value into a type appropriate +to store in @dest_value, e.g. to transform a %G_TYPE_INT value +into a %G_TYPE_FLOAT value. Performing transformations between +value types might incur precision lossage. Especially +transformations into strings might reveal seemingly arbitrary +results and shouldn't be relied upon for production code (such +as rcfile value or object property serialization). + + Whether a transformation rule was found and could be applied. + Upon failing transformations, @dest_value is left untouched. + + + + + Source value. + + + + Target value. + + + + + + Clears the current value in @value (if any) and "unsets" the type, +this releases all resources associated with this GValue. An unset +value is the same as an uninitialized (zero-filled) #GValue +structure. + + + + + + An initialized #GValue structure. + + + + + + Registers a value transformation function for use in g_value_transform(). +A previously registered transformation function for @src_type and @dest_type +will be replaced. + + + + + + Source type. + + + + Target type. + + + + a function which transforms values of type @src_type + into value of type @dest_type + + + + + + Returns whether a #GValue of type @src_type can be copied into +a #GValue of type @dest_type. + + %TRUE if g_value_copy() is possible with @src_type and @dest_type. + + + + + source type to be copied. + + + + destination type for copying. + + + + + + Check whether g_value_transform() is able to transform values +of type @src_type into values of type @dest_type. Note that for +the types to be transformable, they must be compatible or a +transformation function must be registered. + + %TRUE if the transformation is possible, %FALSE otherwise. + + + + + Source type. + + + + Target type. + + + + + + + A #GValueArray contains an array of #GValue elements. + + number of values contained in the array + + + + array of values + + + + + + + Allocate and initialize a new #GValueArray, optionally preserve space +for @n_prealloced elements. New arrays always contain 0 elements, +regardless of the value of @n_prealloced. + Use #GArray and g_array_sized_new() instead. + + a newly allocated #GValueArray with 0 values + + + + + number of values to preallocate space for + + + + + + Insert a copy of @value as last element of @value_array. If @value is +%NULL, an uninitialized value is appended. + Use #GArray and g_array_append_val() instead. + + the #GValueArray passed in as @value_array + + + + + #GValueArray to add an element to + + + + #GValue to copy into #GValueArray, or %NULL + + + + + + Construct an exact copy of a #GValueArray by duplicating all its +contents. + Use #GArray and g_array_ref() instead. + + Newly allocated copy of #GValueArray + + + + + #GValueArray to copy + + + + + + Free a #GValueArray including its contents. + Use #GArray and g_array_unref() instead. + + + + + + #GValueArray to free + + + + + + Return a pointer to the value at @index_ containd in @value_array. + Use g_array_index() instead. + + pointer to a value at @index_ in @value_array + + + + + #GValueArray to get a value from + + + + index of the value of interest + + + + + + Insert a copy of @value at specified position into @value_array. If @value +is %NULL, an uninitialized value is inserted. + Use #GArray and g_array_insert_val() instead. + + the #GValueArray passed in as @value_array + + + + + #GValueArray to add an element to + + + + insertion position, must be <= value_array->;n_values + + + + #GValue to copy into #GValueArray, or %NULL + + + + + + Insert a copy of @value as first element of @value_array. If @value is +%NULL, an uninitialized value is prepended. + Use #GArray and g_array_prepend_val() instead. + + the #GValueArray passed in as @value_array + + + + + #GValueArray to add an element to + + + + #GValue to copy into #GValueArray, or %NULL + + + + + + Remove the value at position @index_ from @value_array. + Use #GArray and g_array_remove_index() instead. + + the #GValueArray passed in as @value_array + + + + + #GValueArray to remove an element from + + + + position of value to remove, which must be less than + @value_array->n_values + + + + + + Sort @value_array using @compare_func to compare the elements according to +the semantics of #GCompareFunc. + +The current implementation uses the same sorting algorithm as standard +C qsort() function. + Use #GArray and g_array_sort(). + + the #GValueArray passed in as @value_array + + + + + #GValueArray to sort + + + + function to compare elements + + + + + + Sort @value_array using @compare_func to compare the elements according +to the semantics of #GCompareDataFunc. + +The current implementation uses the same sorting algorithm as standard +C qsort() function. + Use #GArray and g_array_sort_with_data(). + + the #GValueArray passed in as @value_array + + + + + #GValueArray to sort + + + + function to compare elements + + + + extra data argument provided for @compare_func + + + + + + + The type of value transformation functions which can be registered with +g_value_register_transform_func(). + + + + + + Source value. + + + + Target value. + + + + + + A #GWeakNotify function can be added to an object as a callback that gets +triggered when the object is finalized. Since the object is already being +finalized when the #GWeakNotify is called, there's not much you could do +with the object, apart from e.g. using its address as hash-index or the like. + + + + + + data that was provided when the weak reference was established + + + + the object being finalized + + + + + + A structure containing a weak reference to a #GObject. It can either +be empty (i.e. point to %NULL), or point to an object for as long as +at least one "strong" reference to that object exists. Before the +object's #GObjectClass.dispose method is called, every #GWeakRef +associated with becomes empty (i.e. points to %NULL). + +Like #GValue, #GWeakRef can be statically allocated, stack- or +heap-allocated, or embedded in larger structures. + +Unlike g_object_weak_ref() and g_object_add_weak_pointer(), this weak +reference is thread-safe: converting a weak pointer to a reference is +atomic with respect to invalidation of weak pointers to destroyed +objects. + +If the object's #GObjectClass.dispose method results in additional +references to the object being held, any #GWeakRefs taken +before it was disposed will continue to point to %NULL. If +#GWeakRefs are taken after the object is disposed and +re-referenced, they will continue to point to it until its refcount +goes back to zero, at which point they too will be invalidated. + + + + + + + Frees resources associated with a non-statically-allocated #GWeakRef. +After this call, the #GWeakRef is left in an undefined state. + +You should only call this on a #GWeakRef that previously had +g_weak_ref_init() called on it. + + + + + + location of a weak reference, which + may be empty + + + + + + If @weak_ref is not empty, atomically acquire a strong +reference to the object it points to, and return that reference. + +This function is needed because of the potential race between taking +the pointer value and g_object_ref() on it, if the object was losing +its last reference at the same time in a different thread. + +The caller should release the resulting reference in the usual way, +by using g_object_unref(). + + the object pointed to + by @weak_ref, or %NULL if it was empty + + + + + location of a weak reference to a #GObject + + + + + + Initialise a non-statically-allocated #GWeakRef. + +This function also calls g_weak_ref_set() with @object on the +freshly-initialised weak reference. + +This function should always be matched with a call to +g_weak_ref_clear(). It is not necessary to use this function for a +#GWeakRef in static storage because it will already be +properly initialised. Just use g_weak_ref_set() directly. + + + + + + uninitialized or empty location for a weak + reference + + + + a #GObject or %NULL + + + + + + Change the object to which @weak_ref points, or set it to +%NULL. + +You must own a strong reference on @object while calling this +function. + + + + + + location for a weak reference + + + + a #GObject or %NULL + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. + + The newly created copy of the boxed + structure. + + + + + The type of @src_boxed. + + + + The boxed structure to be copied. + + + + + + Free the boxed structure @boxed which is of type @boxed_type. + + + + + + The type of @boxed. + + + + The boxed structure to be freed. + + + + + + This function creates a new %G_TYPE_BOXED derived type id for a new +boxed type with name @name. Boxed type handling functions have to be +provided to copy and free opaque boxed structures of this type. + + New %G_TYPE_BOXED derived type id for @name. + + + + + Name of the new boxed type. + + + + Boxed structure copy function. + + + + Boxed structure free function. + + + + + + A #GClosureMarshal function for use with signals with handlers that +take two boxed pointers as arguments and return a boolean. If you +have such a signal, you will probably also need to use an +accumulator, such as g_signal_accumulator_true_handled(). + + + + + + A #GClosure. + + + + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. + + + + The length of the @param_values array. + + + + An array of #GValues holding the arguments + on which to invoke the callback of closure. + + + + The invocation hint given as the last argument to + g_closure_invoke(). + + + + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + + + A marshaller for a #GCClosure with a callback of type +`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter +denotes a flags type. + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue which can store the returned #gboolean + + + + 2 + + + + a #GValue array holding instance and arg1 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + a #GValue, which can store the returned string + + + + 3 + + + + a #GValue array holding instance, arg1 and arg2 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gboolean parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GBoxed* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gchar parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gdouble parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the enumeration parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the flags parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gfloat parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gint parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #glong parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GObject* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GParamSpec* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gpointer parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gchar* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #guchar parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #guint parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 3 + + + + a #GValue array holding instance, arg1 and arg2 + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #gulong parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 2 + + + + a #GValue array holding the instance and the #GVariant* parameter + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A marshaller for a #GCClosure with a callback of type +`void (*callback) (gpointer instance, gpointer user_data)`. + + + + + + the #GClosure to which the marshaller belongs + + + + ignored + + + + 1 + + + + a #GValue array holding only the instance + + + + the invocation hint given as the last argument + to g_closure_invoke() + + + + additional data specified when registering the marshaller + + + + + + A generic marshaller function implemented via +[libffi](http://sourceware.org/libffi/). + +Normally this function is not passed explicitly to g_signal_new(), +but used automatically by GLib when specifying a %NULL marshaller. + + + + + + A #GClosure. + + + + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. + + + + The length of the @param_values array. + + + + An array of #GValues holding the arguments + on which to invoke the callback of closure. + + + + The invocation hint given as the last argument to + g_closure_invoke(). + + + + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() + + + + + + Creates a new closure which invokes @callback_func with @user_data as +the last parameter. + + a new #GCClosure + + + + + the function to invoke + + + + user data to pass to @callback_func + + + + destroy notify to be called when @user_data is no longer used + + + + + + A variant of g_cclosure_new() which uses @object as @user_data and +calls g_object_watch_closure() on @object and the created +closure. This function is useful when you have a callback closely +associated with a #GObject, and want the callback to no longer run +after the object is is freed. + + a new #GCClosure + + + + + the function to invoke + + + + a #GObject pointer to pass to @callback_func + + + + + + A variant of g_cclosure_new_swap() which uses @object as @user_data +and calls g_object_watch_closure() on @object and the created +closure. This function is useful when you have a callback closely +associated with a #GObject, and want the callback to no longer run +after the object is is freed. + + a new #GCClosure + + + + + the function to invoke + + + + a #GObject pointer to pass to @callback_func + + + + + + Creates a new closure which invokes @callback_func with @user_data as +the first parameter. + + a new #GCClosure + + + + + the function to invoke + + + + user data to pass to @callback_func + + + + destroy notify to be called when @user_data is no longer used + + + + + + Clears a reference to a #GObject. + +@object_ptr must not be %NULL. + +If the reference is %NULL then this function does nothing. +Otherwise, the reference count of the object is decreased and the +pointer is set to %NULL. + +A macro is also included that allows this function to be used without +pointer casts. + + + + + + a pointer to a #GObject reference + + + + + + This function is meant to be called from the `complete_type_info` +function of a #GTypePlugin implementation, as in the following +example: + +|[<!-- language="C" --> +static void +my_enum_complete_type_info (GTypePlugin *plugin, + GType g_type, + GTypeInfo *info, + GTypeValueTable *value_table) +{ + static const GEnumValue values[] = { + { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" }, + { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }, + { 0, NULL, NULL } + }; + + g_enum_complete_type_info (type, info, values); +} +]| + + + + + + the type identifier of the type being completed + + + + the #GTypeInfo struct to be filled in + + + + An array of #GEnumValue structs for the possible + enumeration values. The array is terminated by a struct with all + members being 0. + + + + + + Returns the #GEnumValue for a value. + + the #GEnumValue for @value, or %NULL + if @value is not a member of the enumeration + + + + + a #GEnumClass + + + + the value to look up + + + + + + Looks up a #GEnumValue by name. + + the #GEnumValue with name @name, + or %NULL if the enumeration doesn't have a member + with that name + + + + + a #GEnumClass + + + + the name to look up + + + + + + Looks up a #GEnumValue by nickname. + + the #GEnumValue with nickname @nick, + or %NULL if the enumeration doesn't have a member + with that nickname + + + + + a #GEnumClass + + + + the nickname to look up + + + + + + Registers a new static enumeration type with the name @name. + +It is normally more convenient to let [glib-mkenums][glib-mkenums], +generate a my_enum_get_type() function from a usual C enumeration +definition than to write one yourself using g_enum_register_static(). + + The new type identifier. + + + + + A nul-terminated string used as the name of the new type. + + + + An array of #GEnumValue structs for the possible + enumeration values. The array is terminated by a struct with all + members being 0. GObject keeps a reference to the data, so it cannot + be stack-allocated. + + + + + + This function is meant to be called from the complete_type_info() +function of a #GTypePlugin implementation, see the example for +g_enum_complete_type_info() above. + + + + + + the type identifier of the type being completed + + + + the #GTypeInfo struct to be filled in + + + + An array of #GFlagsValue structs for the possible + enumeration values. The array is terminated by a struct with all + members being 0. + + + + + + Returns the first #GFlagsValue which is set in @value. + + the first #GFlagsValue which is set in + @value, or %NULL if none is set + + + + + a #GFlagsClass + + + + the value + + + + + + Looks up a #GFlagsValue by name. + + the #GFlagsValue with name @name, + or %NULL if there is no flag with that name + + + + + a #GFlagsClass + + + + the name to look up + + + + + + Looks up a #GFlagsValue by nickname. + + the #GFlagsValue with nickname @nick, + or %NULL if there is no flag with that nickname + + + + + a #GFlagsClass + + + + the nickname to look up + + + + + + Registers a new static flags type with the name @name. + +It is normally more convenient to let [glib-mkenums][glib-mkenums] +generate a my_flags_get_type() function from a usual C enumeration +definition than to write one yourself using g_flags_register_static(). + + The new type identifier. + + + + + A nul-terminated string used as the name of the new type. + + + + An array of #GFlagsValue structs for the possible + flags values. The array is terminated by a struct with all members being 0. + GObject keeps a reference to the data, so it cannot be stack-allocated. + + + + + + + + + + + Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN +property. In many cases, it may be more appropriate to use an enum with +g_param_spec_enum(), both to improve code clarity by using explicitly named +values, and to allow for more values to be added in future without breaking +API. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED +derived property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + %G_TYPE_BOXED derived type of this property + + + + flags for the property specified + + + + + + Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE +property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM +property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + a #GType derived from %G_TYPE_ENUM + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS +property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + a #GType derived from %G_TYPE_FLAGS + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecGType instance specifying a +%G_TYPE_GTYPE property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + a #GType whose subtypes are allowed as values + of the property (use %G_TYPE_NONE for any type) + + + + flags for the property specified + + + + + + Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT +derived property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + %G_TYPE_OBJECT derived type of this property + + + + flags for the property specified + + + + + + Creates a new property of type #GParamSpecOverride. This is used +to direct operations to another paramspec, and will not be directly +useful unless you are implementing a new base type similar to GObject. + + the newly created #GParamSpec + + + + + the name of the property. + + + + The property that is being overridden + + + + + + Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM +property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + a #GType derived from %G_TYPE_PARAM + + + + flags for the property specified + + + + + + Creates a new #GParamSpecPointer instance specifying a pointer property. +Where possible, it is better to use g_param_spec_object() or +g_param_spec_boxed() to expose memory management information. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecPool. + +If @type_prefixing is %TRUE, lookups in the newly created pool will +allow to specify the owner as a colon-separated prefix of the +property name, like "GtkContainer:border-width". This feature is +deprecated, so you should always set @type_prefixing to %FALSE. + + a newly allocated #GParamSpecPool. + + + + + Whether the pool will support type-prefixed property names. + + + + + + Creates a new #GParamSpecString instance. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 +property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG +property. + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + minimum value for the property specified + + + + maximum value for the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT +property. #GValue structures for this property can be accessed with +g_value_set_uint() and g_value_get_uint(). + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + default value for the property specified + + + + flags for the property specified + + + + + + Creates a new #GParamSpecValueArray instance specifying a +%G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a +%G_TYPE_BOXED type, as such, #GValue structures for this property +can be accessed with g_value_set_boxed() and g_value_get_boxed(). + +See g_param_spec_internal() for details on property names. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + a #GParamSpec describing the elements contained in + arrays of this property, may be %NULL + + + + flags for the property specified + + + + + + Creates a new #GParamSpecVariant instance specifying a #GVariant +property. + +If @default_value is floating, it is consumed. + +See g_param_spec_internal() for details on property names. + + the newly created #GParamSpec + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + a #GVariantType + + + + a #GVariant of type @type to + use as the default value, or %NULL + + + + flags for the property specified + + + + + + Registers @name as the name of a new static type derived from +#G_TYPE_PARAM. The type system uses the information contained in +the #GParamSpecTypeInfo structure pointed to by @info to manage the +#GParamSpec type and its instances. + + The new type identifier. + + + + + 0-terminated string used as the name of the new #GParamSpec type. + + + + The #GParamSpecTypeInfo for this #GParamSpec type. + + + + + + Transforms @src_value into @dest_value if possible, and then +validates @dest_value, in order for it to conform to @pspec. If +@strict_validation is %TRUE this function will only succeed if the +transformed @dest_value complied to @pspec without modifications. + +See also g_value_type_transformable(), g_value_transform() and +g_param_value_validate(). + + %TRUE if transformation and validation were successful, + %FALSE otherwise and @dest_value is left untouched. + + + + + a valid #GParamSpec + + + + souce #GValue + + + + destination #GValue of correct type for @pspec + + + + %TRUE requires @dest_value to conform to @pspec +without modifications + + + + + + Checks whether @value contains the default value as specified in @pspec. + + whether @value contains the canonical default for this @pspec + + + + + a valid #GParamSpec + + + + a #GValue of correct type for @pspec + + + + + + Sets @value to its default value as specified in @pspec. + + + + + + a valid #GParamSpec + + + + a #GValue of correct type for @pspec + + + + + + Ensures that the contents of @value comply with the specifications +set out by @pspec. For example, a #GParamSpecInt might require +that integers stored in @value may not be smaller than -42 and not be +greater than +42. If @value contains an integer outside of this range, +it is modified accordingly, so the resulting value will fit into the +range -42 .. +42. + + whether modifying @value was necessary to ensure validity + + + + + a valid #GParamSpec + + + + a #GValue of correct type for @pspec + + + + + + Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, +if @value1 is found to be less than, equal to or greater than @value2, +respectively. + + -1, 0 or +1, for a less than, equal to or greater than result + + + + + a valid #GParamSpec + + + + a #GValue of correct type for @pspec + + + + a #GValue of correct type for @pspec + + + + + + Creates a new %G_TYPE_POINTER derived type id for a new +pointer type with name @name. + + a new %G_TYPE_POINTER derived type id for @name. + + + + + the name of the new pointer type. + + + + + + A predefined #GSignalAccumulator for signals intended to be used as a +hook for application code to provide a particular value. Usually +only one such value is desired and multiple handlers for the same +signal don't make much sense (except for the case of the default +handler defined in the class structure, in which case you will +usually want the signal connection to override the class handler). + +This accumulator will use the return value from the first signal +handler that is run as the return value for the signal and not run +any further handlers (ie: the first handler "wins"). + + standard #GSignalAccumulator result + + + + + standard #GSignalAccumulator parameter + + + + standard #GSignalAccumulator parameter + + + + standard #GSignalAccumulator parameter + + + + standard #GSignalAccumulator parameter + + + + + + A predefined #GSignalAccumulator for signals that return a +boolean values. The behavior that this accumulator gives is +that a return of %TRUE stops the signal emission: no further +callbacks will be invoked, while a return of %FALSE allows +the emission to continue. The idea here is that a %TRUE return +indicates that the callback handled the signal, and no further +handling is needed. + + standard #GSignalAccumulator result + + + + + standard #GSignalAccumulator parameter + + + + standard #GSignalAccumulator parameter + + + + standard #GSignalAccumulator parameter + + + + standard #GSignalAccumulator parameter + + + + + + Adds an emission hook for a signal, which will get called for any emission +of that signal, independent of the instance. This is possible only +for signals which don't have #G_SIGNAL_NO_HOOKS flag set. + + the hook id, for later use with g_signal_remove_emission_hook(). + + + + + the signal identifier, as returned by g_signal_lookup(). + + + + the detail on which to call the hook. + + + + a #GSignalEmissionHook function. + + + + user data for @hook_func. + + + + a #GDestroyNotify for @hook_data. + + + + + + Calls the original class closure of a signal. This function should only +be called from an overridden class closure; see +g_signal_override_class_closure() and +g_signal_override_class_handler(). + + + + + + the argument list of the signal emission. + The first element in the array is a #GValue for the instance the signal + is being emitted on. The rest are any arguments to be passed to the signal. + + + + + + Location for the return value. + + + + + + Calls the original class closure of a signal. This function should +only be called from an overridden class closure; see +g_signal_override_class_closure() and +g_signal_override_class_handler(). + + + + + + the instance the signal is being + emitted on. + + + + parameters to be passed to the parent class closure, followed by a + location for the return value. If the return type of the signal + is #G_TYPE_NONE, the return value location can be omitted. + + + + + + Connects a closure to a signal for a particular object. + + the handler id (always greater than 0 for successful connections) + + + + + the instance to connect to. + + + + a string of the form "signal-name::detail". + + + + the closure to connect. + + + + whether the handler should be called before or after the + default handler of the signal. + + + + + + Connects a closure to a signal for a particular object. + + the handler id (always greater than 0 for successful connections) + + + + + the instance to connect to. + + + + the id of the signal. + + + + the detail. + + + + the closure to connect. + + + + whether the handler should be called before or after the + default handler of the signal. + + + + + + Connects a #GCallback function to a signal for a particular object. Similar +to g_signal_connect(), but allows to provide a #GClosureNotify for the data +which will be called when the signal handler is disconnected and no longer +used. Specify @connect_flags if you need `..._after()` or +`..._swapped()` variants of this function. + + the handler id (always greater than 0 for successful connections) + + + + + the instance to connect to. + + + + a string of the form "signal-name::detail". + + + + the #GCallback to connect. + + + + data to pass to @c_handler calls. + + + + a #GClosureNotify for @data. + + + + a combination of #GConnectFlags. + + + + + + This is similar to g_signal_connect_data(), but uses a closure which +ensures that the @gobject stays alive during the call to @c_handler +by temporarily adding a reference count to @gobject. + +When the @gobject is destroyed the signal handler will be automatically +disconnected. Note that this is not currently threadsafe (ie: +emitting a signal while @gobject is being destroyed in another thread +is not safe). + + the handler id. + + + + + the instance to connect to. + + + + a string of the form "signal-name::detail". + + + + the #GCallback to connect. + + + + the object to pass as data + to @c_handler. + + + + a combination of #GConnectFlags. + + + + + + Emits a signal. + +Note that g_signal_emit() resets the return value to the default +if no handlers are connected, in contrast to g_signal_emitv(). + + + + + + the instance the signal is being emitted on. + + + + the signal id + + + + the detail + + + + parameters to be passed to the signal, followed by a + location for the return value. If the return type of the signal + is #G_TYPE_NONE, the return value location can be omitted. + + + + + + Emits a signal. + +Note that g_signal_emit_by_name() resets the return value to the default +if no handlers are connected, in contrast to g_signal_emitv(). + + + + + + the instance the signal is being emitted on. + + + + a string of the form "signal-name::detail". + + + + parameters to be passed to the signal, followed by a + location for the return value. If the return type of the signal + is #G_TYPE_NONE, the return value location can be omitted. + + + + + + Emits a signal. + +Note that g_signal_emit_valist() resets the return value to the default +if no handlers are connected, in contrast to g_signal_emitv(). + + + + + + the instance the signal is being + emitted on. + + + + the signal id + + + + the detail + + + + a list of parameters to be passed to the signal, followed by a + location for the return value. If the return type of the signal + is #G_TYPE_NONE, the return value location can be omitted. + + + + + + Emits a signal. + +Note that g_signal_emitv() doesn't change @return_value if no handlers are +connected, in contrast to g_signal_emit() and g_signal_emit_valist(). + + + + + + argument list for the signal emission. + The first element in the array is a #GValue for the instance the signal + is being emitted on. The rest are any arguments to be passed to the signal. + + + + + + the signal id + + + + the detail + + + + Location to +store the return value of the signal emission. This must be provided if the +specified signal returns a value, but may be ignored otherwise. + + + + + + Returns the invocation hint of the innermost signal emission of instance. + + the invocation hint of the innermost signal emission. + + + + + the instance to query + + + + + + Blocks a handler of an instance so it will not be called during any +signal emissions unless it is unblocked again. Thus "blocking" a +signal handler means to temporarily deactive it, a signal handler +has to be unblocked exactly the same amount of times it has been +blocked before to become active again. + +The @handler_id has to be a valid signal handler id, connected to a +signal of @instance. + + + + + + The instance to block the signal handler of. + + + + Handler id of the handler to be blocked. + + + + + + Disconnects a handler from an instance so it will not be called during +any future or currently ongoing emissions of the signal it has been +connected to. The @handler_id becomes invalid and may be reused. + +The @handler_id has to be a valid signal handler id, connected to a +signal of @instance. + + + + + + The instance to remove the signal handler from. + + + + Handler id of the handler to be disconnected. + + + + + + Finds the first signal handler that matches certain selection criteria. +The criteria mask is passed as an OR-ed combination of #GSignalMatchType +flags, and the criteria values are passed as arguments. +The match @mask has to be non-0 for successful matches. +If no handler was found, 0 is returned. + + A valid non-0 signal handler id for a successful match. + + + + + The instance owning the signal handler to be found. + + + + Mask indicating which of @signal_id, @detail, @closure, @func + and/or @data the handler has to match. + + + + Signal the handler has to be connected to. + + + + Signal detail the handler has to be connected to. + + + + The closure the handler will invoke. + + + + The C closure callback of the handler (useless for non-C closures). + + + + The closure data of the handler's closure. + + + + + + Returns whether @handler_id is the id of a handler connected to @instance. + + whether @handler_id identifies a handler connected to @instance. + + + + + The instance where a signal handler is sought. + + + + the handler id. + + + + + + Undoes the effect of a previous g_signal_handler_block() call. A +blocked handler is skipped during signal emissions and will not be +invoked, unblocking it (for exactly the amount of times it has been +blocked before) reverts its "blocked" state, so the handler will be +recognized by the signal system and is called upon future or +currently ongoing signal emissions (since the order in which +handlers are called during signal emissions is deterministic, +whether the unblocked handler in question is called as part of a +currently ongoing emission depends on how far that emission has +proceeded yet). + +The @handler_id has to be a valid id of a signal handler that is +connected to a signal of @instance and is currently blocked. + + + + + + The instance to unblock the signal handler of. + + + + Handler id of the handler to be unblocked. + + + + + + Blocks all handlers on an instance that match a certain selection criteria. +The criteria mask is passed as an OR-ed combination of #GSignalMatchType +flags, and the criteria values are passed as arguments. +Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC +or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. +If no handlers were found, 0 is returned, the number of blocked handlers +otherwise. + + The number of handlers that matched. + + + + + The instance to block handlers from. + + + + Mask indicating which of @signal_id, @detail, @closure, @func + and/or @data the handlers have to match. + + + + Signal the handlers have to be connected to. + + + + Signal detail the handlers have to be connected to. + + + + The closure the handlers will invoke. + + + + The C closure callback of the handlers (useless for non-C closures). + + + + The closure data of the handlers' closures. + + + + + + Destroy all signal handlers of a type instance. This function is +an implementation detail of the #GObject dispose implementation, +and should not be used outside of the type system. + + + + + + The instance whose signal handlers are destroyed + + + + + + Disconnects all handlers on an instance that match a certain +selection criteria. The criteria mask is passed as an OR-ed +combination of #GSignalMatchType flags, and the criteria values are +passed as arguments. Passing at least one of the +%G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or +%G_SIGNAL_MATCH_DATA match flags is required for successful +matches. If no handlers were found, 0 is returned, the number of +disconnected handlers otherwise. + + The number of handlers that matched. + + + + + The instance to remove handlers from. + + + + Mask indicating which of @signal_id, @detail, @closure, @func + and/or @data the handlers have to match. + + + + Signal the handlers have to be connected to. + + + + Signal detail the handlers have to be connected to. + + + + The closure the handlers will invoke. + + + + The C closure callback of the handlers (useless for non-C closures). + + + + The closure data of the handlers' closures. + + + + + + Unblocks all handlers on an instance that match a certain selection +criteria. The criteria mask is passed as an OR-ed combination of +#GSignalMatchType flags, and the criteria values are passed as arguments. +Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC +or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. +If no handlers were found, 0 is returned, the number of unblocked handlers +otherwise. The match criteria should not apply to any handlers that are +not currently blocked. + + The number of handlers that matched. + + + + + The instance to unblock handlers from. + + + + Mask indicating which of @signal_id, @detail, @closure, @func + and/or @data the handlers have to match. + + + + Signal the handlers have to be connected to. + + + + Signal detail the handlers have to be connected to. + + + + The closure the handlers will invoke. + + + + The C closure callback of the handlers (useless for non-C closures). + + + + The closure data of the handlers' closures. + + + + + + Returns whether there are any handlers connected to @instance for the +given signal id and detail. + +If @detail is 0 then it will only match handlers that were connected +without detail. If @detail is non-zero then it will match handlers +connected both without detail and with the given detail. This is +consistent with how a signal emitted with @detail would be delivered +to those handlers. + +Since 2.46 this also checks for a non-default class closure being +installed, as this is basically always what you want. + +One example of when you might use this is when the arguments to the +signal are difficult to compute. A class implementor may opt to not +emit the signal if no one is attached anyway, thus saving the cost +of building the arguments. + + %TRUE if a handler is connected to the signal, %FALSE + otherwise. + + + + + the object whose signal handlers are sought. + + + + the signal id. + + + + the detail. + + + + whether blocked handlers should count as match. + + + + + + Lists the signals by id that a certain instance or interface type +created. Further information about the signals can be acquired through +g_signal_query(). + + Newly allocated array of signal IDs. + + + + + + + Instance or interface type. + + + + Location to store the number of signal ids for @itype. + + + + + + Given the name of the signal and the type of object it connects to, gets +the signal's identifying integer. Emitting the signal by number is +somewhat faster than using the name each time. + +Also tries the ancestors of the given type. + +See g_signal_new() for details on allowed signal names. + + the signal's identifying number, or 0 if no signal was found. + + + + + the signal's name. + + + + the type that the signal operates on. + + + + + + Given the signal's identifier, finds its name. + +Two different signals may have the same name, if they have differing types. + + the signal name, or %NULL if the signal number was invalid. + + + + + the signal's identifying number. + + + + + + Creates a new signal. (This is usually done in the class initializer.) + +A signal name consists of segments consisting of ASCII letters and +digits, separated by either the '-' or '_' character. The first +character of a signal name must be a letter. Names which violate these +rules lead to undefined behaviour of the GSignal system. + +When registering a signal and looking up a signal, either separator can +be used, but they cannot be mixed. + +If 0 is used for @class_offset subclasses cannot override the class handler +in their class_init method by doing super_class->signal_handler = my_signal_handler. +Instead they will have to use g_signal_override_class_handler(). + +If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as +the marshaller for this signal. + + the signal id + + + + + the name for the signal + + + + the type this signal pertains to. It will also pertain to + types which are derived from this type. + + + + a combination of #GSignalFlags specifying detail of when + the default handler is to be invoked. You should at least specify + %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + + + + The offset of the function pointer in the class structure + for this type. Used to invoke a class method generically. Pass 0 to + not associate a class method slot with this signal. + + + + the accumulator for this signal; may be %NULL. + + + + user data for the @accumulator. + + + + the function to translate arrays of parameter + values to signal emissions into C language callback invocations or %NULL. + + + + the type of return value, or #G_TYPE_NONE for a signal + without a return value. + + + + the number of parameter types to follow. + + + + a list of types, one for each parameter. + + + + + + Creates a new signal. (This is usually done in the class initializer.) + +This is a variant of g_signal_new() that takes a C callback instead +off a class offset for the signal's class handler. This function +doesn't need a function pointer exposed in the class structure of +an object definition, instead the function pointer is passed +directly and can be overriden by derived classes with +g_signal_override_class_closure() or +g_signal_override_class_handler()and chained to with +g_signal_chain_from_overridden() or +g_signal_chain_from_overridden_handler(). + +See g_signal_new() for information about signal names. + +If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as +the marshaller for this signal. + + the signal id + + + + + the name for the signal + + + + the type this signal pertains to. It will also pertain to + types which are derived from this type. + + + + a combination of #GSignalFlags specifying detail of when + the default handler is to be invoked. You should at least specify + %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + + + + a #GCallback which acts as class implementation of + this signal. Used to invoke a class method generically. Pass %NULL to + not associate a class method with this signal. + + + + the accumulator for this signal; may be %NULL. + + + + user data for the @accumulator. + + + + the function to translate arrays of parameter + values to signal emissions into C language callback invocations or %NULL. + + + + the type of return value, or #G_TYPE_NONE for a signal + without a return value. + + + + the number of parameter types to follow. + + + + a list of types, one for each parameter. + + + + + + Creates a new signal. (This is usually done in the class initializer.) + +See g_signal_new() for details on allowed signal names. + +If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as +the marshaller for this signal. + + the signal id + + + + + the name for the signal + + + + the type this signal pertains to. It will also pertain to + types which are derived from this type. + + + + a combination of #GSignalFlags specifying detail of when + the default handler is to be invoked. You should at least specify + %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + + + + The closure to invoke on signal emission; may be %NULL. + + + + the accumulator for this signal; may be %NULL. + + + + user data for the @accumulator. + + + + the function to translate arrays of parameter + values to signal emissions into C language callback invocations or %NULL. + + + + the type of return value, or #G_TYPE_NONE for a signal + without a return value. + + + + the number of parameter types in @args. + + + + va_list of #GType, one for each parameter. + + + + + + Creates a new signal. (This is usually done in the class initializer.) + +See g_signal_new() for details on allowed signal names. + +If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as +the marshaller for this signal. + + the signal id + + + + + the name for the signal + + + + the type this signal pertains to. It will also pertain to + types which are derived from this type + + + + a combination of #GSignalFlags specifying detail of when + the default handler is to be invoked. You should at least specify + %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST + + + + The closure to invoke on signal emission; + may be %NULL + + + + the accumulator for this signal; may be %NULL + + + + user data for the @accumulator + + + + the function to translate arrays of + parameter values to signal emissions into C language callback + invocations or %NULL + + + + the type of return value, or #G_TYPE_NONE for a signal + without a return value + + + + the length of @param_types + + + + an array of types, one for + each parameter + + + + + + + + Overrides the class closure (i.e. the default handler) for the given signal +for emissions on instances of @instance_type. @instance_type must be derived +from the type to which the signal belongs. + +See g_signal_chain_from_overridden() and +g_signal_chain_from_overridden_handler() for how to chain up to the +parent class closure from inside the overridden one. + + + + + + the signal id + + + + the instance type on which to override the class closure + for the signal. + + + + the closure. + + + + + + Overrides the class closure (i.e. the default handler) for the +given signal for emissions on instances of @instance_type with +callback @class_handler. @instance_type must be derived from the +type to which the signal belongs. + +See g_signal_chain_from_overridden() and +g_signal_chain_from_overridden_handler() for how to chain up to the +parent class closure from inside the overridden one. + + + + + + the name for the signal + + + + the instance type on which to override the class handler + for the signal. + + + + the handler. + + + + + + Internal function to parse a signal name into its @signal_id +and @detail quark. + + Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. + + + + + a string of the form "signal-name::detail". + + + + The interface/instance type that introduced "signal-name". + + + + Location to store the signal id. + + + + Location to store the detail quark. + + + + %TRUE forces creation of a #GQuark for the detail. + + + + + + Queries the signal system for in-depth information about a +specific signal. This function will fill in a user-provided +structure to hold signal-specific information. If an invalid +signal id is passed in, the @signal_id member of the #GSignalQuery +is 0. All members filled into the #GSignalQuery structure should +be considered constant and have to be left untouched. + + + + + + The signal id of the signal to query information for. + + + + A user provided structure that is + filled in with constant values upon success. + + + + + + Deletes an emission hook. + + + + + + the id of the signal + + + + the id of the emission hook, as returned by + g_signal_add_emission_hook() + + + + + + Change the #GSignalCVaMarshaller used for a given signal. This is a +specialised form of the marshaller that can often be used for the +common case of a single connected signal handler and avoids the +overhead of #GValue. Its use is optional. + + + + + + the signal id + + + + the instance type on which to set the marshaller. + + + + the marshaller to set. + + + + + + Stops a signal's current emission. + +This will prevent the default method from running, if the signal was +%G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" +flag). + +Prints a warning if used on a signal which isn't being emitted. + + + + + + the object whose signal handlers you wish to stop. + + + + the signal identifier, as returned by g_signal_lookup(). + + + + the detail which the signal was emitted with. + + + + + + Stops a signal's current emission. + +This is just like g_signal_stop_emission() except it will look up the +signal id for you. + + + + + + the object whose signal handlers you wish to stop. + + + + a string of the form "signal-name::detail". + + + + + + Creates a new closure which invokes the function found at the offset +@struct_offset in the class structure of the interface or classed type +identified by @itype. + + a new #GCClosure + + + + + the #GType identifier of an interface or classed type + + + + the offset of the member function of @itype's class + structure which is to be invoked by the new closure + + + + + + Set the callback for a source as a #GClosure. + +If the source is not one of the standard GLib types, the @closure_callback +and @closure_marshal fields of the #GSourceFuncs structure must have been +filled in with pointers to appropriate functions. + + + + + + the source + + + + a #GClosure + + + + + + Sets a dummy callback for @source. The callback will do nothing, and +if the source expects a #gboolean return value, it will return %TRUE. +(If the source expects any other type of return value, it will return +a 0/%NULL value; whatever g_value_init() initializes a #GValue to for +that type.) + +If the source is not one of the standard GLib types, the +@closure_callback and @closure_marshal fields of the #GSourceFuncs +structure must have been filled in with pointers to appropriate +functions. + + + + + + the source + + + + + + Return a newly allocated string, which describes the contents of a +#GValue. The main purpose of this function is to describe #GValue +contents for debugging output, the way in which the contents are +described may change between different GLib versions. + + Newly allocated string. + + + + + #GValue which contents are to be described. + + + + + + Adds a #GTypeClassCacheFunc to be called before the reference count of a +class goes from one to zero. This can be used to prevent premature class +destruction. All installed #GTypeClassCacheFunc functions will be chained +until one of them returns %TRUE. The functions have to check the class id +passed in to figure whether they actually want to cache the class of this +type, since all classes are routed through the same #GTypeClassCacheFunc +chain. + + + + + + data to be passed to @cache_func + + + + a #GTypeClassCacheFunc + + + + + + Registers a private class structure for a classed type; +when the class is allocated, the private structures for +the class and all of its parent types are allocated +sequentially in the same memory block as the public +structures, and are zero-filled. + +This function should be called in the +type's get_type() function after the type is registered. +The private structure can be retrieved using the +G_TYPE_CLASS_GET_PRIVATE() macro. + + + + + + GType of an classed type + + + + size of private structure + + + + + + + + + + + + + + + + + + + Adds a function to be called after an interface vtable is +initialized for any class (i.e. after the @interface_init +member of #GInterfaceInfo has been called). + +This function is useful when you want to check an invariant +that depends on the interfaces of a class. For instance, the +implementation of #GObject uses this facility to check that an +object implements all of the properties that are defined on its +interfaces. + + + + + + data to pass to @check_func + + + + function to be called after each interface + is initialized + + + + + + Adds the dynamic @interface_type to @instantiable_type. The information +contained in the #GTypePlugin structure pointed to by @plugin +is used to manage the relationship. + + + + + + #GType value of an instantiable type + + + + #GType value of an interface type + + + + #GTypePlugin structure to retrieve the #GInterfaceInfo from + + + + + + Adds the static @interface_type to @instantiable_type. +The information contained in the #GInterfaceInfo structure +pointed to by @info is used to manage the relationship. + + + + + + #GType value of an instantiable type + + + + #GType value of an interface type + + + + #GInterfaceInfo structure for this + (@instance_type, @interface_type) combination + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Private helper function to aid implementation of the +G_TYPE_CHECK_INSTANCE() macro. + + %TRUE if @instance is valid, %FALSE otherwise + + + + + a valid #GTypeInstance structure + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Return a newly allocated and 0-terminated array of type IDs, listing +the child types of @type. + + Newly allocated + and 0-terminated array of child types, free with g_free() + + + + + + + the parent type + + + + location to store the length of + the returned array, or %NULL + + + + + + + + + + + + + + + + + + + This function is essentially the same as g_type_class_ref(), +except that the classes reference count isn't incremented. +As a consequence, this function may return %NULL if the class +of the type passed in does not currently exist (hasn't been +referenced before). + + the #GTypeClass + structure for the given type ID or %NULL if the class does not + currently exist + + + + + type ID of a classed type + + + + + + A more efficient version of g_type_class_peek() which works only for +static types. + + the #GTypeClass + structure for the given type ID or %NULL if the class does not + currently exist or is dynamically loaded + + + + + type ID of a classed type + + + + + + Increments the reference count of the class structure belonging to +@type. This function will demand-create the class if it doesn't +exist already. + + the #GTypeClass + structure for the given type ID + + + + + type ID of a classed type + + + + + + Creates and initializes an instance of @type if @type is valid and +can be instantiated. The type system only performs basic allocation +and structure setups for instances: actual instance creation should +happen through functions supplied by the type's fundamental type +implementation. So use of g_type_create_instance() is reserved for +implementators of fundamental types only. E.g. instances of the +#GObject hierarchy should be created via g_object_new() and never +directly through g_type_create_instance() which doesn't handle things +like singleton objects or object construction. + +The extended members of the returned instance are guaranteed to be filled +with zeros. + +Note: Do not use this function, unless you're implementing a +fundamental type. Also language bindings should not use this +function, but g_object_new() instead. + + an allocated and initialized instance, subject to further + treatment by the fundamental type implementation + + + + + an instantiatable type to create an instance for + + + + + + If the interface type @g_type is currently in use, returns its +default interface vtable. + + the default + vtable for the interface, or %NULL if the type is not currently + in use + + + + + an interface type + + + + + + Increments the reference count for the interface type @g_type, +and returns the default interface vtable for the type. + +If the type is not currently in use, then the default vtable +for the type will be created and initalized by calling +the base interface init and default vtable init functions for +the type (the @base_init and @class_init members of #GTypeInfo). +Calling g_type_default_interface_ref() is useful when you +want to make sure that signals and properties for an interface +have been installed. + + the default + vtable for the interface; call g_type_default_interface_unref() + when you are done using the interface. + + + + + an interface type + + + + + + Decrements the reference count for the type corresponding to the +interface default vtable @g_iface. If the type is dynamic, then +when no one is using the interface and all references have +been released, the finalize function for the interface's default +vtable (the @class_finalize member of #GTypeInfo) will be called. + + + + + + the default vtable + structure for a interface, as returned by g_type_default_interface_ref() + + + + + + Returns the length of the ancestry of the passed in type. This +includes the type itself, so that e.g. a fundamental type has depth 1. + + the depth of @type + + + + + a #GType + + + + + + Ensures that the indicated @type has been registered with the +type system, and its _class_init() method has been run. + +In theory, simply calling the type's _get_type() method (or using +the corresponding macro) is supposed take care of this. However, +_get_type() methods are often marked %G_GNUC_CONST for performance +reasons, even though this is technically incorrect (since +%G_GNUC_CONST requires that the function not have side effects, +which _get_type() methods do on the first call). As a result, if +you write a bare call to a _get_type() macro, it may get optimized +out by the compiler. Using g_type_ensure() guarantees that the +type's _get_type() method is called. + + + + + + a #GType + + + + + + Frees an instance of a type, returning it to the instance pool for +the type, if there is one. + +Like g_type_create_instance(), this function is reserved for +implementors of fundamental types. + + + + + + an instance of a type + + + + + + Lookup the type ID from a given type name, returning 0 if no type +has been registered under this name (this is the preferred method +to find out by name whether a specific type has been registered +yet). + + corresponding type ID or 0 + + + + + type name to lookup + + + + + + Internal function, used to extract the fundamental type ID portion. +Use G_TYPE_FUNDAMENTAL() instead. + + fundamental type ID + + + + + valid type ID + + + + + + Returns the next free fundamental type id which can be used to +register a new fundamental type with g_type_register_fundamental(). +The returned type ID represents the highest currently registered +fundamental type identifier. + + the next available fundamental type ID to be registered, + or 0 if the type system ran out of fundamental type IDs + + + + + Returns the number of instances allocated of the particular type; +this is only available if GLib is built with debugging support and +the instance_count debug flag is set (by setting the GOBJECT_DEBUG +variable to include instance-count). + + the number of instances allocated of the given type; + if instance counts are not available, returns 0. + + + + + a #GType + + + + + + Returns the #GTypePlugin structure for @type. + + the corresponding plugin + if @type is a dynamic type, %NULL otherwise + + + + + #GType to retrieve the plugin for + + + + + + Obtains data which has previously been attached to @type +with g_type_set_qdata(). + +Note that this does not take subtyping into account; data +attached to one type with g_type_set_qdata() cannot +be retrieved from a subtype using g_type_get_qdata(). + + the data, or %NULL if no data was found + + + + + a #GType + + + + a #GQuark id to identify the data + + + + + + Returns an opaque serial number that represents the state of the set +of registered types. Any time a type is registered this serial changes, +which means you can cache information based on type lookups (such as +g_type_from_name()) and know if the cache is still valid at a later +time by comparing the current serial with the one at the type lookup. + + An unsigned int, representing the state of type registrations + + + + + This function used to initialise the type system. Since GLib 2.36, +the type system is initialised automatically and this function does +nothing. + the type system is now initialised automatically + + + + + + This function used to initialise the type system with debugging +flags. Since GLib 2.36, the type system is initialised automatically +and this function does nothing. + +If you need to enable debugging features, use the GOBJECT_DEBUG +environment variable. + the type system is now initialised automatically + + + + + + bitwise combination of #GTypeDebugFlags values for + debugging purposes + + + + + + Adds @prerequisite_type to the list of prerequisites of @interface_type. +This means that any type implementing @interface_type must also implement +@prerequisite_type. Prerequisites can be thought of as an alternative to +interface derivation (which GType doesn't support). An interface can have +at most one instantiatable prerequisite type. + + + + + + #GType value of an interface type + + + + #GType value of an interface or instantiatable type + + + + + + Returns the #GTypePlugin structure for the dynamic interface +@interface_type which has been added to @instance_type, or %NULL +if @interface_type has not been added to @instance_type or does +not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). + + the #GTypePlugin for the dynamic + interface @interface_type of @instance_type + + + + + #GType of an instantiatable type + + + + #GType of an interface type + + + + + + Returns the #GTypeInterface structure of an interface to which the +passed in class conforms. + + the #GTypeInterface + structure of @iface_type if implemented by @instance_class, %NULL + otherwise + + + + + a #GTypeClass structure + + + + an interface ID which this class conforms to + + + + + + Returns the prerequisites of an interfaces type. + + a + newly-allocated zero-terminated array of #GType containing + the prerequisites of @interface_type + + + + + + + an interface type + + + + location to return the number + of prerequisites, or %NULL + + + + + + Return a newly allocated and 0-terminated array of type IDs, listing +the interface types that @type conforms to. + + Newly allocated + and 0-terminated array of interface types, free with g_free() + + + + + + + the type to list interface types for + + + + location to store the length of + the returned array, or %NULL + + + + + + If @is_a_type is a derivable type, check whether @type is a +descendant of @is_a_type. If @is_a_type is an interface, check +whether @type conforms to it. + + %TRUE if @type is a @is_a_type + + + + + type to check anchestry for + + + + possible anchestor of @type or interface that @type + could conform to + + + + + + Get the unique name that is assigned to a type ID. Note that this +function (like all other GType API) cannot cope with invalid type +IDs. %G_TYPE_INVALID may be passed to this function, as may be any +other validly registered type ID, but randomized type IDs should +not be passed in and will most likely lead to a crash. + + static type name or %NULL + + + + + type to return name for + + + + + + + + + + + + + + + + + + + + + + + + + + Given a @leaf_type and a @root_type which is contained in its +anchestry, return the type that @root_type is the immediate parent +of. In other words, this function determines the type that is +derived directly from @root_type which is also a base class of +@leaf_type. Given a root type and a leaf type, this function can +be used to determine the types and order in which the leaf type is +descended from the root type. + + immediate child of @root_type and anchestor of @leaf_type + + + + + descendant of @root_type and the type to be returned + + + + immediate parent of the returned type + + + + + + Return the direct parent type of the passed in type. If the passed +in type has no parent, i.e. is a fundamental type, 0 is returned. + + the parent type + + + + + the derived type + + + + + + Get the corresponding quark of the type IDs name. + + the type names quark or 0 + + + + + type to return quark of type name for + + + + + + Queries the type system for information about a specific type. +This function will fill in a user-provided structure to hold +type-specific information. If an invalid #GType is passed in, the +@type member of the #GTypeQuery is 0. All members filled into the +#GTypeQuery structure should be considered constant and have to be +left untouched. + + + + + + #GType of a static, classed type + + + + a user provided structure that is + filled in with constant values upon success + + + + + + Registers @type_name as the name of a new dynamic type derived from +@parent_type. The type system uses the information contained in the +#GTypePlugin structure pointed to by @plugin to manage the type and its +instances (if not abstract). The value of @flags determines the nature +(e.g. abstract or not) of the type. + + the new type identifier or #G_TYPE_INVALID if registration failed + + + + + type from which this type will be derived + + + + 0-terminated string used as the name of the new type + + + + #GTypePlugin structure to retrieve the #GTypeInfo from + + + + bitwise combination of #GTypeFlags values + + + + + + Registers @type_id as the predefined identifier and @type_name as the +name of a fundamental type. If @type_id is already registered, or a +type named @type_name is already registered, the behaviour is undefined. +The type system uses the information contained in the #GTypeInfo structure +pointed to by @info and the #GTypeFundamentalInfo structure pointed to by +@finfo to manage the type and its instances. The value of @flags determines +additional characteristics of the fundamental type. + + the predefined type identifier + + + + + a predefined type identifier + + + + 0-terminated string used as the name of the new type + + + + #GTypeInfo structure for this type + + + + #GTypeFundamentalInfo structure for this type + + + + bitwise combination of #GTypeFlags values + + + + + + Registers @type_name as the name of a new static type derived from +@parent_type. The type system uses the information contained in the +#GTypeInfo structure pointed to by @info to manage the type and its +instances (if not abstract). The value of @flags determines the nature +(e.g. abstract or not) of the type. + + the new type identifier + + + + + type from which this type will be derived + + + + 0-terminated string used as the name of the new type + + + + #GTypeInfo structure for this type + + + + bitwise combination of #GTypeFlags values + + + + + + Registers @type_name as the name of a new static type derived from +@parent_type. The value of @flags determines the nature (e.g. +abstract or not) of the type. It works by filling a #GTypeInfo +struct and calling g_type_register_static(). + + the new type identifier + + + + + type from which this type will be derived + + + + 0-terminated string used as the name of the new type + + + + size of the class structure (see #GTypeInfo) + + + + location of the class initialization function (see #GTypeInfo) + + + + size of the instance structure (see #GTypeInfo) + + + + location of the instance initialization function (see #GTypeInfo) + + + + bitwise combination of #GTypeFlags values + + + + + + Removes a previously installed #GTypeClassCacheFunc. The cache +maintained by @cache_func has to be empty when calling +g_type_remove_class_cache_func() to avoid leaks. + + + + + + data that was given when adding @cache_func + + + + a #GTypeClassCacheFunc + + + + + + Removes an interface check function added with +g_type_add_interface_check(). + + + + + + callback data passed to g_type_add_interface_check() + + + + callback function passed to g_type_add_interface_check() + + + + + + Attaches arbitrary data to a type. + + + + + + a #GType + + + + a #GQuark id to identify the data + + + + the data + + + + + + + + + + + + + + + + + + + Returns the location of the #GTypeValueTable associated with @type. + +Note that this function should only be used from source code +that implements or has internal knowledge of the implementation of +@type. + + location of the #GTypeValueTable associated with @type or + %NULL if there is no #GTypeValueTable associated with @type + + + + + a #GType + + + + + + Registers a value transformation function for use in g_value_transform(). +A previously registered transformation function for @src_type and @dest_type +will be replaced. + + + + + + Source type. + + + + Target type. + + + + a function which transforms values of type @src_type + into value of type @dest_type + + + + + + Returns whether a #GValue of type @src_type can be copied into +a #GValue of type @dest_type. + + %TRUE if g_value_copy() is possible with @src_type and @dest_type. + + + + + source type to be copied. + + + + destination type for copying. + + + + + + Check whether g_value_transform() is able to transform values +of type @src_type into values of type @dest_type. Note that for +the types to be transformable, they must be compatible or a +transformation function must be registered. + + %TRUE if the transformation is possible, %FALSE otherwise. + + + + + Source type. + + + + Target type. + + + + + + diff --git a/gir-files/Gst-1.0.gir b/gir-files/Gst-1.0.gir new file mode 100644 index 000000000..ee9137a3c --- /dev/null +++ b/gir-files/Gst-1.0.gir @@ -0,0 +1,48190 @@ + + + + + + + + + + + A datatype to hold the handle to an outstanding sync or async clock callback. + + + + A datatype to hold a time, measured in nanoseconds. + + + + A datatype to hold a time difference, measured in nanoseconds. + + + + + + + The allocator name for the default system memory allocator + + + + Parameters to control the allocation of memory + + flags to control allocation + + + + the desired alignment of the memory + + + + the desired prefix + + + + the desired padding + + + + + + + + + Create a copy of @params. + +Free-function: gst_allocation_params_free + + a new ##GstAllocationParams, free with +gst_allocation_params_free(). + + + + + a #GstAllocationParams + + + + + + Free @params + + + + + + a #GstAllocationParams + + + + + + Initialize @params to its default values + + + + + + a #GstAllocationParams + + + + + + + Memory is usually created by allocators with a gst_allocator_alloc() +method call. When %NULL is used as the allocator, the default allocator will +be used. + +New allocators can be registered with gst_allocator_register(). +Allocators are identified by name and can be retrieved with +gst_allocator_find(). gst_allocator_set_default() can be used to change the +default allocator. + +New memory can be created with gst_memory_new_wrapped() that wraps the memory +allocated elsewhere. + + Find a previously registered allocator with @name. When @name is %NULL, the +default allocator will be returned. + + a #GstAllocator or %NULL when +the allocator with @name was not registered. Use gst_object_unref() +to release the allocator after usage. + + + + + the name of the allocator + + + + + + Registers the memory @allocator with @name. This function takes ownership of +@allocator. + + + + + + the name of the allocator + + + + #GstAllocator + + + + + + Use @allocator to allocate a new memory block with memory that is at least +@size big. + +The optional @params can specify the prefix and padding for the memory. If +%NULL is passed, no flags, no extra prefix/padding and a default alignment is +used. + +The prefix/padding will be filled with 0 if flags contains +#GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively. + +When @allocator is %NULL, the default allocator will be used. + +The alignment in @params is given as a bitmask so that @align + 1 equals +the amount of bytes to align to. For example, to align to 8 bytes, +use an alignment of 7. + + a new #GstMemory. + + + + + a #GstAllocator to use + + + + size of the visible memory area + + + + optional parameters + + + + + + Free @memory that was previously allocated with gst_allocator_alloc(). + + + + + + a #GstAllocator to use + + + + the memory to free + + + + + + Use @allocator to allocate a new memory block with memory that is at least +@size big. + +The optional @params can specify the prefix and padding for the memory. If +%NULL is passed, no flags, no extra prefix/padding and a default alignment is +used. + +The prefix/padding will be filled with 0 if flags contains +#GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively. + +When @allocator is %NULL, the default allocator will be used. + +The alignment in @params is given as a bitmask so that @align + 1 equals +the amount of bytes to align to. For example, to align to 8 bytes, +use an alignment of 7. + + a new #GstMemory. + + + + + a #GstAllocator to use + + + + size of the visible memory area + + + + optional parameters + + + + + + Free @memory that was previously allocated with gst_allocator_alloc(). + + + + + + a #GstAllocator to use + + + + the memory to free + + + + + + Set the default allocator. This function takes ownership of @allocator. + + + + + + a #GstAllocator + + + + + + + + + + + + the implementation of the GstMemoryMapFunction + + + + the implementation of the GstMemoryUnmapFunction + + + + the implementation of the GstMemoryCopyFunction + + + + the implementation of the GstMemoryShareFunction + + + + the implementation of the GstMemoryIsSpanFunction + + + + the implementation of the GstMemoryMapFullFunction. + Will be used instead of @mem_map if present. (Since 1.6) + + + + the implementation of the GstMemoryUnmapFullFunction. + Will be used instead of @mem_unmap if present. (Since 1.6) + + + + + + + + + + + + + The #GstAllocator is used to create new memory. + + Object parent class + + + + + + a new #GstMemory. + + + + + a #GstAllocator to use + + + + size of the visible memory area + + + + optional parameters + + + + + + + + + + + + + a #GstAllocator to use + + + + the memory to free + + + + + + + + + + + + + Flags for allocators. + + The allocator has a custom alloc function. + + + first flag that can be used for custom purposes + + + + + + The #GstAtomicQueue object implements a queue that can be used from multiple +threads without performing any blocking operations. + + Create a new atomic queue instance. @initial_size will be rounded up to the +nearest power of 2 and used as the initial size of the queue. + + a new #GstAtomicQueue + + + + + initial queue size + + + + + + Get the amount of items in the queue. + + the number of elements in the queue. + + + + + a #GstAtomicQueue + + + + + + Peek the head element of the queue without removing it from the queue. + + the head element of @queue or +%NULL when the queue is empty. + + + + + a #GstAtomicQueue + + + + + + Get the head element of the queue. + + the head element of @queue or %NULL when +the queue is empty. + + + + + a #GstAtomicQueue + + + + + + Append @data to the tail of the queue. + + + + + + a #GstAtomicQueue + + + + the data + + + + + + Increase the refcount of @queue. + + + + + + a #GstAtomicQueue + + + + + + Unref @queue and free the memory when the refcount reaches 0. + + + + + + a #GstAtomicQueue + + + + + + + Combination of all possible fields that can be copied with +gst_buffer_copy_into(). + + + + Combination of all possible metadata fields that can be copied with +gst_buffer_copy_into(). + + + + Constant for no-offset return results. + + + + #GstBin is an element that can contain other #GstElement, allowing them to be +managed as a group. +Pads from the child elements can be ghosted to the bin, see #GstGhostPad. +This makes the bin look like any other elements and enables creation of +higher-level abstraction elements. + +A new #GstBin is created with gst_bin_new(). Use a #GstPipeline instead if you +want to create a toplevel bin because a normal bin doesn't have a bus or +handle clock distribution of its own. + +After the bin has been created you will typically add elements to it with +gst_bin_add(). You can remove elements with gst_bin_remove(). + +An element can be retrieved from a bin with gst_bin_get_by_name(), using the +elements name. gst_bin_get_by_name_recurse_up() is mainly used for internal +purposes and will query the parent bins when the element is not found in the +current bin. + +An iterator of elements in a bin can be retrieved with +gst_bin_iterate_elements(). Various other iterators exist to retrieve the +elements in a bin. + +gst_object_unref() is used to drop your reference to the bin. + +The #GstBin::element-added signal is fired whenever a new element is added to +the bin. Likewise the #GstBin::element-removed signal is fired whenever an +element is removed from the bin. + +## Notes + +A #GstBin internally intercepts every #GstMessage posted by its children and +implements the following default behaviour for each of them: + +* GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING +state. If all sinks posted the EOS message, this bin will post and EOS +message upwards. + +* GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards. +The messages are used to decide when all elements have completed playback +of their segment. + +* GST_MESSAGE_SEGMENT_DONE: Is posted by #GstBin when all elements that posted +a SEGMENT_START have posted a SEGMENT_DONE. + +* GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change +in the stream duration. The default bin behaviour is to clear any +cached duration values so that the next duration query will perform +a full duration recalculation. The duration change is posted to the +application so that it can refetch the new duration with a duration +query. Note that these messages can be posted before the bin is +prerolled, in which case the duration query might fail. + +* GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it +can no longer provide a clock. The default bin behaviour is to +check if the lost clock was the one provided by the bin. If so and +the bin is currently in the PLAYING state, the message is forwarded to +the bin parent. +This message is also generated when a clock provider is removed from +the bin. If this message is received by the application, it should +PAUSE the pipeline and set it back to PLAYING to force a new clock +distribution. + +* GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element +can provide a clock. This mostly happens when a new clock +provider is added to the bin. The default behaviour of the bin is to +mark the currently selected clock as dirty, which will perform a clock +recalculation the next time the bin is asked to provide a clock. +This message is never sent tot the application but is forwarded to +the parent of the bin. + +* OTHERS: posted upwards. + +A #GstBin implements the following default behaviour for answering to a +#GstQuery: + +* GST_QUERY_DURATION:If the query has been asked before with the same format +and the bin is a toplevel bin (ie. has no parent), +use the cached previous value. If no previous value was cached, the +query is sent to all sink elements in the bin and the MAXIMUM of all +values is returned. If the bin is a toplevel bin the value is cached. +If no sinks are available in the bin, the query fails. + +* GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the +MAXIMUM of all values is returned. If no sinks are available in the bin, +the query fails. + +* OTHERS:the query is forwarded to all sink elements, the result +of the first sink that answers the query successfully is returned. If no +sink is in the bin, the query fails. + +A #GstBin will by default forward any event sent to it to all sink +(#GST_EVENT_TYPE_DOWNSTREAM) or source (#GST_EVENT_TYPE_UPSTREAM) elements +depending on the event type. +If all the elements return %TRUE, the bin will also return %TRUE, else %FALSE +is returned. If no elements of the required type are in the bin, the event +handler will return %TRUE. + + + Creates a new bin with the given name. + + a new #GstBin + + + + + the name of the new bin + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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. + +If the element's pads are linked to other pads, the pads will be unlinked +before the element is added to the bin. + +> When you add an element to an already-running pipeline, you will have to +> take care to set the state of the newly-added element to the desired +> state (usually PLAYING or PAUSED, same you set the pipeline to originally) +> with gst_element_set_state(), or use gst_element_sync_state_with_parent(). +> The bin or pipeline will not take care of this for you. + +MT safe. + + %TRUE if the element could be added, %FALSE if +the bin does not want to accept the element. + + + + + a #GstBin + + + + the #GstElement to add + + + + + + 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 +value of each gst_bin_add() is ignored. + + + + + + a #GstBin + + + + the #GstElement element to add to the bin + + + + additional elements to add to the bin + + + + + + Recursively looks for elements with an unlinked pad of the given +direction within the specified bin and returns an unlinked pad +if one is found, or %NULL otherwise. If a pad is found, the caller +owns a reference to it and should use gst_object_unref() on the +pad when it is not needed any longer. + + unlinked pad of the given +direction, %NULL. + + + + + bin in which to look for elements with unlinked pads + + + + whether to look for an unlinked source or sink pad + + + + + + Looks for an element inside the bin that implements the given +interface. If such an element is found, it returns the element. +You can cast this element to the given interface afterwards. If you want +all elements that implement the interface, use +gst_bin_iterate_all_by_interface(). This function recurses into child bins. + +MT safe. Caller owns returned reference. + + A #GstElement inside the bin implementing the interface + + + + + a #GstBin + + + + the #GType of an interface + + + + + + Gets the element with the given name from a bin. This +function recurses into child bins. + +Returns %NULL if no element with the given name is found in the bin. + +MT safe. Caller owns returned reference. + + the #GstElement with the given +name, or %NULL + + + + + a #GstBin + + + + the element name to search for + + + + + + Gets the element with the given name from this bin. If the +element is not found, a recursion is performed on the parent bin. + +Returns %NULL if: +- no element with the given name is found in the bin + +MT safe. Caller owns returned reference. + + the #GstElement with the given +name, or %NULL + + + + + a #GstBin + + + + the element name to search for + + + + + + Return the suppressed flags of the bin. + +MT safe. + + the bin's suppressed #GstElementFlags. + + + + + a #GstBin + + + + + + Looks for all elements inside the bin that implements the given +interface. You can safely cast all returned elements to the given interface. +The function recurses inside child bins. The iterator will yield a series +of #GstElement that should be unreffed after use. + +MT safe. Caller owns returned value. + + a #GstIterator of #GstElement + for all elements in the bin implementing the given interface, + or %NULL + + + + + a #GstBin + + + + the #GType of an interface + + + + + + Gets an iterator for the elements in this bin. + +MT safe. Caller owns returned value. + + a #GstIterator of #GstElement, +or %NULL + + + + + a #GstBin + + + + + + Gets an iterator for the elements in this bin. +This iterator recurses into GstBin children. + +MT safe. Caller owns returned value. + + a #GstIterator of #GstElement, +or %NULL + + + + + a #GstBin + + + + + + Gets an iterator for all elements in the bin that have the +#GST_ELEMENT_FLAG_SINK flag set. + +MT safe. Caller owns returned value. + + a #GstIterator of #GstElement, +or %NULL + + + + + a #GstBin + + + + + + Gets an iterator for the elements in this bin in topologically +sorted order. This means that the elements are returned from +the most downstream elements (sinks) to the sources. + +This function is used internally to perform the state changes +of the bin elements and for clock selection. + +MT safe. Caller owns returned value. + + a #GstIterator of #GstElement, +or %NULL + + + + + a #GstBin + + + + + + Gets an iterator for all elements in the bin that have the +#GST_ELEMENT_FLAG_SOURCE flag set. + +MT safe. Caller owns returned value. + + a #GstIterator of #GstElement, +or %NULL + + + + + a #GstBin + + + + + + Query @bin for the current latency using and reconfigures this latency to all the +elements with a LATENCY event. + +This method is typically called on the pipeline when a #GST_MESSAGE_LATENCY +is posted on the bus. + +This function simply emits the 'do-latency' signal so any custom latency +calculations will be performed. + + %TRUE if the latency could be queried and reconfigured. + + + + + a #GstBin + + + + + + Removes the element from the bin, unparenting it as well. +Unparenting the element means that the element will be dereferenced, +so if the bin holds the only reference to the element, the element +will be freed in the process of removing it from the bin. If you +want the element to still exist after removing, you need to call +gst_object_ref() before removing it from the bin. + +If the element's pads are linked to other pads, the pads will be unlinked +before the element is removed from the bin. + +MT safe. + + %TRUE if the element could be removed, %FALSE if +the bin does not want to remove the element. + + + + + a #GstBin + + + + the #GstElement to remove + + + + + + Remove a list of elements from a bin. This function is equivalent +to calling gst_bin_remove() with each member of the list. + + + + + + a #GstBin + + + + the first #GstElement to remove from the bin + + + + %NULL-terminated list of elements to remove from the bin + + + + + + Suppress the given flags on the bin. #GstElementFlags of a +child element are propagated when it is added to the bin. +When suppressed flags are set, those specified flags will +not be propagated to the bin. + +MT safe. + + + + + + a #GstBin + + + + the #GstElementFlags to suppress + + + + + + Synchronizes the state of every child of @bin with the state +of @bin. See also gst_element_sync_state_with_parent(). + + %TRUE if syncing the state was successful for all children, + otherwise %FALSE. + + + + + a #GstBin + + + + + + If set to %TRUE, the bin will handle asynchronous state changes. +This should be used only if the bin subclass is modifying the state +of its children on its own. + + + + Forward all children messages, even those that would normally be filtered by +the bin. This can be interesting when one wants to be notified of the EOS +state of individual elements, for example. + +The messages are converted to an ELEMENT message with the bin as the +source. The structure of the message is named 'GstBinForwarded' and contains +a field named 'message' of type GST_TYPE_MESSAGE that contains the original +forwarded message. + + + + + + + the number of children in this bin + + + + the list of children in this bin + + + + + + updated whenever @children changes + + + + internal bus for handling child messages + + + + queued and cached messages + + + + + + the bin is currently calculating its state + + + + the bin needs to recalculate its state (deprecated) + + + + the bin needs to select a new clock + + + + the last clock selected + + + + the element that provided @provided_clock + + + + + + + + + + + + Will be emitted after the element was added to sub_bin. + + + + + + the #GstBin the element was added to + + + + the #GstElement that was added to @sub_bin + + + + + + Will be emitted after the element was removed from sub_bin. + + + + + + the #GstBin the element was removed from + + + + the #GstElement that was removed from @sub_bin + + + + + + Will be emitted when the bin needs to perform latency calculations. This +signal is only emitted for toplevel bins or when async-handling is +enabled. + +Only one signal handler is invoked. If no signals are connected, the +default handler is invoked, which will query and distribute the lowest +possible latency to all sinks. + +Connect to this signal if the default latency calculations are not +sufficient, like when you need different latencies for different sinks in +the same pipeline. + + + + + + Will be emitted after the element was added to the bin. + + + + + + the #GstElement that was added to the bin + + + + + + Will be emitted after the element was removed from the bin. + + + + + + the #GstElement that was removed from the bin + + + + + + + Subclasses can override the @add_element and @remove_element to +update the list of children in the bin. + +The @handle_message method can be overridden to implement custom +message handling. @handle_message takes ownership of the message, just like +#gst_element_post_message. + +The @deep_element_added vfunc will be called when a new element has been +added to any bin inside this bin, so it will also be called if a new child +was added to a sub-bin of this bin. #GstBin implementations that override +this message should chain up to the parent class implementation so the +element-added-deep signal is emitted on all parents. + + bin parent class + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + GstBinFlags are a set of flags specific to bins. Most are set/used +internally. They can be checked using the GST_OBJECT_FLAG_IS_SET () macro, +and (un)set using GST_OBJECT_FLAG_SET () and GST_OBJECT_FLAG_UNSET (). + + don't resync a state change when elements are + added or linked in the bin (Since 1.0.5) + + + Indicates whether the bin can handle elements + that add/remove source pads at any point in time without + first posting a no-more-pads signal (Since 1.10) + + + the last enum in the series of flags for bins. +Derived classes can use this as first value in a list of flags. + + + + + + + + Buffers are the basic unit of data transfer in GStreamer. They contain the +timing and offset along with other arbitrary metadata that is associated +with the #GstMemory blocks that the buffer contains. + +Buffers are usually created with gst_buffer_new(). After a buffer has been +created one will typically allocate memory for it and add it to the buffer. +The following example creates a buffer that can hold a given video frame +with a given width, height and bits per plane. +|[<!-- language="C" --> + GstBuffer *buffer; + GstMemory *memory; + gint size, width, height, bpp; + ... + size = width * height * bpp; + buffer = gst_buffer_new (); + memory = gst_allocator_alloc (NULL, size, NULL); + gst_buffer_insert_memory (buffer, -1, memory); + ... +]| + +Alternatively, use gst_buffer_new_allocate() to create a buffer with +preallocated data of a given size. + +Buffers can contain a list of #GstMemory objects. You can retrieve how many +memory objects with gst_buffer_n_memory() and you can get a pointer +to memory with gst_buffer_peek_memory() + +A buffer will usually have timestamps, and a duration, but neither of these +are guaranteed (they may be set to #GST_CLOCK_TIME_NONE). Whenever a +meaningful value can be given for these, they should be set. The timestamps +and duration are measured in nanoseconds (they are #GstClockTime values). + +The buffer DTS refers to the timestamp when the buffer should be decoded and +is usually monotonically increasing. The buffer PTS refers to the timestamp when +the buffer content should be presented to the user and is not always +monotonically increasing. + +A buffer can also have one or both of a start and an end offset. These are +media-type specific. For video buffers, the start offset will generally be +the frame number. For audio buffers, it will be the number of samples +produced so far. For compressed data, it could be the byte offset in a +source or destination file. Likewise, the end offset will be the offset of +the end of the buffer. These can only be meaningfully interpreted if you +know the media type of the buffer (the preceding CAPS event). Either or both +can be set to #GST_BUFFER_OFFSET_NONE. + +gst_buffer_ref() is used to increase the refcount of a buffer. This must be +done when you want to keep a handle to the buffer after pushing it to the +next element. The buffer refcount determines the writability of the buffer, a +buffer is only writable when the refcount is exactly 1, i.e. when the caller +has the only reference to the buffer. + +To efficiently create a smaller buffer out of an existing one, you can +use gst_buffer_copy_region(). This method tries to share the memory objects +between the two buffers. + +If a plug-in wants to modify the buffer data or metadata in-place, it should +first obtain a buffer that is safe to modify by using +gst_buffer_make_writable(). This function is optimized so that a copy will +only be made when it is necessary. + +Several flags of the buffer can be set and unset with the +GST_BUFFER_FLAG_SET() and GST_BUFFER_FLAG_UNSET() macros. Use +GST_BUFFER_FLAG_IS_SET() to test if a certain #GstBufferFlags flag is set. + +Buffers can be efficiently merged into a larger buffer with +gst_buffer_append(). Copying of memory will only be done when absolutely +needed. + +Arbitrary extra metadata can be set on a buffer with gst_buffer_add_meta(). +Metadata can be retrieved with gst_buffer_get_meta(). See also #GstMeta + +An element should either unref the buffer or push it out on a src pad +using gst_pad_push() (see #GstPad). + +Buffers are usually freed by unreffing them with gst_buffer_unref(). When +the refcount drops to 0, any memory and metadata pointed to by the buffer is +unreffed as well. Buffers allocated from a #GstBufferPool will be returned to +the pool when the refcount drops to 0. + +The #GstParentBufferMeta is a meta which can be attached to a #GstBuffer +to hold a reference to another buffer that is only released when the child +#GstBuffer is released. + +Typically, #GstParentBufferMeta is used when the child buffer is directly +using the #GstMemory of the parent buffer, and wants to prevent the parent +buffer from being returned to a buffer pool until the #GstMemory is available +for re-use. (Since 1.6) + + the parent structure + + + + pointer to the pool owner of the buffer + + + + presentation timestamp of the buffer, can be #GST_CLOCK_TIME_NONE when the + pts is not known or relevant. The pts contains the timestamp when the + media should be presented to the user. + + + + decoding timestamp of the buffer, can be #GST_CLOCK_TIME_NONE when the + dts is not known or relevant. The dts contains the timestamp when the + media should be processed. + + + + duration in time of the buffer data, can be #GST_CLOCK_TIME_NONE + when the duration is not known or relevant. + + + + a media specific offset for the buffer data. + For video frames, this is the frame number of this buffer. + For audio samples, this is the offset of the first sample in this buffer. + For file data or compressed data this is the byte offset of the first + byte in this buffer. + + + + the last offset contained in this buffer. It has the same + format as @offset. + + + + Creates a newly allocated buffer without any data. + +MT safe. + + the new #GstBuffer. + + + + + Tries to create a newly allocated buffer with data of the given size and +extra parameters from @allocator. If the requested amount of memory can't be +allocated, %NULL will be returned. The allocated buffer memory is not cleared. + +When @allocator is %NULL, the default memory allocator will be used. + +Note that when @size == 0, the buffer will not have memory associated with it. + +MT safe. + + a new #GstBuffer, or %NULL if + the memory couldn't be allocated. + + + + + the #GstAllocator to use, or %NULL to use the + default allocator + + + + the size in bytes of the new buffer's data. + + + + optional parameters + + + + + + Creates a new buffer that wraps the given @data. The memory will be freed +with g_free and will be marked writable. + +MT safe. + + a new #GstBuffer + + + + + data to wrap + + + + + + allocated size of @data + + + + + + Allocate a new buffer that wraps the given memory. @data must point to +@maxsize of memory, the wrapped buffer will have the region from @offset and +@size visible. + +When the buffer is destroyed, @notify will be called with @user_data. + +The prefix/padding must be filled with 0 if @flags contains +#GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively. + + a new #GstBuffer + + + + + #GstMemoryFlags + + + + data to wrap + + + + + + allocated size of @data + + + + offset in @data + + + + size of valid data + + + + user_data + + + + called with @user_data when the memory is freed + + + + + + Add metadata for @info to @buffer using the parameters in @params. + + the metadata for the api in @info on @buffer. + + + + + a #GstBuffer + + + + a #GstMetaInfo + + + + params for @info + + + + + + Add a #GstParentBufferMeta to @buffer that holds a reference on +@ref until the buffer is freed. + + The #GstParentBufferMeta that was added to the buffer + + + + + a #GstBuffer + + + + a #GstBuffer to ref + + + + + + Attaches protection metadata to a #GstBuffer. + + a pointer to the added #GstProtectionMeta if successful; %NULL if +unsuccessful. + + + + + #GstBuffer holding an encrypted sample, to which protection + metadata should be added. + + + + a #GstStructure holding cryptographic + information relating to the sample contained in @buffer. This + function takes ownership of @info. + + + + + + Append all the memory from @buf2 to @buf1. The result buffer will contain a +concatenation of the memory of @buf1 and @buf2. + + the new #GstBuffer that contains the memory + of the two source buffers. + + + + + the first source #GstBuffer to append. + + + + the second source #GstBuffer to append. + + + + + + Append the memory block @mem to @buffer. This function takes +ownership of @mem and thus doesn't increase its refcount. + +This function is identical to gst_buffer_insert_memory() with an index of -1. +See gst_buffer_insert_memory() for more details. + + + + + + a #GstBuffer. + + + + a #GstMemory. + + + + + + Append @size bytes at @offset from @buf2 to @buf1. The result buffer will +contain a concatenation of the memory of @buf1 and the requested region of +@buf2. + + the new #GstBuffer that contains the memory + of the two source buffers. + + + + + the first source #GstBuffer to append. + + + + the second source #GstBuffer to append. + + + + the offset in @buf2 + + + + the size or -1 of @buf2 + + + + + + Create a copy of the given buffer. This will make a newly allocated +copy of the data the source buffer contains. + + a new copy of @buf. + + + + + a #GstBuffer. + + + + + + Copies the information from @src into @dest. + +If @dest already contains memory and @flags contains GST_BUFFER_COPY_MEMORY, +the memory from @src will be appended to @dest. + +@flags indicate which fields will be copied. + + %TRUE if the copying succeeded, %FALSE otherwise. + + + + + a destination #GstBuffer + + + + a source #GstBuffer + + + + flags indicating what metadata fields should be copied. + + + + offset to copy from + + + + total size to copy. If -1, all data is copied. + + + + + + Creates a sub-buffer from @parent at @offset and @size. +This sub-buffer uses the actual memory space of the parent buffer. +This function will copy the offset and timestamp fields when the +offset is 0. If not, they will be set to #GST_CLOCK_TIME_NONE and +#GST_BUFFER_OFFSET_NONE. +If @offset equals 0 and @size equals the total size of @buffer, the +duration and offset end fields are also copied. If not they will be set +to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE. + +MT safe. + + the new #GstBuffer or %NULL if the arguments were + invalid. + + + + + a #GstBuffer. + + + + the #GstBufferCopyFlags + + + + the offset into parent #GstBuffer at which the new sub-buffer + begins. + + + + the size of the new #GstBuffer sub-buffer, in bytes. If -1, all + data is copied. + + + + + + Copy @size bytes starting from @offset in @buffer to @dest. + + The amount of bytes extracted. This value can be lower than @size + when @buffer did not contain enough data. + + + + + a #GstBuffer. + + + + the offset to extract + + + + the destination address + + + + the size to extract + + + + + + Extracts a copy of at most @size bytes the data at @offset into +newly-allocated memory. @dest must be freed using g_free() when done. + + + + + + a #GstBuffer + + + + the offset to extract + + + + the size to extract + + + + A pointer where + the destination array will be written. + + + + + + A location where the size of @dest can be written + + + + + + Copy @size bytes from @src to @buffer at @offset. + + The amount of bytes copied. This value can be lower than @size + when @buffer did not contain enough data. + + + + + a #GstBuffer. + + + + the offset to fill + + + + the source address + + + + + + the size to fill + + + + + + Find the memory blocks that span @size bytes starting from @offset +in @buffer. + +When this function returns %TRUE, @idx will contain the index of the first +memory block where the byte for @offset can be found and @length contains the +number of memory blocks containing the @size remaining bytes. @skip contains +the number of bytes to skip in the memory block at @idx to get to the byte +for @offset. + +@size can be -1 to get all the memory blocks after @idx. + + %TRUE when @size bytes starting from @offset could be found in +@buffer and @idx, @length and @skip will be filled. + + + + + a #GstBuffer. + + + + an offset + + + + a size + + + + pointer to index + + + + pointer to length + + + + pointer to skip + + + + + + Call @func with @user_data for each meta in @buffer. + +@func can modify the passed meta pointer or its contents. The return value +of @func define if this function returns or if the remaining metadata items +in the buffer should be skipped. + + %FALSE when @func returned %FALSE for one of the metadata. + + + + + a #GstBuffer + + + + a #GstBufferForeachMetaFunc to call + + + + user data passed to @func + + + + + + Get all the memory block in @buffer. The memory blocks will be merged +into one large #GstMemory. + + a #GstMemory that contains the merged memory. +Use gst_memory_unref () after usage. + + + + + a #GstBuffer. + + + + + + Get the #GstBufferFlags flags set on this buffer. + + the flags set on this buffer. + + + + + a #GstBuffer + + + + + + Get the memory block at index @idx in @buffer. + + a #GstMemory that contains the data of the +memory block at @idx. Use gst_memory_unref () after usage. + + + + + a #GstBuffer. + + + + an index + + + + + + Get @length memory blocks in @buffer starting at @idx. The memory blocks will +be merged into one large #GstMemory. + +If @length is -1, all memory starting from @idx is merged. + + a #GstMemory that contains the merged data of @length + blocks starting at @idx. Use gst_memory_unref () after usage. + + + + + a #GstBuffer. + + + + an index + + + + a length + + + + + + Get the metadata for @api on buffer. When there is no such metadata, %NULL is +returned. If multiple metadata with the given @api are attached to this +buffer only the first one is returned. To handle multiple metadata with a +given API use gst_buffer_iterate_meta() or gst_buffer_foreach_meta() instead +and check the meta->info.api member for the API type. + + the metadata for @api on +@buffer. + + + + + a #GstBuffer + + + + the #GType of an API + + + + + + Get the total size of the memory blocks in @buffer. + + total size of the memory blocks in @buffer. + + + + + a #GstBuffer. + + + + + + Get the total size of the memory blocks in @b. + +When not %NULL, @offset will contain the offset of the data in the +first memory block in @buffer and @maxsize will contain the sum of +the size and @offset and the amount of extra padding on the last +memory block. @offset and @maxsize can be used to resize the +buffer memory blocks with gst_buffer_resize(). + + total size of the memory blocks in @buffer. + + + + + a #GstBuffer. + + + + a pointer to the offset + + + + a pointer to the maxsize + + + + + + Get the total size of @length memory blocks stating from @idx in @buffer. + +When not %NULL, @offset will contain the offset of the data in the +memory block in @buffer at @idx and @maxsize will contain the sum of the size +and @offset and the amount of extra padding on the memory block at @idx + +@length -1. +@offset and @maxsize can be used to resize the buffer memory blocks with +gst_buffer_resize_range(). + + total size of @length memory blocks starting at @idx in @buffer. + + + + + a #GstBuffer. + + + + an index + + + + a length + + + + a pointer to the offset + + + + a pointer to the maxsize + + + + + + + + + + + + + + + + + + + Insert the memory block @mem to @buffer at @idx. This function takes ownership +of @mem and thus doesn't increase its refcount. + +Only gst_buffer_get_max_memory() can be added to a buffer. If more memory is +added, existing memory blocks will automatically be merged to make room for +the new memory. + + + + + + a #GstBuffer. + + + + the index to add the memory at, or -1 to append it to the end + + + + a #GstMemory. + + + + + + Check if all memory blocks in @buffer are writable. + +Note that this function does not check if @buffer is writable, use +gst_buffer_is_writable() to check that if needed. + + %TRUE if all memory blocks in @buffer are writable + + + + + a #GstBuffer. + + + + + + Check if @length memory blocks in @buffer starting from @idx are writable. + +@length can be -1 to check all the memory blocks after @idx. + +Note that this function does not check if @buffer is writable, use +gst_buffer_is_writable() to check that if needed. + + %TRUE if the memory range is writable + + + + + a #GstBuffer. + + + + an index + + + + a length should not be 0 + + + + + + Retrieve the next #GstMeta after @current. If @state points +to %NULL, the first metadata is returned. + +@state will be updated with an opaque state pointer + + The next #GstMeta or %NULL +when there are no more items. + + + + + a #GstBuffer + + + + an opaque state pointer + + + + + + Retrieve the next #GstMeta of type @meta_api_type after the current one +according to @state. If @state points to %NULL, the first metadata of +type @meta_api_type is returned. + +@state will be updated with an opaque state pointer + + The next #GstMeta of type +@meta_api_type or %NULL when there are no more items. + + + + + a #GstBuffer + + + + an opaque state pointer + + + + only return #GstMeta of this type + + + + + + This function fills @info with the #GstMapInfo of all merged memory +blocks in @buffer. + +@flags describe the desired access of the memory. When @flags is +#GST_MAP_WRITE, @buffer should be writable (as returned from +gst_buffer_is_writable()). + +When @buffer is writable but the memory isn't, a writable copy will +automatically be created and returned. The readonly copy of the +buffer memory will then also be replaced with this writable copy. + +The memory in @info should be unmapped with gst_buffer_unmap() after +usage. + + %TRUE if the map succeeded and @info contains valid data. + + + + + a #GstBuffer. + + + + info about the mapping + + + + flags for the mapping + + + + + + This function fills @info with the #GstMapInfo of @length merged memory blocks +starting at @idx in @buffer. When @length is -1, all memory blocks starting +from @idx are merged and mapped. + +@flags describe the desired access of the memory. When @flags is +#GST_MAP_WRITE, @buffer should be writable (as returned from +gst_buffer_is_writable()). + +When @buffer is writable but the memory isn't, a writable copy will +automatically be created and returned. The readonly copy of the buffer memory +will then also be replaced with this writable copy. + +The memory in @info should be unmapped with gst_buffer_unmap() after usage. + + %TRUE if the map succeeded and @info contains valid +data. + + + + + a #GstBuffer. + + + + an index + + + + a length + + + + info about the mapping + + + + flags for the mapping + + + + + + Compare @size bytes starting from @offset in @buffer with the memory in @mem. + + 0 if the memory is equal. + + + + + a #GstBuffer. + + + + the offset in @buffer + + + + the memory to compare + + + + + + the size to compare + + + + + + Fill @buf with @size bytes with @val starting from @offset. + + The amount of bytes filled. This value can be lower than @size + when @buffer did not contain enough data. + + + + + a #GstBuffer. + + + + the offset in @buffer + + + + the value to set + + + + the size to set + + + + + + Get the amount of memory blocks that this buffer has. This amount is never +larger than what gst_buffer_get_max_memory() returns. + + the number of memory blocks this buffer is made of. + + + + + a #GstBuffer. + + + + + + Get the memory block at @idx in @buffer. The memory block stays valid until +the memory block in @buffer is removed, replaced or merged, typically with +any call that modifies the memory in @buffer. + + the #GstMemory at @idx. + + + + + a #GstBuffer. + + + + an index + + + + + + Prepend the memory block @mem to @buffer. This function takes +ownership of @mem and thus doesn't increase its refcount. + +This function is identical to gst_buffer_insert_memory() with an index of 0. +See gst_buffer_insert_memory() for more details. + + + + + + a #GstBuffer. + + + + a #GstMemory. + + + + + + Remove all the memory blocks in @buffer. + + + + + + a #GstBuffer. + + + + + + Remove the memory block in @b at index @i. + + + + + + a #GstBuffer. + + + + an index + + + + + + Remove @length memory blocks in @buffer starting from @idx. + +@length can be -1, in which case all memory starting from @idx is removed. + + + + + + a #GstBuffer. + + + + an index + + + + a length + + + + + + Remove the metadata for @meta on @buffer. + + %TRUE if the metadata existed and was removed, %FALSE if no such +metadata was on @buffer. + + + + + a #GstBuffer + + + + a #GstMeta + + + + + + Replaces all memory in @buffer with @mem. + + + + + + a #GstBuffer. + + + + a #GstMemory + + + + + + Replaces the memory block at index @idx in @buffer with @mem. + + + + + + a #GstBuffer. + + + + an index + + + + a #GstMemory + + + + + + Replaces @length memory blocks in @buffer starting at @idx with @mem. + +If @length is -1, all memory starting from @idx will be removed and +replaced with @mem. + +@buffer should be writable. + + + + + + a #GstBuffer. + + + + an index + + + + a length should not be 0 + + + + a #GstMemory + + + + + + Set the offset and total size of the memory blocks in @buffer. + + + + + + a #GstBuffer. + + + + the offset adjustment + + + + the new size or -1 to just adjust the offset + + + + + + Set the total size of the @length memory blocks starting at @idx in +@buffer + + %TRUE if resizing succeeded, %FALSE otherwise. + + + + + a #GstBuffer. + + + + an index + + + + a length + + + + the offset adjustment + + + + the new size or -1 to just adjust the offset + + + + + + Sets one or more buffer flags on a buffer. + + %TRUE if @flags were successfully set on buffer. + + + + + a #GstBuffer + + + + the #GstBufferFlags to set. + + + + + + Set the total size of the memory blocks in @buffer. + + + + + + a #GstBuffer. + + + + the new size + + + + + + Release the memory previously mapped with gst_buffer_map(). + + + + + + a #GstBuffer. + + + + a #GstMapInfo + + + + + + Clears one or more buffer flags. + + true if @flags is successfully cleared from buffer. + + + + + a #GstBuffer + + + + the #GstBufferFlags to clear + + + + + + Get the maximum amount of memory blocks that a buffer can hold. This is a +compile time constant that can be queried with the function. + +When more memory blocks are added, existing memory blocks will be merged +together to make room for the new block. + + the maximum amount of memory blocks that a buffer can hold. + + + + + + A set of flags that can be provided to the gst_buffer_copy_into() +function to specify which items should be copied. + + copy nothing + + + flag indicating that buffer flags should be copied + + + flag indicating that buffer pts, dts, + duration, offset and offset_end should be copied + + + flag indicating that buffer meta should be + copied + + + flag indicating that buffer memory should be reffed + and appended to already existing memory. Unless the memory is marked as + NO_SHARE, no actual copy of the memory is made but it is simply reffed. + Add @GST_BUFFER_COPY_DEEP to force a real copy. + + + flag indicating that buffer memory should be + merged + + + flag indicating that memory should always be + copied instead of reffed (Since 1.2) + + + + A set of buffer flags used to describe properties of a #GstBuffer. + + the buffer is live data and should be discarded in + the PAUSED state. + + + the buffer contains data that should be dropped + because it will be clipped against the segment + boundaries or because it does not contain data + that should be shown to the user. + + + the buffer marks a data discontinuity in the stream. + This typically occurs after a seek or a dropped buffer + from a live or network source. + + + the buffer timestamps might have a discontinuity + and this buffer is a good point to resynchronize. + + + the buffer data is corrupted. + + + the buffer contains a media specific marker. for + video this is typically the end of a frame boundary, for audio + this is usually the start of a talkspurt. + + + the buffer contains header information that is + needed to decode the following data. + + + the buffer has been created to fill a gap in the + stream and contains media neutral data (elements can + switch to optimized code path that ignores the buffer + content). + + + the buffer can be dropped without breaking the + stream, for example to reduce bandwidth. + + + this unit cannot be decoded independently. + + + this flag is set when memory of the buffer + is added/removed + + + Elements which write to disk or permanent + storage should ensure the data is synced after + writing the contents of this buffer. (Since 1.6) + + + additional media specific flags can be added starting from + this flag. + + + + A function that will be called from gst_buffer_foreach_meta(). The @meta +field will point to a the reference of the meta. + +@buffer should not be modified from this callback. + +When this function returns %TRUE, the next meta will be +returned. When %FALSE is returned, gst_buffer_foreach_meta() will return. + +When @meta is set to %NULL, the item will be removed from the buffer. + + %FALSE when gst_buffer_foreach_meta() should stop + + + + + a #GstBuffer + + + + a pointer to a #GstMeta + + + + user data passed to gst_buffer_foreach_meta() + + + + + + Buffer lists are an object containing a list of buffers. + +Buffer lists are created with gst_buffer_list_new() and filled with data +using a gst_buffer_list_insert(). + +Buffer lists can be pushed on a srcpad with gst_pad_push_list(). This is +interesting when multiple buffers need to be pushed in one go because it +can reduce the amount of overhead for pushing each buffer individually. + + Creates a new, empty #GstBufferList. The caller is responsible for unreffing +the returned #GstBufferList. + +Free-function: gst_buffer_list_unref + + the new #GstBufferList. gst_buffer_list_unref() + after usage. + + + + + Creates a new, empty #GstBufferList. The caller is responsible for unreffing +the returned #GstBufferList. The list will have @size space preallocated so +that memory reallocations can be avoided. + +Free-function: gst_buffer_list_unref + + the new #GstBufferList. gst_buffer_list_unref() + after usage. + + + + + an initial reserved size + + + + + + Create a copy of the given buffer list. This will make a newly allocated +copy of the buffer that the source buffer list contains. + + a new copy of @list. + + + + + a #GstBufferList + + + + + + Call @func with @data for each buffer in @list. + +@func can modify the passed buffer pointer or its contents. The return value +of @func define if this function returns or if the remaining buffers in +the list should be skipped. + + %TRUE when @func returned %TRUE for each buffer in @list or when +@list is empty. + + + + + a #GstBufferList + + + + a #GstBufferListFunc to call + + + + user data passed to @func + + + + + + Get the buffer at @idx. + + the buffer at @idx in @group + or %NULL when there is no buffer. The buffer remains valid as + long as @list is valid and buffer is not removed from the list. + + + + + a #GstBufferList + + + + the index + + + + + + Insert @buffer at @idx in @list. Other buffers are moved to make room for +this new buffer. + +A -1 value for @idx will append the buffer at the end. + + + + + + a #GstBufferList + + + + the index + + + + a #GstBuffer + + + + + + Returns the number of buffers in @list. + + the number of buffers in the buffer list + + + + + a #GstBufferList + + + + + + Remove @length buffers starting from @idx in @list. The following buffers +are moved to close the gap. + + + + + + a #GstBufferList + + + + the index + + + + the amount to remove + + + + + + + A function that will be called from gst_buffer_list_foreach(). The @buffer +field will point to a the reference of the buffer at @idx. + +When this function returns %TRUE, the next buffer will be +returned. When %FALSE is returned, gst_buffer_list_foreach() will return. + +When @buffer is set to %NULL, the item will be removed from the bufferlist. +When @buffer has been made writable, the new buffer reference can be assigned +to @buffer. This function is responsible for unreffing the old buffer when +removing or modifying. + + %FALSE when gst_buffer_list_foreach() should stop + + + + + pointer the buffer + + + + the index of @buffer + + + + user data passed to gst_buffer_list_foreach() + + + + + + A #GstBufferPool is an object that can be used to pre-allocate and recycle +buffers of the same size and with the same properties. + +A #GstBufferPool is created with gst_buffer_pool_new(). + +Once a pool is created, it needs to be configured. A call to +gst_buffer_pool_get_config() returns the current configuration structure from +the pool. With gst_buffer_pool_config_set_params() and +gst_buffer_pool_config_set_allocator() the bufferpool parameters and +allocator can be configured. Other properties can be configured in the pool +depending on the pool implementation. + +A bufferpool can have extra options that can be enabled with +gst_buffer_pool_config_add_option(). The available options can be retrieved +with gst_buffer_pool_get_options(). Some options allow for additional +configuration properties to be set. + +After the configuration structure has been configured, +gst_buffer_pool_set_config() updates the configuration in the pool. This can +fail when the configuration structure is not accepted. + +After the a pool has been configured, it can be activated with +gst_buffer_pool_set_active(). This will preallocate the configured resources +in the pool. + +When the pool is active, gst_buffer_pool_acquire_buffer() can be used to +retrieve a buffer from the pool. + +Buffers allocated from a bufferpool will automatically be returned to the +pool with gst_buffer_pool_release_buffer() when their refcount drops to 0. + +The bufferpool can be deactivated again with gst_buffer_pool_set_active(). +All further gst_buffer_pool_acquire_buffer() calls will return an error. When +all buffers are returned to the pool they will be freed. + +Use gst_object_unref() to release the reference to a bufferpool. If the +refcount of the pool reaches 0, the pool will be freed. + + Creates a new #GstBufferPool instance. + + a new #GstBufferPool instance + + + + + Enabled the option in @config. This will instruct the @bufferpool to enable +the specified option on the buffers that it allocates. + +The supported options by @pool can be retrieved with gst_buffer_pool_get_options(). + + + + + + a #GstBufferPool configuration + + + + an option to add + + + + + + Get the @allocator and @params from @config. + + %TRUE, if the values are set. + + + + + a #GstBufferPool configuration + + + + a #GstAllocator, or %NULL + + + + #GstAllocationParams, or %NULL + + + + + + Parse an available @config and get the option at @index of the options API +array. + + a #gchar of the option at @index. + + + + + a #GstBufferPool configuration + + + + position in the option array to read + + + + + + Get the configuration values from @config. + + %TRUE if all parameters could be fetched. + + + + + a #GstBufferPool configuration + + + + the caps of buffers + + + + the size of each buffer, not including prefix and padding + + + + the minimum amount of buffers to allocate. + + + + the maximum amount of buffers to allocate or 0 for unlimited. + + + + + + Check if @config contains @option. + + %TRUE if the options array contains @option. + + + + + a #GstBufferPool configuration + + + + an option + + + + + + Retrieve the number of values currently stored in the options array of the +@config structure. + + the options array size as a #guint. + + + + + a #GstBufferPool configuration + + + + + + Set the @allocator and @params on @config. + +One of @allocator and @params can be %NULL, but not both. When @allocator +is %NULL, the default allocator of the pool will use the values in @param +to perform its allocation. When @param is %NULL, the pool will use the +provided @allocator with its default #GstAllocationParams. + +A call to gst_buffer_pool_set_config() can update the allocator and params +with the values that it is able to do. Some pools are, for example, not able +to operate with different allocators or cannot allocate with the values +specified in @params. Use gst_buffer_pool_get_config() to get the currently +used values. + + + + + + a #GstBufferPool configuration + + + + a #GstAllocator + + + + #GstAllocationParams + + + + + + Configure @config with the given parameters. + + + + + + a #GstBufferPool configuration + + + + caps for the buffers + + + + the size of each buffer, not including prefix and padding + + + + the minimum amount of buffers to allocate. + + + + the maximum amount of buffers to allocate or 0 for unlimited. + + + + + + Validate that changes made to @config are still valid in the context of the +expected parameters. This function is a helper that can be used to validate +changes made by a pool to a config when gst_buffer_pool_set_config() +returns %FALSE. This expects that @caps haven't changed and that +@min_buffers aren't lower then what we initially expected. +This does not check if options or allocator parameters are still valid, +won't check if size have changed, since changing the size is valid to adapt +padding. + + %TRUE, if the parameters are valid in this context. + + + + + a #GstBufferPool configuration + + + + the excepted caps of buffers + + + + the expected size of each buffer, not including prefix and padding + + + + the expected minimum amount of buffers to allocate. + + + + the expect maximum amount of buffers to allocate or 0 for unlimited. + + + + + + Acquire a buffer from @pool. @buffer should point to a memory location that +can hold a pointer to the new buffer. + +@params can be %NULL or contain optional parameters to influence the +allocation. + + a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is +inactive. + + + + + a #GstBufferPool + + + + a location for a #GstBuffer + + + + parameters. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Get a %NULL terminated array of string with supported bufferpool options for +@pool. An option would typically be enabled with +gst_buffer_pool_config_add_option(). + + a %NULL terminated array + of strings. + + + + + + + a #GstBufferPool + + + + + + Release @buffer to @pool. @buffer should have previously been allocated from +@pool with gst_buffer_pool_acquire_buffer(). + +This function is usually called automatically when the last ref on @buffer +disappears. + + + + + + a #GstBufferPool + + + + a #GstBuffer + + + + + + + + + + + + + + + + + + + Set the configuration of the pool. If the pool is already configured, and +the configuration haven't change, this function will return %TRUE. If the +pool is active, this method will return %FALSE and active configuration +will remain. Buffers allocated form this pool must be returned or else this +function will do nothing and return %FALSE. + +@config is a #GstStructure that contains the configuration parameters for +the pool. A default and mandatory set of parameters can be configured with +gst_buffer_pool_config_set_params(), gst_buffer_pool_config_set_allocator() +and gst_buffer_pool_config_add_option(). + +If the parameters in @config can not be set exactly, this function returns +%FALSE and will try to update as much state as possible. The new state can +then be retrieved and refined with gst_buffer_pool_get_config(). + +This function takes ownership of @config. + + %TRUE when the configuration could be set. + + + + + a #GstBufferPool + + + + a #GstStructure + + + + + + + + + + + + + + + + + + + + + + + + + + Acquire a buffer from @pool. @buffer should point to a memory location that +can hold a pointer to the new buffer. + +@params can be %NULL or contain optional parameters to influence the +allocation. + + a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is +inactive. + + + + + a #GstBufferPool + + + + a location for a #GstBuffer + + + + parameters. + + + + + + Get a copy of the current configuration of the pool. This configuration +can either be modified and used for the gst_buffer_pool_set_config() call +or it must be freed after usage. + + a copy of the current configuration of @pool. use +gst_structure_free() after usage or gst_buffer_pool_set_config(). + + + + + a #GstBufferPool + + + + + + Get a %NULL terminated array of string with supported bufferpool options for +@pool. An option would typically be enabled with +gst_buffer_pool_config_add_option(). + + a %NULL terminated array + of strings. + + + + + + + a #GstBufferPool + + + + + + Check if the bufferpool supports @option. + + %TRUE if the buffer pool contains @option. + + + + + a #GstBufferPool + + + + an option + + + + + + Check if @pool is active. A pool can be activated with the +gst_buffer_pool_set_active() call. + + %TRUE when the pool is active. + + + + + a #GstBufferPool + + + + + + Release @buffer to @pool. @buffer should have previously been allocated from +@pool with gst_buffer_pool_acquire_buffer(). + +This function is usually called automatically when the last ref on @buffer +disappears. + + + + + + a #GstBufferPool + + + + a #GstBuffer + + + + + + Control the active state of @pool. When the pool is inactive, new calls to +gst_buffer_pool_acquire_buffer() will return with %GST_FLOW_FLUSHING. + +Activating the bufferpool will preallocate all resources in the pool based on +the configuration of the pool. + +Deactivating will free the resources again when there are no outstanding +buffers. When there are outstanding buffers, they will be freed as soon as +they are all returned to the pool. + + %FALSE when the pool was not configured or when preallocation of the +buffers failed. + + + + + a #GstBufferPool + + + + the new active state + + + + + + Set the configuration of the pool. If the pool is already configured, and +the configuration haven't change, this function will return %TRUE. If the +pool is active, this method will return %FALSE and active configuration +will remain. Buffers allocated form this pool must be returned or else this +function will do nothing and return %FALSE. + +@config is a #GstStructure that contains the configuration parameters for +the pool. A default and mandatory set of parameters can be configured with +gst_buffer_pool_config_set_params(), gst_buffer_pool_config_set_allocator() +and gst_buffer_pool_config_add_option(). + +If the parameters in @config can not be set exactly, this function returns +%FALSE and will try to update as much state as possible. The new state can +then be retrieved and refined with gst_buffer_pool_get_config(). + +This function takes ownership of @config. + + %TRUE when the configuration could be set. + + + + + a #GstBufferPool + + + + a #GstStructure + + + + + + Enable or disable the flushing state of a @pool without freeing or +allocating buffers. + + + + + + a #GstBufferPool + + + + whether to start or stop flushing + + + + + + + + + + + + + + + + + + + + + Additional flags to control the allocation of a buffer + + no flags + + + buffer is keyframe + + + when the bufferpool is empty, acquire_buffer +will by default block until a buffer is released into the pool again. Setting +this flag makes acquire_buffer return #GST_FLOW_EOS instead of blocking. + + + buffer is discont + + + last flag, subclasses can use private flags + starting from this value. + + + + Parameters passed to the gst_buffer_pool_acquire_buffer() function to control the +allocation of the buffer. + +The default implementation ignores the @start and @stop members but other +implementations can use this extra information to decide what buffer to +return. + + the format of @start and @stop + + + + the start position + + + + the stop position + + + + additional flags + + + + + + + + + + The GstBufferPool class. + + Object parent class + + + + + + a %NULL terminated array + of strings. + + + + + + + a #GstBufferPool + + + + + + + + + %TRUE when the configuration could be set. + + + + + a #GstBufferPool + + + + a #GstStructure + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is +inactive. + + + + + a #GstBufferPool + + + + a location for a #GstBuffer + + + + parameters. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GstBufferPool + + + + a #GstBuffer + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The different types of buffering methods. + + a small amount of data is buffered + + + the stream is being downloaded + + + the stream is being downloaded in a ringbuffer + + + the stream is a live stream + + + + The #GstBus is an object responsible for delivering #GstMessage packets in +a first-in first-out way from the streaming threads (see #GstTask) to the +application. + +Since the application typically only wants to deal with delivery of these +messages from one thread, the GstBus will marshall the messages between +different threads. This is important since the actual streaming of media +is done in another thread than the application. + +The GstBus provides support for #GSource based notifications. This makes it +possible to handle the delivery in the glib mainloop. + +The #GSource callback function gst_bus_async_signal_func() can be used to +convert all bus messages into signal emissions. + +A message is posted on the bus with the gst_bus_post() method. With the +gst_bus_peek() and gst_bus_pop() methods one can look at or retrieve a +previously posted message. + +The bus can be polled with the gst_bus_poll() method. This methods blocks +up to the specified timeout value until one of the specified messages types +is posted on the bus. The application can then gst_bus_pop() the messages +from the bus to handle them. +Alternatively the application can register an asynchronous bus function +using gst_bus_add_watch_full() or gst_bus_add_watch(). This function will +install a #GSource in the default glib main loop and will deliver messages +a short while after they have been posted. Note that the main loop should +be running for the asynchronous callbacks. + +It is also possible to get messages from the bus without any thread +marshalling with the gst_bus_set_sync_handler() method. This makes it +possible to react to a message in the same thread that posted the +message on the bus. This should only be used if the application is able +to deal with messages from different threads. + +Every #GstPipeline has one bus. + +Note that a #GstPipeline will set its bus into flushing state when changing +from READY to NULL state. + + Creates a new #GstBus instance. + + a new #GstBus instance + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Adds a bus signal watch to the default main context with the default priority +(%G_PRIORITY_DEFAULT). It is also possible to use a non-default +main context set up using g_main_context_push_thread_default() (before +one had to create a bus watch source and attach it to the desired main +context 'manually'). + +After calling this statement, the bus will emit the "message" signal for each +message posted on the bus. + +This function may be called multiple times. To clean up, the caller is +responsible for calling gst_bus_remove_signal_watch() as many times as this +function is called. + +MT safe. + + + + + + a #GstBus on which you want to receive the "message" signal + + + + + + Adds a bus signal watch to the default main context with the given @priority +(e.g. %G_PRIORITY_DEFAULT). It is also possible to use a non-default main +context set up using g_main_context_push_thread_default() +(before one had to create a bus watch source and attach it to the desired +main context 'manually'). + +After calling this statement, the bus will emit the "message" signal for each +message posted on the bus when the main loop is running. + +This function may be called multiple times. To clean up, the caller is +responsible for calling gst_bus_remove_signal_watch() as many times as this +function is called. + +There can only be a single bus watch per bus, you must remove any signal +watch before you can set another type of watch. + +MT safe. + + + + + + a #GstBus on which you want to receive the "message" signal + + + + The priority of the watch. + + + + + + Adds a bus watch to the default main context with the default priority +(%G_PRIORITY_DEFAULT). It is also possible to use a non-default main +context set up using g_main_context_push_thread_default() (before +one had to create a bus watch source and attach it to the desired main +context 'manually'). + +This function is used to receive asynchronous messages in the main loop. +There can only be a single bus watch per bus, you must remove it before you +can set a new one. + +The bus watch will only work if a GLib main loop is being run. + +The watch can be removed using gst_bus_remove_watch() or by returning %FALSE +from @func. If the watch was added to the default main context it is also +possible to remove the watch using g_source_remove(). + + The event source id or 0 if @bus already got an event source. + +MT safe. + + + + + a #GstBus to create the watch for + + + + A function to call when a message is received. + + + + user data passed to @func. + + + + + + Adds a bus watch to the default main context with the given @priority (e.g. +%G_PRIORITY_DEFAULT). It is also possible to use a non-default main +context set up using g_main_context_push_thread_default() (before +one had to create a bus watch source and attach it to the desired main +context 'manually'). + +This function is used to receive asynchronous messages in the main loop. +There can only be a single bus watch per bus, you must remove it before you +can set a new one. + +The bus watch will only work if a GLib main loop is being run. + +When @func is called, the message belongs to the caller; if you want to +keep a copy of it, call gst_message_ref() before leaving @func. + +The watch can be removed using gst_bus_remove_watch() or by returning %FALSE +from @func. If the watch was added to the default main context it is also +possible to remove the watch using g_source_remove(). + +MT safe. + + The event source id or 0 if @bus already got an event source. + + + + + a #GstBus to create the watch for. + + + + The priority of the watch. + + + + A function to call when a message is received. + + + + user data passed to @func. + + + + the function to call when the source is removed. + + + + + + A helper #GstBusFunc that can be used to convert all asynchronous messages +into signals. + + %TRUE + + + + + a #GstBus + + + + the #GstMessage received + + + + user data + + + + + + Create watch for this bus. The GSource will be dispatched whenever +a message is on the bus. After the GSource is dispatched, the +message is popped off the bus and unreffed. + + a #GSource that can be added to a mainloop. + + + + + a #GstBus to create the watch for + + + + + + Instructs GStreamer to stop emitting the "sync-message" signal for this bus. +See gst_bus_enable_sync_message_emission() for more information. + +In the event that multiple pieces of code have called +gst_bus_enable_sync_message_emission(), the sync-message emissions will only +be stopped after all calls to gst_bus_enable_sync_message_emission() were +"cancelled" by calling this function. In this way the semantics are exactly +the same as gst_object_ref() that which calls enable should also call +disable. + +MT safe. + + + + + + a #GstBus on which you previously called +gst_bus_enable_sync_message_emission() + + + + + + Instructs GStreamer to emit the "sync-message" signal after running the bus's +sync handler. This function is here so that code can ensure that they can +synchronously receive messages without having to affect what the bin's sync +handler is. + +This function may be called multiple times. To clean up, the caller is +responsible for calling gst_bus_disable_sync_message_emission() as many times +as this function is called. + +While this function looks similar to gst_bus_add_signal_watch(), it is not +exactly the same -- this function enables <emphasis>synchronous</emphasis> emission of +signals when messages arrive; gst_bus_add_signal_watch() adds an idle callback +to pop messages off the bus <emphasis>asynchronously</emphasis>. The sync-message signal +comes from the thread of whatever object posted the message; the "message" +signal is marshalled to the main thread via the main loop. + +MT safe. + + + + + + a #GstBus on which you want to receive the "sync-message" signal + + + + + + Check if there are pending messages on the bus that +should be handled. + + %TRUE if there are messages on the bus to be handled, %FALSE +otherwise. + +MT safe. + + + + + a #GstBus to check + + + + + + Peek the message on the top of the bus' queue. The message will remain +on the bus' message queue. A reference is returned, and needs to be unreffed +by the caller. + + the #GstMessage that is on the + bus, or %NULL if the bus is empty. + +MT safe. + + + + + a #GstBus + + + + + + Poll the bus for messages. Will block while waiting for messages to come. +You can specify a maximum time to poll with the @timeout parameter. If +@timeout is negative, this function will block indefinitely. + +All messages not in @events will be popped off the bus and will be ignored. +It is not possible to use message enums beyond #GST_MESSAGE_EXTENDED in the +@events mask + +Because poll is implemented using the "message" signal enabled by +gst_bus_add_signal_watch(), calling gst_bus_poll() will cause the "message" +signal to be emitted for every message that poll sees. Thus a "message" +signal handler will see the same messages that this function sees -- neither +will steal messages from the other. + +This function will run a main loop from the default main context when +polling. + +You should never use this function, since it is pure evil. This is +especially true for GUI applications based on Gtk+ or Qt, but also for any +other non-trivial application that uses the GLib main loop. As this function +runs a GLib main loop, any callback attached to the default GLib main +context may be invoked. This could be timeouts, GUI events, I/O events etc.; +even if gst_bus_poll() is called with a 0 timeout. Any of these callbacks +may do things you do not expect, e.g. destroy the main application window or +some other resource; change other application state; display a dialog and +run another main loop until the user clicks it away. In short, using this +function may add a lot of complexity to your code through unexpected +re-entrancy and unexpected changes to your application's state. + +For 0 timeouts use gst_bus_pop_filtered() instead of this function; for +other short timeouts use gst_bus_timed_pop_filtered(); everything else is +better handled by setting up an asynchronous bus watch and doing things +from there. + + the message that was received, + or %NULL if the poll timed out. The message is taken from the + bus and needs to be unreffed with gst_message_unref() after + usage. + + + + + a #GstBus + + + + a mask of #GstMessageType, representing the set of message types to +poll for (note special handling of extended message types below) + + + + the poll timeout, as a #GstClockTime, or #GST_CLOCK_TIME_NONE to poll +indefinitely. + + + + + + Get a message from the bus. + + the #GstMessage that is on the + bus, or %NULL if the bus is empty. The message is taken from + the bus and needs to be unreffed with gst_message_unref() after + usage. + +MT safe. + + + + + a #GstBus to pop + + + + + + Get a message matching @type from the bus. Will discard all messages on +the bus that do not match @type and that have been posted before the first +message that does match @type. If there is no message matching @type on +the bus, all messages will be discarded. It is not possible to use message +enums beyond #GST_MESSAGE_EXTENDED in the @events mask. + + the next #GstMessage matching + @type that is on the bus, or %NULL if the bus is empty or there + is no message matching @type. The message is taken from the bus + and needs to be unreffed with gst_message_unref() after usage. + +MT safe. + + + + + a #GstBus to pop + + + + message types to take into account + + + + + + Post a message on the given bus. Ownership of the message +is taken by the bus. + + %TRUE if the message could be posted, %FALSE if the bus is flushing. + +MT safe. + + + + + a #GstBus to post on + + + + the #GstMessage to post + + + + + + Removes a signal watch previously added with gst_bus_add_signal_watch(). + +MT safe. + + + + + + a #GstBus you previously added a signal watch to + + + + + + Removes an installed bus watch from @bus. + + %TRUE on success or %FALSE if @bus has no event source. + + + + + a #GstBus to remove the watch from. + + + + + + If @flushing, flush out and unref any messages queued in the bus. Releases +references to the message origin objects. Will flush future messages until +gst_bus_set_flushing() sets @flushing to %FALSE. + +MT safe. + + + + + + a #GstBus + + + + whether or not to flush the bus + + + + + + Sets the synchronous handler on the bus. The function will be called +every time a new message is posted on the bus. Note that the function +will be called in the same thread context as the posting object. This +function is usually only called by the creator of the bus. Applications +should handle messages asynchronously using the gst_bus watch and poll +functions. + +You cannot replace an existing sync_handler. You can pass %NULL to this +function, which will clear the existing handler. + + + + + + a #GstBus to install the handler on + + + + The handler function to install + + + + User data that will be sent to the handler function. + + + + called when @user_data becomes unused + + + + + + A helper GstBusSyncHandler that can be used to convert all synchronous +messages into signals. + + GST_BUS_PASS + + + + + a #GstBus + + + + the #GstMessage received + + + + user data + + + + + + Get a message from the bus, waiting up to the specified timeout. + +If @timeout is 0, this function behaves like gst_bus_pop(). If @timeout is +#GST_CLOCK_TIME_NONE, this function will block forever until a message was +posted on the bus. + + the #GstMessage that is on the + bus after the 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 gst_message_unref() after usage. + +MT safe. + + + + + a #GstBus to pop + + + + a timeout + + + + + + Get a message from the bus whose type matches the message type mask @types, +waiting up to the specified timeout (and discarding any messages that do not +match the mask provided). + +If @timeout is 0, this function behaves like gst_bus_pop_filtered(). If +@timeout is #GST_CLOCK_TIME_NONE, this function will block forever until a +matching message was posted on the bus. + + a #GstMessage matching the + filter in @types, or %NULL if no matching message was found on + the bus until the timeout expired. The message is taken from + the bus and needs to be unreffed with gst_message_unref() after + usage. + +MT safe. + + + + + a #GstBus to pop from + + + + a timeout in nanoseconds, or GST_CLOCK_TIME_NONE to wait forever + + + + message types to take into account, GST_MESSAGE_ANY for any type + + + + + + + + + + + + + + + + + + + + A message has been posted on the bus. This signal is emitted from a +GSource added to the mainloop. this signal will only be emitted when +there is a mainloop running. + + + + + + the message that has been posted asynchronously + + + + + + A message has been posted on the bus. This signal is emitted from the +thread that posted the message so one has to be careful with locking. + +This signal will not be emitted by default, you have to call +gst_bus_enable_sync_message_emission() before. + + + + + + the message that has been posted synchronously + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The standard flags that a bus may have. + + The bus is currently dropping all messages + + + offset to define more flags + + + + Specifies the type of function passed to gst_bus_add_watch() or +gst_bus_add_watch_full(), which is called from the mainloop when a message +is available on the bus. + +The message passed to the function will be unreffed after execution of this +function so it should not be freed in the function. + +Note that this function is used as a GSourceFunc which means that returning +%FALSE will remove the GSource from the mainloop. + + %FALSE if the event source should be removed. + + + + + the #GstBus that sent the message + + + + the #GstMessage + + + + user data that has been given, when registering the handler + + + + + + + + Handler will be invoked synchronously, when a new message has been injected +into the bus. This function is mostly used internally. Only one sync handler +can be attached to a given bus. + +If the handler returns GST_BUS_DROP, it should unref the message, else the +message should not be unreffed by the sync handler. + + #GstBusSyncReply stating what to do with the message + + + + + the #GstBus that sent the message + + + + the #GstMessage + + + + user data that has been given, when registering the handler + + + + + + The result values for a GstBusSyncHandler. + + drop the message + + + pass the message to the async queue + + + pass message to async queue, continue if message is handled + + + + + + + + + + Constant to define an undefined clock time. + + + + Caps (capabilities) are lightweight refcounted objects describing media types. +They are composed of an array of #GstStructure. + +Caps are exposed on #GstPadTemplate to describe all possible types a +given pad can handle. They are also stored in the #GstRegistry along with +a description of the #GstElement. + +Caps are exposed on the element pads using the gst_pad_query_caps() pad +function. This function describes the possible types that the pad can +handle or produce at runtime. + +A #GstCaps can be constructed with the following code fragment: +|[<!-- language="C" --> + GstCaps *caps = gst_caps_new_simple ("video/x-raw", + "format", G_TYPE_STRING, "I420", + "framerate", GST_TYPE_FRACTION, 25, 1, + "pixel-aspect-ratio", GST_TYPE_FRACTION, 1, 1, + "width", G_TYPE_INT, 320, + "height", G_TYPE_INT, 240, + NULL); +]| + +A #GstCaps is fixed when it has no properties with ranges or lists. Use +gst_caps_is_fixed() to test for fixed caps. Fixed caps can be used in a +caps event to notify downstream elements of the current media type. + +Various methods exist to work with the media types such as subtracting +or intersecting. + +Be aware that the current #GstCaps / #GstStructure serialization into string +has limited support for nested #GstCaps / #GstStructure fields. It can only +support one level of nesting. Using more levels will lead to unexpected +behavior when using serialization features, such as gst_caps_to_string() or +gst_value_serialize() and their counterparts. + + the parent type + + + + Creates a new #GstCaps that indicates that it is compatible with +any media format. + + the new #GstCaps + + + + + Creates a new #GstCaps that is empty. That is, the returned +#GstCaps contains no media formats. +The #GstCaps is guaranteed to be writable. +Caller is responsible for unreffing the returned caps. + + the new #GstCaps + + + + + Creates a new #GstCaps that contains one #GstStructure with name +@media_type. +Caller is responsible for unreffing the returned caps. + + the new #GstCaps + + + + + the media type of the structure + + + + + + Creates a new #GstCaps and adds all the structures listed as +arguments. The list must be %NULL-terminated. The structures +are not copied; the returned #GstCaps owns the structures. + + the new #GstCaps + + + + + the first structure to add + + + + additional structures to add + + + + + + Creates a new #GstCaps and adds all the structures listed as +arguments. The list must be %NULL-terminated. The structures +are not copied; the returned #GstCaps owns the structures. + + the new #GstCaps + + + + + the first structure to add + + + + additional structures to add + + + + + + Creates a new #GstCaps that contains one #GstStructure. The +structure is defined by the arguments, which have the same format +as gst_structure_new(). +Caller is responsible for unreffing the returned caps. + + the new #GstCaps + + + + + the media type of the structure + + + + first field to set + + + + additional arguments + + + + + + Appends the structures contained in @caps2 to @caps1. The structures in +@caps2 are not copied -- they are transferred to @caps1, and then @caps2 is +freed. If either caps is ANY, the resulting caps will be ANY. + + + + + + the #GstCaps that will be appended to + + + + the #GstCaps to append + + + + + + Appends @structure to @caps. The structure is not copied; @caps +becomes the owner of @structure. + + + + + + the #GstCaps that will be appended to + + + + the #GstStructure to append + + + + + + Appends @structure with @features to @caps. The structure is not copied; @caps +becomes the owner of @structure. + + + + + + the #GstCaps that will be appended to + + + + the #GstStructure to append + + + + the #GstCapsFeatures to append + + + + + + Tries intersecting @caps1 and @caps2 and reports whether the result would not +be empty + + %TRUE if intersection would be not empty + + + + + a #GstCaps to intersect + + + + a #GstCaps to intersect + + + + + + Creates a new #GstCaps and appends a copy of the nth structure +contained in @caps. + + the new #GstCaps + + + + + the #GstCaps to copy + + + + the nth structure to copy + + + + + + Calls the provided function once for each structure and caps feature in the +#GstCaps. In contrast to gst_caps_foreach(), the function may modify the +structure and features. In contrast to gst_caps_filter_and_map_in_place(), +the structure and features are removed from the caps if %FALSE is returned +from the function. +The caps must be mutable. + + + + + + a #GstCaps + + + + a function to call for each field + + + + private data + + + + + + Modifies the given @caps into a representation with only fixed +values. First the caps will be truncated and then the first structure will be +fixated with gst_structure_fixate(). + +This function takes ownership of @caps and will call gst_caps_make_writable() +on it so you must not use @caps afterwards unless you keep an additional +reference to it with gst_caps_ref(). + + the fixated caps + + + + + a #GstCaps to fixate + + + + + + Calls the provided function once for each structure and caps feature in the +#GstCaps. The function must not modify the fields. +Also see gst_caps_map_in_place() and gst_caps_filter_and_map_in_place(). + + %TRUE if the supplied function returns %TRUE for each call, +%FALSE otherwise. + + + + + a #GstCaps + + + + a function to call for each field + + + + private data + + + + + + Finds the features in @caps that has the index @index, and +returns it. + +WARNING: This function takes a const GstCaps *, but returns a +non-const GstCapsFeatures *. This is for programming convenience -- +the caller should be aware that structures inside a constant +#GstCaps should not be modified. However, if you know the caps +are writable, either because you have just copied them or made +them writable with gst_caps_make_writable(), you may modify the +features returned in the usual way, e.g. with functions like +gst_caps_features_add(). + +You do not need to free or unref the structure returned, it +belongs to the #GstCaps. + + a pointer to the #GstCapsFeatures corresponding + to @index + + + + + a #GstCaps + + + + the index of the structure + + + + + + Gets the number of structures contained in @caps. + + the number of structures that @caps contains + + + + + a #GstCaps + + + + + + Finds the structure in @caps that has the index @index, and +returns it. + +WARNING: This function takes a const GstCaps *, but returns a +non-const GstStructure *. This is for programming convenience -- +the caller should be aware that structures inside a constant +#GstCaps should not be modified. However, if you know the caps +are writable, either because you have just copied them or made +them writable with gst_caps_make_writable(), you may modify the +structure returned in the usual way, e.g. with functions like +gst_structure_set(). + +You do not need to free or unref the structure returned, it +belongs to the #GstCaps. + + a pointer to the #GstStructure corresponding + to @index + + + + + a #GstCaps + + + + the index of the structure + + + + + + Creates a new #GstCaps that contains all the formats that are common +to both @caps1 and @caps2. Defaults to %GST_CAPS_INTERSECT_ZIG_ZAG mode. + + the new #GstCaps + + + + + a #GstCaps to intersect + + + + a #GstCaps to intersect + + + + + + Creates a new #GstCaps that contains all the formats that are common +to both @caps1 and @caps2, the order is defined by the #GstCapsIntersectMode +used. + + the new #GstCaps + + + + + a #GstCaps to intersect + + + + a #GstCaps to intersect + + + + The intersection algorithm/mode to use + + + + + + A given #GstCaps structure is always compatible with another if +every media format that is in the first is also contained in the +second. That is, @caps1 is a subset of @caps2. + + %TRUE if @caps1 is a subset of @caps2. + + + + + the #GstCaps to test + + + + the #GstCaps to test + + + + + + Determines if @caps represents any media format. + + %TRUE if @caps represents any format. + + + + + the #GstCaps to test + + + + + + Determines if @caps represents no media formats. + + %TRUE if @caps represents no formats. + + + + + the #GstCaps to test + + + + + + Checks if the given caps represent the same set of caps. + + %TRUE if both caps are equal. + + + + + a #GstCaps + + + + another #GstCaps + + + + + + Tests if two #GstCaps are equal. This function only works on fixed +#GstCaps. + + %TRUE if the arguments represent the same format + + + + + the #GstCaps to test + + + + the #GstCaps to test + + + + + + Fixed #GstCaps describe exactly one format, that is, they have exactly +one structure, and each field in the structure describes a fixed type. +Examples of non-fixed types are GST_TYPE_INT_RANGE and GST_TYPE_LIST. + + %TRUE if @caps is fixed + + + + + the #GstCaps to test + + + + + + Checks if the given caps are exactly the same set of caps. + + %TRUE if both caps are strictly equal. + + + + + a #GstCaps + + + + another #GstCaps + + + + + + Checks if all caps represented by @subset are also represented by @superset. + + %TRUE if @subset is a subset of @superset + + + + + a #GstCaps + + + + a potentially greater #GstCaps + + + + + + Checks if @structure is a subset of @caps. See gst_caps_is_subset() +for more information. + + %TRUE if @structure is a subset of @caps + + + + + a #GstCaps + + + + a potential #GstStructure subset of @caps + + + + + + Checks if @structure is a subset of @caps. See gst_caps_is_subset() +for more information. + + %TRUE if @structure is a subset of @caps + + + + + a #GstCaps + + + + a potential #GstStructure subset of @caps + + + + a #GstCapsFeatures for @structure + + + + + + Calls the provided function once for each structure and caps feature in the +#GstCaps. In contrast to gst_caps_foreach(), the function may modify but not +delete the structures and features. The caps must be mutable. + + %TRUE if the supplied function returns %TRUE for each call, +%FALSE otherwise. + + + + + a #GstCaps + + + + a function to call for each field + + + + private data + + + + + + 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 +transferred to a writable copy of @caps1, and then @caps2 is freed. +If either caps is ANY, the resulting caps will be ANY. + + the merged caps. + + + + + the #GstCaps that will take the new entries + + + + the #GstCaps to merge in + + + + + + Appends @structure to @caps if its not already expressed by @caps. + + the merged caps. + + + + + the #GstCaps to merge into + + + + the #GstStructure to merge + + + + + + Appends @structure with @features to @caps if its not already expressed by @caps. + + the merged caps. + + + + + the #GstCaps to merge into + + + + the #GstStructure to merge + + + + the #GstCapsFeatures to merge + + + + + + Returns a #GstCaps that represents the same set of formats as +@caps, but contains no lists. Each list is expanded into separate +@GstStructures. + +This function takes ownership of @caps and will call gst_caps_make_writable() +on it so you must not use @caps afterwards unless you keep an additional +reference to it with gst_caps_ref(). + + the normalized #GstCaps + + + + + a #GstCaps to normalize + + + + + + removes the structure with the given index from the list of structures +contained in @caps. + + + + + + the #GstCaps to remove from + + + + Index of the structure to remove + + + + + + Sets the #GstCapsFeatures @features for the structure at @index. + + + + + + a #GstCaps + + + + the index of the structure + + + + the #GstCapsFeatures to set + + + + + + Sets fields in a #GstCaps. The arguments must be passed in the same +manner as gst_structure_set(), and be %NULL-terminated. + + + + + + the #GstCaps to set + + + + first field to set + + + + additional parameters + + + + + + Sets fields in a #GstCaps. The arguments must be passed in the same +manner as gst_structure_set(), and be %NULL-terminated. + + + + + + the #GstCaps to set + + + + first field to set + + + + additional parameters + + + + + + Sets the given @field on all structures of @caps to the given @value. +This is a convenience function for calling gst_structure_set_value() on +all structures of @caps. + + + + + + a writable caps + + + + name of the field to set + + + + value to set the field to + + + + + + Converts the given @caps into a representation that represents the +same set of formats, but in a simpler form. Component structures that are +identical are merged. Component structures that have values that can be +merged are also merged. + +This function takes ownership of @caps and will call gst_caps_make_writable() +on it if necessary, so you must not use @caps afterwards unless you keep an +additional reference to it with gst_caps_ref(). + +This method does not preserve the original order of @caps. + + The simplified caps. + + + + + a #GstCaps to simplify + + + + + + Retrieves the structure with the given index from the list of structures +contained in @caps. The caller becomes the owner of the returned structure. + + a pointer to the #GstStructure corresponding + to @index. + + + + + the #GstCaps to retrieve from + + + + Index of the structure to retrieve + + + + + + Subtracts the @subtrahend from the @minuend. +> This function does not work reliably if optional properties for caps +> are included on one caps and omitted on the other. + + the resulting caps + + + + + #GstCaps to subtract from + + + + #GstCaps to subtract + + + + + + Converts @caps to a string representation. This string representation +can be converted back to a #GstCaps by gst_caps_from_string(). + +For debugging purposes its easier to do something like this: +|[<!-- language="C" --> +GST_LOG ("caps are %" GST_PTR_FORMAT, caps); +]| +This prints the caps in human readable form. + +The current implementation of serialization will lead to unexpected results +when there are nested #GstCaps / #GstStructure deeper than one level. + + a newly allocated string representing @caps. + + + + + a #GstCaps + + + + + + Discard all but the first structure from @caps. Useful when +fixating. + +This function takes ownership of @caps and will call gst_caps_make_writable() +on it if necessary, so you must not use @caps afterwards unless you keep an +additional reference to it with gst_caps_ref(). + + truncated caps + + + + + the #GstCaps to truncate + + + + + + Converts @caps from a string representation. + +The current implementation of serialization will lead to unexpected results +when there are nested #GstCaps / #GstStructure deeper than one level. + + a newly allocated #GstCaps + + + + + a string to convert to #GstCaps + + + + + + + #GstCapsFeatures can optionally be set on a #GstCaps to add requirements +for additional features for a specific #GstStructure. Caps structures with +the same name but with a non-equal set of caps features are not compatible. +If a pad supports multiple sets of features it has to add multiple equal +structures with different feature sets to the caps. + +Empty #GstCapsFeatures are equivalent with the #GstCapsFeatures that only +contain #GST_CAPS_FEATURE_MEMORY_SYSTEM_MEMORY. ANY #GstCapsFeatures as +created by gst_caps_features_new_any() are equal to any other #GstCapsFeatures +and can be used to specify that any #GstCapsFeatures would be supported, e.g. +for elements that don't touch buffer memory. #GstCaps with ANY #GstCapsFeatures +are considered non-fixed and during negotiation some #GstCapsFeatures have +to be selected. + +Examples for caps features would be the requirement of a specific #GstMemory +types or the requirement of having a specific #GstMeta on the buffer. Features +are given as a string of the format "memory:GstMemoryTypeName" or +"meta:GstMetaAPIName". + + Creates a new #GstCapsFeatures with the given features. +The last argument must be %NULL. + +Free-function: gst_caps_features_free + + a new, empty #GstCapsFeatures + + + + + name of first feature to set + + + + additional features + + + + + + Creates a new, ANY #GstCapsFeatures. This will be equal +to any other #GstCapsFeatures but caps with these are +unfixed. + +Free-function: gst_caps_features_free + + a new, ANY #GstCapsFeatures + + + + + Creates a new, empty #GstCapsFeatures. + +Free-function: gst_caps_features_free + + a new, empty #GstCapsFeatures + + + + + Creates a new #GstCapsFeatures with the given features. +The last argument must be 0. + +Free-function: gst_caps_features_free + + a new, empty #GstCapsFeatures + + + + + name of first feature to set + + + + additional features + + + + + + Creates a new #GstCapsFeatures with the given features. + +Free-function: gst_caps_features_free + + a new, empty #GstCapsFeatures + + + + + name of first feature to set + + + + variable argument list + + + + + + Creates a new #GstCapsFeatures with the given features. + +Free-function: gst_caps_features_free + + a new, empty #GstCapsFeatures + + + + + name of first feature to set + + + + variable argument list + + + + + + Adds @feature to @features. + + + + + + a #GstCapsFeatures. + + + + a feature. + + + + + + Adds @feature to @features. + + + + + + a #GstCapsFeatures. + + + + a feature. + + + + + + Check if @features contains @feature. + + %TRUE if @features contains @feature. + + + + + a #GstCapsFeatures. + + + + a feature + + + + + + Check if @features contains @feature. + + %TRUE if @features contains @feature. + + + + + a #GstCapsFeatures. + + + + a feature + + + + + + Duplicates a #GstCapsFeatures and all its values. + +Free-function: gst_caps_features_free + + a new #GstCapsFeatures. + + + + + a #GstCapsFeatures to duplicate + + + + + + Frees a #GstCapsFeatures and all its values. The caps features must not +have a parent when this function is called. + + + + + + the #GstCapsFeatures to free + + + + + + Returns the @i-th feature of @features. + + The @i-th feature of @features. + + + + + a #GstCapsFeatures. + + + + index of the feature + + + + + + Returns the @i-th feature of @features. + + The @i-th feature of @features. + + + + + a #GstCapsFeatures. + + + + index of the feature + + + + + + Returns the number of features in @features. + + The number of features in @features. + + + + + a #GstCapsFeatures. + + + + + + Check if @features is %GST_CAPS_FEATURES_ANY. + + %TRUE if @features is %GST_CAPS_FEATURES_ANY. + + + + + a #GstCapsFeatures. + + + + + + Check if @features1 and @features2 are equal. + + %TRUE if @features1 and @features2 are equal. + + + + + a #GstCapsFeatures. + + + + a #GstCapsFeatures. + + + + + + Removes @feature from @features. + + + + + + a #GstCapsFeatures. + + + + a feature. + + + + + + Removes @feature from @features. + + + + + + a #GstCapsFeatures. + + + + a feature. + + + + + + Sets the parent_refcount field of #GstCapsFeatures. This field is used to +determine whether a caps features is mutable or not. This function should only be +called by code implementing parent objects of #GstCapsFeatures, as described in +the MT Refcounting section of the design documents. + + %TRUE if the parent refcount could be set. + + + + + a #GstCapsFeatures + + + + a pointer to the parent's refcount + + + + + + Converts @features to a human-readable string representation. + +For debugging purposes its easier to do something like this: +|[<!-- language="C" --> +GST_LOG ("features is %" GST_PTR_FORMAT, features); +]| +This prints the features in human readable form. + +Free-function: g_free + + a pointer to string allocated by g_malloc(). + g_free() after usage. + + + + + a #GstCapsFeatures + + + + + + Creates a #GstCapsFeatures from a string representation. + +Free-function: gst_caps_features_free + + a new #GstCapsFeatures or + %NULL when the string could not be parsed. Free with + gst_caps_features_free() after use. + + + + + a string representation of a #GstCapsFeatures. + + + + + + + A function that will be called in gst_caps_filter_and_map_in_place(). +The function may modify @features and @structure, and both will be +removed from the caps if %FALSE is returned. + + %TRUE if the features and structure should be preserved, +%FALSE if it should be removed. + + + + + the #GstCapsFeatures + + + + the #GstStructure + + + + user data + + + + + + Extra flags for a caps. + + Caps has no specific content, but can contain + anything. + + + + A function that will be called in gst_caps_foreach(). The function may +not modify @features or @structure. + + %TRUE if the foreach operation should continue, %FALSE if +the foreach operation should stop with %FALSE. + + + + + the #GstCapsFeatures + + + + the #GstStructure + + + + user data + + + + + + Modes of caps intersection + +@GST_CAPS_INTERSECT_ZIG_ZAG tries to preserve overall order of both caps +by iterating on the caps' structures as the following matrix shows: +|[ + caps1 + +------------- + | 1 2 4 7 +caps2 | 3 5 8 10 + | 6 9 11 12 +]| +Used when there is no explicit precedence of one caps over the other. e.g. +tee's sink pad getcaps function, it will probe its src pad peers' for their +caps and intersect them with this mode. + +@GST_CAPS_INTERSECT_FIRST is useful when an element wants to preserve +another element's caps priority order when intersecting with its own caps. +Example: If caps1 is [A, B, C] and caps2 is [E, B, D, A], the result +would be [A, B], maintaining the first caps priority on the intersection. + + Zig-zags over both caps. + + + Keeps the first caps order. + + + + A function that will be called in gst_caps_map_in_place(). The function +may modify @features and @structure. + + %TRUE if the map operation should continue, %FALSE if +the map operation should stop with %FALSE. + + + + + the #GstCapsFeatures + + + + the #GstStructure + + + + user data + + + + + + This interface abstracts handling of property sets for elements with +children. Imagine elements such as mixers or polyphonic generators. They all +have multiple #GstPad or some kind of voice objects. Another use case are +container elements like #GstBin. +The element implementing the interface acts as a parent for those child +objects. + +By implementing this interface the child properties can be accessed from the +parent element by using gst_child_proxy_get() and gst_child_proxy_set(). + +Property names are written as "child-name::property-name". The whole naming +scheme is recursive. Thus "child1::child2::property" is valid too, if +"child1" and "child2" implement the #GstChildProxy interface. + + Emits the "child-added" signal. + + + + + + the parent object + + + + the newly added child + + + + the name of the new child + + + + + + Emits the "child-removed" signal. + + + + + + the parent object + + + + the removed child + + + + the name of the old child + + + + + + Fetches a child by its number. + + the child object or %NULL if + not found (index too high). Unref after usage. + +MT safe. + + + + + the parent object to get the child from + + + + the child's position in the child list + + + + + + Looks up a child element by the given name. + +This virtual method has a default implementation that uses #GstObject +together with gst_object_get_name(). If the interface is to be used with +#GObjects, this methods needs to be overridden. + + the child object or %NULL if + not found. Unref after usage. + +MT safe. + + + + + the parent object to get the child from + + + + the child's name + + + + + + Gets the number of child objects this parent contains. + + the number of child objects + +MT safe. + + + + + the parent object + + + + + + Emits the "child-added" signal. + + + + + + the parent object + + + + the newly added child + + + + the name of the new child + + + + + + Emits the "child-removed" signal. + + + + + + the parent object + + + + the removed child + + + + the name of the old child + + + + + + Gets properties of the parent object and its children. + + + + + + the parent object + + + + name of the first property to get + + + + return location for the first property, followed optionally by more name/return location pairs, followed by %NULL + + + + + + Fetches a child by its number. + + the child object or %NULL if + not found (index too high). Unref after usage. + +MT safe. + + + + + the parent object to get the child from + + + + the child's position in the child list + + + + + + Looks up a child element by the given name. + +This virtual method has a default implementation that uses #GstObject +together with gst_object_get_name(). If the interface is to be used with +#GObjects, this methods needs to be overridden. + + the child object or %NULL if + not found. Unref after usage. + +MT safe. + + + + + the parent object to get the child from + + + + the child's name + + + + + + Gets the number of child objects this parent contains. + + the number of child objects + +MT safe. + + + + + the parent object + + + + + + Gets a single property using the GstChildProxy mechanism. +You are responsible for freeing it by calling g_value_unset() + + + + + + object to query + + + + name of the property + + + + a #GValue that should take the result. + + + + + + Gets properties of the parent object and its children. + + + + + + the object to query + + + + name of the first property to get + + + + return location for the first property, followed optionally by more name/return location pairs, followed by %NULL + + + + + + Looks up which object and #GParamSpec would be effected by the given @name. + +MT safe. + + %TRUE if @target and @pspec could be found. %FALSE otherwise. In that +case the values for @pspec and @target are not modified. Unref @target after +usage. For plain GObjects @target is the same as @object. + + + + + child proxy object to lookup the property in + + + + name of the property to look up + + + + pointer to a #GObject that + takes the real object to set property on + + + + pointer to take the #GParamSpec + describing the property + + + + + + Sets properties of the parent object and its children. + + + + + + the parent object + + + + name of the first property to set + + + + value for the first property, followed optionally by more name/value pairs, followed by %NULL + + + + + + Sets a single property using the GstChildProxy mechanism. + + + + + + the parent object + + + + name of the property to set + + + + new #GValue for the property + + + + + + Sets properties of the parent object and its children. + + + + + + the parent object + + + + name of the first property to set + + + + value for the first property, followed optionally by more name/value pairs, followed by %NULL + + + + + + Will be emitted after the @object was added to the @child_proxy. + + + + + + the #GObject that was added + + + + the name of the new child + + + + + + Will be emitted after the @object was removed from the @child_proxy. + + + + + + the #GObject that was removed + + + + the name of the old child + + + + + + + #GstChildProxy interface. + + parent interface type. + + + + + + the child object or %NULL if + not found. Unref after usage. + +MT safe. + + + + + the parent object to get the child from + + + + the child's name + + + + + + + + + the child object or %NULL if + not found (index too high). Unref after usage. + +MT safe. + + + + + the parent object to get the child from + + + + the child's position in the child list + + + + + + + + + the number of child objects + +MT safe. + + + + + the parent object + + + + + + + + + + + + + the parent object + + + + the newly added child + + + + the name of the new child + + + + + + + + + + + + + the parent object + + + + the removed child + + + + the name of the old child + + + + + + + + + + + + + GStreamer uses a global clock to synchronize the plugins in a pipeline. +Different clock implementations are possible by implementing this abstract +base class or, more conveniently, by subclassing #GstSystemClock. + +The #GstClock returns a monotonically increasing time with the method +gst_clock_get_time(). Its accuracy and base time depend on the specific +clock implementation but time is always expressed in nanoseconds. Since the +baseline of the clock is undefined, the clock time returned is not +meaningful in itself, what matters are the deltas between two clock times. +The time returned by a clock is called the absolute time. + +The pipeline uses the clock to calculate the running time. Usually all +renderers synchronize to the global clock using the buffer timestamps, the +newsegment events and the element's base time, see #GstPipeline. + +A clock implementation can support periodic and single shot clock +notifications both synchronous and asynchronous. + +One first needs to create a #GstClockID for the periodic or single shot +notification using gst_clock_new_single_shot_id() or +gst_clock_new_periodic_id(). + +To perform a blocking wait for the specific time of the #GstClockID use the +gst_clock_id_wait(). To receive a callback when the specific time is reached +in the clock use gst_clock_id_wait_async(). Both these calls can be +interrupted with the gst_clock_id_unschedule() call. If the blocking wait is +unscheduled a return value of #GST_CLOCK_UNSCHEDULED is returned. + +Periodic callbacks scheduled async will be repeatedly called automatically +until it is unscheduled. To schedule a sync periodic callback, +gst_clock_id_wait() should be called repeatedly. + +The async callbacks can happen from any thread, either provided by the core +or from a streaming thread. The application should be prepared for this. + +A #GstClockID that has been unscheduled cannot be used again for any wait +operation, a new #GstClockID should be created and the old unscheduled one +should be destroyed with gst_clock_id_unref(). + +It is possible to perform a blocking wait on the same #GstClockID from +multiple threads. However, registering the same #GstClockID for multiple +async notifications is not possible, the callback will only be called for +the thread registering the entry last. + +None of the wait operations unref the #GstClockID, the owner is responsible +for unreffing the ids itself. This holds for both periodic and single shot +notifications. The reason being that the owner of the #GstClockID has to +keep a handle to the #GstClockID to unblock the wait on FLUSHING events or +state changes and if the entry would be unreffed automatically, the handle +might become invalid without any notification. + +These clock operations do not operate on the running time, so the callbacks +will also occur when not in PLAYING state as if the clock just keeps on +running. Some clocks however do not progress when the element that provided +the clock is not PLAYING. + +When a clock has the #GST_CLOCK_FLAG_CAN_SET_MASTER flag set, it can be +slaved to another #GstClock with the gst_clock_set_master(). The clock will +then automatically be synchronized to this master clock by repeatedly +sampling the master clock and the slave clock and recalibrating the slave +clock with gst_clock_set_calibration(). This feature is mostly useful for +plugins that have an internal clock but must operate with another clock +selected by the #GstPipeline. They can track the offset and rate difference +of their internal clock relative to the master clock by using the +gst_clock_get_calibration() function. + +The master/slave synchronisation can be tuned with the #GstClock:timeout, +#GstClock:window-size and #GstClock:window-threshold properties. +The #GstClock:timeout property defines the interval to sample the master +clock and run the calibration functions. #GstClock:window-size defines the +number of samples to use when calibrating and #GstClock:window-threshold +defines the minimum number of samples before the calibration is performed. + + Compares the two #GstClockID instances. This function can be used +as a GCompareFunc when sorting ids. + + negative value if a < b; zero if a = b; positive value if a > b + +MT safe. + + + + + A #GstClockID + + + + A #GstClockID to compare with + + + + + + Get the time of the clock ID + + the time of the given clock id. + +MT safe. + + + + + The #GstClockID to query + + + + + + Increase the refcount of given @id. + + The same #GstClockID with increased refcount. + +MT safe. + + + + + The #GstClockID to ref + + + + + + Unref given @id. When the refcount reaches 0 the +#GstClockID will be freed. + +MT safe. + + + + + + The #GstClockID to unref + + + + + + Cancel an outstanding request with @id. This can either +be an outstanding async notification or a pending sync notification. +After this call, @id cannot be used anymore to receive sync or +async notifications, you need to create a new #GstClockID. + +MT safe. + + + + + + The id to unschedule + + + + + + Perform a blocking wait on @id. +@id should have been created with gst_clock_new_single_shot_id() +or gst_clock_new_periodic_id() and should not have been unscheduled +with a call to gst_clock_id_unschedule(). + +If the @jitter argument is not %NULL and this function returns #GST_CLOCK_OK +or #GST_CLOCK_EARLY, it will contain the difference +against the clock and the time of @id when this method was +called. +Positive values indicate how late @id was relative to the clock +(in which case this function will return #GST_CLOCK_EARLY). +Negative values indicate how much time was spent waiting on the clock +before this function returned. + + the result of the blocking wait. #GST_CLOCK_EARLY will be returned +if the current clock time is past the time of @id, #GST_CLOCK_OK if +@id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was +unscheduled with gst_clock_id_unschedule(). + +MT safe. + + + + + The #GstClockID to wait on + + + + a pointer that will contain the jitter, + can be %NULL. + + + + + + Register a callback on the given #GstClockID @id with the given +function and user_data. When passing a #GstClockID with an invalid +time to this function, the callback will be called immediately +with a time set to GST_CLOCK_TIME_NONE. The callback will +be called when the time of @id has been reached. + +The callback @func can be invoked from any thread, either provided by the +core or from a streaming thread. The application should be prepared for this. + + the result of the non blocking wait. + +MT safe. + + + + + a #GstClockID to wait on + + + + The callback function + + + + User data passed in the callback + + + + #GDestroyNotify for user_data + + + + + + + + + + + + + + + + + + + + + + Gets the current internal time of the given clock. The time is returned +unadjusted for the offset and the rate. + + the internal time of the clock. Or GST_CLOCK_TIME_NONE when +given invalid input. + +MT safe. + + + + + a #GstClock to query + + + + + + Get the accuracy of the clock. The accuracy of the clock is the granularity +of the values returned by gst_clock_get_time(). + + the resolution of the clock in units of #GstClockTime. + +MT safe. + + + + + a #GstClock + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 +are available, a linear regression algorithm is run on the +observations and @clock is recalibrated. + +If this functions returns %TRUE, @r_squared will contain the +correlation coefficient of the interpolation. A value of 1.0 +means a perfect regression was performed. This value can +be used to control the sampling frequency of the master and slave +clocks. + + %TRUE if enough observations were added to run the +regression algorithm. + +MT safe. + + + + + a #GstClock + + + + a time on the slave + + + + a time on the master + + + + a pointer to hold the result + + + + + + Add a clock observation to the internal slaving algorithm the same as +gst_clock_add_observation(), and return the result of the master clock +estimation, without updating the internal calibration. + +The caller can then take the results and call gst_clock_set_calibration() +with the values, or some modified version of them. + + + + + + a #GstClock + + + + a time on the slave + + + + a time on the master + + + + a pointer to hold the result + + + + a location to store the internal time + + + + a location to store the external time + + + + a location to store the rate numerator + + + + a location to store the rate denominator + + + + + + Converts the given @internal clock time to the external time, adjusting for the +rate and reference time set with gst_clock_set_calibration() and making sure +that the returned time is increasing. This function should be called with the +clock's OBJECT_LOCK held and is mainly used by clock subclasses. + +This function is the reverse of gst_clock_unadjust_unlocked(). + + the converted time of the clock. + + + + + a #GstClock to use + + + + a clock time + + + + + + Converts the given @internal_target clock time to the external time, +using the passed calibration parameters. This function performs the +same calculation as gst_clock_adjust_unlocked() when called using the +current calibration parameters, but doesn't ensure a monotonically +increasing result as gst_clock_adjust_unlocked() does. + +Note: The @clock parameter is unused and can be NULL + + the converted time of the clock. + + + + + a #GstClock to use + + + + a clock time + + + + a reference internal time + + + + a reference external time + + + + the numerator of the rate of the clock relative to its + internal time + + + + the denominator of the rate of the clock + + + + + + Gets the internal rate and reference time of @clock. See +gst_clock_set_calibration() for more information. + +@internal, @external, @rate_num, and @rate_denom can be left %NULL if the +caller is not interested in the values. + +MT safe. + + + + + + a #GstClock + + + + a location to store the internal time + + + + a location to store the external time + + + + a location to store the rate numerator + + + + a location to store the rate denominator + + + + + + Gets the current internal time of the given clock. The time is returned +unadjusted for the offset and the rate. + + the internal time of the clock. Or GST_CLOCK_TIME_NONE when +given invalid input. + +MT safe. + + + + + a #GstClock to query + + + + + + Get the master clock that @clock is slaved to or %NULL when the clock is +not slaved to any master clock. + + a master #GstClock or %NULL + when this clock is not slaved to a master clock. Unref after + usage. + +MT safe. + + + + + a #GstClock + + + + + + Get the accuracy of the clock. The accuracy of the clock is the granularity +of the values returned by gst_clock_get_time(). + + the resolution of the clock in units of #GstClockTime. + +MT safe. + + + + + a #GstClock + + + + + + Gets the current time of the given clock. The time is always +monotonically increasing and adjusted according to the current +offset and rate. + + the time of the clock. Or GST_CLOCK_TIME_NONE when +given invalid input. + +MT safe. + + + + + a #GstClock to query + + + + + + Get the amount of time that master and slave clocks are sampled. + + the interval between samples. + + + + + a #GstClock + + + + + + Checks if the clock is currently synced. + +This returns if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock. + + %TRUE if the clock is currently synced + + + + + a GstClock + + + + + + Get an ID from @clock to trigger a periodic notification. +The periodic notifications will start at time @start_time and +will then be fired with the given @interval. @id should be unreffed +after usage. + +Free-function: gst_clock_id_unref + + a #GstClockID that can be used to request the + time notification. + +MT safe. + + + + + The #GstClockID to get a periodic notification id from + + + + the requested start time + + + + the requested interval + + + + + + Get a #GstClockID from @clock to trigger a single shot +notification at the requested time. The single shot id should be +unreffed after usage. + +Free-function: gst_clock_id_unref + + a #GstClockID that can be used to request the + time notification. + +MT safe. + + + + + The #GstClockID to get a single shot notification from + + + + the requested time + + + + + + Reinitializes the provided periodic @id to the provided start time and +interval. Does not modify the reference count. + + %TRUE if the GstClockID could be reinitialized to the provided +@time, else %FALSE. + + + + + a #GstClock + + + + a #GstClockID + + + + the requested start time + + + + the requested interval + + + + + + Adjusts the rate and time of @clock. A rate of 1/1 is the normal speed of +the clock. Values bigger than 1/1 make the clock go faster. + +@internal and @external are calibration parameters that arrange that +gst_clock_get_time() should have been @external at internal time @internal. +This internal time should not be in the future; that is, it should be less +than the value of gst_clock_get_internal_time() when this function is called. + +Subsequent calls to gst_clock_get_time() will return clock times computed as +follows: + +|[ + time = (internal_time - internal) * rate_num / rate_denom + external +]| + +This formula is implemented in gst_clock_adjust_unlocked(). Of course, it +tries to do the integer arithmetic as precisely as possible. + +Note that gst_clock_get_time() always returns increasing values so when you +move the clock backwards, gst_clock_get_time() will report the previous value +until the clock catches up. + +MT safe. + + + + + + a #GstClock to calibrate + + + + a reference internal time + + + + a reference external time + + + + the numerator of the rate of the clock relative to its + internal time + + + + the denominator of the rate of the clock + + + + + + 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 +master clock. + +A clock provider that slaves its clock to a master can get the current +calibration values with gst_clock_get_calibration(). + +@master can be %NULL in which case @clock will not be slaved anymore. It will +however keep reporting its time adjusted with the last configured rate +and time offsets. + + %TRUE if the clock is capable of being slaved to a master clock. +Trying to set a master on a clock without the +#GST_CLOCK_FLAG_CAN_SET_MASTER flag will make this function return %FALSE. + +MT safe. + + + + + a #GstClock + + + + a master #GstClock + + + + + + Set the accuracy of the clock. Some clocks have the possibility to operate +with different accuracy at the expense of more resource usage. There is +normally no need to change the default resolution of a clock. The resolution +of a clock can only be changed if the clock has the +#GST_CLOCK_FLAG_CAN_SET_RESOLUTION flag set. + + the new resolution of the clock. + + + + + a #GstClock + + + + The resolution to set + + + + + + Sets @clock to synced and emits the GstClock::synced signal, and wakes up any +thread waiting in gst_clock_wait_for_sync(). + +This function must only be called if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC +is set on the clock, and is intended to be called by subclasses only. + + + + + + a GstClock + + + + if the clock is synced + + + + + + Set the amount of time, in nanoseconds, to sample master and slave +clocks + + + + + + a #GstClock + + + + a timeout + + + + + + Reinitializes the provided single shot @id to the provided time. Does not +modify the reference count. + + %TRUE if the GstClockID could be reinitialized to the provided +@time, else %FALSE. + + + + + a #GstClock + + + + a #GstClockID + + + + The requested time. + + + + + + Converts the given @external clock time to the internal time of @clock, +using the rate and reference time set with gst_clock_set_calibration(). +This function should be called with the clock's OBJECT_LOCK held and +is mainly used by clock subclasses. + +This function is the reverse of gst_clock_adjust_unlocked(). + + the internal time of the clock corresponding to @external. + + + + + a #GstClock to use + + + + an external clock time + + + + + + Converts the given @external_target clock time to the internal time, +using the passed calibration parameters. This function performs the +same calculation as gst_clock_unadjust_unlocked() when called using the +current calibration parameters. + +Note: The @clock parameter is unused and can be NULL + + the converted time of the clock. + + + + + a #GstClock to use + + + + a clock time + + + + a reference internal time + + + + a reference external time + + + + the numerator of the rate of the clock relative to its + internal time + + + + the denominator of the rate of the clock + + + + + + Waits until @clock is synced for reporting the current time. If @timeout +is %GST_CLOCK_TIME_NONE it will wait forever, otherwise it will time out +after @timeout nanoseconds. + +For asynchronous waiting, the GstClock::synced signal can be used. + +This returns immediately with TRUE if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC +is not set on the clock, or if the clock is already synced. + + %TRUE if waiting was successful, or %FALSE on timeout + + + + + a GstClock + + + + timeout for waiting or %GST_CLOCK_TIME_NONE + + + + + + + + + + + + + + + + + + + + + + + + + + Signaled on clocks with GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC set once +the clock is synchronized, or when it completely lost synchronization. +This signal will not be emitted on clocks without the flag. + +This signal will be emitted from an arbitrary thread, most likely not +the application's main thread. + + + + + + if the clock is synced now + + + + + + + The function prototype of the callback. + + %TRUE or %FALSE (currently unused) + + + + + The clock that triggered the callback + + + + The time it was triggered + + + + The #GstClockID that expired + + + + user data passed in the gst_clock_id_wait_async() function + + + + + + GStreamer clock class. Override the vmethods to implement the clock +functionality. + + the parent class structure + + + + + + + + + + + + + + + + + + + + + + + + the resolution of the clock in units of #GstClockTime. + +MT safe. + + + + + a #GstClock + + + + + + + + + the internal time of the clock. Or GST_CLOCK_TIME_NONE when +given invalid input. + +MT safe. + + + + + a #GstClock to query + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + All pending timeouts or periodic notifies are converted into +an entry. +Note that GstClockEntry should be treated as an opaque structure. It must +not be extended or allocated using a custom allocator. + + reference counter (read-only) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The type of the clock entry + + a single shot timeout + + + a periodic timeout request + + + + The capabilities of this clock + + clock can do a single sync timeout request + + + clock can do a single async timeout request + + + clock can do sync periodic timeout requests + + + clock can do async periodic timeout callbacks + + + clock's resolution can be changed + + + clock can be slaved to a master clock + + + clock needs to be synced before it can be used + (Since 1.6) + + + subclasses can add additional flags starting from this flag + + + + + + The return value of a clock operation. + + The operation succeeded. + + + The operation was scheduled too late. + + + The clockID was unscheduled + + + The ClockID is busy + + + A bad time was provided to a function. + + + An error occurred + + + Operation is not supported + + + The ClockID is done waiting + + + + The different kind of clocks. + + time since Epoch + + + monotonic time since some unspecified starting + point + + + some other time source is used (Since 1.0.5) + + + + #GstContext is a container object used to store contexts like a device +context, a display server connection and similar concepts that should +be shared between multiple elements. + +Applications can set a context on a complete pipeline by using +gst_element_set_context(), which will then be propagated to all +child elements. Elements can handle these in #GstElementClass.set_context() +and merge them with the context information they already have. + +When an element needs a context it will do the following actions in this +order until one step succeeds: +1. Check if the element already has a context +2. Query downstream with GST_QUERY_CONTEXT for the context +3. Query upstream with GST_QUERY_CONTEXT for the context +4. Post a GST_MESSAGE_NEED_CONTEXT message on the bus with the required + context types and afterwards check if a usable context was set now +5. Create a context by itself and post a GST_MESSAGE_HAVE_CONTEXT message + on the bus. + +Bins will catch GST_MESSAGE_NEED_CONTEXT messages and will set any previously +known context on the element that asks for it if possible. Otherwise the +application should provide one if it can. + +#GstContext<!-- -->s can be persistent. +A persistent #GstContext is kept in elements when they reach +%GST_STATE_NULL, non-persistent ones will be removed. +Also, a non-persistent context won't override a previous persistent +context set to an element. + + Create a new context. + + The new context. + + + + + Context type + + + + Persistent context + + + + + + Get the type of @context. + + The type of the context. + + + + + The #GstContext. + + + + + + Access the structure of the context. + + The structure of the context. The structure is +still owned by the context, which means that you should not modify it, +free it and that the pointer becomes invalid when you free the context. + + + + + The #GstContext. + + + + + + Checks if @context has @context_type. + + %TRUE if @context has @context_type. + + + + + The #GstContext. + + + + Context type to check. + + + + + + Check if @context is persistent. + + %TRUE if the context is persistent. + + + + + The #GstContext. + + + + + + Get a writable version of the structure. + + The structure of the context. The structure is still +owned by the context, which means that you should not free it and +that the pointer becomes invalid when you free the context. +This function checks if @context is writable. + + + + + The #GstContext. + + + + + + + A base class for value mapping objects that attaches control sources to gobject +properties. Such an object is taking one or more #GstControlSource instances, +combines them and maps the resulting value to the type and value range of the +bound property. + + Gets a number of #GValues for the given controlled property starting at the +requested time. The array @values need to hold enough space for @n_values of +#GValue. + +This function is useful if one wants to e.g. draw a graph of the control +curve or apply a control curve sample by sample. + + %TRUE if the given array could be filled, %FALSE otherwise + + + + + the control binding + + + + the time that should be processed + + + + the time spacing between subsequent values + + + + the number of values + + + + array to put control-values in + + + + + + + + Gets the value for the given controlled property at the requested time. + + the GValue of the property at the given time, +or %NULL if the property isn't controlled. + + + + + the control binding + + + + the time the control-change should be read from + + + + + + Gets a number of values for the given controlled property starting at the +requested time. The array @values need to hold enough space for @n_values of +the same type as the objects property's type. + +This function is useful if one wants to e.g. draw a graph of the control +curve or apply a control curve sample by sample. + +The values are unboxed and ready to be used. The similar function +gst_control_binding_get_g_value_array() returns the array as #GValues and is +more suitable for bindings. + + %TRUE if the given array could be filled, %FALSE otherwise + + + + + the control binding + + + + the time that should be processed + + + + the time spacing between subsequent values + + + + the number of values + + + + array to put control-values in + + + + + + + + Sets the property of the @object, according to the #GstControlSources that +handle them and for the given timestamp. + +If this function fails, it is most likely the application developers fault. +Most probably the control sources are not setup correctly. + + %TRUE if the controller value could be applied to the object +property, %FALSE otherwise + + + + + the control binding + + + + the object that has controlled properties + + + + the time that should be processed + + + + the last time this was called + + + + + + Gets a number of #GValues for the given controlled property starting at the +requested time. The array @values need to hold enough space for @n_values of +#GValue. + +This function is useful if one wants to e.g. draw a graph of the control +curve or apply a control curve sample by sample. + + %TRUE if the given array could be filled, %FALSE otherwise + + + + + the control binding + + + + the time that should be processed + + + + the time spacing between subsequent values + + + + the number of values + + + + array to put control-values in + + + + + + + + Gets the value for the given controlled property at the requested time. + + the GValue of the property at the given time, +or %NULL if the property isn't controlled. + + + + + the control binding + + + + the time the control-change should be read from + + + + + + Gets a number of values for the given controlled property starting at the +requested time. The array @values need to hold enough space for @n_values of +the same type as the objects property's type. + +This function is useful if one wants to e.g. draw a graph of the control +curve or apply a control curve sample by sample. + +The values are unboxed and ready to be used. The similar function +gst_control_binding_get_g_value_array() returns the array as #GValues and is +more suitable for bindings. + + %TRUE if the given array could be filled, %FALSE otherwise + + + + + the control binding + + + + the time that should be processed + + + + the time spacing between subsequent values + + + + the number of values + + + + array to put control-values in + + + + + + + + Check if the control binding is disabled. + + %TRUE if the binding is inactive + + + + + the control binding + + + + + + This function is used to disable a control binding for some time, i.e. +gst_object_sync_values() will do nothing. + + + + + + the control binding + + + + boolean that specifies whether to disable the controller +or not. + + + + + + Sets the property of the @object, according to the #GstControlSources that +handle them and for the given timestamp. + +If this function fails, it is most likely the application developers fault. +Most probably the control sources are not setup correctly. + + %TRUE if the controller value could be applied to the object +property, %FALSE otherwise + + + + + the control binding + + + + the object that has controlled properties + + + + the time that should be processed + + + + the last time this was called + + + + + + + + + + + + + + + name of the property of this binding + + + + #GParamSpec for this property + + + + + + + + + + + + + + + + + + + + + + + The class structure of #GstControlBinding. + + Parent class + + + + + + %TRUE if the controller value could be applied to the object +property, %FALSE otherwise + + + + + the control binding + + + + the object that has controlled properties + + + + the time that should be processed + + + + the last time this was called + + + + + + + + + the GValue of the property at the given time, +or %NULL if the property isn't controlled. + + + + + the control binding + + + + the time the control-change should be read from + + + + + + + + + %TRUE if the given array could be filled, %FALSE otherwise + + + + + the control binding + + + + the time that should be processed + + + + the time spacing between subsequent values + + + + the number of values + + + + array to put control-values in + + + + + + + + + + + %TRUE if the given array could be filled, %FALSE otherwise + + + + + the control binding + + + + the time that should be processed + + + + the time spacing between subsequent values + + + + the number of values + + + + array to put control-values in + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The #GstControlSource is a base class for control value sources that could +be used to get timestamp-value pairs. A control source essentially is a +function over time. + +A #GstControlSource is used by first getting an instance of a specific +control-source, creating a binding for the control-source to the target property +of the element and then adding the binding to the element. The binding will +convert the data types and value range to fit to the bound property. + +For implementing a new #GstControlSource one has to implement +#GstControlSourceGetValue and #GstControlSourceGetValueArray functions. +These are then used by gst_control_source_get_value() and +gst_control_source_get_value_array() to get values for specific timestamps. + + Gets the value for this #GstControlSource at a given timestamp. + + %FALSE if the value couldn't be returned, %TRUE otherwise. + + + + + the #GstControlSource object + + + + the time for which the value should be returned + + + + the value + + + + + + Gets an array of values for for this #GstControlSource. Values that are +undefined contain NANs. + + %TRUE if the given array could be filled, %FALSE otherwise + + + + + the #GstControlSource object + + + + the first timestamp + + + + the time steps + + + + the number of values to fetch + + + + array to put control-values in + + + + + + + + + + + Function for returning a value for a given timestamp + + + + Function for returning a values array for a given timestamp + + + + + + + + + + The class structure of #GstControlSource. + + Parent class + + + + + + + + + + Function for returning a value for a given timestamp. + + %TRUE if the value was successfully calculated. + + + + + the #GstControlSource instance + + + + timestamp for which a value should be calculated + + + + a value which will be set to the result. + + + + + + Function for returning an array of values for starting at a given timestamp. + + %TRUE if the values were successfully calculated. + + + + + the #GstControlSource instance + + + + timestamp for which a value should be calculated + + + + the time spacing between subsequent values + + + + the number of values + + + + array to put control-values in + + + + + + Core errors are errors inside the core GStreamer library. + + a general error which doesn't fit in any other +category. Make sure you add a custom message to the error call. + + + do not use this except as a placeholder for +deciding where to go while developing code. + + + use this when you do not want to implement +this functionality yet. + + + used for state change errors. + + + used for pad-related errors. + + + used for thread-related errors. + + + used for negotiation-related errors. + + + used for event-related errors. + + + used for seek-related errors. + + + used for caps-related errors. + + + used for negotiation-related errors. + + + used if a plugin is missing. + + + used for clock related errors. + + + used if functionality has been disabled at + compile time. + + + the number of core error types. + + + + + + + + + + + + + + + + + + Struct to store date, time and timezone information altogether. +#GstDateTime is refcounted and immutable. + +Date information is handled using the proleptic Gregorian calendar. + +Provides basic creation functions and accessor functions to its fields. + + Creates a new #GstDateTime using the date and times in the gregorian calendar +in the supplied timezone. + +@year should be from 1 to 9999, @month should be from 1 to 12, @day from +1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59. + +Note that @tzoffset is a float and was chosen so for being able to handle +some fractional timezones, while it still keeps the readability of +representing it in hours for most timezones. + +If value is -1 then all over value will be ignored. For example +if @month == -1, then #GstDateTime will created only for @year. If +@day == -1, then #GstDateTime will created for @year and @month and +so on. + +Free-function: gst_date_time_unref + + the newly created #GstDateTime + + + + + Offset from UTC in hours. + + + + the gregorian year + + + + the gregorian month + + + + the day of the gregorian month + + + + the hour of the day + + + + the minute of the hour + + + + the second of the minute + + + + + + Creates a new #GstDateTime from a #GDateTime object. + +Free-function: gst_date_time_unref + + a newly created #GstDateTime, +or %NULL on error + + + + + the #GDateTime. The new #GstDateTime takes ownership. + + + + + + Tries to parse common variants of ISO-8601 datetime strings into a +#GstDateTime. Possible input formats are (for example): +2012-06-30T22:46:43Z, 2012, 2012-06, 2012-06-30, 2012-06-30T22:46:43-0430, +2012-06-30T22:46Z, 2012-06-30T22:46-0430, 2012-06-30 22:46, +2012-06-30 22:46:43, 2012-06-00, 2012-00-00, 2012-00-30, 22:46:43Z, 22:46Z, +22:46:43-0430, 22:46-0430, 22:46:30, 22:46 +If no date is provided, it is assumed to be "today" in the timezone +provided (if any), otherwise UTC. + +Free-function: gst_date_time_unref + + a newly created #GstDateTime, +or %NULL on error + + + + + ISO 8601-formatted datetime string. + + + + + + Creates a new #GstDateTime using the time since Jan 1, 1970 specified by +@secs. The #GstDateTime is in the local timezone. + +Free-function: gst_date_time_unref + + the newly created #GstDateTime + + + + + seconds from the Unix epoch + + + + + + Creates a new #GstDateTime using the time since Jan 1, 1970 specified by +@secs. The #GstDateTime is in the UTC timezone. + +Free-function: gst_date_time_unref + + the newly created #GstDateTime + + + + + seconds from the Unix epoch + + + + + + Creates a new #GstDateTime using the date and times in the gregorian calendar +in the local timezone. + +@year should be from 1 to 9999, @month should be from 1 to 12, @day from +1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59. + +If @month is -1, then the #GstDateTime created will only contain @year, +and all other fields will be considered not set. + +If @day is -1, then the #GstDateTime created will only contain @year and +@month and all other fields will be considered not set. + +If @hour is -1, then the #GstDateTime created will only contain @year and +@month and @day, and the time fields will be considered not set. In this +case @minute and @seconds should also be -1. + +Free-function: gst_date_time_unref + + the newly created #GstDateTime + + + + + the gregorian year + + + + the gregorian month, or -1 + + + + the day of the gregorian month, or -1 + + + + the hour of the day, or -1 + + + + the minute of the hour, or -1 + + + + the second of the minute, or -1 + + + + + + Creates a new #GstDateTime representing the current date and time. + +Free-function: gst_date_time_unref + + the newly created #GstDateTime which should + be freed with gst_date_time_unref(). + + + + + Creates a new #GstDateTime that represents the current instant at Universal +coordinated time. + +Free-function: gst_date_time_unref + + the newly created #GstDateTime which should + be freed with gst_date_time_unref(). + + + + + Creates a new #GstDateTime using the date and times in the gregorian calendar +in the local timezone. + +@year should be from 1 to 9999. + +Free-function: gst_date_time_unref + + the newly created #GstDateTime + + + + + the gregorian year + + + + + + Creates a new #GstDateTime using the date and times in the gregorian calendar +in the local timezone. + +@year should be from 1 to 9999, @month should be from 1 to 12. + +If value is -1 then all over value will be ignored. For example +if @month == -1, then #GstDateTime will created only for @year. + +Free-function: gst_date_time_unref + + the newly created #GstDateTime + + + + + the gregorian year + + + + the gregorian month + + + + + + Creates a new #GstDateTime using the date and times in the gregorian calendar +in the local timezone. + +@year should be from 1 to 9999, @month should be from 1 to 12, @day from +1 to 31. + +If value is -1 then all over value will be ignored. For example +if @month == -1, then #GstDateTime will created only for @year. If +@day == -1, then #GstDateTime will created for @year and @month and +so on. + +Free-function: gst_date_time_unref + + the newly created #GstDateTime + + + + + the gregorian year + + + + the gregorian month + + + + the day of the gregorian month + + + + + + Returns the day of the month of this #GstDateTime. +Call gst_date_time_has_day before, to avoid warnings. + + The day of this #GstDateTime + + + + + a #GstDateTime + + + + + + Retrieves the hour of the day represented by @datetime in the gregorian +calendar. The return is in the range of 0 to 23. +Call gst_date_time_has_haur before, to avoid warnings. + + the hour of the day + + + + + a #GstDateTime + + + + + + Retrieves the fractional part of the seconds in microseconds represented by +@datetime in the gregorian calendar. + + the microsecond of the second + + + + + a #GstDateTime + + + + + + Retrieves the minute of the hour represented by @datetime in the gregorian +calendar. +Call gst_date_time_has_minute before, to avoid warnings. + + the minute of the hour + + + + + a #GstDateTime + + + + + + Returns the month of this #GstDateTime. January is 1, February is 2, etc.. +Call gst_date_time_has_month before, to avoid warnings. + + The month of this #GstDateTime + + + + + a #GstDateTime + + + + + + Retrieves the second of the minute represented by @datetime in the gregorian +calendar. +Call gst_date_time_has_second before, to avoid warnings. + + the second represented by @datetime + + + + + a #GstDateTime + + + + + + Retrieves the offset from UTC in hours that the timezone specified +by @datetime represents. Timezones ahead (to the east) of UTC have positive +values, timezones before (to the west) of UTC have negative values. +If @datetime represents UTC time, then the offset is zero. + + the offset from UTC in hours + + + + + a #GstDateTime + + + + + + Returns the year of this #GstDateTime +Call gst_date_time_has_year before, to avoid warnings. + + The year of this #GstDateTime + + + + + a #GstDateTime + + + + + + + %TRUE if @datetime<!-- -->'s day field is set, otherwise %FALSE + + + + + a #GstDateTime + + + + + + + %TRUE if @datetime<!-- -->'s month field is set, otherwise %FALSE + + + + + a #GstDateTime + + + + + + + %TRUE if @datetime<!-- -->'s second field is set, otherwise %FALSE + + + + + a #GstDateTime + + + + + + + %TRUE if @datetime<!-- -->'s hour and minute fields are set, + otherwise %FALSE + + + + + a #GstDateTime + + + + + + + %TRUE if @datetime<!-- -->'s year field is set (which should always + be the case), otherwise %FALSE + + + + + a #GstDateTime + + + + + + Atomically increments the reference count of @datetime by one. + + the reference @datetime + + + + + a #GstDateTime + + + + + + Creates a new #GDateTime from a fully defined #GstDateTime object. + +Free-function: g_date_time_unref + + a newly created #GDateTime, or +%NULL on error + + + + + GstDateTime. + + + + + + Create a minimal string compatible with ISO-8601. Possible output formats +are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z, +2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100 + + a newly allocated string formatted according + to ISO 8601 and only including the datetime fields that are + valid, or %NULL in case there was an error. The string should + be freed with g_free(). + + + + + GstDateTime. + + + + + + Atomically decrements the reference count of @datetime by one. When the +reference count reaches zero, the structure is freed. + + + + + + a #GstDateTime + + + + + + + This is the struct that describes the categories. Once initialized with +#GST_DEBUG_CATEGORY_INIT, its values can't be changed anymore. + + + + + + + + + + + + + + Removes and frees the category and all associated resources. + + + + + + #GstDebugCategory to free. + + + + + + Returns the color of a debug category used when printing output in this +category. + + the color of the category. + + + + + a #GstDebugCategory to get the color of. + + + + + + Returns the description of a debug category. + + the description of the category. + + + + + a #GstDebugCategory to get the description of. + + + + + + Returns the name of a debug category. + + the name of the category. + + + + + a #GstDebugCategory to get name of. + + + + + + Returns the threshold of a #GstDebugCategory. + + the #GstDebugLevel that is used as threshold. + + + + + a #GstDebugCategory to get threshold of. + + + + + + Resets the threshold of the category to the default level. Debug information +will only be output if the threshold is lower or equal to the level of the +debugging message. +Use this function to set the threshold back to where it was after using +gst_debug_category_set_threshold(). + + + + + + a #GstDebugCategory to reset threshold of. + + + + + + Sets the threshold of the category to the given level. Debug information will +only be output if the threshold is lower or equal to the level of the +debugging message. +> Do not use this function in production code, because other functions may +> change the threshold of categories as side effect. It is however a nice +> function to use when debugging (even from gdb). + + + + + + a #GstDebugCategory to set threshold of. + + + + the #GstDebugLevel threshold to set. + + + + + + + These are some terminal style flags you can use when creating your +debugging categories to make them stand out in debugging output. + + Use black as foreground color. + + + Use red as foreground color. + + + Use green as foreground color. + + + Use yellow as foreground color. + + + Use blue as foreground color. + + + Use magenta as foreground color. + + + Use cyan as foreground color. + + + Use white as foreground color. + + + Use black as background color. + + + Use red as background color. + + + Use green as background color. + + + Use yellow as background color. + + + Use blue as background color. + + + Use magenta as background color. + + + Use cyan as background color. + + + Use white as background color. + + + Make the output bold. + + + Underline the output. + + + + + Do not use colors in logs. + + + Paint logs in a platform-specific way. + + + Paint logs with UNIX terminal color codes + no matter what platform GStreamer is running on. + + + + + + + + + Available details for pipeline graphs produced by GST_DEBUG_BIN_TO_DOT_FILE() +and GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS(). + + show caps-name on edges + + + show caps-details on edges + + + show modified parameters on + elements + + + show element states + + + show full element parameter values even + if they are very long + + + show all the typical details that one might want + + + show all details regardless of how large or + verbose they make the resulting output + + + + The level defines the importance of a debugging message. The more important a +message is, the greater the probability that the debugging system outputs it. + + No debugging level specified or desired. Used to deactivate + debugging output. + + + Error messages are to be used only when an error occurred + that stops the application from keeping working correctly. + An examples is gst_element_error, which outputs a message with this priority. + It does not mean that the application is terminating as with g_error. + + + Warning messages are to inform about abnormal behaviour + that could lead to problems or weird behaviour later on. An example of this + would be clocking issues ("your computer is pretty slow") or broken input + data ("Can't synchronize to stream.") + + + Fixme messages are messages that indicate that something + in the executed code path is not fully implemented or handled yet. Note + that this does not replace proper error handling in any way, the purpose + of this message is to make it easier to spot incomplete/unfinished pieces + of code when reading the debug log. + + + Informational messages should be used to keep the developer + updated about what is happening. + Examples where this should be used are when a typefind function has + successfully determined the type of the stream or when an mp3 plugin detects + the format to be used. ("This file has mono sound.") + + + Debugging messages should be used when something common + happens that is not the expected default behavior, or something that's + useful to know but doesn't happen all the time (ie. per loop iteration or + buffer processed or event handled). + An example would be notifications about state changes or receiving/sending + of events. + + + Log messages are messages that are very common but might be + useful to know. As a rule of thumb a pipeline that is running as expected + should never output anything else but LOG messages whilst processing data. + Use this log level to log recurring information in chain functions and + loop functions, for example. + + + Tracing-related messages. + Examples for this are referencing/dereferencing of objects. + + + memory dump messages are used to log (small) chunks of + data as memory dumps in the log. They will be displayed as hexdump with + ASCII characters. + + + The number of defined debugging levels. + + + Get the string representation of a debugging level + + the name + + + + + the level to get the name for + + + + + + + + Gets the string representation of a #GstDebugMessage. This function is used +in debug handlers to extract the message. + + the string representation of a #GstDebugMessage. + + + + + a debug message + + + + + + + #GstDevice are objects representing a device, they contain +relevant metadata about the device, such as its class and the #GstCaps +representing the media types it can produce or handle. + +#GstDevice are created by #GstDeviceProvider objects which can be +aggregated by #GstDeviceMonitor objects. + + Creates the element with all of the required parameters set to use +this device. + + a new #GstElement configured to use this device + + + + + a #GstDevice + + + + name of new element, or %NULL to automatically +create a unique name. + + + + + + Tries to reconfigure an existing element to use the device. If this +function fails, then one must destroy the element and create a new one +using gst_device_create_element(). + +Note: This should only be implemented for elements can change their +device in the PLAYING state. + + %TRUE if the element could be reconfigured to use this device, +%FALSE otherwise. + + + + + a #GstDevice + + + + a #GstElement + + + + + + Creates the element with all of the required parameters set to use +this device. + + a new #GstElement configured to use this device + + + + + a #GstDevice + + + + name of new element, or %NULL to automatically +create a unique name. + + + + + + Getter for the #GstCaps that this device supports. + + The #GstCaps supported by this device. Unref with +gst_caps_unref() when done. + + + + + a #GstDevice + + + + + + Gets the "class" of a device. This is a "/" separated list of +classes that represent this device. They are a subset of the +classes of the #GstDeviceProvider that produced this device. + + The device class. Free with g_free() after use. + + + + + a #GstDevice + + + + + + Gets the user-friendly name of the device. + + The device name. Free with g_free() after use. + + + + + a #GstDevice + + + + + + Gets the extra properties of a device. + + The extra properties or %NULL when there are none. + Free with gst_structure_free() after use. + + + + + a #GstDevice + + + + + + Check if @device matches all of the given classes + + %TRUE if @device matches. + + + + + a #GstDevice + + + + a "/"-separated list of device classes to match, only match if + all classes are matched + + + + + + Check if @factory matches all of the given classes + + %TRUE if @device matches. + + + + + a #GstDevice + + + + a %NULL terminated array of classes + to match, only match if all classes are matched + + + + + + + + Tries to reconfigure an existing element to use the device. If this +function fails, then one must destroy the element and create a new one +using gst_device_create_element(). + +Note: This should only be implemented for elements can change their +device in the PLAYING state. + + %TRUE if the element could be reconfigured to use this device, +%FALSE otherwise. + + + + + a #GstDevice + + + + a #GstElement + + + + + + + + + + + + + + + + + + The parent #GstObject strucuture. + + + + + + + + + + + + + + + + + + The class structure for a #GstDevice object. + + The parent #GstObjectClass strucuture. + + + + + + a new #GstElement configured to use this device + + + + + a #GstDevice + + + + name of new element, or %NULL to automatically +create a unique name. + + + + + + + + + %TRUE if the element could be reconfigured to use this device, +%FALSE otherwise. + + + + + a #GstDevice + + + + a #GstElement + + + + + + + + + + + + + Applications should create a #GstDeviceMonitor when they want +to probe, list and monitor devices of a specific type. The +#GstDeviceMonitor will create the appropriate +#GstDeviceProvider objects and manage them. It will then post +messages on its #GstBus for devices that have been added and +removed. + +The device monitor will monitor all devices matching the filters that +the application has set. + +The basic use pattern of a device monitor is as follows: +|[ + static gboolean + my_bus_func (GstBus * bus, GstMessage * message, gpointer user_data) + { + GstDevice *device; + gchar *name; + + switch (GST_MESSAGE_TYPE (message)) { + case GST_MESSAGE_DEVICE_ADDED: + gst_message_parse_device_added (message, &device); + name = gst_device_get_display_name (device); + g_print("Device added: %s\n", name); + g_free (name); + gst_object_unref (device); + break; + case GST_MESSAGE_DEVICE_REMOVED: + gst_message_parse_device_removed (message, &device); + name = gst_device_get_display_name (device); + g_print("Device removed: %s\n", name); + g_free (name); + gst_object_unref (device); + break; + default: + break; + } + + return G_SOURCE_CONTINUE; + } + + GstDeviceMonitor * + setup_raw_video_source_device_monitor (void) { + GstDeviceMonitor *monitor; + GstBus *bus; + GstCaps *caps; + + monitor = gst_device_monitor_new (); + + bus = gst_device_monitor_get_bus (monitor); + gst_bus_add_watch (bus, my_bus_func, NULL); + gst_object_unref (bus); + + caps = gst_caps_new_empty_simple ("video/x-raw"); + gst_device_monitor_add_filter (monitor, "Video/Source", caps); + gst_caps_unref (caps); + + gst_device_monitor_start (monitor); + + return monitor; + } +]| + + Create a new #GstDeviceMonitor + + a new device monitor. + + + + + Adds a filter for which #GstDevice will be monitored, any device that matches +all these classes and the #GstCaps will be returned. + +If this function is called multiple times to add more filters, each will be +matched independently. That is, adding more filters will not further restrict +what devices are matched. + +The #GstCaps supported by the device as returned by gst_device_get_caps() are +not intersected with caps filters added using this function. + +Filters must be added before the #GstDeviceMonitor is started. + + The id of the new filter or 0 if no provider matched the filter's + classes. + + + + + a device monitor + + + + device classes to use as filter or %NULL for any class + + + + the #GstCaps to filter or %NULL for ANY + + + + + + Gets the #GstBus of this #GstDeviceMonitor + + a #GstBus + + + + + a #GstDeviceProvider + + + + + + Gets a list of devices from all of the relevant monitors. This may actually +probe the hardware if the monitor is not currently started. + + a #GList of + #GstDevice + + + + + + + A #GstDeviceProvider + + + + + + Get a list of the currently selected device provider factories. + +This + + + A list of device provider factory names that are currently being + monitored by @monitor or %NULL when nothing is being monitored. + + + + + + + a #GstDeviceMonitor + + + + + + Get if @monitor is curretly showing all devices, even those from hidden +providers. + + %TRUE when all devices will be shown. + + + + + a #GstDeviceMonitor + + + + + + Removes a filter from the #GstDeviceMonitor using the id that was returned +by gst_device_monitor_add_filter(). + + %TRUE of the filter id was valid, %FALSE otherwise + + + + + a device monitor + + + + the id of the filter + + + + + + Set if all devices should be visible, even those devices from hidden +providers. Setting @show_all to true might show some devices multiple times. + + + + + + a #GstDeviceMonitor + + + + show all devices + + + + + + Starts monitoring the devices, one this has succeeded, the +%GST_MESSAGE_DEVICE_ADDED and %GST_MESSAGE_DEVICE_REMOVED messages +will be emitted on the bus when the list of devices changes. + + %TRUE if the device monitoring could be started + + + + + A #GstDeviceMonitor + + + + + + Stops monitoring the devices. + + + + + + A #GstDeviceProvider + + + + + + + + + the parent #GstObject structure + + + + + + + + + + + + + Opaque device monitor class structure. + + the parent #GstObjectClass structure + + + + + + + + + + + + + + A #GstDeviceProvider subclass is provided by a plugin that handles devices +if there is a way to programatically list connected devices. It can also +optionally provide updates to the list of connected devices. + +Each #GstDeviceProvider subclass is a singleton, a plugin should +normally provide a single subclass for all devices. + +Applications would normally use a #GstDeviceMonitor to monitor devices +from all relevant providers. + + Create a new device providerfactory capable of instantiating objects of the +@type and add the factory to @plugin. + + %TRUE, if the registering succeeded, %FALSE on error + + + + + #GstPlugin to register the device provider with, or %NULL for + a static device provider. + + + + name of device providers of this type + + + + rank of device provider (higher rank means more importance when autoplugging) + + + + GType of device provider to register + + + + + + + + + + + + + + + + + + Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED +and #GST_MESSAGE_DEVICE_REMOVED messages to be posted on the provider's bus +when devices are added or removed from the system. + +Since the #GstDeviceProvider is a singleton, +gst_device_provider_start() may already have been called by another +user of the object, gst_device_provider_stop() needs to be called the same +number of times. + + %TRUE if the device providering could be started + + + + + A #GstDeviceProvider + + + + + + Decreases the use-count by one. If the use count reaches zero, this +#GstDeviceProvider will stop providering the devices. This needs to be +called the same number of times that gst_device_provider_start() was called. + + + + + + A #GstDeviceProvider + + + + + + + + + + + + + + + + Posts a message on the provider's #GstBus to inform applications that +a new device has been added. + +This is for use by subclasses. + + + + + + a #GstDeviceProvider + + + + a #GstDevice that has been added + + + + + + Posts a message on the provider's #GstBus to inform applications that +a device has been removed. + +This is for use by subclasses. + + + + + + a #GstDeviceProvider + + + + a #GstDevice that has been removed + + + + + + Gets the #GstBus of this #GstDeviceProvider + + a #GstBus + + + + + a #GstDeviceProvider + + + + + + Gets a list of devices that this provider understands. This may actually +probe the hardware if the provider is not currently started. + + a #GList of + #GstDevice + + + + + + + A #GstDeviceProvider + + + + + + Retrieves the factory that was used to create this device provider. + + the #GstDeviceProviderFactory used for + creating this device provider. no refcounting is needed. + + + + + a #GstDeviceProvider to request the device provider factory of. + + + + + + Get the provider factory names of the #GstDeviceProvider instances that +are hidden by @provider. + + + a list of hidden providers factory names or %NULL when + nothing is hidden by @provider. Free with g_strfreev. + + + + + + + a #GstDeviceProvider + + + + + + Make @provider hide the devices from the factory with @name. + +This function is used when @provider will also provide the devices reported +by provider factory @name. A monitor should stop monitoring the +device provider with @name to avoid duplicate devices. + + + + + + a #GstDeviceProvider + + + + a provider factory name + + + + + + Starts providering the devices. This will cause #GST_MESSAGE_DEVICE_ADDED +and #GST_MESSAGE_DEVICE_REMOVED messages to be posted on the provider's bus +when devices are added or removed from the system. + +Since the #GstDeviceProvider is a singleton, +gst_device_provider_start() may already have been called by another +user of the object, gst_device_provider_stop() needs to be called the same +number of times. + + %TRUE if the device providering could be started + + + + + A #GstDeviceProvider + + + + + + Decreases the use-count by one. If the use count reaches zero, this +#GstDeviceProvider will stop providering the devices. This needs to be +called the same number of times that gst_device_provider_start() was called. + + + + + + A #GstDeviceProvider + + + + + + Make @provider unhide the devices from factory @name. + +This function is used when @provider will no longer provide the devices +reported by provider factory @name. A monitor should start +monitoring the devices from provider factory @name in order to see +all devices again. + + + + + + a #GstDeviceProvider + + + + a provider factory name + + + + + + The parent #GstObject + + + + a #GList of the #GstDevice objects + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The structure of the base #GstDeviceProviderClass + + the parent #GstObjectClass structure + + + + a pointer to the #GstDeviceProviderFactory that creates this + provider + + + + + + + + + + + + + + + + + + + + %TRUE if the device providering could be started + + + + + A #GstDeviceProvider + + + + + + + + + + + + + A #GstDeviceProvider + + + + + + + + + + + + + + + Set @key with @value as metadata in @klass. + + + + + + class to set metadata for + + + + the key to set + + + + the value to set + + + + + + Set @key with @value as metadata in @klass. + +Same as gst_device_provider_class_add_metadata(), but @value must be a static string +or an inlined string, as it will not be copied. (GStreamer plugins will +be made resident once loaded, so this function can be used even from +dynamically loaded plugins.) + + + + + + class to set metadata for + + + + the key to set + + + + the value to set + + + + + + Get metadata with @key in @klass. + + the metadata for @key. + + + + + class to get metadata for + + + + the key to get + + + + + + Sets the detailed information for a #GstDeviceProviderClass. + +> This function is for use in _class_init functions only. + + + + + + class to set metadata for + + + + The long English name of the device provider. E.g. "File Sink" + + + + String describing the type of device provider, as an + unordered list separated with slashes ('/'). See draft-klass.txt of the + design docs +for more details and common types. E.g: "Sink/File" + + + + Sentence describing the purpose of the device provider. +E.g: "Write stream to a file" + + + + Name and contact details of the author(s). Use \n to separate +multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" + + + + + + Sets the detailed information for a #GstDeviceProviderClass. + +> This function is for use in _class_init functions only. + +Same as gst_device_provider_class_set_metadata(), but @longname, @classification, +@description, and @author must be static strings or inlined strings, as +they will not be copied. (GStreamer plugins will be made resident once +loaded, so this function can be used even from dynamically loaded plugins.) + + + + + + class to set metadata for + + + + The long English name of the element. E.g. "File Sink" + + + + String describing the type of element, as +an unordered list separated with slashes ('/'). See draft-klass.txt of the +design docs for more details and common types. E.g: "Sink/File" + + + + Sentence describing the purpose of the +element. E.g: "Write stream to a file" + + + + Name and contact details of the author(s). Use \n +to separate multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at +foo.com&gt;" + + + + + + + #GstDeviceProviderFactory is used to create instances of device providers. A +GstDeviceProviderfactory can be added to a #GstPlugin as it is also a +#GstPluginFeature. + +Use the gst_device_provider_factory_find() and +gst_device_provider_factory_get() functions to create device +provider instances or use gst_device_provider_factory_get_by_name() as a +convenient shortcut. + + Search for an device provider factory of the given name. Refs the returned +device provider factory; caller is responsible for unreffing. + + #GstDeviceProviderFactory if +found, %NULL otherwise + + + + + name of factory to find + + + + + + Returns the device provider of the type defined by the given device +provider factory. + + a #GstDeviceProvider or %NULL +if unable to create device provider + + + + + a named factory to instantiate + + + + + + Get a list of factories with a rank greater or equal to @minrank. +The list of factories is returned by decreasing rank. + + +a #GList of #GstDeviceProviderFactory device providers. Use +gst_plugin_feature_list_free() after usage. + + + + + + + Minimum rank + + + + + + Returns the device provider of the type defined by the given device +providerfactory. + + the #GstDeviceProvider or %NULL +if the device provider couldn't be created + + + + + factory to instantiate + + + + + + Get the #GType for device providers managed by this factory. The type can +only be retrieved if the device provider factory is loaded, which can be +assured with gst_plugin_feature_load(). + + the #GType for device providers managed by this factory. + + + + + factory to get managed #GType from + + + + + + Get the metadata on @factory with @key. + + the metadata with @key on @factory or %NULL +when there was no metadata with the given @key. + + + + + a #GstDeviceProviderFactory + + + + a key + + + + + + Get the available keys for the metadata on @factory. + + +a %NULL-terminated array of key strings, or %NULL when there is no +metadata. Free with g_strfreev() when no longer needed. + + + + + + + a #GstDeviceProviderFactory + + + + + + Check if @factory matches all of the given @classes + + %TRUE if @factory matches or if @classes is %NULL. + + + + + a #GstDeviceProviderFactory + + + + a "/" separate list of classes to match, only match + if all classes are matched + + + + + + Check if @factory matches all of the given classes + + %TRUE if @factory matches. + + + + + a #GstDeviceProviderFactory + + + + a %NULL terminated array + of classes to match, only match if all classes are matched + + + + + + + + + The opaque #GstDeviceProviderFactoryClass data structure. + + + + + + + #GstDynamicTypeFactory is used to represent a type that can be +automatically loaded the first time it is used. For example, +a non-standard type for use in caps fields. + +In general, applications and plugins don't need to use the factory +beyond registering the type in a plugin init function. Once that is +done, the type is stored in the registry, and ready as soon as the +registry is loaded. + +## Registering a type for dynamic loading + +|[<!-- language="C" --> + +static gboolean +plugin_init (GstPlugin * plugin) +{ + return gst_dynamic_type_register (plugin, GST_TYPE_CUSTOM_CAPS_FIELD); +} +]| + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Elements of any of the defined GST_ELEMENT_FACTORY_LIST types + + + + All sinks handling audio, video or image media types + + + + All encoders handling audio media types + + + + All elements used to 'decode' streams (decoders, demuxers, parsers, depayloaders) + + + + + + + + + + + + + + + + + + + + + + + + + + + + Elements matching any of the defined GST_ELEMENT_FACTORY_TYPE_MEDIA types + +Note: Do not use this if you wish to not filter against any of the defined +media types. If you wish to do this, simply don't specify any +GST_ELEMENT_FACTORY_TYPE_MEDIA flag. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + All encoders handling video or image media types + + + + Name and contact details of the author(s). Use \n to separate +multiple author details. +E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" + + + + Sentence describing the purpose of the element. +E.g: "Write stream to a file" + + + + Set uri pointing to user documentation. Applications can use this to show +help for e.g. effects to users. + + + + Elements that bridge to certain other products can include an icon of that +used product. Application can show the icon in menus/selectors to help +identifying specific elements. + + + + String describing the type of element, as an unordered list +separated with slashes ('/'). See draft-klass.txt of the design docs +for more details and common types. E.g: "Sink/File" + + + + The long English name of the element. E.g. "File Sink" + + + + Builds a string using errno describing the previously failed system +call. To be used as the debug argument in #GST_ELEMENT_ERROR. + + + + + + + The same thing as #GST_EVENT_TYPE_UPSTREAM | #GST_EVENT_TYPE_DOWNSTREAM. + + + + GstElement is the abstract base class needed to construct an element that +can be used in a GStreamer pipeline. Please refer to the plugin writers +guide for more information on creating #GstElement subclasses. + +The name of a #GstElement can be get with gst_element_get_name() and set with +gst_element_set_name(). For speed, GST_ELEMENT_NAME() can be used in the +core when using the appropriate locking. Do not use this in plug-ins or +applications in order to retain ABI compatibility. + +Elements can have pads (of the type #GstPad). These pads link to pads on +other elements. #GstBuffer flow between these linked pads. +A #GstElement has a #GList of #GstPad structures for all their input (or sink) +and output (or source) pads. +Core and plug-in writers can add and remove pads with gst_element_add_pad() +and gst_element_remove_pad(). + +An existing pad of an element can be retrieved by name with +gst_element_get_static_pad(). A new dynamic pad can be created using +gst_element_request_pad() with a #GstPadTemplate. +An iterator of all pads can be retrieved with gst_element_iterate_pads(). + +Elements can be linked through their pads. +If the link is straightforward, use the gst_element_link() +convenience function to link two elements, or gst_element_link_many() +for more elements in a row. +Use gst_element_link_filtered() to link two elements constrained by +a specified set of #GstCaps. +For finer control, use gst_element_link_pads() and +gst_element_link_pads_filtered() to specify the pads to link on +each element by name. + +Each element has a state (see #GstState). You can get and set the state +of an element with gst_element_get_state() and gst_element_set_state(). +Setting a state triggers a #GstStateChange. To get a string representation +of a #GstState, use gst_element_state_get_name(). + +You can get and set a #GstClock on an element using gst_element_get_clock() +and gst_element_set_clock(). +Some elements can provide a clock for the pipeline if +the #GST_ELEMENT_FLAG_PROVIDE_CLOCK flag is set. With the +gst_element_provide_clock() method one can retrieve the clock provided by +such an element. +Not all elements require a clock to operate correctly. If the +#GST_ELEMENT_FLAG_REQUIRE_CLOCK() flag is set, a clock should be set on the +element with gst_element_set_clock(). + +Note that clock selection and distribution is normally handled by the +toplevel #GstPipeline so the clock functions are only to be used in very +specific situations. + + Creates an element for handling the given URI. + + a new element or %NULL if none could be created + + + + + Whether to create a source or a sink + + + + URI to create an element for + + + + Name of created element, can be %NULL. + + + + + + Create a new elementfactory capable of instantiating objects of the +@type and add the factory to @plugin. + + %TRUE, if the registering succeeded, %FALSE on error + + + + + #GstPlugin to register the element with, or %NULL for + a static element. + + + + name of elements of this type + + + + rank of element (higher rank means more importance when autoplugging) + + + + GType of element to register + + + + + + Gets a string representing the given state change result. + + a string with the name of the state + result. + + + + + a #GstStateChangeReturn to get the name of. + + + + + + Gets a string representing the given state. + + a string with the name of the state. + + + + + a #GstState to get the name of. + + + + + + Perform @transition on @element. + +This function must be called with STATE_LOCK held and is mainly used +internally. + + the #GstStateChangeReturn of the state transition. + + + + + a #GstElement + + + + the requested transition + + + + + + Gets the state of the element. + +For elements that performed an ASYNC state change, as reported by +gst_element_set_state(), this function will block up to the +specified timeout value for the state change to complete. +If the element completes the state change or goes into +an error, this function returns immediately with a return value of +%GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively. + +For elements that did not return %GST_STATE_CHANGE_ASYNC, this function +returns the current and pending state immediately. + +This function returns %GST_STATE_CHANGE_NO_PREROLL if the element +successfully changed its state but is not able to provide data yet. +This mostly happens for live sources that only produce data in +%GST_STATE_PLAYING. While the state change return is equivalent to +%GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that +some sink elements might not be able to complete their state change because +an element is not producing data to complete the preroll. When setting the +element to playing, the preroll will complete and playback will start. + + %GST_STATE_CHANGE_SUCCESS if the element has no more pending state + and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the + element is still performing a state change or + %GST_STATE_CHANGE_FAILURE if the last state change failed. + +MT safe. + + + + + a #GstElement to get the state of. + + + + a pointer to #GstState to hold the state. + Can be %NULL. + + + + a pointer to #GstState to hold the pending + state. Can be %NULL. + + + + a #GstClockTime to specify the timeout for an async + state change or %GST_CLOCK_TIME_NONE for infinite timeout. + + + + + + Use this function to signal that the element does not expect any more pads +to show up in the current pipeline. This function should be called whenever +pads have been added by the element itself. Elements with #GST_PAD_SOMETIMES +pad templates use this in combination with autopluggers to figure out that +the element is done initializing its pads. + +This function emits the #GstElement::no-more-pads signal. + +MT safe. + + + + + + a #GstElement + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 +additional reference before calling. + + %TRUE if the message was successfully posted. The function returns +%FALSE if the element did not have a bus. + +MT safe. + + + + + a #GstElement posting the message + + + + a #GstMessage to post + + + + + + Get the clock provided by the given element. +> An element is only required to provide a clock in the PAUSED +> state. Some elements can provide a clock in other states. + + the GstClock provided by the +element or %NULL if no clock could be provided. Unref after usage. + +MT safe. + + + + + a #GstElement to query + + + + + + Performs a query on the given element. + +For elements that don't implement a query handler, this function +forwards the query to a random srcpad or to the peer of a +random linked sinkpad of this element. + +Please note that some queries might need a running pipeline to work. + + %TRUE if the query could be performed. + +MT safe. + + + + + a #GstElement to perform the query on. + + + + the #GstQuery. + + + + + + + + + + + + + + + + + + + Retrieves a request pad from the element according to the provided template. +Pad templates can be looked up using +gst_element_factory_get_static_pad_templates(). + +The pad should be released with gst_element_release_request_pad(). + + requested #GstPad if found, + otherwise %NULL. Release after usage. + + + + + a #GstElement to find a request pad of. + + + + a #GstPadTemplate of which we want a pad of. + + + + the name of the request #GstPad +to retrieve. Can be %NULL. + + + + the caps of the pad we want to +request. Can be %NULL. + + + + + + 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 +downstream events or a random linked source pad for upstream events. + +This function takes ownership of the provided event so you should +gst_event_ref() it if you want to reuse the event after this call. + +MT safe. + + %TRUE if the event was handled. Events that trigger a preroll (such +as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. + + + + + a #GstElement to send the event to. + + + + the #GstEvent to send to the element. + + + + + + Sets the bus of the element. Increases the refcount on the bus. +For internal use only, unless you're testing elements. + +MT safe. + + + + + + a #GstElement to set the bus of. + + + + the #GstBus to set. + + + + + + Sets the clock for the element. This function increases the +refcount on the clock. Any previously set clock on the object +is unreffed. + + %TRUE if the element accepted the clock. An element can refuse a +clock when it, for example, is not able to slave its internal clock to the +@clock or when it requires a specific clock to operate. + +MT safe. + + + + + a #GstElement to set the clock for. + + + + the #GstClock to set for the element. + + + + + + Sets the context of the element. Increases the refcount of the context. + +MT safe. + + + + + + a #GstElement to set the context of. + + + + the #GstContext to set. + + + + + + Sets the state of the element. This function will try to set the +requested state by going through all the intermediary states and calling +the class's state change function for each. + +This function can return #GST_STATE_CHANGE_ASYNC, in which case the +element will perform the remainder of the state change asynchronously in +another thread. +An application can use gst_element_get_state() to wait for the completion +of the state change or it can wait for a %GST_MESSAGE_ASYNC_DONE or +%GST_MESSAGE_STATE_CHANGED on the bus. + +State changes to %GST_STATE_READY or %GST_STATE_NULL never return +#GST_STATE_CHANGE_ASYNC. + + Result of the state change using #GstStateChangeReturn. + +MT safe. + + + + + a #GstElement to change state of. + + + + the element's new #GstState. + + + + + + + + + + + + + + + + + + + + + + + + + Abort the state change of the element. This function is used +by elements that do asynchronous state changes and find out +something is wrong. + +This function should be called with the STATE_LOCK held. + +MT safe. + + + + + + a #GstElement to abort the state of. + + + + + + Adds a pad (link point) to @element. @pad's parent will be set to @element; +see gst_object_set_parent() for refcounting information. + +Pads are not automatically activated so elements should perform the needed +steps to activate the pad in case this pad is added in the PAUSED or PLAYING +state. See gst_pad_set_active() for more information about activating pads. + +The pad and the element should be unlocked when calling this function. + +This function will emit the #GstElement::pad-added signal on the element. + + %TRUE if the pad could be added. This function can fail when +a pad with the same name already existed or the pad already had another +parent. + +MT safe. + + + + + a #GstElement to add the pad to. + + + + the #GstPad to add to the element. + + + + + + + a watch id, which can be used in connection with + gst_element_remove_property_notify_watch() to remove the watch again. + + + + + a #GstElement to watch (recursively) for property changes + + + + name of property to watch for changes, or + NULL to watch all properties + + + + whether to include the new property value in the message + + + + + + + a watch id, which can be used in connection with + gst_element_remove_property_notify_watch() to remove the watch again. + + + + + a #GstElement to watch for property changes + + + + name of property to watch for changes, or + NULL to watch all properties + + + + whether to include the new property value in the message + + + + + + Calls @func from another thread and passes @user_data to it. This is to be +used for cases when a state change has to be performed from a streaming +thread, directly via gst_element_set_state() or indirectly e.g. via SEEK +events. + +Calling those functions directly from the streaming thread will cause +deadlocks in many situations, as they might involve waiting for the +streaming thread to shut down from this very streaming thread. + +MT safe. + + + + + + a #GstElement + + + + Function to call asynchronously from another thread + + + + Data to pass to @func + + + + GDestroyNotify for @user_data + + + + + + Perform @transition on @element. + +This function must be called with STATE_LOCK held and is mainly used +internally. + + the #GstStateChangeReturn of the state transition. + + + + + a #GstElement + + + + the requested transition + + + + + + Commit the state change of the element and proceed to the next +pending state if any. This function is used +by elements that do asynchronous state changes. +The core will normally call this method automatically when an +element returned %GST_STATE_CHANGE_SUCCESS from the state change function. + +If after calling this method the element still has not reached +the pending state, the next state change is performed. + +This method is used internally and should normally not be called by plugins +or applications. + + The result of the commit state change. + +MT safe. + + + + + a #GstElement to continue the state change of. + + + + The previous state return value + + + + + + Creates a pad for each pad template that is always available. +This function is only useful during object initialization of +subclasses of #GstElement. + + + + + + a #GstElement to create pads for + + + + + + Returns the base time of the element. The base time is the +absolute time of the clock when this element was last put to +PLAYING. Subtracting the base time from the clock time gives +the running time of the element. + + the base time of the element. + +MT safe. + + + + + a #GstElement. + + + + + + Returns the bus of the element. Note that only a #GstPipeline will provide a +bus for the application. + + the element's #GstBus. unref after usage. + +MT safe. + + + + + a #GstElement to get the bus of. + + + + + + Gets the currently configured clock of the element. This is the clock as was +last set with gst_element_set_clock(). + +Elements in a pipeline will only have their clock set when the +pipeline is in the PLAYING state. + + the #GstClock of the element. unref after usage. + +MT safe. + + + + + a #GstElement to get the clock of. + + + + + + Looks for an unlinked pad to which the given pad can link. It is not +guaranteed that linking the pads will work, though it should work in most +cases. + +This function will first attempt to find a compatible unlinked ALWAYS pad, +and if none can be found, it will request a compatible REQUEST pad by looking +at the templates of @element. + + the #GstPad to which a link + can be made, or %NULL if one cannot be found. gst_object_unref() + after usage. + + + + + a #GstElement in which the pad should be found. + + + + the #GstPad to find a compatible one for. + + + + the #GstCaps to use as a filter. + + + + + + Retrieves a pad template from @element that is compatible with @compattempl. +Pads from compatible templates can be linked together. + + a compatible #GstPadTemplate, + or %NULL if none was found. No unreferencing is necessary. + + + + + a #GstElement to get a compatible pad template for + + + + the #GstPadTemplate to find a compatible + template for + + + + + + Gets the context with @context_type set on the element or NULL. + +MT safe. + + A #GstContext or NULL + + + + + a #GstElement to get the context of. + + + + a name of a context to retrieve + + + + + + Gets the context with @context_type set on the element or NULL. + + A #GstContext or NULL + + + + + a #GstElement to get the context of. + + + + a name of a context to retrieve + + + + + + Gets the contexts set on the element. + +MT safe. + + List of #GstContext + + + + + + + a #GstElement to set the context of. + + + + + + Retrieves the factory that was used to create this element. + + the #GstElementFactory used for creating this + element. no refcounting is needed. + + + + + a #GstElement to request the element factory of. + + + + + + Retrieves a pad from the element by name (e.g. "src_\%d"). This version only +retrieves request pads. The pad should be released with +gst_element_release_request_pad(). + +This method is slower than manually getting the pad template and calling +gst_element_request_pad() if the pads should have a specific name (e.g. +@name is "src_1" instead of "src_\%u"). + + requested #GstPad if found, + otherwise %NULL. Release after usage. + + + + + a #GstElement to find a request pad of. + + + + the name of the request #GstPad to retrieve. + + + + + + Returns the start time of the element. The start time is the +running time of the clock when this element was last put to PAUSED. + +Usually the start_time is managed by a toplevel element such as +#GstPipeline. + +MT safe. + + the start time of the element. + + + + + a #GstElement. + + + + + + Gets the state of the element. + +For elements that performed an ASYNC state change, as reported by +gst_element_set_state(), this function will block up to the +specified timeout value for the state change to complete. +If the element completes the state change or goes into +an error, this function returns immediately with a return value of +%GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively. + +For elements that did not return %GST_STATE_CHANGE_ASYNC, this function +returns the current and pending state immediately. + +This function returns %GST_STATE_CHANGE_NO_PREROLL if the element +successfully changed its state but is not able to provide data yet. +This mostly happens for live sources that only produce data in +%GST_STATE_PLAYING. While the state change return is equivalent to +%GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that +some sink elements might not be able to complete their state change because +an element is not producing data to complete the preroll. When setting the +element to playing, the preroll will complete and playback will start. + + %GST_STATE_CHANGE_SUCCESS if the element has no more pending state + and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the + element is still performing a state change or + %GST_STATE_CHANGE_FAILURE if the last state change failed. + +MT safe. + + + + + a #GstElement to get the state of. + + + + a pointer to #GstState to hold the state. + Can be %NULL. + + + + a pointer to #GstState to hold the pending + state. Can be %NULL. + + + + a #GstClockTime to specify the timeout for an async + state change or %GST_CLOCK_TIME_NONE for infinite timeout. + + + + + + Retrieves a pad from @element by name. This version only retrieves +already-existing (i.e. 'static') pads. + + the requested #GstPad if + found, otherwise %NULL. unref after usage. + +MT safe. + + + + + a #GstElement to find a static pad of. + + + + the name of the static #GstPad to retrieve. + + + + + + Checks if the state of an element is locked. +If the state of an element is locked, state changes of the parent don't +affect the element. +This way you can leave currently unused elements inside bins. Just lock their +state before changing the state from #GST_STATE_NULL. + +MT safe. + + %TRUE, if the element's state is locked. + + + + + a #GstElement. + + + + + + Retrieves an iterator of @element's pads. The iterator should +be freed after usage. Also more specialized iterators exists such as +gst_element_iterate_src_pads() or gst_element_iterate_sink_pads(). + +The order of pads returned by the iterator will be the order in which +the pads were added to the element. + + the #GstIterator of #GstPad. + +MT safe. + + + + + a #GstElement to iterate pads of. + + + + + + Retrieves an iterator of @element's sink pads. + +The order of pads returned by the iterator will be the order in which +the pads were added to the element. + + the #GstIterator of #GstPad. + +MT safe. + + + + + a #GstElement. + + + + + + Retrieves an iterator of @element's source pads. + +The order of pads returned by the iterator will be the order in which +the pads were added to the element. + + the #GstIterator of #GstPad. + +MT safe. + + + + + a #GstElement. + + + + + + Links @src to @dest. The link must be from source to +destination; the other direction will not be tried. The function looks for +existing pads that aren't linked yet. It will request new pads if necessary. +Such pads need to be released manually when unlinking. +If multiple links are possible, only one is established. + +Make sure you have added your elements to a bin or pipeline with +gst_bin_add() before trying to link them. + + %TRUE if the elements could be linked, %FALSE otherwise. + + + + + a #GstElement containing the source pad. + + + + the #GstElement containing the destination pad. + + + + + + Links @src to @dest using the given caps as filtercaps. +The link must be from source to +destination; the other direction will not be tried. The function looks for +existing pads that aren't linked yet. It will request new pads if necessary. +If multiple links are possible, only one is established. + +Make sure you have added your elements to a bin or pipeline with +gst_bin_add() before trying to link them. + + %TRUE if the pads could be linked, %FALSE otherwise. + + + + + a #GstElement containing the source pad. + + + + the #GstElement containing the destination pad. + + + + the #GstCaps to filter the link, + or %NULL for no filter. + + + + + + Chain together a series of elements. Uses gst_element_link(). +Make sure you have added your elements to a bin or pipeline with +gst_bin_add() before trying to link them. + + %TRUE on success, %FALSE otherwise. + + + + + the first #GstElement in the link chain. + + + + the second #GstElement in the link chain. + + + + the %NULL-terminated list of elements to link in order. + + + + + + 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 the other element. If they have different +parents, the link fails. + + %TRUE if the pads could be linked, %FALSE otherwise. + + + + + a #GstElement containing the source pad. + + + + the name of the #GstPad in source element + or %NULL for any pad. + + + + the #GstElement containing the destination pad. + + + + the name of the #GstPad in destination element, +or %NULL for any pad. + + + + + + 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 +the other element. If they have different parents, the link fails. If @caps +is not %NULL, makes sure that the caps of the link is a subset of @caps. + + %TRUE if the pads could be linked, %FALSE otherwise. + + + + + a #GstElement containing the source pad. + + + + the name of the #GstPad in source element + or %NULL for any pad. + + + + the #GstElement containing the destination pad. + + + + the name of the #GstPad in destination element + or %NULL for any pad. + + + + the #GstCaps to filter the link, + or %NULL for no filter. + + + + + + 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 the other element. If they have different +parents, the link fails. + +Calling gst_element_link_pads_full() with @flags == %GST_PAD_LINK_CHECK_DEFAULT +is the same as calling gst_element_link_pads() and the recommended way of +linking pads with safety checks applied. + +This is a convenience function for gst_pad_link_full(). + + %TRUE if the pads could be linked, %FALSE otherwise. + + + + + a #GstElement containing the source pad. + + + + the name of the #GstPad in source element + or %NULL for any pad. + + + + the #GstElement containing the destination pad. + + + + the name of the #GstPad in destination element, +or %NULL for any pad. + + + + the #GstPadLinkCheck to be performed when linking pads. + + + + + + Brings the element to the lost state. The current state of the +element is copied to the pending state so that any call to +gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC. + +An ASYNC_START message is posted. If the element was PLAYING, it will +go to PAUSED. The element will be restored to its PLAYING state by +the parent pipeline when it prerolls again. + +This is mostly used for elements that lost their preroll buffer +in the %GST_STATE_PAUSED or %GST_STATE_PLAYING state after a flush, +they will go to their pending state again when a new preroll buffer is +queued. This function can only be called when the element is currently +not in error or an async state change. + +This function is used internally and should normally not be called from +plugins or applications. + + + + + + a #GstElement the state is lost of + + + + + + Post an error, warning or info message on the bus from inside an element. + +@type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or +#GST_MESSAGE_INFO. + +MT safe. + + + + + + a #GstElement to send message from + + + + the #GstMessageType + + + + the GStreamer GError domain this message belongs to + + + + the GError code belonging to the domain + + + + an allocated text string to be used + as a replacement for the default message connected to code, + or %NULL + + + + an allocated debug message to be + used as a replacement for the default debugging information, + or %NULL + + + + the source code file where the error was generated + + + + the source code function where the error was generated + + + + the source code line where the error was generated + + + + + + Post an error, warning or info message on the bus from inside an element. + +@type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or +#GST_MESSAGE_INFO. + + + + + + a #GstElement to send message from + + + + the #GstMessageType + + + + the GStreamer GError domain this message belongs to + + + + the GError code belonging to the domain + + + + an allocated text string to be used + as a replacement for the default message connected to code, + or %NULL + + + + an allocated debug message to be + used as a replacement for the default debugging information, + or %NULL + + + + the source code file where the error was generated + + + + the source code function where the error was generated + + + + the source code line where the error was generated + + + + optional details structure + + + + + + Use this function to signal that the element does not expect any more pads +to show up in the current pipeline. This function should be called whenever +pads have been added by the element itself. Elements with #GST_PAD_SOMETIMES +pad templates use this in combination with autopluggers to figure out that +the element is done initializing its pads. + +This function emits the #GstElement::no-more-pads signal. + +MT safe. + + + + + + a #GstElement + + + + + + 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 +additional reference before calling. + + %TRUE if the message was successfully posted. The function returns +%FALSE if the element did not have a bus. + +MT safe. + + + + + a #GstElement posting the message + + + + a #GstMessage to post + + + + + + Get the clock provided by the given element. +> An element is only required to provide a clock in the PAUSED +> state. Some elements can provide a clock in other states. + + the GstClock provided by the +element or %NULL if no clock could be provided. Unref after usage. + +MT safe. + + + + + a #GstElement to query + + + + + + Performs a query on the given element. + +For elements that don't implement a query handler, this function +forwards the query to a random srcpad or to the peer of a +random linked sinkpad of this element. + +Please note that some queries might need a running pipeline to work. + + %TRUE if the query could be performed. + +MT safe. + + + + + a #GstElement to perform the query on. + + + + the #GstQuery. + + + + + + Queries an element to convert @src_val in @src_format to @dest_format. + + %TRUE if the query could be performed. + + + + + a #GstElement to invoke the convert query on. + + + + a #GstFormat to convert from. + + + + a value to convert. + + + + the #GstFormat to convert to. + + + + a pointer to the result. + + + + + + Queries an element (usually top-level pipeline or playbin element) for the +total stream duration in nanoseconds. This query will only work once the +pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application +will receive an ASYNC_DONE message on the pipeline bus when that is the case. + +If the duration changes for some reason, you will get a DURATION_CHANGED +message on the pipeline bus, in which case you should re-query the duration +using this function. + + %TRUE if the query could be performed. + + + + + a #GstElement to invoke the duration query on. + + + + the #GstFormat requested + + + + A location in which to store the total duration, or %NULL. + + + + + + Queries an element (usually top-level pipeline or playbin element) for the +stream position in nanoseconds. This will be a value between 0 and the +stream duration (if the stream duration is known). This query will usually +only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING +state). The application will receive an ASYNC_DONE message on the pipeline +bus when that is the case. + +If one repeatedly calls this function one can also create a query and reuse +it in gst_element_query(). + + %TRUE if the query could be performed. + + + + + a #GstElement to invoke the position query on. + + + + the #GstFormat requested + + + + a location in which to store the current + position, or %NULL. + + + + + + Makes the element free the previously requested pad as obtained +with gst_element_request_pad(). + +This does not unref the pad. If the pad was created by using +gst_element_request_pad(), gst_element_release_request_pad() needs to be +followed by gst_object_unref() to free the @pad. + +MT safe. + + + + + + a #GstElement to release the request pad of. + + + + the #GstPad to release. + + + + + + Removes @pad from @element. @pad will be destroyed if it has not been +referenced elsewhere using gst_object_unparent(). + +This function is used by plugin developers and should not be used +by applications. Pads that were dynamically requested from elements +with gst_element_request_pad() should be released with the +gst_element_release_request_pad() function instead. + +Pads are not automatically deactivated so elements should perform the needed +steps to deactivate the pad in case this pad is removed in the PAUSED or +PLAYING state. See gst_pad_set_active() for more information about +deactivating pads. + +The pad and the element should be unlocked when calling this function. + +This function will emit the #GstElement::pad-removed signal on the element. + + %TRUE if the pad could be removed. Can return %FALSE if the +pad does not belong to the provided element. + +MT safe. + + + + + a #GstElement to remove pad from. + + + + the #GstPad to remove from the element. + + + + + + + + + + + a #GstElement being watched for property changes + + + + watch id to remove + + + + + + Retrieves a request pad from the element according to the provided template. +Pad templates can be looked up using +gst_element_factory_get_static_pad_templates(). + +The pad should be released with gst_element_release_request_pad(). + + requested #GstPad if found, + otherwise %NULL. Release after usage. + + + + + a #GstElement to find a request pad of. + + + + a #GstPadTemplate of which we want a pad of. + + + + the name of the request #GstPad +to retrieve. Can be %NULL. + + + + the caps of the pad we want to +request. Can be %NULL. + + + + + + Sends a seek event to an element. See gst_event_new_seek() for the details of +the parameters. The seek event is sent to the element using +gst_element_send_event(). + +MT safe. + + %TRUE if the event was handled. Flushing seeks will trigger a +preroll, which will emit %GST_MESSAGE_ASYNC_DONE. + + + + + a #GstElement to send the event to. + + + + The new playback rate + + + + The format of the seek values + + + + The optional seek flags. + + + + The type and flags for the new start position + + + + The value of the new start position + + + + The type and flags for the new stop position + + + + The value of the new stop position + + + + + + Simple API to perform a seek on the given element, meaning it just seeks +to the given position relative to the start of the stream. For more complex +operations like segment seeks (e.g. for looping) or changing the playback +rate or seeking relative to the last configured playback segment you should +use gst_element_seek(). + +In a completely prerolled PAUSED or PLAYING pipeline, seeking is always +guaranteed to return %TRUE on a seekable media type or %FALSE when the media +type is certainly not seekable (such as a live stream). + +Some elements allow for seeking in the READY state, in this +case they will store the seek event and execute it when they are put to +PAUSED. If the element supports seek in READY, it will always return %TRUE when +it receives the event in the READY state. + + %TRUE if the seek operation succeeded. Flushing seeks will trigger a +preroll, which will emit %GST_MESSAGE_ASYNC_DONE. + + + + + a #GstElement to seek on + + + + a #GstFormat to execute the seek in, such as #GST_FORMAT_TIME + + + + seek options; playback applications will usually want to use + GST_SEEK_FLAG_FLUSH | GST_SEEK_FLAG_KEY_UNIT here + + + + position to seek to (relative to the start); if you are doing + a seek in #GST_FORMAT_TIME this value is in nanoseconds - + multiply with #GST_SECOND to convert seconds to nanoseconds or + with #GST_MSECOND to convert milliseconds to nanoseconds. + + + + + + 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 +downstream events or a random linked source pad for upstream events. + +This function takes ownership of the provided event so you should +gst_event_ref() it if you want to reuse the event after this call. + +MT safe. + + %TRUE if the event was handled. Events that trigger a preroll (such +as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. + + + + + a #GstElement to send the event to. + + + + the #GstEvent to send to the element. + + + + + + Set the base time of an element. See gst_element_get_base_time(). + +MT safe. + + + + + + a #GstElement. + + + + the base time to set. + + + + + + Sets the bus of the element. Increases the refcount on the bus. +For internal use only, unless you're testing elements. + +MT safe. + + + + + + a #GstElement to set the bus of. + + + + the #GstBus to set. + + + + + + Sets the clock for the element. This function increases the +refcount on the clock. Any previously set clock on the object +is unreffed. + + %TRUE if the element accepted the clock. An element can refuse a +clock when it, for example, is not able to slave its internal clock to the +@clock or when it requires a specific clock to operate. + +MT safe. + + + + + a #GstElement to set the clock for. + + + + the #GstClock to set for the element. + + + + + + Sets the context of the element. Increases the refcount of the context. + +MT safe. + + + + + + a #GstElement to set the context of. + + + + the #GstContext to set. + + + + + + Locks the state of an element, so state changes of the parent don't affect +this element anymore. + +MT safe. + + %TRUE if the state was changed, %FALSE if bad parameters were given +or the elements state-locking needed no change. + + + + + a #GstElement + + + + %TRUE to lock the element's state + + + + + + Set the start time of an element. The start time of the element is the +running time of the element when it last went to the PAUSED state. In READY +or after a flushing seek, it is set to 0. + +Toplevel elements like #GstPipeline will manage the start_time and +base_time on its children. Setting the start_time to #GST_CLOCK_TIME_NONE +on such a toplevel element will disable the distribution of the base_time to +the children and can be useful if the application manages the base_time +itself, for example if you want to synchronize capture from multiple +pipelines, and you can also ensure that the pipelines have the same clock. + +MT safe. + + + + + + a #GstElement. + + + + the base time to set. + + + + + + Sets the state of the element. This function will try to set the +requested state by going through all the intermediary states and calling +the class's state change function for each. + +This function can return #GST_STATE_CHANGE_ASYNC, in which case the +element will perform the remainder of the state change asynchronously in +another thread. +An application can use gst_element_get_state() to wait for the completion +of the state change or it can wait for a %GST_MESSAGE_ASYNC_DONE or +%GST_MESSAGE_STATE_CHANGED on the bus. + +State changes to %GST_STATE_READY or %GST_STATE_NULL never return +#GST_STATE_CHANGE_ASYNC. + + Result of the state change using #GstStateChangeReturn. + +MT safe. + + + + + a #GstElement to change state of. + + + + the element's new #GstState. + + + + + + Tries to change the state of the element to the same as its parent. +If this function returns %FALSE, the state of element is undefined. + + %TRUE, if the element's state could be synced to the parent's state. + +MT safe. + + + + + a #GstElement. + + + + + + Unlinks all source pads of the source element with all sink pads +of the sink element to which they are linked. + +If the link has been made using gst_element_link(), it could have created an +requestpad, which has to be released using gst_element_release_request_pad(). + + + + + + the source #GstElement to unlink. + + + + the sink #GstElement to unlink. + + + + + + Unlinks a series of elements. Uses gst_element_unlink(). + + + + + + the first #GstElement in the link chain. + + + + the second #GstElement in the link chain. + + + + the %NULL-terminated list of elements to unlink in order. + + + + + + Unlinks the two named pads of the source and destination elements. + +This is a convenience function for gst_pad_unlink(). + + + + + + a (transfer none): #GstElement containing the source pad. + + + + the name of the #GstPad in source element. + + + + a #GstElement containing the destination pad. + + + + the name of the #GstPad in destination element. + + + + + + + + + Used to serialize execution of gst_element_set_state() + + + + Used to signal completion of a state change + + + + Used to detect concurrent execution of +gst_element_set_state() and gst_element_get_state() + + + + the target state of an element as set by the application + + + + the current state of an element + + + + the next state of an element, can be #GST_STATE_VOID_PENDING if +the element is in the correct state. + + + + the final state the element should go to, can be +#GST_STATE_VOID_PENDING if the element is in the correct state + + + + the last return value of an element state change + + + + the bus of the element. This bus is provided to the element by the +parent element or the application. A #GstPipeline has a bus of its own. + + + + the clock of the element. This clock is usually provided to the +element by the toplevel #GstPipeline. + + + + the time of the clock right before the element is set to +PLAYING. Subtracting @base_time from the current clock time in the PLAYING +state will yield the running_time against the clock. + + + + the running_time of the last PAUSED state + + + + number of pads of the element, includes both source and sink pads. + + + + list of pads + + + + + + number of source pads of the element. + + + + list of source pads + + + + + + number of sink pads of the element. + + + + list of sink pads + + + + + + updated whenever the a pad is added or removed + + + + list of contexts + + + + + + + + + + + This signals that the element will not generate more dynamic pads. +Note that this signal will usually be emitted from the context of +the streaming thread. + + + + + + a new #GstPad has been added to the element. Note that this signal will +usually be emitted from the context of the streaming thread. Also keep in +mind that if you add new elements to the pipeline in the signal handler +you will need to set them to the desired target state with +gst_element_set_state() or gst_element_sync_state_with_parent(). + + + + + + the pad that has been added + + + + + + a #GstPad has been removed from the element + + + + + + the pad that has been removed + + + + + + + + + + + + + + + + + + + + GStreamer element class. Override the vmethods to implement the element +functionality. + + the parent class structure + + + + metadata for elements of this class + + + + the #GstElementFactory that creates these elements + + + + a #GList of #GstPadTemplate + + + + + + the number of padtemplates + + + + changed whenever the padtemplates change + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GstElement + + + + + + + + + requested #GstPad if found, + otherwise %NULL. Release after usage. + + + + + a #GstElement to find a request pad of. + + + + a #GstPadTemplate of which we want a pad of. + + + + the name of the request #GstPad +to retrieve. Can be %NULL. + + + + the caps of the pad we want to +request. Can be %NULL. + + + + + + + + + + + + + + + + + + + + + + + + %GST_STATE_CHANGE_SUCCESS if the element has no more pending state + and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the + element is still performing a state change or + %GST_STATE_CHANGE_FAILURE if the last state change failed. + +MT safe. + + + + + a #GstElement to get the state of. + + + + a pointer to #GstState to hold the state. + Can be %NULL. + + + + a pointer to #GstState to hold the pending + state. Can be %NULL. + + + + a #GstClockTime to specify the timeout for an async + state change or %GST_CLOCK_TIME_NONE for infinite timeout. + + + + + + + + + Result of the state change using #GstStateChangeReturn. + +MT safe. + + + + + a #GstElement to change state of. + + + + the element's new #GstState. + + + + + + + + + the #GstStateChangeReturn of the state transition. + + + + + a #GstElement + + + + the requested transition + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a #GstElement to set the bus of. + + + + the #GstBus to set. + + + + + + + + + the GstClock provided by the +element or %NULL if no clock could be provided. Unref after usage. + +MT safe. + + + + + a #GstElement to query + + + + + + + + + %TRUE if the element accepted the clock. An element can refuse a +clock when it, for example, is not able to slave its internal clock to the +@clock or when it requires a specific clock to operate. + +MT safe. + + + + + a #GstElement to set the clock for. + + + + the #GstClock to set for the element. + + + + + + + + + %TRUE if the event was handled. Events that trigger a preroll (such +as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE. + + + + + a #GstElement to send the event to. + + + + the #GstEvent to send to the element. + + + + + + + + + %TRUE if the query could be performed. + +MT safe. + + + + + a #GstElement to perform the query on. + + + + the #GstQuery. + + + + + + + + + %TRUE if the message was successfully posted. The function returns +%FALSE if the element did not have a bus. + +MT safe. + + + + + a #GstElement posting the message + + + + a #GstMessage to post + + + + + + + + + + + + + a #GstElement to set the context of. + + + + the #GstContext to set. + + + + + + + + + + + + Set @key with @value as metadata in @klass. + + + + + + class to set metadata for + + + + the key to set + + + + the value to set + + + + + + Adds a padtemplate to an element class. This is mainly used in the _class_init +functions of classes. If a pad template with the same name as an already +existing one is added the old one is replaced by the new one. + + + + + + the #GstElementClass to add the pad template to. + + + + a #GstPadTemplate to add to the element class. + + + + + + Set @key with @value as metadata in @klass. + +Same as gst_element_class_add_metadata(), but @value must be a static string +or an inlined string, as it will not be copied. (GStreamer plugins will +be made resident once loaded, so this function can be used even from +dynamically loaded plugins.) + + + + + + class to set metadata for + + + + the key to set + + + + the value to set + + + + + + Adds a pad template to an element class based on the static pad template +@templ. This is mainly used in the _class_init functions of element +implementations. If a pad template with the same name already exists, +the old one is replaced by the new one. + + + + + + the #GstElementClass to add the pad template to. + + + + #GstStaticPadTemplate to add as pad template to the element class. + + + + + + Get metadata with @key in @klass. + + the metadata for @key. + + + + + class to get metadata for + + + + the key to get + + + + + + Retrieves a padtemplate from @element_class with the given name. +> If you use this function in the #GInstanceInitFunc of an object class +> that has subclasses, make sure to pass the g_class parameter of the +> #GInstanceInitFunc here. + + the #GstPadTemplate with the + given name, or %NULL if none was found. No unreferencing is + necessary. + + + + + a #GstElementClass to get the pad template of. + + + + the name of the #GstPadTemplate to get. + + + + + + Retrieves a list of the pad templates associated with @element_class. The +list must not be modified by the calling code. +> If you use this function in the #GInstanceInitFunc of an object class +> that has subclasses, make sure to pass the g_class parameter of the +> #GInstanceInitFunc here. + + the #GList of + pad templates. + + + + + + + a #GstElementClass to get pad templates of. + + + + + + Sets the detailed information for a #GstElementClass. +> This function is for use in _class_init functions only. + + + + + + class to set metadata for + + + + The long English name of the element. E.g. "File Sink" + + + + String describing the type of element, as an unordered list +separated with slashes ('/'). See draft-klass.txt of the design docs +for more details and common types. E.g: "Sink/File" + + + + Sentence describing the purpose of the element. +E.g: "Write stream to a file" + + + + Name and contact details of the author(s). Use \n to separate +multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" + + + + + + Sets the detailed information for a #GstElementClass. + +> This function is for use in _class_init functions only. + +Same as gst_element_class_set_metadata(), but @longname, @classification, +@description, and @author must be static strings or inlined strings, as +they will not be copied. (GStreamer plugins will be made resident once +loaded, so this function can be used even from dynamically loaded plugins.) + + + + + + class to set metadata for + + + + The long English name of the element. E.g. "File Sink" + + + + String describing the type of element, as an unordered list +separated with slashes ('/'). See draft-klass.txt of the design docs +for more details and common types. E.g: "Sink/File" + + + + Sentence describing the purpose of the element. +E.g: "Write stream to a file" + + + + Name and contact details of the author(s). Use \n to separate +multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" + + + + + + + #GstElementFactory is used to create instances of elements. A +GstElementFactory can be added to a #GstPlugin as it is also a +#GstPluginFeature. + +Use the gst_element_factory_find() and gst_element_factory_create() +functions to create element instances or use gst_element_factory_make() as a +convenient shortcut. + +The following code example shows you how to create a GstFileSrc element. + +## Using an element factory +|[<!-- language="C" --> + #include &lt;gst/gst.h&gt; + + GstElement *src; + GstElementFactory *srcfactory; + + gst_init (&amp;argc, &amp;argv); + + srcfactory = gst_element_factory_find ("filesrc"); + g_return_if_fail (srcfactory != NULL); + src = gst_element_factory_create (srcfactory, "src"); + g_return_if_fail (src != NULL); + ... +]| + + Search for an element factory of the given name. Refs the returned +element factory; caller is responsible for unreffing. + + #GstElementFactory if found, +%NULL otherwise + + + + + name of factory to find + + + + + + Filter out all the elementfactories in @list that can handle @caps in +the given direction. + +If @subsetonly is %TRUE, then only the elements whose pads templates +are a complete superset of @caps will be returned. Else any element +whose pad templates caps can intersect with @caps will be returned. + + a #GList of + #GstElementFactory elements that match the given requisites. + Use #gst_plugin_feature_list_free after usage. + + + + + + + a #GList of + #GstElementFactory to filter + + + + + + a #GstCaps + + + + a #GstPadDirection to filter on + + + + whether to filter on caps subsets or not. + + + + + + Get a list of factories that match the given @type. Only elements +with a rank greater or equal to @minrank will be returned. +The list of factories is returned by decreasing rank. + + a #GList of + #GstElementFactory elements. Use gst_plugin_feature_list_free() after + usage. + + + + + + + a #GstElementFactoryListType + + + + Minimum rank + + + + + + Create a new element of the type defined by the given element factory. +If name is %NULL, then the element will receive a guaranteed unique name, +consisting of the element factory name and a number. +If name is given, it will be given the name supplied. + + new #GstElement or %NULL +if unable to create element + + + + + a named factory to instantiate + + + + name of new element, or %NULL to automatically create + a unique name + + + + + + Checks if the factory can sink all possible capabilities. + + %TRUE if the caps are fully compatible. + + + + + factory to query + + + + the caps to check + + + + + + Checks if the factory can sink any possible capability. + + %TRUE if the caps have a common subset. + + + + + factory to query + + + + the caps to check + + + + + + Checks if the factory can src all possible capabilities. + + %TRUE if the caps are fully compatible. + + + + + factory to query + + + + the caps to check + + + + + + Checks if the factory can src any possible capability. + + %TRUE if the caps have a common subset. + + + + + factory to query + + + + the caps to check + + + + + + Create a new element of the type defined by the given elementfactory. +It will be given the name supplied, since all elements require a name as +their first argument. + + new #GstElement or %NULL + if the element couldn't be created + + + + + factory to instantiate + + + + name of new element, or %NULL to automatically create + a unique name + + + + + + Get the #GType for elements managed by this factory. The type can +only be retrieved if the element factory is loaded, which can be +assured with gst_plugin_feature_load(). + + the #GType for elements managed by this factory or 0 if +the factory is not loaded. + + + + + factory to get managed #GType from + + + + + + Get the metadata on @factory with @key. + + the metadata with @key on @factory or %NULL +when there was no metadata with the given @key. + + + + + a #GstElementFactory + + + + a key + + + + + + Get the available keys for the metadata on @factory. + + +a %NULL-terminated array of key strings, or %NULL when there is no +metadata. Free with g_strfreev() when no longer needed. + + + + + + + a #GstElementFactory + + + + + + Gets the number of pad_templates in this factory. + + the number of pad_templates + + + + + a #GstElementFactory + + + + + + Gets the #GList of #GstStaticPadTemplate for this factory. + + the + static pad templates + + + + + + + a #GstElementFactory + + + + + + Gets a %NULL-terminated array of protocols this element supports or %NULL if +no protocols are supported. You may not change the contents of the returned +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. + + the supported protocols + or %NULL + + + + + + + a #GstElementFactory + + + + + + Gets the type of URIs the element supports or #GST_URI_UNKNOWN if none. + + type of URIs this element supports + + + + + a #GstElementFactory + + + + + + Check if @factory implements the interface with name @interfacename. + + %TRUE when @factory implement the interface. + + + + + a #GstElementFactory + + + + an interface name + + + + + + Check if @factory is of the given types. + + %TRUE if @factory is of @type. + + + + + a #GstElementFactory + + + + a #GstElementFactoryListType + + + + + + + + + The standard flags that an element may have. + + ignore state changes from parent + + + the element is a sink + + + the element is a source. + + + the element can provide a clock + + + the element requires a clock + + + the element can use an index + + + offset to define more flags + + + + The event class provides factory methods to construct events for sending +and functions to query (parse) received events. + +Events are usually created with gst_event_new_*() which takes event-type +specific parameters as arguments. +To send an event application will usually use gst_element_send_event() and +elements will use gst_pad_send_event() or gst_pad_push_event(). +The event should be unreffed with gst_event_unref() if it has not been sent. + +Events that have been received can be parsed with their respective +gst_event_parse_*() functions. It is valid to pass %NULL for unwanted details. + +Events are passed between elements in parallel to the data stream. Some events +are serialized with buffers, others are not. Some events only travel downstream, +others only upstream. Some events can travel both upstream and downstream. + +The events are used to signal special conditions in the datastream such as +EOS (end of stream) or the start of a new stream-segment. +Events are also used to flush the pipeline of any pending data. + +Most of the event API is used inside plugins. Applications usually only +construct and use seek events. +To do that gst_event_new_seek() is used to create a seek event. It takes +the needed parameters to specify seeking time and mode. +|[<!-- language="C" --> + GstEvent *event; + gboolean result; + ... + // construct a seek event to play the media from second 2 to 5, flush + // the pipeline to decrease latency. + event = gst_event_new_seek (1.0, + GST_FORMAT_TIME, + GST_SEEK_FLAG_FLUSH, + GST_SEEK_TYPE_SET, 2 * GST_SECOND, + GST_SEEK_TYPE_SET, 5 * GST_SECOND); + ... + result = gst_element_send_event (pipeline, event); + if (!result) + g_warning ("seek failed"); + ... +]| + + the parent structure + + + + the #GstEventType of the event + + + + the timestamp of the event + + + + the sequence number of the event + + + + Create a new buffersize event. The event is sent downstream and notifies +elements that they should provide a buffer of the specified dimensions. + +When the @async flag is set, a thread boundary is preferred. + + a new #GstEvent + + + + + buffer format + + + + minimum buffer size + + + + maximum buffer size + + + + thread behavior + + + + + + Create a new CAPS event for @caps. The caps event can only travel downstream +synchronized with the buffer flow and contains the format of the buffers +that will follow after the event. + + the new CAPS event. + + + + + a #GstCaps + + + + + + 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 +element. + +Make sure to allocate an event type with the #GST_EVENT_MAKE_TYPE macro, +assigning a free number and filling in the correct direction and +serialization flags. + +New custom events can also be created by subclassing the event type if +needed. + + the new custom event. + + + + + The type of the new event + + + + the structure for the event. The event will + take ownership of the structure. + + + + + + Create a new EOS event. The eos event can only travel downstream +synchronized with the buffer flow. Elements that receive the EOS +event on a pad can return #GST_FLOW_EOS as a #GstFlowReturn +when data after the EOS event arrives. + +The EOS event will travel down to the sink elements in the pipeline +which will then post the #GST_MESSAGE_EOS on the bus after they have +finished playing any buffered data. + +When all sinks have posted an EOS message, an EOS message is +forwarded to the application. + +The EOS event itself will not cause any state transitions of the pipeline. + + the new EOS event. + + + + + Allocate a new flush start event. The flush start event can be sent +upstream and downstream and travels out-of-bounds with the dataflow. + +It marks pads as being flushing and will make them return +#GST_FLOW_FLUSHING when used for data flow with gst_pad_push(), +gst_pad_chain(), gst_pad_get_range() and gst_pad_pull_range(). +Any event (except a #GST_EVENT_FLUSH_STOP) received +on a flushing pad will return %FALSE immediately. + +Elements should unlock any blocking functions and exit their streaming +functions as fast as possible when this event is received. + +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. + + a new flush start event. + + + + + Allocate a new flush stop event. The flush stop event can be sent +upstream and downstream and travels serialized with the dataflow. +It is typically sent after sending a FLUSH_START event to make the +pads accept data again. + +Elements can process this event synchronized with the dataflow since +the preceding FLUSH_START event stopped the dataflow. + +This event is typically generated to complete a seek and to resume +dataflow. + + a new flush stop event. + + + + + if time should be reset + + + + + + Create a new GAP event. A gap event can be thought of as conceptually +equivalent to a buffer to signal that there is no data for a certain +amount of time. This is useful to signal a gap to downstream elements +which may wait for data, such as muxers or mixers or overlays, especially +for sparse streams such as subtitle streams. + + the new GAP event. + + + + + the start time (pts) of the gap + + + + the duration of the gap + + + + + + Create a new latency event. The event is sent upstream from the sinks and +notifies elements that they should add an additional @latency to the +running time before synchronising against the clock. + +The latency is mostly used in live sinks and is always expressed in +the time format. + + a new #GstEvent + + + + + the new latency value + + + + + + Create a new navigation event from the given description. + + a new #GstEvent + + + + + description of the event. The event will take + ownership of the structure. + + + + + + Creates a new event containing information specific to a particular +protection system (uniquely identified by @system_id), by which that +protection system can acquire key(s) to decrypt a protected stream. + +In order for a decryption element to decrypt media +protected using a specific system, it first needs all the +protection system specific information necessary to acquire the decryption +key(s) for that stream. The functions defined here enable this information +to be passed in events from elements that extract it +(e.g., ISOBMFF demuxers, MPEG DASH demuxers) to protection decrypter +elements that use it. + +Events containing protection system specific information are created using +#gst_event_new_protection, and they can be parsed by downstream elements +using #gst_event_parse_protection. + +In Common Encryption, protection system specific information may be located +within ISOBMFF files, both in movie (moov) boxes and movie fragment (moof) +boxes; it may also be contained in ContentProtection elements within MPEG +DASH MPDs. The events created by #gst_event_new_protection contain data +identifying from which of these locations the encapsulated protection system +specific information originated. This origin information is required as +some protection systems use different encodings depending upon where the +information originates. + +The events returned by gst_event_new_protection() are implemented +in such a way as to ensure that the most recently-pushed protection info +event of a particular @origin and @system_id will +be stuck to the output pad of the sending element. + + a #GST_EVENT_PROTECTION event, if successful; %NULL +if unsuccessful. + + + + + a string holding a UUID that uniquely +identifies a protection system. + + + + a #GstBuffer holding protection system specific +information. The reference count of the buffer will be incremented by one. + + + + a string indicating where the protection +information carried in the event was extracted from. The allowed values +of this string will depend upon the protection scheme. + + + + + + Allocate a new qos event with the given values. +The QOS event is generated in an element that wants an upstream +element to either reduce or increase its rate because of +high/low CPU load or other resource usage such as network performance or +throttling. Typically sinks generate these events for each buffer +they receive. + +@type indicates the reason for the QoS event. #GST_QOS_TYPE_OVERFLOW is +used when a buffer arrived in time or when the sink cannot keep up with +the upstream datarate. #GST_QOS_TYPE_UNDERFLOW is when the sink is not +receiving buffers fast enough and thus has to drop late buffers. +#GST_QOS_TYPE_THROTTLE is used when the datarate is artificially limited +by the application, for example to reduce power consumption. + +@proportion indicates the real-time performance of the streaming in the +element that generated the QoS event (usually the sink). The value is +generally computed based on more long term statistics about the streams +timestamps compared to the clock. +A value < 1.0 indicates that the upstream element is producing data faster +than real-time. A value > 1.0 indicates that the upstream element is not +producing data fast enough. 1.0 is the ideal @proportion value. The +proportion value can safely be used to lower or increase the quality of +the element. + +@diff is the difference against the clock in running time of the last +buffer that caused the element to generate the QOS event. A negative value +means that the buffer with @timestamp arrived in time. A positive value +indicates how late the buffer with @timestamp was. When throttling is +enabled, @diff will be set to the requested throttling interval. + +@timestamp is the timestamp of the last buffer that cause the element +to generate the QOS event. It is expressed in running time and thus an ever +increasing value. + +The upstream element can use the @diff and @timestamp values to decide +whether to process more buffers. For positive @diff, all buffers with +timestamp <= @timestamp + @diff will certainly arrive late in the sink +as well. A (negative) @diff value so that @timestamp + @diff would yield a +result smaller than 0 is not allowed. + +The application can use general event probes to intercept the QoS +event and implement custom application specific QoS handling. + + a new QOS event. + + + + + the QoS type + + + + the proportion of the qos message + + + + The time difference of the last Clock sync + + + + The timestamp of the buffer + + + + + + Create a new reconfigure event. The purpose of the reconfigure event is +to travel upstream and make elements renegotiate their caps or reconfigure +their buffer pools. This is useful when changing properties on elements +or changing the topology of the pipeline. + + a new #GstEvent + + + + + Allocate a new seek event with the given parameters. + +The seek event configures playback of the pipeline between @start to @stop +at the speed given in @rate, also called a playback segment. +The @start and @stop values are expressed in @format. + +A @rate of 1.0 means normal playback rate, 2.0 means double speed. +Negatives values means backwards playback. A value of 0.0 for the +rate is not allowed and should be accomplished instead by PAUSING the +pipeline. + +A pipeline has a default playback segment configured with a start +position of 0, a stop position of -1 and a rate of 1.0. The currently +configured playback segment can be queried with #GST_QUERY_SEGMENT. + +@start_type and @stop_type specify how to adjust the currently configured +start and stop fields in playback segment. Adjustments can be made relative +or absolute to the last configured values. A type of #GST_SEEK_TYPE_NONE +means that the position should not be updated. + +When the rate is positive and @start has been updated, playback will start +from the newly configured start position. + +For negative rates, playback will start from the newly configured stop +position (if any). If the stop position is updated, it must be different from +-1 (#GST_CLOCK_TIME_NONE) for negative rates. + +It is not possible to seek relative to the current playback position, to do +this, PAUSE the pipeline, query the current playback position with +#GST_QUERY_POSITION and update the playback segment current position with a +#GST_SEEK_TYPE_SET to the desired position. + + a new seek event. + + + + + The new playback rate + + + + The format of the seek values + + + + The optional seek flags + + + + The type and flags for the new start position + + + + The value of the new start position + + + + The type and flags for the new stop position + + + + The value of the new stop position + + + + + + Create a new SEGMENT event for @segment. The segment event can only travel +downstream synchronized with the buffer flow and contains timing information +and playback properties for the buffers that will follow. + +The segment event marks the range of buffers to be processed. All +data not within the segment range is not to be processed. This can be +used intelligently by plugins to apply more efficient methods of skipping +unneeded data. The valid range is expressed with the @start and @stop +values. + +The time value of the segment is used in conjunction with the start +value to convert the buffer timestamps into the stream time. This is +usually done in sinks to report the current stream_time. +@time represents the stream_time of a buffer carrying a timestamp of +@start. @time cannot be -1. + +@start cannot be -1, @stop can be -1. If there +is a valid @stop given, it must be greater or equal the @start, including +when the indicated playback @rate is < 0. + +The @applied_rate value provides information about any rate adjustment that +has already been made to the timestamps and content on the buffers of the +stream. (@rate * @applied_rate) should always equal the rate that has been +requested for playback. For example, if an element has an input segment +with intended playback @rate of 2.0 and applied_rate of 1.0, it can adjust +incoming timestamps and buffer content by half and output a segment event +with @rate of 1.0 and @applied_rate of 2.0 + +After a segment event, the buffer stream time is calculated with: + + time + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate) + + the new SEGMENT event. + + + + + a #GstSegment + + + + + + Create a new segment-done event. This event is sent by elements that +finish playback of a segment as a result of a segment seek. + + a new #GstEvent + + + + + The format of the position being done + + + + The position of the segment being done + + + + + + Allocate a new select-streams event. + +The select-streams event requests the specified @streams to be activated. + +The list of @streams corresponds to the "Stream ID" of each stream to be +activated. Those ID can be obtained via the #GstStream objects present +in #GST_EVENT_STREAM_START, #GST_EVENT_STREAM_COLLECTION or +#GST_MESSSAGE_STREAM_COLLECTION. + + a new select-streams event. + + + + + the list of streams to +activate + + + + + + + + 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 +with the stream. + +@name is used to store multiple sticky events on one pad. + + a new #GstEvent + + + + + a name for the event + + + + the #GstMessage to be posted + + + + + + Create a new step event. The purpose of the step event is to instruct a sink +to skip @amount (expressed in @format) of media. It can be used to implement +stepping through the video frame by frame or for doing fast trick modes. + +A rate of <= 0.0 is not allowed. Pause the pipeline, for the effect of rate += 0.0 or first reverse the direction of playback using a seek event to get +the same effect as rate < 0.0. + +The @flush flag will clear any pending data in the pipeline before starting +the step operation. + +The @intermediate flag instructs the pipeline that this step operation is +part of a larger step operation. + + a new #GstEvent + + + + + the format of @amount + + + + the amount of data to step + + + + the step rate + + + + flushing steps + + + + intermediate steps + + + + + + Create a new STREAM_COLLECTION event. The stream collection event can only +travel downstream synchronized with the buffer flow. + +Source elements, demuxers and other elements that manage collections +of streams and post #GstStreamCollection messages on the bus also send +this event downstream on each pad involved in the collection, so that +activation of a new collection can be tracked through the downstream +data flow. + + the new STREAM_COLLECTION event. + + + + + Active collection for this data flow + + + + + + Create a new Stream Group Done event. The stream-group-done event can +only travel downstream synchronized with the buffer flow. Elements +that receive the event on a pad should handle it mostly like EOS, +and emit any data or pending buffers that would depend on more data +arriving and unblock, since there won't be any more data. + +This event is followed by EOS at some point in the future, and is +generally used when switching pads - to unblock downstream so that +new pads can be exposed before sending EOS on the existing pads. + + the new stream-group-done event. + + + + + the group id of the stream group which is ending + + + + + + Create a new STREAM_START event. The stream start event can only +travel downstream synchronized with the buffer flow. It is expected +to be the first event that is sent for a new stream. + +Source elements, demuxers and other elements that create new streams +are supposed to send this event as the first event of a new stream. It +should not be sent after a flushing seek or in similar situations +and is used to mark the beginning of a new logical stream. Elements +combining multiple streams must ensure that this event is only forwarded +downstream once and not for every single input stream. + +The @stream_id should be a unique string that consists of the upstream +stream-id, / as separator and a unique stream-id for this specific +stream. A new stream-id should only be created for a stream if the upstream +stream is split into (potentially) multiple new streams, e.g. in a demuxer, +but not for every single element in the pipeline. +gst_pad_create_stream_id() or gst_pad_create_stream_id_printf() can be +used to create a stream-id. There are no particular semantics for the +stream-id, though it should be deterministic (to support stream matching) +and it might be used to order streams (besides any information conveyed by +stream flags). + + the new STREAM_START event. + + + + + Identifier for this stream + + + + + + Generates a metadata tag event from the given @taglist. + +The scope of the taglist specifies if the taglist applies to the +complete medium or only to this specific stream. As the tag event +is a sticky event, elements should merge tags received from +upstream with a given scope with their own tags with the same +scope and create a new tag event from it. + + a new #GstEvent + + + + + metadata list. The event will take ownership + of the taglist. + + + + + + Generate a TOC event from the given @toc. The purpose of the TOC event is to +inform elements that some kind of the TOC was found. + + a new #GstEvent. + + + + + #GstToc structure. + + + + whether @toc was updated or not. + + + + + + Generate a TOC select event with the given @uid. The purpose of the +TOC select event is to start playback based on the TOC's entry with the +given @uid. + + a new #GstEvent. + + + + + UID in the TOC to start playback from. + + + + + + Parses a segment @event and copies the #GstSegment into the location +given by @segment. + + + + + + The event to parse + + + + a pointer to a #GstSegment + + + + + + Retrieve the accumulated running time offset of the event. + +Events passing through #GstPads that have a running time +offset set via gst_pad_set_offset() will get their offset +adjusted according to the pad's offset. + +If the event contains any information that related to the +running time, this information will need to be updated +before usage with this offset. + + The event's running time offset + +MT safe. + + + + + A #GstEvent. + + + + + + Retrieve the sequence number of a event. + +Events have ever-incrementing sequence numbers, which may also be set +explicitly via gst_event_set_seqnum(). Sequence numbers are typically used to +indicate that a event corresponds to some other set of events or messages, +for example an EOS event corresponding to a SEEK event. It is considered good +practice to make this correspondence when possible, though it is not +required. + +Note that events and messages share the same sequence number incrementor; +two events or messages will never have the same sequence number unless +that correspondence was made explicitly. + + The event's sequence number. + +MT safe. + + + + + A #GstEvent. + + + + + + Access the structure of the event. + + The structure of the event. The structure is still +owned by the event, which means that you should not free it and +that the pointer becomes invalid when you free the event. + +MT safe. + + + + + The #GstEvent. + + + + + + Checks if @event has the given @name. This function is usually used to +check the name of a custom event. + + %TRUE if @name matches the name of the event structure. + + + + + The #GstEvent. + + + + name to check + + + + + + Get the format, minsize, maxsize and async-flag in the buffersize event. + + + + + + The event to query + + + + A pointer to store the format in + + + + A pointer to store the minsize in + + + + A pointer to store the maxsize in + + + + A pointer to store the async-flag in + + + + + + Get the caps from @event. The caps remains valid as long as @event remains +valid. + + + + + + The event to parse + + + + A pointer to the caps + + + + + + Parse the FLUSH_STOP event and retrieve the @reset_time member. + + + + + + The event to parse + + + + if time should be reset + + + + + + Extract timestamp and duration from a new GAP event. + + + + + + a #GstEvent of type #GST_EVENT_GAP + + + + location where to store the + start time (pts) of the gap, or %NULL + + + + location where to store the duration of + the gap, or %NULL + + + + + + + %TRUE if a group id was set on the event and could be parsed, + %FALSE otherwise. + + + + + a stream-start event + + + + address of variable where to store the group id + + + + + + Get the latency in the latency event. + + + + + + The event to query + + + + A pointer to store the latency in. + + + + + + Parses an event containing protection system specific information and stores +the results in @system_id, @data and @origin. The data stored in @system_id, +@origin and @data are valid until @event is released. + + + + + + a #GST_EVENT_PROTECTION event. + + + + pointer to store the UUID +string uniquely identifying a content protection system. + + + + pointer to store a #GstBuffer +holding protection system specific information. + + + + pointer to store a value that +indicates where the protection information carried by @event was extracted +from. + + + + + + Get the type, proportion, diff and timestamp in the qos event. See +gst_event_new_qos() for more information about the different QoS values. + +@timestamp will be adjusted for any pad offsets of pads it was passing through. + + + + + + The event to query + + + + A pointer to store the QoS type in + + + + A pointer to store the proportion in + + + + A pointer to store the diff in + + + + A pointer to store the timestamp in + + + + + + Parses a seek @event and stores the results in the given result locations. + + + + + + a seek event + + + + result location for the rate + + + + result location for the stream format + + + + result location for the #GstSeekFlags + + + + result location for the #GstSeekType of the start position + + + + result location for the start position expressed in @format + + + + result location for the #GstSeekType of the stop position + + + + result location for the stop position expressed in @format + + + + + + Parses a segment @event and stores the result in the given @segment location. +@segment remains valid only until the @event is freed. Don't modify the segment +and make a copy if you want to modify it or store it for later use. + + + + + + The event to parse + + + + a pointer to a #GstSegment + + + + + + Extracts the position and format from the segment done message. + + + + + + A valid #GstEvent of type GST_EVENT_SEGMENT_DONE. + + + + Result location for the format, or %NULL + + + + Result location for the position, or %NULL + + + + + + Parse the SELECT_STREAMS event and retrieve the contained streams. + + + + + + The event to parse + + + + the streams + + + + + + + + Parse the sink-message event. Unref @msg after usage. + + + + + + The event to query + + + + a pointer to store the #GstMessage in. + + + + + + Parse the step event. + + + + + + The event to query + + + + a pointer to store the format in + + + + a pointer to store the amount in + + + + a pointer to store the rate in + + + + a pointer to store the flush boolean in + + + + a pointer to store the intermediate + boolean in + + + + + + Parse a stream-start @event and extract the #GstStream from it. + + + + + + a stream-start event + + + + adress of variable to store the stream + + + + + + Retrieve new #GstStreamCollection from STREAM_COLLECTION event @event. + + + + + + a stream-collection event + + + + pointer to store the collection + + + + + + + + + + + a stream-start event + + + + address of variable where to store the stream flags + + + + + + Parse a stream-group-done @event and store the result in the given +@group_id location. + + + + + + a stream-group-done event. + + + + address of variable to store the group id into + + + + + + Parse a stream-id @event and store the result in the given @stream_id +location. The string stored in @stream_id must not be modified and will +remain valid only until @event gets freed. Make a copy if you want to +modify it or store it for later use. + + + + + + a stream-start event. + + + + pointer to store the stream-id + + + + + + Parses a tag @event and stores the results in the given @taglist location. +No reference to the taglist will be returned, it remains valid only until +the @event is freed. Don't modify or free the taglist, make a copy if you +want to modify it or store it for later use. + + + + + + a tag event + + + + pointer to metadata list + + + + + + Parse a TOC @event and store the results in the given @toc and @updated locations. + + + + + + a TOC event. + + + + pointer to #GstToc structure. + + + + pointer to store TOC updated flag. + + + + + + Parse a TOC select @event and store the results in the given @uid location. + + + + + + a TOC select event. + + + + storage for the selection UID. + + + + + + All streams that have the same group id are supposed to be played +together, i.e. all streams inside a container file should have the +same group id but different stream ids. The group id should change +each time the stream is started, resulting in different group ids +each time a file is played for example. + +Use gst_util_group_id_next() to get a new group id. + + + + + + a stream-start event + + + + the group id to set + + + + + + Set the running time offset of a event. See +gst_event_get_running_time_offset() for more information. + +MT safe. + + + + + + A #GstEvent. + + + + A the new running time offset + + + + + + Set the sequence number of a event. + +This function might be called by the creator of a event to indicate that the +event relates to other events or messages. See gst_event_get_seqnum() for +more information. + +MT safe. + + + + + + A #GstEvent. + + + + A sequence number. + + + + + + Set the @stream on the stream-start @event + + + + + + a stream-start event + + + + the stream object to set + + + + + + + + + + + a stream-start event + + + + the stream flags to set + + + + + + Get a writable version of the structure. + + The structure of the event. The structure +is still owned by the event, which means that you should not free +it and that the pointer becomes invalid when you free the event. +This function checks if @event is writable and will never return +%NULL. + +MT safe. + + + + + The #GstEvent. + + + + + + + #GstEventType lists the standard event types that can be sent in a pipeline. + +The custom event types can be used for private messages between elements +that can't be expressed using normal +GStreamer buffer passing semantics. Custom events carry an arbitrary +#GstStructure. +Specific custom events are distinguished by the name of the structure. + + unknown event. + + + Start a flush operation. This event clears all data + from the pipeline and unblock all streaming threads. + + + Stop a flush operation. This event resets the + running-time of the pipeline. + + + Event to mark the start of a new stream. Sent before any + other serialized event and only sent at the start of a new stream, + not after flushing seeks. + + + #GstCaps event. Notify the pad of a new media type. + + + A new media segment follows in the dataflow. The + segment events contains information for clipping buffers and + converting buffer timestamps to running-time and + stream-time. + + + A new #GstStreamCollection is available (Since 1.10) + + + A new set of metadata tags has been found in the stream. + + + Notification of buffering requirements. Currently not + used yet. + + + An event that sinks turn into a message. Used to + send messages that should be emitted in sync with + rendering. + + + Indicates that there is no more data for + the stream group ID in the message. Sent before EOS + in some instances and should be handled mostly the same. (Since 1.10) + + + End-Of-Stream. No more data is to be expected to follow + without either a STREAM_START event, or a FLUSH_STOP and a SEGMENT + event. + + + An event which indicates that a new table of contents (TOC) + was found or updated. + + + An event which indicates that new or updated + encryption information has been found in the stream. + + + Marks the end of a segment playback. + + + Marks a gap in the datastream. + + + A quality message. Used to indicate to upstream elements + that the downstream elements should adjust their processing + rate. + + + A request for a new playback position and rate. + + + Navigation events are usually used for communicating + user requests, such as mouse or keyboard movements, + to upstream elements. + + + Notification of new latency adjustment. Sinks will use + the latency information to adjust their synchronisation. + + + A request for stepping through the media. Sinks will usually + execute the step operation. + + + A request for upstream renegotiating caps and reconfiguring. + + + A request for a new playback position based on TOC + entry's UID. + + + A request to select one or more streams (Since 1.10) + + + Upstream custom event + + + Downstream custom event that travels in the + data flow. + + + Custom out-of-band downstream event. + + + Custom sticky downstream event. + + + Custom upstream or downstream event. + In-band when travelling downstream. + + + Custom upstream or downstream out-of-band event. + + + Gets the #GstEventTypeFlags associated with @type. + + a #GstEventTypeFlags. + + + + + a #GstEventType + + + + + + Get a printable name for the given event type. Do not modify or free. + + a reference to the static name of the event. + + + + + the event type + + + + + + Get the unique quark for the given event type. + + the quark associated with the event type + + + + + the event type + + + + + + + #GstEventTypeFlags indicate the aspects of the different #GstEventType +values. You can get the type flags of a #GstEventType with the +gst_event_type_get_flags() function. + + Set if the event can travel upstream. + + + Set if the event can travel downstream. + + + Set if the event should be serialized with data + flow. + + + Set if the event is sticky on the pads. + + + Multiple sticky events can be on a pad, each + identified by the event name. + + + + A mask value with all bits set, for use as a +#GstFlagSet mask where all flag bits must match +exactly + + + + The PERCENT format is between 0 and this value + + + + The value used to scale down the reported PERCENT format value to +its real value. + + + + Can be used together with #GST_FOURCC_ARGS to properly output a +#guint32 fourcc value in a printf()-style text message. + +|[ +printf ("fourcc: %" GST_FOURCC_FORMAT "\n", GST_FOURCC_ARGS (fcc)); +]| + + + + + Create a new sub-class of #GST_TYPE_FLAG_SET +which will pretty-print the human-readable flags +when serializing, for easier debugging. + + + + + + a #GType of a #G_TYPE_FLAGS type. + + + + + + + The result of passing data to a pad. + +Note that the custom return values should not be exposed outside of the +element scope. + + Pre-defined custom success code. + + + Pre-defined custom success code (define your + custom success code to this to avoid compiler + warnings). + + + Elements can use values starting from + this (and higher) to define custom success + codes. + + + Data passing was ok. + + + Pad is not linked. + + + Pad is flushing. + + + Pad is EOS. + + + Pad is not negotiated. + + + Some (fatal) error occurred. Element generating + this error should post an error message with more + details. + + + This operation is not supported. + + + Elements can use values starting from + this (and lower) to define custom error codes. + + + Pre-defined custom error code (define your + custom error code to this to avoid compiler + warnings). + + + Pre-defined custom error code. + + + + Standard predefined formats + + undefined format + + + the default format of the pad/element. This can be + samples for raw audio, frames/fields for raw video (some, but not all, + elements support this; use @GST_FORMAT_TIME if you don't have a good + reason to query for samples/frames) + + + bytes + + + time in nanoseconds + + + buffers (few, if any, elements implement this as of + May 2009) + + + percentage of stream (few, if any, elements implement + this as of May 2009) + + + Return the format registered with the given nick. + + The format with @nick or GST_FORMAT_UNDEFINED +if the format was not registered. + + + + + The nick of the format + + + + + + Get details about the given format. + + The #GstFormatDefinition for @format or %NULL +on failure. + +MT safe. + + + + + The format to get details of + + + + + + Get a printable name for the given format. Do not modify or free. + + a reference to the static name of the format +or %NULL if the format is unknown. + + + + + a #GstFormat + + + + + + Iterate all the registered formats. The format definition is read +only. + + a GstIterator of #GstFormatDefinition. + + + + + Create a new GstFormat based on the nick or return an +already registered format with that nick. + + A new GstFormat or an already registered format +with the same nick. + +MT safe. + + + + + The nick of the new format + + + + The description of the new format + + + + + + Get the unique quark for the given format. + + the quark associated with the format or 0 if the format +is unknown. + + + + + a #GstFormat + + + + + + + A format definition + + The unique id of this format + + + + A short nick of the format + + + + A longer description of the format + + + + A quark for the nick + + + + + + + + + GhostPads are useful when organizing pipelines with #GstBin like elements. +The idea here is to create hierarchical element graphs. The bin element +contains a sub-graph. Now one would like to treat the bin-element like any +other #GstElement. This is where GhostPads come into play. A GhostPad acts as +a proxy for another pad. Thus the bin can have sink and source ghost-pads +that are associated with sink and source pads of the child elements. + +If the target pad is known at creation time, gst_ghost_pad_new() is the +function to use to get a ghost-pad. Otherwise one can use gst_ghost_pad_new_no_target() +to create the ghost-pad and use gst_ghost_pad_set_target() to establish the +association later on. + +Note that GhostPads add overhead to the data processing of a pipeline. + + Create a new ghostpad with @target as the target. The direction will be taken +from the target pad. @target must be unlinked. + +Will ref the target. + + a new #GstPad, or %NULL in +case of an error. + + + + + the name of the new pad, or %NULL to assign a default name + + + + the pad to ghost. + + + + + + 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. + +Will ref the target. + + a new #GstPad, or %NULL in +case of an error. + + + + + the name of the new pad, or %NULL to assign a default name. + + + + the pad to ghost. + + + + the #GstPadTemplate to use on the ghostpad. + + + + + + Create a new ghostpad without a target with the given direction. +A target can be set on the ghostpad later with the +gst_ghost_pad_set_target() function. + +The created ghostpad will not have a padtemplate. + + a new #GstPad, or %NULL in +case of an error. + + + + + the name of the new pad, or %NULL to assign a default name. + + + + the direction of the ghostpad + + + + + + Create a new ghostpad based on @templ, without setting a target. The +direction will be taken from the @templ. + + a new #GstPad, or %NULL in +case of an error. + + + + + the name of the new pad, or %NULL to assign a default name + + + + the #GstPadTemplate to create the ghostpad from. + + + + + + Invoke the default activate mode function of a ghost pad. + + %TRUE if the operation was successful. + + + + + the #GstPad to activate or deactivate. + + + + the parent of @pad or %NULL + + + + the requested activation mode + + + + whether the pad should be active or not. + + + + + + Invoke the default activate mode function of a proxy pad that is +owned by a ghost pad. + + %TRUE if the operation was successful. + + + + + the #GstPad to activate or deactivate. + + + + the parent of @pad or %NULL + + + + the requested activation mode + + + + whether the pad should be active or not. + + + + + + Finish initialization of a newly allocated ghost pad. + +This function is most useful in language bindings and when subclassing +#GstGhostPad; plugin and application developers normally will not call this +function. Call this function directly after a call to g_object_new +(GST_TYPE_GHOST_PAD, "direction", @dir, ..., NULL). + + %TRUE if the construction succeeds, %FALSE otherwise. + + + + + the newly allocated ghost pad + + + + + + Get the target pad of @gpad. Unref target pad after usage. + + the target #GstPad, can be +%NULL if the ghostpad has no target set. Unref target pad after +usage. + + + + + the #GstGhostPad + + + + + + Set the new target of the ghostpad @gpad. Any existing target +is unlinked and links to the new target are established. if @newtarget is +%NULL the target will be cleared. + + %TRUE if the new target could be set. This function + can return %FALSE when the internal pads could not be linked. + + + + + the #GstGhostPad + + + + the new pad target + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A GstIterator is used to retrieve multiple objects from another object in +a threadsafe way. + +Various GStreamer objects provide access to their internal structures using +an iterator. + +Note that if calling a GstIterator function results in your code receiving +a refcounted object (with, say, g_value_get_object()), the refcount for that +object will not be increased. Your code is responsible for taking a reference +if it wants to continue using it later. + +The basic use pattern of an iterator is as follows: +|[<!-- language="C" --> + GstIterator *it = _get_iterator(object); + GValue item = G_VALUE_INIT; + done = FALSE; + while (!done) { + switch (gst_iterator_next (it, &amp;item)) { + case GST_ITERATOR_OK: + ...get/use/change item here... + g_value_reset (&amp;item); + break; + case GST_ITERATOR_RESYNC: + ...rollback changes to items... + gst_iterator_resync (it); + break; + case GST_ITERATOR_ERROR: + ...wrong parameters were given... + done = TRUE; + break; + case GST_ITERATOR_DONE: + done = TRUE; + break; + } + } + g_value_unset (&amp;item); + gst_iterator_free (it); +]| + + The function to copy the iterator + + + + The function to get the next item in the iterator + + + + The function to be called for each item retrieved + + + + The function to call when a resync is needed. + + + + The function to call when the iterator is freed + + + + The iterator that is currently pushed with gst_iterator_push() + + + + The type of the object that this iterator will return + + + + The lock protecting the data structure and the cookie. + + + + The cookie; the value of the master_cookie when this iterator was + created. + + + + A pointer to the master cookie. + + + + the size of the iterator + + + + + + + + + Create a new iterator. This function is mainly used for objects +implementing the next/resync/free function to iterate a data structure. + +For each item retrieved, the @item function is called with the lock +held. The @free function is called when the iterator is freed. + + the new #GstIterator. + +MT safe. + + + + + the size of the iterator structure + + + + #GType of children + + + + pointer to a #GMutex. + + + + pointer to a guint32 that is changed when the items in the + iterator changed. + + + + copy function + + + + function to get next item + + + + function to call on each item retrieved + + + + function to resync the iterator + + + + function to free the iterator + + + + + + Create a new iterator designed for iterating @list. + +The list you iterate is usually part of a data structure @owner and is +protected with @lock. + +The iterator will use @lock to retrieve the next item of the list and it +will then call the @item function before releasing @lock again. + +When a concurrent update to the list is performed, usually by @owner while +holding @lock, @master_cookie will be updated. The iterator implementation +will notice the update of the cookie and will return %GST_ITERATOR_RESYNC to +the user of the iterator in the next call to gst_iterator_next(). + + the new #GstIterator for @list. + +MT safe. + + + + + #GType of elements + + + + pointer to a #GMutex protecting the list. + + + + pointer to a guint32 that is incremented when the list + is changed. + + + + pointer to the list + + + + + + object owning the list + + + + function to call on each item retrieved + + + + + + This #GstIterator is a convenient iterator for the common +case where a #GstIterator needs to be returned but only +a single object has to be considered. This happens often +for the #GstPadIterIntLinkFunction. + + the new #GstIterator for @object. + + + + + #GType of the passed object + + + + object that this iterator should return + + + + + + Copy the iterator and its state. + + a new copy of @it. + + + + + a #GstIterator + + + + + + Create a new iterator from an existing iterator. The new iterator +will only return those elements that match the given compare function @func. +The first parameter that is passed to @func is the #GValue of the current +iterator element and the second parameter is @user_data. @func should +return 0 for elements that should be included in the filtered iterator. + +When this iterator is freed, @it will also be freed. + + a new #GstIterator. + +MT safe. + + + + + The #GstIterator to filter + + + + the compare function to select elements + + + + user data passed to the compare function + + + + + + Find the first element in @it that matches the compare function @func. +@func should return 0 when the element is found. The first parameter +to @func will be the current element of the iterator and the +second parameter will be @user_data. +The result will be stored in @elem if a result is found. + +The iterator will not be freed. + +This function will return %FALSE if an error happened to the iterator +or if the element wasn't found. + + Returns %TRUE if the element was found, else %FALSE. + +MT safe. + + + + + The #GstIterator to iterate + + + + the compare function to use + + + + pointer to a #GValue where to store the result + + + + user data passed to the compare function + + + + + + Folds @func over the elements of @iter. That is to say, @func will be called +as @func (object, @ret, @user_data) for each object in @it. The normal use +of this procedure is to accumulate the results of operating on the objects in +@ret. + +This procedure can be used (and is used internally) to implement the +gst_iterator_foreach() and gst_iterator_find_custom() operations. + +The fold will proceed as long as @func returns %TRUE. When the iterator has no +more arguments, %GST_ITERATOR_DONE will be returned. If @func returns %FALSE, +the fold will stop, and %GST_ITERATOR_OK will be returned. Errors or resyncs +will cause fold to return %GST_ITERATOR_ERROR or %GST_ITERATOR_RESYNC as +appropriate. + +The iterator will not be freed. + + A #GstIteratorResult, as described above. + +MT safe. + + + + + The #GstIterator to fold over + + + + the fold function + + + + the seed value passed to the fold function + + + + user data passed to the fold function + + + + + + Iterate over all element of @it and call the given function @func for +each element. + + the result call to gst_iterator_fold(). The iterator will not be +freed. + +MT safe. + + + + + The #GstIterator to iterate + + + + the function to call for each element. + + + + user data passed to the function + + + + + + Free the iterator. + +MT safe. + + + + + + The #GstIterator to free + + + + + + Get the next item from the iterator in @elem. + +Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid +value. @elem must have been initialized to the type of the iterator or +initialized to zeroes with g_value_unset(). The caller is responsible for +unsetting or resetting @elem with g_value_unset() or g_value_reset() +after usage. + +When this function returns %GST_ITERATOR_DONE, no more elements can be +retrieved from @it. + +A return value of %GST_ITERATOR_RESYNC indicates that the element list was +concurrently updated. The user of @it should call gst_iterator_resync() to +get the newly updated list. + +A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error. + + The result of the iteration. Unset @elem after usage. + +MT safe. + + + + + The #GstIterator to iterate + + + + pointer to hold next element + + + + + + Pushes @other iterator onto @it. All calls performed on @it are +forwarded to @other. If @other returns %GST_ITERATOR_DONE, it is +popped again and calls are handled by @it again. + +This function is mainly used by objects implementing the iterator +next function to recurse into substructures. + +When gst_iterator_resync() is called on @it, @other will automatically be +popped. + +MT safe. + + + + + + The #GstIterator to use + + + + The #GstIterator to push + + + + + + Resync the iterator. this function is mostly called +after gst_iterator_next() returned %GST_ITERATOR_RESYNC. + +When an iterator was pushed on @it, it will automatically be popped again +with this function. + +MT safe. + + + + + + The #GstIterator to resync + + + + + + + This function will be called when creating a copy of @it and should +create a copy of all custom iterator fields or increase their +reference counts. + + + + + + The original iterator + + + + The copied iterator + + + + + + A function to be passed to gst_iterator_fold(). + + %TRUE if the fold should continue, %FALSE if it should stop. + + + + + the item to fold + + + + a #GValue collecting the result + + + + data passed to gst_iterator_fold() + + + + + + A function that is called by gst_iterator_foreach() for every element. + + + + + + The item + + + + User data + + + + + + This function will be called when the iterator is freed. + +Implementors of a #GstIterator should implement this +function and pass it to the constructor of the custom iterator. +The function will be called with the iterator lock held. + + + + + + the iterator + + + + + + The result of a #GstIteratorItemFunction. + + Skip this item + + + Return item + + + Stop after this item. + + + + The function that will be called after the next item of the iterator +has been retrieved. This function can be used to skip items or stop +the iterator. + +The function will be called with the iterator lock held. + + the result of the operation. + + + + + the iterator + + + + the item being retrieved. + + + + + + The function that will be called when the next element of the iterator +should be retrieved. + +Implementors of a #GstIterator should implement this +function and pass it to the constructor of the custom iterator. +The function will be called with the iterator lock held. + + the result of the operation. + + + + + the iterator + + + + a pointer to hold the next item + + + + + + The result of gst_iterator_next(). + + No more items in the iterator + + + An item was retrieved + + + Datastructure changed while iterating + + + An error happened + + + + This function will be called whenever a concurrent update happened +to the iterated datastructure. The implementor of the iterator should +restart the iterator from the beginning and clean up any state it might +have. + +Implementors of a #GstIterator should implement this +function and pass it to the constructor of the custom iterator. +The function will be called with the iterator lock held. + + + + + + the iterator + + + + + + To be used in GST_PLUGIN_DEFINE if unsure about the licence. + + + + GstLockFlags value alias for GST_LOCK_FLAG_READ | GST_LOCK_FLAG_WRITE + + + + Library errors are for errors from the library being used by elements +(initializing, finalizing, settings, ...) + + a general error which doesn't fit in any other +category. Make sure you add a custom message to the error call. + + + do not use this except as a placeholder for +deciding where to go while developing code. + + + used when the library could not be opened. + + + used when the library could not be closed. + + + used when the library doesn't accept settings. + + + used when the library generated an encoding error. + + + the number of library error types. + + + + + + + + + Flags used when locking miniobjects + + lock for read access + + + lock for write access + + + lock for exclusive access + + + first flag that can be used for custom purposes + + + + Function prototype for a logging function that can be registered with +gst_debug_add_log_function(). +Use G_GNUC_NO_INSTRUMENT on that function. + + + + + + a #GstDebugCategory + + + + a #GstDebugLevel + + + + file name + + + + function name + + + + line number + + + + a #GObject + + + + the message + + + + user data for the log function + + + + + + GstMapFlags value alias for GST_MAP_READ | GST_MAP_WRITE + + + + This metadata stays relevant as long as memory layout is unchanged. + + + + Constant that defines one GStreamer millisecond. + + + + Flags used when mapping memory + + map for read access + + + map for write access + + + first flag that can be used for custom purposes + + + + A structure containing the result of a map operation such as +gst_memory_map(). It contains the data and size. + + a pointer to the mapped memory + + + + flags used when mapping the memory + + + + a pointer to the mapped data + + + + + + the valid size in @data + + + + the maximum bytes in @data + + + + extra private user_data that the implementation of the memory + can use to store extra info. + + + + + + + + + + + + GstMemory is a lightweight refcounted object that wraps a region of memory. +They are typically used to manage the data of a #GstBuffer. + +A GstMemory object has an allocated region of memory of maxsize. The maximum +size does not change during the lifetime of the memory object. The memory +also has an offset and size property that specifies the valid range of memory +in the allocated region. + +Memory is usually created by allocators with a gst_allocator_alloc() +method call. When %NULL is used as the allocator, the default allocator will +be used. + +New allocators can be registered with gst_allocator_register(). +Allocators are identified by name and can be retrieved with +gst_allocator_find(). gst_allocator_set_default() can be used to change the +default allocator. + +New memory can be created with gst_memory_new_wrapped() that wraps the memory +allocated elsewhere. + +Refcounting of the memory block is performed with gst_memory_ref() and +gst_memory_unref(). + +The size of the memory can be retrieved and changed with +gst_memory_get_sizes() and gst_memory_resize() respectively. + +Getting access to the data of the memory is performed with gst_memory_map(). +The call will return a pointer to offset bytes into the region of memory. +After the memory access is completed, gst_memory_unmap() should be called. + +Memory can be copied with gst_memory_copy(), which will return a writable +copy. gst_memory_share() will create a new memory block that shares the +memory with an existing memory block at a custom offset and with a custom +size. + +Memory can be efficiently merged when gst_memory_is_span() returns %TRUE. + + parent structure + + + + pointer to the #GstAllocator + + + + parent memory block + + + + the maximum size allocated + + + + the alignment of the memory + + + + the offset where valid data starts + + + + the size of valid data + + + + Allocate a new memory block that wraps the given @data. + +The prefix/padding must be filled with 0 if @flags contains +#GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively. + + a new #GstMemory. + + + + + #GstMemoryFlags + + + + data to + wrap + + + + + + allocated size of @data + + + + offset in @data + + + + size of valid data + + + + user_data + + + + called with @user_data when the memory is freed + + + + + + Return a copy of @size bytes from @mem starting from @offset. This copy is +guaranteed to be writable. @size can be set to -1 to return a copy +from @offset to the end of the memory region. + + a new #GstMemory. + + + + + a #GstMemory + + + + offset to copy from + + + + size to copy, or -1 to copy to the end of the memory region + + + + + + Get the current @size, @offset and @maxsize of @mem. + + the current sizes of @mem + + + + + a #GstMemory + + + + pointer to offset + + + + pointer to maxsize + + + + + + Initializes a newly allocated @mem with the given parameters. This function +will call gst_mini_object_init() with the default memory parameters. + + + + + + a #GstMemory + + + + #GstMemoryFlags + + + + the #GstAllocator + + + + the parent of @mem + + + + the total size of the memory + + + + the alignment of the memory + + + + The offset in the memory + + + + the size of valid data in the memory + + + + + + Check if @mem1 and mem2 share the memory with a common parent memory object +and that the memory is contiguous. + +If this is the case, the memory of @mem1 and @mem2 can be merged +efficiently by performing gst_memory_share() on the parent object from +the returned @offset. + + %TRUE if the memory is contiguous and of a common parent. + + + + + a #GstMemory + + + + a #GstMemory + + + + a pointer to a result offset + + + + + + Check if @mem if allocated with an allocator for @mem_type. + + %TRUE if @mem was allocated from an allocator for @mem_type. + + + + + a #GstMemory + + + + a memory type + + + + + + Create a #GstMemory object that is mapped with @flags. If @mem is mappable +with @flags, this function returns the mapped @mem directly. Otherwise a +mapped copy of @mem is returned. + +This function takes ownership of old @mem and returns a reference to a new +#GstMemory. + + a #GstMemory object mapped +with @flags or %NULL when a mapping is not possible. + + + + + a #GstMemory + + + + pointer for info + + + + mapping flags + + + + + + Fill @info with the pointer and sizes of the memory in @mem that can be +accessed according to @flags. + +This function can return %FALSE for various reasons: +- the memory backed by @mem is not accessible with the given @flags. +- the memory was already mapped with a different mapping. + +@info and its contents remain valid for as long as @mem is valid and +until gst_memory_unmap() is called. + +For each gst_memory_map() call, a corresponding gst_memory_unmap() call +should be done. + + %TRUE if the map operation was successful. + + + + + a #GstMemory + + + + pointer for info + + + + mapping flags + + + + + + Resize the memory region. @mem should be writable and offset + size should be +less than the maxsize of @mem. + +#GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED will be +cleared when offset or padding is increased respectively. + + + + + + a #GstMemory + + + + a new offset + + + + a new size + + + + + + Return a shared copy of @size bytes from @mem starting from @offset. No +memory copy is performed and the memory region is simply shared. The result +is guaranteed to be non-writable. @size can be set to -1 to return a shared +copy from @offset to the end of the memory region. + + a new #GstMemory. + + + + + a #GstMemory + + + + offset to share from + + + + size to share, or -1 to share to the end of the memory region + + + + + + Release the memory obtained with gst_memory_map() + + + + + + a #GstMemory + + + + a #GstMapInfo + + + + + + + Copy @size bytes from @mem starting at @offset and return them wrapped in a +new GstMemory object. +If @size is set to -1, all bytes starting at @offset are copied. + + a new #GstMemory object wrapping a copy of the requested region in +@mem. + + + + + a #GstMemory + + + + an offset + + + + a size or -1 + + + + + + Flags for wrapped memory. + + memory is readonly. It is not allowed to map the +memory with #GST_MAP_WRITE. + + + memory must not be shared. Copies will have to be +made when this memory needs to be shared between buffers. + + + the memory prefix is filled with 0 bytes + + + the memory padding is filled with 0 bytes + + + the memory is physically contiguous. (Since 1.2) + + + the memory can't be mapped via gst_memory_map() without any preconditions. (Since 1.2) + + + first flag that can be used for custom purposes + + + + Check if @mem1 and @mem2 occupy contiguous memory and return the offset of +@mem1 in the parent buffer in @offset. + + %TRUE if @mem1 and @mem2 are in contiguous memory. + + + + + a #GstMemory + + + + a #GstMemory + + + + a result offset + + + + + + Get the memory of @mem that can be accessed according to the mode specified +in @info's flags. The function should return a pointer that contains at least +@maxsize bytes. + + a pointer to memory of which at least @maxsize bytes can be +accessed according to the access pattern in @info's flags. + + + + + a #GstMemory + + + + the #GstMapInfo to map with + + + + size to map + + + + + + Get the memory of @mem that can be accessed according to the mode specified +in @flags. The function should return a pointer that contains at least +@maxsize bytes. + + a pointer to memory of which at least @maxsize bytes can be +accessed according to the access pattern in @flags. + + + + + a #GstMemory + + + + size to map + + + + access mode for the memory + + + + + + Share @size bytes from @mem starting at @offset and return them wrapped in a +new GstMemory object. If @size is set to -1, all bytes starting at @offset are +shared. This function does not make a copy of the bytes in @mem. + + a new #GstMemory object sharing the requested region in @mem. + + + + + a #GstMemory + + + + an offset + + + + a size or -1 + + + + + + Return the pointer previously retrieved with gst_memory_map() with @info. + + + + + + a #GstMemory + + + + a #GstMapInfo + + + + + + Return the pointer previously retrieved with gst_memory_map(). + + + + + + a #GstMemory + + + + + + Messages are implemented as a subclass of #GstMiniObject with a generic +#GstStructure as the content. This allows for writing custom messages without +requiring an API change while allowing a wide range of different types +of messages. + +Messages are posted by objects in the pipeline and are passed to the +application using the #GstBus. + +The basic use pattern of posting a message on a #GstBus is as follows: +|[<!-- language="C" --> + gst_bus_post (bus, gst_message_new_eos()); +]| + +A #GstElement usually posts messages on the bus provided by the parent +container using gst_element_post_message(). + + the parent structure + + + + the #GstMessageType of the message + + + + the timestamp of the message + + + + the src of the message + + + + the sequence number of the message + + + + + + + + + + Create a new application-typed message. GStreamer will never create these +messages; they are a gift from us to you. Enjoy. + + The new application message. + +MT safe. + + + + + The object originating the message. + + + + the structure for the message. The message + will take ownership of the structure. + + + + + + The message is posted when elements completed an ASYNC state change. +@running_time contains the time of the desired running_time when this +elements goes to PLAYING. A value of #GST_CLOCK_TIME_NONE for @running_time +means that the element has no clock interaction and thus doesn't care about +the running_time of the pipeline. + + The new async_done message. + +MT safe. + + + + + The object originating the message. + + + + the desired running_time + + + + + + This message is posted by elements when they start an ASYNC state change. + + The new async_start message. + +MT safe. + + + + + The object originating the message. + + + + + + Create a new buffering message. This message can be posted by an element that +needs to buffer data before it can continue processing. @percent should be a +value between 0 and 100. A value of 100 means that the buffering completed. + +When @percent is < 100 the application should PAUSE a PLAYING pipeline. When +@percent is 100, the application can set the pipeline (back) to PLAYING. +The application must be prepared to receive BUFFERING messages in the +PREROLLING state and may only set the pipeline to PLAYING after receiving a +message with @percent set to 100, which can happen after the pipeline +completed prerolling. + +MT safe. + + The new buffering message. + + + + + The object originating the message. + + + + The buffering percent + + + + + + Create a clock lost message. This message is posted whenever the +clock is not valid anymore. + +If this message is posted by the pipeline, the pipeline will +select a new clock again when it goes to PLAYING. It might therefore +be needed to set the pipeline to PAUSED and PLAYING again. + + The new clock lost message. + +MT safe. + + + + + The object originating the message. + + + + the clock that was lost + + + + + + Create a clock provide message. This message is posted whenever an +element is ready to provide a clock or lost its ability to provide +a clock (maybe because it paused or became EOS). + +This message is mainly used internally to manage the clock +selection. + + the new provide clock message. + +MT safe. + + + + + The object originating the message. + + + + the clock it provides + + + + %TRUE if the sender can provide a clock + + + + + + 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 +app. The structure field can be %NULL. + + The new message. + +MT safe. + + + + + The #GstMessageType to distinguish messages + + + + The object originating the message. + + + + the structure for the + message. The message will take ownership of the structure. + + + + + + Creates a new device-added message. The device-added message is produced by +#GstDeviceProvider or a #GstDeviceMonitor. They announce the appearance +of monitored devices. + + a newly allocated #GstMessage + + + + + The #GstObject that created the message + + + + The new #GstDevice + + + + + + Creates a new device-removed message. The device-removed message is produced +by #GstDeviceProvider or a #GstDeviceMonitor. They announce the +disappearance of monitored devices. + + a newly allocated #GstMessage + + + + + The #GstObject that created the message + + + + The removed #GstDevice + + + + + + Create a new duration changed message. This message is posted by elements +that know the duration of a stream when the duration changes. This message +is received by bins and is used to calculate the total duration of a +pipeline. + + The new duration-changed message. + +MT safe. + + + + + The object originating the message. + + + + + + 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 +"the firewire cable was unplugged". The format of the message should be +documented in the element's documentation. The structure field can be %NULL. + + The new element message. + +MT safe. + + + + + The object originating the message. + + + + The structure for the + message. The message will take ownership of the structure. + + + + + + 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 +message to the application if all sinks have posted an EOS message. + + The new eos message. + +MT safe. + + + + + The object originating the message. + + + + + + Create a new error message. The message will copy @error and +@debug. This message is posted by element when a fatal event +occurred. The pipeline will probably (partially) stop. The application +receiving this message should stop the pipeline. + + the new error message. + +MT safe. + + + + + The object originating the message. + + + + The GError for this message. + + + + A debugging string. + + + + + + Create a new error message. The message will copy @error and +@debug. This message is posted by element when a fatal event +occurred. The pipeline will probably (partially) stop. The application +receiving this message should stop the pipeline. + + the new error message. + + + + + The object originating the message. + + + + The GError for this message. + + + + A debugging string. + + + + (allow-none): A GstStructure with details + + + + + + This message is posted when an element has a new local #GstContext. + + The new have-context message. + +MT safe. + + + + + The object originating the message. + + + + the context + + + + + + Create a new info message. The message will make copies of @error and +@debug. + + the new info message. + +MT safe. + + + + + The object originating the message. + + + + The GError for this message. + + + + A debugging string. + + + + + + Create a new info message. The message will make copies of @error and +@debug. + + the new warning message. + + + + + The object originating the message. + + + + The GError for this message. + + + + A debugging string. + + + + (allow-none): A GstStructure with details + + + + + + This message can be posted by elements when their latency requirements have +changed. + + The new latency message. + +MT safe. + + + + + The object originating the message. + + + + + + This message is posted when an element needs a specific #GstContext. + + The new need-context message. + +MT safe. + + + + + The object originating the message. + + + + The context type that is needed + + + + + + Create a new clock message. This message is posted whenever the +pipeline selects a new clock for the pipeline. + + The new new clock message. + +MT safe. + + + + + The object originating the message. + + + + the new selected clock + + + + + + Progress messages are posted by elements when they use an asynchronous task +to perform actions triggered by a state change. + +@code contains a well defined string describing the action. +@text should contain a user visible string detailing the current action. + + The new qos message. + + + + + The object originating the message. + + + + a #GstProgressType + + + + a progress code + + + + free, user visible text describing the progress + + + + + + + a newly allocated #GstMessage + + + + + The #GstObject whose property changed (may or may not be a #GstElement) + + + + name of the property that changed + + + + new property value, or %NULL + + + + + + A QOS message is posted on the bus whenever an element decides to drop a +buffer because of QoS reasons or whenever it changes its processing strategy +because of QoS reasons (quality adjustments such as processing at lower +accuracy). + +This message can be posted by an element that performs synchronisation against the +clock (live) or it could be dropped by an element that performs QoS because of QOS +events received from a downstream element (!live). + +@running_time, @stream_time, @timestamp, @duration should be set to the +respective running-time, stream-time, timestamp and duration of the (dropped) +buffer that generated the QoS event. Values can be left to +GST_CLOCK_TIME_NONE when unknown. + + The new qos message. + +MT safe. + + + + + The object originating the message. + + + + if the message was generated by a live element + + + + the running time of the buffer that generated the message + + + + the stream time of the buffer that generated the message + + + + the timestamps of the buffer that generated the message + + + + the duration of the buffer that generated the message + + + + + + Creates a new redirect message and adds a new entry to it. Redirect messages +are posted when an element detects that the actual data has to be retrieved +from a different location. This is useful if such a redirection cannot be +handled inside a source element, for example when HTTP 302/303 redirects +return a non-HTTP URL. + +The redirect message can hold multiple entries. The first one is added +when the redirect message is created, with the given location, tag_list, +entry_struct arguments. Use gst_message_add_redirect_entry() to add more +entries. + +Each entry has a location, a tag list, and a structure. All of these are +optional. The tag list and structure are useful for additional metadata, +such as bitrate statistics for the given location. + +By default, message recipients should treat entries in the order they are +stored. The recipient should therefore try entry #0 first, and if this +entry is not acceptable or working, try entry #1 etc. Senders must make +sure that they add entries in this order. However, recipients are free to +ignore the order and pick an entry that is "best" for them. One example +would be a recipient that scans the entries for the one with the highest +bitrate tag. + +The specified location string is copied. However, ownership over the tag +list and structure are transferred to the message. + + a newly allocated #GstMessage + + + + + The #GstObject whose property changed (may or may not be a #GstElement) + + + + location string for the new entry + + + + tag list for the new entry + + + + structure for the new entry + + + + + + 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 +pipeline because a higher priority stream is being played. + + the new request state message. + +MT safe. + + + + + The object originating the message. + + + + The new requested state + + + + + + This message is posted when the pipeline running-time should be reset to +@running_time, like after a flushing seek. + + The new reset_time message. + +MT safe. + + + + + The object originating the message. + + + + the requested running-time + + + + + + Create a new segment done message. This message is posted by elements that +finish playback of a segment as a result of a segment seek. This message +is received by the application after all elements that posted a segment_start +have posted the segment_done. + + the new segment done message. + +MT safe. + + + + + The object originating the message. + + + + The format of the position being done + + + + The position of the segment being done + + + + + + Create a new segment message. This message is posted by elements that +start playback of a segment as a result of a segment seek. This message +is not received by the application but is used for maintenance reasons in +container elements. + + the new segment start message. + +MT safe. + + + + + The object originating the message. + + + + The format of the position being played + + + + The position of the segment being played + + + + + + Create a state change message. This message is posted whenever an element +changed its state. + + the new state change message. + +MT safe. + + + + + The object originating the message. + + + + the previous state + + + + the new (current) state + + + + the pending (target) state + + + + + + Create a state dirty message. This message is posted whenever an element +changed its state asynchronously and is used internally to update the +states of container objects. + + the new state dirty message. + +MT safe. + + + + + The object originating the message + + + + + + This message is posted by elements when they complete a part, when @intermediate set +to %TRUE, or a complete step operation. + +@duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped +@amount of media in format @format. + + the new step_done message. + +MT safe. + + + + + The object originating the message. + + + + the format of @amount + + + + the amount of stepped data + + + + the rate of the stepped amount + + + + is this an flushing step + + + + is this an intermediate step + + + + the duration of the data + + + + the step caused EOS + + + + + + This message is posted by elements when they accept or activate a new step +event for @amount in @format. + +@active is set to %FALSE when the element accepted the new step event and has +queued it for execution in the streaming threads. + +@active is set to %TRUE when the element has activated the step operation and +is now ready to start executing the step in the streaming thread. After this +message is emitted, the application can queue a new step operation in the +element. + + The new step_start message. + +MT safe. + + + + + The object originating the message. + + + + if the step is active or queued + + + + the format of @amount + + + + the amount of stepped data + + + + the rate of the stepped amount + + + + is this an flushing step + + + + is this an intermediate step + + + + + + Creates a new stream-collection message. The message is used to announce new +#GstStreamCollection + + a newly allocated #GstMessage + + + + + The #GstObject that created the message + + + + The #GstStreamCollection + + + + + + Create a new stream_start message. This message is generated and posted in +the sink elements of a GstBin. The bin will only forward the STREAM_START +message to the application if all sinks have posted an STREAM_START message. + + The new stream_start message. + +MT safe. + + + + + The object originating the message. + + + + + + Create a new stream status message. This message is posted when a streaming +thread is created/destroyed or when the state changed. + + the new stream status message. + +MT safe. + + + + + The object originating the message. + + + + The stream status type. + + + + the owner element of @src. + + + + + + Creates a new steams-selected message. The message is used to announce +that an array of streams has been selected. This is generally in response +to a #GST_EVENT_SELECT_STREAMS event, or when an element (such as decodebin3) +makes an initial selection of streams. + +The message also contains the #GstStreamCollection to which the various streams +belong to. + +Users of gst_message_new_streams_selected() can add the selected streams with +gst_message_streams_selected_add(). + + a newly allocated #GstMessage + + + + + The #GstObject that created the message + + + + The #GstStreamCollection + + + + + + Create a new structure change message. This message is posted when the +structure of a pipeline is in the process of being changed, for example +when pads are linked or unlinked. + +@src should be the sinkpad that unlinked or linked. + + the new structure change message. + +MT safe. + + + + + The object originating the message. + + + + The change type. + + + + The owner element of @src. + + + + Whether the structure change is busy. + + + + + + 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 new tag message. + +MT safe. + + + + + The object originating the message. + + + + the tag list for the message. + + + + + + Create a new TOC message. The message is posted by elements +that discovered or updated a TOC. + + a new TOC message. + +MT safe. + + + + + the object originating the message. + + + + #GstToc structure for the message. + + + + whether TOC was updated or not. + + + + + + Create a new warning message. The message will make copies of @error and +@debug. + + the new warning message. + +MT safe. + + + + + The object originating the message. + + + + The GError for this message. + + + + A debugging string. + + + + + + Create a new warning message. The message will make copies of @error and +@debug. + + the new warning message. + + + + + The object originating the message. + + + + The GError for this message. + + + + A debugging string. + + + + (allow-none): A GstStructure with details + + + + + + Creates and appends a new entry. + +The specified location string is copied. However, ownership over the tag +list and structure are transferred to the message. + + + + + + a #GstMessage of type %GST_MESSAGE_REDIRECT + + + + location string for the new entry + + + + tag list for the new entry + + + + structure for the new entry + + + + + + + the number of entries stored in the message + + + + + a #GstMessage of type %GST_MESSAGE_REDIRECT + + + + + + Retrieve the sequence number of a message. + +Messages have ever-incrementing sequence numbers, which may also be set +explicitly via gst_message_set_seqnum(). Sequence numbers are typically used +to indicate that a message corresponds to some other set of messages or +events, for example a SEGMENT_DONE message corresponding to a SEEK event. It +is considered good practice to make this correspondence when possible, though +it is not required. + +Note that events and messages share the same sequence number incrementor; +two events or messages will never have the same sequence number unless +that correspondence was made explicitly. + + The message's sequence number. + +MT safe. + + + + + A #GstMessage. + + + + + + Extracts the object managing the streaming thread from @message. + + a GValue containing the object that manages the streaming thread. +This object is usually of type GstTask but other types can be added in the +future. The object remains valid as long as @message is valid. + + + + + A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. + + + + + + Access the structure of the message. + + The structure of the message. The structure is +still owned by the message, which means that you should not free it and +that the pointer becomes invalid when you free the message. + +MT safe. + + + + + The #GstMessage. + + + + + + Checks if @message has the given @name. This function is usually used to +check the name of a custom message. + + %TRUE if @name matches the name of the message structure. + + + + + The #GstMessage. + + + + name to check + + + + + + Extract the running_time from the async_done message. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_ASYNC_DONE. + + + + Result location for the running_time or %NULL + + + + + + Extracts the buffering percent from the GstMessage. see also +gst_message_new_buffering(). + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_BUFFERING. + + + + Return location for the percent. + + + + + + Extracts the buffering stats values from @message. + + + + + + A valid #GstMessage of type GST_MESSAGE_BUFFERING. + + + + a buffering mode, or %NULL + + + + the average input rate, or %NULL + + + + the average output rate, or %NULL + + + + amount of buffering time left in + milliseconds, or %NULL + + + + + + Extracts the lost clock from the GstMessage. +The clock object returned remains valid until the message is freed. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST. + + + + a pointer to hold the lost clock + + + + + + Extracts the clock and ready flag from the GstMessage. +The clock object returned remains valid until the message is freed. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE. + + + + a pointer to hold a clock + object, or %NULL + + + + a pointer to hold the ready flag, or %NULL + + + + + + Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message. + + a #gboolean indicating if the parsing succeeded. + + + + + a GST_MESSAGE_NEED_CONTEXT type message + + + + the context type, or %NULL + + + + + + Parses a device-added message. The device-added message is produced by +#GstDeviceProvider or a #GstDeviceMonitor. It announces the appearance +of monitored devices. + + + + + + a #GstMessage of type %GST_MESSAGE_DEVICE_ADDED + + + + A location where to store a + pointer to the new #GstDevice, or %NULL + + + + + + Parses a device-removed message. The device-removed message is produced by +#GstDeviceProvider or a #GstDeviceMonitor. It announces the +disappearance of monitored devices. + + + + + + a #GstMessage of type %GST_MESSAGE_DEVICE_REMOVED + + + + A location where to store a + pointer to the removed #GstDevice, or %NULL + + + + + + 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. + +Typical usage of this function might be: +|[<!-- language="C" --> + ... + switch (GST_MESSAGE_TYPE (msg)) { + case GST_MESSAGE_ERROR: { + GError *err = NULL; + gchar *dbg_info = NULL; + + gst_message_parse_error (msg, &amp;err, &amp;dbg_info); + g_printerr ("ERROR from element %s: %s\n", + GST_OBJECT_NAME (msg->src), err->message); + g_printerr ("Debugging info: %s\n", (dbg_info) ? dbg_info : "none"); + g_error_free (err); + g_free (dbg_info); + break; + } + ... + } + ... +]| + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_ERROR. + + + + location for the GError + + + + location for the debug message, + or %NULL + + + + + + Returns the optional details structure, may be NULL if none. +The returned structure must not be freed. + + + + + + The message object + + + + A pointer to the returned details + + + + + + Extract the group from the STREAM_START message. + + %TRUE if the message had a group id set, %FALSE otherwise + +MT safe. + + + + + A valid #GstMessage of type GST_MESSAGE_STREAM_START. + + + + Result location for the group id or + %NULL + + + + + + Extract the context from the HAVE_CONTEXT message. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_HAVE_CONTEXT. + + + + Result location for the + context or %NULL + + + + + + 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. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_INFO. + + + + location for the GError + + + + location for the debug message, + or %NULL + + + + + + Returns the optional details structure, may be NULL if none +The returned structure must not be freed. + + + + + + The message object + + + + A pointer to the returned details structure + + + + + + Extracts the new clock from the GstMessage. +The clock object returned remains valid until the message is freed. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK. + + + + a pointer to hold the selected + new clock + + + + + + Parses the progress @type, @code and @text. + + + + + + A valid #GstMessage of type GST_MESSAGE_PROGRESS. + + + + location for the type + + + + location for the code + + + + location for the text + + + + + + Parses a property-notify message. These will be posted on the bus only +when set up with gst_element_add_property_notify_watch() or +gst_element_add_property_deep_notify_watch(). + + + + + + a #GstMessage of type %GST_MESSAGE_PROPERTY_NOTIFY + + + + location where to store a + pointer to the object whose property got changed, or %NULL + + + + return location for the name of the + property that got changed, or %NULL + + + + return location for the new value of + the property that got changed, or %NULL. This will only be set if the + property notify watch was told to include the value when it was set up + + + + + + Extract the timestamps and live status from the QoS message. + +The returned values give the running_time, stream_time, timestamp and +duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown +values. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_QOS. + + + + if the message was generated by a live element + + + + the running time of the buffer that + generated the message + + + + the stream time of the buffer that + generated the message + + + + the timestamps of the buffer that + generated the message + + + + the duration of the buffer that + generated the message + + + + + + Extract the QoS stats representing the history of the current continuous +pipeline playback period. + +When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are +invalid. Values of -1 for either @processed or @dropped mean unknown values. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_QOS. + + + + Units of the 'processed' and 'dropped' fields. + Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). + Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT + (samples). + + + + Total number of units correctly processed + since the last state change to READY or a flushing operation. + + + + Total number of units dropped since the last + state change to READY or a flushing operation. + + + + + + Extract the QoS values that have been calculated/analysed from the QoS data + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_QOS. + + + + The difference of the running-time against + the deadline. + + + + Long term prediction of the ideal rate + relative to normal rate to get optimal quality. + + + + An element dependent integer value that + specifies the current quality level of the element. The default + maximum quality is 1000000. + + + + + + Parses the location and/or structure from the entry with the given index. +The index must be between 0 and gst_message_get_num_redirect_entries() - 1. +Returned pointers are valid for as long as this message exists. + + + + + + a #GstMessage of type %GST_MESSAGE_REDIRECT + + + + index of the entry to parse + + + + return location for + the pointer to the entry's location string, or %NULL + + + + return location for + the pointer to the entry's tag list, or %NULL + + + + return location + for the pointer to the entry's structure, or %NULL + + + + + + Extract the requested state from the request_state message. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_REQUEST_STATE. + + + + Result location for the requested state or %NULL + + + + + + Extract the running-time from the RESET_TIME message. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_RESET_TIME. + + + + Result location for the running_time or + %NULL + + + + + + Extracts the position and format from the segment done message. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_SEGMENT_DONE. + + + + Result location for the format, or %NULL + + + + Result location for the position, or %NULL + + + + + + Extracts the position and format from the segment start message. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_SEGMENT_START. + + + + Result location for the format, or %NULL + + + + Result location for the position, or %NULL + + + + + + Extracts the old and new states from the GstMessage. + +Typical usage of this function might be: +|[<!-- language="C" --> + ... + switch (GST_MESSAGE_TYPE (msg)) { + case GST_MESSAGE_STATE_CHANGED: { + GstState old_state, new_state; + + gst_message_parse_state_changed (msg, &amp;old_state, &amp;new_state, NULL); + g_print ("Element %s changed state from %s to %s.\n", + GST_OBJECT_NAME (msg->src), + gst_element_state_get_name (old_state), + gst_element_state_get_name (new_state)); + break; + } + ... + } + ... +]| + +MT safe. + + + + + + a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED + + + + the previous state, or %NULL + + + + the new (current) state, or %NULL + + + + the pending (target) state, or %NULL + + + + + + Extract the values the step_done message. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_STEP_DONE. + + + + result location for the format + + + + result location for the amount + + + + result location for the rate + + + + result location for the flush flag + + + + result location for the intermediate flag + + + + result location for the duration + + + + result location for the EOS flag + + + + + + Extract the values from step_start message. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_STEP_DONE. + + + + result location for the active flag + + + + result location for the format + + + + result location for the amount + + + + result location for the rate + + + + result location for the flush flag + + + + result location for the intermediate flag + + + + + + Parses a stream-collection message. + + + + + + a #GstMessage of type %GST_MESSAGE_STREAM_COLLECTION + + + + A location where to store a + pointer to the #GstStreamCollection, or %NULL + + + + + + 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 +should thus not be unreffed. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. + + + + A pointer to hold the status type + + + + The owner element of the message source + + + + + + Parses a streams-selected message. + + + + + + a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED + + + + A location where to store a + pointer to the #GstStreamCollection, or %NULL + + + + + + Extracts the change type and completion status from the GstMessage. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE. + + + + A pointer to hold the change type + + + + The owner element of the + message source + + + + a pointer to hold whether the change is in + progress or has been completed + + + + + + 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. + +Typical usage of this function might be: +|[<!-- language="C" --> + ... + switch (GST_MESSAGE_TYPE (msg)) { + case GST_MESSAGE_TAG: { + GstTagList *tags = NULL; + + gst_message_parse_tag (msg, &amp;tags); + g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src)); + handle_tags (tags); + gst_tag_list_unref (tags); + break; + } + ... + } + ... +]| + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_TAG. + + + + return location for the tag-list. + + + + + + Extract the TOC from the #GstMessage. The TOC returned in the +output argument is a copy; the caller must free it with +gst_toc_unref() when done. + +MT safe. + + + + + + a valid #GstMessage of type GST_MESSAGE_TOC. + + + + return location for the TOC. + + + + return location for the updated flag. + + + + + + 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. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_WARNING. + + + + location for the GError + + + + location for the debug message, + or %NULL + + + + + + Returns the optional details structure, may be NULL if none +The returned structure must not be freed. + + + + + + The message object + + + + A pointer to the returned details structure + + + + + + Configures the buffering stats values in @message. + + + + + + A valid #GstMessage of type GST_MESSAGE_BUFFERING. + + + + a buffering mode + + + + the average input rate + + + + the average output rate + + + + amount of buffering time left in milliseconds + + + + + + Sets the group id on the stream-start message. + +All streams that have the same group id are supposed to be played +together, i.e. all streams inside a container file should have the +same group id but different stream ids. The group id should change +each time the stream is started, resulting in different group ids +each time a file is played for example. + +MT safe. + + + + + + the message + + + + the group id + + + + + + Set the QoS stats representing the history of the current continuous pipeline +playback period. + +When @format is @GST_FORMAT_UNDEFINED both @dropped and @processed are +invalid. Values of -1 for either @processed or @dropped mean unknown values. + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_QOS. + + + + Units of the 'processed' and 'dropped' fields. Video sinks and video +filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters +will likely use GST_FORMAT_DEFAULT (samples). + + + + Total number of units correctly processed since the last state +change to READY or a flushing operation. + + + + Total number of units dropped since the last state change to READY +or a flushing operation. + + + + + + Set the QoS values that have been calculated/analysed from the QoS data + +MT safe. + + + + + + A valid #GstMessage of type GST_MESSAGE_QOS. + + + + The difference of the running-time against the deadline. + + + + Long term prediction of the ideal rate relative to normal rate +to get optimal quality. + + + + An element dependent integer value that specifies the current +quality level of the element. The default maximum quality is 1000000. + + + + + + Set the sequence number of a message. + +This function might be called by the creator of a message to indicate that +the message relates to other messages or events. See gst_message_get_seqnum() +for more information. + +MT safe. + + + + + + A #GstMessage. + + + + A sequence number. + + + + + + Configures the object handling the streaming thread. This is usually a +GstTask object but other objects might be added in the future. + + + + + + A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. + + + + the object controlling the streaming + + + + + + Adds the @stream to the @message. + + + + + + a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED + + + + a #GstStream to add to @message + + + + + + Returns the number of streams contained in the @message. + + The number of streams contained within. + + + + + a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED + + + + + + Retrieves the #GstStream with index @index from the @message. + + A #GstStream + + + + + a #GstMessage of type %GST_MESSAGE_STREAMS_SELECTED + + + + Index of the stream to retrieve + + + + + + + The different message types that are available. + + an undefined message + + + end-of-stream reached in a pipeline. The application will +only receive this message in the PLAYING state and every time it sets a +pipeline to PLAYING that is in the EOS state. The application can perform a +flushing seek in the pipeline, which will undo the EOS state again. + + + an error occurred. When the application receives an error +message it should stop playback of the pipeline and not assume that more +data will be played. + + + a warning occurred. + + + an info message occurred + + + a tag was found. + + + the pipeline is buffering. When the application +receives a buffering message in the PLAYING state for a non-live pipeline it +must PAUSE the pipeline until the buffering completes, when the percentage +field in the message is 100%. For live pipelines, no action must be +performed and the buffering percentage can be used to inform the user about +the progress. + + + a state change happened + + + an element changed state in a streaming thread. +This message is deprecated. + + + a stepping operation finished. + + + an element notifies its capability of providing + a clock. This message is used internally and + never forwarded to the application. + + + The current clock as selected by the pipeline became + unusable. The pipeline will select a new clock on + the next PLAYING state change. The application + should set the pipeline to PAUSED and back to + PLAYING when this message is received. + + + a new clock was selected in the pipeline. + + + the structure of the pipeline changed. This +message is used internally and never forwarded to the application. + + + status about a stream, emitted when it starts, + stops, errors, etc.. + + + message posted by the application, possibly + via an application-specific element. + + + element-specific message, see the specific element's + documentation + + + pipeline started playback of a segment. This +message is used internally and never forwarded to the application. + + + pipeline completed playback of a segment. This +message is forwarded to the application after all elements that posted +@GST_MESSAGE_SEGMENT_START posted a GST_MESSAGE_SEGMENT_DONE message. + + + The duration of a pipeline changed. The +application can get the new duration with a duration query. + + + Posted by elements when their latency changes. The +application should recalculate and distribute a new latency. + + + Posted by elements when they start an ASYNC +#GstStateChange. This message is not forwarded to the application but is used +internally. + + + Posted by elements when they complete an ASYNC +#GstStateChange. The application will only receive this message from the toplevel +pipeline. + + + Posted by elements when they want the pipeline to +change state. This message is a suggestion to the application which can +decide to perform the state change on (part of) the pipeline. + + + A stepping operation was started. + + + A buffer was dropped or an element changed its processing +strategy for Quality of Service reasons. + + + A progress message. + + + A new table of contents (TOC) was found or previously found TOC +was updated. + + + Message to request resetting the pipeline's + running time from the pipeline. This is an internal message which + applications will likely never receive. + + + Message indicating start of a new stream. Useful + e.g. when using playbin in gapless playback mode, to get notified when + the next title actually starts playing (which will be some time after + the URI for the next title has been set). + + + Message indicating that an element wants a specific context (Since 1.2) + + + Message indicating that an element created a context (Since 1.2) + + + Message is an extended message type (see below). + These extended message IDs can't be used directly with mask-based API + like gst_bus_poll() or gst_bus_timed_pop_filtered(), but you can still + filter for GST_MESSAGE_EXTENDED and then check the result for the + specific type. (Since 1.4) + + + Message indicating a #GstDevice was added to + a #GstDeviceProvider (Since 1.4) + + + Message indicating a #GstDevice was removed + from a #GstDeviceProvider (Since 1.4) + + + Message indicating a #GObject property has + changed (Since 1.10) + + + Message indicating a new #GstStreamCollection + is available (Since 1.10) + + + Message indicating the active selection of + #GstStreams has changed (Since 1.10) + + + Message indicating to request the application to + try to play the given URL(s). Useful if for example a HTTP 302/303 + response is received with a non-HTTP URL inside. (Since 1.10) + + + mask for all of the above messages. + + + Get a printable name for the given message type. Do not modify or free. + + a reference to the static name of the message. + + + + + the message type + + + + + + Get the unique quark for the given message type. + + the quark associated with the message type + + + + + the message type + + + + + + + The #GstMeta structure should be included as the first member of a #GstBuffer +metadata structure. The structure defines the API of the metadata and should +be accessible to all elements using the metadata. + +A metadata API is registered with gst_meta_api_type_register() which takes a +name for the metadata API and some tags associated with the metadata. +With gst_meta_api_type_has_tag() one can check if a certain metadata API +contains a given tag. + +Multiple implementations of a metadata API can be registered. +To implement a metadata API, gst_meta_register() should be used. This +function takes all parameters needed to create, free and transform metadata +along with the size of the metadata. The function returns a #GstMetaInfo +structure that contains the information for the implementation of the API. + +A specific implementation can be retrieved by name with gst_meta_get_info(). + +See #GstBuffer for how the metadata can be added, retrieved and removed from +buffers. + + extra flags for the metadata + + + + pointer to the #GstMetaInfo + + + + + an array of tags as strings. + + + + + + + an API + + + + + + Check if @api was registered with @tag. + + %TRUE if @api was registered with @tag. + + + + + an API + + + + the tag to check + + + + + + Register and return a GType for the @api and associate it with +@tags. + + a unique GType for @api. + + + + + an API to register + + + + tags for @api + + + + + + Lookup a previously registered meta info structure by its implementation name +@impl. + + a #GstMetaInfo with @impl, or +%NULL when no such metainfo exists. + + + + + the name + + + + + + Register a new #GstMeta implementation. + +The same @info can be retrieved later with gst_meta_get_info() by using +@impl as the key. + + a #GstMetaInfo that can be used to access metadata. + + + + + the type of the #GstMeta API + + + + the name of the #GstMeta implementation + + + + the size of the #GstMeta structure + + + + a #GstMetaInitFunction + + + + a #GstMetaFreeFunction + + + + a #GstMetaTransformFunction + + + + + + + Extra metadata flags. + + no flags + + + metadata should not be modified + + + metadata is managed by a bufferpool + + + metadata should not be removed + + + additional flags can be added starting from this flag. + + + + Function called when @meta is freed in @buffer. + + + + + + a #GstMeta + + + + a #GstBuffer + + + + + + The #GstMetaInfo provides information about a specific metadata +structure. + + tag identifying the metadata structure and api + + + + type identifying the implementor of the api + + + + size of the metadata + + + + function for initializing the metadata + + + + function for freeing the metadata + + + + function for transforming the metadata + + + + + Function called when @meta is initialized in @buffer. + + + + + + a #GstMeta + + + + parameters passed to the init function + + + + a #GstBuffer + + + + + + Extra data passed to a "gst-copy" transform #GstMetaTransformFunction. + + %TRUE if only region is copied + + + + the offset to copy, 0 if @region is %FALSE, otherwise > 0 + + + + the size to copy, -1 or the buffer size when @region is %FALSE + + + + + Function called for each @meta in @buffer as a result of performing a +transformation on @transbuf. Additional @type specific transform data +is passed to the function as @data. + +Implementations should check the @type of the transform and parse +additional type specific fields in @data that should be used to update +the metadata on @transbuf. + + %TRUE if the transform could be performed + + + + + a #GstBuffer + + + + a #GstMeta + + + + a #GstBuffer + + + + the transform type + + + + transform specific data. + + + + + + #GstMiniObject is a simple structure that can be used to implement refcounted +types. + +Subclasses will include #GstMiniObject as the first member in their structure +and then call gst_mini_object_init() to initialize the #GstMiniObject fields. + +gst_mini_object_ref() and gst_mini_object_unref() increment and decrement the +refcount respectively. When the refcount of a mini-object reaches 0, the +dispose function is called first and when this returns %TRUE, the free +function of the miniobject is called. + +A copy can be made with gst_mini_object_copy(). + +gst_mini_object_is_writable() will return %TRUE when the refcount of the +object is exactly 1, meaning the current caller has the only reference to the +object. gst_mini_object_make_writable() will return a writable version of the +object, which might be a new copy when the refcount was not 1. + +Opaque data can be associated with a #GstMiniObject with +gst_mini_object_set_qdata() and gst_mini_object_get_qdata(). The data is +meant to be specific to the particular object and is not automatically copied +with gst_mini_object_copy() or similar methods. + +A weak reference can be added and remove with gst_mini_object_weak_ref() +and gst_mini_object_weak_unref() respectively. + + the GType of the object + + + + atomic refcount + + + + atomic state of the locks + + + + extra flags. + + + + a copy function + + + + a dispose function + + + + the free function + + + + + + + + + + Creates a copy of the mini-object. + +MT safe + + the new mini-object. + + + + + the mini-object to copy + + + + + + This function gets back user data pointers stored via +gst_mini_object_set_qdata(). + + The user data pointer set, or +%NULL + + + + + The GstMiniObject to get a stored user data pointer from + + + + A #GQuark, naming the user data pointer + + + + + + Initializes a mini-object with the desired type and copy/dispose/free +functions. + + + + + + a #GstMiniObject + + + + initial #GstMiniObjectFlags + + + + the #GType of the mini-object to create + + + + the copy function, or %NULL + + + + the dispose function, or %NULL + + + + the free function or %NULL + + + + + + If @mini_object has the LOCKABLE flag set, check if the current EXCLUSIVE +lock on @object is the only one, this means that changes to the object will +not be visible to any other object. + +If the LOCKABLE flag is not set, check if the refcount of @mini_object is +exactly 1, meaning that no other reference exists to the object and that the +object is therefore writable. + +Modification of a mini-object should only be done after verifying that it +is writable. + + %TRUE if the object is writable. + + + + + the mini-object to check + + + + + + Lock the mini-object with the specified access mode in @flags. + + %TRUE if @object could be locked. + + + + + the mini-object to lock + + + + #GstLockFlags + + + + + + 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, +and returns a reference to the new object. + +MT safe + + a mini-object (possibly the same pointer) that + is writable. + + + + + the mini-object to make writable + + + + + + Increase the reference count of the mini-object. + +Note that the refcount affects the writability +of @mini-object, see gst_mini_object_is_writable(). It is +important to note that keeping additional references to +GstMiniObject instances can potentially increase the number +of memcpy operations in a pipeline, especially if the miniobject +is a #GstBuffer. + + the mini-object. + + + + + the mini-object + + + + + + This sets an opaque, named pointer on a miniobject. +The name is specified through a #GQuark (retrieved e.g. via +g_quark_from_static_string()), and the pointer +can be gotten back from the @object with gst_mini_object_get_qdata() +until the @object is disposed. +Setting a previously set user data pointer, overrides (frees) +the old pointer set, using %NULL as pointer essentially +removes the data stored. + +@destroy may be specified which is called with @data as argument +when the @object is disposed, or the data is being overwritten by +a call to gst_mini_object_set_qdata() with the same @quark. + + + + + + a #GstMiniObject + + + + A #GQuark, naming the user data pointer + + + + An opaque user data pointer + + + + Function to invoke with @data as argument, when @data + needs to be freed + + + + + + This function gets back user data pointers stored via gst_mini_object_set_qdata() +and removes the data from @object without invoking its destroy() function (if +any was set). + + The user data pointer set, or +%NULL + + + + + The GstMiniObject to get a stored user data pointer from + + + + A #GQuark, naming the user data pointer + + + + + + Unlock the mini-object with the specified access mode in @flags. + + + + + + the mini-object to unlock + + + + #GstLockFlags + + + + + + Decreases the reference count of the mini-object, possibly freeing +the mini-object. + + + + + + the mini-object + + + + + + Adds a weak reference callback to a mini object. Weak references are +used for notification when a mini object is finalized. They are called +"weak references" because they allow you to safely hold a pointer +to the mini object without calling gst_mini_object_ref() +(gst_mini_object_ref() adds a strong reference, that is, forces the object +to stay alive). + + + + + + #GstMiniObject to reference weakly + + + + callback to invoke before the mini object is freed + + + + extra data to pass to notify + + + + + + Removes a weak reference callback from a mini object. + + + + + + #GstMiniObject to remove a weak reference from + + + + callback to search for + + + + data to search for + + + + + + Atomically modifies a pointer to point to a new mini-object. +The reference count of @olddata is decreased and the reference count of +@newdata is increased. + +Either @newdata and the value pointed to by @olddata may be %NULL. + + %TRUE if @newdata was different from @olddata + + + + + pointer to a pointer to a + mini-object to be replaced + + + + pointer to new mini-object + + + + + + Replace the current #GstMiniObject pointer to by @olddata with %NULL and +return the old value. + + the #GstMiniObject at @oldata + + + + + pointer to a pointer to a mini-object to + be stolen + + + + + + Modifies a pointer to point to a new mini-object. The modification +is done atomically. This version is similar to gst_mini_object_replace() +except that it does not increase the refcount of @newdata and thus +takes ownership of @newdata. + +Either @newdata and the value pointed to by @olddata may be %NULL. + + %TRUE if @newdata was different from @olddata + + + + + pointer to a pointer to a mini-object to + be replaced + + + + pointer to new mini-object + + + + + + + Function prototype for methods to create copies of instances. + + reference to cloned instance. + + + + + MiniObject to copy + + + + + + Function prototype for when a miniobject has lost its last refcount. +Implementation of the mini object are allowed to revive the +passed object by doing a gst_mini_object_ref(). If the object is not +revived after the dispose function, the function should return %TRUE +and the memory associated with the object is freed. + + %TRUE if the object should be cleaned up. + + + + + MiniObject to dispose + + + + + + Flags for the mini object + + the object can be locked and unlocked with +gst_mini_object_lock() and gst_mini_object_unlock(). + + + the object is permanently locked in +READONLY mode. Only read locks can be performed on the object. + + + the object is expected to stay alive +even after gst_deinit() has been called and so should be ignored by leak +detection tools. (Since 1.10) + + + first flag that can be used by subclasses. + + + + Virtual function prototype for methods to free resources used by +mini-objects. + + + + + + MiniObject to free + + + + + + A #GstMiniObjectNotify function can be added to a mini object as a +callback that gets triggered when gst_mini_object_unref() drops the +last ref and @obj is about to be freed. + + + + + + data that was provided when the notify was added + + + + the mini object + + + + + + Constant that defines one GStreamer nanosecond + + + + #GstObject provides a root for the object hierarchy tree filed in by the +GStreamer library. It is currently a thin wrapper on top of +#GInitiallyUnowned. It is an abstract class that is not very usable on its own. + +#GstObject gives us basic refcounting, parenting functionality and locking. +Most of the functions are just extended for special GStreamer needs and can be +found under the same name in the base class of #GstObject which is #GObject +(e.g. g_object_ref() becomes gst_object_ref()). + +Since #GstObject derives from #GInitiallyUnowned, it also inherits the +floating reference. Be aware that functions such as gst_bin_add() and +gst_element_add_pad() take ownership of the floating reference. + +In contrast to #GObject instances, #GstObject adds a name property. The functions +gst_object_set_name() and gst_object_get_name() are used to set/get the name +of the object. + +## controlled properties + +Controlled properties offers a lightweight way to adjust gobject properties +over stream-time. It works by using time-stamped value pairs that are queued +for element-properties. At run-time the elements continuously pull value +changes for the current stream-time. + +What needs to be changed in a #GstElement? +Very little - it is just two steps to make a plugin controllable! + + * mark gobject-properties paramspecs that make sense to be controlled, + by GST_PARAM_CONTROLLABLE. + + * when processing data (get, chain, loop function) at the beginning call + gst_object_sync_values(element,timestamp). + This will make the controller update all GObject properties that are + under its control with the current values based on the timestamp. + +What needs to be done in applications? Again it's not a lot to change. + + * create a #GstControlSource. + csource = gst_interpolation_control_source_new (); + g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL); + + * Attach the #GstControlSource on the controller to a property. + gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource)); + + * Set the control values + gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1); + gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2); + + * start your pipeline + + Checks to see if there is any object named @name in @list. This function +does not do any locking of any kind. You might want to protect the +provided list with the lock of the owner of the list. This function +will lock each #GstObject in the list to compare the name, so be +careful when passing a list with a locked object. + + %TRUE if a #GstObject named @name does not appear in @list, +%FALSE if it does. + +MT safe. Grabs and releases the LOCK of each object in the list. + + + + + a list of #GstObject to + check through + + + + + + the name to search for + + + + + + 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 +from the notify. The default handler will print the new value of the property +using g_print. + +MT safe. This function grabs and releases @object's LOCK for getting its + path string. + + + + + + the #GObject that signalled the notify. + + + + a #GstObject that initiated the notify. + + + + a #GParamSpec of the property. + + + + + a set of user-specified properties to exclude or %NULL to show + all changes. + + + + + + + + Increase the reference count of @object, and possibly remove the floating +reference, if @object has a floating reference. + +In other words, if the object is floating, then this call "assumes ownership" +of the floating reference, converting it to a normal reference by clearing +the floating flag while leaving the reference count unchanged. If the object +is not floating, then this call adds a new normal reference increasing the +reference count by one. + + + + + + a #GstObject to sink + + + + + + Atomically modifies a pointer to point to a new object. +The reference count of @oldobj is decreased and the reference count of +@newobj is increased. + +Either @newobj and the value pointed to by @oldobj may be %NULL. + + %TRUE if @newobj was different from @oldobj + + + + + pointer to a place of + a #GstObject to replace + + + + a new #GstObject + + + + + + + + + + + + + + + + + + + + + + Attach the #GstControlBinding to the object. If there already was a +#GstControlBinding for this property it will be replaced. + +The @object will take ownership of the @binding. + + %FALSE if the given @binding has not been setup for this object or +has been setup for a non suitable property, %TRUE otherwise. + + + + + the controller object + + + + the #GstControlBinding that should be used + + + + + + A default error function that uses g_printerr() to display the error message +and the optional debug sting.. + +The default handler will simply print the error string using g_print. + + + + + + the #GstObject that initiated the error. + + + + the GError. + + + + an additional debug information string, or %NULL + + + + + + Gets the corresponding #GstControlBinding for the property. This should be +unreferenced again after use. + + the #GstControlBinding for +@property_name or %NULL if the property is not controlled. + + + + + the object + + + + name of the property + + + + + + Obtain the control-rate for this @object. Audio processing #GstElement +objects will use this rate to sub-divide their processing loop and call +gst_object_sync_values() inbetween. The length of the processing segment +should be up to @control-rate nanoseconds. + +If the @object is not under property control, this will return +%GST_CLOCK_TIME_NONE. This allows the element to avoid the sub-dividing. + +The control-rate is not expected to change if the element is in +%GST_STATE_PAUSED or %GST_STATE_PLAYING. + + the control rate in nanoseconds + + + + + the object that has controlled properties + + + + + + Gets a number of #GValues for the given controlled property starting at the +requested time. The array @values need to hold enough space for @n_values of +#GValue. + +This function is useful if one wants to e.g. draw a graph of the control +curve or apply a control curve sample by sample. + + %TRUE if the given array could be filled, %FALSE otherwise + + + + + the object that has controlled properties + + + + the name of the property to get + + + + the time that should be processed + + + + the time spacing between subsequent values + + + + the number of values + + + + array to put control-values in + + + + + + Returns a copy of the name of @object. +Caller should g_free() the return value after usage. +For a nameless object, this returns %NULL, which you can safely g_free() +as well. + +Free-function: g_free + + the name of @object. g_free() +after usage. + +MT safe. This function grabs and releases @object's LOCK. + + + + + a #GstObject + + + + + + Returns the parent of @object. This function increases the refcount +of the parent object so you should gst_object_unref() it after usage. + + parent of @object, this can be + %NULL if @object has no parent. unref after usage. + +MT safe. Grabs and releases @object's LOCK. + + + + + a #GstObject + + + + + + Generates a string describing the path of @object in +the object hierarchy. Only useful (or used) for debugging. + +Free-function: g_free + + a string describing the path of @object. You must + g_free() the string after usage. + +MT safe. Grabs and releases the #GstObject's LOCK for all objects + in the hierarchy. + + + + + a #GstObject + + + + + + Gets the value for the given controlled property at the requested time. + + the GValue of the property at the given time, +or %NULL if the property isn't controlled. + + + + + the object that has controlled properties + + + + the name of the property to get + + + + the time the control-change should be read from + + + + + + Gets a number of values for the given controlled property starting at the +requested time. The array @values need to hold enough space for @n_values of +the same type as the objects property's type. + +This function is useful if one wants to e.g. draw a graph of the control +curve or apply a control curve sample by sample. + +The values are unboxed and ready to be used. The similar function +gst_object_get_g_value_array() returns the array as #GValues and is +better suites for bindings. + + %TRUE if the given array could be filled, %FALSE otherwise + + + + + the object that has controlled properties + + + + the name of the property to get + + + + the time that should be processed + + + + the time spacing between subsequent values + + + + the number of values + + + + array to put control-values in + + + + + + Check if the @object has active controlled properties. + + %TRUE if the object has active controlled properties + + + + + the object that has controlled properties + + + + + + Check if @object has an ancestor @ancestor somewhere up in +the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. + Use gst_object_has_as_ancestor() instead. + +MT safe. Grabs and releases @object's locks. + + %TRUE if @ancestor is an ancestor of @object. + + + + + a #GstObject to check + + + + a #GstObject to check as ancestor + + + + + + Check if @object has an ancestor @ancestor somewhere up in +the hierarchy. One can e.g. check if a #GstElement is inside a #GstPipeline. + + %TRUE if @ancestor is an ancestor of @object. + +MT safe. Grabs and releases @object's locks. + + + + + a #GstObject to check + + + + a #GstObject to check as ancestor + + + + + + Check if @parent is the parent of @object. +E.g. a #GstElement can check if it owns a given #GstPad. + + %FALSE if either @object or @parent is %NULL. %TRUE if @parent is + the parent of @object. Otherwise %FALSE. + +MT safe. Grabs and releases @object's locks. + + + + + a #GstObject to check + + + + a #GstObject to check as parent + + + + + + Increments the reference count on @object. This function +does not take the lock on @object because it relies on +atomic refcounting. + +This object returns the input parameter to ease writing +constructs like : + result = gst_object_ref (object->parent); + + A pointer to @object + + + + + a #GstObject to reference + + + + + + Removes the corresponding #GstControlBinding. If it was the +last ref of the binding, it will be disposed. + + %TRUE if the binding could be removed. + + + + + the object + + + + the binding + + + + + + This function is used to disable the control bindings on a property for +some time, i.e. gst_object_sync_values() will do nothing for the +property. + + + + + + the object that has controlled properties + + + + property to disable + + + + boolean that specifies whether to disable the controller +or not. + + + + + + This function is used to disable all controlled properties of the @object for +some time, i.e. gst_object_sync_values() will do nothing. + + + + + + the object that has controlled properties + + + + boolean that specifies whether to disable the controller +or not. + + + + + + Change the control-rate for this @object. Audio processing #GstElement +objects will use this rate to sub-divide their processing loop and call +gst_object_sync_values() inbetween. The length of the processing segment +should be up to @control-rate nanoseconds. + +The control-rate should not change if the element is in %GST_STATE_PAUSED or +%GST_STATE_PLAYING. + + + + + + the object that has controlled properties + + + + the new control-rate in nanoseconds. + + + + + + Sets the name of @object, or gives @object a guaranteed unique +name (if @name is %NULL). +This function makes a copy of the provided name, so the caller +retains ownership of the name it sent. + + %TRUE if the name could be set. Since Objects that have +a parent cannot be renamed, this function returns %FALSE in those +cases. + +MT safe. This function grabs and releases @object's LOCK. + + + + + a #GstObject + + + + new name of object + + + + + + Sets the parent of @object to @parent. The object's reference count will +be incremented, and any floating reference will be removed (see gst_object_ref_sink()). + + %TRUE if @parent could be set or %FALSE when @object +already had a parent or @object and @parent are the same. + +MT safe. Grabs and releases @object's LOCK. + + + + + a #GstObject + + + + new parent of object + + + + + + Returns a suggestion for timestamps where buffers should be split +to get best controller results. + + Returns the suggested timestamp or %GST_CLOCK_TIME_NONE +if no control-rate was set. + + + + + the object that has controlled properties + + + + + + Sets the properties of the object, according to the #GstControlSources that +(maybe) handle them and for the given timestamp. + +If this function fails, it is most likely the application developers fault. +Most probably the control sources are not setup correctly. + + %TRUE if the controller values could be applied to the object +properties, %FALSE otherwise + + + + + the object that has controlled properties + + + + the time that should be processed + + + + + + Clear the parent of @object, removing the associated reference. +This function decreases the refcount of @object. + +MT safe. Grabs and releases @object's lock. + + + + + + a #GstObject to unparent + + + + + + Decrements the reference count on @object. If reference count hits +zero, destroy @object. This function does not take the lock +on @object as it relies on atomic refcounting. + +The unref method should never be called with the LOCK held since +this might deadlock the dispose function. + + + + + + a #GstObject to unreference + + + + + + + + + The parent of the object. Please note, that when changing the 'parent' +property, we don't emit #GObject::notify and #GstObject::deep-notify +signals due to locking issues. In some cases one can use +#GstBin::element-added or #GstBin::element-removed signals on the parent to +achieve a similar effect. + + + + + + + object LOCK + + + + The name of the object + + + + this object's parent, weak ref + + + + flags for this object + + + + + + + + + + + + + + + + + + The deep notify signal is used to be notified of property changes. It is +typically attached to the toplevel bin to receive notifications from all +the elements contained in that bin. + + + + + + the object that originated the signal + + + + the property that changed + + + + + + + GStreamer base object class. + + parent + + + + separator used by gst_object_get_path_string() + + + + + + + + + + + + + + + + + + + + + + + + + + + + The standard flags that an gstobject may have. + + the object is expected to stay alive even +after gst_deinit() has been called and so should be ignored by leak +detection tools. (Since 1.10) + + + subclasses can add additional flags starting from this flag + + + + Use this flag on GObject properties to signal they can make sense to be. +controlled over time. This hint is used by the GstController. + + + + Use this flag on GObject properties of GstElements to indicate that +they can be changed when the element is in the PAUSED or lower state. +This flag implies GST_PARAM_MUTABLE_READY. + + + + Use this flag on GObject properties of GstElements to indicate that +they can be changed when the element is in the PLAYING or lower state. +This flag implies GST_PARAM_MUTABLE_PAUSED. + + + + Use this flag on GObject properties of GstElements to indicate that +they can be changed when the element is in the READY or lower state. + + + + Bits based on GST_PARAM_USER_SHIFT can be used by 3rd party applications. + + + + The field name in a GstCaps that is used to signal the UUID of the protection +system. + + + + printf format type used to debug GStreamer types. You can use this in +combination with GStreamer's debug logging system as well as the functions +gst_info_vasprintf(), gst_info_strdup_vprintf() and gst_info_strdup_printf() +to pretty-print the following types: #GstCaps, #GstStructure, +#GstCapsFeatures, #GstTagList, #GstDateTime, #GstBuffer, #GstBufferList, +#GstMessage, #GstEvent, #GstQuery, #GstContext, #GstPad, #GstObject. All +#GObject types will be printed as typename plus pointer, and everything +else will simply be printed as pointer address. + +This can only be used on types whose size is >= sizeof(gpointer). + + + + A #GstElement is linked to other elements via "pads", which are extremely +light-weight generic link points. + +Pads have a #GstPadDirection, source pads produce data, sink pads consume +data. + +Pads are typically created from a #GstPadTemplate with +gst_pad_new_from_template() and are then added to a #GstElement. This usually +happens when the element is created but it can also happen dynamically based +on the data that the element is processing or based on the pads that the +application requests. + +Pads without pad templates can be created with gst_pad_new(), +which takes a direction and a name as an argument. If the name is %NULL, +then a guaranteed unique name will be assigned to it. + +A #GstElement creating a pad will typically use the various +gst_pad_set_*_function() calls to register callbacks for events, queries or +dataflow on the pads. + +gst_pad_get_parent() will retrieve the #GstElement that owns the pad. + +After two pads are retrieved from an element by gst_element_get_static_pad(), +the pads can be linked with gst_pad_link(). (For quick links, +you can also use gst_element_link(), which will make the obvious +link for you if it's straightforward.). Pads can be unlinked again with +gst_pad_unlink(). gst_pad_get_peer() can be used to check what the pad is +linked to. + +Before dataflow is possible on the pads, they need to be activated with +gst_pad_set_active(). + +gst_pad_query() and gst_pad_peer_query() can be used to query various +properties of the pad and the stream. + +To send a #GstEvent on a pad, use gst_pad_send_event() and +gst_pad_push_event(). Some events will be sticky on the pad, meaning that +after they pass on the pad they can be queried later with +gst_pad_get_sticky_event() and gst_pad_sticky_events_foreach(). +gst_pad_get_current_caps() and gst_pad_has_current_caps() are convenience +functions to query the current sticky CAPS event on a pad. + +GstElements will use gst_pad_push() and gst_pad_pull_range() to push out +or pull in a buffer. + +The dataflow, events and queries that happen on a pad can be monitored with +probes that can be installed with gst_pad_add_probe(). gst_pad_is_blocked() +can be used to check if a block probe is installed on the pad. +gst_pad_is_blocking() checks if the blocking probe is currently blocking the +pad. gst_pad_remove_probe() is used to remove a previously installed probe +and unblock blocking probes if any. + +Pad have an offset that can be retrieved with gst_pad_get_offset(). This +offset will be applied to the running_time of all data passing over the pad. +gst_pad_set_offset() can be used to change the offset. + +Convenience functions exist to start, pause and stop the task on a pad with +gst_pad_start_task(), gst_pad_pause_task() and gst_pad_stop_task() +respectively. + + Creates a new pad with the given name in the given direction. +If name is %NULL, a guaranteed unique name (across all pads) +will be assigned. +This function makes a copy of the name so you can safely free the name. + + a new #GstPad, or %NULL in +case of an error. + +MT safe. + + + + + the name of the new pad. + + + + the #GstPadDirection of the pad. + + + + + + Creates a new pad with the given name from the given static template. +If name is %NULL, a guaranteed unique name (across all pads) +will be assigned. +This function makes a copy of the name so you can safely free the name. + + a new #GstPad, or %NULL in +case of an error. + + + + + the #GstStaticPadTemplate to use + + + + the name of the pad + + + + + + Creates a new pad with the given name from the given template. +If name is %NULL, a guaranteed unique name (across all pads) +will be assigned. +This function makes a copy of the name so you can safely free the name. + + a new #GstPad, or %NULL in +case of an error. + + + + + the pad template to use + + + + the name of the pad + + + + + + Gets a string representing the given pad-link return. + + a static string with the name of the pad-link return. + + + + + a #GstPadLinkReturn to get the name of. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Activates or deactivates the given pad in @mode via dispatching to the +pad's activatemodefunc. For use from within pad activation functions only. + +If you don't know what this is, you probably don't want to call it. + + %TRUE if the operation was successful. + +MT safe. + + + + + the #GstPad to activate or deactivate. + + + + the requested activation mode + + + + whether or not the pad should be active. + + + + + + Be notified of different states of pads. The provided callback is called for +every state that matches @mask. + +Probes are called in groups: First GST_PAD_PROBE_TYPE_BLOCK probes are +called, then others, then finally GST_PAD_PROBE_TYPE_IDLE. The only +exception here are GST_PAD_PROBE_TYPE_IDLE probes that are called +immediately if the pad is already idle while calling gst_pad_add_probe(). +In each of the groups, probes are called in the order in which they were +added. + + an id or 0 if no probe is pending. The id can be used to remove the +probe with gst_pad_remove_probe(). When using GST_PAD_PROBE_TYPE_IDLE it can +happen that the probe can be run immediately and if the probe returns +GST_PAD_PROBE_REMOVE this functions returns 0. + +MT safe. + + + + + the #GstPad to add the probe to + + + + the probe mask + + + + #GstPadProbeCallback that will be called with notifications of + the pad state + + + + user data passed to the callback + + + + #GDestroyNotify for user_data + + + + + + Checks if the source pad and the sink pad are compatible so they can be +linked. + + %TRUE if the pads can be linked. + + + + + the source #GstPad. + + + + the sink #GstPad. + + + + + + Chain a buffer to @pad. + +The function returns #GST_FLOW_FLUSHING if the pad was flushing. + +If the buffer type is not acceptable for @pad (as negotiated with a +preceding GST_EVENT_CAPS event), this function returns +#GST_FLOW_NOT_NEGOTIATED. + +The function proceeds calling the chain function installed on @pad (see +gst_pad_set_chain_function()) and the return value of that function is +returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no +chain function. + +In all cases, success or failure, the caller loses its reference to @buffer +after calling this function. + + a #GstFlowReturn from the pad. + +MT safe. + + + + + a sink #GstPad, returns GST_FLOW_ERROR if not. + + + + the #GstBuffer to send, return GST_FLOW_ERROR + if not. + + + + + + Chain a bufferlist to @pad. + +The function returns #GST_FLOW_FLUSHING if the pad was flushing. + +If @pad was not negotiated properly with a CAPS event, this function +returns #GST_FLOW_NOT_NEGOTIATED. + +The function proceeds calling the chainlist function installed on @pad (see +gst_pad_set_chain_list_function()) and the return value of that function is +returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no +chainlist function. + +In all cases, success or failure, the caller loses its reference to @list +after calling this function. + +MT safe. + + a #GstFlowReturn from the pad. + + + + + a sink #GstPad, returns GST_FLOW_ERROR if not. + + + + the #GstBufferList to send, return GST_FLOW_ERROR + if not. + + + + + + Check and clear the #GST_PAD_FLAG_NEED_RECONFIGURE flag on @pad and return %TRUE +if the flag was set. + + %TRUE is the GST_PAD_FLAG_NEED_RECONFIGURE flag was set on @pad. + + + + + the #GstPad to check + + + + + + Creates a stream-id for the source #GstPad @pad by combining the +upstream information with the optional @stream_id of the stream +of @pad. @pad must have a parent #GstElement and which must have zero +or one sinkpad. @stream_id can only be %NULL if the parent element +of @pad has only a single source pad. + +This function generates an unique stream-id by getting the upstream +stream-start event stream ID and appending @stream_id to it. If the +element has no sinkpad it will generate an upstream stream-id by +doing an URI query on the element and in the worst case just uses +a random number. Source elements that don't implement the URI +handler interface should ideally generate a unique, deterministic +stream-id manually instead. + +Since stream IDs are sorted alphabetically, any numbers in the +stream ID should be printed with a fixed number of characters, +preceded by 0's, such as by using the format \%03u instead of \%u. + + A stream-id for @pad. g_free() after usage. + + + + + A source #GstPad + + + + Parent #GstElement of @pad + + + + The stream-id + + + + + + Creates a stream-id for the source #GstPad @pad by combining the +upstream information with the optional @stream_id of the stream +of @pad. @pad must have a parent #GstElement and which must have zero +or one sinkpad. @stream_id can only be %NULL if the parent element +of @pad has only a single source pad. + +This function generates an unique stream-id by getting the upstream +stream-start event stream ID and appending @stream_id to it. If the +element has no sinkpad it will generate an upstream stream-id by +doing an URI query on the element and in the worst case just uses +a random number. Source elements that don't implement the URI +handler interface should ideally generate a unique, deterministic +stream-id manually instead. + + A stream-id for @pad. g_free() after usage. + + + + + A source #GstPad + + + + Parent #GstElement of @pad + + + + The stream-id + + + + parameters for the @stream_id format string + + + + + + Creates a stream-id for the source #GstPad @pad by combining the +upstream information with the optional @stream_id of the stream +of @pad. @pad must have a parent #GstElement and which must have zero +or one sinkpad. @stream_id can only be %NULL if the parent element +of @pad has only a single source pad. + +This function generates an unique stream-id by getting the upstream +stream-start event stream ID and appending @stream_id to it. If the +element has no sinkpad it will generate an upstream stream-id by +doing an URI query on the element and in the worst case just uses +a random number. Source elements that don't implement the URI +handler interface should ideally generate a unique, deterministic +stream-id manually instead. + + A stream-id for @pad. g_free() after usage. + + + + + A source #GstPad + + + + Parent #GstElement of @pad + + + + The stream-id + + + + parameters for the @stream_id format string + + + + + + Invokes the default event handler for the given pad. + +The EOS event will pause the task associated with @pad before it is forwarded +to all internally linked pads, + +The event is sent to all pads internally linked to @pad. This function +takes ownership of @event. + + %TRUE if the event was sent successfully. + + + + + a #GstPad to call the default event handler on. + + + + the parent of @pad or %NULL + + + + the #GstEvent to handle. + + + + + + Calls @forward for all internally linked pads of @pad. This function deals with +dynamically changing internal pads and will make sure that the @forward +function is only called once for each pad. + +When @forward returns %TRUE, no further pads will be processed. + + %TRUE if one of the dispatcher functions returned %TRUE. + + + + + a #GstPad + + + + a #GstPadForwardFunction + + + + user data passed to @forward + + + + + + Gets the capabilities of the allowed media types that can flow through +@pad and its peer. + +The allowed capabilities is calculated as the intersection of the results of +calling gst_pad_query_caps() on @pad and its peer. The caller owns a reference +on the resulting caps. + + the allowed #GstCaps of the + pad link. Unref the caps when you no longer need it. This + function returns %NULL when @pad has no peer. + +MT safe. + + + + + a #GstPad. + + + + + + Gets the capabilities currently configured on @pad with the last +#GST_EVENT_CAPS event. + + the current caps of the pad with +incremented ref-count or %NULL when pad has no caps. Unref after usage. + + + + + a #GstPad to get the current capabilities of. + + + + + + Gets the direction of the pad. The direction of the pad is +decided at construction time so this function does not take +the LOCK. + + the #GstPadDirection of the pad. + +MT safe. + + + + + a #GstPad to get the direction of. + + + + + + Gets the private data of a pad. +No locking is performed in this function. + + a #gpointer to the private data. + + + + + the #GstPad to get the private data of. + + + + + + Gets the #GstFlowReturn return from the last data passed by this pad. + + + + + + the #GstPad + + + + + + Get the offset applied to the running time of @pad. @pad has to be a source +pad. + + the offset. + + + + + a #GstPad + + + + + + Gets the template for @pad. + + the #GstPadTemplate from which + this pad was instantiated, or %NULL if this pad has no + template. Unref after usage. + + + + + a #GstPad. + + + + + + Gets the capabilities for @pad's template. + + the #GstCaps of this pad template. +Unref after usage. + + + + + a #GstPad to get the template capabilities from. + + + + + + Gets the parent of @pad, cast to a #GstElement. If a @pad has no parent or +its parent is not an element, return %NULL. + + the parent of the pad. The +caller has a reference on the parent, so unref when you're finished +with it. + +MT safe. + + + + + a pad + + + + + + Gets the peer of @pad. This function refs the peer pad so +you need to unref it after use. + + the peer #GstPad. Unref after usage. + +MT safe. + + + + + a #GstPad to get the peer of. + + + + + + When @pad is flushing this function returns #GST_FLOW_FLUSHING +immediately and @buffer is %NULL. + +Calls the getrange function of @pad, see #GstPadGetRangeFunction for a +description of a getrange function. If @pad has no getrange function +installed (see gst_pad_set_getrange_function()) this function returns +#GST_FLOW_NOT_SUPPORTED. + +If @buffer points to a variable holding %NULL, a valid new #GstBuffer will be +placed in @buffer when this function returns #GST_FLOW_OK. The new buffer +must be freed with gst_buffer_unref() after usage. + +When @buffer points to a variable that points to a valid #GstBuffer, the +buffer will be filled with the result data when this function returns +#GST_FLOW_OK. If the provided buffer is larger than @size, only +@size bytes will be filled in the result buffer and its size will be updated +accordingly. + +Note that less than @size bytes can be returned in @buffer when, for example, +an EOS condition is near or when @buffer is not large enough to hold @size +bytes. The caller should check the result buffer size to get the result size. + +When this function returns any other result value than #GST_FLOW_OK, @buffer +will be unchanged. + +This is a lowlevel function. Usually gst_pad_pull_range() is used. + + a #GstFlowReturn from the pad. + +MT safe. + + + + + a src #GstPad, returns #GST_FLOW_ERROR if not. + + + + The start offset of the buffer + + + + The length of the buffer + + + + a pointer to hold the #GstBuffer, + returns #GST_FLOW_ERROR if %NULL. + + + + + + Returns a new reference of the sticky event of type @event_type +from the event. + + a #GstEvent of type +@event_type or %NULL when no event of @event_type was on +@pad. Unref after usage. + + + + + the #GstPad to get the event from. + + + + the #GstEventType that should be retrieved. + + + + the index of the event + + + + + + Returns the current #GstStream for the @pad, or %NULL if none has been +set yet, i.e. the pad has not received a stream-start event yet. + +This is a convenience wrapper around gst_pad_get_sticky_event() and +gst_event_parse_stream(). + + the current #GstStream for @pad, or %NULL. + unref the returned stream when no longer needed. + + + + + A source #GstPad + + + + + + Returns the current stream-id for the @pad, or %NULL if none has been +set yet, i.e. the pad has not received a stream-start event yet. + +This is a convenience wrapper around gst_pad_get_sticky_event() and +gst_event_parse_stream_start(). + +The returned stream-id string should be treated as an opaque string, its +contents should not be interpreted. + + a newly-allocated copy of the stream-id for + @pad, or %NULL. g_free() the returned string when no longer + needed. + + + + + A source #GstPad + + + + + + Get @pad task state. If no task is currently +set, #GST_TASK_STOPPED is returned. + + The current state of @pad's task. + + + + + the #GstPad to get task state from + + + + + + Check if @pad has caps set on it with a #GST_EVENT_CAPS event. + + %TRUE when @pad has caps associated with it. + + + + + a #GstPad to check + + + + + + Query if a pad is active + + %TRUE if the pad is active. + +MT safe. + + + + + the #GstPad to query + + + + + + Checks if the pad is blocked or not. This function returns the +last requested state of the pad. It is not certain that the pad +is actually blocking at this point (see gst_pad_is_blocking()). + + %TRUE if the pad is blocked. + +MT safe. + + + + + the #GstPad to query + + + + + + Checks if the pad is blocking or not. This is a guaranteed state +of whether the pad is actually blocking on a #GstBuffer or a #GstEvent. + + %TRUE if the pad is blocking. + +MT safe. + + + + + the #GstPad to query + + + + + + Checks if a @pad is linked to another pad or not. + + %TRUE if the pad is linked, %FALSE otherwise. + +MT safe. + + + + + pad to check + + + + + + Gets an iterator for the pads to which the given pad is linked to inside +of the parent element. + +Each #GstPad element yielded by the iterator will have its refcount increased, +so unref after use. + +Free-function: gst_iterator_free + + a new #GstIterator of #GstPad + or %NULL when the pad does not have an iterator function + configured. Use gst_iterator_free() after usage. + + + + + the GstPad to get the internal links of. + + + + + + Iterate the list of pads to which the given pad is linked to inside of +the parent element. +This is the default handler, and thus returns an iterator of all of the +pads inside the parent element with opposite direction. + +The caller must free this iterator after use with gst_iterator_free(). + + a #GstIterator of #GstPad, or %NULL if @pad +has no parent. Unref each returned pad with gst_object_unref(). + + + + + the #GstPad to get the internal links of. + + + + the parent of @pad or %NULL + + + + + + Links the source pad and the sink pad. + + A result code indicating if the connection worked or + what went wrong. + +MT Safe. + + + + + the source #GstPad to link. + + + + the sink #GstPad to link. + + + + + + Links the source pad and the sink pad. + +This variant of #gst_pad_link provides a more granular control on the +checks being done when linking. While providing some considerable speedups +the caller of this method must be aware that wrong usage of those flags +can cause severe issues. Refer to the documentation of #GstPadLinkCheck +for more information. + +MT Safe. + + A result code indicating if the connection worked or + what went wrong. + + + + + the source #GstPad to link. + + + + the sink #GstPad to link. + + + + the checks to validate when linking + + + + + + Links @src to @sink, creating any #GstGhostPad's in between as necessary. + +This is a convenience function to save having to create and add intermediate +#GstGhostPad's as required for linking across #GstBin boundaries. + +If @src or @sink pads don't have parent elements or do not share a common +ancestor, the link will fail. + + whether the link succeeded. + + + + + a #GstPad + + + + a #GstPad + + + + + + Links @src to @sink, creating any #GstGhostPad's in between as necessary. + +This is a convenience function to save having to create and add intermediate +#GstGhostPad's as required for linking across #GstBin boundaries. + +If @src or @sink pads don't have parent elements or do not share a common +ancestor, the link will fail. + +Calling gst_pad_link_maybe_ghosting_full() with +@flags == %GST_PAD_LINK_CHECK_DEFAULT is the recommended way of linking +pads with safety checks applied. + + whether the link succeeded. + + + + + a #GstPad + + + + a #GstPad + + + + some #GstPadLinkCheck flags + + + + + + Mark a pad for needing reconfiguration. The next call to +gst_pad_check_reconfigure() will return %TRUE after this call. + + + + + + the #GstPad to mark + + + + + + Check the #GST_PAD_FLAG_NEED_RECONFIGURE flag on @pad and return %TRUE +if the flag was set. + + %TRUE is the GST_PAD_FLAG_NEED_RECONFIGURE flag is set on @pad. + + + + + the #GstPad to check + + + + + + Pause the task of @pad. This function will also wait until the +function executed by the task is finished if this function is not +called from the task function. + + a %TRUE if the task could be paused or %FALSE when the pad +has no task. + + + + + the #GstPad to pause the task of + + + + + + Performs gst_pad_query() on the peer of @pad. + +The caller is responsible for both the allocation and deallocation of +the query structure. + + %TRUE if the query could be performed. This function returns %FALSE +if @pad has no peer. + + + + + a #GstPad to invoke the peer query on. + + + + the #GstQuery to perform. + + + + + + Check if the peer of @pad accepts @caps. If @pad has no peer, this function +returns %TRUE. + + %TRUE if the peer of @pad can accept the caps or @pad has no peer. + + + + + a #GstPad to check the peer of + + + + a #GstCaps to check on the pad + + + + + + Gets the capabilities of the peer connected to this pad. Similar to +gst_pad_query_caps(). + +When called on srcpads @filter contains the caps that +upstream could produce in the order preferred by upstream. When +called on sinkpads @filter contains the caps accepted by +downstream in the preferred order. @filter might be %NULL but +if it is not %NULL the returned caps will be a subset of @filter. + + the caps of the peer pad with incremented +ref-count. When there is no peer pad, this function returns @filter or, +when @filter is %NULL, ANY caps. + + + + + a #GstPad to get the capabilities of. + + + + a #GstCaps filter, or %NULL. + + + + + + Queries the peer pad of a given sink pad to convert @src_val in @src_format +to @dest_format. + + %TRUE if the query could be performed. + + + + + a #GstPad, on whose peer pad to invoke the convert query on. + Must be a sink pad. + + + + a #GstFormat to convert from. + + + + a value to convert. + + + + the #GstFormat to convert to. + + + + a pointer to the result. + + + + + + Queries the peer pad of a given sink pad for the total stream duration. + + %TRUE if the query could be performed. + + + + + a #GstPad on whose peer pad to invoke the duration query on. + Must be a sink pad. + + + + the #GstFormat requested + + + + a location in which to store the total + duration, or %NULL. + + + + + + Queries the peer of a given sink pad for the stream position. + + %TRUE if the query could be performed. + + + + + a #GstPad on whose peer to invoke the position query on. + Must be a sink pad. + + + + the #GstFormat requested + + + + a location in which to store the current + position, or %NULL. + + + + + + Checks if all internally linked pads of @pad accepts the caps in @query and +returns the intersection of the results. + +This function is useful as a default accept caps query function for an element +that can handle any stream format, but requires caps that are acceptable for +all opposite pads. + + %TRUE if @query could be executed + + + + + a #GstPad to proxy. + + + + an ACCEPT_CAPS #GstQuery. + + + + + + Calls gst_pad_query_caps() for all internally linked pads of @pad and returns +the intersection of the results. + +This function is useful as a default caps query function for an element +that can handle any stream format, but requires all its pads to have +the same caps. Two such elements are tee and adder. + + %TRUE if @query could be executed + + + + + a #GstPad to proxy. + + + + a CAPS #GstQuery. + + + + + + Pulls a @buffer from the peer pad or fills up a provided buffer. + +This function will first trigger the pad block signal if it was +installed. + +When @pad is not linked #GST_FLOW_NOT_LINKED is returned else this +function returns the result of gst_pad_get_range() on the peer pad. +See gst_pad_get_range() for a list of return values and for the +semantics of the arguments of this function. + +If @buffer points to a variable holding %NULL, a valid new #GstBuffer will be +placed in @buffer when this function returns #GST_FLOW_OK. The new buffer +must be freed with gst_buffer_unref() after usage. When this function +returns any other result value, @buffer will still point to %NULL. + +When @buffer points to a variable that points to a valid #GstBuffer, the +buffer will be filled with the result data when this function returns +#GST_FLOW_OK. When this function returns any other result value, +@buffer will be unchanged. If the provided buffer is larger than @size, only +@size bytes will be filled in the result buffer and its size will be updated +accordingly. + +Note that less than @size bytes can be returned in @buffer when, for example, +an EOS condition is near or when @buffer is not large enough to hold @size +bytes. The caller should check the result buffer size to get the result size. + + a #GstFlowReturn from the peer pad. + +MT safe. + + + + + a sink #GstPad, returns GST_FLOW_ERROR if not. + + + + The start offset of the buffer + + + + The length of the buffer + + + + a pointer to hold the #GstBuffer, returns + GST_FLOW_ERROR if %NULL. + + + + + + Pushes a buffer to the peer of @pad. + +This function will call installed block probes before triggering any +installed data probes. + +The function proceeds calling gst_pad_chain() on the peer pad and returns +the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will +be returned. + +In all cases, success or failure, the caller loses its reference to @buffer +after calling this function. + + a #GstFlowReturn from the peer pad. + +MT safe. + + + + + a source #GstPad, returns #GST_FLOW_ERROR if not. + + + + the #GstBuffer to push returns GST_FLOW_ERROR + if not. + + + + + + Sends the event to the peer of the given pad. This function is +mainly used by elements to send events to their peer +elements. + +This function takes ownership of the provided event so you should +gst_event_ref() it if you want to reuse the event after this call. + + %TRUE if the event was handled. + +MT safe. + + + + + a #GstPad to push the event to. + + + + the #GstEvent to send to the pad. + + + + + + Pushes a buffer list to the peer of @pad. + +This function will call installed block probes before triggering any +installed data probes. + +The function proceeds calling the chain function on the peer pad and returns +the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will +be returned. If the peer pad does not have any installed chainlist function +every group buffer of the list will be merged into a normal #GstBuffer and +chained via gst_pad_chain(). + +In all cases, success or failure, the caller loses its reference to @list +after calling this function. + + a #GstFlowReturn from the peer pad. + +MT safe. + + + + + a source #GstPad, returns #GST_FLOW_ERROR if not. + + + + the #GstBufferList to push returns GST_FLOW_ERROR + if not. + + + + + + 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 +the pad belongs to is responsible for filling the query with an appropriate +response, which should then be parsed with a type-specific query parsing +function. + +Again, the caller is responsible for both the allocation and deallocation of +the query structure. + +Please also note that some queries might need a running pipeline to work. + + %TRUE if the query could be performed. + + + + + a #GstPad to invoke the default query on. + + + + the #GstQuery to perform. + + + + + + Check if the given pad accepts the caps. + + %TRUE if the pad can accept the caps. + + + + + a #GstPad to check + + + + a #GstCaps to check on the pad + + + + + + Gets the capabilities this pad can produce or consume. +Note that this method doesn't necessarily return the caps set by sending a +gst_event_new_caps() - use gst_pad_get_current_caps() for that instead. +gst_pad_query_caps returns all possible caps a pad can operate with, using +the pad's CAPS query function, If the query fails, this function will return +@filter, if not %NULL, otherwise ANY. + +When called on sinkpads @filter contains the caps that +upstream could produce in the order preferred by upstream. When +called on srcpads @filter contains the caps accepted by +downstream in the preferred order. @filter might be %NULL but +if it is not %NULL the returned caps will be a subset of @filter. + +Note that this function does not return writable #GstCaps, use +gst_caps_make_writable() before modifying the caps. + + the caps of the pad with incremented ref-count. + + + + + a #GstPad to get the capabilities of. + + + + suggested #GstCaps, or %NULL + + + + + + Queries a pad to convert @src_val in @src_format to @dest_format. + + %TRUE if the query could be performed. + + + + + a #GstPad to invoke the convert query on. + + + + a #GstFormat to convert from. + + + + a value to convert. + + + + the #GstFormat to convert to. + + + + a pointer to the result. + + + + + + Invokes the default query handler for the given pad. +The query is sent to all pads internally linked to @pad. Note that +if there are many possible sink pads that are internally linked to +@pad, only one will be sent the query. +Multi-sinkpad elements should implement custom query handlers. + + %TRUE if the query was performed successfully. + + + + + a #GstPad to call the default query handler on. + + + + the parent of @pad or %NULL + + + + the #GstQuery to handle. + + + + + + Queries a pad for the total stream duration. + + %TRUE if the query could be performed. + + + + + a #GstPad to invoke the duration query on. + + + + the #GstFormat requested + + + + a location in which to store the total + duration, or %NULL. + + + + + + Queries a pad for the stream position. + + %TRUE if the query could be performed. + + + + + a #GstPad to invoke the position query on. + + + + the #GstFormat requested + + + + A location in which to store the current position, or %NULL. + + + + + + Remove the probe with @id from @pad. + +MT safe. + + + + + + the #GstPad with the probe + + + + the probe id to remove + + + + + + Sends the event to the pad. This function can be used +by applications to send events in the pipeline. + +If @pad is a source pad, @event should be an upstream event. If @pad is a +sink pad, @event should be a downstream event. For example, you would not +send a #GST_EVENT_EOS on a src pad; EOS events only propagate downstream. +Furthermore, some downstream events have to be serialized with data flow, +like EOS, while some can travel out-of-band, like #GST_EVENT_FLUSH_START. If +the event needs to be serialized with data flow, this function will take the +pad's stream lock while calling its event function. + +To find out whether an event type is upstream, downstream, or downstream and +serialized, see #GstEventTypeFlags, gst_event_type_get_flags(), +#GST_EVENT_IS_UPSTREAM, #GST_EVENT_IS_DOWNSTREAM, and +#GST_EVENT_IS_SERIALIZED. Note that in practice that an application or +plugin doesn't need to bother itself with this information; the core handles +all necessary locks and checks. + +This function takes ownership of the provided event so you should +gst_event_ref() it if you want to reuse the event after this call. + + %TRUE if the event was handled. + + + + + a #GstPad to send the event to. + + + + the #GstEvent to send to the pad. + + + + + + Sets the given activate function for @pad. The activate function will +dispatch to gst_pad_activate_mode() to perform the actual activation. +Only makes sense to set on sink pads. + +Call this function if your sink pad can start a pull-based task. + + + + + + a #GstPad. + + + + the #GstPadActivateFunction to set. + + + + user_data passed to @notify + + + + notify called when @activate will not be used anymore. + + + + + + Sets the given activate_mode function for the pad. An activate_mode function +prepares the element for data passing. + + + + + + a #GstPad. + + + + the #GstPadActivateModeFunction to set. + + + + user_data passed to @notify + + + + notify called when @activatemode will not be used anymore. + + + + + + Activates or deactivates the given pad. +Normally called from within core state change functions. + +If @active, makes sure the pad is active. If it is already active, either in +push or pull mode, just return. Otherwise dispatches to the pad's activate +function to perform the actual activation. + +If not @active, calls gst_pad_activate_mode() with the pad's current mode +and a %FALSE argument. + + %TRUE if the operation was successful. + +MT safe. + + + + + the #GstPad to activate or deactivate. + + + + whether or not the pad should be active. + + + + + + Sets the given chain function for the pad. The chain function is called to +process a #GstBuffer input buffer. see #GstPadChainFunction for more details. + + + + + + a sink #GstPad. + + + + the #GstPadChainFunction to set. + + + + user_data passed to @notify + + + + notify called when @chain will not be used anymore. + + + + + + Sets the given chain list function for the pad. The chainlist function is +called to process a #GstBufferList input buffer list. See +#GstPadChainListFunction for more details. + + + + + + a sink #GstPad. + + + + the #GstPadChainListFunction to set. + + + + user_data passed to @notify + + + + notify called when @chainlist will not be used anymore. + + + + + + Set the given private data gpointer on the pad. +This function can only be used by the element that owns the pad. +No locking is performed in this function. + + + + + + the #GstPad to set the private data of. + + + + The private data to attach to the pad. + + + + + + Sets the given event handler for the pad. + + + + + + a #GstPad of either direction. + + + + the #GstPadEventFullFunction to set. + + + + user_data passed to @notify + + + + notify called when @event will not be used anymore. + + + + + + Sets the given event handler for the pad. + + + + + + a #GstPad of either direction. + + + + the #GstPadEventFunction to set. + + + + user_data passed to @notify + + + + notify called when @event will not be used anymore. + + + + + + Sets the given getrange function for the pad. The getrange function is +called to produce a new #GstBuffer to start the processing pipeline. see +#GstPadGetRangeFunction for a description of the getrange function. + + + + + + a source #GstPad. + + + + the #GstPadGetRangeFunction to set. + + + + user_data passed to @notify + + + + notify called when @get will not be used anymore. + + + + + + Sets the given internal link iterator function for the pad. + + + + + + a #GstPad of either direction. + + + + the #GstPadIterIntLinkFunction to set. + + + + user_data passed to @notify + + + + notify called when @iterintlink will not be used anymore. + + + + + + Sets the given link function for the pad. It will be called when +the pad is linked with another pad. + +The return value #GST_PAD_LINK_OK should be used when the connection can be +made. + +The return value #GST_PAD_LINK_REFUSED should be used when the connection +cannot be made for some reason. + +If @link is installed on a source pad, it should call the #GstPadLinkFunction +of the peer sink pad, if present. + + + + + + a #GstPad. + + + + the #GstPadLinkFunction to set. + + + + user_data passed to @notify + + + + notify called when @link will not be used anymore. + + + + + + Set the offset that will be applied to the running time of @pad. + + + + + + a #GstPad + + + + the offset + + + + + + Set the given query function for the pad. + + + + + + a #GstPad of either direction. + + + + the #GstPadQueryFunction to set. + + + + user_data passed to @notify + + + + notify called when @query will not be used anymore. + + + + + + Sets the given unlink function for the pad. It will be called +when the pad is unlinked. + + + + + + a #GstPad. + + + + the #GstPadUnlinkFunction to set. + + + + user_data passed to @notify + + + + notify called when @unlink will not be used anymore. + + + + + + Starts a task that repeatedly calls @func with @user_data. This function +is mostly used in pad activation functions to start the dataflow. +The #GST_PAD_STREAM_LOCK of @pad will automatically be acquired +before @func is called. + + a %TRUE if the task could be started. + + + + + the #GstPad to start the task of + + + + the task function to call + + + + user data passed to the task function + + + + called when @user_data is no longer referenced + + + + + + Iterates all sticky events on @pad and calls @foreach_func for every +event. If @foreach_func returns %FALSE the iteration is immediately stopped. + + + + + + the #GstPad that should be used for iteration. + + + + the #GstPadStickyEventsForeachFunction that + should be called for every event. + + + + the optional user data. + + + + + + Stop the task of @pad. This function will also make sure that the +function executed by the task will effectively stop if not called +from the GstTaskFunction. + +This function will deadlock if called from the GstTaskFunction of +the task. Use gst_task_pause() instead. + +Regardless of whether the pad has a task, the stream lock is acquired and +released so as to ensure that streaming through this pad has finished. + + a %TRUE if the task could be stopped or %FALSE on error. + + + + + the #GstPad to stop the task of + + + + + + Store the sticky @event on @pad + + #GST_FLOW_OK on success, #GST_FLOW_FLUSHING when the pad +was flushing or #GST_FLOW_EOS when the pad was EOS. + + + + + a #GstPad + + + + a #GstEvent + + + + + + Unlinks the source pad from the sink pad. Will emit the #GstPad::unlinked +signal on both pads. + + %TRUE if the pads were unlinked. This function returns %FALSE if +the pads were not linked together. + +MT safe. + + + + + the source #GstPad to unlink. + + + + the sink #GstPad to unlink. + + + + + + A helper function you can use that sets the FIXED_CAPS flag +This way the default CAPS query will always return the negotiated caps +or in case the pad is not negotiated, the padtemplate caps. + +The negotiated caps are the caps of the last CAPS event that passed on the +pad. Use this function on a pad that, once it negotiated to a CAPS, cannot +be renegotiated to something else. + + + + + + the pad to use + + + + + + + + + + + + The offset that will be applied to the running time of the pad. + + + + + + + + + + private data owned by the parent element + + + + padtemplate for this pad + + + + the direction of the pad, cannot change after creating + the pad. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Signals that a pad has been linked to the peer pad. + + + + + + the peer pad that has been connected + + + + + + Signals that a pad has been unlinked from the peer pad. + + + + + + the peer pad that has been disconnected + + + + + + + This function is called when the pad is activated during the element +READY to PAUSED state change. By default this function will call the +activate function that puts the pad in push mode but elements can +override this function to activate the pad in pull mode if they wish. + + %TRUE if the pad could be activated. + + + + + a #GstPad + + + + the parent of @pad + + + + + + The prototype of the push and pull activate functions. + + %TRUE if the pad could be activated or deactivated. + + + + + a #GstPad + + + + the parent of @pad + + + + the requested activation mode of @pad + + + + activate or deactivate the pad. + + + + + + A function that will be called on sinkpads when chaining buffers. +The function typically processes the data contained in the buffer and +either consumes the data or passes it on to the internally linked pad(s). + +The implementer of this function receives a refcount to @buffer and should +gst_buffer_unref() when the buffer is no longer needed. + +When a chain function detects an error in the data stream, it must post an +error on the bus and return an appropriate #GstFlowReturn value. + + #GST_FLOW_OK for success + + + + + the sink #GstPad that performed the chain. + + + + the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT + flag is set, @parent is guaranteed to be not-%NULL and remain valid + during the execution of this function. + + + + the #GstBuffer that is chained, not %NULL. + + + + + + A function that will be called on sinkpads when chaining buffer lists. +The function typically processes the data contained in the buffer list and +either consumes the data or passes it on to the internally linked pad(s). + +The implementer of this function receives a refcount to @list and +should gst_buffer_list_unref() when the list is no longer needed. + +When a chainlist function detects an error in the data stream, it must +post an error on the bus and return an appropriate #GstFlowReturn value. + + #GST_FLOW_OK for success + + + + + the sink #GstPad that performed the chain. + + + + the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT + flag is set, @parent is guaranteed to be not-%NULL and remain valid + during the execution of this function. + + + + the #GstBufferList that is chained, not %NULL. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The direction of a pad. + + direction is unknown. + + + the pad is a source pad. + + + the pad is a sink pad. + + + + Function signature to handle an event for the pad. + +This variant is for specific elements that will take into account the +last downstream flow return (from a pad push), in which case they can +return it. + + %GST_FLOW_OK if the event was handled properly, or any other +#GstFlowReturn dependent on downstream state. + + + + + the #GstPad to handle the event. + + + + the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT + flag is set, @parent is guaranteed to be not-%NULL and remain valid + during the execution of this function. + + + + the #GstEvent to handle. + + + + + + Function signature to handle an event for the pad. + + %TRUE if the pad could handle the event. + + + + + the #GstPad to handle the event. + + + + the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT + flag is set, @parent is guaranteed to be not-%NULL and remain valid + during the execution of this function. + + + + the #GstEvent to handle. + + + + + + Pad state flags + + is dataflow on a pad blocked + + + is pad flushing + + + is pad in EOS state + + + is pad currently blocking on a buffer or event + + + ensure that there is a parent object before calling + into the pad callbacks. + + + the pad should be reconfigured/renegotiated. + The flag has to be unset manually after + reconfiguration happened. + + + the pad has pending events + + + the pad is using fixed caps. This means that + once the caps are set on the pad, the default caps query function + will only return those caps. + + + the default event and query handler will forward + all events and queries to the internally linked pads + instead of discarding them. + + + the default query handler will forward + allocation queries to the internally linked pads + instead of discarding them. + + + the default query handler will forward + scheduling queries to the internally linked pads + instead of discarding them. + + + the default accept-caps handler will check + it the caps intersect the query-caps result instead + of checking for a subset. This is interesting for + parsers that can accept incompletely specified caps. + + + the default accept-caps handler will use + the template pad caps instead of query caps to + compare with the accept caps. Use this in combination + with %GST_PAD_FLAG_ACCEPT_INTERSECT. (Since 1.6) + + + offset to define more flags + + + + A forward function is called for all internally linked pads, see +gst_pad_forward(). + + %TRUE if the dispatching procedure has to be stopped. + + + + + the #GstPad that is forwarded. + + + + the gpointer to optional user data. + + + + + + This function will be called on source pads when a peer element +request a buffer at the specified @offset and @length. If this function +returns #GST_FLOW_OK, the result buffer will be stored in @buffer. The +contents of @buffer is invalid for any other return value. + +This function is installed on a source pad with +gst_pad_set_getrange_function() and can only be called on source pads after +they are successfully activated with gst_pad_activate_mode() with the +#GST_PAD_MODE_PULL. + +@offset and @length are always given in byte units. @offset must normally be a value +between 0 and the length in bytes of the data available on @pad. The +length (duration in bytes) can be retrieved with a #GST_QUERY_DURATION or with a +#GST_QUERY_SEEKING. + +Any @offset larger or equal than the length will make the function return +#GST_FLOW_EOS, which corresponds to EOS. In this case @buffer does not +contain a valid buffer. + +The buffer size of @buffer will only be smaller than @length when @offset is +near the end of the stream. In all other cases, the size of @buffer must be +exactly the requested size. + +It is allowed to call this function with a 0 @length and valid @offset, in +which case @buffer will contain a 0-sized buffer and the function returns +#GST_FLOW_OK. + +When this function is called with a -1 @offset, the sequentially next buffer +of length @length in the stream is returned. + +When this function is called with a -1 @length, a buffer with a default +optimal length is returned in @buffer. The length might depend on the value +of @offset. + + #GST_FLOW_OK for success and a valid buffer in @buffer. Any other +return value leaves @buffer undefined. + + + + + the src #GstPad to perform the getrange on. + + + + the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT + flag is set, @parent is guaranteed to be not-%NULL and remain valid + during the execution of this function. + + + + the offset of the range + + + + the length of the range + + + + a memory location to hold the result buffer, cannot be %NULL. + + + + + + The signature of the internal pad link iterator function. + + a new #GstIterator that will iterate over all pads that are +linked to the given pad on the inside of the parent element. + +the caller must call gst_iterator_free() after usage. + + + + + The #GstPad to query. + + + + the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT + flag is set, @parent is guaranteed to be not-%NULL and remain valid + during the execution of this function. + + + + + + The amount of checking to be done when linking pads. @GST_PAD_LINK_CHECK_CAPS +and @GST_PAD_LINK_CHECK_TEMPLATE_CAPS are mutually exclusive. If both are +specified, expensive but safe @GST_PAD_LINK_CHECK_CAPS are performed. + +> Only disable some of the checks if you are 100% certain you know the link +> will not fail because of hierarchy/caps compatibility failures. If uncertain, +> use the default checks (%GST_PAD_LINK_CHECK_DEFAULT) or the regular methods +> for linking the pads. + + Don't check hierarchy or caps compatibility. + + + Check the pads have same parents/grandparents. + Could be omitted if it is already known that the two elements that own the + pads are in the same bin. + + + Check if the pads are compatible by using + their template caps. This is much faster than @GST_PAD_LINK_CHECK_CAPS, but + would be unsafe e.g. if one pad has %GST_CAPS_ANY. + + + Check if the pads are compatible by comparing the + caps returned by gst_pad_query_caps(). + + + Disables pushing a reconfigure event when pads are + linked. + + + The default checks done when linking + pads (i.e. the ones used by gst_pad_link()). + + + + Function signature to handle a new link on the pad. + + the result of the link with the specified peer. + + + + + the #GstPad that is linked. + + + + the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT + flag is set, @parent is guaranteed to be not-%NULL and remain valid + during the execution of this function. + + + + the peer #GstPad of the link + + + + + + Result values from gst_pad_link and friends. + + link succeeded + + + pads have no common grandparent + + + pad was already linked + + + pads have wrong direction + + + pads do not have common format + + + pads cannot cooperate in scheduling + + + refused for some reason + + + + The status of a GstPad. After activating a pad, which usually happens when the +parent element goes from READY to PAUSED, the GstPadMode defines if the +pad operates in push or pull mode. + + Pad will not handle dataflow + + + Pad handles dataflow in downstream push mode + + + Pad handles dataflow in upstream pull mode + + + Return the name of a pad mode, for use in debug messages mostly. + + short mnemonic for pad mode @mode + + + + + the pad mode + + + + + + + Indicates when this pad will become available. + + the pad is always available + + + the pad will become available depending on the media stream + + + the pad is only available on request with + gst_element_request_pad(). + + + + + + Callback used by gst_pad_add_probe(). Gets called to notify about the current +blocking type. + +The callback is allowed to modify the data pointer in @info. + + a #GstPadProbeReturn + + + + + the #GstPad that is blocked + + + + #GstPadProbeInfo + + + + the gpointer to optional user data. + + + + + + Info passed in the #GstPadProbeCallback. + + the current probe type + + + + the id of the probe + + + + type specific data, check the @type field to know the + datatype. This field can be %NULL. + + + + offset of pull probe, this field is valid when @type contains + #GST_PAD_PROBE_TYPE_PULL + + + + size of pull probe, this field is valid when @type contains + #GST_PAD_PROBE_TYPE_PULL + + + + + + + + + + + + + + + + + The #GstBuffer from the probe + + + + + a #GstPadProbeInfo + + + + + + + The #GstBufferList from the probe + + + + + a #GstPadProbeInfo + + + + + + + The #GstEvent from the probe + + + + + a #GstPadProbeInfo + + + + + + + The #GstQuery from the probe + + + + + a #GstPadProbeInfo + + + + + + + Different return values for the #GstPadProbeCallback. + + drop data in data probes. For push mode this means that + the data item is not sent downstream. For pull mode, it means that + the data item is not passed upstream. In both cases, no other probes + are called for this item and %GST_FLOW_OK or %TRUE is returned to the + caller. + + + normal probe return value. This leaves the probe in + place, and defers decisions about dropping or passing data to other + probes, if any. If there are no other probes, the default behaviour + for the probe type applies ('block' for blocking probes, + and 'pass' for non-blocking probes). + + + remove this probe. + + + pass the data item in the block probe and block on the + next item. + + + Data has been handled in the probe and will not be + forwarded further. For events and buffers this is the same behaviour as + %GST_PAD_PROBE_DROP (except that in this case you need to unref the buffer + or event yourself). For queries it will also return %TRUE to the caller. + The probe can also modify the #GstFlowReturn value by using the + #GST_PAD_PROBE_INFO_FLOW_RETURN() accessor. + Note that the resulting query must contain valid entries. + Since: 1.6 + + + + The different probing types that can occur. When either one of +@GST_PAD_PROBE_TYPE_IDLE or @GST_PAD_PROBE_TYPE_BLOCK is used, the probe will be a +blocking probe. + + invalid probe type + + + probe idle pads and block while the callback is called + + + probe and block pads + + + probe buffers + + + probe buffer lists + + + probe downstream events + + + probe upstream events + + + probe flush events. This probe has to be + explicitly enabled and is not included in the + @@GST_PAD_PROBE_TYPE_EVENT_DOWNSTREAM or + @@GST_PAD_PROBE_TYPE_EVENT_UPSTREAM probe types. + + + probe downstream queries + + + probe upstream queries + + + probe push + + + probe pull + + + probe and block at the next opportunity, at data flow or when idle + + + probe downstream data (buffers, buffer lists, and events) + + + probe upstream data (events) + + + probe upstream and downstream data (buffers, buffer lists, and events) + + + probe and block downstream data (buffers, buffer lists, and events) + + + probe and block upstream data (events) + + + probe upstream and downstream events + + + probe upstream and downstream queries + + + probe upstream events and queries and downstream buffers, buffer lists, events and queries + + + probe push and pull + + + + The signature of the query function. + + %TRUE if the query could be performed. + + + + + the #GstPad to query. + + + + the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT + flag is set, @parent is guaranteed to be not-%NULL and remain valid + during the execution of this function. + + + + the #GstQuery object to execute + + + + + + Callback used by gst_pad_sticky_events_foreach(). + +When this function returns %TRUE, the next event will be +returned. When %FALSE is returned, gst_pad_sticky_events_foreach() will return. + +When @event is set to %NULL, the item will be removed from the list of sticky events. +@event can be replaced by assigning a new reference to it. +This function is responsible for unreffing the old event when +removing or modifying. + + %TRUE if the iteration should continue + + + + + the #GstPad. + + + + a sticky #GstEvent. + + + + the #gpointer to optional user data. + + + + + + Padtemplates describe the possible media types a pad or an elementfactory can +handle. This allows for both inspection of handled types before loading the +element plugin as well as identifying pads on elements that are not yet +created (request or sometimes pads). + +Pad and PadTemplates have #GstCaps attached to it to describe the media type +they are capable of dealing with. gst_pad_template_get_caps() or +GST_PAD_TEMPLATE_CAPS() are used to get the caps of a padtemplate. It's not +possible to modify the caps of a padtemplate after creation. + +PadTemplates have a #GstPadPresence property which identifies the lifetime +of the pad and that can be retrieved with GST_PAD_TEMPLATE_PRESENCE(). Also +the direction of the pad can be retrieved from the #GstPadTemplate with +GST_PAD_TEMPLATE_DIRECTION(). + +The GST_PAD_TEMPLATE_NAME_TEMPLATE () is important for GST_PAD_REQUEST pads +because it has to be used as the name in the gst_element_get_request_pad() +call to instantiate a pad from this template. + +Padtemplates can be created with gst_pad_template_new() or with +gst_static_pad_template_get (), which creates a #GstPadTemplate from a +#GstStaticPadTemplate that can be filled with the +convenient GST_STATIC_PAD_TEMPLATE() macro. + +A padtemplate can be used to create a pad (see gst_pad_new_from_template() +or gst_pad_new_from_static_template ()) or to add to an element class +(see gst_element_class_add_static_pad_template ()). + +The following code example shows the code to create a pad from a padtemplate. +|[<!-- language="C" --> + GstStaticPadTemplate my_template = + GST_STATIC_PAD_TEMPLATE ( + "sink", // the name of the pad + GST_PAD_SINK, // the direction of the pad + GST_PAD_ALWAYS, // when this pad will be present + GST_STATIC_CAPS ( // the capabilities of the padtemplate + "audio/x-raw, " + "channels = (int) [ 1, 6 ]" + ) + ); + void + my_method (void) + { + GstPad *pad; + pad = gst_pad_new_from_static_template (&amp;my_template, "sink"); + ... + } +]| + +The following example shows you how to add the padtemplate to an +element class, this is usually done in the class_init of the class: +|[<!-- language="C" --> + static void + my_element_class_init (GstMyElementClass *klass) + { + GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass); + + gst_element_class_add_static_pad_template (gstelement_class, &amp;my_template); + } +]| + + Creates a new pad template with a name according to the given template +and with the given arguments. + + a new #GstPadTemplate. + + + + + the name template. + + + + the #GstPadDirection of the template. + + + + the #GstPadPresence of the pad. + + + + a #GstCaps set for the template. + + + + + + Emit the pad-created signal for this template when created by this pad. + + + + + + a #GstPadTemplate that has been created + + + + the #GstPad that created it + + + + + + Gets the capabilities of the pad template. + + the #GstCaps of the pad template. +Unref after usage. + + + + + a #GstPadTemplate to get capabilities of. + + + + + + Emit the pad-created signal for this template when created by this pad. + + + + + + a #GstPadTemplate that has been created + + + + the #GstPad that created it + + + + + + The capabilities of the pad described by the pad template. + + + + The direction of the pad described by the pad template. + + + + The name template of the pad template. + + + + When the pad described by the pad template will become available. + + + + + + + + + + + + + + + + + + + + + + + + This signal is fired when an element creates a pad from this template. + + + + + + the pad that was created. + + + + + + + + + + + + + + + + + a #GstPadTemplate that has been created + + + + the #GstPad that created it + + + + + + + + + + + + + Flags for the padtemplate + + first flag that can be used by subclasses. + + + + Function signature to handle a unlinking the pad prom its peer. + + + + + + the #GstPad that is linked. + + + + the parent of @pad. If the #GST_PAD_FLAG_NEED_PARENT + flag is set, @parent is guaranteed to be not-%NULL and remain valid + during the execution of this function. + + + + + + + + + + A GParamSpec derived structure that contains the meta data for fractional +properties. + + super class + + + + + + + + A GParamSpec derived structure that contains the meta data for fractional +properties. + + super class + + + + minimal numerator + + + + minimal denominator + + + + maximal numerator + + + + maximal denominator + + + + default numerator + + + + default denominator + + + + + The #GstParentBufferMeta is a #GstMeta which can be attached to a #GstBuffer +to hold a reference to another buffer that is only released when the child +#GstBuffer is released. + +Typically, #GstParentBufferMeta is used when the child buffer is directly +using the #GstMemory of the parent buffer, and wants to prevent the parent +buffer from being returned to a buffer pool until the #GstMemory is available +for re-use. + + the parent #GstMeta structure + + + + the #GstBuffer on which a reference is being held. + + + + Get the global #GstMetaInfo describing the #GstParentBufferMeta meta. + + The #GstMetaInfo + + + + + + Opaque structure. + + Allocates a parse context for use with gst_parse_launch_full() or +gst_parse_launchv_full(). + +Free-function: gst_parse_context_free + + a newly-allocated parse context. Free with + gst_parse_context_free() when no longer needed. + + + + + Frees a parse context previously allocated with gst_parse_context_new(). + + + + + + a #GstParseContext + + + + + + Retrieve missing elements from a previous run of gst_parse_launch_full() +or gst_parse_launchv_full(). Will only return results if an error code +of %GST_PARSE_ERROR_NO_SUCH_ELEMENT was returned. + + a + %NULL-terminated array of element factory name strings of missing + elements. Free with g_strfreev() when no longer needed. + + + + + + + a #GstParseContext + + + + + + + The different parsing errors that can occur. + + A syntax error occurred. + + + The description contained an unknown element + + + An element did not have a specified property + + + There was an error linking two pads. + + + There was an error setting a property + + + An empty bin was specified. + + + An empty description was specified + + + A delayed link did not get resolved. + + + Get the error quark used by the parsing subsystem. + + the quark of the parse errors. + + + + + + Parsing options. + + Do not use any special parsing options. + + + Always return %NULL when an error occurs + (default behaviour is to return partially constructed bins or elements + in some cases) + + + If a bin only has a single element, + just return the element. + + + If more than one toplevel element is described + by the pipeline description string, put them in a #GstBin instead of a + #GstPipeline. (Since 1.10) + + + + A #GstPipeline is a special #GstBin used as the toplevel container for +the filter graph. The #GstPipeline will manage the selection and +distribution of a global #GstClock as well as provide a #GstBus to the +application. + +gst_pipeline_new() is used to create a pipeline. when you are done with +the pipeline, use gst_object_unref() to free its resources including all +added #GstElement objects (if not otherwise referenced). + +Elements are added and removed from the pipeline using the #GstBin +methods like gst_bin_add() and gst_bin_remove() (see #GstBin). + +Before changing the state of the #GstPipeline (see #GstElement) a #GstBus +can be retrieved with gst_pipeline_get_bus(). This bus can then be +used to receive #GstMessage from the elements in the pipeline. + +By default, a #GstPipeline will automatically flush the pending #GstBus +messages when going to the NULL state to ensure that no circular +references exist when no messages are read from the #GstBus. This +behaviour can be changed with gst_pipeline_set_auto_flush_bus(). + +When the #GstPipeline performs the PAUSED to PLAYING state change it will +select a clock for the elements. The clock selection algorithm will by +default select a clock provided by an element that is most upstream +(closest to the source). For live pipelines (ones that return +#GST_STATE_CHANGE_NO_PREROLL from the gst_element_set_state() call) this +will select the clock provided by the live source. For normal pipelines +this will select a clock provided by the sinks (most likely the audio +sink). If no element provides a clock, a default #GstSystemClock is used. + +The clock selection can be controlled with the gst_pipeline_use_clock() +method, which will enforce a given clock on the pipeline. With +gst_pipeline_auto_clock() the default clock selection algorithm can be +restored. + +A #GstPipeline maintains a running time for the elements. The running +time is defined as the difference between the current clock time and +the base time. When the pipeline goes to READY or a flushing seek is +performed on it, the running time is reset to 0. When the pipeline is +set from PLAYING to PAUSED, the current clock time is sampled and used to +configure the base time for the elements when the pipeline is set +to PLAYING again. The effect is that the running time (as the difference +between the clock time and the base time) will count how much time was spent +in the PLAYING state. This default behaviour can be changed with the +gst_element_set_start_time() method. + + + Create a new pipeline with the given name. + + newly created GstPipeline + +MT safe. + + + + + name of new pipeline + + + + + + Let @pipeline select a clock automatically. This is the default +behaviour. + +Use this function if you previous forced a fixed clock with +gst_pipeline_use_clock() and want to restore the default +pipeline clock selection algorithm. + +MT safe. + + + + + + a #GstPipeline + + + + + + Check if @pipeline will automatically flush messages when going to +the NULL state. + + whether the pipeline will automatically flush its bus when +going from READY to NULL state or not. + +MT safe. + + + + + a #GstPipeline + + + + + + Gets the #GstBus of @pipeline. The bus allows applications to receive +#GstMessage packets. + + a #GstBus, unref after usage. + +MT safe. + + + + + a #GstPipeline + + + + + + Gets the current clock used by @pipeline. Users of object +oriented languages should use gst_pipeline_get_pipeline_clock() +to avoid confusion with gst_element_get_clock() which has a different behavior. + +Unlike gst_element_get_clock(), this function will always return a +clock, even if the pipeline is not in the PLAYING state. + + a #GstClock, unref after usage. + + + + + a #GstPipeline + + + + + + Get the configured delay (see gst_pipeline_set_delay()). + + The configured delay. + +MT safe. + + + + + a #GstPipeline + + + + + + Gets the latency that should be configured on the pipeline. See +gst_pipeline_set_latency(). + + Latency to configure on the pipeline or GST_CLOCK_TIME_NONE + + + + + a #GstPipeline + + + + + + Gets the current clock used by @pipeline. + +Unlike gst_element_get_clock(), this function will always return a +clock, even if the pipeline is not in the PLAYING state. + + a #GstClock, unref after usage. + + + + + a #GstPipeline + + + + + + Usually, when a pipeline goes from READY to NULL state, it automatically +flushes all pending messages on the bus, which is done for refcounting +purposes, to break circular references. + +This means that applications that update state using (async) bus messages +(e.g. do certain things when a pipeline goes from PAUSED to READY) might +not get to see messages when the pipeline is shut down, because they might +be flushed before they can be dispatched in the main thread. This behaviour +can be disabled using this function. + +It is important that all messages on the bus are handled when the +automatic flushing is disabled else memory leaks will be introduced. + +MT safe. + + + + + + a #GstPipeline + + + + whether or not to automatically flush the bus when +the pipeline goes from READY to NULL state + + + + + + Set the clock for @pipeline. The clock will be distributed +to all the elements managed by the pipeline. + + %TRUE if the clock could be set on the pipeline. %FALSE if + some element did not accept the clock. + +MT safe. + + + + + a #GstPipeline + + + + the clock to set + + + + + + Set the expected delay needed for all elements to perform the +PAUSED to PLAYING state change. @delay will be added to the +base time of the elements so that they wait an additional @delay +amount of time before starting to process buffers and cannot be +#GST_CLOCK_TIME_NONE. + +This option is used for tuning purposes and should normally not be +used. + +MT safe. + + + + + + a #GstPipeline + + + + the delay + + + + + + Sets the latency that should be configured on the pipeline. Setting +GST_CLOCK_TIME_NONE will restore the default behaviour of using the minimum +latency from the LATENCY query. Setting this is usually not required and +the pipeline will figure out an appropriate latency automatically. + +Setting a too low latency, especially lower than the minimum latency from +the LATENCY query, will most likely cause the pipeline to fail. + + + + + + a #GstPipeline + + + + latency to configure + + + + + + Force @pipeline to use the given @clock. The pipeline will +always use the given clock even if new clock providers are added +to this pipeline. + +If @clock is %NULL all clocking will be disabled which will make +the pipeline run as fast as possible. + +MT safe. + + + + + + a #GstPipeline + + + + the clock to use + + + + + + Whether or not to automatically flush all messages on the +pipeline's bus when going from READY to NULL state. Please see +gst_pipeline_set_auto_flush_bus() for more information on this option. + + + + The expected delay needed for elements to spin up to the +PLAYING state expressed in nanoseconds. +see gst_pipeline_set_delay() for more information on this option. + + + + Latency to configure on the pipeline. See gst_pipeline_set_latency(). + + + + + + + The fixed clock of the pipeline, used when + GST_PIPELINE_FLAG_FIXED_CLOCK is set. + + + + The stream time of the pipeline. A better name for this + property would be the running_time, the total time spent in the + PLAYING state without being flushed. (deprecated, use the start_time + on GstElement). + + + + Extra delay added to base_time to compensate for computing delays + when setting elements to PLAYING. + + + + + + + + + + + + + + + + + + + + + + + Pipeline flags + + this pipeline works with a fixed clock + + + offset to define more flags + + + + + + GStreamer is extensible, so #GstElement instances can be loaded at runtime. +A plugin system can provide one or more of the basic +<application>GStreamer</application> #GstPluginFeature subclasses. + +A plugin should export a symbol <symbol>gst_plugin_desc</symbol> that is a +struct of type #GstPluginDesc. +the plugin loader will check the version of the core library the plugin was +linked against and will create a new #GstPlugin. It will then call the +#GstPluginInitFunc function that was provided in the +<symbol>gst_plugin_desc</symbol>. + +Once you have a handle to a #GstPlugin (e.g. from the #GstRegistry), you +can add any object that subclasses #GstPluginFeature. + +Usually plugins are always automatically loaded so you don't need to call +gst_plugin_load() explicitly to bring it into memory. There are options to +statically link plugins to an app or even use GStreamer without a plugin +repository in which case gst_plugin_load() can be needed to bring the plugin +into memory. + + Unrefs each member of @list, then frees the list. + + + + + + list of #GstPlugin + + + + + + + + Load the named plugin. Refs the plugin. + + a reference to a loaded plugin, or %NULL on error. + + + + + name of plugin to load + + + + + + Loads the given plugin and refs it. Caller needs to unref after use. + + a reference to the existing loaded GstPlugin, a +reference to the newly-loaded GstPlugin, or %NULL if an error occurred. + + + + + the plugin filename to load + + + + + + Registers a static plugin, ie. a plugin which is private to an application +or library and contained within the application or library (as opposed to +being shipped as a separate module file). + +You must make sure that GStreamer has been initialised (with gst_init() or +via gst_init_get_option_group()) before calling this function. + + %TRUE if the plugin was registered correctly, otherwise %FALSE. + + + + + the major version number of the GStreamer core that the + plugin was compiled for, you can just use GST_VERSION_MAJOR here + + + + the minor version number of the GStreamer core that the + plugin was compiled for, you can just use GST_VERSION_MINOR here + + + + a unique name of the plugin (ideally prefixed with an application- or + library-specific namespace prefix in order to avoid name conflicts in + case a similar plugin with the same name ever gets added to GStreamer) + + + + description of the plugin + + + + pointer to the init function of this plugin. + + + + version string of the plugin + + + + effective license of plugin. Must be one of the approved licenses + (see #GstPluginDesc above) or the plugin will not be registered. + + + + source module plugin belongs to + + + + shipped package plugin belongs to + + + + URL to provider of plugin + + + + + + Registers a static plugin, ie. a plugin which is private to an application +or library and contained within the application or library (as opposed to +being shipped as a separate module file) with a #GstPluginInitFullFunc +which allows user data to be passed to the callback function (useful +for bindings). + +You must make sure that GStreamer has been initialised (with gst_init() or +via gst_init_get_option_group()) before calling this function. + + %TRUE if the plugin was registered correctly, otherwise %FALSE. + + + + + the major version number of the GStreamer core that the + plugin was compiled for, you can just use GST_VERSION_MAJOR here + + + + the minor version number of the GStreamer core that the + plugin was compiled for, you can just use GST_VERSION_MINOR here + + + + a unique name of the plugin (ideally prefixed with an application- or + library-specific namespace prefix in order to avoid name conflicts in + case a similar plugin with the same name ever gets added to GStreamer) + + + + description of the plugin + + + + pointer to the init function with user data + of this plugin. + + + + version string of the plugin + + + + effective license of plugin. Must be one of the approved licenses + (see #GstPluginDesc above) or the plugin will not be registered. + + + + source module plugin belongs to + + + + shipped package plugin belongs to + + + + URL to provider of plugin + + + + gpointer to user data + + + + + + Make GStreamer aware of external dependencies which affect the feature +set of this plugin (ie. the elements or typefinders associated with it). + +GStreamer will re-inspect plugins with external dependencies whenever any +of the external dependencies change. This is useful for plugins which wrap +other plugin systems, e.g. a plugin which wraps a plugin-based visualisation +library and makes visualisations available as GStreamer elements, or a +codec loader which exposes elements and/or caps dependent on what external +codec libraries are currently installed. + + + + + + a #GstPlugin + + + + %NULL-terminated array of environment variables affecting the + feature set of the plugin (e.g. an environment variable containing + paths where to look for additional modules/plugins of a library), + or %NULL. Environment variable names may be followed by a path component + which will be added to the content of the environment variable, e.g. + "HOME/.mystuff/plugins". + + + + %NULL-terminated array of directories/paths where dependent files + may be, or %NULL. + + + + %NULL-terminated array of file names (or file name suffixes, + depending on @flags) to be used in combination with the paths from + @paths and/or the paths extracted from the environment variables in + @env_vars, or %NULL. + + + + optional flags, or #GST_PLUGIN_DEPENDENCY_FLAG_NONE + + + + + + Make GStreamer aware of external dependencies which affect the feature +set of this plugin (ie. the elements or typefinders associated with it). + +GStreamer will re-inspect plugins with external dependencies whenever any +of the external dependencies change. This is useful for plugins which wrap +other plugin systems, e.g. a plugin which wraps a plugin-based visualisation +library and makes visualisations available as GStreamer elements, or a +codec loader which exposes elements and/or caps dependent on what external +codec libraries are currently installed. + +Convenience wrapper function for gst_plugin_add_dependency() which +takes simple strings as arguments instead of string arrays, with multiple +arguments separated by predefined delimiters (see above). + + + + + + the #GstPlugin + + + + one or more environment variables (separated by ':', ';' or ','), + or %NULL. Environment variable names may be followed by a path component + which will be added to the content of the environment variable, e.g. + "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH" + + + + one ore more directory paths (separated by ':' or ';' or ','), + or %NULL. Example: "/usr/lib/mystuff/plugins" + + + + one or more file names or file name suffixes (separated by commas), + or %NULL + + + + optional flags, or #GST_PLUGIN_DEPENDENCY_FLAG_NONE + + + + + + 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. + + The cached data as a +#GstStructure or %NULL. + + + + + a plugin + + + + + + Get the long descriptive name of the plugin + + the long name of the plugin + + + + + plugin to get long name of + + + + + + get the filename of the plugin + + the filename of the plugin + + + + + plugin to get the filename of + + + + + + get the license of the plugin + + the license of the plugin + + + + + plugin to get the license of + + + + + + Get the short name of the plugin + + the name of the plugin + + + + + plugin to get the name of + + + + + + get the URL where the plugin comes from + + the origin of the plugin + + + + + plugin to get the origin of + + + + + + get the package the plugin belongs to. + + the package of the plugin + + + + + plugin to get the package of + + + + + + Get the release date (and possibly time) in form of a string, if available. + +For normal GStreamer plugin releases this will usually just be a date in +the form of "YYYY-MM-DD", while pre-releases and builds from git may contain +a time component after the date as well, in which case the string will be +formatted like "YYYY-MM-DDTHH:MMZ" (e.g. "2012-04-30T09:30Z"). + +There may be plugins that do not have a valid release date set on them. + + the date string of the plugin, or %NULL if not +available. + + + + + plugin to get the release date of + + + + + + get the source module the plugin belongs to. + + the source of the plugin + + + + + plugin to get the source of + + + + + + get the version of the plugin + + the version of the plugin + + + + + plugin to get the version of + + + + + + queries if the plugin is loaded into memory + + %TRUE is loaded, %FALSE otherwise + + + + + plugin to query + + + + + + Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is +untouched. The normal use pattern of this function goes like this: + +|[ +GstPlugin *loaded_plugin; +loaded_plugin = gst_plugin_load (plugin); +// presumably, we're no longer interested in the potentially-unloaded plugin +gst_object_unref (plugin); +plugin = loaded_plugin; +]| + + a reference to a loaded plugin, or %NULL on error. + + + + + plugin to load + + + + + + Adds plugin specific data to cache. Passes the ownership of the structure to +the @plugin. + +The cache is flushed every time the registry is rebuilt. + + + + + + a plugin + + + + a structure containing the data to cache + + + + + + + + + Flags used in connection with gst_plugin_add_dependency(). + + no special flags + + + recurse into subdirectories + + + use paths + argument only if none of the environment variables is set + + + interpret + filename argument as filter suffix and check all matching files in + the directory + + + interpret + filename argument as filter prefix and check all matching files in + the directory. Since 1.8. + + + + A plugin should export a variable of this type called plugin_desc. The plugin +loader will use the data provided there to initialize the plugin. + +The @licence parameter must be one of: LGPL, GPL, QPL, GPL/QPL, MPL, +BSD, MIT/X11, Proprietary, unknown. + + the major version number of core that plugin was compiled for + + + + the minor version number of core that plugin was compiled for + + + + a unique name of the plugin + + + + description of plugin + + + + pointer to the init function of this plugin. + + + + version of the plugin + + + + effective license of plugin + + + + source module plugin belongs to + + + + shipped package plugin belongs to + + + + URL to provider of plugin + + + + date time string in ISO 8601 + format (or rather, a subset thereof), or %NULL. Allowed are the + following formats: "YYYY-MM-DD" and "YYY-MM-DDTHH:MMZ" (with + 'T' a separator and 'Z' indicating UTC/Zulu time). This field + should be set via the GST_PACKAGE_RELEASE_DATETIME + preprocessor macro. + + + + + + + + + + The plugin loading errors + + The plugin could not be loaded + + + The plugin has unresolved dependencies + + + The plugin has already be loaded from a different file + + + Get the error quark. + + The error quark used in GError messages + + + + + + This is a base class for anything that can be added to a #GstPlugin. + + Copies the list of features. Caller should call @gst_plugin_feature_list_free +when done with the list. + + a copy of @list, + with each feature's reference count incremented. + + + + + + + list + of #GstPluginFeature + + + + + + + + Debug the plugin feature names in @list. + + + + + + a #GList of + plugin features + + + + + + + + Unrefs each member of @list, then frees the list. + + + + + + list + of #GstPluginFeature + + + + + + + + Compares the two given #GstPluginFeature instances. This function can be +used as a #GCompareFunc when sorting by rank and then by name. + + negative value if the rank of p1 > the rank of p2 or the ranks are +equal but the name of p1 comes before the name of p2; zero if the rank +and names are equal; positive value if the rank of p1 < the rank of p2 or the +ranks are equal but the name of p2 comes before the name of p1 + + + + + a #GstPluginFeature + + + + a #GstPluginFeature + + + + + + Checks whether the given plugin feature is at least + the required version + + %TRUE if the plugin feature has at least + the required version, otherwise %FALSE. + + + + + a feature + + + + minimum required major version + + + + minimum required minor version + + + + minimum required micro version + + + + + + Get the plugin that provides this feature. + + the plugin that provides this + feature, or %NULL. Unref with gst_object_unref() when no + longer needed. + + + + + a feature + + + + + + Get the name of the plugin that provides this feature. + + the name of the plugin that provides this + feature, or %NULL if the feature is not associated with a + plugin. + + + + + a feature + + + + + + Gets the rank of a plugin feature. + + The rank of the feature + + + + + a feature + + + + + + Loads the plugin containing @feature if it's not already loaded. @feature is +unaffected; use the return value instead. + +Normally this function is used like this: +|[<!-- language="C" --> +GstPluginFeature *loaded_feature; + +loaded_feature = gst_plugin_feature_load (feature); +// presumably, we're no longer interested in the potentially-unloaded feature +gst_object_unref (feature); +feature = loaded_feature; +]| + + a reference to the loaded +feature, or %NULL on error + + + + + the plugin feature to check + + + + + + Specifies a rank for a plugin feature, so that autoplugging uses +the most appropriate feature. + + + + + + feature to rank + + + + rank value - higher number means more priority rank + + + + + + + + + A function that can be used with e.g. gst_registry_feature_filter() +to get a list of pluginfeature that match certain criteria. + + %TRUE for a positive match, %FALSE otherwise + + + + + the pluginfeature to check + + + + the user_data that has been passed on e.g. + gst_registry_feature_filter() + + + + + + A function that can be used with e.g. gst_registry_plugin_filter() +to get a list of plugins that match certain criteria. + + %TRUE for a positive match, %FALSE otherwise + + + + + the plugin to check + + + + the user_data that has been passed on e.g. gst_registry_plugin_filter() + + + + + + The plugin loading state + + Temporarily loaded plugins + + + The plugin won't be scanned (again) + + + + A plugin should provide a pointer to a function of either #GstPluginInitFunc +or this type in the plugin_desc struct. +The function will be called by the loader at startup. One would then +register each #GstPluginFeature. This version allows +user data to be passed to init function (useful for bindings). + + %TRUE if plugin initialised successfully + + + + + The plugin object + + + + extra data + + + + + + A plugin should provide a pointer to a function of this type in the +plugin_desc struct. +This function will be called by the loader at startup. One would then +register each #GstPluginFeature. + + %TRUE if plugin initialised successfully + + + + + The plugin object + + + + + + A #GstPoll keeps track of file descriptors much like fd_set (used with +select()) or a struct pollfd array (used with poll()). Once created with +gst_poll_new(), the set can be used to wait for file descriptors to be +readable and/or writable. It is possible to make this wait be controlled +by specifying %TRUE for the @controllable flag when creating the set (or +later calling gst_poll_set_controllable()). + +New file descriptors are added to the set using gst_poll_add_fd(), and +removed using gst_poll_remove_fd(). Controlling which file descriptors +should be waited for to become readable and/or writable are done using +gst_poll_fd_ctl_read() and gst_poll_fd_ctl_write(). + +Use gst_poll_wait() to wait for the file descriptors to actually become +readable and/or writable, or to timeout if no file descriptor is available +in time. The wait can be controlled by calling gst_poll_restart() and +gst_poll_set_flushing(). + +Once the file descriptor set has been waited for, one can use +gst_poll_fd_has_closed() to see if the file descriptor has been closed, +gst_poll_fd_has_error() to see if it has generated an error, +gst_poll_fd_can_read() to see if it is possible to read from the file +descriptor, and gst_poll_fd_can_write() to see if it is possible to +write to it. + + Add a file descriptor to the file descriptor set. + + %TRUE if the file descriptor was successfully added to the set. + + + + + a file descriptor set. + + + + a file descriptor. + + + + + + Check if @fd in @set has data to be read. + + %TRUE if the descriptor has data to be read. + + + + + a file descriptor set. + + + + a file descriptor. + + + + + + Check if @fd in @set can be used for writing. + + %TRUE if the descriptor can be used for writing. + + + + + a file descriptor set. + + + + a file descriptor. + + + + + + Control whether the descriptor @fd in @set will be monitored for +readability. + + %TRUE if the descriptor was successfully updated. + + + + + a file descriptor set. + + + + a file descriptor. + + + + a new status. + + + + + + Control whether the descriptor @fd in @set will be monitored for +writability. + + %TRUE if the descriptor was successfully updated. + + + + + a file descriptor set. + + + + a file descriptor. + + + + a new status. + + + + + + Check if @fd in @set has closed the connection. + + %TRUE if the connection was closed. + + + + + a file descriptor set. + + + + a file descriptor. + + + + + + Check if @fd in @set has an error. + + %TRUE if the descriptor has an error. + + + + + a file descriptor set. + + + + a file descriptor. + + + + + + Mark @fd as ignored so that the next call to gst_poll_wait() will yield +the same result for @fd as last time. This function must be called if no +operation (read/write/recv/send/etc.) will be performed on @fd before +the next call to gst_poll_wait(). + +The reason why this is needed is because the underlying implementation +might not allow querying the fd more than once between calls to one of +the re-enabling operations. + + + + + + a file descriptor set. + + + + a file descriptor. + + + + + + Free a file descriptor set. + + + + + + a file descriptor set. + + + + + + Get a GPollFD for the reading part of the control socket. This is useful when +integrating with a GSource and GMainLoop. + + + + + + a #GstPoll + + + + a #GPollFD + + + + + + Read a byte from the control socket of the controllable @set. + +This function only works for timer #GstPoll objects created with +gst_poll_new_timer(). + + %TRUE on success. %FALSE when when there was no byte to read or +reading the byte failed. If there was no byte to read, and only then, errno +will contain EWOULDBLOCK or EAGAIN. For all other values of errno this always signals a +critical error. + + + + + a #GstPoll. + + + + + + Remove a file descriptor from the file descriptor set. + + %TRUE if the file descriptor was successfully removed from the set. + + + + + a file descriptor set. + + + + a file descriptor. + + + + + + Restart any gst_poll_wait() that is in progress. This function is typically +used after adding or removing descriptors to @set. + +If @set is not controllable, then this call will have no effect. + +This function only works for non-timer #GstPoll objects created with +gst_poll_new(). + + + + + + a #GstPoll. + + + + + + When @controllable is %TRUE, this function ensures that future calls to +gst_poll_wait() will be affected by gst_poll_restart() and +gst_poll_set_flushing(). + +This function only works for non-timer #GstPoll objects created with +gst_poll_new(). + + %TRUE if the controllability of @set could be updated. + + + + + a #GstPoll. + + + + new controllable state. + + + + + + When @flushing is %TRUE, this function ensures that current and future calls +to gst_poll_wait() will return -1, with errno set to EBUSY. + +Unsetting the flushing state will restore normal operation of @set. + +This function only works for non-timer #GstPoll objects created with +gst_poll_new(). + + + + + + a #GstPoll. + + + + new flushing state. + + + + + + Wait for activity on the file descriptors in @set. This function waits up to +the specified @timeout. A timeout of #GST_CLOCK_TIME_NONE waits forever. + +For #GstPoll objects created with gst_poll_new(), this function can only be +called from a single thread at a time. If called from multiple threads, +-1 will be returned with errno set to EPERM. + +This is not true for timer #GstPoll objects created with +gst_poll_new_timer(), where it is allowed to have multiple threads waiting +simultaneously. + + The number of #GstPollFD in @set that have activity or 0 when no +activity was detected after @timeout. If an error occurs, -1 is returned +and errno is set. + + + + + a #GstPoll. + + + + a timeout in nanoseconds. + + + + + + Write a byte to the control socket of the controllable @set. +This function is mostly useful for timer #GstPoll objects created with +gst_poll_new_timer(). + +It will make any current and future gst_poll_wait() function return with +1, meaning the control socket is set. After an equal amount of calls to +gst_poll_read_control() have been performed, calls to gst_poll_wait() will +block again until their timeout expired. + +This function only works for timer #GstPoll objects created with +gst_poll_new_timer(). + + %TRUE on success. %FALSE when when the byte could not be written. +errno contains the detailed error code but will never be EAGAIN, EINTR or +EWOULDBLOCK. %FALSE always signals a critical error. + + + + + a #GstPoll. + + + + + + Create a new file descriptor set. If @controllable, it +is possible to restart or flush a call to gst_poll_wait() with +gst_poll_restart() and gst_poll_set_flushing() respectively. + +Free-function: gst_poll_free + + a new #GstPoll, or %NULL in + case of an error. Free with gst_poll_free(). + + + + + whether it should be possible to control a wait. + + + + + + Create a new poll object that can be used for scheduling cancellable +timeouts. + +A timeout is performed with gst_poll_wait(). Multiple timeouts can be +performed from different threads. + +Free-function: gst_poll_free + + a new #GstPoll, or %NULL in + case of an error. Free with gst_poll_free(). + + + + + + A file descriptor object. + + a file descriptor + + + + + + + Initializes @fd. Alternatively you can initialize it with +#GST_POLL_FD_INIT. + + + + + + a #GstPollFD + + + + + + + This interface offers methods to query and manipulate parameter preset sets. +A preset is a bunch of property settings, together with meta data and a name. +The name of a preset serves as key for subsequent method calls to manipulate +single presets. +All instances of one type will share the list of presets. The list is created +on demand, if presets are not used, the list is not created. + +The interface comes with a default implementation that serves most plugins. +Wrapper plugins will override most methods to implement support for the +native preset format of those wrapped plugins. +One method that is useful to be overridden is gst_preset_get_property_names(). +With that one can control which properties are saved and in which order. +When implementing support for read-only presets, one should set the vmethods +for gst_preset_save_preset() and gst_preset_delete_preset() to %NULL. +Applications can use gst_preset_is_editable() to check for that. + +The default implementation supports presets located in a system directory, +application specific directory and in the users home directory. When getting +a list of presets individual presets are read and overlaid in 1) system, +2) application and 3) user order. Whenever an earlier entry is newer, the +later entries will be updated. Since 1.8 you can also provide extra paths +where to find presets through the GST_PRESET_PATH environment variable. +Presets found in those paths will be concidered as "app presets". + + Gets the directory for application specific presets if set by the +application. + + the directory or %NULL, don't free or modify +the string + + + + + Sets an extra directory as an absolute path that should be considered when +looking for presets. Any presets in the application dir will shadow the +system presets. + + %TRUE for success, %FALSE if the dir already has been set + + + + + the application specific preset dir + + + + + + Delete the given preset. + + %TRUE for success, %FALSE if e.g. there is no preset with that @name + + + + + a #GObject that implements #GstPreset + + + + preset name to remove + + + + + + 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. + + %TRUE for success, %FALSE if e.g. there is no preset with that @name +or no value for the given @tag + + + + + a #GObject that implements #GstPreset + + + + preset name + + + + meta data item name + + + + value + + + + + + Get a copy of preset names as a %NULL terminated string array. + + + list with names, use g_strfreev() after usage. + + + + + + + a #GObject that implements #GstPreset + + + + + + Get a the names of the GObject properties that can be used for presets. + + an + array of property names which should be freed with g_strfreev() after use. + + + + + + + a #GObject that implements #GstPreset + + + + + + Load the given preset. + + %TRUE for success, %FALSE if e.g. there is no preset with that @name + + + + + a #GObject that implements #GstPreset + + + + preset name to load + + + + + + Renames a preset. If there is already a preset by the @new_name it will be +overwritten. + + %TRUE for success, %FALSE if e.g. there is no preset with @old_name + + + + + a #GObject that implements #GstPreset + + + + current preset name + + + + new preset name + + + + + + Save the current object settings as a preset under the given name. If there +is already a preset by this @name it will be overwritten. + + %TRUE for success, %FALSE + + + + + a #GObject that implements #GstPreset + + + + preset name to save + + + + + + Sets a new @value for an existing meta data item or adds a new item. Meta +data @tag names can be something like e.g. "comment". Supplying %NULL for the +@value will unset an existing value. + + %TRUE for success, %FALSE if e.g. there is no preset with that @name + + + + + a #GObject that implements #GstPreset + + + + preset name + + + + meta data item name + + + + new value + + + + + + Delete the given preset. + + %TRUE for success, %FALSE if e.g. there is no preset with that @name + + + + + a #GObject that implements #GstPreset + + + + preset name to remove + + + + + + 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. + + %TRUE for success, %FALSE if e.g. there is no preset with that @name +or no value for the given @tag + + + + + a #GObject that implements #GstPreset + + + + preset name + + + + meta data item name + + + + value + + + + + + Get a copy of preset names as a %NULL terminated string array. + + + list with names, use g_strfreev() after usage. + + + + + + + a #GObject that implements #GstPreset + + + + + + Get a the names of the GObject properties that can be used for presets. + + an + array of property names which should be freed with g_strfreev() after use. + + + + + + + a #GObject that implements #GstPreset + + + + + + Check if one can add new presets, change existing ones and remove presets. + + %TRUE if presets are editable or %FALSE if they are static + + + + + a #GObject that implements #GstPreset + + + + + + Load the given preset. + + %TRUE for success, %FALSE if e.g. there is no preset with that @name + + + + + a #GObject that implements #GstPreset + + + + preset name to load + + + + + + Renames a preset. If there is already a preset by the @new_name it will be +overwritten. + + %TRUE for success, %FALSE if e.g. there is no preset with @old_name + + + + + a #GObject that implements #GstPreset + + + + current preset name + + + + new preset name + + + + + + Save the current object settings as a preset under the given name. If there +is already a preset by this @name it will be overwritten. + + %TRUE for success, %FALSE + + + + + a #GObject that implements #GstPreset + + + + preset name to save + + + + + + Sets a new @value for an existing meta data item or adds a new item. Meta +data @tag names can be something like e.g. "comment". Supplying %NULL for the +@value will unset an existing value. + + %TRUE for success, %FALSE if e.g. there is no preset with that @name + + + + + a #GObject that implements #GstPreset + + + + preset name + + + + meta data item name + + + + new value + + + + + + + #GstPreset interface. + + parent interface type. + + + + + + + list with names, use g_strfreev() after usage. + + + + + + + a #GObject that implements #GstPreset + + + + + + + + + an + array of property names which should be freed with g_strfreev() after use. + + + + + + + a #GObject that implements #GstPreset + + + + + + + + + %TRUE for success, %FALSE if e.g. there is no preset with that @name + + + + + a #GObject that implements #GstPreset + + + + preset name to load + + + + + + + + + %TRUE for success, %FALSE + + + + + a #GObject that implements #GstPreset + + + + preset name to save + + + + + + + + + %TRUE for success, %FALSE if e.g. there is no preset with @old_name + + + + + a #GObject that implements #GstPreset + + + + current preset name + + + + new preset name + + + + + + + + + %TRUE for success, %FALSE if e.g. there is no preset with that @name + + + + + a #GObject that implements #GstPreset + + + + preset name to remove + + + + + + + + + %TRUE for success, %FALSE if e.g. there is no preset with that @name + + + + + a #GObject that implements #GstPreset + + + + preset name + + + + meta data item name + + + + new value + + + + + + + + + %TRUE for success, %FALSE if e.g. there is no preset with that @name +or no value for the given @tag + + + + + a #GObject that implements #GstPreset + + + + preset name + + + + meta data item name + + + + value + + + + + + + + + + + + + The type of a %GST_MESSAGE_PROGRESS. The progress messages inform the +application of the status of asynchronous tasks. + + A new task started. + + + A task completed and a new one continues. + + + A task completed. + + + A task was canceled. + + + A task caused an error. An error message is also + posted on the bus. + + + + Metadata type that holds information about a sample from a protection-protected +track, including the information needed to decrypt it (if it is encrypted). + + the parent #GstMeta. + + + + the cryptographic information needed to decrypt the sample. + + + + + + + + + + + Invoke the default chain function of the proxy pad. + + a #GstFlowReturn from the pad. + + + + + a sink #GstPad, returns GST_FLOW_ERROR if not. + + + + the parent of @pad or %NULL + + + + the #GstBuffer to send, return GST_FLOW_ERROR + if not. + + + + + + Invoke the default chain list function of the proxy pad. + + a #GstFlowReturn from the pad. + + + + + a sink #GstPad, returns GST_FLOW_ERROR if not. + + + + the parent of @pad or %NULL + + + + the #GstBufferList to send, return GST_FLOW_ERROR + if not. + + + + + + Invoke the default getrange function of the proxy pad. + + a #GstFlowReturn from the pad. + + + + + a src #GstPad, returns #GST_FLOW_ERROR if not. + + + + the parent of @pad + + + + The start offset of the buffer + + + + The length of the buffer + + + + a pointer to hold the #GstBuffer, + returns #GST_FLOW_ERROR if %NULL. + + + + + + Invoke the default iterate internal links function of the proxy pad. + + a #GstIterator of #GstPad, or %NULL if @pad +has no parent. Unref each returned pad with gst_object_unref(). + + + + + the #GstPad to get the internal links of. + + + + the parent of @pad or %NULL + + + + + + Get the internal pad of @pad. Unref target pad after usage. + +The internal pad of a #GstGhostPad is the internally used +pad of opposite direction, which is used to link to the target. + + the target #GstProxyPad, can +be %NULL. Unref target pad after usage. + + + + + the #GstProxyPad + + + + + + + + + + + + + + + + + + + + + + + + + The different types of QoS events that can be given to the +gst_event_new_qos() method. + + The QoS event type that is produced when upstream + elements are producing data too quickly and the element can't keep up + processing the data. Upstream should reduce their production rate. This + type is also used when buffers arrive early or in time. + + + The QoS event type that is produced when upstream + elements are producing data too slowly and need to speed up their + production rate. + + + The QoS event type that is produced when the + application enabled throttling to limit the data rate. + + + + + + + The same thing as #GST_QUERY_TYPE_UPSTREAM | #GST_QUERY_TYPE_DOWNSTREAM. + + + + Queries can be performed on pads (gst_pad_query()) and elements +(gst_element_query()). Please note that some queries might need a running +pipeline to work. + +Queries can be created using the gst_query_new_*() functions. +Query values can be set using gst_query_set_*(), and parsed using +gst_query_parse_*() helpers. + +The following example shows how to query the duration of a pipeline: +|[<!-- language="C" --> + GstQuery *query; + gboolean res; + query = gst_query_new_duration (GST_FORMAT_TIME); + res = gst_element_query (pipeline, query); + if (res) { + gint64 duration; + gst_query_parse_duration (query, NULL, &amp;duration); + g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration)); + } else { + g_print ("duration query failed..."); + } + gst_query_unref (query); +]| + + The parent #GstMiniObject type + + + + the #GstQueryType + + + + Constructs a new query object for querying if @caps are accepted. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + a fixed #GstCaps + + + + + + Constructs a new query object for querying the allocation properties. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + the negotiated caps + + + + return a pool + + + + + + Constructs a new query object for querying the buffering status of +a stream. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + the default #GstFormat for the new query + + + + + + Constructs a new query object for querying the caps. + +The CAPS query should return the allowable caps for a pad in the context +of the element's state, its link to other elements, and the devices or files +it has opened. These caps must be a subset of the pad template caps. In the +NULL state with no links, the CAPS query should ideally return the same caps +as the pad template. In rare circumstances, an object property can affect +the caps returned by the CAPS query, but this is discouraged. + +For most filters, the caps returned by CAPS query is directly affected by the +allowed caps on other pads. For demuxers and decoders, the caps returned by +the srcpad's getcaps function is directly related to the stream data. Again, +the CAPS query should return the most specific caps it reasonably can, since this +helps with autoplugging. + +The @filter is used to restrict the result caps, only the caps matching +@filter should be returned from the CAPS query. Specifying a filter might +greatly reduce the amount of processing an element needs to do. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + a filter + + + + + + Constructs a new query object for querying the pipeline-local context. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + Context type to query + + + + + + Constructs a new convert query object. Use gst_query_unref() +when done with it. A convert query is used to ask for a conversion between +one format and another. + +Free-function: gst_query_unref() + + a #GstQuery + + + + + the source #GstFormat for the new query + + + + the value to convert + + + + the target #GstFormat + + + + + + Constructs a new custom query object. Use gst_query_unref() +when done with it. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + the query type + + + + a structure for the query + + + + + + Constructs a new query object for querying the drain state. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + Constructs a new stream duration query object to query in the given format. +Use gst_query_unref() when done with it. A duration query will give the +total length of the stream. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + the #GstFormat for this duration query + + + + + + Constructs a new query object for querying formats of +the stream. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + Constructs a new latency query object. +Use gst_query_unref() when done with it. A latency query is usually performed +by sinks to compensate for additional latency introduced by elements in the +pipeline. + +Free-function: gst_query_unref() + + a #GstQuery + + + + + Constructs a new query stream position query object. Use gst_query_unref() +when done with it. A position query is used to query the current position +of playback in the streams, in some format. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + the default #GstFormat for the new query + + + + + + Constructs a new query object for querying the scheduling properties. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + Constructs a new query object for querying seeking properties of +the stream. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + the default #GstFormat for the new query + + + + + + Constructs a new segment query object. Use gst_query_unref() +when done with it. A segment query is used to discover information about the +currently configured segment for playback. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + the #GstFormat for the new query + + + + + + Constructs a new query URI query object. Use gst_query_unref() +when done with it. An URI query is used to query the current URI +that is used by the source or sink. + +Free-function: gst_query_unref() + + a new #GstQuery + + + + + Add @api with @params as one of the supported metadata API to @query. + + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + the metadata API + + + + API specific parameters + + + + + + Add @allocator and its @params as a supported memory allocator. + + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + the memory allocator + + + + a #GstAllocationParams + + + + + + Set the pool parameters in @query. + + + + + + A valid #GstQuery of type GST_QUERY_ALLOCATION. + + + + the #GstBufferPool + + + + the buffer size + + + + the min buffers + + + + the max buffers + + + + + + Set the buffering-ranges array field in @query. The current last +start position of the array should be inferior to @start. + + a #gboolean indicating if the range was added or not. + + + + + a GST_QUERY_BUFFERING type query #GstQuery + + + + start position of the range + + + + stop position of the range + + + + + + Add @mode as one of the supported scheduling modes to @query. + + + + + + a GST_QUERY_SCHEDULING type query #GstQuery + + + + a #GstPadMode + + + + + + Check if @query has metadata @api set. When this function returns %TRUE, +@index will contain the index where the requested API and the parameters +can be found. + + %TRUE when @api is in the list of metadata. + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + the metadata API + + + + the index + + + + + + Retrieve the number of values currently stored in the +meta API array of the query's structure. + + the metadata API array size as a #guint. + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + + + Retrieve the number of values currently stored in the +allocator params array of the query's structure. + +If no memory allocator is specified, the downstream element can handle +the default memory allocator. The first memory allocator in the query +should be generic and allow mapping to system memory, all following +allocators should be ordered by preference with the preferred one first. + + the allocator array size as a #guint. + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + + + Retrieve the number of values currently stored in the +pool array of the query's structure. + + the pool array size as a #guint. + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + + + Retrieve the number of values currently stored in the +buffered-ranges array of the query's structure. + + the range array size as a #guint. + + + + + a GST_QUERY_BUFFERING type query #GstQuery + + + + + + Retrieve the number of values currently stored in the +scheduling mode array of the query's structure. + + the scheduling mode array size as a #guint. + + + + + a GST_QUERY_SCHEDULING type query #GstQuery + + + + + + Get the structure of a query. + + the #GstStructure of the query. The structure is + still owned by the query and will therefore be freed when the query + is unreffed. + + + + + a #GstQuery + + + + + + Check if @query has scheduling mode set. + +> When checking if upstream supports pull mode, it is usually not +> enough to just check for GST_PAD_MODE_PULL with this function, you +> also want to check whether the scheduling flags returned by +> gst_query_parse_scheduling() have the seeking flag set (meaning +> random access is supported, not only sequential pulls). + + %TRUE when @mode is in the list of scheduling modes. + + + + + a GST_QUERY_SCHEDULING type query #GstQuery + + + + the scheduling mode + + + + + + Check if @query has scheduling mode set and @flags is set in +query scheduling flags. + + %TRUE when @mode is in the list of scheduling modes + and @flags are compatible with query flags. + + + + + a GST_QUERY_SCHEDULING type query #GstQuery + + + + the scheduling mode + + + + #GstSchedulingFlags + + + + + + Get the caps from @query. The caps remains valid as long as @query remains +valid. + + + + + + The query to parse + + + + A pointer to the caps + + + + + + Parse the result from @query and store in @result. + + + + + + a GST_QUERY_ACCEPT_CAPS type query #GstQuery + + + + location for the result + + + + + + Parse an allocation query, writing the requested caps in @caps and +whether a pool is needed in @need_pool, if the respective parameters +are non-%NULL. + +Pool details can be retrieved using gst_query_get_n_allocation_pools() and +gst_query_parse_nth_allocation_pool(). + + + + + + a #GstQuery + + + + The #GstCaps + + + + Whether a #GstBufferPool is needed + + + + + + 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. + + + + + + A valid #GstQuery of type GST_QUERY_BUFFERING. + + + + if buffering is busy, or %NULL + + + + a buffering percent, or %NULL + + + + + + Parse an available query, writing the format into @format, and +other results into the passed parameters, if the respective parameters +are non-%NULL + + + + + + a GST_QUERY_BUFFERING type query #GstQuery + + + + the format to set for the @segment_start + and @segment_end values, or %NULL + + + + the start to set, or %NULL + + + + the stop to set, or %NULL + + + + estimated total amount of download + time remaining in milliseconds, or %NULL + + + + + + Extracts the buffering stats values from @query. + + + + + + A valid #GstQuery of type GST_QUERY_BUFFERING. + + + + a buffering mode, or %NULL + + + + the average input rate, or %NULL + + + + the average output rat, or %NULL + + + + amount of buffering time left in + milliseconds, or %NULL + + + + + + Get the filter from the caps @query. The caps remains valid as long as +@query remains valid. + + + + + + The query to parse + + + + A pointer to the caps filter + + + + + + Get the caps result from @query. The caps remains valid as long as +@query remains valid. + + + + + + The query to parse + + + + A pointer to the caps + + + + + + Get the context from the context @query. The context remains valid as long as +@query remains valid. + + + + + + The query to parse + + + + A pointer to store the #GstContext + + + + + + Parse a context type from an existing GST_QUERY_CONTEXT query. + + a #gboolean indicating if the parsing succeeded. + + + + + a GST_QUERY_CONTEXT type query + + + + the context type, or %NULL + + + + + + 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. + + + + + + a #GstQuery + + + + the storage for the #GstFormat of the + source value, or %NULL + + + + the storage for the source value, or %NULL + + + + the storage for the #GstFormat of the + destination value, or %NULL + + + + the storage for the destination value, + or %NULL + + + + + + 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. + + + + + + a #GstQuery + + + + the storage for the #GstFormat of the duration + value, or %NULL. + + + + the storage for the total duration, or %NULL. + + + + + + Parse a latency query answer. + + + + + + a #GstQuery + + + + storage for live or %NULL + + + + the storage for the min latency or %NULL + + + + the storage for the max latency or %NULL + + + + + + Parse the number of formats in the formats @query. + + + + + + a #GstQuery + + + + the number of formats in this query. + + + + + + Parse an available query and get the metadata API +at @index of the metadata API array. + + a #GType of the metadata API at @index. + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + position in the metadata API array to read + + + + API specific parameters + + + + + + Parse an available query and get the allocator and its params +at @index of the allocator array. + + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + position in the allocator array to read + + + + variable to hold the result + + + + parameters for the allocator + + + + + + Get the pool parameters in @query. + +Unref @pool with gst_object_unref() when it's not needed any more. + + + + + + A valid #GstQuery of type GST_QUERY_ALLOCATION. + + + + index to parse + + + + the #GstBufferPool + + + + the buffer size + + + + the min buffers + + + + the max buffers + + + + + + Parse an available query and get the start and stop values stored +at the @index of the buffered ranges array. + + a #gboolean indicating if the parsing succeeded. + + + + + a GST_QUERY_BUFFERING type query #GstQuery + + + + position in the buffered-ranges array to read + + + + the start position to set, or %NULL + + + + the stop position to set, or %NULL + + + + + + Parse the format query and retrieve the @nth format from it into +@format. If the list contains less elements than @nth, @format will be +set to GST_FORMAT_UNDEFINED. + + + + + + a #GstQuery + + + + the nth format to retrieve. + + + + a pointer to store the nth format + + + + + + Parse an available query and get the scheduling mode +at @index of the scheduling modes array. + + a #GstPadMode of the scheduling mode at @index. + + + + + a GST_QUERY_SCHEDULING type query #GstQuery + + + + position in the scheduling modes array to read + + + + + + Parse a position query, writing the format into @format, and the position +into @cur, if the respective parameters are non-%NULL. + + + + + + a #GstQuery + + + + the storage for the #GstFormat of the + position values (may be %NULL) + + + + the storage for the current position (may be %NULL) + + + + + + Set the scheduling properties. + + + + + + A valid #GstQuery of type GST_QUERY_SCHEDULING. + + + + #GstSchedulingFlags + + + + the suggested minimum size of pull requests + + + + the suggested maximum size of pull requests: + + + + the suggested alignment of pull requests + + + + + + Parse a seeking query, writing the format into @format, and +other results into the passed parameters, if the respective parameters +are non-%NULL + + + + + + a GST_QUERY_SEEKING type query #GstQuery + + + + the format to set for the @segment_start + and @segment_end values, or %NULL + + + + the seekable flag to set, or %NULL + + + + the segment_start to set, or %NULL + + + + the segment_end to set, or %NULL + + + + + + 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. + +See gst_query_set_segment() for an explanation of the function arguments. + + + + + + a #GstQuery + + + + the storage for the rate of the segment, or %NULL + + + + the storage for the #GstFormat of the values, + or %NULL + + + + the storage for the start value, or %NULL + + + + the storage for the stop value, or %NULL + + + + + + Parse an URI query, writing the URI into @uri as a newly +allocated string, if the respective parameters are non-%NULL. +Free the string with g_free() after usage. + + + + + + a #GstQuery + + + + the storage for the current URI + (may be %NULL) + + + + + + Parse an URI query, writing the URI into @uri as a newly +allocated string, if the respective parameters are non-%NULL. +Free the string with g_free() after usage. + + + + + + a #GstQuery + + + + the storage for the redirect URI + (may be %NULL) + + + + + + Parse an URI query, and set @permanent to %TRUE if there is a redirection +and it should be considered permanent. If a redirection is permanent, +applications should update their internal storage of the URI, otherwise +they should make all future requests to the original URI. + + + + + + a #GstQuery + + + + if the URI redirection is permanent + (may be %NULL) + + + + + + Remove the metadata API at @index of the metadata API array. + + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + position in the metadata API array to remove + + + + + + Remove the allocation param at @index of the allocation param array. + + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + position in the allocation param array to remove + + + + + + Remove the allocation pool at @index of the allocation pool array. + + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + position in the allocation pool array to remove + + + + + + Set @result as the result for the @query. + + + + + + a GST_QUERY_ACCEPT_CAPS type query #GstQuery + + + + the result to set + + + + + + Set the percentage of buffered data. This is a value between 0 and 100. +The @busy indicator is %TRUE when the buffering is in progress. + + + + + + A valid #GstQuery of type GST_QUERY_BUFFERING. + + + + if buffering is busy + + + + a buffering percent + + + + + + Set the available query result fields in @query. + + + + + + a #GstQuery + + + + the format to set for the @start and @stop values + + + + the start to set + + + + the stop to set + + + + estimated total amount of download time remaining in + milliseconds + + + + + + Configures the buffering stats values in @query. + + + + + + A valid #GstQuery of type GST_QUERY_BUFFERING. + + + + a buffering mode + + + + the average input rate + + + + the average output rate + + + + amount of buffering time left in milliseconds + + + + + + Set the @caps result in @query. + + + + + + The query to use + + + + A pointer to the caps + + + + + + Answer a context query by setting the requested context. + + + + + + a #GstQuery with query type GST_QUERY_CONTEXT + + + + the requested #GstContext + + + + + + Answer a convert query by setting the requested values. + + + + + + a #GstQuery + + + + the source #GstFormat + + + + the source value + + + + the destination #GstFormat + + + + the destination value + + + + + + Answer a duration query by setting the requested value in the given format. + + + + + + a #GstQuery + + + + the #GstFormat for the duration + + + + the duration of the stream + + + + + + Set the formats query result fields in @query. The number of formats passed +must be equal to @n_formats. + + + + + + a #GstQuery + + + + the number of formats to set. + + + + A number of @GstFormats equal to @n_formats. + + + + + + Set the formats query result fields in @query. The number of formats passed +in the @formats array must be equal to @n_formats. + + + + + + a #GstQuery + + + + the number of formats to set. + + + + an array containing @n_formats + @GstFormat values. + + + + + + + + Answer a latency query by setting the requested values in the given format. + + + + + + a #GstQuery + + + + if there is a live element upstream + + + + the minimal latency of the upstream elements + + + + the maximal latency of the upstream elements + + + + + + Parse an available query and get the allocator and its params +at @index of the allocator array. + + + + + + a GST_QUERY_ALLOCATION type query #GstQuery + + + + position in the allocator array to set + + + + new allocator to set + + + + parameters for the allocator + + + + + + Set the pool parameters in @query. + + + + + + A valid #GstQuery of type GST_QUERY_ALLOCATION. + + + + index to modify + + + + the #GstBufferPool + + + + the size + + + + the min buffers + + + + the max buffers + + + + + + Answer a position query by setting the requested value in the given format. + + + + + + a #GstQuery with query type GST_QUERY_POSITION + + + + the requested #GstFormat + + + + the position to set + + + + + + Set the scheduling properties. + + + + + + A valid #GstQuery of type GST_QUERY_SCHEDULING. + + + + #GstSchedulingFlags + + + + the suggested minimum size of pull requests + + + + the suggested maximum size of pull requests + + + + the suggested alignment of pull requests + + + + + + Set the seeking query result fields in @query. + + + + + + a #GstQuery + + + + the format to set for the @segment_start and @segment_end values + + + + the seekable flag to set + + + + the segment_start to set + + + + the segment_end to set + + + + + + Answer a segment query by setting the requested values. The normal +playback segment of a pipeline is 0 to duration at the default rate of +1.0. If a seek was performed on the pipeline to play a different +segment, this query will return the range specified in the last seek. + +@start_value and @stop_value will respectively contain the configured +playback range start and stop values expressed in @format. +The values are always between 0 and the duration of the media and +@start_value <= @stop_value. @rate will contain the playback rate. For +negative rates, playback will actually happen from @stop_value to +@start_value. + + + + + + a #GstQuery + + + + the rate of the segment + + + + the #GstFormat of the segment values (@start_value and @stop_value) + + + + the start value + + + + the stop value + + + + + + Answer a URI query by setting the requested URI. + + + + + + a #GstQuery with query type GST_QUERY_URI + + + + the URI to set + + + + + + Answer a URI query by setting the requested URI redirection. + + + + + + a #GstQuery with query type GST_QUERY_URI + + + + the URI to set + + + + + + Answer a URI query by setting the requested URI redirection +to permanent or not. + + + + + + a #GstQuery with query type %GST_QUERY_URI + + + + whether the redirect is permanent or not + + + + + + Get the structure of a query. This method should be called with a writable +@query so that the returned structure is guaranteed to be writable. + + the #GstStructure of the query. The structure is + still owned by the query and will therefore be freed when the query + is unreffed. + + + + + a #GstQuery + + + + + + + Standard predefined Query types + + unknown query type + + + current position in stream + + + total duration of the stream + + + latency of stream + + + current jitter of stream + + + current rate of the stream + + + seeking capabilities + + + segment start/stop positions + + + convert values between formats + + + query supported formats for convert + + + query available media for efficient seeking. + + + a custom application or element defined query. + + + query the URI of the source or sink. + + + the buffer allocation properties + + + the scheduling properties + + + the accept caps query + + + the caps query + + + wait till all serialized data is consumed downstream + + + query the pipeline-local context from + downstream or upstream (since 1.2) + + + Gets the #GstQueryTypeFlags associated with @type. + + a #GstQueryTypeFlags. + + + + + a #GstQueryType + + + + + + Get a printable name for the given query type. Do not modify or free. + + a reference to the static name of the query. + + + + + the query type + + + + + + Get the unique quark for the given query type. + + the quark associated with the query type + + + + + the query type + + + + + + + #GstQueryTypeFlags indicate the aspects of the different #GstQueryType +values. You can get the type flags of a #GstQueryType with the +gst_query_type_get_flags() function. + + Set if the query can travel upstream. + + + Set if the query can travel downstream. + + + Set if the query should be serialized with data + flow. + + + + Element priority ranks. Defines the order in which the autoplugger (or +similar rank-picking mechanisms, such as e.g. gst_element_make_from_uri()) +will choose this element over an alternative one with the same function. + +These constants serve as a rough guidance for defining the rank of a +#GstPluginFeature. Any value is valid, including values bigger than +@GST_RANK_PRIMARY. + + will be chosen last or not at all + + + unlikely to be chosen + + + likely to be chosen + + + will be chosen first + + + + One registry holds the metadata of a set of plugins. + +<emphasis role="bold">Design:</emphasis> + +The #GstRegistry object is a list of plugins and some functions for dealing +with them. Each #GstPlugin is matched 1-1 with a file on disk, and may or may +not be loaded at a given time. + +The primary source, at all times, of plugin information is each plugin file +itself. Thus, if an application wants information about a particular plugin, +or wants to search for a feature that satisfies given criteria, the primary +means of doing so is to load every plugin and look at the resulting +information that is gathered in the default registry. Clearly, this is a time +consuming process, so we cache information in the registry file. The format +and location of the cache file is internal to gstreamer. + +On startup, plugins are searched for in the plugin search path. The following +locations are checked in this order: + +* location from --gst-plugin-path commandline option. +* the GST_PLUGIN_PATH environment variable. +* the GST_PLUGIN_SYSTEM_PATH environment variable. +* default locations (if GST_PLUGIN_SYSTEM_PATH is not set). + Those default locations are: + `$XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/` + and `$prefix/libs/gstreamer-$GST_API_VERSION/`. + [$XDG_DATA_HOME](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) defaults to + `$HOME/.local/share`. + +The registry cache file is loaded from +`$XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin` +(where $XDG_CACHE_HOME defaults to `$HOME/.cache`) or the file listed in the `GST_REGISTRY` +env var. One reason to change the registry location is for testing. + +For each plugin that is found in the plugin search path, there could be 3 +possibilities for cached information: + + * the cache may not contain information about a given file. + * the cache may have stale information. + * the cache may have current information. + +In the first two cases, the plugin is loaded and the cache updated. In +addition to these cases, the cache may have entries for plugins that are not +relevant to the current process. These are marked as not available to the +current process. If the cache is updated for whatever reason, it is marked +dirty. + +A dirty cache is written out at the end of initialization. Each entry is +checked to make sure the information is minimally valid. If not, the entry is +simply dropped. + +## Implementation notes: + +The "cache" and "registry" are different concepts and can represent +different sets of plugins. For various reasons, at init time, the cache is +stored in the default registry, and plugins not relevant to the current +process are marked with the %GST_PLUGIN_FLAG_CACHED bit. These plugins are +removed at the end of initialization. + + By default GStreamer will perform scanning and rebuilding of the +registry file using a helper child process. + +Applications might want to disable this behaviour with the +gst_registry_fork_set_enabled() function, in which case new plugins +are scanned (and loaded) into the application process. + + %TRUE if GStreamer will use the child helper process when +rebuilding the registry. + + + + + Applications might want to disable/enable spawning of a child helper process +when rebuilding the registry. See gst_registry_fork_is_enabled() for more +information. + + + + + + whether rebuilding the registry can use a temporary child helper process. + + + + + + Retrieves the singleton plugin registry. The caller does not own a +reference on the registry, as it is alive as long as GStreamer is +initialized. + + the #GstRegistry. + + + + + Add the feature to the registry. The feature-added signal will be emitted. +This function sinks @feature. + + %TRUE on success. + +MT safe. + + + + + the registry to add the plugin to + + + + the feature to add + + + + + + Add the plugin to the registry. The plugin-added signal will be emitted. +This function will sink @plugin. + + %TRUE on success. + +MT safe. + + + + + the registry to add the plugin to + + + + the plugin to add + + + + + + Checks whether a plugin feature by the given name exists in +@registry and whether its version is at least the +version required. + + %TRUE if the feature could be found and the version is +the same as the required version or newer, and %FALSE otherwise. + + + + + a #GstRegistry + + + + the name of the feature (e.g. "oggdemux") + + + + the minimum major version number + + + + the minimum minor version number + + + + the minimum micro version number + + + + + + Runs a filter against all features of the plugins in the registry +and returns a GList with the results. +If the first flag is set, only the first match is +returned (as a list with a single object). + + a #GList of + #GstPluginFeature. Use gst_plugin_feature_list_free() after usage. + +MT safe. + + + + + + + registry to query + + + + the filter to use + + + + only return first match + + + + user data passed to the filter function + + + + + + Find the pluginfeature with the given name and type in the registry. + + the pluginfeature with the + given name and type or %NULL if the plugin was not + found. gst_object_unref() after usage. + +MT safe. + + + + + the registry to search + + + + the pluginfeature name to find + + + + the pluginfeature type to find + + + + + + Find the plugin with the given name in the registry. +The plugin will be reffed; caller is responsible for unreffing. + + the plugin with the given name + or %NULL if the plugin was not found. gst_object_unref() after + usage. + +MT safe. + + + + + the registry to search + + + + the plugin name to find + + + + + + Retrieves a #GList of #GstPluginFeature of @type. + + a #GList of + #GstPluginFeature of @type. Use gst_plugin_feature_list_free() after use + +MT safe. + + + + + + + a #GstRegistry + + + + a #GType. + + + + + + Retrieves a #GList of features of the plugin with name @name. + + a #GList of + #GstPluginFeature. Use gst_plugin_feature_list_free() after usage. + + + + + + + a #GstRegistry. + + + + a plugin name. + + + + + + Returns the registry's feature list cookie. This changes +every time a feature is added or removed from the registry. + + the feature list cookie. + + + + + the registry + + + + + + Get a copy of all plugins registered in the given registry. The refcount +of each element in the list in incremented. + + a #GList of #GstPlugin. + Use gst_plugin_list_free() after usage. + +MT safe. + + + + + + + the registry to search + + + + + + Look up a plugin in the given registry with the given filename. +If found, plugin is reffed. + + the #GstPlugin if found, or + %NULL if not. gst_object_unref() after usage. + + + + + the registry to look up in + + + + the name of the file to look up + + + + + + Find a #GstPluginFeature with @name in @registry. + + a #GstPluginFeature with its refcount incremented, + use gst_object_unref() after usage. + +MT safe. + + + + + a #GstRegistry + + + + a #GstPluginFeature name + + + + + + 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 +returned (as a list with a single object). +Every plugin is reffed; use gst_plugin_list_free() after use, which +will unref again. + + a #GList of #GstPlugin. + Use gst_plugin_list_free() after usage. + +MT safe. + + + + + + + registry to query + + + + the filter to use + + + + only return first match + + + + user data passed to the filter function + + + + + + Remove the feature from the registry. + +MT safe. + + + + + + the registry to remove the feature from + + + + the feature to remove + + + + + + Remove the plugin from the registry. + +MT safe. + + + + + + the registry to remove the plugin from + + + + the plugin to remove + + + + + + Scan the given path for plugins to add to the registry. The syntax of the +path is specific to the registry. + + %TRUE if registry changed + + + + + the registry to add found plugins to + + + + the path to scan + + + + + + + + + + + + Signals that a feature has been added to the registry (possibly +replacing a previously-added one by the same name) + + + + + + the feature that has been added + + + + + + Signals that a plugin has been added to the registry (possibly +replacing a previously-added one by the same name) + + + + + + the plugin that has been added + + + + + + + + + + + + + + Resource errors are for any resource used by an element: +memory, files, network connections, process space, ... +They're typically used by source and sink elements. + + a general error which doesn't fit in any other +category. Make sure you add a custom message to the error call. + + + do not use this except as a placeholder for +deciding where to go while developing code. + + + used when the resource could not be found. + + + used when resource is busy. + + + used when resource fails to open for reading. + + + used when resource fails to open for writing. + + + used when resource cannot be opened for +both reading and writing, or either (but unspecified which). + + + used when the resource can't be closed. + + + used when the resource can't be read from. + + + used when the resource can't be written to. + + + used when a seek on the resource fails. + + + used when a synchronize on the resource fails. + + + used when settings can't be manipulated on. + + + used when the resource has no space left. + + + used when the resource can't be opened + due to missing authorization. + (Since 1.2.4) + + + the number of resource error types. + + + + + + + + + Constant that defines one GStreamer second. + + + + printf format type used to debug GStreamer segments. You can use this in +combination with GStreamer's debug logging system as well as the functions +gst_info_vasprintf(), gst_info_strdup_vprintf() and gst_info_strdup_printf() +to pretty-print #GstSegment structures. +This can only be used on pointers to GstSegment structures. + + + + A string that can be used in printf-like format strings to display a signed +#GstClockTimeDiff or #gint64 value in h:m:s format. Use GST_TIME_ARGS() to +construct the matching arguments. + +Example: +|[ +printf("%" GST_STIME_FORMAT "\n", GST_STIME_ARGS(ts)); +]| + + + + A #GstSample is a small object containing data, a type, timing and +extra arbitrary information. + + Create a new #GstSample with the provided details. + +Free-function: gst_sample_unref + + the new #GstSample. gst_sample_unref() + after usage. + + + + + a #GstBuffer, or %NULL + + + + a #GstCaps, or %NULL + + + + a #GstSegment, or %NULL + + + + a #GstStructure, or %NULL + + + + + + Get the buffer associated with @sample + + the buffer of @sample or %NULL + when there is no buffer. The buffer remains valid as long as + @sample is valid. If you need to hold on to it for longer than + that, take a ref to the buffer with gst_buffer_ref(). + + + + + a #GstSample + + + + + + Get the buffer list associated with @sample + + the buffer list of @sample or %NULL + when there is no buffer list. The buffer list remains valid as long as + @sample is valid. If you need to hold on to it for longer than + that, take a ref to the buffer list with gst_mini_object_ref (). + + + + + a #GstSample + + + + + + Get the caps associated with @sample + + the caps of @sample or %NULL + when there is no caps. The caps remain valid as long as @sample is + valid. If you need to hold on to the caps for longer than that, + take a ref to the caps with gst_caps_ref(). + + + + + a #GstSample + + + + + + Get extra information associated with @sample. + + the extra info of @sample. + The info remains valid as long as @sample is valid. + + + + + a #GstSample + + + + + + Get the segment associated with @sample + + the segment of @sample. + The segment remains valid as long as @sample is valid. + + + + + a #GstSample + + + + + + Set the buffer list associated with @sample + + + + + + a #GstSample + + + + a #GstBufferList + + + + + + + The different scheduling flags. + + if seeking is possible + + + if sequential access is recommended + + + if bandwidth is limited and buffering possible (since 1.2) + + + + The different search modes. + + Only search for exact matches. + + + Search for an exact match or the element just before. + + + Search for an exact match or the element just after. + + + + Flags to be used with gst_element_seek() or gst_event_new_seek(). All flags +can be used together. + +A non flushing seek might take some time to perform as the currently +playing data in the pipeline will not be cleared. + +An accurate seek might be slower for formats that don't have any indexes +or timestamp markers in the stream. Specifying this flag might require a +complete scan of the file in those cases. + +When performing a segment seek: after the playback of the segment completes, +no EOS will be emitted by the element that performed the seek, but a +%GST_MESSAGE_SEGMENT_DONE message will be posted on the bus by the element. +When this message is posted, it is possible to send a new seek event to +continue playback. With this seek method it is possible to perform seamless +looping or simple linear editing. + +When doing fast forward (rate > 1.0) or fast reverse (rate < -1.0) trickmode +playback, the %GST_SEEK_FLAG_TRICKMODE flag can be used to instruct decoders +and demuxers to adjust the playback rate by skipping frames. This can improve +performance and decrease CPU usage because not all frames need to be decoded. + +Beyond that, the %GST_SEEK_FLAG_TRICKMODE_KEY_UNITS flag can be used to +request that decoders skip all frames except key units, and +%GST_SEEK_FLAG_TRICKMODE_NO_AUDIO flags can be used to request that audio +decoders do no decoding at all, and simple output silence. + +The %GST_SEEK_FLAG_SNAP_BEFORE flag can be used to snap to the previous +relevant location, and the %GST_SEEK_FLAG_SNAP_AFTER flag can be used to +select the next relevant location. If %GST_SEEK_FLAG_KEY_UNIT is specified, +the relevant location is a keyframe. If both flags are specified, the nearest +of these locations will be selected. If none are specified, the implementation is +free to select whichever it wants. + +The before and after here are in running time, so when playing backwards, +the next location refers to the one that will played in next, and not the +one that is located after in the actual source stream. + +Also see part-seeking.txt in the GStreamer design documentation for more +details on the meaning of these flags and the behaviour expected of +elements that handle them. + + no flag + + + flush pipeline + + + accurate position is requested, this might + be considerably slower for some formats. + + + seek to the nearest keyframe. This might be + faster but less accurate. + + + perform a segment seek. + + + when doing fast forward or fast reverse playback, allow + elements to skip frames instead of generating all + frames. (Since 1.6) + + + Deprecated backward compatibility flag, replaced + by %GST_SEEK_FLAG_TRICKMODE + + + go to a location before the requested position, + if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe at or before + the requested position the one at or before the seek target. + + + go to a location after the requested position, + if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe at of after the + requested position. + + + go to a position near the requested position, + if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe closest + to the requested position, if both keyframes are at an equal + distance, behaves like %GST_SEEK_FLAG_SNAP_BEFORE. + + + when doing fast forward or fast reverse + playback, request that elements only decode keyframes + and skip all other content, for formats that have + keyframes. (Since 1.6) + + + when doing fast forward or fast reverse + playback, request that audio decoder elements skip + decoding and output only gap events or silence. (Since 1.6) + + + + The different types of seek events. When constructing a seek event with +gst_event_new_seek() or when doing gst_segment_do_seek (). + + no change in position is required + + + absolute position is requested + + + relative position to duration is requested + + + + This helper structure holds the relevant values for tracking the region of +interest in a media file, called a segment. + +The structure can be used for two purposes: + + * performing seeks (handling seek events) + * tracking playback regions (handling newsegment events) + +The segment is usually configured by the application with a seek event which +is propagated upstream and eventually handled by an element that performs the seek. + +The configured segment is then propagated back downstream with a newsegment event. +This information is then used to clip media to the segment boundaries. + +A segment structure is initialized with gst_segment_init(), which takes a #GstFormat +that will be used as the format of the segment values. The segment will be configured +with a start value of 0 and a stop/duration of -1, which is undefined. The default +rate and applied_rate is 1.0. + +The public duration field contains the duration of the segment. When using +the segment for seeking, the start and time members should normally be left +to their default 0 value. The stop position is left to -1 unless explicitly +configured to a different value after a seek event. + +The current position in the segment should be set by changing the position +member in the structure. + +For elements that perform seeks, the current segment should be updated with the +gst_segment_do_seek() and the values from the seek event. This method will update +all the segment fields. The position field will contain the new playback position. +If the start_type was different from GST_SEEK_TYPE_NONE, playback continues from +the position position, possibly with updated flags or rate. + +For elements that want to use #GstSegment to track the playback region, +update the segment fields with the information from the newsegment event. +The gst_segment_clip() method can be used to check and clip +the media data to the segment boundaries. + +For elements that want to synchronize to the pipeline clock, gst_segment_to_running_time() +can be used to convert a timestamp to a value that can be used to synchronize +to the clock. This function takes into account the base as well as +any rate or applied_rate conversions. + +For elements that need to perform operations on media data in stream_time, +gst_segment_to_stream_time() can be used to convert a timestamp and the segment +info to stream time (which is always between 0 and the duration of the stream). + + flags for this segment + + + + the playback rate of the segment + + + + the already applied rate to the segment + + + + the format of the segment values + + + + the running time (plus elapsed time, see offset) of the segment start + + + + the amount (in buffer timestamps) that has already been elapsed in + the segment + + + + the start of the segment in buffer timestamp time (PTS) + + + + the stop of the segment in buffer timestamp time (PTS) + + + + the stream time of the segment start + + + + the buffer timestamp position in the segment (used internally by + elements such as sources, demuxers or parsers to track progress) + + + + the duration of the segment + + + + + + + + + Allocate a new #GstSegment structure and initialize it using +gst_segment_init(). + +Free-function: gst_segment_free + + a new #GstSegment, free with gst_segment_free(). + + + + + Clip the given @start and @stop values to the segment boundaries given +in @segment. @start and @stop are compared and clipped to @segment +start and stop values. + +If the function returns %FALSE, @start and @stop are known to fall +outside of @segment and @clip_start and @clip_stop are not updated. + +When the function returns %TRUE, @clip_start and @clip_stop will be +updated. If @clip_start or @clip_stop are different from @start or @stop +respectively, the region fell partially in the segment. + +Note that when @stop is -1, @clip_stop will be set to the end of the +segment. Depending on the use case, this may or may not be what you want. + + %TRUE if the given @start and @stop times fall partially or + completely in @segment, %FALSE if the values are completely outside + of the segment. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the start position in the segment + + + + the stop position in the segment + + + + the clipped start position in the segment + + + + the clipped stop position in the segment + + + + + + Create a copy of given @segment. + +Free-function: gst_segment_free + + a new #GstSegment, free with gst_segment_free(). + + + + + a #GstSegment + + + + + + Copy the contents of @src into @dest. + + + + + + a #GstSegment + + + + a #GstSegment + + + + + + Update the segment structure with the field values of a seek event (see +gst_event_new_seek()). + +After calling this method, the segment field position and time will +contain the requested new position in the segment. The new requested +position in the segment depends on @rate and @start_type and @stop_type. + +For positive @rate, the new position in the segment is the new @segment +start field when it was updated with a @start_type different from +#GST_SEEK_TYPE_NONE. If no update was performed on @segment start position +(#GST_SEEK_TYPE_NONE), @start is ignored and @segment position is +unmodified. + +For negative @rate, the new position in the segment is the new @segment +stop field when it was updated with a @stop_type different from +#GST_SEEK_TYPE_NONE. If no stop was previously configured in the segment, the +duration of the segment will be used to update the stop position. +If no update was performed on @segment stop position (#GST_SEEK_TYPE_NONE), +@stop is ignored and @segment position is unmodified. + +The applied rate of the segment will be set to 1.0 by default. +If the caller can apply a rate change, it should update @segment +rate and applied_rate after calling this function. + +@update will be set to %TRUE if a seek should be performed to the segment +position field. This field can be %FALSE if, for example, only the @rate +has been changed but not the playback position. + + %TRUE if the seek could be performed. + + + + + a #GstSegment structure. + + + + the rate of the segment. + + + + the format of the segment. + + + + the segment flags for the segment + + + + the seek method + + + + the seek start value + + + + the seek method + + + + the seek stop value + + + + boolean holding whether position was updated. + + + + + + Free the allocated segment @segment. + + + + + + a #GstSegment + + + + + + The start/position fields are set to 0 and the stop/duration +fields are set to -1 (unknown). The default rate of 1.0 and no +flags are set. + +Initialize @segment to its default values. + + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + + + Checks for two segments being equal. Equality here is defined +as perfect equality, including floating point values. + + %TRUE if the segments are equal, %FALSE otherwise. + + + + + a #GstSegment structure. + + + + a #GstSegment structure. + + + + + + Adjust the values in @segment so that @offset is applied to all +future running-time calculations. + + %TRUE if the segment could be updated successfully. If %FALSE is +returned, @offset is not in @segment. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the offset to apply in the segment + + + + + + Convert @running_time into a position in the segment so that +gst_segment_to_running_time() with that position returns @running_time. + + the position in the segment for @running_time. This function returns +-1 when @running_time is -1 or when it is not inside @segment. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the running_time in the segment + + + + + + Translate @running_time to the segment position using the currently configured +segment. Compared to gst_segment_position_from_running_time() this function can +return negative segment position. + +This function is typically used by elements that need to synchronize buffers +against the clock or each other. + +@running_time can be any value and the result of this function for values +outside of the segment is extrapolated. + +When 1 is returned, @running_time resulted in a positive position returned +in @position. + +When this function returns -1, the returned @position should be negated +to get the real negative segment position. + + a 1 or -1 on success, 0 on failure. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the running-time + + + + the resulting position in the segment + + + + + + Convert @stream_time into a position in the segment so that +gst_segment_to_stream_time() with that position returns @stream_time. + + the position in the segment for @stream_time. This function returns +-1 when @stream_time is -1 or when it is not inside @segment. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the stream_time in the segment + + + + + + Translate @stream_time to the segment position using the currently configured +segment. Compared to gst_segment_position_from_stream_time() this function can +return negative segment position. + +This function is typically used by elements that need to synchronize buffers +against the clock or each other. + +@stream_time can be any value and the result of this function for values outside +of the segment is extrapolated. + +When 1 is returned, @stream_time resulted in a positive position returned +in @position. + +When this function returns -1, the returned @position should be negated +to get the real negative segment position. + + a 1 or -1 on success, 0 on failure. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the stream-time + + + + the resulting position in the segment + + + + + + Adjust the start/stop and base values of @segment such that the next valid +buffer will be one with @running_time. + + %TRUE if the segment could be updated successfully. If %FALSE is +returned, @running_time is -1 or not in @segment. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the running_time in the segment + + + + + + Convert @running_time into a position in the segment so that +gst_segment_to_running_time() with that position returns @running_time. + + the position in the segment for @running_time. This function returns +-1 when @running_time is -1 or when it is not inside @segment. + +Deprecated. Use gst_segment_position_from_running_time() instead. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the running_time in the segment + + + + + + Translate @position to the total running time using the currently configured +segment. Position is a value between @segment start and stop time. + +This function is typically used by elements that need to synchronize to the +global clock in a pipeline. The running time is a constantly increasing value +starting from 0. When gst_segment_init() is called, this value will reset to +0. + +This function returns -1 if the position is outside of @segment start and stop. + + the position as the total running time or -1 when an invalid position +was given. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the position in the segment + + + + + + Translate @position to the total running time using the currently configured +segment. Compared to gst_segment_to_running_time() this function can return +negative running-time. + +This function is typically used by elements that need to synchronize buffers +against the clock or eachother. + +@position can be any value and the result of this function for values outside +of the segment is extrapolated. + +When 1 is returned, @position resulted in a positive running-time returned +in @running_time. + +When this function returns -1, the returned @running_time should be negated +to get the real negative running time. + + a 1 or -1 on success, 0 on failure. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the position in the segment + + + + result running-time + + + + + + Translate @position to stream time using the currently configured +segment. The @position value must be between @segment start and +stop value. + +This function is typically used by elements that need to operate on +the stream time of the buffers it receives, such as effect plugins. +In those use cases, @position is typically the buffer timestamp or +clock time that one wants to convert to the stream time. +The stream time is always between 0 and the total duration of the +media stream. + + the position in stream_time or -1 when an invalid position +was given. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the position in the segment + + + + + + Translate @position to the total stream time using the currently configured +segment. Compared to gst_segment_to_stream_time() this function can return +negative stream-time. + +This function is typically used by elements that need to synchronize buffers +against the clock or eachother. + +@position can be any value and the result of this function for values outside +of the segment is extrapolated. + +When 1 is returned, @position resulted in a positive stream-time returned +in @stream_time. + +When this function returns -1, the returned @stream_time should be negated +to get the real negative stream time. + + a 1 or -1 on success, 0 on failure. + + + + + a #GstSegment structure. + + + + the format of the segment. + + + + the position in the segment + + + + result stream-time + + + + + + + Flags for the GstSegment structure. Currently mapped to the corresponding +values of the seek flags. + + no flags + + + reset the pipeline running_time to the segment + running_time + + + perform skip playback (Since 1.6) + + + Deprecated backward compatibility flag, replaced + by @GST_SEGMENT_FLAG_TRICKMODE + + + send SEGMENT_DONE instead of EOS + + + Decode only keyframes, where + possible (Since 1.6) + + + Do not decode any audio, where + possible (Since 1.6) + + + + + Try to retrieve as much information as + possible when getting the stack trace + + + + The possible states an element can be in. States can be changed using +gst_element_set_state() and checked using gst_element_get_state(). + + no pending state. + + + the NULL state or initial state of an element. + + + the element is ready to go to PAUSED. + + + the element is PAUSED, it is ready to accept and + process data. Sink elements however only accept one + buffer and then block. + + + the element is PLAYING, the #GstClock is running and + the data is flowing. + + + + #GST_STATE_CHANGE_NULL_TO_READY : state change from NULL to READY. + * The element must check if the resources it needs are available. Device + sinks and -sources typically try to probe the device to constrain their + caps. + * The element opens the device (in case feature need to be probed). + +#GST_STATE_CHANGE_READY_TO_PAUSED : state change from READY to PAUSED. + + * The element pads are activated in order to receive data in PAUSED. + Streaming threads are started. + * Some elements might need to return %GST_STATE_CHANGE_ASYNC and complete + the state change when they have enough information. It is a requirement + for sinks to return %GST_STATE_CHANGE_ASYNC and complete the state change + when they receive the first buffer or %GST_EVENT_EOS (preroll). + Sinks also block the dataflow when in PAUSED. + * A pipeline resets the running_time to 0. + + * Live sources return %GST_STATE_CHANGE_NO_PREROLL and don't generate data. + +#GST_STATE_CHANGE_PAUSED_TO_PLAYING: state change from PAUSED to PLAYING. + + * Most elements ignore this state change. + * The pipeline selects a #GstClock and distributes this to all the children + before setting them to PLAYING. This means that it is only allowed to + synchronize on the #GstClock in the PLAYING state. + * The pipeline uses the #GstClock and the running_time to calculate the + base_time. The base_time is distributed to all children when performing + the state change. + * Sink elements stop blocking on the preroll buffer or event and start + rendering the data. + * Sinks can post %GST_MESSAGE_EOS in the PLAYING state. It is not allowed + to post %GST_MESSAGE_EOS when not in the PLAYING state. + * While streaming in PAUSED or PLAYING elements can create and remove + sometimes pads. + * Live sources start generating data and return %GST_STATE_CHANGE_SUCCESS. + +#GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED. + + * Most elements ignore this state change. + * The pipeline calculates the running_time based on the last selected + #GstClock and the base_time. It stores this information to continue + playback when going back to the PLAYING state. + + * Sinks unblock any #GstClock wait calls. + * When a sink does not have a pending buffer to play, it returns + #GST_STATE_CHANGE_ASYNC from this state change and completes the state + change when it receives a new buffer or an %GST_EVENT_EOS. + * Any queued %GST_MESSAGE_EOS items are removed since they will be reposted + when going back to the PLAYING state. The EOS messages are queued in + #GstBin containers. + + * Live sources stop generating data and return %GST_STATE_CHANGE_NO_PREROLL. + +#GST_STATE_CHANGE_PAUSED_TO_READY : state change from PAUSED to READY. + + * Sinks unblock any waits in the preroll. + * Elements unblock any waits on devices + * Chain or get_range functions return %GST_FLOW_FLUSHING. + * The element pads are deactivated so that streaming becomes impossible and + all streaming threads are stopped. + * The sink forgets all negotiated formats + * Elements remove all sometimes pads + +#GST_STATE_CHANGE_READY_TO_NULL : state change from READY to NULL. + + * Elements close devices + * Elements reset any internal state. + +These are the different state changes an element goes through. +%GST_STATE_NULL &rArr; %GST_STATE_PLAYING is called an upwards state change +and %GST_STATE_PLAYING &rArr; %GST_STATE_NULL a downwards state change. + + + + + + + + + + + + + + + The possible return values from a state change function such as +gst_element_set_state(). Only @GST_STATE_CHANGE_FAILURE is a real failure. + + the state change failed + + + the state change succeeded + + + the state change will happen asynchronously + + + the state change succeeded but the element + cannot produce data in %GST_STATE_PAUSED. + This typically happens with live sources. + + + + Datastructure to initialize #GstCaps from a string description usually +used in conjunction with GST_STATIC_CAPS() and gst_static_caps_get() to +instantiate a #GstCaps. + + the cached #GstCaps + + + + a string describing a caps + + + + + + + + + Clean up the cached caps contained in @static_caps. + + + + + + the #GstStaticCaps to clean + + + + + + Converts a #GstStaticCaps to a #GstCaps. + + a pointer to the #GstCaps. Unref after usage. + Since the core holds an additional ref to the returned caps, + use gst_caps_make_writable() on the returned caps to modify it. + + + + + the #GstStaticCaps to convert + + + + + + + Structure describing the #GstStaticPadTemplate. + + the name of the template + + + + the direction of the template + + + + the presence of the template + + + + the caps of the template. + + + + Converts a #GstStaticPadTemplate into a #GstPadTemplate. + + a new #GstPadTemplate. + + + + + the static pad template + + + + + + Gets the capabilities of the static pad template. + + the #GstCaps of the static pad template. +Unref after usage. Since the core holds an additional +ref to the returned caps, use gst_caps_make_writable() +on the returned caps to modify it. + + + + + a #GstStaticPadTemplate to get capabilities of. + + + + + + + A high-level object representing a single stream. It might be backed, or +not, by an actual flow of data in a pipeline (#GstPad). + +A #GstStream does not care about data changes (such as decoding, encoding, +parsing,...) as long as the underlying data flow corresponds to the same +high-level flow (ex: a certain audio track). + +A #GstStream contains all the information pertinent to a stream, such as +stream-id, tags, caps, type, ... + +Elements can subclass a #GstStream for internal usage (to contain information +pertinent to streams of data). + + Create a new #GstStream for the given @stream_id, @caps, @type +and @flags + + The new #GstStream + + + + + the id for the new stream. If %NULL, +a new one will be automatically generated + + + + the #GstCaps of the stream + + + + the #GstStreamType of the stream + + + + the #GstStreamFlags of the stream + + + + + + Retrieve the caps for @stream, if any + + The #GstCaps for @stream + + + + + a #GstStream + + + + + + Retrieve the current stream flags for @stream + + The #GstStreamFlags for @stream + + + + + a #GstStream + + + + + + Returns the stream ID of @stream. + + the stream ID of @stream. Only valid +during the lifetime of @stream. + + + + + a #GstStream + + + + + + Retrieve the stream type for @stream + + The #GstStreamType for @stream + + + + + a #GstStream + + + + + + Retrieve the tags for @stream, if any + + The #GstTagList for @stream + + + + + a #GstStream + + + + + + Set the caps for the #GstStream + + + + + + a #GstStream + + + + a #GstCaps + + + + + + Set the @flags for the @stream. + + + + + + a #GstStream + + + + the flags to set on @stream + + + + + + Set the stream type of @stream + + + + + + a #GstStream + + + + the type to set on @stream + + + + + + Set the tags for the #GstStream + + + + + + a #GstStream + + + + a #GstTagList + + + + + + The #GstCaps of the #GstStream. + + + + + + + The unique identifier of the #GstStream. Can only be set at construction +time. + + + + The #GstStreamType of the #GstStream. Can only be set at construction time. + + + + The #GstTagList of the #GstStream. + + + + + + + The Stream Identifier for this #GstStream + + + + + + + + + + + + + GstStream class structure + + the parent class structure + + + + + + + + + + A collection of #GstStream that are available. + +A #GstStreamCollection will be provided by elements that can make those +streams available. Applications can use the collection to show the user +what streams are available by using %gst_stream_collection_get_stream() + +Once posted, a #GstStreamCollection is immutable. Updates are made by sending +a new #GstStreamCollection message, which may or may not share some of +the #GstStream objects from the collection it replaces. The receiver can check +the sender of a stream collection message to know which collection is +obsoleted. + +Several elements in a pipeline can provide #GstStreamCollection. + +Applications can activate streams from a collection by using the +#GST_EVENT_SELECT_STREAMS event on a pipeline, bin or element. + + Create a new #GstStreamCollection. + + The new #GstStreamCollection. + + + + + The stream id of the parent stream + + + + + + + + + + + + + + + + + + + + + + Add the given @stream to the @collection. + + %TRUE if the @stream was properly added, else %FALSE + + + + + a #GstStreamCollection + + + + the #GstStream to add + + + + + + Get the number of streams this collection contains + + The number of streams that @collection contains + + + + + a #GstStreamCollection + + + + + + Retrieve the #GstStream with index @index from the collection. + +The caller should not modify the returned #GstStream + + A #GstStream + + + + + a #GstStreamCollection + + + + Index of the stream to retrieve + + + + + + Returns the upstream id of the @collection. + + The upstream id + + + + + a #GstStreamCollection + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + GstStreamCollection class structure + + the parent class structure + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Stream errors are for anything related to the stream being processed: +format errors, media type errors, ... +They're typically used by decoders, demuxers, converters, ... + + a general error which doesn't fit in any other +category. Make sure you add a custom message to the error call. + + + do not use this except as a placeholder for +deciding where to go while developing code. + + + use this when you do not want to implement +this functionality yet. + + + used when the element doesn't know the +stream's type. + + + used when the element doesn't handle this type +of stream. + + + used when there's no codec to handle the +stream's type. + + + used when decoding fails. + + + used when encoding fails. + + + used when demuxing fails. + + + used when muxing fails. + + + used when the stream is of the wrong format +(for example, wrong caps). + + + used when the stream is encrypted and can't be +decrypted because this is not supported by the element. + + + used when the stream is encrypted and +can't be decrypted because no suitable key is available. + + + the number of stream error types. + + + + + + + + + + This stream has no special attributes + + + This stream is a sparse stream (e.g. a subtitle + stream), data may flow only in irregular intervals with large gaps in + between. + + + This stream should be selected by default. This + flag may be used by demuxers to signal that a stream should be selected + by default in a playback scenario. + + + This stream should not be selected by default. + This flag may be used by demuxers to signal that a stream should not + be selected by default in a playback scenario, but only if explicitly + selected by the user (e.g. an audio track for the hard of hearing or + a director's commentary track). + + + + + + The type of a %GST_MESSAGE_STREAM_STATUS. The stream status messages inform the +application of new streaming threads and their status. + + A new thread need to be created. + + + a thread entered its loop function + + + a thread left its loop function + + + a thread is destroyed + + + a thread is started + + + a thread is paused + + + a thread is stopped + + + + #GstStreamType describes a high level classification set for +flows of data in #GstStream objects. + +Note that this is a flag, and therefore users should not assume it +will be a single value. Do not use the equality operator for checking +whether a stream is of a certain type. + + The stream is of unknown (unclassified) type. + + + The stream is of audio data + + + The stream carries video data + + + The stream is a muxed container type + + + The stream contains subtitle / subpicture data. + + + Get a descriptive string for a given #GstStreamType + + A string describing the stream type + + + + + a #GstStreamType + + + + + + + A #GstStructure is a collection of key/value pairs. The keys are expressed +as GQuarks and the values can be of any GType. + +In addition to the key/value pairs, a #GstStructure also has a name. The name +starts with a letter and can be filled by letters, numbers and any of "/-_.:". + +#GstStructure is used by various GStreamer subsystems to store information +in a flexible and extensible way. A #GstStructure does not have a refcount +because it usually is part of a higher level object such as #GstCaps, +#GstMessage, #GstEvent, #GstQuery. It provides a means to enforce mutability +using the refcount of the parent with the gst_structure_set_parent_refcount() +method. + +A #GstStructure can be created with gst_structure_new_empty() or +gst_structure_new(), which both take a name and an optional set of +key/value pairs along with the types of the values. + +Field values can be changed with gst_structure_set_value() or +gst_structure_set(). + +Field values can be retrieved with gst_structure_get_value() or the more +convenient gst_structure_get_*() functions. + +Fields can be removed with gst_structure_remove_field() or +gst_structure_remove_fields(). + +Strings in structures must be ASCII or UTF-8 encoded. Other encodings are +not allowed. Strings may be %NULL however. + +Be aware that the current #GstCaps / #GstStructure serialization into string +has limited support for nested #GstCaps / #GstStructure fields. It can only +support one level of nesting. Using more levels will lead to unexpected +behavior when using serialization features, such as gst_caps_to_string() or +gst_value_serialize() and their counterparts. + + the GType of a structure + + + + + + + Creates a new #GstStructure with the given name. Parses the +list of variable arguments and sets fields to the values listed. +Variable arguments should be passed as field name, field type, +and value. Last variable argument should be %NULL. + +Free-function: gst_structure_free + + a new #GstStructure + + + + + name of new structure + + + + name of first field to set + + + + additional arguments + + + + + + Creates a new, empty #GstStructure with the given @name. + +See gst_structure_set_name() for constraints on the @name parameter. + +Free-function: gst_structure_free + + a new, empty #GstStructure + + + + + name of new structure + + + + + + Creates a #GstStructure from a string representation. +If end is not %NULL, a pointer to the place inside the given string +where parsing ended will be returned. + +The current implementation of serialization will lead to unexpected results +when there are nested #GstCaps / #GstStructure deeper than one level. + +Free-function: gst_structure_free + + a new #GstStructure or %NULL + when the string could not be parsed. Free with + gst_structure_free() after use. + + + + + a string representation of a #GstStructure + + + + + + Creates a new #GstStructure with the given name as a GQuark, followed by +fieldname quark, GType, argument(s) "triplets" in the same format as +gst_structure_id_set(). Basically a convenience wrapper around +gst_structure_new_id_empty() and gst_structure_id_set(). + +The last variable argument must be %NULL (or 0). + +Free-function: gst_structure_free + + a new #GstStructure + + + + + name of new structure + + + + the GQuark for the name of the field to set + + + + variable arguments + + + + + + Creates a new, empty #GstStructure with the given name as a GQuark. + +Free-function: gst_structure_free + + a new, empty #GstStructure + + + + + name of new structure + + + + + + Creates a new #GstStructure with the given @name. Structure fields +are set according to the varargs in a manner similar to +gst_structure_new(). + +See gst_structure_set_name() for constraints on the @name parameter. + +Free-function: gst_structure_free + + a new #GstStructure + + + + + name of new structure + + + + name of first field to set + + + + variable argument list + + + + + + Tries intersecting @struct1 and @struct2 and reports whether the result +would not be empty. + + %TRUE if intersection would not be empty + + + + + a #GstStructure + + + + a #GstStructure + + + + + + Duplicates a #GstStructure and all its fields and values. + +Free-function: gst_structure_free + + a new #GstStructure. + + + + + a #GstStructure to duplicate + + + + + + Calls the provided function once for each field in the #GstStructure. In +contrast to gst_structure_foreach(), the function may modify the fields. +In contrast to gst_structure_map_in_place(), the field is removed from +the structure if %FALSE is returned from the function. +The structure must be mutable. + + + + + + a #GstStructure + + + + a function to call for each field + + + + private data + + + + + + Fixate all values in @structure using gst_value_fixate(). +@structure will be modified in-place and should be writable. + + + + + + a #GstStructure + + + + + + Fixates a #GstStructure by changing the given field with its fixated value. + + %TRUE if the structure field could be fixated + + + + + a #GstStructure + + + + a field in @structure + + + + + + Fixates a #GstStructure by changing the given @field_name field to the given +@target boolean if that field is not fixed yet. + + %TRUE if the structure could be fixated + + + + + a #GstStructure + + + + a field in @structure + + + + the target value of the fixation + + + + + + Fixates a #GstStructure by changing the given field to the nearest +double to @target that is a subset of the existing field. + + %TRUE if the structure could be fixated + + + + + a #GstStructure + + + + a field in @structure + + + + the target value of the fixation + + + + + + Fixates a #GstStructure by changing the given field to the nearest +fraction to @target_numerator/@target_denominator that is a subset +of the existing field. + + %TRUE if the structure could be fixated + + + + + a #GstStructure + + + + a field in @structure + + + + The numerator of the target value of the fixation + + + + The denominator of the target value of the fixation + + + + + + Fixates a #GstStructure by changing the given field to the nearest +integer to @target that is a subset of the existing field. + + %TRUE if the structure could be fixated + + + + + a #GstStructure + + + + a field in @structure + + + + the target value of the fixation + + + + + + Fixates a #GstStructure by changing the given @field_name field to the given +@target string if that field is not fixed yet. + + %TRUE if the structure could be fixated + + + + + a #GstStructure + + + + a field in @structure + + + + the target value of the fixation + + + + + + 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() +and gst_structure_filter_and_map_in_place(). + + %TRUE if the supplied function returns %TRUE For each of the fields, +%FALSE otherwise. + + + + + a #GstStructure + + + + a function to call for each field + + + + private data + + + + + + Frees a #GstStructure and all its fields and values. The structure must not +have a parent when this function is called. + + + + + + the #GstStructure to free + + + + + + Parses the variable arguments and reads fields from @structure accordingly. +Variable arguments should be in the form field name, field type +(as a GType), pointer(s) to a variable(s) to hold the return value(s). +The last variable argument should be %NULL. + +For refcounted (mini)objects you will receive a new reference which +you must release with a suitable _unref() when no longer needed. For +strings and boxed types you will receive a copy which you will need to +release with either g_free() or the suitable function for the boxed type. + + %FALSE if there was a problem reading any of the fields (e.g. + because the field requested did not exist, or was of a type other + than the type specified), otherwise %TRUE. + + + + + a #GstStructure + + + + the name of the first field to read + + + + variable arguments + + + + + + This is useful in language bindings where unknown #GValue types are not +supported. This function will convert the %GST_TYPE_ARRAY and +%GST_TYPE_LIST into a newly allocated #GValueArray and return it through +@array. Be aware that this is slower then getting the #GValue directly. + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain an int, this function +returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a #GValueArray + + + + + + Sets the boolean pointed to by @value corresponding to the value of the +given field. Caller is responsible for making sure the field exists +and has the correct type. + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain a boolean, this +function returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a #gboolean to set + + + + + + 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 +and has the correct type. + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain a #GstClockTime, this +function returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a #GstClockTime to set + + + + + + Sets the date pointed to by @value corresponding to the date of the +given field. Caller is responsible for making sure the field exists +and has the correct type. + +On success @value will point to a newly-allocated copy of the date which +should be freed with g_date_free() when no longer needed (note: this is +inconsistent with e.g. gst_structure_get_string() which doesn't return a +copy of the string). + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain a data, this function +returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a #GDate to set + + + + + + Sets the datetime pointed to by @value corresponding to the datetime of the +given field. Caller is responsible for making sure the field exists +and has the correct type. + +On success @value will point to a reference of the datetime which +should be unreffed with gst_date_time_unref() when no longer needed +(note: this is inconsistent with e.g. gst_structure_get_string() +which doesn't return a copy of the string). + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain a data, this function +returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a #GstDateTime to set + + + + + + Sets the double pointed to by @value corresponding to the value of the +given field. Caller is responsible for making sure the field exists +and has the correct type. + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain a double, this +function returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a gdouble to set + + + + + + Sets the int pointed to by @value corresponding to the value of the +given field. Caller is responsible for making sure the field exists, +has the correct type and that the enumtype is correct. + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain an enum of the given +type, this function returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + the enum type of a field + + + + a pointer to an int to set + + + + + + Finds the field with the given name, and returns the type of the +value it contains. If the field is not found, G_TYPE_INVALID is +returned. + + the #GValue of the field + + + + + a #GstStructure + + + + the name of the field + + + + + + Read the GstFlagSet flags and mask out of the structure into the +provided pointers. + + %TRUE if the values could be set correctly. If there was no field +with @fieldname or the existing field did not contain a GstFlagSet, this +function returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a guint for the flags field + + + + a pointer to a guint for the mask field + + + + + + Sets the integers pointed to by @value_numerator and @value_denominator +corresponding to the value of the given field. Caller is responsible +for making sure the field exists and has the correct type. + + %TRUE if the values could be set correctly. If there was no field +with @fieldname or the existing field did not contain a GstFraction, this +function returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to an int to set + + + + a pointer to an int to set + + + + + + Sets the int pointed to by @value corresponding to the value of the +given field. Caller is responsible for making sure the field exists +and has the correct type. + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain an int, this function +returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to an int to set + + + + + + Sets the #gint64 pointed to by @value corresponding to the value of the +given field. Caller is responsible for making sure the field exists +and has the correct type. + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain a #gint64, this function +returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a #gint64 to set + + + + + + This is useful in language bindings where unknown #GValue types are not +supported. This function will convert the %GST_TYPE_ARRAY and +%GST_TYPE_LIST into a newly allocated GValueArray and return it through +@array. Be aware that this is slower then getting the #GValue directly. + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain an int, this function +returns %FALSE. + +Since 1.12 + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a #GValueArray + + + + + + Get the name of @structure as a string. + + the name of the structure. + + + + + a #GstStructure + + + + + + Get the name of @structure as a GQuark. + + the quark representing the name of the structure. + + + + + a #GstStructure + + + + + + Finds the field corresponding to @fieldname, and returns the string +contained in the field's value. Caller is responsible for making +sure the field exists and has the correct type. + +The string should not be modified, and remains valid until the next +call to a gst_structure_*() function with the given structure. + + a pointer to the string or %NULL when the +field did not exist or did not contain a string. + + + + + a #GstStructure + + + + the name of a field + + + + + + Sets the uint pointed to by @value corresponding to the value of the +given field. Caller is responsible for making sure the field exists +and has the correct type. + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain a uint, this function +returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a uint to set + + + + + + Sets the #guint64 pointed to by @value corresponding to the value of the +given field. Caller is responsible for making sure the field exists +and has the correct type. + + %TRUE if the value could be set correctly. If there was no field +with @fieldname or the existing field did not contain a #guint64, this function +returns %FALSE. + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a #guint64 to set + + + + + + Parses the variable arguments and reads fields from @structure accordingly. +valist-variant of gst_structure_get(). Look at the documentation of +gst_structure_get() for more details. + + %TRUE, or %FALSE if there was a problem reading any of the fields + + + + + a #GstStructure + + + + the name of the first field to read + + + + variable arguments + + + + + + Get the value of the field with name @fieldname. + + the #GValue corresponding to the field with the given name. + + + + + a #GstStructure + + + + the name of the field to get + + + + + + Check if @structure contains a field named @fieldname. + + %TRUE if the structure contains a field with the given name + + + + + a #GstStructure + + + + the name of a field + + + + + + Check if @structure contains a field named @fieldname and with GType @type. + + %TRUE if the structure contains a field with the given name and type + + + + + a #GstStructure + + + + the name of a field + + + + the type of a value + + + + + + Checks if the structure has the given name + + %TRUE if @name matches the name of the structure. + + + + + a #GstStructure + + + + structure name to check for + + + + + + Parses the variable arguments and reads fields from @structure accordingly. +Variable arguments should be in the form field id quark, field type +(as a GType), pointer(s) to a variable(s) to hold the return value(s). +The last variable argument should be %NULL (technically it should be a +0 quark, but we require %NULL so compilers that support it can check for +the %NULL terminator and warn if it's not there). + +This function is just like gst_structure_get() only that it is slightly +more efficient since it saves the string-to-quark lookup in the global +quark hashtable. + +For refcounted (mini)objects you will receive a new reference which +you must release with a suitable _unref() when no longer needed. For +strings and boxed types you will receive a copy which you will need to +release with either g_free() or the suitable function for the boxed type. + + %FALSE if there was a problem reading any of the fields (e.g. + because the field requested did not exist, or was of a type other + than the type specified), otherwise %TRUE. + + + + + a #GstStructure + + + + the quark of the first field to read + + + + variable arguments + + + + + + Parses the variable arguments and reads fields from @structure accordingly. +valist-variant of gst_structure_id_get(). Look at the documentation of +gst_structure_id_get() for more details. + + %TRUE, or %FALSE if there was a problem reading any of the fields + + + + + a #GstStructure + + + + the quark of the first field to read + + + + variable arguments + + + + + + Get the value of the field with GQuark @field. + + the #GValue corresponding to the field with the given name + identifier. + + + + + a #GstStructure + + + + the #GQuark of the field to get + + + + + + Check if @structure contains a field named @field. + + %TRUE if the structure contains a field with the given name + + + + + a #GstStructure + + + + #GQuark of the field name + + + + + + Check if @structure contains a field named @field and with GType @type. + + %TRUE if the structure contains a field with the given name and type + + + + + a #GstStructure + + + + #GQuark of the field name + + + + the type of a value + + + + + + Identical to gst_structure_set, except that field names are +passed using the GQuark for the field name. This allows more efficient +setting of the structure if the caller already knows the associated +quark values. +The last variable argument must be %NULL. + + + + + + a #GstStructure + + + + the GQuark for the name of the field to set + + + + variable arguments + + + + + + va_list form of gst_structure_id_set(). + + + + + + a #GstStructure + + + + the name of the field to set + + + + variable arguments + + + + + + Sets the field with the given GQuark @field to @value. If the field +does not exist, it is created. If the field exists, the previous +value is replaced and freed. + + + + + + a #GstStructure + + + + a #GQuark representing a field + + + + the new value of the field + + + + + + Sets the field with the given GQuark @field to @value. If the field +does not exist, it is created. If the field exists, the previous +value is replaced and freed. + + + + + + a #GstStructure + + + + a #GQuark representing a field + + + + the new value of the field + + + + + + Intersects @struct1 and @struct2 and returns the intersection. + + Intersection of @struct1 and @struct2 + + + + + a #GstStructure + + + + a #GstStructure + + + + + + Tests if the two #GstStructure are equal. + + %TRUE if the two structures have the same name and field. + + + + + a #GstStructure. + + + + a #GstStructure. + + + + + + Checks if @subset is a subset of @superset, i.e. has the same +structure name and for all fields that are existing in @superset, +@subset has a value that is a subset of the value in @superset. + + %TRUE if @subset is a subset of @superset + + + + + a #GstStructure + + + + a potentially greater #GstStructure + + + + + + 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 +fields. The structure must be mutable. + + %TRUE if the supplied function returns %TRUE For each of the fields, +%FALSE otherwise. + + + + + a #GstStructure + + + + a function to call for each field + + + + private data + + + + + + Get the number of fields in the structure. + + the number of fields in the structure + + + + + a #GstStructure + + + + + + Get the name of the given field number, counting from 0 onwards. + + the name of the given field number + + + + + a #GstStructure + + + + the index to get the name of + + + + + + Removes all fields in a GstStructure. + + + + + + a #GstStructure + + + + + + Removes the field with the given name. If the field with the given +name does not exist, the structure is unchanged. + + + + + + a #GstStructure + + + + the name of the field to remove + + + + + + Removes the fields with the given names. If a field does not exist, the +argument is ignored. + + + + + + a #GstStructure + + + + the name of the field to remove + + + + %NULL-terminated list of more fieldnames to remove + + + + + + va_list form of gst_structure_remove_fields(). + + + + + + a #GstStructure + + + + the name of the field to remove + + + + %NULL-terminated list of more fieldnames to remove + + + + + + Parses the variable arguments and sets fields accordingly. Fields that +weren't already part of the structure are added as needed. +Variable arguments should be in the form field name, field type +(as a GType), value(s). The last variable argument should be %NULL. + + + + + + a #GstStructure + + + + the name of the field to set + + + + variable arguments + + + + + + This is useful in language bindings where unknown GValue types are not +supported. This function will convert a @array to %GST_TYPE_ARRAY and set +the field specified by @fieldname. Be aware that this is slower then using +%GST_TYPE_ARRAY in a #GValue directly. + +Since 1.12 + + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a #GValueArray + + + + + + This is useful in language bindings where unknown GValue types are not +supported. This function will convert a @array to %GST_TYPE_ARRAY and set +the field specified by @fieldname. Be aware that this is slower then using +%GST_TYPE_ARRAY in a #GValue directly. + +Since 1.12 + + + + + + a #GstStructure + + + + the name of a field + + + + a pointer to a #GValueArray + + + + + + Sets the name of the structure to the given @name. The string +provided is copied before being used. It must not be empty, start with a +letter and can be followed by letters, numbers and any of "/-_.:". + + + + + + a #GstStructure + + + + the new name of the structure + + + + + + 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 +called by code implementing parent objects of #GstStructure, as described in +the MT Refcounting section of the design documents. + + %TRUE if the parent refcount could be set. + + + + + a #GstStructure + + + + a pointer to the parent's refcount + + + + + + va_list form of gst_structure_set(). + + + + + + a #GstStructure + + + + the name of the field to set + + + + variable arguments + + + + + + Sets the field with the given name @field to @value. If the field +does not exist, it is created. If the field exists, the previous +value is replaced and freed. + + + + + + a #GstStructure + + + + the name of the field to set + + + + the new value of the field + + + + + + Sets the field with the given name @field to @value. If the field +does not exist, it is created. If the field exists, the previous +value is replaced and freed. The function will take ownership of @value. + + + + + + a #GstStructure + + + + the name of the field to set + + + + the new value of the field + + + + + + Converts @structure to a human-readable string representation. + +For debugging purposes its easier to do something like this: +|[<!-- language="C" --> +GST_LOG ("structure is %" GST_PTR_FORMAT, structure); +]| +This prints the structure in human readable form. + +The current implementation of serialization will lead to unexpected results +when there are nested #GstCaps / #GstStructure deeper than one level. + +Free-function: g_free + + a pointer to string allocated by g_malloc(). + g_free() after usage. + + + + + a #GstStructure + + + + + + Creates a #GstStructure from a string representation. +If end is not %NULL, a pointer to the place inside the given string +where parsing ended will be returned. + +Free-function: gst_structure_free + + a new #GstStructure or %NULL + when the string could not be parsed. Free with + gst_structure_free() after use. + + + + + a string representation of a #GstStructure. + + + + pointer to store the end of the string in. + + + + + + + The type of a %GST_MESSAGE_STRUCTURE_CHANGE. + + Pad linking is starting or done. + + + Pad unlinking is starting or done. + + + + A function that will be called in gst_structure_filter_and_map_in_place(). +The function may modify @value, and the value will be removed from +the structure if %FALSE is returned. + + %TRUE if the field should be preserved, %FALSE if it +should be removed. + + + + + the #GQuark of the field name + + + + the #GValue of the field + + + + user data + + + + + + A function that will be called in gst_structure_foreach(). The function may +not modify @value. + + %TRUE if the foreach operation should continue, %FALSE if +the foreach operation should stop with %FALSE. + + + + + the #GQuark of the field name + + + + the #GValue of the field + + + + user data + + + + + + A function that will be called in gst_structure_map_in_place(). The function +may modify @value. + + %TRUE if the map operation should continue, %FALSE if +the map operation should stop with %FALSE. + + + + + the #GQuark of the field name + + + + the #GValue of the field + + + + user data + + + + + + The GStreamer core provides a GstSystemClock based on the system time. +Asynchronous callbacks are scheduled from an internal thread. + +Clock implementors are encouraged to subclass this systemclock as it +implements the async notification. + +Subclasses can however override all of the important methods for sync and +async notifications to implement their own callback methods or blocking +wait operations. + + Get a handle to the default system clock. The refcount of the +clock will be increased so you need to unref the clock after +usage. + + the default clock. + +MT safe. + + + + + Sets the default system clock that can be obtained with +gst_system_clock_obtain(). + +This is mostly used for testing and debugging purposes when you +want to have control over the time reported by the default system +clock. + +MT safe. + + + + + + a #GstClock + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + album containing this data (string) + +The album name as it should be displayed, e.g. 'The Jazz Guitar' + + + + The artist of the entire album, as it should be displayed. + + + + The artist of the entire album, as it should be sorted. + + + + album gain in db (double) + + + + peak of the album (double) + + + + album containing this data, as used for sorting (string) + +The album name as it should be sorted, e.g. 'Jazz Guitar, The' + + + + count of discs inside collection this disc belongs to (unsigned integer) + + + + disc number inside a collection (unsigned integer) + + + + Arbitrary application data (sample) + +Some formats allow applications to add their own arbitrary data +into files. This data is application dependent. + + + + Name of the application used to create the media (string) + + + + person(s) responsible for the recording (string) + +The artist name as it should be displayed, e.g. 'Jimi Hendrix' or +'The Guitar Heroes' + + + + person(s) responsible for the recording, as used for sorting (string) + +The artist name as it should be sorted, e.g. 'Hendrix, Jimi' or +'Guitar Heroes, The' + + + + generic file attachment (sample) (sample taglist should specify the content +type and if possible set "filename" to the file name of the +attachment) + + + + codec the audio data is stored in (string) + + + + number of beats per minute in audio (double) + + + + exact or average bitrate in bits/s (unsigned integer) + + + + codec the data is stored in (string) + + + + free text commenting the data (string) + + + + person(s) who composed the recording (string) + + + + The composer's name, used for sorting (string) + + + + conductor/performer refinement (string) + + + + contact information (string) + + + + container format the data is stored in (string) + + + + copyright notice of the data (string) + + + + URI to location where copyright details can be found (string) + + + + date the data was created (#GDate structure) + + + + date and time the data was created (#GstDateTime structure) + + + + short text describing the content of the data (string) + + + + Manufacturer of the device used to create the media (string) + + + + Model of the device used to create the media (string) + + + + length in GStreamer time units (nanoseconds) (unsigned 64-bit integer) + + + + name of the person or organisation that encoded the file. May contain a +copyright message if the person or organisation also holds the copyright +(string) + +Note: do not use this field to describe the encoding application. Use +#GST_TAG_APPLICATION_NAME or #GST_TAG_COMMENT for that. + + + + encoder used to encode this stream (string) + + + + version of the encoder used to encode this stream (unsigned integer) + + + + key/value text commenting the data (string) + +Must be in the form of 'key=comment' or +'key[lc]=comment' where 'lc' is an ISO-639 +language code. + +This tag is used for unknown Vorbis comment tags, +unknown APE tags and certain ID3v2 comment fields. + + + + genre this data belongs to (string) + + + + Indicates the direction the device is pointing to when capturing +a media. It is represented as degrees in floating point representation, +0 means the geographic north, and increases clockwise (double from 0 to 360) + +See also #GST_TAG_GEO_LOCATION_MOVEMENT_DIRECTION + + + + The city (english name) where the media has been produced (string). + + + + The country (english name) where the media has been produced (string). + + + + geo elevation of where the media has been recorded or produced in meters +according to WGS84 (zero is average sea level) (double). + + + + Represents the expected error on the horizontal positioning in +meters (double). + + + + geo latitude location of where the media has been recorded or produced in +degrees according to WGS84 (zero at the equator, negative values for southern +latitudes) (double). + + + + geo longitude location of where the media has been recorded or produced in +degrees according to WGS84 (zero at the prime meridian in Greenwich/UK, +negative values for western longitudes). (double). + + + + Indicates the movement direction of the device performing the capture +of a media. It is represented as degrees in floating point representation, +0 means the geographic north, and increases clockwise (double from 0 to 360) + +See also #GST_TAG_GEO_LOCATION_CAPTURE_DIRECTION + + + + Speed of the capturing device when performing the capture. +Represented in m/s. (double) + +See also #GST_TAG_GEO_LOCATION_MOVEMENT_DIRECTION + + + + human readable descriptive location of where the media has been recorded or +produced. (string). + + + + A location 'smaller' than GST_TAG_GEO_LOCATION_CITY that specifies better +where the media has been produced. (e.g. the neighborhood) (string). + +This tag has been added as this is how it is handled/named in XMP's +Iptc4xmpcore schema. + + + + Groups together media that are related and spans multiple tracks. An +example are multiple pieces of a concerto. (string) + + + + Homepage for this media (i.e. artist or movie homepage) (string) + + + + image (sample) (sample taglist should specify the content type and preferably +also set "image-type" field as #GstTagImageType) + + + + Represents the 'Orientation' tag from EXIF. Defines how the image +should be rotated and mirrored for display. (string) + +This tag has a predefined set of allowed values: + "rotate-0" + "rotate-90" + "rotate-180" + "rotate-270" + "flip-rotate-0" + "flip-rotate-90" + "flip-rotate-180" + "flip-rotate-270" + +The naming is adopted according to a possible transformation to perform +on the image to fix its orientation, obviously equivalent operations will +yield the same result. + +Rotations indicated by the values are in clockwise direction and +'flip' means an horizontal mirroring. + + + + Information about the people behind a remix and similar +interpretations of another existing piece (string) + + + + International Standard Recording Code - see http://www.ifpi.org/isrc/ (string) + + + + comma separated keywords describing the content (string). + + + + ISO-639-2 or ISO-639-1 code for the language the content is in (string) + +There is utility API in libgsttag in gst-plugins-base to obtain a translated +language name from the language code: gst_tag_get_language_name() + + + + Name of the language the content is in (string) + +Free-form name of the language the content is in, if a language code +is not available. This tag should not be set in addition to a language +code. It is undefined what language or locale the language name is in. + + + + license of data (string) + + + + URI to location where license details can be found (string) + + + + Origin of media as a URI (location, where the original of the file or stream +is hosted) (string) + + + + The lyrics of the media (string) + + + + maximum bitrate in bits/s (unsigned integer) + + + + <ulink url="http://en.wikipedia.org/wiki/Note#Note_designation_in_accordance_with_octave_name">Midi note number</ulink> +of the audio track. This is useful for sample instruments and in particular +for multi-samples. + + + + minimum bitrate in bits/s (unsigned integer) + + + + nominal bitrate in bits/s (unsigned integer). The actual bitrate might be +different from this target bitrate. + + + + organization (string) + + + + person(s) performing (string) + + + + image that is meant for preview purposes, e.g. small icon-sized version +(sample) (sample taglist should specify the content type) + + + + Any private data that may be contained in tags (sample). + +It is represented by #GstSample in which #GstBuffer contains the +binary data and the sample's info #GstStructure may contain any +extra information that identifies the origin or meaning of the data. + +Private frames in ID3v2 tags ('PRIV' frames) will be represented +using this tag, in which case the GstStructure will be named +"ID3PrivateFrame" and contain a field named "owner" of type string +which contains the owner-identification string from the tag. + + + + Name of the label or publisher (string) + + + + reference level of track and album gain values (double) + + + + serial number of track (unsigned integer) + + + + Number of the episode within a season/show (unsigned integer) + + + + Name of the show, used for displaying (string) + + + + Number of the season of a show/series (unsigned integer) + + + + Name of the show, used for sorting (string) + + + + codec/format the subtitle data is stored in (string) + + + + commonly used title (string) + +The title as it should be displayed, e.g. 'The Doll House' + + + + commonly used title, as used for sorting (string) + +The title as it should be sorted, e.g. 'Doll House, The' + + + + count of tracks inside collection this track belongs to (unsigned integer) + + + + track gain in db (double) + + + + track number inside a collection (unsigned integer) + + + + peak of the track (double) + + + + Rating attributed by a person (likely the application user). +The higher the value, the more the user likes this media +(unsigned int from 0 to 100) + + + + version of this data (string) + + + + codec the video data is stored in (string) + + + + A string that can be used in printf-like format strings to display a +#GstClockTime value in h:m:s format. Use GST_TIME_ARGS() to construct +the matching arguments. + +Example: +|[<!-- language="C" --> +printf("%" GST_TIME_FORMAT "\n", GST_TIME_ARGS(ts)); +]| + + + + Special value for the repeat_count set in gst_toc_entry_set_loop() or +returned by gst_toc_entry_set_loop() to indicate infinite looping. + + + + Extra tag flags used when registering tags. + + undefined flag + + + tag is meta data + + + tag is encoded + + + tag is decoded + + + number of tag flags + + + + A function that will be called in gst_tag_list_foreach(). The function may +not modify the tag list. + + + + + + the #GstTagList + + + + a name of a tag in @list + + + + user data + + + + + + List of tags and values used to describe media metadata. + +Strings in structures must be ASCII or UTF-8 encoded. Other encodings are +not allowed. Strings must not be empty or %NULL. + + the parent type + + + + Creates a new taglist and appends the values for the given tags. It expects +tag-value pairs like gst_tag_list_add(), and a %NULL terminator after the +last pair. The type of the values is implicit and is documented in the API +reference, but can also be queried at runtime with gst_tag_get_type(). It +is an error to pass a value of a type not matching the tag type into this +function. The tag list will make copies of any arguments passed +(e.g. strings, buffers). + +After creation you might also want to set a #GstTagScope on the returned +taglist to signal if the contained tags are global or stream tags. By +default stream scope is assumes. See gst_tag_list_set_scope(). + +Free-function: gst_tag_list_unref + + a new #GstTagList. Free with gst_tag_list_unref() + when no longer needed. + + + + + tag + + + + %NULL-terminated list of values to set + + + + + + Creates a new empty GstTagList. + +Free-function: gst_tag_list_unref + + An empty tag list + + + + + Deserializes a tag list. + + a new #GstTagList, or %NULL in case of an +error. + + + + + a string created with gst_tag_list_to_string() + + + + + + Just like gst_tag_list_new(), only that it takes a va_list argument. +Useful mostly for language bindings. + +Free-function: gst_tag_list_unref + + a new #GstTagList. Free with gst_tag_list_unref() + when no longer needed. + + + + + tag / value pairs to set + + + + + + Sets the values for the given tags using the specified mode. + + + + + + list to set tags in + + + + the mode to use + + + + tag + + + + %NULL-terminated list of values to set + + + + + + Sets the values for the given tags using the specified mode. + + + + + + list to set tags in + + + + the mode to use + + + + tag + + + + tag / value pairs to set + + + + + + Sets the GValues for the given tags using the specified mode. + + + + + + list to set tags in + + + + the mode to use + + + + tag + + + + tag / GValue pairs to set + + + + + + Sets the GValue for a given tag using the specified mode. + + + + + + list to set tags in + + + + the mode to use + + + + tag + + + + GValue for this tag + + + + + + Sets the GValues for the given tags using the specified mode. + + + + + + list to set tags in + + + + the mode to use + + + + tag + + + + GValues to set + + + + + + 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. + + + + + + list to iterate over + + + + function to be called for each tag + + + + user specified data + + + + + + Copies the contents for the given tag into the value, merging multiple values +into one if multiple values are associated with the tag. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + location for the result + + + + + + Gets the value that is at the given index for the given tag in the given +list. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + 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 +needed. + +Free-function: g_date_free + + %TRUE, if a date was copied, %FALSE if the tag didn't exist in the + given list or if it was %NULL. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + address of a GDate pointer + variable to store the result into + + + + + + 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 +with g_date_free() when it is no longer needed. + +Free-function: g_date_free + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list or if it was %NULL. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + 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 +it is no longer needed. + +Free-function: gst_date_time_unref + + %TRUE, if a datetime was copied, %FALSE if the tag didn't exist in + the given list or if it was %NULL. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + address of a #GstDateTime + pointer variable to store the result into + + + + + + 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 +with gst_date_time_unref() when it is no longer needed. + +Free-function: gst_date_time_unref + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list or if it was %NULL. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + Copies the contents for the given tag into the value, merging multiple values +into one if multiple values are associated with the tag. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + location for the result + + + + + + Gets the value that is at the given index for the given tag in the given +list. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + Copies the contents for the given tag into the value, merging multiple values +into one if multiple values are associated with the tag. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + location for the result + + + + + + Gets the value that is at the given index for the given tag in the given +list. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + Copies the contents for the given tag into the value, merging multiple values +into one if multiple values are associated with the tag. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + location for the result + + + + + + + + + + + + + + + + + + + + + + Gets the value that is at the given index for the given tag in the given +list. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + Gets the value that is at the given index for the given tag in the given +list. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + Copies the contents for the given tag into the value, merging multiple values +into one if multiple values are associated with the tag. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + location for the result + + + + + + Gets the value that is at the given index for the given tag in the given +list. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + Copies the first sample for the given tag in the taglist into the variable +pointed to by @sample. Free the sample with gst_sample_unref() when it is +no longer needed. You can retrieve the buffer from the sample using +gst_sample_get_buffer() and the associated caps (if any) with +gst_sample_get_caps(). + +Free-function: gst_sample_unref + + %TRUE, if a sample was returned, %FALSE if the tag didn't exist in + the given list or if it was %NULL. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + address of a GstSample + pointer variable to store the result into + + + + + + Gets the sample that is at the given index for the given tag in the given +list and copies it into the variable pointed to by @sample. Free the sample +with gst_sample_unref() when it is no longer needed. You can retrieve the +buffer from the sample using gst_sample_get_buffer() and the associated +caps (if any) with gst_sample_get_caps(). + +Free-function: gst_sample_unref + + %TRUE, if a sample was copied, %FALSE if the tag didn't exist in the + given list or if it was %NULL. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + address of a GstSample + pointer variable to store the result into + + + + + + Gets the scope of @list. + + The scope of @list + + + + + a #GstTagList + + + + + + Copies the contents for the given tag into the value, possibly merging +multiple values into one if multiple values are associated with the tag. + +Use gst_tag_list_get_string_index (list, tag, 0, value) if you want +to retrieve the first string associated with this tag unmodified. + +The resulting string in @value will be in UTF-8 encoding and should be +freed by the caller using g_free when no longer needed. The +returned string is also guaranteed to be non-%NULL and non-empty. + +Free-function: g_free + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + location for the result + + + + + + Gets the value that is at the given index for the given tag in the given +list. + +The resulting string in @value will be in UTF-8 encoding and should be +freed by the caller using g_free when no longer needed. The +returned string is also guaranteed to be non-%NULL and non-empty. + +Free-function: g_free + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + Checks how many value are stored in this tag list for the given tag. + + The number of tags stored + + + + + a taglist + + + + the tag to query + + + + + + Copies the contents for the given tag into the value, merging multiple values +into one if multiple values are associated with the tag. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + location for the result + + + + + + Copies the contents for the given tag into the value, merging multiple values +into one if multiple values are associated with the tag. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + location for the result + + + + + + Gets the value that is at the given index for the given tag in the given +list. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + Gets the value that is at the given index for the given tag in the given +list. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + Gets the value that is at the given index for the given tag in the given +list. + + The GValue for the specified + entry or %NULL if the tag wasn't available or the tag + doesn't have as many entries + + + + + a #GstTagList + + + + tag to read out + + + + number of entry to read out + + + + + + Inserts the tags of the @from list into the first list using the given mode. + + + + + + list to merge into + + + + list to merge from + + + + the mode to use + + + + + + Checks if the given taglist is empty. + + %TRUE if the taglist is empty, otherwise %FALSE. + + + + + A #GstTagList. + + + + + + Checks if the two given taglists are equal. + + %TRUE if the taglists are equal, otherwise %FALSE + + + + + a #GstTagList. + + + + a #GstTagList. + + + + + + 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. + +Free-function: gst_tag_list_unref + + the new list + + + + + first list to merge + + + + second list to merge + + + + the mode to use + + + + + + Get the number of tags in @list. + + The number of tags in @list. + + + + + A #GstTagList. + + + + + + Get the name of the tag in @list at @index. + + The name of the tag at @index. + + + + + A #GstTagList. + + + + the index + + + + + + Peeks at the value that is at the given index for the given tag in the given +list. + +The resulting string in @value will be in UTF-8 encoding and doesn't need +to be freed by the caller. The returned string is also guaranteed to +be non-%NULL and non-empty. + + %TRUE, if a value was set, %FALSE if the tag didn't exist in the + given list. + + + + + a #GstTagList to get the tag from + + + + tag to read out + + + + number of entry to read out + + + + location for the result + + + + + + Removes the given tag from the taglist. + + + + + + list to remove tag from + + + + tag to remove + + + + + + Sets the scope of @list to @scope. By default the scope +of a taglist is stream scope. + + + + + + a #GstTagList + + + + new scope for @list + + + + + + Serializes a tag list to a string. + + a newly-allocated string, or %NULL in case of + an error. The string must be freed with g_free() when no longer + needed. + + + + + a #GstTagList + + + + + + Copies the contents for the given tag into the value, +merging multiple values into one if multiple values are associated +with the tag. +You must g_value_unset() the value after use. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + uninitialized #GValue to copy into + + + + list to get the tag from + + + + tag to read out + + + + + + + A function for merging multiple values of a tag used when registering +tags. + + + + + + the destination #GValue + + + + the source #GValue + + + + + + The different tag merging modes are basically replace, overwrite and append, +but they can be seen from two directions. Given two taglists: (A) the tags +already in the element and (B) the ones that are supplied to the element ( +e.g. via gst_tag_setter_merge_tags() / gst_tag_setter_add_tags() or a +%GST_EVENT_TAG), how are these tags merged? +In the table below this is shown for the cases that a tag exists in the list +(A) or does not exists (!A) and combinations thereof. + +<table frame="all" colsep="1" rowsep="1"> + <title>merge mode</title> + <tgroup cols='5' align='left'> + <thead> + <row> + <entry>merge mode</entry> + <entry>A + B</entry> + <entry>A + !B</entry> + <entry>!A + B</entry> + <entry>!A + !B</entry> + </row> + </thead> + <tbody> + <row> + <entry>REPLACE_ALL</entry> + <entry>B</entry> + <entry>-</entry> + <entry>B</entry> + <entry>-</entry> + </row> + <row> + <entry>REPLACE</entry> + <entry>B</entry> + <entry>A</entry> + <entry>B</entry> + <entry>-</entry> + </row> + <row> + <entry>APPEND</entry> + <entry>A, B</entry> + <entry>A</entry> + <entry>B</entry> + <entry>-</entry> + </row> + <row> + <entry>PREPEND</entry> + <entry>B, A</entry> + <entry>A</entry> + <entry>B</entry> + <entry>-</entry> + </row> + <row> + <entry>KEEP</entry> + <entry>A</entry> + <entry>A</entry> + <entry>B</entry> + <entry>-</entry> + </row> + <row> + <entry>KEEP_ALL</entry> + <entry>A</entry> + <entry>A</entry> + <entry>-</entry> + <entry>-</entry> + </row> + </tbody> + </tgroup> +</table> + + undefined merge mode + + + replace all tags (clear list and append) + + + replace tags + + + append tags + + + prepend tags + + + keep existing tags + + + keep all existing tags + + + the number of merge modes + + + + GstTagScope specifies if a taglist applies to the complete +medium or only to one single stream. + + tags specific to this single stream + + + global tags for the complete medium + + + + Element interface that allows setting of media metadata. + +Elements that support changing a stream's metadata will implement this +interface. Examples of such elements are 'vorbisenc', 'theoraenc' and +'id3v2mux'. + +If you just want to retrieve metadata in your application then all you +need to do is watch for tag messages on your pipeline's bus. This +interface is only for setting metadata, not for extracting it. To set tags +from the application, find tagsetter elements and set tags using e.g. +gst_tag_setter_merge_tags() or gst_tag_setter_add_tags(). Also consider +setting the #GstTagMergeMode that is used for tag events that arrive at the +tagsetter element (default mode is to keep existing tags). +The application should do that before the element goes to %GST_STATE_PAUSED. + +Elements implementing the #GstTagSetter interface often have to merge +any tags received from upstream and the tags set by the application via +the interface. This can be done like this: + +|[<!-- language="C" --> +GstTagMergeMode merge_mode; +const GstTagList *application_tags; +const GstTagList *event_tags; +GstTagSetter *tagsetter; +GstTagList *result; + +tagsetter = GST_TAG_SETTER (element); + +merge_mode = gst_tag_setter_get_tag_merge_mode (tagsetter); +application_tags = gst_tag_setter_get_tag_list (tagsetter); +event_tags = (const GstTagList *) element->event_tags; + +GST_LOG_OBJECT (tagsetter, "merging tags, merge mode = %d", merge_mode); +GST_LOG_OBJECT (tagsetter, "event tags: %" GST_PTR_FORMAT, event_tags); +GST_LOG_OBJECT (tagsetter, "set tags: %" GST_PTR_FORMAT, application_tags); + +result = gst_tag_list_merge (application_tags, event_tags, merge_mode); + +GST_LOG_OBJECT (tagsetter, "final tags: %" GST_PTR_FORMAT, result); +]| + + + Adds the given tag / value pairs on the setter using the given merge mode. +The list must be terminated with %NULL. + + + + + + a #GstTagSetter + + + + the mode to use + + + + tag to set + + + + tag / value pairs to set + + + + + + Adds the given tag / GValue pairs on the setter using the given merge mode. +The list must be terminated with %NULL. + + + + + + a #GstTagSetter + + + + the mode to use + + + + tag to set + + + + tag / GValue pairs to set + + + + + + Adds the given tag / GValue pair on the setter using the given merge mode. + + + + + + a #GstTagSetter + + + + the mode to use + + + + tag to set + + + + GValue to set for the tag + + + + + + Adds the given tag / GValue pairs on the setter using the given merge mode. +The list must be terminated with %NULL. + + + + + + a #GstTagSetter + + + + the mode to use + + + + tag to set + + + + more tag / GValue pairs to set + + + + + + Adds the given tag / value pairs on the setter using the given merge mode. +The list must be terminated with %NULL. + + + + + + a #GstTagSetter + + + + the mode to use + + + + tag to set + + + + more tag / value pairs to set + + + + + + Returns the current list of tags the setter uses. The list should not be +modified or freed. + +This function is not thread-safe. + + a current snapshot of the + taglist used in the setter or %NULL if none is used. + + + + + a #GstTagSetter + + + + + + Queries the mode by which tags inside the setter are overwritten by tags +from events + + the merge mode used inside the element. + + + + + a #GstTagSetter + + + + + + Merges the given list into the setter's list using the given mode. + + + + + + a #GstTagSetter + + + + a tag list to merge from + + + + the mode to merge with + + + + + + Reset the internal taglist. Elements should call this from within the +state-change handler. + + + + + + a #GstTagSetter + + + + + + Sets the given merge mode that is used for adding tags from events to tags +specified by this interface. The default is #GST_TAG_MERGE_KEEP, which keeps +the tags set with this interface and discards tags from events. + + + + + + a #GstTagSetter + + + + The mode with which tags are added + + + + + + + #GstTagSetterInterface interface. + + parent interface type. + + + + + #GstTask is used by #GstElement and #GstPad to provide the data passing +threads in a #GstPipeline. + +A #GstPad will typically start a #GstTask to push or pull data to/from the +peer pads. Most source elements start a #GstTask to push data. In some cases +a demuxer element can start a #GstTask to pull data from a peer element. This +is typically done when the demuxer can perform random access on the upstream +peer element for improved performance. + +Although convenience functions exist on #GstPad to start/pause/stop tasks, it +might sometimes be needed to create a #GstTask manually if it is not related to +a #GstPad. + +Before the #GstTask can be run, it needs a #GRecMutex that can be set with +gst_task_set_lock(). + +The task can be started, paused and stopped with gst_task_start(), gst_task_pause() +and gst_task_stop() respectively or with the gst_task_set_state() function. + +A #GstTask will repeatedly call the #GstTaskFunction with the user data +that was provided when creating the task with gst_task_new(). While calling +the function it will acquire the provided lock. The provided lock is released +when the task pauses or stops. + +Stopping a task with gst_task_stop() will not immediately make sure the task is +not running anymore. Use gst_task_join() to make sure the task is completely +stopped and the thread is stopped. + +After creating a #GstTask, use gst_object_unref() to free its resources. This can +only be done when the task is not running anymore. + +Task functions can send a #GstMessage to send out-of-band data to the +application. The application can receive messages from the #GstBus in its +mainloop. + +For debugging purposes, the task will configure its object name as the thread +name on Linux. Please note that the object name should be configured before the +task is started; changing the object name after the task has been started, has +no effect on the thread name. + + Create a new Task that will repeatedly call the provided @func +with @user_data as a parameter. Typically the task will run in +a new thread. + +The function cannot be changed after the task has been created. You +must create a new #GstTask to change the function. + +This function will not yet create and start a thread. Use gst_task_start() or +gst_task_pause() to create and start the GThread. + +Before the task can be used, a #GRecMutex must be configured using the +gst_task_set_lock() function. This lock will always be acquired while +@func is called. + + A new #GstTask. + +MT safe. + + + + + The #GstTaskFunction to use + + + + User data to pass to @func + + + + the function to call when @user_data is no longer needed. + + + + + + Wait for all tasks to be stopped. This is mainly used internally +to ensure proper cleanup of internal data structures in test suites. + +MT safe. + + + + + + Get the #GstTaskPool that this task will use for its streaming +threads. + +MT safe. + + the #GstTaskPool used by @task. gst_object_unref() +after usage. + + + + + a #GstTask + + + + + + Get the current state of the task. + + The #GstTaskState of the task + +MT safe. + + + + + The #GstTask to query + + + + + + Joins @task. After this call, it is safe to unref the task +and clean up the lock set with gst_task_set_lock(). + +The task will automatically be stopped with this call. + +This function cannot be called from within a task function as this +would cause a deadlock. The function will detect this and print a +g_warning. + + %TRUE if the task could be joined. + +MT safe. + + + + + The #GstTask to join + + + + + + Pauses @task. This method can also be called on a task in the +stopped state, in which case a thread will be started and will remain +in the paused state. This function does not wait for the task to complete +the paused state. + + %TRUE if the task could be paused. + +MT safe. + + + + + The #GstTask to pause + + + + + + Call @enter_func when the task function of @task is entered. @user_data will +be passed to @enter_func and @notify will be called when @user_data is no +longer referenced. + + + + + + The #GstTask to use + + + + a #GstTaskThreadFunc + + + + user data passed to @enter_func + + + + called when @user_data is no longer referenced + + + + + + Call @leave_func when the task function of @task is left. @user_data will +be passed to @leave_func and @notify will be called when @user_data is no +longer referenced. + + + + + + The #GstTask to use + + + + a #GstTaskThreadFunc + + + + user data passed to @leave_func + + + + called when @user_data is no longer referenced + + + + + + Set the mutex used by the task. The mutex will be acquired before +calling the #GstTaskFunction. + +This function has to be called before calling gst_task_pause() or +gst_task_start(). + +MT safe. + + + + + + The #GstTask to use + + + + The #GRecMutex to use + + + + + + Set @pool as the new GstTaskPool for @task. Any new streaming threads that +will be created by @task will now use @pool. + +MT safe. + + + + + + a #GstTask + + + + a #GstTaskPool + + + + + + Sets the state of @task to @state. + +The @task must have a lock associated with it using +gst_task_set_lock() when going to GST_TASK_STARTED or GST_TASK_PAUSED or +this function will return %FALSE. + +MT safe. + + %TRUE if the state could be changed. + + + + + a #GstTask + + + + the new task state + + + + + + Starts @task. The @task must have a lock associated with it using +gst_task_set_lock() or this function will return %FALSE. + + %TRUE if the task could be started. + +MT safe. + + + + + The #GstTask to start + + + + + + Stops @task. This method merely schedules the task to stop and +will not wait for the task to have completely stopped. Use +gst_task_join() to stop and wait for completion. + + %TRUE if the task could be stopped. + +MT safe. + + + + + The #GstTask to stop + + + + + + + + + the state of the task + + + + used to pause/resume the task + + + + The lock taken when iterating the task function + + + + the function executed by this task + + + + user_data passed to the task function + + + + GDestroyNotify for @user_data + + + + a flag indicating that the task is running + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A function that will repeatedly be called in the thread created by +a #GstTask. + + + + + + user data passed to the function + + + + + + This object provides an abstraction for creating threads. The default +implementation uses a regular GThreadPool to start tasks. + +Subclasses can be made to create custom threads. + + Create a new default task pool. The default task pool will use a regular +GThreadPool for threads. + + a new #GstTaskPool. gst_object_unref() after usage. + + + + + Wait for all tasks to be stopped. This is mainly used internally +to ensure proper cleanup of internal data structures in test suites. + +MT safe. + + + + + + a #GstTaskPool + + + + + + Join a task and/or return it to the pool. @id is the id obtained from +gst_task_pool_push(). + + + + + + a #GstTaskPool + + + + the id + + + + + + Prepare the taskpool for accepting gst_task_pool_push() operations. + +MT safe. + + + + + + a #GstTaskPool + + + + + + Start the execution of a new thread from @pool. + + a pointer that should be used +for the gst_task_pool_join function. This pointer can be %NULL, you +must check @error to detect errors. + + + + + a #GstTaskPool + + + + the function to call + + + + data to pass to @func + + + + + + Wait for all tasks to be stopped. This is mainly used internally +to ensure proper cleanup of internal data structures in test suites. + +MT safe. + + + + + + a #GstTaskPool + + + + + + Join a task and/or return it to the pool. @id is the id obtained from +gst_task_pool_push(). + + + + + + a #GstTaskPool + + + + the id + + + + + + Prepare the taskpool for accepting gst_task_pool_push() operations. + +MT safe. + + + + + + a #GstTaskPool + + + + + + Start the execution of a new thread from @pool. + + a pointer that should be used +for the gst_task_pool_join function. This pointer can be %NULL, you +must check @error to detect errors. + + + + + a #GstTaskPool + + + + the function to call + + + + data to pass to @func + + + + + + + + + + + + + + + + + + The #GstTaskPoolClass object. + + the parent class structure + + + + + + + + + + a #GstTaskPool + + + + + + + + + + + + + a #GstTaskPool + + + + + + + + + a pointer that should be used +for the gst_task_pool_join function. This pointer can be %NULL, you +must check @error to detect errors. + + + + + a #GstTaskPool + + + + the function to call + + + + data to pass to @func + + + + + + + + + + + + + a #GstTaskPool + + + + the id + + + + + + + + + + + + + Task function, see gst_task_pool_push(). + + + + + + user data for the task function + + + + + + + + The different states a task can be in + + the task is started and running + + + the task is stopped + + + the task is paused + + + + Custom GstTask thread callback functions that can be installed. + + + + + + The #GstTask + + + + The #GThread + + + + user data + + + + + + Structure for saving a timestamp and a value. + + timestamp of the value change + + + + the corresponding value + + + + + #GstToc functions are used to create/free #GstToc and #GstTocEntry structures. +Also they are used to convert #GstToc into #GstStructure and vice versa. + +#GstToc lets you to inform other elements in pipeline or application that playing +source has some kind of table of contents (TOC). These may be chapters, editions, +angles or other types. For example: DVD chapters, Matroska chapters or cue sheet +TOC. Such TOC will be useful for applications to display instead of just a +playlist. + +Using TOC is very easy. Firstly, create #GstToc structure which represents root +contents of the source. You can also attach TOC-specific tags to it. Then fill +it with #GstTocEntry entries by appending them to the #GstToc using +gst_toc_append_entry(), and appending subentries to a #GstTocEntry using +gst_toc_entry_append_sub_entry(). + +Note that root level of the TOC can contain only either editions or chapters. You +should not mix them together at the same level. Otherwise you will get serialization +/deserialization errors. Make sure that no one of the entries has negative start and + stop values. + +Use gst_event_new_toc() to create a new TOC #GstEvent, and gst_event_parse_toc() to +parse received TOC event. Use gst_event_new_toc_select() to create a new TOC select #GstEvent, +and gst_event_parse_toc_select() to parse received TOC select event. The same rule for +the #GstMessage: gst_message_new_toc() to create new TOC #GstMessage, and +gst_message_parse_toc() to parse received TOC message. + +TOCs can have global scope or current scope. Global scope TOCs contain +all entries that can possibly be selected using a toc select event, and +are what an application is usually interested in. TOCs with current scope +only contain the parts of the TOC relevant to the currently selected/playing +stream; the current scope TOC is used by downstream elements such as muxers +to write correct TOC entries when transcoding files, for example. When +playing a DVD, the global TOC would contain a hierarchy of all titles, +chapters and angles, for example, while the current TOC would only contain +the chapters for the currently playing title if playback of a specific +title was requested. + +Applications and plugins should not rely on TOCs having a certain kind of +structure, but should allow for different alternatives. For example, a +simple CUE sheet embedded in a file may be presented as a flat list of +track entries, or could have a top-level edition node (or some other +alternative type entry) with track entries underneath that node; or even +multiple top-level edition nodes (or some other alternative type entries) +each with track entries underneath, in case the source file has extracted +a track listing from different sources). + + Create a new #GstToc structure. + + newly allocated #GstToc structure, free it + with gst_toc_unref(). + + + + + scope of this TOC + + + + + + Appends the #GstTocEntry @entry to @toc. + + + + + + A #GstToc instance + + + + A #GstTocEntry + + + + + + + + + + + + + + + + Find #GstTocEntry with given @uid in the @toc. + + #GstTocEntry with specified +@uid from the @toc, or %NULL if not found. + + + + + #GstToc to search in. + + + + UID to find #GstTocEntry with. + + + + + + Gets the list of #GstTocEntry of @toc. + + A #GList of #GstTocEntry for @entry + + + + + + + A #GstToc instance + + + + + + + scope of @toc + + + + + a #GstToc instance + + + + + + Gets the tags for @toc. + + A #GstTagList for @entry + + + + + A #GstToc instance + + + + + + Merge @tags into the existing tags of @toc using @mode. + + + + + + A #GstToc instance + + + + A #GstTagList or %NULL + + + + A #GstTagMergeMode + + + + + + Set a #GstTagList with tags for the complete @toc. + + + + + + A #GstToc instance + + + + A #GstTagList or %NULL + + + + + + + + Create new #GstTocEntry structure. + + newly allocated #GstTocEntry structure, free it with gst_toc_entry_unref(). + + + + + entry type. + + + + unique ID (UID) in the whole TOC. + + + + + + Appends the #GstTocEntry @subentry to @entry. + + + + + + A #GstTocEntry instance + + + + A #GstTocEntry + + + + + + + @entry's entry type + + + + + a #GstTocEntry + + + + + + Get @loop_type and @repeat_count values from the @entry and write them into +appropriate storages. Loops are e.g. used by sampled instruments. GStreamer +is not automatically applying the loop. The application can process this +meta data and use it e.g. to send a seek-event to loop a section. + + %TRUE if all non-%NULL storage pointers were filled with appropriate +values, %FALSE otherwise. + + + + + #GstTocEntry to get values from. + + + + the storage for the loop_type + value, leave %NULL if not need. + + + + the storage for the repeat_count + value, leave %NULL if not need. + + + + + + Gets the parent #GstTocEntry of @entry. + + The parent #GstTocEntry of @entry + + + + + A #GstTocEntry instance + + + + + + Get @start and @stop values from the @entry and write them into appropriate +storages. + + %TRUE if all non-%NULL storage pointers were filled with appropriate +values, %FALSE otherwise. + + + + + #GstTocEntry to get values from. + + + + the storage for the start value, leave + %NULL if not need. + + + + the storage for the stop value, leave + %NULL if not need. + + + + + + Gets the sub-entries of @entry. + + A #GList of #GstTocEntry of @entry + + + + + + + A #GstTocEntry instance + + + + + + Gets the tags for @entry. + + A #GstTagList for @entry + + + + + A #GstTocEntry instance + + + + + + Gets the parent #GstToc of @entry. + + The parent #GstToc of @entry + + + + + A #GstTocEntry instance + + + + + + Gets the UID of @entry. + + The UID of @entry + + + + + A #GstTocEntry instance + + + + + + + %TRUE if @entry's type is an alternative type, otherwise %FALSE + + + + + a #GstTocEntry + + + + + + + %TRUE if @entry's type is a sequence type, otherwise %FALSE + + + + + a #GstTocEntry + + + + + + Merge @tags into the existing tags of @entry using @mode. + + + + + + A #GstTocEntry instance + + + + A #GstTagList or %NULL + + + + A #GstTagMergeMode + + + + + + Set @loop_type and @repeat_count values for the @entry. + + + + + + #GstTocEntry to set values. + + + + loop_type value to set. + + + + repeat_count value to set. + + + + + + Set @start and @stop values for the @entry. + + + + + + #GstTocEntry to set values. + + + + start value to set. + + + + stop value to set. + + + + + + Set a #GstTagList with tags for the complete @entry. + + + + + + A #GstTocEntry instance + + + + A #GstTagList or %NULL + + + + + + + The different types of TOC entries (see #GstTocEntry). + +There are two types of TOC entries: alternatives or parts in a sequence. + + entry is an angle (i.e. an alternative) + + + entry is a version (i.e. alternative) + + + entry is an edition (i.e. alternative) + + + invalid entry type value + + + entry is a title (i.e. a part of a sequence) + + + entry is a track (i.e. a part of a sequence) + + + entry is a chapter (i.e. a part of a sequence) + + + Converts @type to a string representation. + + Returns a human-readable string for @type. This string is + only for debugging purpose and should not be displayed in a user + interface. + + + + + a #GstTocEntryType. + + + + + + + How a #GstTocEntry should be repeated. By default, entries are played a +single time. + + single forward playback + + + repeat forward + + + repeat backward + + + repeat forward and backward + + + + The scope of a TOC. + + global TOC representing all selectable options + (this is what applications are usually interested in) + + + TOC for the currently active/selected stream + (this is a TOC representing the current stream from start to EOS, + and is what a TOC writer / muxer is usually interested in; it will + usually be a subset of the global TOC, e.g. just the chapters of + the current title, or the chapters selected for playback from the + current title) + + + + Element interface that allows setting of the TOC. + +Elements that support some kind of chapters or editions (or tracks like in +the FLAC cue sheet) will implement this interface. + +If you just want to retrieve the TOC in your application then all you +need to do is watch for TOC messages on your pipeline's bus (or you can +perform TOC query). This interface is only for setting TOC data, not for +extracting it. To set TOC from the application, find proper tocsetter element +and set TOC using gst_toc_setter_set_toc(). + +Elements implementing the #GstTocSetter interface can extend existing TOC +by getting extend UID for that (you can use gst_toc_find_entry() to retrieve it) +with any TOC entries received from downstream. + + + Return current TOC the setter uses. The TOC should not be +modified without making it writable first. + + TOC set, or %NULL. Unref with + gst_toc_unref() when no longer needed + + + + + a #GstTocSetter. + + + + + + Reset the internal TOC. Elements should call this from within the +state-change handler. + + + + + + a #GstTocSetter. + + + + + + Set the given TOC on the setter. Previously set TOC will be +unreffed before setting a new one. + + + + + + a #GstTocSetter. + + + + a #GstToc to set. + + + + + + + #GstTocSetterInterface interface. + + parent interface type. + + + + + Tracing modules will subclass #GstTracer and register through +gst_tracing_register(). Modules can attach to various hook-types - see +gst_tracing_register_hook(). When invoked they receive hook specific +contextual data, which they must not modify. + + + + + + + + + + + + + + + + + + + + + + + + + + + Use gst_tracer_factory_get_list() to get a list of tracer factories known to +GStreamer. + + Gets the list of all registered tracer factories. You must free the +list using gst_plugin_feature_list_free(). + +The returned factories are sorted by factory name. + +Free-function: gst_plugin_feature_list_free + + the list of all + registered #GstTracerFactory. + + + + + + + + + + + + Tracing modules will create instances of this class to announce the data they +will log and create a log formatter. + + + + + Flag that describe the value. These flags help applications processing the +logs to understand the values. + + no flags + + + the value is optional. When using this flag + one need to have an additional boolean arg before this value in the + var-args list passed to gst_tracer_record_log(). + + + the value is a combined figure, since the + start of tracing. Examples are averages or timestamps. + + + + Tracing record will contain fields that contain a meassured value or extra +meta-data. One such meta data are values that tell where a measurement was +taken. This enumerating declares to which scope such a meta data field +relates to. If it is e.g. %GST_TRACER_VALUE_SCOPE_PAD, then each of the log +events may contain values for different #GstPads. + + the value is related to the process + + + the value is related to a thread + + + the value is related to an #GstElement + + + the value is related to a #GstPad + + + + The following functions allow you to detect the media type of an unknown +stream. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The data used by the caller of the typefinding function. + + + + + + + + + + + + + + + + + + + + + Get the length of the data stream. + + The length of the data stream, or 0 if it is not available. + + + + + The #GstTypeFind the function was called with + + + + + + Returns the @size bytes of the stream to identify beginning at offset. If +offset is a positive number, the offset is relative to the beginning of the +stream, if offset is a negative number the offset is relative to the end of +the stream. The returned memory is valid until the typefinding function +returns and must not be freed. + + the + requested data, or %NULL if that data is not available. + + + + + + + The #GstTypeFind object the function was called with + + + + The offset + + + + The number of bytes to return + + + + + + If a #GstTypeFindFunction calls this function it suggests the caps with the +given probability. A #GstTypeFindFunction may supply different suggestions +in one call. +It is up to the caller of the #GstTypeFindFunction to interpret these values. + + + + + + The #GstTypeFind object the function was called with + + + + The probability in percent that the suggestion is right + + + + The fixed #GstCaps to suggest + + + + + + If a #GstTypeFindFunction calls this function it suggests the caps with the +given probability. A #GstTypeFindFunction may supply different suggestions +in one call. It is up to the caller of the #GstTypeFindFunction to interpret +these values. + +This function is similar to gst_type_find_suggest(), only that instead of +passing a #GstCaps argument you can create the caps on the fly in the same +way as you can with gst_caps_new_simple(). + +Make sure you terminate the list of arguments with a %NULL argument and that +the values passed have the correct type (in terms of width in bytes when +passed to the vararg function - this applies particularly to gdouble and +guint64 arguments). + + + + + + The #GstTypeFind object the function was called with + + + + The probability in percent that the suggestion is right + + + + the media type of the suggested caps + + + + first field of the suggested caps, or %NULL + + + + additional arguments to the suggested caps in the same format as the + arguments passed to gst_structure_new() (ie. triplets of field name, + field GType and field value) + + + + + + Registers a new typefind function to be used for typefinding. After +registering this function will be available for typefinding. +This function is typically called during an element's plugin initialization. + + %TRUE on success, %FALSE otherwise + + + + + A #GstPlugin, or %NULL for a static typefind function + + + + The name for registering + + + + The rank (or importance) of this typefind function + + + + The #GstTypeFindFunction to use + + + + Optional comma-separated list of extensions + that could belong to this type + + + + Optionally the caps that could be returned when typefinding + succeeds + + + + Optional user data. This user data must be available until the plugin + is unloaded. + + + + a #GDestroyNotify that will be called on @data when the plugin + is unloaded. + + + + + + + These functions allow querying informations about registered typefind +functions. How to create and register these functions is described in +the section <link linkend="gstreamer-Writing-typefind-functions"> +"Writing typefind functions"</link>. + +The following example shows how to write a very simple typefinder that +identifies the given data. You can get quite a bit more complicated than +that though. +|[<!-- language="C" --> + typedef struct { + guint8 *data; + guint size; + guint probability; + GstCaps *data; + } MyTypeFind; + static void + my_peek (gpointer data, gint64 offset, guint size) + { + MyTypeFind *find = (MyTypeFind *) data; + if (offset &gt;= 0 &amp;&amp; offset + size &lt;= find->size) { + return find->data + offset; + } + return NULL; + } + static void + my_suggest (gpointer data, guint probability, GstCaps *caps) + { + MyTypeFind *find = (MyTypeFind *) data; + if (probability &gt; find->probability) { + find->probability = probability; + gst_caps_replace (&amp;find->caps, caps); + } + } + static GstCaps * + find_type (guint8 *data, guint size) + { + GList *walk, *type_list; + MyTypeFind find = {data, size, 0, NULL}; + GstTypeFind gst_find = {my_peek, my_suggest, &amp;find, }; + walk = type_list = gst_type_find_factory_get_list (); + while (walk) { + GstTypeFindFactory *factory = GST_TYPE_FIND_FACTORY (walk->data); + walk = g_list_next (walk) + gst_type_find_factory_call_function (factory, &amp;gst_find); + } + g_list_free (type_list); + return find.caps; + }; +]| + + Gets the list of all registered typefind factories. You must free the +list using gst_plugin_feature_list_free(). + +The returned factories are sorted by highest rank first, and then by +factory name. + +Free-function: gst_plugin_feature_list_free + + the list of all + registered #GstTypeFindFactory. + + + + + + + Calls the #GstTypeFindFunction associated with this factory. + + + + + + A #GstTypeFindFactory + + + + a properly setup #GstTypeFind entry. The get_data + and suggest_type members must be set. + + + + + + Gets the #GstCaps associated with a typefind factory. + + the #GstCaps associated with this factory + + + + + A #GstTypeFindFactory + + + + + + Gets the extensions associated with a #GstTypeFindFactory. The returned +array should not be changed. If you need to change stuff in it, you should +copy it using g_strdupv(). This function may return %NULL to indicate +a 0-length list. + + + a %NULL-terminated array of extensions associated with this factory + + + + + + + A #GstTypeFindFactory + + + + + + Check whether the factory has a typefind function. Typefind factories +without typefind functions are a last-effort fallback mechanism to +e.g. assume a certain media type based on the file extension. + + %TRUE if the factory has a typefind functions set, otherwise %FALSE + + + + + A #GstTypeFindFactory + + + + + + + + + A function that will be called by typefinding. + + + + + + A #GstTypeFind structure + + + + optional data to pass to the function + + + + + + The probability of the typefind function. Higher values have more certainty +in doing a reliable typefind. + + type undetected. + + + unlikely typefind. + + + possible type detected. + + + likely a type was detected. + + + nearly certain that a type was detected. + + + very certain a type was detected. + + + + Different URI-related errors that can occur. + + The protocol is not supported + + + There was a problem with the URI + + + Could not set or change the URI because the + URI handler was in a state where that is not possible or not permitted + + + There was a problem with the entity that + the URI references + + + + + + + + + The #GstURIHandler is an interface that is implemented by Source and Sink +#GstElement to unify handling of URI. + +An application can use the following functions to quickly get an element +that handles the given URI for reading or writing +(gst_element_make_from_uri()). + +Source and Sink plugins should implement this interface when possible. + + Gets the currently handled URI. + + the URI currently handled by + the @handler. Returns %NULL if there are no URI currently + handled. The returned string must be freed with g_free() when no + longer needed. + + + + + A #GstURIHandler + + + + + + Tries to set the URI of the given handler. + + %TRUE if the URI was set successfully, else %FALSE. + + + + + A #GstURIHandler + + + + URI to set + + + + + + Gets the list of protocols supported by @handler. This list may not be +modified. + + the + supported protocols. Returns %NULL if the @handler isn't + implemented properly, or the @handler doesn't support any + protocols. + + + + + + + A #GstURIHandler. + + + + + + Gets the currently handled URI. + + the URI currently handled by + the @handler. Returns %NULL if there are no URI currently + handled. The returned string must be freed with g_free() when no + longer needed. + + + + + A #GstURIHandler + + + + + + Gets the type of the given URI handler + + the #GstURIType of the URI handler. +Returns #GST_URI_UNKNOWN if the @handler isn't implemented correctly. + + + + + A #GstURIHandler. + + + + + + Tries to set the URI of the given handler. + + %TRUE if the URI was set successfully, else %FALSE. + + + + + A #GstURIHandler + + + + URI to set + + + + + + + Any #GstElement using this interface should implement these methods. + + The parent interface type + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + the URI currently handled by + the @handler. Returns %NULL if there are no URI currently + handled. The returned string must be freed with g_free() when no + longer needed. + + + + + A #GstURIHandler + + + + + + + + + %TRUE if the URI was set successfully, else %FALSE. + + + + + A #GstURIHandler + + + + URI to set + + + + + + + + The different types of URI direction. + + The URI direction is unknown + + + The URI is a consumer. + + + The URI is a producer. + + + + Value for #GstUri<!-- -->.port to indicate no port number. + + + + Constant that defines one GStreamer microsecond. + + + + A #GstUri object can be used to parse and split a URI string into its +constituant parts. Two #GstUri objects can be joined to make a new #GstUri +using the algorithm described in RFC3986. + + Creates a new #GstUri object with the given URI parts. The path and query +strings will be broken down into their elements. All strings should not be +escaped except where indicated. + + A new #GstUri object. + + + + + The scheme for the new URI. + + + + The user-info for the new URI. + + + + The host name for the new URI. + + + + The port number for the new URI or %GST_URI_NO_PORT. + + + + The path for the new URI with '/' separating path + elements. + + + + The query string for the new URI with '&' separating + query elements. Elements containing '&' characters + should encode them as "&percnt;26". + + + + The fragment name for the new URI. + + + + + + Append a path onto the end of the path in the URI. The path is not +normalized, call #gst_uri_normalize() to normalize the path. + + %TRUE if the path was appended successfully. + + + + + The #GstUri to modify. + + + + Relative path to append to the end of the current path. + + + + + + Append a single path segment onto the end of the URI path. + + %TRUE if the path was appended successfully. + + + + + The #GstUri to modify. + + + + The path segment string to append to the URI path. + + + + + + Compares two #GstUri objects to see if they represent the same normalized +URI. + + %TRUE if the normalized versions of the two URI's would be equal. + + + + + First #GstUri to compare. + + + + Second #GstUri to compare. + + + + + + Like gst_uri_from_string() but also joins with a base URI. + + A new #GstUri object. + + + + + The base URI to join the new URI with. + + + + The URI string to parse. + + + + + + Get the fragment name from the URI or %NULL if it doesn't exist. +If @uri is %NULL then returns %NULL. + + The host name from the #GstUri object or %NULL. + + + + + This #GstUri object. + + + + + + Get the host name from the URI or %NULL if it doesn't exist. +If @uri is %NULL then returns %NULL. + + The host name from the #GstUri object or %NULL. + + + + + This #GstUri object. + + + + + + Get the media fragment table from the URI, as defined by "Media Fragments URI 1.0". +Hash table returned by this API is a list of "key-value" pairs, and the each +pair is generated by splitting "URI fragment" per "&" sub-delims, then "key" +and "value" are splitted by "=" sub-delims. The "key" returned by this API may +be undefined keyword by standard. +A value may be %NULL to indicate that the key should appear in the fragment +string in the URI, but does not have a value. Free the returned #GHashTable +with #g_hash_table_unref() when it is no longer required. +Modifying this hash table does not affect the fragment in the URI. + +See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frags/ + + The fragment hash table + from the URI. + + + + + + + + The #GstUri to get the fragment table from. + + + + + + Extract the path string from the URI object. + + The path from the URI. Once finished with the + string should be g_free()'d. + + + + + The #GstUri to get the path from. + + + + + + Get a list of path segments from the URI. + + A #GList of path segment + strings or %NULL if no path segments are available. Free the list + when no longer needed with g_list_free_full(list, g_free). + + + + + + + The #GstUri to get the path from. + + + + + + Extract the path string from the URI object as a percent encoded URI path. + + The path from the URI. Once finished with the + string should be g_free()'d. + + + + + The #GstUri to get the path from. + + + + + + Get the port number from the URI or %GST_URI_NO_PORT if it doesn't exist. +If @uri is %NULL then returns %GST_URI_NO_PORT. + + The port number from the #GstUri object or %GST_URI_NO_PORT. + + + + + This #GstUri object. + + + + + + Get a list of the query keys from the URI. + + A list of keys from + the URI query. Free the list with g_list_free(). + + + + + + + The #GstUri to examine. + + + + + + Get a percent encoded URI query string from the @uri. + + A percent encoded query string. Use g_free() when + no longer needed. + + + + + The #GstUri to get the query string from. + + + + + + Get the query table from the URI. Keys and values in the table are freed +with g_free when they are deleted. A value may be %NULL to indicate that +the key should appear in the query string in the URI, but does not have a +value. Free the returned #GHashTable with #g_hash_table_unref() when it is +no longer required. Modifying this hash table will modify the query in the +URI. + + The query hash table + from the URI. + + + + + + + + The #GstUri to get the query table from. + + + + + + Get the value associated with the @query_key key. Will return %NULL if the +key has no value or if the key does not exist in the URI query table. Because +%NULL is returned for both missing keys and keys with no value, you should +use gst_uri_query_has_key() to determine if a key is present in the URI +query. + + The value for the given key, or %NULL if not found. + + + + + The #GstUri to examine. + + + + The key to lookup. + + + + + + Get the scheme name from the URI or %NULL if it doesn't exist. +If @uri is %NULL then returns %NULL. + + The scheme from the #GstUri object or %NULL. + + + + + This #GstUri object. + + + + + + Get the userinfo (usually in the form "username:password") from the URI +or %NULL if it doesn't exist. If @uri is %NULL then returns %NULL. + + The userinfo from the #GstUri object or %NULL. + + + + + This #GstUri object. + + + + + + Tests the @uri to see if it is normalized. A %NULL @uri is considered to be +normalized. + + TRUE if the URI is normalized or is %NULL. + + + + + The #GstUri to test to see if it is normalized. + + + + + + Check if it is safe to write to this #GstUri. + +Check if the refcount of @uri is exactly 1, meaning that no other +reference exists to the #GstUri and that the #GstUri is therefore writable. + +Modification of a #GstUri should only be done after verifying that it is +writable. + + %TRUE if it is safe to write to the object. + + + + + The #GstUri object to test. + + + + + + Join a reference URI onto a base URI using the method from RFC 3986. +If either URI is %NULL then the other URI will be returned with the ref count +increased. + + A #GstUri which represents the base with the + reference URI joined on. + + + + + The base URI to join another to. + + + + The reference URI to join onto the + base URI. + + + + + + Make the #GstUri writable. + +Checks if @uri is writable, and if so the original object is returned. If +not, then a writable copy is made and returned. This gives away the +reference to @uri and returns a reference to the new #GstUri. +If @uri is %NULL then %NULL is returned. + + A writable version of @uri. + + + + + The #GstUri object to make writable. + + + + + + Like gst_uri_new(), but joins the new URI onto a base URI. + + The new URI joined onto @base. + + + + + The base URI to join the new URI to. + + + + The scheme for the new URI. + + + + The user-info for the new URI. + + + + The host name for the new URI. + + + + The port number for the new URI or %GST_URI_NO_PORT. + + + + The path for the new URI with '/' separating path + elements. + + + + The query string for the new URI with '&' separating + query elements. Elements containing '&' characters + should encode them as "&percnt;26". + + + + The fragment name for the new URI. + + + + + + Normalization will remove extra path segments ("." and "..") from the URI. It +will also convert the scheme and host name to lower case and any +percent-encoded values to uppercase. + +The #GstUri object must be writable. Check with gst_uri_is_writable() or use +gst_uri_make_writable() first. + + TRUE if the URI was modified. + + + + + The #GstUri to normalize. + + + + + + Check if there is a query table entry for the @query_key key. + + %TRUE if @query_key exists in the URI query table. + + + + + The #GstUri to examine. + + + + The key to lookup. + + + + + + Remove an entry from the query table by key. + + %TRUE if the key existed in the table and was removed. + + + + + The #GstUri to modify. + + + + The key to remove. + + + + + + Sets the fragment string in the URI. Use a value of %NULL in @fragment to +unset the fragment string. + + %TRUE if the fragment was set/unset successfully. + + + + + The #GstUri to modify. + + + + The fragment string to set. + + + + + + Set or unset the host for the URI. + + %TRUE if the host was set/unset successfully. + + + + + The #GstUri to modify. + + + + The new host string to set or %NULL to unset. + + + + + + Sets or unsets the path in the URI. + + %TRUE if the path was set successfully. + + + + + The #GstUri to modify. + + + + The new path to set with path segments separated by '/', or use %NULL + to unset the path. + + + + + + Replace the path segments list in the URI. + + %TRUE if the path segments were set successfully. + + + + + The #GstUri to modify. + + + + The new + path list to set. + + + + + + + + Sets or unsets the path in the URI. + + %TRUE if the path was set successfully. + + + + + The #GstUri to modify. + + + + The new percent encoded path to set with path segments separated by +'/', or use %NULL to unset the path. + + + + + + Set or unset the port number for the URI. + + %TRUE if the port number was set/unset successfully. + + + + + The #GstUri to modify. + + + + The new port number to set or %GST_URI_NO_PORT to unset. + + + + + + Sets or unsets the query table in the URI. + + %TRUE if the query table was set successfully. + + + + + The #GstUri to modify. + + + + The new percent encoded query string to use to populate the query + table, or use %NULL to unset the query table. + + + + + + Set the query table to use in the URI. The old table is unreferenced and a +reference to the new one is used instead. A value if %NULL for @query_table +will remove the query string from the URI. + + %TRUE if the new table was sucessfully used for the query table. + + + + + The #GstUri to modify. + + + + The new + query table to use. + + + + + + + + + This inserts or replaces a key in the query table. A @query_value of %NULL +indicates that the key has no associated value, but will still be present in +the query string. + + %TRUE if the query table was sucessfully updated. + + + + + The #GstUri to modify. + + + + The key for the query entry. + + + + The value for the key. + + + + + + Set or unset the scheme for the URI. + + %TRUE if the scheme was set/unset successfully. + + + + + The #GstUri to modify. + + + + The new scheme to set or %NULL to unset the scheme. + + + + + + Set or unset the user information for the URI. + + %TRUE if the user information was set/unset successfully. + + + + + The #GstUri to modify. + + + + The new user-information string to set or %NULL to unset. + + + + + + Convert the URI to a string. + +Returns the URI as held in this object as a #gchar* nul-terminated string. +The caller should g_free() the string once they are finished with it. +The string is put together as described in RFC 3986. + + The string version of the URI. + + + + + This #GstUri to convert to a string. + + + + + + Constructs a URI for a given valid protocol and location. + +Free-function: g_free + + a new string for this URI. Returns %NULL if the + given URI protocol is not valid, or the given location is %NULL. + + + + + Protocol for URI + + + + Location for URI + + + + + + Parses a URI string into a new #GstUri object. Will return NULL if the URI +cannot be parsed. + + A new #GstUri object, or NULL. + + + + + The URI string to parse. + + + + + + Extracts the location out of a given valid URI, ie. the protocol and "://" +are stripped from the URI, which means that the location returned includes +the hostname if one is specified. The returned string must be freed using +g_free(). + +Free-function: g_free + + 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. + + + + + A URI string + + + + + + Extracts the protocol out of a given valid URI. The returned string must be +freed using g_free(). + + The protocol for this URI. + + + + + A URI string + + + + + + Checks if the protocol of a given valid URI matches @protocol. + + %TRUE if the protocol matches. + + + + + a URI string + + + + a protocol string (e.g. "http") + + + + + + Tests if the given string is a valid URI identifier. URIs start with a valid +scheme followed by ":" and maybe a string identifying the location. + + %TRUE if the string is a valid URI + + + + + A URI string + + + + + + This is a convenience function to join two URI strings and return the result. +The returned string should be g_free()'d after use. + + A string representing the percent-encoded join of + the two URIs. + + + + + The percent-encoded base URI. + + + + The percent-encoded reference URI to join to the @base_uri. + + + + + + Checks if an element exists that supports the given URI protocol. Note +that a positive return value does not imply that a subsequent call to +gst_element_make_from_uri() is guaranteed to work. + + %TRUE + + + + + Whether to check for a source or a sink + + + + Protocol that should be checked for (e.g. "http" or "smb") + + + + + + Tests if the given string is a valid protocol identifier. Protocols +must consist of alphanumeric characters, '+', '-' and '.' and must +start with a alphabetic character. See RFC 3986 Section 3.1. + + %TRUE if the string is a valid protocol identifier, %FALSE otherwise. + + + + + A string + + + + + + + Indicates that the first value provided to a comparison function +(gst_value_compare()) is equal to the second one. + + + + Indicates that the first value provided to a comparison function +(gst_value_compare()) is greater than the second one. + + + + Indicates that the first value provided to a comparison function +(gst_value_compare()) is lesser than the second one. + + + + Indicates that the comparison function (gst_value_compare()) can not +determine a order for the two provided values. + + + + The major version of GStreamer at compile time: + + + + The micro version of GStreamer at compile time: + + + + The minor version of GStreamer at compile time: + + + + The nano version of GStreamer at compile time: +Actual releases have 0, GIT versions have 1, prerelease versions have 2-... + + + + + Appends @append_value to the GstValueArray in @value. + + + + + + a #GValue of type #GST_TYPE_ARRAY + + + + the value to append + + + + + + Appends @append_value to the GstValueArray in @value. + + + + + + a #GValue of type #GST_TYPE_ARRAY + + + + the value to append + + + + + + Gets the number of values contained in @value. + + the number of values + + + + + a #GValue of type #GST_TYPE_ARRAY + + + + + + Gets the value that is a member of the array contained in @value and +has the index @index. + + the value at the given index + + + + + a #GValue of type #GST_TYPE_ARRAY + + + + index of value to get from the array + + + + + + Prepends @prepend_value to the GstValueArray in @value. + + + + + + a #GValue of type #GST_TYPE_ARRAY + + + + the value to prepend + + + + + + + Used together with gst_value_compare() to compare #GValue items. + + one of GST_VALUE_LESS_THAN, GST_VALUE_EQUAL, GST_VALUE_GREATER_THAN +or GST_VALUE_UNORDERED + + + + + first value for comparison + + + + second value for comparison + + + + + + Used by gst_value_deserialize() to parse a non-binary form into the #GValue. + + %TRUE for success + + + + + a #GValue + + + + a string + + + + + + + Appends @append_value to the GstValueList in @value. + + + + + + a #GValue of type #GST_TYPE_LIST + + + + the value to append + + + + + + Appends @append_value to the GstValueList in @value. + + + + + + a #GValue of type #GST_TYPE_LIST + + + + the value to append + + + + + + Concatenates copies of @value1 and @value2 into a list. Values that are not +of type #GST_TYPE_LIST are treated as if they were lists of length 1. +@dest will be initialized to the type #GST_TYPE_LIST. + + + + + + an uninitialized #GValue to take the result + + + + a #GValue + + + + a #GValue + + + + + + Gets the number of values contained in @value. + + the number of values + + + + + a #GValue of type #GST_TYPE_LIST + + + + + + Gets the value that is a member of the list contained in @value and +has the index @index. + + the value at the given index + + + + + a #GValue of type #GST_TYPE_LIST + + + + index of value to get from the list + + + + + + Merges copies of @value1 and @value2. Values that are not +of type #GST_TYPE_LIST are treated as if they were lists of length 1. + +The result will be put into @dest and will either be a list that will not +contain any duplicates, or a non-list type (if @value1 and @value2 +were equal). + + + + + + an uninitialized #GValue to take the result + + + + a #GValue + + + + a #GValue + + + + + + Prepends @prepend_value to the GstValueList in @value. + + + + + + a #GValue of type #GST_TYPE_LIST + + + + the value to prepend + + + + + + + Used by gst_value_serialize() to obtain a non-binary form of the #GValue. + +Free-function: g_free + + the string representation of the value + + + + + a #GValue + + + + + + VTable for the #GValue @type. + + a #GType + + + + a #GstValueCompareFunc + + + + a #GstValueSerializeFunc + + + + a #GstValueDeserializeFunc + + + + + + + + + + Get the maximum amount of memory blocks that a buffer can hold. This is a +compile time constant that can be queried with the function. + +When more memory blocks are added, existing memory blocks will be merged +together to make room for the new block. + + the maximum amount of memory blocks that a buffer can hold. + + + + + Calculates the linear regression of the values @xy and places the +result in @m_num, @m_denom, @b and @xbase, representing the function + y(x) = m_num/m_denom * (x - xbase) + b +that has the least-square distance from all points @x and @y. + +@r_squared will contain the remaining error. + +If @temp is not %NULL, it will be used as temporary space for the function, +in which case the function works without any allocation at all. If @temp is +%NULL, an allocation will take place. @temp should have at least the same +amount of memory allocated as @xy, i.e. 2*n*sizeof(GstClockTime). + +> This function assumes (x,y) values with reasonable large differences +> between them. It will not calculate the exact results if the differences +> between neighbouring values are too small due to not being able to +> represent sub-integer values during the calculations. + + %TRUE if the linear regression was successfully calculated + + + + + Pairs of (x,y) values + + + + Temporary scratch space used by the function + + + + number of (x,y) pairs + + + + numerator of calculated slope + + + + denominator of calculated slope + + + + Offset at Y-axis + + + + Offset at X-axis + + + + R-squared + + + + + + Creates a #GstCapsFeatures from a string representation. + +Free-function: gst_caps_features_free + + a new #GstCapsFeatures or + %NULL when the string could not be parsed. Free with + gst_caps_features_free() after use. + + + + + a string representation of a #GstCapsFeatures. + + + + + + Converts @caps from a string representation. + +The current implementation of serialization will lead to unexpected results +when there are nested #GstCaps / #GstStructure deeper than one level. + + a newly allocated #GstCaps + + + + + a string to convert to #GstCaps + + + + + + + + + + + Adds the logging function to the list of logging functions. +Be sure to use #G_GNUC_NO_INSTRUMENT on that function, it is needed. + + + + + + the function to use + + + + user data + + + + called when @user_data is not used anymore + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Constructs a string that can be used for getting the desired color in color +terminals. +You need to free the string after use. + + a string containing the color + definition + + + + + the color info + + + + + + Constructs an integer that can be used for getting the desired color in +windows' terminals (cmd.exe). As there is no mean to underline, we simply +ignore this attribute. + +This function returns 0 on non-windows machines. + + an integer containing the color definition + + + + + the color info + + + + + + Returns a snapshot of a all categories that are currently in use . This list +may change anytime. +The caller has to free the list after use. + + the list of + debug categories + + + + + + + Changes the coloring mode for debug output. + + see @GstDebugColorMode for possible values. + + + + + Returns the default threshold that is used for new categories. + + the default threshold level + + + + + If libunwind or glibc backtrace are present, a stack trace +is returned. + + + + + + A set of #GstStackTraceFlags to determine how the stack +trace should look like. Pass 0 to retrieve a minimal backtrace. + + + + + + Checks if debugging output is activated. + + %TRUE, if debugging is activated + + + + + Checks if the debugging output should be colored. + + %TRUE, if the debug output should be colored. + + + + + Get the string representation of a debugging level + + the name + + + + + the level to get the name for + + + + + + Logs the given message using the currently registered debugging handlers. + + + + + + category to log + + + + level of the message is in + + + + the file that emitted the message, usually the __FILE__ identifier + + + + the function that emitted the message + + + + the line from that the message was emitted, usually __LINE__ + + + + the object this message relates to, + or %NULL if none + + + + a printf style format string + + + + optional arguments for the format + + + + + + The default logging handler used by GStreamer. Logging functions get called +whenever a macro like GST_DEBUG or similar is used. By default this function +is setup to output the message and additional info to stderr (or the log file +specified via the GST_DEBUG_FILE environment variable) as received via +@user_data. + +You can add other handlers by using gst_debug_add_log_function(). +And you can remove this handler by calling +gst_debug_remove_log_function(gst_debug_log_default); + + + + + + category to log + + + + level of the message + + + + the file that emitted the message, usually the __FILE__ identifier + + + + the function that emitted the message + + + + the line from that the message was emitted, usually __LINE__ + + + + the object this message relates to, + or %NULL if none + + + + the actual message + + + + the FILE* to log to + + + + + + Logs the given message using the currently registered debugging handlers. + + + + + + category to log + + + + level of the message is in + + + + the file that emitted the message, usually the __FILE__ identifier + + + + the function that emitted the message + + + + the line from that the message was emitted, usually __LINE__ + + + + the object this message relates to, + or %NULL if none + + + + a printf style format string + + + + optional arguments for the format + + + + + + If libunwind or glibc backtrace are present +a stack trace is printed. + + + + + + Removes all registered instances of the given logging functions. + + How many instances of the function were removed + + + + + the log function to remove, or %NULL to + remove the default log function + + + + + + Removes all registered instances of log functions with the given user data. + + How many instances of the function were removed + + + + + user data of the log function to remove + + + + + + If activated, debugging messages are sent to the debugging +handlers. +It makes sense to deactivate it for speed issues. +> This function is not threadsafe. It makes sense to only call it +during initialization. + + + + + + Whether to use debugging output or not + + + + + + Changes the coloring mode for debug output. + +This function may be called before gst_init(). + + + + + + The coloring mode for debug output. See @GstDebugColorMode. + + + + + + Changes the coloring mode for debug output. + +This function may be called before gst_init(). + + + + + + The coloring mode for debug output. One of the following: +"on", "auto", "off", "disable", "unix". + + + + + + Sets or unsets the use of coloured debugging output. +Same as gst_debug_set_color_mode () with the argument being +being GST_DEBUG_COLOR_MODE_ON or GST_DEBUG_COLOR_MODE_OFF. + +This function may be called before gst_init(). + + + + + + Whether to use colored output or not + + + + + + Sets the default threshold to the given level and updates all categories to +use this threshold. + +This function may be called before gst_init(). + + + + + + level to set + + + + + + Sets all categories which match the given glob style pattern to the given +level. + + + + + + name of the categories to set + + + + level to set them to + + + + + + Sets the debug logging wanted in the same form as with the GST_DEBUG +environment variable. You can use wildcards such as '*', but note that +the order matters when you use wild cards, e.g. "foosrc:6,*src:3,*:2" sets +everything to log level 2. + + + + + + comma-separated list of "category:level" pairs to be used + as debug logging levels + + + + %TRUE to clear all previously-set debug levels before setting + new thresholds +%FALSE if adding the threshold described by @list to the one already set. + + + + + + Resets all categories with the given name back to the default level. + + + + + + name of the categories to set + + + + + + Clean up any resources created by GStreamer in gst_init(). + +It is normally not needed to call this function in a normal application +as the resources will automatically be freed when the program terminates. +This function is therefore mostly used by testsuites and other memory +profiling tools. + +After this call GStreamer (including this method) should not be used anymore. + + + + + + + + + + + + + + + + + + + Get a string describing the error message in the current locale. + + a newly allocated string describing + the error message (in UTF-8 encoding) + + + + + the GStreamer error domain this error belongs to. + + + + the error code belonging to the domain. + + + + + + Gets the #GstEventTypeFlags associated with @type. + + a #GstEventTypeFlags. + + + + + a #GstEventType + + + + + + Get a printable name for the given event type. Do not modify or free. + + a reference to the static name of the event. + + + + + the event type + + + + + + Get the unique quark for the given event type. + + the quark associated with the event type + + + + + the event type + + + + + + Similar to g_filename_to_uri(), but attempts to handle relative file paths +as well. Before converting @filename into an URI, it will be prefixed by +the current working directory if it is a relative path, and then the path +will be canonicalised so that it doesn't contain any './' or '../' segments. + +On Windows #filename should be in UTF-8 encoding. + + newly-allocated URI string, or NULL on error. The caller must + free the URI string with g_free() when no longer needed. + + + + + absolute or relative file name path + + + + + + Gets a string representing the given flow return. + + a static string with the name of the flow return. + + + + + a #GstFlowReturn to get the name of. + + + + + + Get the unique quark for the given GstFlowReturn. + + the quark associated with the flow return or 0 if an +invalid return was specified. + + + + + a #GstFlowReturn to get the quark of. + + + + + + Return the format registered with the given nick. + + The format with @nick or GST_FORMAT_UNDEFINED +if the format was not registered. + + + + + The nick of the format + + + + + + Get details about the given format. + + The #GstFormatDefinition for @format or %NULL +on failure. + +MT safe. + + + + + The format to get details of + + + + + + Get a printable name for the given format. Do not modify or free. + + a reference to the static name of the format +or %NULL if the format is unknown. + + + + + a #GstFormat + + + + + + Iterate all the registered formats. The format definition is read +only. + + a GstIterator of #GstFormatDefinition. + + + + + Create a new GstFormat based on the nick or return an +already registered format with that nick. + + A new GstFormat or an already registered format +with the same nick. + +MT safe. + + + + + The nick of the new format + + + + The description of the new format + + + + + + Get the unique quark for the given format. + + the quark associated with the format or 0 if the format +is unknown. + + + + + a #GstFormat + + + + + + See if the given format is inside the format array. + + %TRUE if the format is found inside the array + + + + + The format array to search + + + + + + the format to find + + + + + + Allocates, fills and returns a 0-terminated string from the printf style +@format string and corresponding arguments. + +See gst_info_vasprintf() for when this function is required. + +Free with g_free(). + + a newly allocated null terminated string or %NULL on any error + + + + + a printf style format string + + + + the printf arguments for @format + + + + + + Allocates, fills and returns a null terminated string from the printf style +@format string and @args. + +See gst_info_vasprintf() for when this function is required. + +Free with g_free(). + + a newly allocated null terminated string or %NULL on any error + + + + + a printf style format string + + + + the va_list of printf arguments for @format + + + + + + Allocates and fills a string large enough (including the terminating null +byte) to hold the specified printf style @format and @args. + +This function deals with the GStreamer specific printf specifiers +#GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. If you do not have these specifiers +in your @format string, you do not need to use this function and can use +alternatives such as g_vasprintf(). + +Free @result with g_free(). + + the length of the string allocated into @result or -1 on any error + + + + + the resulting string + + + + a printf style format string + + + + the va_list of printf arguments for @format + + + + + + Initializes the GStreamer library, setting up internal path lists, +registering built-in elements, and loading standard plugins. + +Unless the plugin registry is disabled at compile time, the registry will be +loaded. By default this will also check if the registry cache needs to be +updated and rescan all plugins if needed. See gst_update_registry() for +details and section +<link linkend="gst-running">Running GStreamer Applications</link> +for how to disable automatic registry updates. + +> This function will terminate your program if it was unable to initialize +> GStreamer for some reason. If you want your program to fall back, +> use gst_init_check() instead. + +WARNING: This function does not work in the same way as corresponding +functions in other glib-style libraries, such as gtk_init\(\). In +particular, unknown command line options cause this function to +abort program execution. + + + + + + pointer to application's argc + + + + pointer to application's argv + + + + + + + + Initializes the GStreamer library, setting up internal path lists, +registering built-in elements, and loading standard plugins. + +This function will return %FALSE if GStreamer could not be initialized +for some reason. If you want your program to fail fatally, +use gst_init() instead. + + %TRUE if GStreamer could be initialized. + + + + + pointer to application's argc + + + + pointer to application's argv + + + + + + + + Returns a #GOptionGroup with GStreamer's argument specifications. The +group is set up to use standard GOption callbacks, so when using this +group in combination with GOption parsing methods, all argument parsing +and initialization is automated. + +This function is useful if you want to integrate GStreamer with other +libraries that use GOption (see g_option_context_add_group() ). + +If you use this function, you should make sure you initialise the GLib +threading system as one of the very first things in your program +(see the example at the beginning of this section). + + a pointer to GStreamer's option group. + + + + + + + + + + + + + + + Use this function to check if GStreamer has been initialized with gst_init() +or gst_init_check(). + + %TRUE if initialization has been done, %FALSE otherwise. + + + + + + + + + + + + + + + + + + + + + + + Get a printable name for the given message type. Do not modify or free. + + a reference to the static name of the message. + + + + + the message type + + + + + + Get the unique quark for the given message type. + + the quark associated with the message type + + + + + the message type + + + + + + + an array of tags as strings. + + + + + + + an API + + + + + + Check if @api was registered with @tag. + + %TRUE if @api was registered with @tag. + + + + + an API + + + + the tag to check + + + + + + Register and return a GType for the @api and associate it with +@tags. + + a unique GType for @api. + + + + + an API to register + + + + tags for @api + + + + + + Lookup a previously registered meta info structure by its implementation name +@impl. + + a #GstMetaInfo with @impl, or +%NULL when no such metainfo exists. + + + + + the name + + + + + + Register a new #GstMeta implementation. + +The same @info can be retrieved later with gst_meta_get_info() by using +@impl as the key. + + a #GstMetaInfo that can be used to access metadata. + + + + + the type of the #GstMeta API + + + + the name of the #GstMeta implementation + + + + the size of the #GstMeta structure + + + + a #GstMetaInitFunction + + + + a #GstMetaFreeFunction + + + + a #GstMetaTransformFunction + + + + + + Atomically modifies a pointer to point to a new mini-object. +The reference count of @olddata is decreased and the reference count of +@newdata is increased. + +Either @newdata and the value pointed to by @olddata may be %NULL. + + %TRUE if @newdata was different from @olddata + + + + + pointer to a pointer to a + mini-object to be replaced + + + + pointer to new mini-object + + + + + + Replace the current #GstMiniObject pointer to by @olddata with %NULL and +return the old value. + + the #GstMiniObject at @oldata + + + + + pointer to a pointer to a mini-object to + be stolen + + + + + + Modifies a pointer to point to a new mini-object. The modification +is done atomically. This version is similar to gst_mini_object_replace() +except that it does not increase the refcount of @newdata and thus +takes ownership of @newdata. + +Either @newdata and the value pointed to by @olddata may be %NULL. + + %TRUE if @newdata was different from @olddata + + + + + pointer to a pointer to a mini-object to + be replaced + + + + pointer to new mini-object + + + + + + Return the name of a pad mode, for use in debug messages mostly. + + short mnemonic for pad mode @mode + + + + + the pad mode + + + + + + This function creates a GstArray GParamSpec for use by objects/elements +that want to expose properties of GstArray type. This function is +typically * used in connection with g_object_class_install_property() in a +GObjects's instance_init function. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + GParamSpec of the array + + + + flags for the property specified + + + + + + This function creates a fraction GParamSpec for use by objects/elements +that want to expose properties of fraction type. This function is typically +used in connection with g_object_class_install_property() in a GObjects's +instance_init function. + + a newly created parameter specification + + + + + canonical name of the property specified + + + + nick name for the property specified + + + + description of the property specified + + + + minimum value (fraction numerator) + + + + minimum value (fraction denominator) + + + + maximum value (fraction numerator) + + + + maximum value (fraction denominator) + + + + default value (fraction numerator) + + + + default value (fraction denominator) + + + + flags for the property specified + + + + + + + + + + + Get the global #GstMetaInfo describing the #GstParentBufferMeta meta. + + The #GstMetaInfo + + + + + This is a convenience wrapper around gst_parse_launch() to create a +#GstBin from a gst-launch-style pipeline description. See +gst_parse_launch() and the gst-launch man page for details about the +syntax. Ghost pads on the bin for unlinked source or sink pads +within the bin can automatically be created (but only a maximum of +one ghost pad for each direction will be created; if you expect +multiple unlinked source pads or multiple unlinked sink pads +and want them all ghosted, you will have to create the ghost pads +yourself). + + a + newly-created bin, or %NULL if an error occurred. + + + + + command line describing the bin + + + + whether to automatically create ghost pads + for unlinked source or sink pads within the bin + + + + + + This is a convenience wrapper around gst_parse_launch() to create a +#GstBin from a gst-launch-style pipeline description. See +gst_parse_launch() and the gst-launch man page for details about the +syntax. Ghost pads on the bin for unlinked source or sink pads +within the bin can automatically be created (but only a maximum of +one ghost pad for each direction will be created; if you expect +multiple unlinked source pads or multiple unlinked sink pads +and want them all ghosted, you will have to create the ghost pads +yourself). + + a newly-created + element, which is guaranteed to be a bin unless + GST_FLAG_NO_SINGLE_ELEMENT_BINS was passed, or %NULL if an error + occurred. + + + + + command line describing the bin + + + + whether to automatically create ghost pads + for unlinked source or sink pads within the bin + + + + a parse context allocated with + gst_parse_context_new(), or %NULL + + + + parsing options, or #GST_PARSE_FLAG_NONE + + + + + + Get the error quark used by the parsing subsystem. + + the quark of the parse errors. + + + + + Create a new pipeline based on command line syntax. +Please note that you might get a return value that is not %NULL even though +the @error is set. In this case there was a recoverable parsing error and you +can try to play the pipeline. + + a new element on success, %NULL on failure. If + more than one toplevel element is specified by the @pipeline_description, + all elements are put into a #GstPipeline, which than is returned. + + + + + the command line describing the pipeline + + + + + + Create a new pipeline based on command line syntax. +Please note that you might get a return value that is not %NULL even though +the @error is set. In this case there was a recoverable parsing error and you +can try to play the pipeline. + + a new element on success, %NULL on failure. If + more than one toplevel element is specified by the @pipeline_description, + all elements are put into a #GstPipeline, which then is returned (unless + the GST_PARSE_FLAG_PLACE_IN_BIN flag is set, in which case they are put + in a #GstBin instead). + + + + + the command line describing the pipeline + + + + a parse context allocated with + gst_parse_context_new(), or %NULL + + + + parsing options, or #GST_PARSE_FLAG_NONE + + + + + + Create a new element based on command line syntax. +@error will contain an error message if an erroneous pipeline is specified. +An error does not mean that the pipeline could not be constructed. + + a new element on success and %NULL on failure. + + + + + null-terminated array of arguments + + + + + + + + Create a new element based on command line syntax. +@error will contain an error message if an erroneous pipeline is specified. +An error does not mean that the pipeline could not be constructed. + + a new element on success; on failure, either %NULL + or a partially-constructed bin or element will be returned and @error will + be set (unless you passed #GST_PARSE_FLAG_FATAL_ERRORS in @flags, then + %NULL will always be returned on failure) + + + + + null-terminated array of arguments + + + + + + a parse context allocated with + gst_parse_context_new(), or %NULL + + + + parsing options, or #GST_PARSE_FLAG_NONE + + + + + + Get the error quark. + + The error quark used in GError messages + + + + + Create a new file descriptor set. If @controllable, it +is possible to restart or flush a call to gst_poll_wait() with +gst_poll_restart() and gst_poll_set_flushing() respectively. + +Free-function: gst_poll_free + + a new #GstPoll, or %NULL in + case of an error. Free with gst_poll_free(). + + + + + whether it should be possible to control a wait. + + + + + + Create a new poll object that can be used for scheduling cancellable +timeouts. + +A timeout is performed with gst_poll_wait(). Multiple timeouts can be +performed from different threads. + +Free-function: gst_poll_free + + a new #GstPoll, or %NULL in + case of an error. Free with gst_poll_free(). + + + + + Gets the directory for application specific presets if set by the +application. + + the directory or %NULL, don't free or modify +the string + + + + + Sets an extra directory as an absolute path that should be considered when +looking for presets. Any presets in the application dir will shadow the +system presets. + + %TRUE for success, %FALSE if the dir already has been set + + + + + the application specific preset dir + + + + + + Outputs a formatted message via the GLib print handler. The default print +handler simply outputs the message to stdout. + +This function will not append a new-line character at the end, unlike +gst_println() which will. + +All strings must be in ASCII or UTF-8 encoding. + +This function differs from g_print() in that it supports all the additional +printf specifiers that are supported by GStreamer's debug logging system, +such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. + +This function is primarily for printing debug output. + + + + + + a printf style format string + + + + the printf arguments for @format + + + + + + Outputs a formatted message via the GLib error message handler. The default +handler simply outputs the message to stderr. + +This function will not append a new-line character at the end, unlike +gst_printerrln() which will. + +All strings must be in ASCII or UTF-8 encoding. + +This function differs from g_printerr() in that it supports the additional +printf specifiers that are supported by GStreamer's debug logging system, +such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. + +This function is primarily for printing debug output. + + + + + + a printf style format string + + + + the printf arguments for @format + + + + + + Outputs a formatted message via the GLib error message handler. The default +handler simply outputs the message to stderr. + +This function will append a new-line character at the end, unlike +gst_printerr() which will not. + +All strings must be in ASCII or UTF-8 encoding. + +This function differs from g_printerr() in that it supports the additional +printf specifiers that are supported by GStreamer's debug logging system, +such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. + +This function is primarily for printing debug output. + + + + + + a printf style format string + + + + the printf arguments for @format + + + + + + Outputs a formatted message via the GLib print handler. The default print +handler simply outputs the message to stdout. + +This function will append a new-line character at the end, unlike +gst_print() which will not. + +All strings must be in ASCII or UTF-8 encoding. + +This function differs from g_print() in that it supports all the additional +printf specifiers that are supported by GStreamer's debug logging system, +such as #GST_PTR_FORMAT and #GST_SEGMENT_FORMAT. + +This function is primarily for printing debug output. + + + + + + a printf style format string + + + + the printf arguments for @format + + + + + + + + + + + + + + + + Iterates the supplied list of UUIDs and checks the GstRegistry for +an element that supports one of the supplied UUIDs. If more than one +element matches, the system ID of the highest ranked element is selected. + + One of the strings from @system_identifiers that +indicates the highest ranked element that implements the protection system +indicated by that system ID, or %NULL if no element has been found. + + + + + A null terminated array of strings +that contains the UUID values of each protection system that is to be +checked. + + + + + + Gets the #GstQueryTypeFlags associated with @type. + + a #GstQueryTypeFlags. + + + + + a #GstQueryType + + + + + + Get a printable name for the given query type. Do not modify or free. + + a reference to the static name of the query. + + + + + the query type + + + + + + Get the unique quark for the given query type. + + the quark associated with the query type + + + + + the query type + + + + + + + + + + + Some functions in the GStreamer core might install a custom SIGSEGV handler +to better catch and report errors to the application. Currently this feature +is enabled by default when loading plugins. + +Applications might want to disable this behaviour with the +gst_segtrap_set_enabled() function. This is typically done if the application +wants to install its own handler without GStreamer interfering. + + %TRUE if GStreamer is allowed to install a custom SIGSEGV handler. + + + + + Applications might want to disable/enable the SIGSEGV handling of +the GStreamer core. See gst_segtrap_is_enabled() for more information. + + + + + + whether a custom SIGSEGV handler should be installed. + + + + + + + + + + + + + + + + + + + + + Get a descriptive string for a given #GstStreamType + + A string describing the stream type + + + + + a #GstStreamType + + + + + + Creates a #GstStructure from a string representation. +If end is not %NULL, a pointer to the place inside the given string +where parsing ended will be returned. + +Free-function: gst_structure_free + + a new #GstStructure or %NULL + when the string could not be parsed. Free with + gst_structure_free() after use. + + + + + a string representation of a #GstStructure. + + + + pointer to store the end of the string in. + + + + + + Checks if the given type is already registered. + + %TRUE if the type is already registered + + + + + name of the tag + + + + + + Returns the human-readable description of this tag, You must not change or +free this string. + + the human-readable description of this tag + + + + + the tag + + + + + + Gets the flag of @tag. + + the flag of this tag. + + + + + the tag + + + + + + Returns the human-readable name of this tag, You must not change or free +this string. + + the human-readable name of this tag + + + + + the tag + + + + + + Gets the #GType used for this tag. + + the #GType of this tag + + + + + the tag + + + + + + Checks if the given tag is fixed. A fixed tag can only contain one value. +Unfixed tags can contain lists of values. + + %TRUE, if the given tag is fixed. + + + + + tag to check + + + + + + Copies the contents for the given tag into the value, +merging multiple values into one if multiple values are associated +with the tag. +You must g_value_unset() the value after use. + + %TRUE, if a value was copied, %FALSE if the tag didn't exist in the + given list. + + + + + uninitialized #GValue to copy into + + + + list to get the tag from + + + + tag to read out + + + + + + This is a convenience function for the func argument of gst_tag_register(). +It concatenates all given strings using a comma. The tag must be registered +as a G_TYPE_STRING or this function will fail. + + + + + + uninitialized GValue to store result in + + + + GValue to copy from + + + + + + This is a convenience function for the func argument of gst_tag_register(). +It creates a copy of the first value from the list. + + + + + + uninitialized GValue to store result in + + + + GValue to copy from + + + + + + Registers a new tag type for the use with GStreamer's type system. If a type +with that name is already registered, that one is used. +The old registration may have used a different type however. So don't rely +on your supplied values. + +Important: if you do not supply a merge function the implication will be +that there can only be one single value for this tag in a tag list and +any additional values will silently be discarded when being added (unless +#GST_TAG_MERGE_REPLACE, #GST_TAG_MERGE_REPLACE_ALL, or +#GST_TAG_MERGE_PREPEND is used as merge mode, in which case the new +value will replace the old one in the list). + +The merge function will be called from gst_tag_list_copy_value() when +it is required that one or more values for a tag be condensed into +one single value. This may happen from gst_tag_list_get_string(), +gst_tag_list_get_int(), gst_tag_list_get_double() etc. What will happen +exactly in that case depends on how the tag was registered and if a +merge function was supplied and if so which one. + +Two default merge functions are provided: gst_tag_merge_use_first() and +gst_tag_merge_strings_with_comma(). + + + + + + the name or identifier string + + + + a flag describing the type of tag info + + + + the type this data is in + + + + human-readable name + + + + a human-readable description about this tag + + + + function for merging multiple values of this tag, or %NULL + + + + + + Registers a new tag type for the use with GStreamer's type system. + +Same as gst_tag_register(), but @name, @nick, and @blurb must be +static strings or inlined strings, as they will not be copied. (GStreamer +plugins will be made resident once loaded, so this function can be used +even from dynamically loaded plugins.) + + + + + + the name or identifier string (string constant) + + + + a flag describing the type of tag info + + + + the type this data is in + + + + human-readable name or short description (string constant) + + + + a human-readable description for this tag (string constant) + + + + function for merging multiple values of this tag, or %NULL + + + + + + Converts @type to a string representation. + + Returns a human-readable string for @type. This string is + only for debugging purpose and should not be displayed in a user + interface. + + + + + a #GstTocEntryType. + + + + + + + + + + + Registers a new typefind function to be used for typefinding. After +registering this function will be available for typefinding. +This function is typically called during an element's plugin initialization. + + %TRUE on success, %FALSE otherwise + + + + + A #GstPlugin, or %NULL for a static typefind function + + + + The name for registering + + + + The rank (or importance) of this typefind function + + + + The #GstTypeFindFunction to use + + + + Optional comma-separated list of extensions + that could belong to this type + + + + Optionally the caps that could be returned when typefinding + succeeds + + + + Optional user data. This user data must be available until the plugin + is unloaded. + + + + a #GDestroyNotify that will be called on @data when the plugin + is unloaded. + + + + + + Forces GStreamer to re-scan its plugin paths and update the default +plugin registry. + +Applications will almost never need to call this function, it is only +useful if the application knows new plugins have been installed (or old +ones removed) since the start of the application (or, to be precise, the +first call to gst_init()) and the application wants to make use of any +newly-installed plugins without restarting the application. + +Applications should assume that the registry update is neither atomic nor +thread-safe and should therefore not have any dynamic pipelines running +(including the playbin and decodebin elements) and should also not create +any elements or access the GStreamer registry while the update is in +progress. + +Note that this function may block for a significant amount of time. + + %TRUE if the registry has been updated successfully (does not + imply that there were changes), otherwise %FALSE. + + + + + Constructs a URI for a given valid protocol and location. + +Free-function: g_free + + a new string for this URI. Returns %NULL if the + given URI protocol is not valid, or the given location is %NULL. + + + + + Protocol for URI + + + + Location for URI + + + + + + + + + + + Parses a URI string into a new #GstUri object. Will return NULL if the URI +cannot be parsed. + + A new #GstUri object, or NULL. + + + + + The URI string to parse. + + + + + + Extracts the location out of a given valid URI, ie. the protocol and "://" +are stripped from the URI, which means that the location returned includes +the hostname if one is specified. The returned string must be freed using +g_free(). + +Free-function: g_free + + 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. + + + + + A URI string + + + + + + Extracts the protocol out of a given valid URI. The returned string must be +freed using g_free(). + + The protocol for this URI. + + + + + A URI string + + + + + + Checks if the protocol of a given valid URI matches @protocol. + + %TRUE if the protocol matches. + + + + + a URI string + + + + a protocol string (e.g. "http") + + + + + + Tests if the given string is a valid URI identifier. URIs start with a valid +scheme followed by ":" and maybe a string identifying the location. + + %TRUE if the string is a valid URI + + + + + A URI string + + + + + + This is a convenience function to join two URI strings and return the result. +The returned string should be g_free()'d after use. + + A string representing the percent-encoded join of + the two URIs. + + + + + The percent-encoded base URI. + + + + The percent-encoded reference URI to join to the @base_uri. + + + + + + Checks if an element exists that supports the given URI protocol. Note +that a positive return value does not imply that a subsequent call to +gst_element_make_from_uri() is guaranteed to work. + + %TRUE + + + + + Whether to check for a source or a sink + + + + Protocol that should be checked for (e.g. "http" or "smb") + + + + + + Tests if the given string is a valid protocol identifier. Protocols +must consist of alphanumeric characters, '+', '-' and '.' and must +start with a alphabetic character. See RFC 3986 Section 3.1. + + %TRUE if the string is a valid protocol identifier, %FALSE otherwise. + + + + + A string + + + + + + Searches inside @array for @search_data by using the comparison function +@search_func. @array must be sorted ascending. + +As @search_data is always passed as second argument to @search_func it's +not required that @search_data has the same type as the array elements. + +The complexity of this search function is O(log (num_elements)). + + The address of the found +element or %NULL if nothing was found + + + + + the sorted input array + + + + number of elements in the array + + + + size of every element in bytes + + + + function to compare two elements, @search_data will always be passed as second argument + + + + search mode that should be used + + + + element that should be found + + + + data to pass to @search_func + + + + + + Transforms a #gdouble to a fraction and simplifies +the result. + + + + + + #gdouble to transform + + + + pointer to a #gint to hold the result numerator + + + + pointer to a #gint to hold the result denominator + + + + + + Dumps the memory block into a hex representation. Useful for debugging. + + + + + + a pointer to the memory to dump + + + + the size of the memory block to dump + + + + + + Adds the fractions @a_n/@a_d and @b_n/@b_d and stores +the result in @res_n and @res_d. + + %FALSE on overflow, %TRUE otherwise. + + + + + Numerator of first value + + + + Denominator of first value + + + + Numerator of second value + + + + Denominator of second value + + + + Pointer to #gint to hold the result numerator + + + + Pointer to #gint to hold the result denominator + + + + + + Compares the fractions @a_n/@a_d and @b_n/@b_d and returns +-1 if a < b, 0 if a = b and 1 if a > b. + + -1 if a < b; 0 if a = b; 1 if a > b. + + + + + Numerator of first value + + + + Denominator of first value + + + + Numerator of second value + + + + Denominator of second value + + + + + + Multiplies the fractions @a_n/@a_d and @b_n/@b_d and stores +the result in @res_n and @res_d. + + %FALSE on overflow, %TRUE otherwise. + + + + + Numerator of first value + + + + Denominator of first value + + + + Numerator of second value + + + + Denominator of second value + + + + Pointer to #gint to hold the result numerator + + + + Pointer to #gint to hold the result denominator + + + + + + Transforms a fraction to a #gdouble. + + + + + + Fraction numerator as #gint + + + + Fraction denominator #gint + + + + pointer to a #gdouble for the result + + + + + + + + + + + + + + + + Get a property of type %GST_TYPE_ARRAY and transform it into a +#GValueArray. This allow language bindings to get GST_TYPE_ARRAY +properties which are otherwise not an accessible type. + + + + + + the object to set the array to + + + + the name of the property to set + + + + a return #GValueArray + + + + + + Get a timestamp as GstClockTime to be used for interval measurements. +The timestamp should not be interpreted in any other way. + + the timestamp + + + + + Calculates the greatest common divisor of @a +and @b. + + Greatest common divisor of @a and @b + + + + + First value as #gint + + + + Second value as #gint + + + + + + Calculates the greatest common divisor of @a +and @b. + + Greatest common divisor of @a and @b + + + + + First value as #gint64 + + + + Second value as #gint64 + + + + + + Return a constantly incrementing group id. + +This function is used to generate a new group-id for the +stream-start event. + + A constantly incrementing unsigned integer, which might +overflow back to 0 at some point. + + + + + + + + + + + + + + + Compare two sequence numbers, handling wraparound. + +The current implementation just returns (gint32)(@s1 - @s2). + + A negative number if @s1 is before @s2, 0 if they are equal, or a +positive number if @s1 is after @s2. + + + + + A sequence number. + + + + Another sequence number. + + + + + + Return a constantly incrementing sequence number. + +This function is used internally to GStreamer to be able to determine which +events and messages are "the same". For example, elements may set the seqnum +on a segment-done message to be the same as that of the last seek event, to +indicate that event and the message correspond to the same segment. + + A constantly incrementing 32-bit unsigned integer, which might +overflow back to 0 at some point. Use gst_util_seqnum_compare() to make sure +you handle wraparound correctly. + + + + + Converts the string value to the type of the objects argument and +sets the argument with it. + +Note that this function silently returns if @object has no property named +@name or when @value cannot be converted to the type of the property. + + + + + + the object to set the argument of + + + + the name of the argument to set + + + + the string value to set + + + + + + Transfer a #GValueArray to %GST_TYPE_ARRAY and set this value on the +specified property name. This allow language bindings to set GST_TYPE_ARRAY +properties which are otherwise not an accessible type. + + + + + + the object to set the array to + + + + the name of the property to set + + + + a #GValueArray containing the values + + + + + + Converts the string to the type of the value and +sets the value with it. + +Note that this function is dangerous as it does not return any indication +if the conversion worked or not. + + + + + + the value to set + + + + the string to get the value from + + + + + + Scale @val by the rational number @num / @denom, avoiding overflows and +underflows and without loss of precision. + +This function can potentially be very slow if val and num are both +greater than G_MAXUINT32. + + @val * @num / @denom. In the case of an overflow, this +function returns G_MAXUINT64. If the result is not exactly +representable as an integer it is truncated. See also +gst_util_uint64_scale_round(), gst_util_uint64_scale_ceil(), +gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(), +gst_util_uint64_scale_int_ceil(). + + + + + the number to scale + + + + the numerator of the scale ratio + + + + the denominator of the scale ratio + + + + + + Scale @val by the rational number @num / @denom, avoiding overflows and +underflows and without loss of precision. + +This function can potentially be very slow if val and num are both +greater than G_MAXUINT32. + + @val * @num / @denom. In the case of an overflow, this +function returns G_MAXUINT64. If the result is not exactly +representable as an integer, it is rounded up. See also +gst_util_uint64_scale(), gst_util_uint64_scale_round(), +gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(), +gst_util_uint64_scale_int_ceil(). + + + + + the number to scale + + + + the numerator of the scale ratio + + + + the denominator of the scale ratio + + + + + + Scale @val by the rational number @num / @denom, avoiding overflows and +underflows and without loss of precision. @num must be non-negative and +@denom must be positive. + + @val * @num / @denom. In the case of an overflow, this +function returns G_MAXUINT64. If the result is not exactly +representable as an integer, it is truncated. See also +gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil(), +gst_util_uint64_scale(), gst_util_uint64_scale_round(), +gst_util_uint64_scale_ceil(). + + + + + guint64 (such as a #GstClockTime) to scale. + + + + numerator of the scale factor. + + + + denominator of the scale factor. + + + + + + Scale @val by the rational number @num / @denom, avoiding overflows and +underflows and without loss of precision. @num must be non-negative and +@denom must be positive. + + @val * @num / @denom. In the case of an overflow, this +function returns G_MAXUINT64. If the result is not exactly +representable as an integer, it is rounded up. See also +gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(), +gst_util_uint64_scale(), gst_util_uint64_scale_round(), +gst_util_uint64_scale_ceil(). + + + + + guint64 (such as a #GstClockTime) to scale. + + + + numerator of the scale factor. + + + + denominator of the scale factor. + + + + + + Scale @val by the rational number @num / @denom, avoiding overflows and +underflows and without loss of precision. @num must be non-negative and +@denom must be positive. + + @val * @num / @denom. In the case of an overflow, this +function returns G_MAXUINT64. If the result is not exactly +representable as an integer, it is rounded to the nearest integer +(half-way cases are rounded up). See also gst_util_uint64_scale_int(), +gst_util_uint64_scale_int_ceil(), gst_util_uint64_scale(), +gst_util_uint64_scale_round(), gst_util_uint64_scale_ceil(). + + + + + guint64 (such as a #GstClockTime) to scale. + + + + numerator of the scale factor. + + + + denominator of the scale factor. + + + + + + Scale @val by the rational number @num / @denom, avoiding overflows and +underflows and without loss of precision. + +This function can potentially be very slow if val and num are both +greater than G_MAXUINT32. + + @val * @num / @denom. In the case of an overflow, this +function returns G_MAXUINT64. If the result is not exactly +representable as an integer, it is rounded to the nearest integer +(half-way cases are rounded up). See also gst_util_uint64_scale(), +gst_util_uint64_scale_ceil(), gst_util_uint64_scale_int(), +gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil(). + + + + + the number to scale + + + + the numerator of the scale ratio + + + + the denominator of the scale ratio + + + + + + Determines if @value1 and @value2 can be compared. + + %TRUE if the values can be compared + + + + + a value to compare + + + + another value to compare + + + + + + Determines if intersecting two values will produce a valid result. +Two values will produce a valid intersection if they have the same +type. + + %TRUE if the values can intersect + + + + + a value to intersect + + + + another value to intersect + + + + + + Checks if it's possible to subtract @subtrahend from @minuend. + + %TRUE if a subtraction is possible + + + + + the value to subtract from + + + + the value to subtract + + + + + + Determines if @value1 and @value2 can be non-trivially unioned. +Any two values can be trivially unioned by adding both of them +to a GstValueList. However, certain types have the possibility +to be unioned in a simpler way. For example, an integer range +and an integer can be unioned if the integer is a subset of the +integer range. If there is the possibility that two values can +be unioned, this function returns %TRUE. + + %TRUE if there is a function allowing the two values to +be unioned. + + + + + a value to union + + + + another value to union + + + + + + Compares @value1 and @value2. If @value1 and @value2 cannot be +compared, the function returns GST_VALUE_UNORDERED. Otherwise, +if @value1 is greater than @value2, GST_VALUE_GREATER_THAN is returned. +If @value1 is less than @value2, GST_VALUE_LESS_THAN is returned. +If the values are equal, GST_VALUE_EQUAL is returned. + + comparison result + + + + + a value to compare + + + + another value to compare + + + + + + Tries to deserialize a string into the type specified by the given GValue. +If the operation succeeds, %TRUE is returned, %FALSE otherwise. + + %TRUE on success + + + + + #GValue to fill with contents of + deserialization + + + + string to deserialize + + + + + + Fixate @src into a new value @dest. +For ranges, the first element is taken. For lists and arrays, the +first item is fixated and returned. +If @src is already fixed, this function returns %FALSE. + + %TRUE if @dest contains a fixated version of @src. + + + + + the #GValue destination + + + + the #GValue to fixate + + + + + + Multiplies the two #GValue items containing a #GST_TYPE_FRACTION and sets +@product to the product of the two fractions. + + %FALSE in case of an error (like integer overflow), %TRUE otherwise. + + + + + a GValue initialized to #GST_TYPE_FRACTION + + + + a GValue initialized to #GST_TYPE_FRACTION + + + + a GValue initialized to #GST_TYPE_FRACTION + + + + + + Subtracts the @subtrahend from the @minuend and sets @dest to the result. + + %FALSE in case of an error (like integer overflow), %TRUE otherwise. + + + + + a GValue initialized to #GST_TYPE_FRACTION + + + + a GValue initialized to #GST_TYPE_FRACTION + + + + a GValue initialized to #GST_TYPE_FRACTION + + + + + + Gets the bitmask specified by @value. + + the bitmask. + + + + + a GValue initialized to #GST_TYPE_BITMASK + + + + + + Gets the contents of @value. The reference count of the returned +#GstCaps will not be modified, therefore the caller must take one +before getting rid of the @value. + + the contents of @value + + + + + a GValue initialized to GST_TYPE_CAPS + + + + + + Gets the contents of @value. + + the contents of @value + + + + + a GValue initialized to GST_TYPE_CAPS_FEATURES + + + + + + Gets the maximum of the range specified by @value. + + the maximum of the range + + + + + a GValue initialized to GST_TYPE_DOUBLE_RANGE + + + + + + Gets the minimum of the range specified by @value. + + the minimum of the range + + + + + a GValue initialized to GST_TYPE_DOUBLE_RANGE + + + + + + Retrieve the flags field of a GstFlagSet @value. + + the flags field of the flagset instance. + + + + + a GValue initialized to #GST_TYPE_FLAG_SET + + + + + + Retrieve the mask field of a GstFlagSet @value. + + the mask field of the flagset instance. + + + + + a GValue initialized to #GST_TYPE_FLAG_SET + + + + + + Gets the denominator of the fraction specified by @value. + + the denominator of the fraction. + + + + + a GValue initialized to #GST_TYPE_FRACTION + + + + + + Gets the numerator of the fraction specified by @value. + + the numerator of the fraction. + + + + + a GValue initialized to #GST_TYPE_FRACTION + + + + + + Gets the maximum of the range specified by @value. + + the maximum of the range + + + + + a GValue initialized to GST_TYPE_FRACTION_RANGE + + + + + + Gets the minimum of the range specified by @value. + + the minimum of the range + + + + + a GValue initialized to GST_TYPE_FRACTION_RANGE + + + + + + Gets the maximum of the range specified by @value. + + the maximum of the range + + + + + a GValue initialized to GST_TYPE_INT64_RANGE + + + + + + Gets the minimum of the range specified by @value. + + the minimum of the range + + + + + a GValue initialized to GST_TYPE_INT64_RANGE + + + + + + Gets the step of the range specified by @value. + + the step of the range + + + + + a GValue initialized to GST_TYPE_INT64_RANGE + + + + + + Gets the maximum of the range specified by @value. + + the maximum of the range + + + + + a GValue initialized to GST_TYPE_INT_RANGE + + + + + + Gets the minimum of the range specified by @value. + + the minimum of the range + + + + + a GValue initialized to GST_TYPE_INT_RANGE + + + + + + Gets the step of the range specified by @value. + + the step of the range + + + + + a GValue initialized to GST_TYPE_INT_RANGE + + + + + + Gets the contents of @value. + + the contents of @value + + + + + a GValue initialized to GST_TYPE_STRUCTURE + + + + + + Initialises the target value to be of the same type as source and then copies +the contents from source to target. + + + + + + the target value + + + + the source value + + + + + + Calculates the intersection of two values. If the values have +a non-empty intersection, the value representing the intersection +is placed in @dest, unless %NULL. If the intersection is non-empty, +@dest is not modified. + + %TRUE if the intersection is non-empty + + + + + + a uninitialized #GValue that will hold the calculated + intersection value. May be %NULL if the resulting set if not + needed. + + + + a value to intersect + + + + another value to intersect + + + + + + Tests if the given GValue, if available in a GstStructure (or any other +container) contains a "fixed" (which means: one value) or an "unfixed" +(which means: multiple possible values, such as data lists or data +ranges) value. + + true if the value is "fixed". + + + + + the #GValue to check + + + + + + Check that @value1 is a subset of @value2. + + %TRUE is @value1 is a subset of @value2 + + + + + a #GValue + + + + a #GValue + + + + + + Registers functions to perform calculations on #GValue items of a given +type. Each type can only be added once. + + + + + + structure containing functions to register + + + + + + tries to transform the given @value into a string representation that allows +getting back this string later on using gst_value_deserialize(). + +Free-function: g_free + + the serialization for @value +or %NULL if none exists + + + + + a #GValue to serialize + + + + + + Sets @value to the bitmask specified by @bitmask. + + + + + + a GValue initialized to #GST_TYPE_BITMASK + + + + the bitmask + + + + + + Sets the contents of @value to @caps. A reference to the +provided @caps will be taken by the @value. + + + + + + a GValue initialized to GST_TYPE_CAPS + + + + the caps to set the value to + + + + + + Sets the contents of @value to @features. + + + + + + a GValue initialized to GST_TYPE_CAPS_FEATURES + + + + the features to set the value to + + + + + + Sets @value to the range specified by @start and @end. + + + + + + a GValue initialized to GST_TYPE_DOUBLE_RANGE + + + + the start of the range + + + + the end of the range + + + + + + Sets @value to the flags and mask values provided in @flags and @mask. +The @flags value indicates the values of flags, the @mask represents +which bits in the flag value have been set, and which are "don't care" + + + + + + a GValue initialized to %GST_TYPE_FLAG_SET + + + + The value of the flags set or unset + + + + The mask indicate which flags bits must match for comparisons + + + + + + Sets @value to the fraction specified by @numerator over @denominator. +The fraction gets reduced to the smallest numerator and denominator, +and if necessary the sign is moved to the numerator. + + + + + + a GValue initialized to #GST_TYPE_FRACTION + + + + the numerator of the fraction + + + + the denominator of the fraction + + + + + + Sets @value to the range specified by @start and @end. + + + + + + a GValue initialized to GST_TYPE_FRACTION_RANGE + + + + the start of the range (a GST_TYPE_FRACTION GValue) + + + + the end of the range (a GST_TYPE_FRACTION GValue) + + + + + + Sets @value to the range specified by @numerator_start/@denominator_start +and @numerator_end/@denominator_end. + + + + + + a GValue initialized to GST_TYPE_FRACTION_RANGE + + + + the numerator start of the range + + + + the denominator start of the range + + + + the numerator end of the range + + + + the denominator end of the range + + + + + + Sets @value to the range specified by @start and @end. + + + + + + a GValue initialized to GST_TYPE_INT64_RANGE + + + + the start of the range + + + + the end of the range + + + + + + Sets @value to the range specified by @start, @end and @step. + + + + + + a GValue initialized to GST_TYPE_INT64_RANGE + + + + the start of the range + + + + the end of the range + + + + the step of the range + + + + + + Sets @value to the range specified by @start and @end. + + + + + + a GValue initialized to GST_TYPE_INT_RANGE + + + + the start of the range + + + + the end of the range + + + + + + Sets @value to the range specified by @start, @end and @step. + + + + + + a GValue initialized to GST_TYPE_INT_RANGE + + + + the start of the range + + + + the end of the range + + + + the step of the range + + + + + + Sets the contents of @value to @structure. + + + + + + a GValue initialized to GST_TYPE_STRUCTURE + + + + the structure to set the value to + + + + + + Subtracts @subtrahend from @minuend and stores the result in @dest. +Note that this means subtraction as in sets, not as in mathematics. + + %TRUE if the subtraction is not empty + + + + + the destination value + for the result if the subtraction is not empty. May be %NULL, + in which case the resulting set will not be computed, which can + give a fair speedup. + + + + the value to subtract from + + + + the value to subtract + + + + + + Creates a GValue corresponding to the union of @value1 and @value2. + + %TRUE if the union succeeded. + + + + + the destination value + + + + a value to union + + + + another value to union + + + + + + Gets the version number of the GStreamer library. + + + + + + pointer to a guint to store the major version number + + + + pointer to a guint to store the minor version number + + + + pointer to a guint to store the micro version number + + + + pointer to a guint to store the nano version number + + + + + + This function returns a string that is useful for describing this version +of GStreamer to the outside world: user agent strings, logging, ... + + a newly allocated string describing this version + of GStreamer. + + + + +