diff options
author | Rico Tzschichholz <ricotz@ubuntu.com> | 2018-11-14 10:36:15 +0100 |
---|---|---|
committer | Rico Tzschichholz <ricotz@ubuntu.com> | 2018-11-14 10:36:15 +0100 |
commit | 89a4c269a517f34a7732c276c6a55b56874fc8b5 (patch) | |
tree | d879d6f36772615eba909bb5c2f26cffae6050c8 /gir | |
parent | 886d36d65f3bcd30ddc23005e378c0fb4d295e21 (diff) | |
download | gobject-introspection-89a4c269a517f34a7732c276c6a55b56874fc8b5.tar.gz |
gir: Update annotations from glib git master
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 121 | ||||
-rw-r--r-- | gir/glib-2.0.c | 128 | ||||
-rw-r--r-- | gir/gobject-2.0.c | 10 |
3 files changed, 213 insertions, 46 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index ce76cdb8..947b71f6 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -5804,8 +5804,7 @@ * well-known name, the property cache is flushed when the name owner * vanishes and reloaded when a name owner appears. * - * If a #GDBusProxy is used for a well-known name, the owner of the - * name is tracked and can be read from + * The unique name owner of the proxy's name is tracked and can be read from * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to * get notified of changes. Additionally, only signals and property * changes emitted from the current name owner are considered and @@ -6976,7 +6975,7 @@ * then attempt to connect to that host, handling the possibility of * multiple IP addresses and multiple address families. * - * See #GSocketConnectable for and example of using the connectable + * See #GSocketConnectable for an example of using the connectable * interface. */ @@ -7034,7 +7033,7 @@ * address families. * * See #GSrvTarget for more information about SRV records, and see - * #GSocketConnectable for and example of using the connectable + * #GSocketConnectable for an example of using the connectable * interface. */ @@ -7452,7 +7451,7 @@ * fixed-size. * * #GSeekable on fixed-sized streams is approximately the same as POSIX - * lseek() on a block device (for example: attmepting to seek past the + * lseek() on a block device (for example: attempting to seek past the * end of the device is an error). Fixed streams typically cannot be * truncated. * @@ -7588,6 +7587,11 @@ * <default>(20,30)</default> * </key> * + * <key name="empty-string" type="s"> + * <default>""</default> + * <summary>Empty strings have to be provided in GVariant form</summary> + * </key> + * * </schema> * </schemalist> * ]| @@ -9290,6 +9294,9 @@ * from a certificate or key store. It is an abstract base class which * TLS library specific subtypes override. * + * A #GTlsDatabase may be accessed from multiple threads by the TLS backend. + * All implementations are required to be fully thread-safe. + * * Most common client applications will not directly interact with * #GTlsDatabase. It is used internally by #GTlsConnection. * @@ -9588,6 +9595,9 @@ * [thread-default-context aware][g-main-context-push-thread-default], * and so should not be used other than from the main thread, with no * thread-default-context active. + * + * In order to receive updates about volumes and mounts monitored through GVFS, + * a main loop must be running. */ @@ -14916,7 +14926,7 @@ * dispatched anywhere else - not even the standard dispatch machinery * (that API such as g_dbus_connection_signal_subscribe() and * g_dbus_connection_send_message_with_reply() relies on) will see the - * message. Similary, if a filter consumes an outgoing message, the + * message. Similarly, if a filter consumes an outgoing message, the * message will not be sent to the other peer. * * If @user_data_free_func is non-%NULL, it will be called (in the @@ -15996,6 +16006,11 @@ * signal is unsubscribed from, and may be called after @connection * has been destroyed.) * + * The returned subscription identifier is an opaque value which is guaranteed + * to never be zero. + * + * This function can never fail. + * * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe() * Since: 2.26 */ @@ -16798,7 +16813,7 @@ /** * g_dbus_message_bytes_needed: - * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message. + * @blob: (array length=blob_len) (element-type guint8): A blob representing a binary D-Bus message. * @blob_len: The length of @blob (must be at least 16). * @error: Return location for error or %NULL. * @@ -16904,7 +16919,10 @@ * * Gets a header field on @message. * - * Returns: A #GVariant with the value if the header was found, %NULL + * The caller is responsible for checking the type of the returned #GVariant + * matches what is expected. + * + * Returns: (transfer none) (nullable): A #GVariant with the value if the header was found, %NULL * otherwise. Do not free, it is owned by @message. * Since: 2.26 */ @@ -17080,6 +17098,9 @@ * order that the message was in can be retrieved using * g_dbus_message_get_byte_order(). * + * If the @blob cannot be parsed, contains invalid fields, or contains invalid + * headers, %G_IO_ERROR_INVALID_ARGUMENT will be returned. + * * Returns: A new #GDBusMessage or %NULL if @error is set. Free with * g_object_unref(). * Since: 2.26 @@ -18691,6 +18712,10 @@ * match rules for signals. Connect to the #GDBusProxy::g-signal signal * to handle signals from the remote object. * + * If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and + * %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is + * guaranteed to complete immediately without blocking. + * * If @name is a well-known name and the * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION * flags aren't set and no name owner currently exists, the message bus @@ -18796,6 +18821,10 @@ * match rules for signals. Connect to the #GDBusProxy::g-signal signal * to handle signals from the remote object. * + * If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and + * %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is + * guaranteed to return immediately without blocking. + * * If @name is a well-known name and the * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION * flags aren't set and no name owner currently exists, the message bus @@ -19195,6 +19224,23 @@ /** + * g_desktop_app_info_get_string_list: + * @info: a #GDesktopAppInfo + * @key: the key to look up + * @length: (out) (optional): return location for the number of returned strings, or %NULL + * + * Looks up a string list value in the keyfile backing @info. + * + * The @key is looked up in the "Desktop Entry" group. + * + * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): + * a %NULL-terminated string array or %NULL if the specified + * key cannot be found. The array should be freed with g_strfreev(). + * Since: 2.59.0 + */ + + +/** * g_desktop_app_info_has_key: * @info: a #GDesktopAppInfo * @key: the key to look up @@ -24907,8 +24953,8 @@ * native, the returned string is the result of g_file_get_uri() * (such as `sftp://path/to/my%20icon.png`). * - * - If @icon is a #GThemedIcon with exactly one name, the encoding is - * simply the name (such as `network-server`). + * - If @icon is a #GThemedIcon with exactly one name and no fallbacks, + * the encoding is simply the name (such as `network-server`). * * Returns: (nullable): An allocated NUL-terminated UTF8 string or * %NULL if @icon can't be serialized. Use g_free() to free. @@ -31915,16 +31961,9 @@ * The list is exactly the list of strings for which it is not an error * to call g_settings_get_child(). * - * For GSettings objects that are lists, this value can change at any - * time. Note that there is a race condition here: you may - * request a child after listing it only for it to have been destroyed - * in the meantime. For this reason, g_settings_get_child() may return - * %NULL even for a child that was listed by this function. - * - * For GSettings objects that are not lists, you should probably not be - * calling this function from "normal" code (since you should already - * know what children are in your schema). This function may still be - * useful there for introspection reasons, however. + * There is little reason to call this function from "normal" code, since + * you should already know what children are in your schema. This function + * may still be useful there for introspection reasons, however. * * You should free the return value with g_strfreev() when you are done * with it. @@ -37929,6 +37968,24 @@ /** + * g_tls_backend_set_default_database: + * @backend: the #GTlsBackend + * @database: (nullable): the #GTlsDatabase + * + * Set the default #GTlsDatabase used to verify TLS connections + * + * Any subsequent call to g_tls_backend_get_default_database() will return + * the database set in this call. Existing databases and connections are not + * modified. + * + * Setting a %NULL default database will reset to using the system default + * database as if g_tls_backend_set_default_database() had never been called. + * + * Since: 2.60 + */ + + +/** * g_tls_backend_supports_dtls: * @backend: the #GTlsBackend * @@ -38394,8 +38451,10 @@ * the beginning of the communication, you do not need to call this * function explicitly unless you want clearer error reporting. * However, you may call g_tls_connection_handshake() later on to - * rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, this will - * instead perform a rekey. + * rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, the + * behavior is undefined but guaranteed to be reasonable and + * nondestructive, so most older code should be expected to continue to + * work without changes. * * #GTlsConnection::accept_certificate may be emitted during the * handshake. @@ -39897,6 +39956,22 @@ /** + * g_unix_mount_get_root_path: + * @mount_entry: a #GUnixMountEntry. + * + * Gets the root of the mount within the filesystem. This is useful e.g. for + * mounts created by bind operation, or btrfs subvolumes. + * + * For example, the root path is equal to "/" for mount created by + * "mount /dev/sda1 /mnt/foo" and "/bar" for + * "mount --bind /mnt/foo/bar /mnt/bar". + * + * Returns: (nullable): a string containing the root, or %NULL if not supported. + * Since: 2.60 + */ + + +/** * g_unix_mount_guess_can_eject: * @mount_entry: a #GUnixMountEntry * @@ -40809,7 +40884,7 @@ * also listen for the "removed" signal on the returned object * and give up its reference when handling that signal * - * Similary, if implementing g_volume_monitor_adopt_orphan_mount(), + * Similarly, if implementing g_volume_monitor_adopt_orphan_mount(), * the implementor must take a reference to @mount and return it in * its g_volume_get_mount() implemented. Also, the implementor must * listen for the "unmounted" signal on @mount and give up its diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 66ab9a05..8a8ce87a 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -2108,7 +2108,9 @@ * * 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. + * removed from a future version of GLib. A consequence of using `glong` for + * `tv_sec` is that on 32-bit systems `GTimeVal` is subject to the year 2038 + * problem. */ @@ -3325,6 +3327,23 @@ /** + * G_GNUC_FALLTHROUGH: + * + * Expands to the GNU C fallthrough statement attribute if the compiler is gcc. + * This allows declaring case statement to explicitly fall through in switch + * statements. To enable this feature, use -Wimplicit-fallthrough during + * compilation. + * + * Put the attribute right before the case statement you want to fall through + * to. + * + * See the GNU C documentation for more details. + * + * Since: 2.60 + */ + + +/** * G_GNUC_FORMAT: * @arg_idx: the index of the argument * @@ -3565,6 +3584,24 @@ /** + * G_GNUC_STRFTIME: + * @format_idx: the index of the argument corresponding to + * the format string (the arguments are numbered from 1) + * + * Expands to the GNU C strftime format function attribute if the compiler + * is gcc. This is used for declaring functions which take a format argument + * which is passed to strftime() or an API implementing its formats. It allows + * the compiler check the format passed to the function. + * + * See the + * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) + * for details. + * + * Since: 2.60 + */ + + +/** * G_GNUC_UNUSED: * * Expands to the GNU C unused function attribute if the compiler is gcc. @@ -6708,7 +6745,10 @@ * * 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)}))". + * "a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant + * imposes a limit on recursion depth of 65 nested containers. This is the + * limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to + * be nested in a top-level tuple. * * The meaning of each of the characters is as follows: * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. @@ -9137,15 +9177,15 @@ * @free_segment: if %TRUE the actual element data is freed as well * * 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 + * %TRUE it frees the memory block holding the elements as well. 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. + * 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. + * If array contents point to dynamically-allocated memory, they should + * be freed separately if @free_seg is %TRUE and no @clear_func + * function has been set for @array. * * This function is not thread-safe. If using a #GArray from multiple * threads, use only the atomic g_array_ref() and g_array_unref() @@ -11729,8 +11769,8 @@ * @stamp: (out) (optional): return location for the last registration time, or %NULL * @error: return location for a #GError, or %NULL * - * Gets the registration informations of @app_name for the bookmark for - * @uri. See g_bookmark_file_set_app_info() for more informations about + * Gets the registration information of @app_name for the bookmark for + * @uri. See g_bookmark_file_set_app_info() for more information about * the returned data. * * The string returned in @app_exec must be freed. @@ -16904,8 +16944,9 @@ * * g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES"). * - * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib - * that must not be modified or freed. + * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by + * the thread g_get_language_names_with_category was called from. + * It must not be modified or freed. It must be copied if planned to be used in another thread. * Since: 2.58 */ @@ -19303,7 +19344,9 @@ * @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. + * Note that the returned string does not include the '#' comment markers, + * but does include any whitespace after them (on each line). It includes + * the line breaks between lines, but does not include the final line break. * * Returns: a comment that should be freed with g_free() * Since: 2.6 @@ -24277,7 +24320,9 @@ * g_path_get_dirname: * @file_name: (type filename): the name of the file * - * Gets the directory components of a file name. + * Gets the directory components of a file name. For example, the directory + * component of `/usr/bin/test` is `/usr/bin`. The directory component of `/` + * is `/`. * * If the file name has no directory components "." is returned. * The returned string should be freed when no longer needed. @@ -29391,7 +29436,11 @@ * 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. + * to the type of source you are using, such as g_idle_add() or g_timeout_add(). + * + * It is safe to call this function multiple times on a source which has already + * been attached to a context. The changes will take effect for the next time + * the source is dispatched after this call returns. */ @@ -29408,6 +29457,10 @@ * an initial reference count on @callback_data, and thus * @callback_funcs->unref will eventually be called once more * than @callback_funcs->ref. + * + * It is safe to call this function multiple times on a source which has already + * been attached to a context. The changes will take effect for the next time + * the source is dispatched after this call returns. */ @@ -33031,10 +33084,12 @@ * variation of ISO 8601 format is required. * * If @time_ represents a date which is too large to fit into a `struct tm`, - * %NULL will be returned. This is platform dependent, but it is safe to assume - * years up to 3000 are supported. The return value of g_time_val_to_iso8601() - * has been nullable since GLib 2.54; before then, GLib would crash under the - * same conditions. + * %NULL will be returned. This is platform dependent. Note also that since + * `GTimeVal` stores the number of seconds as a `glong`, on 32-bit systems it + * is subject to the year 2038 problem. + * + * The return value of g_time_val_to_iso8601() has been nullable since GLib + * 2.54; before then, GLib would crash under the same conditions. * * Returns: (nullable): a newly allocated string containing an ISO 8601 date, * or %NULL if @time_ was too large @@ -35536,6 +35591,22 @@ /** + * g_utf8_validate_len: + * @str: (array length=max_len) (element-type guint8): a pointer to character data + * @max_len: max bytes to validate + * @end: (out) (optional) (transfer none): return location for end of valid data + * + * Validates UTF-8 encoded text. + * + * As with g_utf8_validate(), but @max_len must be set, and hence this function + * will always return %FALSE if any of the bytes of @str are nul. + * + * Returns: %TRUE if the text was valid UTF-8 + * Since: 2.60 + */ + + +/** * g_utime: * @filename: (type filename): a pathname in the GLib file name encoding * (UTF-8 on Windows) @@ -36438,6 +36509,11 @@ * The returned value is never floating. You should free it with * g_variant_unref() when you're done with it. * + * There may be implementation specific restrictions on deeply nested values, + * which would result in the unit tuple being returned as the child value, + * instead of further nested children. #GVariant is guaranteed to handle + * nesting up to at least 64 levels. + * * This function is O(1). * * Returns: (transfer full): the child at the specified index @@ -36923,6 +36999,9 @@ * being trusted. If the value was already marked as being trusted then * this function will immediately return %TRUE. * + * There may be implementation specific restrictions on deeply nested values. + * GVariant is guaranteed to handle nesting up to at least 64 levels. + * * Returns: %TRUE if @value is in normal form * Since: 2.24 */ @@ -37488,6 +37567,10 @@ * * A reference is taken on @bytes. * + * The data in @bytes must be aligned appropriately for the @type being loaded. + * Otherwise this function will internally create a copy of the memory (since + * GLib 2.60) or (in older versions) fail and exit the process. + * * Returns: (transfer none): a new #GVariant with a floating reference * Since: 2.36 */ @@ -37527,6 +37610,11 @@ * needed. The exact time of this call is unspecified and might even be * before this function returns. * + * Note: @data must be backed by memory that is aligned appropriately for the + * @type being loaded. Otherwise this function will internally create a copy of + * the memory (since GLib 2.60) or (in older versions) fail and exit the + * process. + * * Returns: (transfer none): a new floating #GVariant of type @type * Since: 2.24 */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 1a4f3bcb..b6c3f152 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -1821,6 +1821,8 @@ * Creates a new closure which invokes @callback_func with @user_data as * the last parameter. * + * @destroy_data will be called as a finalize notifier on the #GClosure. + * * Returns: (transfer none): a floating reference to a new #GCClosure */ @@ -1864,6 +1866,8 @@ * Creates a new closure which invokes @callback_func with @user_data as * the first parameter. * + * @destroy_data will be called as a finalize notifier on the #GClosure. + * * Returns: (transfer none): a floating reference to a new #GCClosure */ @@ -1934,7 +1938,7 @@ /** * g_closure_invalidate: - * @closure: GClosure to invalidate + * @closure: #GClosure to invalidate * * Sets a flag on the closure to indicate that its calling * environment has become invalid, and thus causes any future @@ -3466,8 +3470,8 @@ /** * g_object_watch_closure: - * @object: GObject restricting lifetime of @closure - * @closure: GClosure to watch + * @object: #GObject restricting lifetime of @closure + * @closure: #GClosure to watch * * This function essentially limits the life time of the @closure to * the life time of the object. That is, when the object is finalized, |