diff options
| -rw-r--r-- | .gitlab-ci.yml | 34 | ||||
| -rw-r--r-- | .gitlab-ci/Dockerfile | 2 | ||||
| -rwxr-xr-x | .gitlab-ci/run-docker.sh | 2 | ||||
| -rw-r--r-- | docs/g-ir-compiler.1 | 2 | ||||
| -rw-r--r-- | docs/g-ir-generate.1 | 2 | ||||
| -rw-r--r-- | docs/g-ir-scanner.1 | 2 | ||||
| -rw-r--r-- | docs/reference/gi-struct-hierarchy.xml | 4 | ||||
| -rw-r--r-- | docs/website/tools/g-ir-compiler.rst | 2 | ||||
| -rw-r--r-- | docs/website/tools/g-ir-generate.rst | 2 | ||||
| -rw-r--r-- | docs/website/tools/g-ir-scanner.rst | 2 | ||||
| -rw-r--r-- | docs/website/users.rst | 2 | ||||
| -rw-r--r-- | gir/gio-2.0.c | 274 | ||||
| -rw-r--r-- | gir/glib-2.0.c | 1194 | ||||
| -rw-r--r-- | gir/gobject-2.0.c | 32 | ||||
| -rw-r--r-- | gir/meson.build | 28 | ||||
| -rw-r--r-- | giscanner/dumper.py | 4 | ||||
| -rw-r--r-- | gobject-introspection-1.0.pc.in | 24 | ||||
| -rw-r--r-- | gobject-introspection-no-export-1.0.pc.in | 23 | ||||
| -rw-r--r-- | gobject-introspection.doap | 2 | ||||
| -rw-r--r-- | meson.build | 73 | ||||
| -rw-r--r-- | meson_options.txt | 4 | ||||
| -rwxr-xr-x | tools/g-ir-tool-template.in | 9 | ||||
| -rw-r--r-- | tools/meson.build | 14 |
23 files changed, 1392 insertions, 345 deletions
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 0cb71530..e9e79b97 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -2,12 +2,44 @@ stages: - build - deploy -image: registry.gitlab.gnome.org/gnome/gobject-introspection:v6 +image: registry.gitlab.gnome.org/gnome/gobject-introspection:v7 cache: paths: - _ccache/ +example-meson: + stage: build + script: + - python3 -m pip install --user mako markdown + - meson --prefix /usr --libdir /usr/lib64 --buildtype debug -Ddoctool=enabled -Dgtk_doc=true -Dcairo=enabled -Dpython=python3 _build . + - ninja -C _build + - sudo ninja -C _build install + - g-ir-scanner --version + - cd examples/library + - meson --prefix /usr --default-library both _build + - ninja -C _build + - sudo ninja -C _build install + - g-ir-inspect --print-typelibs --print-shlibs GISample + # also build a small program using libgirepository + - cd ../girepository + - meson _build + - ninja -C _build + +example-autotools: + stage: build + script: + - python3 -m pip install --user mako markdown + - meson --prefix /usr --libdir /usr/lib64 --buildtype debug -Ddoctool=enabled -Dgtk_doc=true -Dcairo=enabled -Dpython=python3 _build . + - ninja -C _build + - sudo ninja -C _build install + - g-ir-scanner --version + - cd examples/library + - ./autogen.sh --prefix /usr + - make -j + - sudo make install + - g-ir-inspect --print-typelibs --print-shlibs GISample + fedora-x86_64-meson: stage: build variables: diff --git a/.gitlab-ci/Dockerfile b/.gitlab-ci/Dockerfile index 0dec6700..3a579cf8 100644 --- a/.gitlab-ci/Dockerfile +++ b/.gitlab-ci/Dockerfile @@ -43,6 +43,7 @@ RUN dnf -y install \ python3-wheel \ readline-devel \ redhat-rpm-config \ + sudo \ sqlite-devel \ systemtap-sdt-devel \ zlib-devel \ @@ -53,6 +54,7 @@ RUN pip3 install meson==0.50.1 ARG HOST_USER_ID=5555 ENV HOST_USER_ID ${HOST_USER_ID} RUN useradd -u $HOST_USER_ID -ms /bin/bash user +RUN echo 'user ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers USER user WORKDIR /home/user diff --git a/.gitlab-ci/run-docker.sh b/.gitlab-ci/run-docker.sh index 5d29002c..8e6a04ab 100755 --- a/.gitlab-ci/run-docker.sh +++ b/.gitlab-ci/run-docker.sh @@ -2,7 +2,7 @@ set -e -TAG="registry.gitlab.gnome.org/gnome/gobject-introspection:v6" +TAG="registry.gitlab.gnome.org/gnome/gobject-introspection:v7" sudo docker build --build-arg HOST_USER_ID="$UID" --tag "${TAG}" \ --file "Dockerfile" . diff --git a/docs/g-ir-compiler.1 b/docs/g-ir-compiler.1 index 48dc5ceb..f3eda03c 100644 --- a/docs/g-ir-compiler.1 +++ b/docs/g-ir-compiler.1 @@ -72,7 +72,7 @@ Show program\(aqs version number and exit Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP .SH HOMEPAGE AND CONTACT .sp -\fI\%http://live.gnome.org/GObjectIntrospection\fP +\fI\%https://gi.readthedocs.io/\fP .SH AUTHORS .sp Mattias Clasen diff --git a/docs/g-ir-generate.1 b/docs/g-ir-generate.1 index 038d171f..f05a295a 100644 --- a/docs/g-ir-generate.1 +++ b/docs/g-ir-generate.1 @@ -58,7 +58,7 @@ Show program\(aqs version number and exit Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP .SH HOMEPAGE AND CONTACT .sp -\fI\%http://live.gnome.org/GObjectIntrospection\fP +\fI\%https://gi.readthedocs.io/\fP .SH AUTHORS .sp Mattias Clasen diff --git a/docs/g-ir-scanner.1 b/docs/g-ir-scanner.1 index 528bed5c..d25f321b 100644 --- a/docs/g-ir-scanner.1 +++ b/docs/g-ir-scanner.1 @@ -177,7 +177,7 @@ generating introspection data in a cross-compilation environment. Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP .SH HOMEPAGE AND CONTACT .sp -\fI\%http://live.gnome.org/GObjectIntrospection\fP +\fI\%https://gi.readthedocs.io/\fP .SH AUTHORS .sp Johan Dahlin diff --git a/docs/reference/gi-struct-hierarchy.xml b/docs/reference/gi-struct-hierarchy.xml index 685f85aa..7d40e053 100644 --- a/docs/reference/gi-struct-hierarchy.xml +++ b/docs/reference/gi-struct-hierarchy.xml @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> <!ENTITY version SYSTEM "version.xml"> ]> diff --git a/docs/website/tools/g-ir-compiler.rst b/docs/website/tools/g-ir-compiler.rst index 5c17a7ce..28ca44aa 100644 --- a/docs/website/tools/g-ir-compiler.rst +++ b/docs/website/tools/g-ir-compiler.rst @@ -62,7 +62,7 @@ Report bugs at https://gitlab.gnome.org/GNOME/gobject-introspection/issues HOMEPAGE and CONTACT ==================== -http://live.gnome.org/GObjectIntrospection +https://gi.readthedocs.io/ AUTHORS diff --git a/docs/website/tools/g-ir-generate.rst b/docs/website/tools/g-ir-generate.rst index 931ee449..0b0c8fe0 100644 --- a/docs/website/tools/g-ir-generate.rst +++ b/docs/website/tools/g-ir-generate.rst @@ -48,7 +48,7 @@ Report bugs at https://gitlab.gnome.org/GNOME/gobject-introspection/issues HOMEPAGE and CONTACT ==================== -http://live.gnome.org/GObjectIntrospection +https://gi.readthedocs.io/ AUTHORS diff --git a/docs/website/tools/g-ir-scanner.rst b/docs/website/tools/g-ir-scanner.rst index fc6abe3e..e8df7457 100644 --- a/docs/website/tools/g-ir-scanner.rst +++ b/docs/website/tools/g-ir-scanner.rst @@ -166,7 +166,7 @@ Report bugs at https://gitlab.gnome.org/GNOME/gobject-introspection/issues HOMEPAGE and CONTACT ==================== -http://live.gnome.org/GObjectIntrospection +https://gi.readthedocs.io/ AUTHORS diff --git a/docs/website/users.rst b/docs/website/users.rst index 6d651092..c2faf51b 100644 --- a/docs/website/users.rst +++ b/docs/website/users.rst @@ -14,7 +14,7 @@ Bindings based on GObject-Introspection * `JGIR <https://wiki.gnome.org/Projects/JGIR>`__ - Java/JVM bindings (compile time, using typelib) * `GJS <https://wiki.gnome.org/Projects/Gjs>`__ - Javascript (spidermonkey) bindings (runtime) * `Seed <https://wiki.gnome.org/Projects/Seed>`__ - Javascript (JSCore, WebKit JS engine) bindings (runtime) -* `sbank <http://live.gnome.org/sbank>`__ - Scheme binding for gobject-introspection (runtime) +* `sbank <https://wiki.gnome.org/sbank>`__ - Scheme binding for gobject-introspection (runtime) * `GObjectIntrospection/GObjectConsume <https://wiki.gnome.org/Projects/GObjectIntrospection/GObjectConsume>`__ - Qt bindings (compile time) * `GirFFI <http://github.com/mvz/ruby-gir-ffi>`__ - Ruby bindings (runtime) * `Ruby-GNOME <https://github.com/ruby-gnome/ruby-gnome>`__ - Ruby bindings (runtime) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 64812d38..485355a9 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -1582,7 +1582,7 @@ * GDtlsClientConnection:validation-flags: * * What steps to perform when validating a certificate received from - * a server. Server certificates that fail to validate in all of the + * a server. Server certificates that fail to validate in any of the * ways indicated here will be rejected unless the application * overrides the default via #GDtlsConnection::accept-certificate. * @@ -1715,9 +1715,8 @@ * GDtlsConnection:peer-certificate: (nullable) * * The connection's peer's certificate, after the TLS handshake has - * completed and the certificate has been accepted. Note in - * particular that this is not yet set during the emission of - * #GDtlsConnection::accept-certificate. + * completed or failed. Note in particular that this is not yet set + * during the emission of #GDtlsConnection::accept-certificate. * * (You can watch for a #GObject::notify signal on this property to * detect when a handshake has occurred.) @@ -1729,7 +1728,7 @@ /** * GDtlsConnection:peer-certificate-errors: * - * The errors noticed-and-ignored while verifying + * The errors noticed while verifying * #GDtlsConnection:peer-certificate. Normally this should be 0, but * it may not be if #GDtlsClientConnection:validation-flags is not * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if @@ -2246,7 +2245,7 @@ * @removed: the number of items removed * @added: the number of items added * - * Emitted when a change has occured to the menu. + * Emitted when a change has occurred to the menu. * * The only changes that can occur to a menu is that items are removed * or added. Items may not change (except by being removed and added @@ -2383,7 +2382,7 @@ /** * GMountOperation::show-unmount-progress: * @op: a #GMountOperation: - * @message: string containing a mesage to display to the user + * @message: string containing a message to display to the user * @time_left: the estimated time left before the operation completes, * in microseconds, or -1 * @bytes_left: the amount of bytes to be written before the operation @@ -3562,7 +3561,7 @@ * GThreadedSocketService::run: * @service: the #GThreadedSocketService. * @connection: a new #GSocketConnection object. - * @source_object: the source_object passed to g_socket_listener_add_address(). + * @source_object: (nullable): the source_object passed to g_socket_listener_add_address(). * * The ::run signal is emitted in a worker thread in response to an * incoming connection. This thread is dedicated to handling @@ -3724,7 +3723,7 @@ * GTlsClientConnection:validation-flags: * * What steps to perform when validating a certificate received from - * a server. Server certificates that fail to validate in all of the + * a server. Server certificates that fail to validate in any of the * ways indicated here will be rejected unless the application * overrides the default via #GTlsConnection::accept-certificate. * @@ -3860,9 +3859,8 @@ * GTlsConnection:peer-certificate: (nullable) * * The connection's peer's certificate, after the TLS handshake has - * completed and the certificate has been accepted. Note in - * particular that this is not yet set during the emission of - * #GTlsConnection::accept-certificate. + * completed or failed. Note in particular that this is not yet set + * during the emission of #GTlsConnection::accept-certificate. * * (You can watch for a #GObject::notify signal on this property to * detect when a handshake has occurred.) @@ -3874,7 +3872,7 @@ /** * GTlsConnection:peer-certificate-errors: * - * The errors noticed-and-ignored while verifying + * The errors noticed while verifying * #GTlsConnection:peer-certificate. Normally this should be 0, but * it may not be if #GTlsClientConnection:validation-flags is not * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if @@ -5356,22 +5354,26 @@ * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and * g_unix_connection_receive_credentials() for details. * - * On Linux, the native credential type is a struct ucred - see the + * On Linux, the native credential type is a `struct ucred` - see the * unix(7) man page for details. This corresponds to * %G_CREDENTIALS_TYPE_LINUX_UCRED. * + * On Apple operating systems (including iOS, tvOS, and macOS), + * the native credential type is a `struct xucred`. + * This corresponds to %G_CREDENTIALS_TYPE_APPLE_XUCRED. + * * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native - * credential type is a struct cmsgcred. This corresponds + * credential type is a `struct cmsgcred`. This corresponds * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. * - * On NetBSD, the native credential type is a struct unpcbid. + * On NetBSD, the native credential type is a `struct unpcbid`. * This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID. * - * On OpenBSD, the native credential type is a struct sockpeercred. + * On OpenBSD, the native credential type is a `struct sockpeercred`. * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED. * * On Solaris (including OpenSolaris and its derivatives), the native - * credential type is a ucred_t. This corresponds to + * credential type is a `ucred_t`. This corresponds to * %G_CREDENTIALS_TYPE_SOLARIS_UCRED. */ @@ -6064,7 +6066,7 @@ * * If the #GDrive reports that media isn't automatically detected, one * can poll for media; typically one should not do this periodically - * as a poll for media operation is potententially expensive and may + * as a poll for media operation is potentially expensive and may * spin up the drive creating noise. * * #GDrive supports starting and stopping drives with authentication @@ -6264,7 +6266,7 @@ * * Keys are strings that contain a key namespace and a key name, separated * by a colon, e.g. "namespace::keyname". Namespaces are included to sort - * key-value pairs by namespaces for relevance. Keys can be retrived + * key-value pairs by namespaces for relevance. Keys can be retrieved * using wildcards, e.g. "standard::*" will return all of the keys in the * "standard" namespace. * @@ -6689,7 +6691,7 @@ * unreferenced). * * For bindings in languages where the native constructor supports - * exceptions the binding could check for objects implemention %GInitable + * exceptions the binding could check for objects implementing %GInitable * during normal construction and automatically initialize them, throwing * an exception on failure. */ @@ -6849,7 +6851,7 @@ * it are gone. * * On the other side, a consumer is expected only to hold references on - * objects that are currently "user visible", in order to faciliate the + * objects that are currently "user visible", in order to facilitate the * maximum level of laziness in the implementation of the list and to * reduce the required number of signal connections at a given time. * @@ -8479,7 +8481,7 @@ * g_socket_address_enumerator_next_finish() should be used where possible. * * Each #GSocketAddressEnumerator can only be enumerated once. Once - * g_socket_address_enumerator_next() has returned %NULL (and no error), further + * g_socket_address_enumerator_next() has returned %NULL, further * enumeration with that #GSocketAddressEnumerator is not possible, and it can * be unreffed. */ @@ -10989,7 +10991,7 @@ * * Gets the default #GAppInfo for a given content type. * - * Returns: (transfer full): #GAppInfo for given @content_type or + * Returns: (transfer full) (nullable): #GAppInfo for given @content_type or * %NULL on error. */ @@ -11003,7 +11005,8 @@ * of the URI, up to but not including the ':', e.g. "http", * "ftp" or "sip". * - * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error. + * Returns: (transfer full) (nullable): #GAppInfo for given @uri_scheme or + * %NULL on error. */ @@ -12001,7 +12004,7 @@ * Gets the application's current busy state, as set through * g_application_mark_busy() or g_application_bind_busy_property(). * - * Returns: %TRUE if @application is currenty marked as busy + * Returns: %TRUE if @application is currently marked as busy * Since: 2.44 */ @@ -14142,7 +14145,8 @@ * * This operation can fail if #GCredentials is not supported on the * OS or if the native credentials type does not contain information - * about the UNIX process ID. + * about the UNIX process ID (for example this is the case for + * %G_CREDENTIALS_TYPE_APPLE_XUCRED). * * Returns: The UNIX process ID, or -1 if @error is set. * Since: 2.36 @@ -19782,7 +19786,8 @@ * in a GIO module. There is no reason for applications to use it * directly. Applications should use g_app_info_get_default_for_uri_scheme(). * - * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error. + * Returns: (transfer full) (nullable): #GAppInfo for given @uri_scheme or + * %NULL on error. * Deprecated: 2.28: The #GDesktopAppInfoLookup interface is deprecated and * unused by GIO. */ @@ -19844,6 +19849,13 @@ * The algorithm for determining matches is undefined and may change at * any time. * + * None of the search results are subjected to the normal validation + * checks performed by g_desktop_app_info_new() (for example, checking that + * the executable referenced by a result exists), and so it is possible for + * g_desktop_app_info_new() to return %NULL when passed an app ID returned by + * this function. It is expected that calling code will do this when + * subsequently creating a #GDesktopAppInfo for each result. + * * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a * list of strvs. Free each item with g_strfreev() and free the outer * list with g_free(). @@ -20110,9 +20122,9 @@ * g_drive_is_media_check_automatic: * @drive: a #GDrive. * - * Checks if @drive is capabable of automatically detecting media changes. + * Checks if @drive is capable of automatically detecting media changes. * - * Returns: %TRUE if the @drive is capabable of automatically detecting + * Returns: %TRUE if the @drive is capable of automatically detecting * media changes, %FALSE otherwise. */ @@ -20409,6 +20421,33 @@ /** + * g_dtls_connection_get_channel_binding_data: + * @conn: a #GDtlsConnection + * @type: #GTlsChannelBindingType type of data to fetch + * @data: (out callee-allocates) (optional) (transfer none): #GByteArray is + * filled with the binding data, or %NULL + * @error: a #GError pointer, or %NULL + * + * Query the TLS backend for TLS channel binding data of @type for @conn. + * + * This call retrieves TLS channel binding data as specified in RFC + * [5056](https://tools.ietf.org/html/rfc5056), RFC + * [5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The + * binding data is returned in @data. The @data is resized by the callee + * using #GByteArray buffer management and will be freed when the @data + * is destroyed by g_byte_array_unref(). If @data is %NULL, it will only + * check whether TLS backend is able to fetch the data (e.g. whether @type + * is supported by the TLS backend). It does not guarantee that the data + * will be available though. That could happen if TLS connection does not + * support @type or the binding data is not available yet due to additional + * negotiation or input required. + * + * Returns: %TRUE on success, %FALSE otherwise + * Since: 2.66 + */ + + +/** * g_dtls_connection_get_database: * @conn: a #GDtlsConnection * @@ -20454,8 +20493,8 @@ * g_dtls_connection_get_peer_certificate: * @conn: a #GDtlsConnection * - * Gets @conn's peer's certificate after the handshake has completed. - * (It is not set during the emission of + * Gets @conn's peer's certificate after the handshake has completed + * or failed. (It is not set during the emission of * #GDtlsConnection::accept-certificate.) * * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL @@ -20468,8 +20507,8 @@ * @conn: a #GDtlsConnection * * Gets the errors associated with validating @conn's peer's - * certificate, after the handshake has completed. (It is not set - * during the emission of #GDtlsConnection::accept-certificate.) + * certificate, after the handshake has completed or failed. (It is + * not set during the emission of #GDtlsConnection::accept-certificate.) * * Returns: @conn's peer's certificate errors * Since: 2.48 @@ -21038,7 +21077,7 @@ * * Gets the next matched attribute from a #GFileAttributeMatcher. * - * Returns: a string containing the next attribute or %NULL if + * Returns: (nullable): a string containing the next attribute or, %NULL if * no more attribute exist. */ @@ -22282,7 +22321,7 @@ * @info: a #GFileInfo. * @attribute: a file attribute key. * - * Gets the value of a attribute, formated as a string. + * Gets the value of a attribute, formatted as a string. * This escapes things as needed to make the string valid * UTF-8. * @@ -22312,7 +22351,7 @@ * Gets the value of a byte string attribute. If the attribute does * not contain a byte string, %NULL will be returned. * - * Returns: the contents of the @attribute value as a byte string, or + * Returns: (nullable): the contents of the @attribute value as a byte string, or * %NULL otherwise. */ @@ -22367,8 +22406,8 @@ * Gets the value of a #GObject attribute. If the attribute does * not contain a #GObject, %NULL will be returned. * - * Returns: (transfer none): a #GObject associated with the given @attribute, or - * %NULL otherwise. + * Returns: (transfer none) (nullable): a #GObject associated with the given @attribute, + * or %NULL otherwise. */ @@ -22392,8 +22431,8 @@ * Gets the value of a string attribute. If the attribute does * not contain a string, %NULL will be returned. * - * Returns: the contents of the @attribute value as a UTF-8 string, or - * %NULL otherwise. + * Returns: (nullable): the contents of the @attribute value as a UTF-8 string, + * or %NULL otherwise. */ @@ -22405,8 +22444,8 @@ * Gets the value of a stringv attribute. If the attribute does * not contain a stringv, %NULL will be returned. * - * Returns: (transfer none): the contents of the @attribute value as a stringv, or - * %NULL otherwise. Do not free. These returned strings are UTF-8. + * Returns: (transfer none) (nullable): the contents of the @attribute value as a stringv, + * or %NULL otherwise. Do not free. These returned strings are UTF-8. * Since: 2.22 */ @@ -22455,7 +22494,8 @@ * * Gets the file's content type. * - * Returns: a string containing the file's content type. + * Returns: (nullable): a string containing the file's content type, + * or %NULL if unknown. */ @@ -22467,7 +22507,7 @@ * available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned. * - * Returns: a #GDateTime, or %NULL. + * Returns: (nullable): a #GDateTime, or %NULL. * Since: 2.36 */ @@ -26701,7 +26741,7 @@ * * This may not actually load and initialize all the types in each * module, some modules may be lazily loaded and initialized when - * an extension point it implementes is used with e.g. + * an extension point it implements is used with e.g. * g_io_extension_point_get_extensions() or * g_io_extension_point_get_extension_by_name(). * @@ -26723,7 +26763,7 @@ * * This may not actually load and initialize all the types in each * module, some modules may be lazily loaded and initialized when - * an extension point it implementes is used with e.g. + * an extension point it implements is used with e.g. * g_io_extension_point_get_extensions() or * g_io_extension_point_get_extension_by_name(). * @@ -26972,7 +27012,7 @@ * @callback: (scope async): a #GAsyncReadyCallback. * @user_data: (closure): user data passed to @callback. * - * Asyncronously splice the output stream of @stream1 to the input stream of + * Asynchronously splice the output stream of @stream1 to the input stream of * @stream2, and splice the output stream of @stream2 to the input stream of * @stream1. * @@ -29526,7 +29566,7 @@ * g_network_service_get_scheme: * @srv: a #GNetworkService * - * Get's the URI scheme used to resolve proxies. By default, the service name + * Gets the URI scheme used to resolve proxies. By default, the service name * is used as scheme. * * Returns: @srv's scheme name @@ -32094,7 +32134,7 @@ * * Sets the length of the stream to @offset. If the stream was previously * larger than @offset, the extra data is discarded. If the stream was - * previouly shorter than @offset, it is extended with NUL ('\0') bytes. + * previously shorter than @offset, it is extended with NUL ('\0') bytes. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation @@ -35614,6 +35654,7 @@ * - OpenBSD since GLib 2.30 * - Solaris, Illumos and OpenSolaris since GLib 2.40 * - NetBSD since GLib 2.42 + * - macOS, tvOS, iOS since GLib 2.66 * * Other ways to obtain credentials from a foreign peer includes the * #GUnixCredentialsMessage type and @@ -38529,7 +38570,7 @@ * g_task_return_error_if_cancelled() and then returned. * * This allows you to create a cancellable wrapper around an - * uninterruptable function. The #GTaskThreadFunc just needs to be + * uninterruptible function. The #GTaskThreadFunc just needs to be * careful that it does not modify any externally-visible state after * it has been cancelled. To do that, the thread should call * g_task_set_return_on_cancel() again to (atomically) set @@ -38618,7 +38659,7 @@ * g_tcp_wrapper_connection_get_base_io_stream: * @conn: a #GTcpWrapperConnection * - * Get's @conn's base #GIOStream + * Gets @conn's base #GIOStream * * Returns: (transfer none): @conn's base #GIOStream */ @@ -39145,6 +39186,16 @@ /** + * g_tls_channel_binding_error_quark: + * + * Gets the TLS channel binding error quark. + * + * Returns: a #GQuark. + * Since: 2.66 + */ + + +/** * g_tls_client_connection_copy_session_state: * @conn: a #GTlsClientConnection * @source: a #GTlsClientConnection @@ -39334,6 +39385,33 @@ /** + * g_tls_connection_get_channel_binding_data: + * @conn: a #GTlsConnection + * @type: #GTlsChannelBindingType type of data to fetch + * @data: (out callee-allocates) (optional) (transfer none): #GByteArray is + * filled with the binding data, or %NULL + * @error: a #GError pointer, or %NULL + * + * Query the TLS backend for TLS channel binding data of @type for @conn. + * + * This call retrieves TLS channel binding data as specified in RFC + * [5056](https://tools.ietf.org/html/rfc5056), RFC + * [5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The + * binding data is returned in @data. The @data is resized by the callee + * using #GByteArray buffer management and will be freed when the @data + * is destroyed by g_byte_array_unref(). If @data is %NULL, it will only + * check whether TLS backend is able to fetch the data (e.g. whether @type + * is supported by the TLS backend). It does not guarantee that the data + * will be available though. That could happen if TLS connection does not + * support @type or the binding data is not available yet due to additional + * negotiation or input required. + * + * Returns: %TRUE on success, %FALSE otherwise + * Since: 2.66 + */ + + +/** * g_tls_connection_get_database: * @conn: a #GTlsConnection * @@ -39379,8 +39457,8 @@ * g_tls_connection_get_peer_certificate: * @conn: a #GTlsConnection * - * Gets @conn's peer's certificate after the handshake has completed. - * (It is not set during the emission of + * Gets @conn's peer's certificate after the handshake has completed + * or failed. (It is not set during the emission of * #GTlsConnection::accept-certificate.) * * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL @@ -39393,8 +39471,8 @@ * @conn: a #GTlsConnection * * Gets the errors associated with validating @conn's peer's - * certificate, after the handshake has completed. (It is not set - * during the emission of #GTlsConnection::accept-certificate.) + * certificate, after the handshake has completed or failed. (It is + * not set during the emission of #GTlsConnection::accept-certificate.) * * Returns: @conn's peer's certificate errors * Since: 2.28 @@ -39890,9 +39968,13 @@ * which means that the certificate is being used to authenticate a server * (and we are acting as the client). * - * The @identity is used to check for pinned certificates (trust exceptions) - * in the database. These will override the normal verification process on a - * host by host basis. + * The @identity is used to ensure the server certificate is valid for + * the expected peer identity. If the identity does not match the + * certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the + * return value. If @identity is %NULL, that bit will never be set in + * the return value. The peer identity may also be used to check for + * pinned certificates (trust exceptions) in the database. These may + * override the normal verification process on a host-by-host basis. * * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be * used. @@ -42181,6 +42263,28 @@ /** + * g_win32_registry_get_os_dirs: + * + * Returns a list of directories for DLL lookups. + * Can be used with g_win32_registry_key_get_value(). + * + * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of UTF-8 strings. + * Since: 2.66 + */ + + +/** + * g_win32_registry_get_os_dirs_w: + * + * Returns a list of directories for DLL lookups. + * Can be used with g_win32_registry_key_get_value_w(). + * + * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of UTF-16 strings. + * Since: 2.66 + */ + + +/** * g_win32_registry_key_erase_change_indicator: * @key: (in) (transfer none): a #GWin32RegistryKey * @@ -42246,6 +42350,10 @@ /** * g_win32_registry_key_get_value: * @key: (in) (transfer none): a #GWin32RegistryKey + * @mui_dll_dirs: (in) (transfer none) (array zero-terminated=1) (optional): a %NULL-terminated + * array of directory names where the OS + * should look for a DLL indicated in a MUI string, if the + * DLL path in the string is not absolute * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR * to G_WIN32_REGISTRY_VALUE_STR. * @value_name: (in) (transfer none): name of the value to get (in UTF-8). @@ -42259,14 +42367,37 @@ * Get data from a value of a key. String data is guaranteed to be * appropriately terminated and will be in UTF-8. * + * When not %NULL, @mui_dll_dirs indicates that `RegLoadMUIStringW()` API + * should be used instead of the usual `RegQueryValueExW()`. This implies + * that the value being queried is of type `REG_SZ` or `REG_EXPAND_SZ` (if it is not, the function + * falls back to `RegQueryValueExW()`), and that this string must undergo special processing + * (see [`SHLoadIndirectString()` documentation](https://docs.microsoft.com/en-us/windows/win32/api/shlwapi/nf-shlwapi-shloadindirectstring) for an explanation on what + * kinds of strings are processed) to get the result. + * + * If no specific MUI DLL directories need to be used, pass + * the return value of g_win32_registry_get_os_dirs() as @mui_dll_dirs + * (as an bonus, the value from g_win32_registry_get_os_dirs() + * does not add any extra UTF8->UTF16 conversion overhead). + * + * @auto_expand works with @mui_dll_dirs, but only affects the processed + * string, making it somewhat useless. The unprocessed string is always expanded + * internally, if its type is `REG_EXPAND_SZ` - there is no need to enable + * @auto_expand for this to work. + * + * The API for this function changed in GLib 2.66 to add the @mui_dll_dirs argument. + * * Returns: %TRUE on success, %FALSE on failure. - * Since: 2.46 + * Since: 2.66 */ /** * g_win32_registry_key_get_value_w: * @key: (in) (transfer none): a #GWin32RegistryKey + * @mui_dll_dirs: (in) (transfer none) (array zero-terminated=1) (optional): a %NULL-terminated + * array of directory names where the OS + * should look for a DLL indicated in a MUI string, if the + * DLL path in the string is not absolute * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR * to G_WIN32_REGISTRY_VALUE_STR. * @value_name: (in) (transfer none): name of the value to get (in UTF-16). @@ -42277,19 +42408,34 @@ * by @value_data. * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Get data from a value of a key. - * * Get data from a value of a key. String data is guaranteed to be * appropriately terminated and will be in UTF-16. * * When calling with value_data == NULL (to get data size without getting * the data itself) remember that returned size corresponds to possibly * unterminated string data (if value is some kind of string), because - * termination cannot be checked and fixed unless the data is retreived + * termination cannot be checked and fixed unless the data is retrieved * too. * + * When not %NULL, @mui_dll_dirs indicates that `RegLoadMUIStringW()` API + * should be used instead of the usual `RegQueryValueExW()`. This implies + * that the value being queried is of type `REG_SZ` or `REG_EXPAND_SZ` (if it is not, the function + * falls back to `RegQueryValueExW()`), and that this string must undergo special processing + * (see [`SHLoadIndirectString()` documentation](https://docs.microsoft.com/en-us/windows/win32/api/shlwapi/nf-shlwapi-shloadindirectstring) for an explanation on what + * kinds of strings are processed) to get the result. + * + * If no specific MUI DLL directories need to be used, pass + * the return value of g_win32_registry_get_os_dirs_w() as @mui_dll_dirs. + * + * @auto_expand works with @mui_dll_dirs, but only affects the processed + * string, making it somewhat useless. The unprocessed string is always expanded + * internally, if its type is `REG_EXPAND_SZ` - there is no need to enable + * @auto_expand for this to work. + * + * The API for this function changed in GLib 2.66 to add the @mui_dll_dirs argument. + * * Returns: %TRUE on success, %FALSE on failure. - * Since: 2.46 + * Since: 2.66 */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 931caca0..a9f47372 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -269,7 +269,7 @@ * * 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 + * but safe. 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. */ @@ -605,7 +605,7 @@ * 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 + * vulnerable to * [Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/). * * The key to choosing a good hash is unpredictability. Even @@ -1068,7 +1068,7 @@ * @G_IO_STATUS_EOF: End of file. * @G_IO_STATUS_AGAIN: Resource temporarily unavailable. * - * Stati returned by most of the #GIOFuncs functions. + * Statuses returned by most of the #GIOFuncs functions. */ @@ -2231,7 +2231,7 @@ * its grandchildren, and so on. Note that this is less * efficient than the other orders. * - * Specifies the type of traveral performed by g_tree_traverse(), + * Specifies the type of traversal 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 @@ -2540,6 +2540,63 @@ /** + * GUri: + * + * A parsed absolute URI. + * + * Since #GUri only represents absolute URIs, all #GUris will have a + * URI scheme, so g_uri_get_scheme() will always return a non-%NULL + * answer. Likewise, by definition, all URIs have a path component, so + * g_uri_get_path() will always return non-%NULL (though it may return + * the empty string). + * + * If the URI string has an "authority" component (that is, if the + * scheme is followed by "`://`" rather than just "`:`"), then the + * #GUri will contain a hostname, and possibly a port and "userinfo". + * Additionally, depending on how the #GUri was constructed/parsed, + * the userinfo may be split out into a username, password, and + * additional authorization-related parameters. + * + * Normally, the components of a #GUri will have all `%`-encoded + * characters decoded. However, if you construct/parse a #GUri with + * %G_URI_FLAGS_ENCODED, then the `%`-encoding will be preserved instead in + * the userinfo, path, and query fields (and in the host field if also + * created with %G_URI_FLAGS_NON_DNS). In particular, this is necessary if + * the URI may contain binary data or non-UTF-8 text, or if decoding + * the components might change the interpretation of the URI. + * + * For example, with the encoded flag: + * + * |[<!-- language="C" --> + * GUri *uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_ENCODED, &err); + * g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue"); + * ]| + * + * While the default `%`-decoding behaviour would give: + * + * |[<!-- language="C" --> + * GUri *uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_NONE, &err); + * g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http://host/path?param=value"); + * ]| + * + * During decoding, if an invalid UTF-8 string is encountered, parsing will fail + * with an error indicating the bad string location: + * + * |[<!-- language="C" --> + * GUri *uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fbad%3D%00alue", G_URI_FLAGS_NONE, &err); + * g_assert_error(err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY); + * ]| + * + * (you should pass %G_URI_FLAGS_ENCODED if you need to handle that case manually). + * + * #GUri is immutable once constructed, and can safely be accessed from + * multiple threads. Its reference counting is atomic. + * + * Since: 2.66 + */ + + +/** * GVariant: * * #GVariant is an opaque data structure and can only be accessed @@ -4858,7 +4915,7 @@ * If you need to clear the contents of the data, you will need to use an * ancillary function that calls g_rc_box_release_full(): * - * |[<!-- laguage="C" --> + * |[<!-- language="C" --> * static void * my_data_struct_release (MyDataStruct *data) * { @@ -5161,7 +5218,7 @@ * * The important caveat of bookmark files is that when you add a new * bookmark you must also add the application that is registering it, using - * g_bookmark_file_add_application() or g_bookmark_file_set_app_info(). + * g_bookmark_file_add_application() or g_bookmark_file_set_application_info(). * If a bookmark has no applications then it won't be dumped when creating * the on disk representation, using g_bookmark_file_to_data() or * g_bookmark_file_to_file(). @@ -5454,8 +5511,8 @@ * * #GDate is simple to use. First you need a "blank" date; you can get a * dynamically allocated date from g_date_new(), or you can declare an - * automatic variable or array and initialize it to a sane state by - * calling g_date_clear(). A cleared date is sane; it's safe to call + * automatic variable or array and initialize it by + * calling g_date_clear(). A cleared date is safe; it's safe to call * g_date_set_dmy() and the other mutator functions to initialize the * value of a cleared date. However, a cleared date is initially * invalid, meaning that it doesn't represent a day that exists. @@ -6009,15 +6066,78 @@ /** - * SECTION:gurifuncs - * @title: URI Functions - * @short_description: manipulating URIs + * SECTION:guri + * @short_description: URI-handling utilities + * @include: glib.h + * + * The #GUri type and related functions can be used to parse URIs into + * their components, and build valid URIs from individual components. + * + * ## Parsing URIs + * + * The most minimalist APIs for parsing URIs are g_uri_split() and + * g_uri_split_with_user(). These split a URI into its component + * parts, and return the parts; the difference between the two is that + * g_uri_split() treats the "userinfo" component of the URI as a + * single element, while g_uri_split_with_user() can (depending on the + * #GUriFlags you pass) treat it as containing a username, password, + * and authentication parameters. Alternatively, g_uri_split_network() + * can be used when you are only interested in the components that are + * needed to initiate a network connection to the service (scheme, + * host, and port). * - * Functions for manipulating Universal Resource Identifiers (URIs) as - * defined by - * [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt). - * It is highly recommended that you have read and - * understand RFC 3986 for understanding this API. + * g_uri_parse() is similar to g_uri_split(), but instead of returning + * individual strings, it returns a #GUri structure (and it requires + * that the URI be an absolute URI). + * + * g_uri_resolve_relative() and g_uri_parse_relative() allow you to + * resolve a relative URI relative to a base URI. + * g_uri_resolve_relative() takes two strings and returns a string, + * and g_uri_parse_relative() takes a #GUri and a string and returns a + * #GUri. + * + * All of the parsing functions take a #GUriFlags argument describing + * exactly how to parse the URI; see the documentation for that type + * for more details on the specific flags that you can pass. If you + * need to choose different flags based on the type of URI, you can + * use g_uri_peek_scheme() on the URI string to check the scheme + * first, and use that to decide what flags to parse it with. + * + * ## Building URIs + * + * g_uri_join() and g_uri_join_with_user() can be used to construct + * valid URI strings from a set of component strings; they are the + * inverse of g_uri_split() and g_uri_split_with_user(). + * + * Similarly, g_uri_build() and g_uri_build_with_user() can be used to + * construct a #GUri from a set of component strings. + * + * As with the parsing functions, the building functions take a + * #GUriFlags argument; in particular, it is important to keep in mind + * whether the URI components you are using have `%`-encoded + * characters in them or not, and pass the appropriate flags + * accordingly. + * + * ## `file://` URIs + * + * Note that Windows and Unix both define special rules for parsing + * `file://` URIs (involving non-UTF-8 character sets on Unix, and the + * interpretation of path separators on Windows). #GUri does not + * implement these rules. Use g_filename_from_uri() and + * g_filename_to_uri() if you want to properly convert between + * `file://` URIs and local filenames. + * + * ## URI Equality + * + * Note that there is no `g_uri_equal ()` function, because comparing + * URIs usefully requires scheme-specific knowledge that #GUri does + * not have. For example, "`http://example.com/`" and + * "`http://EXAMPLE.COM:80`" have exactly the same meaning according + * to the HTTP specification, and "`data:,foo`" and + * "`data:;base64,Zm9v`" resolve to the same thing according to the + * `data:` URI specification. + * + * Since: 2.66 */ @@ -7076,11 +7196,15 @@ * If any call to allocate memory using functions g_new(), g_new0(), g_renew(), * g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n() * fails, the application is terminated. This also means that there is no - * need to check if the call succeeded. On the other hand, g_try_...() family + * need to check if the call succeeded. On the other hand, the `g_try_...()` family * of functions returns %NULL on failure that can be used as a check * for unsuccessful memory allocation. The application is not terminated * in this case. * + * As all GLib functions and data structures use `g_malloc()` internally, unless + * otherwise specified, any allocation failure will result in the application + * being terminated. + * * It's important to match g_malloc() (and wrappers such as g_new()) with * g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with * g_slice_free(), plain malloc() with free(), and (if you're using C++) @@ -8431,7 +8555,7 @@ * g_time_zone_get_identifier(). * * A time zone contains a number of intervals. Each interval has - * an abbreviation to describe it (for example, ‘PDT’), an offet to UTC and a + * an abbreviation to describe it (for example, ‘PDT’), an offset to UTC and a * flag indicating if the daylight savings time is in effect during that * interval. A time zone always has at least one interval — interval 0. Note * that interval abbreviations are not the same as time zone identifiers @@ -9776,7 +9900,7 @@ * g_ascii_xdigit_value: * @c: an ASCII character. * - * Determines the numeric value of a character as a hexidecimal + * Determines the numeric value of a character as a hexadecimal * digit. Differs from g_unichar_xdigit_value() because it takes * a char, so there's no worry about sign extension if characters * are signed. @@ -10004,6 +10128,25 @@ /** + * g_assert_no_errno: + * @expr: the expression to check + * + * Debugging macro to check that an expression has a non-negative return value, + * as used by traditional POSIX functions (such as `rmdir()`) to indicate + * success. + * + * If the assertion fails (i.e. the @expr returns a negative value), an error + * message is logged and the testcase is marked as failed. The error message + * will contain the value of `errno` and its human-readable message from + * g_strerror(). + * + * This macro will clear the value of `errno` before executing @expr. + * + * Since: 2.66 + */ + + +/** * g_assert_no_error: * @err: a #GError, possibly %NULL * @@ -10903,7 +11046,7 @@ * @block_size: the size of the allocation, must be greater than 0 * * Allocates @block_size bytes of memory, and adds atomic - * referenc counting semantics to it. + * reference counting semantics to it. * * The contents of the returned data is set to zero. * @@ -11610,6 +11753,24 @@ * * Returns: a timestamp * Since: 2.12 + * Deprecated: 2.66: Use g_bookmark_file_get_added_date_time() instead, as + * `time_t` is deprecated due to the year 2038 problem. + */ + + +/** + * g_bookmark_file_get_added_date_time: + * @bookmark: a #GBookmarkFile + * @uri: a valid URI + * @error: return location for a #GError, or %NULL + * + * Gets the time the bookmark for @uri was added to @bookmark + * + * In the event the URI cannot be found, %NULL is returned and + * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + * + * Returns: (transfer none): a #GDateTime + * Since: 2.66 */ @@ -11624,7 +11785,7 @@ * @error: return location for a #GError, or %NULL * * Gets the registration information of @app_name for the bookmark for - * @uri. See g_bookmark_file_set_app_info() for more information about + * @uri. See g_bookmark_file_set_application_info() for more information about * the returned data. * * The string returned in @app_exec must be freed. @@ -11639,6 +11800,37 @@ * * Returns: %TRUE on success. * Since: 2.12 + * Deprecated: 2.66: Use g_bookmark_file_get_application_info() instead, as + * `time_t` is deprecated due to the year 2038 problem. + */ + + +/** + * g_bookmark_file_get_application_info: + * @bookmark: a #GBookmarkFile + * @uri: a valid URI + * @name: an application's name + * @exec: (out) (optional): return location for the command line of the application, or %NULL + * @count: (out) (optional): return location for the registration count, or %NULL + * @stamp: (out) (optional) (transfer none): return location for the last registration time, or %NULL + * @error: return location for a #GError, or %NULL + * + * Gets the registration information of @app_name for the bookmark for + * @uri. See g_bookmark_file_set_application_info() for more information 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. + * + * Returns: %TRUE on success. + * Since: 2.66 */ @@ -11768,6 +11960,24 @@ * * Returns: a timestamp * Since: 2.12 + * Deprecated: 2.66: Use g_bookmark_file_get_modified_date_time() instead, as + * `time_t` is deprecated due to the year 2038 problem. + */ + + +/** + * g_bookmark_file_get_modified_date_time: + * @bookmark: a #GBookmarkFile + * @uri: a valid URI + * @error: return location for a #GError, or %NULL + * + * Gets the time when the bookmark for @uri was last modified. + * + * In the event the URI cannot be found, %NULL is returned and + * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + * + * Returns: (transfer none): a #GDateTime + * Since: 2.66 */ @@ -11829,6 +12039,24 @@ * * Returns: a timestamp. * Since: 2.12 + * Deprecated: 2.66: Use g_bookmark_file_get_visited_date_time() instead, as + * `time_t` is deprecated due to the year 2038 problem. + */ + + +/** + * g_bookmark_file_get_visited_date_time: + * @bookmark: a #GBookmarkFile + * @uri: a valid URI + * @error: return location for a #GError, or %NULL + * + * Gets the time the bookmark for @uri was last visited. + * + * In the event the URI cannot be found, %NULL is returned and + * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + * + * Returns: (transfer none): a #GDateTime + * Since: 2.66 */ @@ -12030,6 +12258,22 @@ * If no bookmark for @uri is found then it is created. * * Since: 2.12 + * Deprecated: 2.66: Use g_bookmark_file_set_added_date_time() instead, as + * `time_t` is deprecated due to the year 2038 problem. + */ + + +/** + * g_bookmark_file_set_added_date_time: + * @bookmark: a #GBookmarkFile + * @uri: a valid URI + * @added: a #GDateTime + * + * Sets the time the bookmark for @uri was added into @bookmark. + * + * If no bookmark for @uri is found then it is created. + * + * Since: 2.66 */ @@ -12056,7 +12300,7 @@ * 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. + * command line using the g_bookmark_file_get_application_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 @@ -12075,6 +12319,53 @@ * Returns: %TRUE if the application's meta-data was successfully * changed. * Since: 2.12 + * Deprecated: 2.66: Use g_bookmark_file_set_application_info() instead, as + * `time_t` is deprecated due to the year 2038 problem. + */ + + +/** + * g_bookmark_file_set_application_info: + * @bookmark: a #GBookmarkFile + * @uri: a valid URI + * @name: an application's name + * @exec: an application's command line + * @count: the number of registrations done for this application + * @stamp: (nullable): the time of the last registration for this application, + * which may be %NULL if @count is 0 + * @error: return location for a #GError or %NULL + * + * 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_application_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 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. + * + * Returns: %TRUE if the application's meta-data was successfully + * changed. + * Since: 2.66 */ @@ -12169,9 +12460,30 @@ * 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(). + * g_bookmark_file_set_visited_date_time(). * * Since: 2.12 + * Deprecated: 2.66: Use g_bookmark_file_set_modified_date_time() instead, as + * `time_t` is deprecated due to the year 2038 problem. + */ + + +/** + * g_bookmark_file_set_modified_date_time: + * @bookmark: a #GBookmarkFile + * @uri: a valid URI + * @modified: a #GDateTime + * + * 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_date_time(). + * + * Since: 2.66 */ @@ -12203,12 +12515,34 @@ * 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() + * either using the command line retrieved by g_bookmark_file_get_application_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. * * Since: 2.12 + * Deprecated: 2.66: Use g_bookmark_file_set_visited_date_time() instead, as + * `time_t` is deprecated due to the year 2038 problem. + */ + + +/** + * g_bookmark_file_set_visited_date_time: + * @bookmark: a #GBookmarkFile + * @uri: a valid URI + * @visited: a #GDateTime + * + * 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_application_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. + * + * Since: 2.66 */ @@ -14139,7 +14473,7 @@ * @date: pointer to one or more dates to clear * @n_dates: number of dates to clear * - * Initializes one or more #GDate structs to a sane but invalid + * Initializes one or more #GDate structs to a safe 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(). @@ -14378,7 +14712,7 @@ * g_date_new: * * Allocates a #GDate and initializes - * it to a sane state. The new date will + * it to a safe 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(). * @@ -14612,8 +14946,8 @@ * * Creates a copy of @datetime and adds the specified timespan to the copy. * - * Returns: the newly created #GDateTime which should be freed with - * g_date_time_unref(). + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -14626,8 +14960,8 @@ * Creates a copy of @datetime and adds the specified number of days to the * copy. Add negative values to subtract days. * - * Returns: the newly created #GDateTime which should be freed with - * g_date_time_unref(). + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -14645,8 +14979,8 @@ * Creates a new #GDateTime adding the specified values to the current date and * time in @datetime. Add negative values to subtract. * - * Returns: the newly created #GDateTime that should be freed with - * g_date_time_unref(). + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -14659,8 +14993,8 @@ * Creates a copy of @datetime and adds the specified number of hours. * Add negative values to subtract hours. * - * Returns: the newly created #GDateTime which should be freed with - * g_date_time_unref(). + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -14673,8 +15007,8 @@ * Creates a copy of @datetime adding the specified number of minutes. * Add negative values to subtract minutes. * - * Returns: the newly created #GDateTime which should be freed with - * g_date_time_unref(). + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -14692,8 +15026,8 @@ * 31st January 2018, the result would be 28th February 2018. In 2020 (a leap * year), the result would be 29th February. * - * Returns: the newly created #GDateTime which should be freed with - * g_date_time_unref(). + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -14706,8 +15040,8 @@ * Creates a copy of @datetime and adds the specified number of seconds. * Add negative values to subtract seconds. * - * Returns: the newly created #GDateTime which should be freed with - * g_date_time_unref(). + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -14720,8 +15054,8 @@ * Creates a copy of @datetime and adds the specified number of weeks to the * copy. Add negative values to subtract weeks. * - * Returns: the newly created #GDateTime which should be freed with - * g_date_time_unref(). + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -14737,8 +15071,8 @@ * As with g_date_time_add_months(), if the resulting date would be 29th * February on a non-leap year, the day will be clamped to 28th February. * - * Returns: the newly created #GDateTime which should be freed with - * g_date_time_unref(). + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -14833,10 +15167,14 @@ * - \%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". + * "PM" and midnight as "AM". Use of this format specifier is discouraged, as + * many locales have no concept of AM/PM formatting. Use \%c or \%X instead. * - \%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 + * the current locale. Use of this format specifier is discouraged, as + * many locales have no concept of AM/PM formatting. Use \%c or \%X instead. + * - \%r: the time in a.m. or p.m. notation. Use of this format specifier is + * discouraged, as many locales have no concept of AM/PM formatting. Use \%c + * or \%X instead. * - \%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 @@ -14888,10 +15226,10 @@ * strftime() extension expected to be added to the future POSIX specification, * \%Ob and \%Oh are GNU strftime() extensions. Since: 2.56 * - * Returns: a newly allocated string formatted to the requested format - * or %NULL in the case that there was an error (such as a format specifier - * not being supported in the current locale). The string - * should be freed with g_free(). + * Returns: (transfer full) (nullable): a newly allocated string formatted to + * the requested format or %NULL in the case that there was an error (such + * as a format specifier not being supported in the current locale). The + * string should be freed with g_free(). * Since: 2.26 */ @@ -14904,9 +15242,9 @@ * including the date, time and time zone, and return that as a UTF-8 encoded * string. * - * Returns: a newly allocated string formatted in ISO 8601 format - * or %NULL in the case that there was an error. The string - * should be freed with g_free(). + * Returns: (transfer full) (nullable): a newly allocated string formatted in + * ISO 8601 format or %NULL in the case that there was an error. The string + * should be freed with g_free(). * Since: 2.62 */ @@ -15177,7 +15515,7 @@ /** - * g_date_time_new: + * g_date_time_new: (constructor) * @tz: a #GTimeZone * @year: the year component of the date * @month: the month component of the date @@ -15215,13 +15553,13 @@ * You should release the return value by calling g_date_time_unref() * when you are done with it. * - * Returns: a new #GDateTime, or %NULL + * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL * Since: 2.26 */ /** - * g_date_time_new_from_iso8601: + * g_date_time_new_from_iso8601: (constructor) * @text: an ISO 8601 formatted time string. * @default_tz: (nullable): a #GTimeZone to use if the text doesn't contain a * timezone, or %NULL. @@ -15276,7 +15614,7 @@ /** - * g_date_time_new_from_timeval_local: + * g_date_time_new_from_timeval_local: (constructor) * @tv: a #GTimeVal * * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the @@ -15292,7 +15630,7 @@ * You should release the return value by calling g_date_time_unref() * when you are done with it. * - * Returns: a new #GDateTime, or %NULL + * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL * Since: 2.26 * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use * g_date_time_new_from_unix_local() instead. @@ -15300,7 +15638,7 @@ /** - * g_date_time_new_from_timeval_utc: + * g_date_time_new_from_timeval_utc: (constructor) * @tv: a #GTimeVal * * Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC. @@ -15314,7 +15652,7 @@ * You should release the return value by calling g_date_time_unref() * when you are done with it. * - * Returns: a new #GDateTime, or %NULL + * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL * Since: 2.26 * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use * g_date_time_new_from_unix_utc() instead. @@ -15322,7 +15660,7 @@ /** - * g_date_time_new_from_unix_local: + * g_date_time_new_from_unix_local: (constructor) * @t: the Unix time * * Creates a #GDateTime corresponding to the given Unix time @t in the @@ -15337,13 +15675,13 @@ * You should release the return value by calling g_date_time_unref() * when you are done with it. * - * Returns: a new #GDateTime, or %NULL + * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL * Since: 2.26 */ /** - * g_date_time_new_from_unix_utc: + * g_date_time_new_from_unix_utc: (constructor) * @t: the Unix time * * Creates a #GDateTime corresponding to the given Unix time @t in UTC. @@ -15357,13 +15695,13 @@ * You should release the return value by calling g_date_time_unref() * when you are done with it. * - * Returns: a new #GDateTime, or %NULL + * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL * Since: 2.26 */ /** - * g_date_time_new_local: + * g_date_time_new_local: (constructor) * @year: the year component of the date * @month: the month component of the date * @day: the day component of the date @@ -15377,33 +15715,32 @@ * This call is equivalent to calling g_date_time_new() with the time * zone returned by g_time_zone_new_local(). * - * Returns: a #GDateTime, or %NULL + * Returns: (transfer full) (nullable): a #GDateTime, or %NULL * Since: 2.26 */ /** - * g_date_time_new_now: + * g_date_time_new_now: (constructor) * @tz: a #GTimeZone * * 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). + * This function will always succeed 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. * - * Returns: a new #GDateTime, or %NULL + * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL * Since: 2.26 */ /** - * g_date_time_new_now_local: + * g_date_time_new_now_local: (constructor) * * Creates a #GDateTime corresponding to this exact instant in the local * time zone. @@ -15411,26 +15748,26 @@ * This is equivalent to calling g_date_time_new_now() with the time * zone returned by g_time_zone_new_local(). * - * Returns: a new #GDateTime, or %NULL + * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL * Since: 2.26 */ /** - * g_date_time_new_now_utc: + * g_date_time_new_now_utc: (constructor) * * 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(). * - * Returns: a new #GDateTime, or %NULL + * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL * Since: 2.26 */ /** - * g_date_time_new_utc: + * g_date_time_new_utc: (constructor) * @year: the year component of the date * @month: the month component of the date * @day: the day component of the date @@ -15444,7 +15781,7 @@ * This call is equivalent to calling g_date_time_new() with the time * zone returned by g_time_zone_new_utc(). * - * Returns: a #GDateTime, or %NULL + * Returns: (transfer full) (nullable): a #GDateTime, or %NULL * Since: 2.26 */ @@ -15470,7 +15807,8 @@ * This call is equivalent to calling g_date_time_to_timezone() with the * time zone returned by g_time_zone_new_local(). * - * Returns: the newly created #GDateTime + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -15513,10 +15851,8 @@ * 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. - * - * Returns: a new #GDateTime, or %NULL + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -15546,7 +15882,8 @@ * This call is equivalent to calling g_date_time_to_timezone() with the * time zone returned by g_time_zone_new_utc(). * - * Returns: the newly created #GDateTime + * Returns: (transfer full) (nullable): the newly created #GDateTime which + * should be freed with g_date_time_unref(), or %NULL * Since: 2.26 */ @@ -15570,7 +15907,7 @@ * @tm: (not nullable): struct tm to fill * * Fills in the date-related bits of a struct tm using the @date value. - * Initializes the non-date parts with something sane but meaningless. + * Initializes the non-date parts with something safe but meaningless. */ @@ -18848,7 +19185,7 @@ * @buf: (out caller-allocates) (array length=count) (element-type guint8): * a buffer to read data into * @count: (in): the size of the buffer. Note that the buffer may not be - * complelely filled even if there is data in the buffer if the + * completely filled even if there is data in the buffer if the * remaining data is not a complete character. * @bytes_read: (out) (optional): The number of bytes read. This may be * zero even on success if count < 6 and the channel's encoding @@ -19781,7 +20118,7 @@ * @full_path. If the file could not be loaded then an %error is * set to either a #GFileError or #GKeyFileError. * - * Returns: %TRUE if a key file could be loaded, %FALSE othewise + * Returns: %TRUE if a key file could be loaded, %FALSE otherwise * Since: 2.6 */ @@ -20880,7 +21217,7 @@ * * - `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which * messages should be prefixed by the program name and PID of the - * aplication. + * application. * * - `G_MESSAGES_DEBUG`: A space-separated list of log domains for * which debug and informational messages are printed. By default @@ -26938,7 +27275,7 @@ * Compiles the regular expression to an internal form, and does * the initial setup of the #GRegex structure. * - * Returns: (nullable): a #GRegex structure or %NULL if an error occured. Call + * Returns: (nullable): a #GRegex structure or %NULL if an error occurred. Call * g_regex_unref() when you are done with it * Since: 2.14 */ @@ -26985,7 +27322,7 @@ * 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 + * passed to g_regex_new(). If you want to use not UTF-8 encoded strings * you can use g_regex_replace_literal(). * * Setting @start_position differs from just passing over a shortened @@ -31010,7 +31347,7 @@ * to be used, or %NULL * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters * - * Appends @unescaped to @string, escaped any characters that + * Appends @unescaped to @string, escaping any characters that * are reserved in URIs using URI-style escape sequences. * * Returns: (transfer none): @string @@ -32659,16 +32996,14 @@ /** * g_test_set_nonfatal_assertions: * - * 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 + * Changes the behaviour of the various `g_assert_*()` macros, + * 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 + * Note that the g_assert_not_reached() and g_assert() macros are not * affected by this. * * This function can only be called after g_test_init(). @@ -33075,7 +33410,7 @@ /** * g_thread_join: - * @thread: a #GThread + * @thread: (transfer full): a #GThread * * Waits until @thread finishes, i.e. the function @func, as * given to g_thread_new(), returns or g_thread_exit() is called. @@ -33094,15 +33429,15 @@ * 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. * - * Returns: the return value of the thread + * Returns: (transfer full): the return value of the thread */ /** * g_thread_new: * @name: (nullable): an (optional) name for the new thread - * @func: a function to execute in the new thread - * @data: an argument to supply to the new thread + * @func: (closure data) (scope async): a function to execute in the new thread + * @data: (nullable): an argument to supply to the new thread * * This function creates a new thread. The new thread starts by invoking * @func with the argument data. The thread will run until @func returns @@ -33132,7 +33467,7 @@ * Starting with GLib 2.64 the behaviour is now consistent between Windows and * POSIX and all threads inherit their parent thread's priority. * - * Returns: the new #GThread + * Returns: (transfer full): the new #GThread * Since: 2.32 */ @@ -33151,10 +33486,10 @@ * 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 + * If @wait_ is %TRUE, this function 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. + * Otherwise this function returns immediately. * * After calling this function @pool must not be used anymore. */ @@ -33408,7 +33743,7 @@ * * Increase the reference count on @thread. * - * Returns: a new reference to @thread + * Returns: (transfer full): a new reference to @thread * Since: 2.32 */ @@ -33426,7 +33761,7 @@ * (i.e. comparisons) but you must not use GLib functions (such * as g_thread_join()) on these threads. * - * Returns: the #GThread representing the current thread + * Returns: (transfer none): the #GThread representing the current thread */ @@ -33446,8 +33781,8 @@ /** * g_thread_try_new: * @name: (nullable): an (optional) name for the new thread - * @func: a function to execute in the new thread - * @data: an argument to supply to the new thread + * @func: (closure data) (scope async): a function to execute in the new thread + * @data: (nullable): an argument to supply to the new thread * @error: return location for error, or %NULL * * This function is the same as g_thread_new() except that @@ -33456,14 +33791,14 @@ * If a thread can not be created (due to resource limits), * @error is set and %NULL is returned. * - * Returns: the new #GThread, or %NULL if an error occurred + * Returns: (transfer full): the new #GThread, or %NULL if an error occurred * Since: 2.32 */ /** * g_thread_unref: - * @thread: a #GThread + * @thread: (transfer full): a #GThread * * Decrease the reference count on @thread, possibly freeing all * resources associated with it. @@ -35026,7 +35361,7 @@ * g_unichar_isxdigit: * @c: a Unicode character. * - * Determines if a character is a hexidecimal digit. + * Determines if a character is a hexadecimal digit. * * Returns: %TRUE if the character is a hexadecimal digit */ @@ -35126,7 +35461,7 @@ * g_unichar_xdigit_value: * @c: a Unicode character * - * Determines the numeric value of a character as a hexidecimal + * Determines the numeric value of a character as a hexadecimal * digit. * * Returns: If @c is a hex digit (according to @@ -35436,28 +35771,313 @@ /** + * g_uri_build: + * @flags: flags describing how to build the #GUri + * @scheme: the URI scheme + * @userinfo: (nullable): the userinfo component, or %NULL + * @host: (nullable): the host component, or %NULL + * @port: the port, or -1 + * @path: the path component + * @query: (nullable): the query component, or %NULL + * @fragment: (nullable): the fragment, or %NULL + * + * Creates a new #GUri from the given components according to @flags. + * + * See also g_uri_build_with_user(), which allows specifying the + * components of the "userinfo" separately. + * + * Returns: (transfer full): a new #GUri + * Since: 2.66 + */ + + +/** + * g_uri_build_with_user: + * @flags: flags describing how to build the #GUri + * @scheme: the URI scheme + * @user: (nullable): the user component of the userinfo, or %NULL + * @password: (nullable): the password component of the userinfo, or %NULL + * @auth_params: (nullable): the auth params of the userinfo, or %NULL + * @host: (nullable): the host component, or %NULL + * @port: the port, or -1 + * @path: the path component + * @query: (nullable): the query component, or %NULL + * @fragment: (nullable): the fragment, or %NULL + * + * Creates a new #GUri from the given components according to @flags. + * + * In constrast to g_uri_build(), this allows specifying the components + * of the "userinfo" field separately. Note that @user must be non-%NULL + * if either @password or @auth_params is non-%NULL. + * + * Returns: (transfer full): a new #GUri + * Since: 2.66 + */ + + +/** + * g_uri_escape_bytes: + * @unescaped: (array length=length): the unescaped input data. + * @length: the length of @unescaped + * @reserved_chars_allowed: (nullable): a string of reserved + * characters that are allowed to be used, or %NULL. + * + * Escapes arbitrary data 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. + * + * Though technically incorrect, this will also allow escaping "0" + * bytes as "`%``00`". + * + * Returns: an escaped version of @unescaped. The returned string + * should be freed when no longer needed. + * Since: 2.66 + */ + + +/** * g_uri_escape_string: * @unescaped: the unescaped input string. - * @reserved_chars_allowed: (nullable): a string of reserved characters that - * are allowed to be used, or %NULL. + * @reserved_chars_allowed: (nullable): a string of reserved + * characters that are allowed to be used, or %NULL. * @allow_utf8: %TRUE if the result can include UTF-8 characters. * * 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. + * 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. * - * Returns: an escaped version of @unescaped. The returned string should be - * freed when no longer needed. + * Returns: an escaped version of @unescaped. The returned string + * should be freed when no longer needed. * Since: 2.16 */ /** + * g_uri_get_auth_params: + * @uri: a #GUri + * + * Gets @uri's authentication parameters, which may contain + * `%`-encoding, depending on the flags with which @uri was created. + * (If @uri was not created with %G_URI_FLAGS_HAS_AUTH_PARAMS then this will + * be %NULL.) + * + * Depending on the URI scheme, g_uri_parse_params() may be useful for + * further parsing this information. + * + * Returns: @uri's authentication parameters. + * Since: 2.66 + */ + + +/** + * g_uri_get_flags: + * @uri: a #GUri + * + * Gets @uri's flags set upon construction. + * + * Returns: @uri's flags. + * Since: 2.66 + */ + + +/** + * g_uri_get_fragment: + * @uri: a #GUri + * + * Gets @uri's fragment, which may contain `%`-encoding, depending on + * the flags with which @uri was created. + * + * Returns: @uri's fragment. + * Since: 2.66 + */ + + +/** + * g_uri_get_host: + * @uri: a #GUri + * + * Gets @uri's host. This will never have `%`-encoded characters, + * unless it is non-UTF-8 (which can only be the case if @uri was + * created with %G_URI_FLAGS_NON_DNS). + * + * If @uri contained an IPv6 address literal, this value will be just + * that address, without the brackets around it that are necessary in + * the string form of the URI. Note that in this case there may also + * be a scope ID attached to the address. Eg, "`fe80::1234%``em1`" (or + * "`fe80::1234%``25em1" if the string is still encoded). + * + * Returns: @uri's host. + * Since: 2.66 + */ + + +/** + * g_uri_get_password: + * @uri: a #GUri + * + * Gets @uri's password, which may contain `%`-encoding, depending on + * the flags with which @uri was created. (If @uri was not created + * with %G_URI_FLAGS_HAS_PASSWORD then this will be %NULL.) + * + * Returns: @uri's password. + * Since: 2.66 + */ + + +/** + * g_uri_get_path: + * @uri: a #GUri + * + * Gets @uri's path, which may contain `%`-encoding, depending on the + * flags with which @uri was created. + * + * Returns: @uri's path. + * Since: 2.66 + */ + + +/** + * g_uri_get_port: + * @uri: a #GUri + * + * Gets @uri's port. + * + * Returns: @uri's port, or -1 if no port was specified. + * Since: 2.66 + */ + + +/** + * g_uri_get_query: + * @uri: a #GUri + * + * Gets @uri's query, which may contain `%`-encoding, depending on the + * flags with which @uri was created. + * + * For queries consisting of a series of "`name=value`" parameters, + * g_uri_parse_params() may be useful. + * + * Returns: @uri's query. + * Since: 2.66 + */ + + +/** + * g_uri_get_scheme: + * @uri: a #GUri + * + * Gets @uri's scheme. Note that this will always be all-lowercase, + * regardless of the string or strings that @uri was created from. + * + * Returns: @uri's scheme. + * Since: 2.66 + */ + + +/** + * g_uri_get_user: + * @uri: a #GUri + * + * Gets the "username" component of @uri's userinfo, which may contain + * `%`-encoding, depending on the flags with which @uri was created. + * If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD or + * %G_URI_FLAGS_HAS_AUTH_PARAMS, this is the same as g_uri_get_userinfo(). + * + * Returns: @uri's user. + * Since: 2.66 + */ + + +/** + * g_uri_get_userinfo: + * @uri: a #GUri + * + * Gets @uri's userinfo, which may contain `%`-encoding, depending on + * the flags with which @uri was created. + * + * Returns: @uri's userinfo. + * Since: 2.66 + */ + + +/** + * g_uri_is_valid: + * @uri_string: a string containing a relative or absolute URI + * @flags: flags for parsing @uri_string + * @error: #GError for error reporting, or %NULL to ignore. + * + * Parses @uri_string (which can be an absolute or relative URI) + * according to @flags, to determine whether it is valid. + * + * See g_uri_split(), and the definition of #GUriFlags, for more + * information on the effect of @flags. + * + * Returns: %TRUE if @uri_string parsed successfully, %FALSE on error. + * Since: 2.66 + */ + + +/** + * g_uri_join: + * @flags: flags describing how to build the URI string + * @scheme: the URI scheme + * @userinfo: (nullable): the userinfo component, or %NULL + * @host: (nullable): the host component, or %NULL + * @port: the port, or -1 + * @path: the path component + * @query: (nullable): the query component, or %NULL + * @fragment: (nullable): the fragment, or %NULL + * + * Joins the given components together according to @flags to create + * a complete URI string. At least @scheme must be specified, and + * @path may not be %NULL (though it may be ""). + * + * See also g_uri_join_with_user(), which allows specifying the + * components of the "userinfo" separately. + * + * Returns: a URI string + * Since: 2.66 + */ + + +/** + * g_uri_join_with_user: + * @flags: flags describing how to build the URI string + * @scheme: the URI scheme + * @user: (nullable): the user component of the userinfo, or %NULL + * @password: (nullable): the password component of the userinfo, or + * %NULL + * @auth_params: (nullable): the auth params of the userinfo, or + * %NULL + * @host: (nullable): the host component, or %NULL + * @port: the port, or -1 + * @path: the path component + * @query: (nullable): the query component, or %NULL + * @fragment: (nullable): the fragment, or %NULL + * + * Joins the given components together according to @flags to create + * a complete URI string. At least @scheme must be specified, and + * @path may not be %NULL (though it may be ""). + * + * In constrast to g_uri_join(), this allows specifying the components + * of the "userinfo" separately. + * + * Returns: a URI string + * Since: 2.66 + */ + + +/** * g_uri_list_extract_uris: * @uri_list: an URI list * @@ -35473,6 +36093,65 @@ /** + * g_uri_parse: + * @uri_string: a string representing an absolute URI + * @flags: flags describing how to parse @uri_string + * @error: #GError for error reporting, or %NULL to ignore. + * + * Parses @uri_string according to @flags. If the result is not a + * valid absolute URI, it will be discarded, and an error returned. + * + * Returns: (transfer full): a new #GUri. + * Since: 2.66 + */ + + +/** + * g_uri_parse_params: + * @params: a `%`-encoded string containing "attribute=value" + * parameters + * @length: the length of @params, or -1 if it is NUL-terminated + * @separator: the separator character between parameters. + * (usually ';', but sometimes '&') + * @case_insensitive: whether parameter names are case insensitive + * + * Many URI schemes include one or more attribute/value pairs as part of the URI + * value. This method can be used to parse them into a hash table. + * + * The @params string is assumed to still be `%`-encoded, but the returned + * values will be fully decoded. (Thus it is possible that the returned values + * may contain '=' or @separator, if the value was encoded in the input.) + * Invalid `%`-encoding is treated as with the non-%G_URI_FLAGS_PARSE_STRICT + * rules for g_uri_parse(). (However, if @params is the path or query string + * from a #GUri that was parsed with %G_URI_FLAGS_PARSE_STRICT and + * %G_URI_FLAGS_ENCODED, then you already know that it does not contain any + * invalid encoding.) + * + * Returns: (transfer full) (element-type utf8 utf8): a hash table of + * attribute/value pairs. Both names and values will be fully-decoded. If + * @params cannot be parsed (eg, it contains two @separator characters in a + * row), then %NULL is returned. + * Since: 2.66 + */ + + +/** + * g_uri_parse_relative: + * @base_uri: (nullable): a base URI + * @uri_string: a string representing a relative or absolute URI + * @flags: flags describing how to parse @uri_string + * @error: #GError for error reporting, or %NULL to ignore. + * + * Parses @uri_string according to @flags and, if it is a relative + * URI, resolves it relative to @base_uri. If the result is not a + * valid absolute URI, it will be discarded, and an error returned. + * + * Returns: (transfer full): a new #GUri. + * Since: 2.66 + */ + + +/** * g_uri_parse_scheme: * @uri: a valid URI. * @@ -35482,25 +36161,235 @@ * ]| * Common schemes include "file", "http", "svn+ssh", etc. * - * Returns: The "Scheme" component of the URI, or %NULL on error. + * Returns: The "scheme" component of the URI, or %NULL on error. * The returned string should be freed when no longer needed. * Since: 2.16 */ /** + * g_uri_peek_scheme: + * @uri: a valid URI. + * + * 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. + * + * Returns: The "scheme" component of the URI, or %NULL on error. The + * returned string is normalized to all-lowercase, and interned via + * g_intern_string(), so it does not need to be freed. + * Since: 2.66 + */ + + +/** + * g_uri_ref: (skip) + * @uri: a #GUri + * + * Increments the reference count of @uri by one. + * + * Returns: @uri + * Since: 2.66 + */ + + +/** + * g_uri_resolve_relative: + * @base_uri_string: (nullable): a string representing a base URI + * @uri_string: a string representing a relative or absolute URI + * @flags: flags describing how to parse @uri_string + * @error: #GError for error reporting, or %NULL to ignore. + * + * Parses @uri_string according to @flags and, if it is a relative + * URI, resolves it relative to @base_uri_string. If the result is not + * a valid absolute URI, it will be discarded, and an error returned. + * + * (If @base_uri_string is %NULL, this just returns @uri_string, or + * %NULL if @uri_string is invalid or not absolute.) + * + * Returns: the resolved URI string. + * Since: 2.66 + */ + + +/** + * g_uri_split: + * @uri_string: a string containing a relative or absolute URI + * @flags: flags for parsing @uri_string + * @scheme: (out) (nullable) (optional) (transfer full): on return, contains + * the scheme (converted to lowercase), or %NULL + * @userinfo: (out) (nullable) (optional) (transfer full): on return, contains + * the userinfo, or %NULL + * @host: (out) (nullable) (optional) (transfer full): on return, contains the + * host, or %NULL + * @port: (out) (nullable) (optional) (transfer full): on return, contains the + * port, or -1 + * @path: (out) (nullable) (optional) (transfer full): on return, contains the + * path + * @query: (out) (nullable) (optional) (transfer full): on return, contains the + * query, or %NULL + * @fragment: (out) (nullable) (optional) (transfer full): on return, contains + * the fragment, or %NULL + * @error: #GError for error reporting, or %NULL to ignore. + * + * Parses @uri_string (which can be an absolute or relative URI) + * according to @flags, and returns the pieces. Any component that + * doesn't appear in @uri_string will be returned as %NULL (but note + * that all URIs always have a path component, though it may be the + * empty string). + * + * If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in + * @uri_string will remain encoded in the output strings. (If not, + * then all such characters will be decoded.) Note that decoding will + * only work if the URI components are ASCII or UTF-8, so you will + * need to use %G_URI_FLAGS_ENCODED if they are not. + * + * Note that the %G_URI_FLAGS_HAS_PASSWORD and + * %G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(), + * since it always returns only the full userinfo; use + * g_uri_split_with_user() if you want it split up. + * + * Returns: (skip): %TRUE if @uri_string parsed successfully, %FALSE + * on error. + * Since: 2.66 + */ + + +/** + * g_uri_split_network: + * @uri_string: a string containing a relative or absolute URI + * @flags: flags for parsing @uri_string + * @scheme: (out) (nullable) (optional) (transfer full): on return, contains + * the scheme (converted to lowercase), or %NULL + * @host: (out) (nullable) (optional) (transfer full): on return, contains the + * host, or %NULL + * @port: (out) (nullable) (optional) (transfer full): on return, contains the + * port, or -1 + * @error: #GError for error reporting, or %NULL to ignore. + * + * Parses @uri_string (which must be an absolute URI) according to + * @flags, and returns the pieces relevant to connecting to a host. + * See the documentation for g_uri_split() for more details; this is + * mostly a wrapper around that function with simpler arguments. + * However, it will return an error if @uri_string is a relative URI, + * or does not contain a hostname component. + * + * Returns: (skip): %TRUE if @uri_string parsed successfully, + * %FALSE on error. + * Since: 2.66 + */ + + +/** + * g_uri_split_with_user: + * @uri_string: a string containing a relative or absolute URI + * @flags: flags for parsing @uri_string + * @scheme: (out) (nullable) (optional) (transfer full): on return, contains + * the scheme (converted to lowercase), or %NULL + * @user: (out) (nullable) (optional) (transfer full): on return, contains + * the user, or %NULL + * @password: (out) (nullable) (optional) (transfer full): on return, contains + * the password, or %NULL + * @auth_params: (out) (nullable) (optional) (transfer full): on return, contains + * the auth_params, or %NULL + * @host: (out) (nullable) (optional) (transfer full): on return, contains the + * host, or %NULL + * @port: (out) (nullable) (optional) (transfer full): on return, contains the + * port, or -1 + * @path: (out) (nullable) (optional) (transfer full): on return, contains the + * path + * @query: (out) (nullable) (optional) (transfer full): on return, contains the + * query, or %NULL + * @fragment: (out) (nullable) (optional) (transfer full): on return, contains + * the fragment, or %NULL + * @error: #GError for error reporting, or %NULL to ignore. + * + * Parses @uri_string (which can be an absolute or relative URI) + * according to @flags, and returns the pieces. Any component that + * doesn't appear in @uri_string will be returned as %NULL (but note + * that all URIs always have a path component, though it may be the + * empty string). + * + * See g_uri_split(), and the definition of #GUriFlags, for more + * information on the effect of @flags. Note that @password will only + * be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and + * @auth_params will only be parsed out if @flags contains + * %G_URI_FLAGS_HAS_AUTH_PARAMS. + * + * Returns: (skip): %TRUE if @uri_string parsed successfully, %FALSE + * on error. + * Since: 2.66 + */ + + +/** + * g_uri_to_string: + * @uri: a #GUri + * + * Returns a string representing @uri. + * + * This is not guaranteed to return a string which is identical to the + * string that @uri was parsed from. However, if the source URI was + * syntactically correct (according to RFC 3986), and it was parsed + * with %G_URI_FLAGS_ENCODED, then g_uri_to_string() is guaranteed to return + * a string which is at least semantically equivalent to the source + * URI (according to RFC 3986). + * + * Returns: a string representing @uri, which the caller must + * free. + * Since: 2.66 + */ + + +/** + * g_uri_to_string_partial: + * @uri: a #GUri + * @flags: flags describing what parts of @uri to hide + * + * Returns a string representing @uri, subject to the options in + * @flags. See g_uri_to_string() and #GUriHideFlags for more details. + * + * Returns: a string representing @uri, which the caller must + * free. + * Since: 2.66 + */ + + +/** + * g_uri_unescape_bytes: + * @escaped_string: A URI-escaped string + * @length: the length of @escaped_string to escape, or -1 if it + * is NUL-terminated. + * + * Unescapes a segment of an escaped string as binary data. + * + * Note that in contrast to g_uri_unescape_string(), this does allow + * `NUL` bytes to appear in the output. + * + * Returns: (transfer full): an unescaped version of @escaped_string + * or %NULL on error. The returned #GBytes should be unreffed when no + * longer needed. + * Since: 2.66 + */ + + +/** * g_uri_unescape_segment: * @escaped_string: (nullable): A string, may be %NULL - * @escaped_string_end: (nullable): Pointer to end of @escaped_string, may be %NULL - * @illegal_characters: (nullable): An optional string of illegal characters not to be allowed, may be %NULL + * @escaped_string_end: (nullable): Pointer to end of @escaped_string, + * may be %NULL + * @illegal_characters: (nullable): An optional string of illegal + * characters not to be allowed, may be %NULL * * 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. + * If any of the characters in @illegal_characters or the NUL + * character appears as an escaped character in @escaped_string, then + * that is an error and %NULL will be returned. This is useful if you + * want to avoid for instance having a slash being expanded in an + * escaped path element, which might confuse pathname handling. * * Returns: an unescaped version of @escaped_string or %NULL on error. * The returned string should be freed when no longer needed. As a @@ -35513,16 +36402,16 @@ /** * g_uri_unescape_string: * @escaped_string: an escaped string to be unescaped. - * @illegal_characters: (nullable): a string of illegal characters not to be - * allowed, or %NULL. + * @illegal_characters: (nullable): a string of illegal characters + * not to be allowed, or %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. + * If any of the characters in @illegal_characters or the NUL + * character appears as an escaped character in @escaped_string, then + * that is an error and %NULL will be returned. This is useful if you + * want to avoid for instance having a slash being expanded in an + * escaped path element, which might confuse pathname handling. * * Returns: an unescaped version of @escaped_string. The returned string * should be freed when no longer needed. @@ -35531,6 +36420,19 @@ /** + * g_uri_unref: (skip) + * @uri: a #GUri + * + * Atomically decrements the reference count of @uri by one. + * + * When the reference count reaches zero, the resources allocated by + * @uri are freed + * + * Since: 2.66 + */ + + +/** * g_usleep: * @microseconds: number of microseconds to pause * @@ -35590,7 +36492,7 @@ * 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. + * ambiguous endianness. * * Further note that this function does not validate the result * string; it may e.g. include embedded NUL characters. The only @@ -37308,11 +38210,15 @@ * 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. + * The string will always be UTF-8 encoded, will never be %NULL, and will never + * contain nul bytes. * * 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. + * known. Untrusted values will be validated and, if valid, a strlen() will be + * performed. If invalid, a default value will be returned — for + * %G_VARIANT_TYPE_OBJECT_PATH, this is `"/"`, and for other types it is the + * empty string. * * It is an error to call this function with a @value of any type * other than those three. @@ -37594,7 +38500,7 @@ * 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. + * and will be related only when g_variant_iter_free() is called. * * Returns: (transfer full): a new heap-allocated #GVariantIter * Since: 2.24 @@ -38740,7 +39646,7 @@ * * 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 + * will always 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. * @@ -39604,7 +40510,7 @@ * installations of different versions of some GLib-using library, or * GLib itself, is desirable for various reasons. * - * For this reason it is recommeded to always pass %NULL as + * For this reason it is recommended to always pass %NULL as * @package to this function, to avoid the temptation to use the * Registry. In version 2.20 of GLib the @package parameter * will be ignored and this function won't look in the Registry at all. @@ -39994,7 +40900,7 @@ * This is an internal function and should only be used by * the internals of glib (such as libgio). * - * Returns: the transation of @str to the current locale + * Returns: the translation of @str to the current locale */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index f773584b..ef504701 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -2086,7 +2086,7 @@ * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); * ]| * - * Generally, this function is used together with g_closure_ref(). Ane example + * Generally, this function is used together with g_closure_ref(). An example * of storing a closure for later notification looks like: * |[<!-- language="C" --> * static GClosure *notify_closure = NULL; @@ -3317,7 +3317,7 @@ * @data: (nullable): An opaque user data pointer * * This sets an opaque, named pointer on an object. - * The name is specified through a #GQuark (retrived e.g. via + * 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 g_object_get_qdata() * until the @object is finalized. @@ -3401,7 +3401,7 @@ * { * // the quark, naming the object data * GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); - * // retrive the old string list + * // retrieve the old string list * GList *list = g_object_steal_qdata (object, quark_string_list); * * // prepend new string @@ -4225,7 +4225,7 @@ /** * g_param_value_convert: * @pspec: a valid #GParamSpec - * @src_value: souce #GValue + * @src_value: source #GValue * @dest_value: destination #GValue of correct type for @pspec * @strict_validation: %TRUE requires @dest_value to conform to @pspec * without modifications @@ -4548,7 +4548,7 @@ * * 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 + * signal handler means to temporarily deactivate it, a signal handler * has to be unblocked exactly the same amount of times it has been * blocked before to become active again. * @@ -4871,7 +4871,7 @@ * of 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 + * directly and can be overridden 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 @@ -5416,7 +5416,7 @@ * 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 + * implementers 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. @@ -5455,7 +5455,7 @@ * 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 + * for the type will be created and initialized 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 @@ -6727,6 +6727,19 @@ /** + * g_value_set_interned_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: (nullable): static string to be set + * + * Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is + * assumed to be static and interned (canonical, for example from + * g_intern_string()), and is thus not duplicated when setting the #GValue. + * + * Since: 2.66 + */ + + +/** * g_value_set_long: * @value: a valid #GValue of type %G_TYPE_LONG * @v_long: long integer value to be set @@ -6824,6 +6837,9 @@ * 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. + * + * If the the string is a canonical string, using g_value_set_interned_string() + * is more appropriate. */ diff --git a/gir/meson.build b/gir/meson.build index 04f9371a..557e5517 100644 --- a/gir/meson.build +++ b/gir/meson.build @@ -41,24 +41,14 @@ gir_files = [ typelibdir = join_paths(get_option('libdir'), 'girepository-1.0') install_data(gir_files, install_dir: girdir) -if get_option('gi_cross_use_host_gi') - scanner_command = [ - 'g-ir-scanner', - ] -else - scanner_command = [ - python, - girscanner, - ] -endif - -scanner_command += [ - '--output=@OUTPUT@', - '--no-libtool', - '--quiet', - '--reparse-validate', - '--add-include-path', join_paths(meson.current_build_dir()), - '--add-include-path', join_paths(meson.current_source_dir()), +scanner_command = [ + find_program('g-ir-scanner', native: true), + '--output=@OUTPUT@', + '--no-libtool', + '--quiet', + '--reparse-validate', + '--add-include-path', join_paths(meson.current_build_dir()), + '--add-include-path', join_paths(meson.current_source_dir()), ] dep_type = glib_dep.type_name() @@ -458,7 +448,7 @@ foreach gir : gir_files typelibs += custom_target('generate-typelib-@0@'.format(gir).underscorify(), input: gir, output: '@BASENAME@.typelib', - depends: [gobject_gir, ], + depends: [gobject_gir, gircompiler, ], command: gircompiler_command, install: true, install_dir: typelibdir, diff --git a/giscanner/dumper.py b/giscanner/dumper.py index 0c10a780..e4b6ea03 100644 --- a/giscanner/dumper.py +++ b/giscanner/dumper.py @@ -126,7 +126,7 @@ class DumpCompiler(object): if len(self._get_type_functions) > 0: for func in self._get_type_functions: f.write("extern GType " + func + "(void);\n") - f.write("GType (*GI_GET_TYPE_FUNCS_[])(void) = {\n") + f.write("G_MODULE_EXPORT GType (*GI_GET_TYPE_FUNCS_[])(void) = {\n") first = True for func in self._get_type_functions: if first: @@ -138,7 +138,7 @@ class DumpCompiler(object): if len(self._error_quark_functions) > 0: for func in self._error_quark_functions: f.write("extern GQuark " + func + "(void);\n") - f.write("GQuark (*GI_ERROR_QUARK_FUNCS_[])(void) = {\n") + f.write("G_MODULE_EXPORT GQuark (*GI_ERROR_QUARK_FUNCS_[])(void) = {\n") first = True for func in self._error_quark_functions: if first: diff --git a/gobject-introspection-1.0.pc.in b/gobject-introspection-1.0.pc.in deleted file mode 100644 index 1036f90c..00000000 --- a/gobject-introspection-1.0.pc.in +++ /dev/null @@ -1,24 +0,0 @@ -prefix=@prefix@ -exec_prefix=@exec_prefix@ -libdir=@libdir@ -bindir=@bindir@ -datarootdir=@datarootdir@ -datadir=@datadir@ -includedir=@includedir@ - -g_ir_scanner=${bindir}/g-ir-scanner -g_ir_compiler=${bindir}/g-ir-compiler@EXEEXT@ -g_ir_generate=${bindir}/g-ir-generate@EXEEXT@ -gidatadir=${datadir}/gobject-introspection-1.0 -girdir=@GIR_PC_DIR@ -typelibdir=${libdir}/girepository-1.0 - -Cflags: -I${includedir}/gobject-introspection-1.0 @FFI_PC_CFLAGS@ -Requires: glib-2.0 gobject-2.0 -Requires.private: gmodule-2.0 @FFI_PC_PACKAGES@ -Libs: -L${libdir} -lgirepository-1.0 -Libs.private: @FFI_PC_LIBS@ - -Name: gobject-introspection -Description: GObject Introspection -Version: @VERSION@ diff --git a/gobject-introspection-no-export-1.0.pc.in b/gobject-introspection-no-export-1.0.pc.in deleted file mode 100644 index bde4faf6..00000000 --- a/gobject-introspection-no-export-1.0.pc.in +++ /dev/null @@ -1,23 +0,0 @@ -prefix=@prefix@ -exec_prefix=@exec_prefix@ -libdir=@libdir@ -bindir=@bindir@ -datarootdir=@datarootdir@ -datadir=@datadir@ -includedir=@includedir@ - -g_ir_scanner=${bindir}/g-ir-scanner -g_ir_compiler=${bindir}/g-ir-compiler@EXEEXT@ -g_ir_generate=${bindir}/g-ir-generate@EXEEXT@ -girdir=@GIR_PC_DIR@ -typelibdir=${libdir}/girepository-1.0 - -Cflags: -I${includedir}/gobject-introspection-1.0 @FFI_PC_CFLAGS@ -Requires: glib-2.0 gobject-2.0 -Requires.private: gmodule-no-export-2.0 @FFI_PC_PACKAGES@ -Libs: -L${libdir} -lgirepository-1.0 -Libs.private: @FFI_PC_LIBS@ - -Name: gobject-introspection -Description: GObject Introspection -Version: @VERSION@ diff --git a/gobject-introspection.doap b/gobject-introspection.doap index 0da06245..6e59acc5 100644 --- a/gobject-introspection.doap +++ b/gobject-introspection.doap @@ -13,7 +13,7 @@ <description xml:lang="en">GObject introspection provides tools and libraries to help manage its common metadata format for representing GObject-based C APIs, designed for bindings, documentation tools and API verification.</description> - <homepage rdf:resource="http://live.gnome.org/GObjectIntrospection" /> + <homepage rdf:resource="https://gi.readthedocs.io/" /> <license rdf:resource="http://usefulinc.com/doap/licenses/lgpl" /> <bug-database rdf:resource="https://gitlab.gnome.org/GNOME/gobject-introspection/issues/" /> <mailing-list rdf:resource="mailto:gtk-devel-list@gnome.org" /> diff --git a/meson.build b/meson.build index 506757d2..04426515 100644 --- a/meson.build +++ b/meson.build @@ -231,46 +231,49 @@ endif install_data('Makefile.introspection', install_dir: join_paths(get_option('datadir'), 'gobject-introspection-1.0')) install_data('m4/introspection.m4', install_dir: join_paths(get_option('datadir'), 'aclocal')) -prefix = join_paths(get_option('prefix')) -pkgconfig_conf = configuration_data() -pkgconfig_conf.set('prefix', prefix) -pkgconfig_conf.set('exec_prefix', '${prefix}') -pkgconfig_conf.set('bindir', join_paths('${exec_prefix}', get_option('bindir'))) -pkgconfig_conf.set('libdir', join_paths('${exec_prefix}', get_option('libdir'))) -pkgconfig_conf.set('datarootdir', join_paths('${prefix}', get_option('datadir'))) -pkgconfig_conf.set('datadir', '${datarootdir}') -pkgconfig_conf.set('includedir', join_paths('${prefix}', get_option('includedir'))) -pkgconfig_conf.set('GIR_PC_DIR', join_paths(gir_dir_pc_prefix, 'gir-1.0')) +pkg = import('pkgconfig') + +# We must put in the '.exe' extension for .exe executables +exe_ext = '' + if host_system == 'windows' or host_system == 'cygwin' - pkgconfig_conf.set('EXEEXT', '.exe') -else - pkgconfig_conf.set('EXEEXT', '') -endif -pkgconfig_conf.set('VERSION', meson.project_version()) -pkgconfig_conf.set('FFI_PC_PACKAGES', 'libffi') -if libffi_dep.type_name() == 'pkgconfig' - prog_pkgconfig = find_program('pkg-config') - pkgconfig_conf.set('FFI_PC_CFLAGS', run_command(prog_pkgconfig, ['libffi', '--cflags-only-I']).stdout()) - pkgconfig_conf.set('FFI_PC_LIBS', run_command(prog_pkgconfig, ['libffi', '--libs-only-l']).stdout()) -else - # XXX: We can't know the correct values for these, needs meson API. Maybe we - # should use meson's pkgconfig module to generate the whole file. - pkgconfig_conf.set('FFI_PC_CFLAGS', '') - pkgconfig_conf.set('FFI_PC_LIBS', '-lffi') + exe_ext = '.exe' endif -configure_file( - input: 'gobject-introspection-no-export-1.0.pc.in', - output: 'gobject-introspection-no-export-1.0.pc', - configuration: pkgconfig_conf, - install_dir: join_paths(get_option('libdir'), 'pkgconfig'), +pkgconfig_variables = [ + 'datadir=' + '${prefix}' / get_option('datadir'), + 'bindir=' + '${prefix}' / get_option('bindir'), + 'g_ir_scanner=${bindir}/g-ir-scanner', + 'g_ir_compiler=${bindir}/g-ir-compiler@0@'.format(exe_ext), + 'g_ir_generate=${bindir}/g-ir-generate@0@'.format(exe_ext), + 'gidatadir=${datadir}/gobject-introspection-1.0', + 'girdir=' + gir_dir_pc_prefix / 'gir-1.0', + 'typelibdir=${libdir}/girepository-1.0', +] + +pkg.generate(girepo_lib, + name : 'gobject-introspection', + filebase : 'gobject-introspection-1.0', + description : 'GObject Introspection', + subdirs: ['gobject-introspection-1.0'], + variables : pkgconfig_variables, + libraries : [glib_dep, gobject_dep], ) -configure_file( - input: 'gobject-introspection-1.0.pc.in', - output: 'gobject-introspection-1.0.pc', - configuration: pkgconfig_conf, - install_dir: join_paths(get_option('libdir'), 'pkgconfig'), +# This is legacy for backward compat. It is identical to the pc file generated +# above because we actually never had a pc file that has `-Wl,--export-dynamic`. +# The reason is `gmodule-2.0` was in `Requires.private` so its libs flags are +# only included when doing `pkg-config gobject-introspection-1.0 --libs --static` +# which makes no sense since we don't even build static girepository library. +# Users who need `-Wl,--export-dynamic` can add `gmodule-2.0` explicitly in their +# dependencies in addition to `gobject-introspection-1.0`. +pkg.generate( + name : 'gobject-introspection', + filebase : 'gobject-introspection-no-export-1.0', + description : 'GObject Introspection', + subdirs: ['gobject-introspection-1.0'], + variables : pkgconfig_variables, + libraries : [girepo_lib, glib_dep, gobject_dep], ) # Dependency object used by Meson's GNOME module. This dependency variable must diff --git a/meson_options.txt b/meson_options.txt index 20ccc3b9..dff9be8e 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -26,8 +26,8 @@ option('gir_dir_prefix', type: 'string', description: 'Intermediate prefix for gir installation under ${prefix}' ) -option('gi_cross_use_host_gi', type: 'boolean', value : false, - description: 'Use gobject introspection tools installed in the host system (useful when cross-compiling)' +option('gi_cross_use_prebuilt_gi', type: 'boolean', value : false, + description: 'Use gobject introspection tools installed in the build system (useful when cross-compiling)' ) option('gi_cross_binary_wrapper', type: 'string', diff --git a/tools/g-ir-tool-template.in b/tools/g-ir-tool-template.in index c4a10a28..75bf759c 100755 --- a/tools/g-ir-tool-template.in +++ b/tools/g-ir-tool-template.in @@ -53,14 +53,9 @@ if not os.path.isdir(os.path.join(datadir, 'gir-1.0')): builtins.__dict__['DATADIR'] = datadir -# Respect gir_dir_prefix for meson and autotools +# Respect gir_dir_prefix girdir = '' -# for meson -if '@gir_dir_prefix@' and not '@gir_dir_prefix@'.startswith('@'): - girdir = os.path.abspath(os.path.join(filedir, '..', '@gir_dir_prefix@')) -# for autotools -elif '@GIR_DIR@' and not '@GIR_DIR@'.startswith('@'): - girdir = os.path.dirname(os.path.abspath('@GIR_DIR@')) +girdir = os.path.abspath(os.path.join(filedir, '..', '@gir_dir_prefix@')) builtins.__dict__['GIRDIR'] = [girdir] # Again, relative paths first so that the installation prefix is relocatable diff --git a/tools/meson.build b/tools/meson.build index 103480c4..f272c955 100644 --- a/tools/meson.build +++ b/tools/meson.build @@ -22,7 +22,6 @@ foreach tool : tools tools_conf.set('datarootdir', datadir_abs) tools_conf.set('gir_dir_prefix', gir_dir_prefix) tools_conf.set('PYTHON_CMD', python_cmd) - tools_conf.set('GIR_DIR', girdir) tools_conf.set('TOOL_MODULE', tool[1]) tools_conf.set('TOOL_FUNCTION', tool[2]) @@ -34,7 +33,9 @@ foreach tool : tools ) tool_output += tool_bin # Provide tools for others when we're a subproject and they use the Meson GNOME module - meson.override_find_program(tool[0], tool_bin) + if not get_option('gi_cross_use_prebuilt_gi') + meson.override_find_program(tool[0], tool_bin) + endif endforeach girscanner = tool_output[0] @@ -58,7 +59,6 @@ gircompiler = executable('g-ir-compiler', 'compiler.c', install: true, c_args: custom_c_args, ) -meson.override_find_program('g-ir-compiler', gircompiler) girgenerate = executable('g-ir-generate', 'generate.c', dependencies: [ @@ -68,11 +68,15 @@ girgenerate = executable('g-ir-generate', 'generate.c', install: true, c_args: custom_c_args, ) -meson.override_find_program('g-ir-generate', girgenerate) girinspect = executable('g-ir-inspect', 'g-ir-inspect.c', dependencies: girepo_dep, install: true, c_args: custom_c_args, ) -meson.override_find_program('g-ir-inspect', girinspect)
\ No newline at end of file + +if not get_option('gi_cross_use_prebuilt_gi') + meson.override_find_program('g-ir-compiler', gircompiler) + meson.override_find_program('g-ir-generate', girgenerate) + meson.override_find_program('g-ir-inspect', girinspect) +endif |