diff options
author | Rico Tzschichholz <ricotz@ubuntu.com> | 2020-08-23 08:54:59 +0200 |
---|---|---|
committer | Rico Tzschichholz <ricotz@ubuntu.com> | 2020-08-23 08:54:59 +0200 |
commit | bf349e6f79ed24bedcf64cf262bbc87ff855064b (patch) | |
tree | 3ab9adfab1e48b73bacba350667be0304ed79251 /gir | |
parent | 9e329e9b7bc2f29d4265af87abfc41db1348f24c (diff) | |
download | gobject-introspection-bf349e6f79ed24bedcf64cf262bbc87ff855064b.tar.gz |
gir: Update annotations from glib git master
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 56 | ||||
-rw-r--r-- | gir/glib-2.0.c | 481 |
2 files changed, 381 insertions, 156 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 3f8aa5d7..db7e25b5 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -7593,6 +7593,13 @@ * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will * abort. * + * `json-stripblanks` which will use the `json-glib-format` command to strip + * ignorable whitespace from the JSON file. For this to work, the + * `JSON_GLIB_FORMAT` environment variable must be set to the full path to the + * `json-glib-format` executable, or it must be in the `PATH`; + * otherwise the preprocessing step is skipped. In addition, at least version + * 1.6 of `json-glib-format` is required. + * * Resource files will be exported in the GResource namespace using the * combination of the given `prefix` and the filename from the `file` element. * The `alias` attribute can be used to alter the filename to expose them at a @@ -21487,6 +21494,21 @@ * Deletes a file. If the @file is a directory, it will only be * deleted if it is empty. This has the same semantics as g_unlink(). * + * If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows + * for deletion to be implemented avoiding + * [time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use): + * |[ + * g_autoptr(GError) local_error = NULL; + * if (!g_file_delete (my_file, my_cancellable, &local_error) && + * !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND)) + * { + * // deletion failed for some reason other than the file not existing: + * // so report the error + * g_warning ("Failed to delete %s: %s", + * g_file_peek_path (my_file), local_error->message); + * } + * ]| + * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. @@ -25188,7 +25210,9 @@ * Sends @file to the "Trashcan", if possible. This is similar to * deleting it, but the user can recover it before emptying the trashcan. * Not all file systems support trashing, so this call can return the - * %G_IO_ERROR_NOT_SUPPORTED error. + * %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix + * mount option can be used to disable g_file_trash() support for certain + * mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation @@ -36317,8 +36341,8 @@ /** * g_socket_receive: * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): a buffer to - * read data into (which should be at least @size bytes long). + * @buffer: (array length=size) (element-type guint8) (out caller-allocates): + * a buffer to read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @cancellable: (nullable): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -36358,8 +36382,8 @@ * @socket: a #GSocket * @address: (out) (optional): a pointer to a #GSocketAddress * pointer, or %NULL - * @buffer: (array length=size) (element-type guint8): a buffer to - * read data into (which should be at least @size bytes long). + * @buffer: (array length=size) (element-type guint8) (out caller-allocates): + * a buffer to read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @cancellable: (nullable): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -36533,8 +36557,8 @@ /** * g_socket_receive_with_blocking: * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): a buffer to - * read data into (which should be at least @size bytes long). + * @buffer: (array length=size) (element-type guint8) (out caller-allocates): + * a buffer to read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @blocking: whether to do blocking or non-blocking I/O * @cancellable: (nullable): a %GCancellable or %NULL @@ -41244,6 +41268,24 @@ /** + * g_unix_mount_point_at: + * @mount_path: (type filename): path for a possible unix mount point. + * @time_read: (out) (optional): guint64 to contain a timestamp. + * + * Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it + * will be filled with a unix timestamp for checking if the mount points have + * changed since with g_unix_mount_points_changed_since(). + * + * If more mount points have the same mount path, the last matching mount point + * is returned. + * + * Returns: (transfer full) (nullable): a #GUnixMountPoint, or %NULL if no match + * is found. + * Since: 2.66 + */ + + +/** * g_unix_mount_point_compare: * @mount1: a #GUnixMount. * @mount2: a #GUnixMount. diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 3901e323..89d55033 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -2547,13 +2547,14 @@ * 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, + * g_uri_get_path() will always return a non-%NULL string (which may be empty). + * + * If the URI string has an + * [‘authority’ component](https://tools.ietf.org/html/rfc3986#section-3) (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 (for example, + * using the %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS flags), * the userinfo may be split out into a username, password, and * additional authorization-related parameters. * @@ -2568,14 +2569,14 @@ * 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_autoptr(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_autoptr(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"); * ]| * @@ -2583,13 +2584,13 @@ * 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); + * g_autoptr(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 or %G_URI_FLAGS_ENCODED_QUERY if you * need to handle that case manually. In particular, if the query string - * contains '=' characters that are '%'-encoded, you should let + * contains `=` characters that are `%`-encoded, you should let * g_uri_parse_params() do the decoding once of the query. * * #GUri is immutable once constructed, and can safely be accessed from @@ -2600,6 +2601,23 @@ /** + * GUriParamsIter: + * + * Many URI schemes include one or more attribute/value pairs as part of the URI + * value. For example `scheme://server/path?query=string&is=there` has two + * attributes – `query=string` and `is=there` – in its query part. + * + * A #GUriParamsIter structure represents an iterator that can be used to + * iterate over the attribute/value pairs of a URI query string. #GUriParamsIter + * structures are typically allocated on the stack and then initialized with + * g_uri_params_iter_init(). See the documentation for g_uri_params_iter_init() + * for a usage example. + * + * Since: 2.66 + */ + + +/** * GVariant: * * #GVariant is an opaque data structure and can only be accessed @@ -6076,12 +6094,50 @@ * The #GUri type and related functions can be used to parse URIs into * their components, and build valid URIs from individual components. * + * Note that #GUri scope is to help manipulate URIs in various applications, + * following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular, + * it doesn't intend to cover web browser needs, and doesn't implement the + * [WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to + * help prevent + * [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so + * #GUri is not suitable for formatting URIs for display to the user for making + * security-sensitive decisions. + * + * ## Relative and absolute URIs # {#relative-absolute-uris} + * + * As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the + * hierarchical nature of URIs means that they can either be ‘relative + * references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for + * clarity, ‘URIs’ are referred to in this documentation as + * ‘absolute URIs’ — although + * [in constrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3), + * fragment identifiers are always allowed). + * + * Relative references have one or more components of the URI missing. In + * particular, they have no scheme. Any other component, such as hostname, + * query, etc. may be missing, apart from a path, which has to be specified (but + * may be empty). The path may be relative, starting with `./` rather than `/`. + * + * For example, a valid relative reference is `./path?query`, + * `/?query#fragment` or `//example.com`. + * + * Absolute URIs have a scheme specified. Any other components of the URI which + * are missing are specified as explicitly unset in the URI, rather than being + * resolved relative to a base URI using g_uri_parse_relative(). + * + * For example, a valid absolute URI is `file:///home/bob` or + * `https://search.com?query=string`. + * + * A #GUri instance is always an absolute URI. A string may be an absolute URI + * or a relative reference; see the documentation for individual functions as to + * what forms they accept. + * * ## 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 + * 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() @@ -6106,20 +6162,23 @@ * 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. * + * For example, you might want to use %G_URI_PARAMS_WWW_FORM when parsing the + * params for a web URI, so compare the result of g_uri_peek_scheme() against + * `http` and `https`. + * * ## 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 + * 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. + * #GUriFlags argument. In particular, it is important to keep in mind + * whether the URI components you are using are already `%`-encoded. If so, + * you must pass the %G_URI_FLAGS_ENCODED flag. * * ## `file://` URIs * @@ -6134,10 +6193,10 @@ * * 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 + * 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 @@ -15136,7 +15195,7 @@ * strftime() format language as specified by C99. The \%D, \%U and \%W * conversions are not supported, nor is the 'E' modifier. The GNU * extensions \%k, \%l, \%s and \%P are supported, however, as are the - * '0', '_' and '-' modifiers. + * '0', '_' and '-' modifiers. The Python extension \%f is also supported. * * In contrast to strftime(), this function always produces a UTF-8 * string, regardless of the current locale. Note that the rendering of @@ -15168,6 +15227,7 @@ * single digits are preceded by a blank * - \%m: the month as a decimal number (range 01 to 12) * - \%M: the minute as a decimal number (range 00 to 59) + * - \%f: the microsecond as a decimal number (range 000000 to 999999) * - \%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". Use of this format specifier is discouraged, as @@ -15245,6 +15305,8 @@ * including the date, time and time zone, and return that as a UTF-8 encoded * string. * + * Since GLib 2.66, this will output to sub-second precision if needed. + * * 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(). @@ -18687,6 +18749,8 @@ * Tests if @hostname is the string form of an IPv4 or IPv6 address. * (Eg, "192.168.0.1".) * + * Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874). + * * Returns: %TRUE if @hostname is an IP address * Since: 2.22 */ @@ -35827,11 +35891,11 @@ /** * g_uri_build: * @flags: flags describing how to build the #GUri - * @scheme: the URI scheme + * @scheme: (not nullable): 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 + * @port: the port, or `-1` + * @path: (not nullable): the path component * @query: (nullable): the query component, or %NULL * @fragment: (nullable): the fragment, or %NULL * @@ -35848,20 +35912,23 @@ /** * g_uri_build_with_user: * @flags: flags describing how to build the #GUri - * @scheme: the URI scheme + * @scheme: (not nullable): 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 + * @port: the port, or `-1` + * @path: (not nullable): 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. + * Creates a new #GUri from the given components according to @flags + * (%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be + * coherent with the passed values, in particular use `%`-encoded values with + * %G_URI_FLAGS_ENCODED. * - * In constrast to g_uri_build(), this allows specifying the components - * of the "userinfo" field separately. Note that @user must be non-%NULL + * In contrast 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 @@ -35878,18 +35945,18 @@ * * Escapes arbitrary data for use in a URI. * - * Normally all characters that are not "unreserved" (i.e. ASCII + * 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 + * 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`". + * Though technically incorrect, this will also allow escaping nul + * bytes as `%``00`. * - * Returns: an escaped version of @unescaped. The returned string - * should be freed when no longer needed. + * Returns: (transfer full): an escaped version of @unescaped. The returned + * string should be freed when no longer needed. * Since: 2.66 */ @@ -35928,7 +35995,7 @@ * Depending on the URI scheme, g_uri_parse_params() may be useful for * further parsing this information. * - * Returns: @uri's authentication parameters. + * Returns: (nullable): @uri's authentication parameters. * Since: 2.66 */ @@ -35951,7 +36018,7 @@ * Gets @uri's fragment, which may contain `%`-encoding, depending on * the flags with which @uri was created. * - * Returns: @uri's fragment. + * Returns: (nullable): @uri's fragment. * Since: 2.66 */ @@ -35967,10 +36034,10 @@ * 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). + * 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. + * Returns: (not nullable): @uri's host. * Since: 2.66 */ @@ -35983,7 +36050,7 @@ * 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. + * Returns: (nullable): @uri's password. * Since: 2.66 */ @@ -35995,7 +36062,7 @@ * Gets @uri's path, which may contain `%`-encoding, depending on the * flags with which @uri was created. * - * Returns: @uri's path. + * Returns: (not nullable): @uri's path. * Since: 2.66 */ @@ -36006,7 +36073,7 @@ * * Gets @uri's port. * - * Returns: @uri's port, or -1 if no port was specified. + * Returns: @uri's port, or `-1` if no port was specified. * Since: 2.66 */ @@ -36018,10 +36085,10 @@ * 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. + * For queries consisting of a series of `name=value` parameters, + * #GUriParamsIter or g_uri_parse_params() may be useful. * - * Returns: @uri's query. + * Returns: (nullable): @uri's query. * Since: 2.66 */ @@ -36033,7 +36100,7 @@ * 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. + * Returns: (not nullable): @uri's scheme. * Since: 2.66 */ @@ -36042,12 +36109,12 @@ * g_uri_get_user: * @uri: a #GUri * - * Gets the "username" component of @uri's userinfo, which may contain + * 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. + * Returns: (nullable): @uri's user. * Since: 2.66 */ @@ -36059,24 +36126,27 @@ * Gets @uri's userinfo, which may contain `%`-encoding, depending on * the flags with which @uri was created. * - * Returns: @uri's userinfo. + * Returns: (nullable): @uri's userinfo. * Since: 2.66 */ /** * g_uri_is_valid: - * @uri_string: a string containing a relative or absolute URI + * @uri_string: a string containing an 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. + * Parses @uri_string according to @flags, to determine whether it is a valid + * [absolute URI][relative-absolute-uris], i.e. it does not need to be resolved + * relative to another URI using g_uri_parse_relative(). + * + * If it’s not a valid URI, an error is returned explaining how it’s invalid. * * 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. + * Returns: %TRUE if @uri_string is a valid absolute URI, %FALSE on error. * Since: 2.66 */ @@ -36084,22 +36154,30 @@ /** * g_uri_join: * @flags: flags describing how to build the URI string - * @scheme: the URI scheme + * @scheme: (nullable): the URI scheme, or %NULL * @userinfo: (nullable): the userinfo component, or %NULL * @host: (nullable): the host component, or %NULL - * @port: the port, or -1 - * @path: the path component + * @port: the port, or `-1` + * @path: (not nullable): 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 ""). + * an absolute URI string. @path may not be %NULL (though it may be the empty + * string). + * + * When @host is present, @path must either be empty or begin with a slash (`/`) + * character. When @host is not present, @path cannot begin with two slash + * characters (`//`). See + * [RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3). * * See also g_uri_join_with_user(), which allows specifying the - * components of the "userinfo" separately. + * components of the ‘userinfo’ separately. + * + * %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set + * in @flags. * - * Returns: a URI string + * Returns: (transfer full): an absolute URI string * Since: 2.66 */ @@ -36107,26 +36185,29 @@ /** * g_uri_join_with_user: * @flags: flags describing how to build the URI string - * @scheme: the URI scheme + * @scheme: (nullable): the URI scheme, or %NULL * @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 + * @port: the port, or `-1` + * @path: (not nullable): 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 ""). + * an absolute URI string. @path may not be %NULL (though it may be the empty + * string). * - * In constrast to g_uri_join(), this allows specifying the components - * of the "userinfo" separately. + * In contrast to g_uri_join(), this allows specifying the components + * of the ‘userinfo’ separately. It otherwise behaves the same. * - * Returns: a URI string + * %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set + * in @flags. + * + * Returns: (transfer full): an absolute URI string * Since: 2.66 */ @@ -36147,13 +36228,90 @@ /** + * g_uri_params_iter_init: + * @iter: an uninitialized #GUriParamsIter + * @params: a `%`-encoded string containing `attribute=value` + * parameters + * @length: the length of @params, or `-1` if it is nul-terminated + * @separators: the separator byte character set between parameters. (usually + * `&`, but sometimes `;` or both `&;`). Note that this function works on + * bytes not characters, so it can't be used to delimit UTF-8 strings for + * anything but ASCII characters. You may pass an empty set, in which case + * no splitting will occur. + * @flags: flags to modify the way the parameters are handled. + * + * Initializes an attribute/value pair iterator. + * + * The iterator keeps pointers to the @params and @separators arguments, those + * variables must thus outlive the iterator and not be modified during the + * iteration. + * + * If %G_URI_PARAMS_WWW_FORM is passed in @flags, `+` characters in the param + * string will be replaced with spaces in the output. For example, `foo=bar+baz` + * will give attribute `foo` with value `bar baz`. This is commonly used on the + * web (the `https` and `http` schemes only), but is deprecated in favour of + * the equivalent of encoding spaces as `%20`. + * + * Unlike with g_uri_parse_params(), %G_URI_PARAMS_CASE_INSENSITIVE has no + * effect if passed to @flags for g_uri_params_iter_init(). The caller is + * responsible for doing their own case-insensitive comparisons. + * + * |[<!-- language="C" --> + * GUriParamsIter iter; + * GError *error = NULL; + * gchar *unowned_attr, *unowned_value; + * + * g_uri_params_iter_init (&iter, "foo=bar&baz=bar&Foo=frob&baz=bar2", -1, "&", G_URI_PARAMS_NONE); + * while (g_uri_params_iter_next (&iter, &unowned_attr, &unowned_value, &error)) + * { + * g_autofree gchar *attr = g_steal_pointer (&unowned_attr); + * g_autofree gchar *value = g_steal_pointer (&unowned_value); + * // do something with attr and value; this code will be called 4 times + * // for the params string in this example: once with attr=foo and value=bar, + * // then with baz/bar, then Foo/frob, then baz/bar2. + * } + * if (error) + * // handle parsing error + * ]| + * + * Since: 2.66 + */ + + +/** + * g_uri_params_iter_next: + * @iter: an initialized #GUriParamsIter + * @attribute: (out) (nullable) (optional) (transfer full): on return, contains + * the attribute, or %NULL. + * @value: (out) (nullable) (optional) (transfer full): on return, contains + * the value, or %NULL. + * @error: #GError for error reporting, or %NULL to ignore. + * + * Advances @iter and retrieves the next attribute/value. %FALSE is returned if + * an error has occurred (in which case @error is set), or if the end of the + * iteration is reached (in which case @attribute and @value are set to %NULL + * and the iterator becomes invalid). If %TRUE is returned, + * g_uri_params_iter_next() may be called again to receive another + * attribute/value pair. + * + * Note that the same @attribute may be returned multiple times, since URIs + * allow repeated attributes. + * + * Returns: %FALSE if the end of the parameters has been reached or an error was + * encountered. %TRUE otherwise. + * Since: 2.66 + */ + + +/** * 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. + * valid [absolute URI][relative-absolute-uris], it will be discarded, and an + * error returned. * * Returns: (transfer full): a new #GUri. * Since: 2.66 @@ -36162,11 +36320,11 @@ /** * g_uri_parse_params: - * @params: a `%`-encoded string containing "attribute=value" + * @params: a `%`-encoded string containing `attribute=value` * parameters - * @length: the length of @params, or -1 if it is NUL-terminated + * @length: the length of @params, or `-1` if it is nul-terminated * @separators: the separator byte character set between parameters. (usually - * "&", but sometimes ";" or both "&;"). Note that this function works on + * `&`, but sometimes `;` or both `&;`). Note that this function works on * bytes not characters, so it can't be used to delimit UTF-8 strings for * anything but ASCII characters. You may pass an empty set, in which case * no splitting will occur. @@ -36174,35 +36332,48 @@ * @error: #GError for error reporting, or %NULL to ignore. * * 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. + * value. This method can be used to parse them into a hash table. When an + * attribute has multiple occurrences, the last value is the final returned + * value. If you need to handle repeated attributes differently, use + * #GUriParamsIter. * * 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 @separators, if the value was encoded in the input.) - * Invalid `%`-encoding is treated as with the non-%G_URI_FLAGS_PARSE_STRICT + * may contain `=` or @separators, if the value was encoded in the input.) + * Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED * 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 + * from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED 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 @separators characters in a - * row), then %NULL is returned. + * %G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init(). + * + * If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be + * compared case-insensitively, so a params string `attr=123&Attr=456` will only + * return a single attribute–value pair, `Attr=456`. Case will be preserved in + * the returned attributes. + * + * If @params cannot be parsed (for example, it contains two @separators + * characters in a row), then @error is set and %NULL is returned. + * + * Returns: (transfer full) (element-type utf8 utf8): A hash table of + * attribute/value pairs, with both names and values fully-decoded; or %NULL + * on error. * 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 + * @base_uri: (nullable) (transfer none): a base absolute URI + * @uri_ref: a string representing a relative or absolute URI + * @flags: flags describing how to parse @uri_ref * @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. + * Parses @uri_ref according to @flags and, if it is a + * [relative URI][relative-absolute-uris], 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 @@ -36213,14 +36384,16 @@ * g_uri_parse_scheme: * @uri: a valid URI. * - * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as: + * Gets the scheme portion of a URI string. + * [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme + * as: * |[ * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] * ]| - * Common schemes include "file", "http", "svn+ssh", etc. + * Common schemes include `file`, `https`, `svn+ssh`, etc. * - * Returns: The "scheme" component of the URI, or %NULL on error. - * The returned string should be freed when no longer needed. + * Returns: (transfer full) (nullable): The ‘scheme’ component of the URI, or + * %NULL on error. The returned string should be freed when no longer needed. * Since: 2.16 */ @@ -36229,15 +36402,20 @@ * g_uri_peek_scheme: * @uri: a valid URI. * - * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as: + * Gets the scheme portion of a URI string. + * [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme + * as: * |[ * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] * ]| - * Common schemes include "file", "http", "svn+ssh", etc. + * Common schemes include `file`, `https`, `svn+ssh`, etc. + * + * Unlike g_uri_parse_scheme(), the returned scheme is normalized to + * all-lowercase and does not need to be freed. * - * 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. + * Returns: (transfer none) (nullable): 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 */ @@ -36256,35 +36434,36 @@ /** * 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 + * @uri_ref: a string representing a relative or absolute URI + * @flags: flags describing how to parse @uri_ref * @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. + * Parses @uri_ref according to @flags and, if it is a + * [relative URI][relative-absolute-uris], 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.) + * (If @base_uri_string is %NULL, this just returns @uri_ref, or + * %NULL if @uri_ref is invalid or not absolute.) * - * Returns: the resolved URI string. + * Returns: (transfer full): 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 + * @uri_ref: a string containing a relative or absolute URI + * @flags: flags for parsing @uri_ref * @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 + * @port: (out) (optional) (transfer full): on return, contains the + * port, or `-1` + * @path: (out) (not nullable) (optional) (transfer full): on return, contains the * path * @query: (out) (nullable) (optional) (transfer full): on return, contains the * query, or %NULL @@ -36292,14 +36471,14 @@ * 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). + * Parses @uri_ref (which can be an + * [absolute or relative URI][relative-absolute-uris]) according to @flags, and + * returns the pieces. Any component that doesn't appear in @uri_ref 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, + * @uri_ref 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. @@ -36309,7 +36488,7 @@ * 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 + * Returns: (skip): %TRUE if @uri_ref parsed successfully, %FALSE * on error. * Since: 2.66 */ @@ -36317,18 +36496,18 @@ /** * g_uri_split_network: - * @uri_string: a string containing a relative or absolute URI + * @uri_string: a string containing an 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 + * @port: (out) (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. + * Parses @uri_string (which must be an [absolute URI][relative-absolute-uris]) + * 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, @@ -36342,8 +36521,8 @@ /** * g_uri_split_with_user: - * @uri_string: a string containing a relative or absolute URI - * @flags: flags for parsing @uri_string + * @uri_ref: a string containing a relative or absolute URI + * @flags: flags for parsing @uri_ref * @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 @@ -36354,9 +36533,9 @@ * 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 + * @port: (out) (optional) (transfer full): on return, contains the + * port, or `-1` + * @path: (out) (not nullable) (optional) (transfer full): on return, contains the * path * @query: (out) (nullable) (optional) (transfer full): on return, contains the * query, or %NULL @@ -36364,11 +36543,11 @@ * 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). + * Parses @uri_ref (which can be an + * [absolute or relative URI][relative-absolute-uris]) according to @flags, and + * returns the pieces. Any component that doesn't appear in @uri_ref 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 @@ -36376,7 +36555,7 @@ * @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 + * Returns: (skip): %TRUE if @uri_ref parsed successfully, %FALSE * on error. * Since: 2.66 */ @@ -36395,8 +36574,12 @@ * 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. + * If @uri might contain sensitive details, such as authentication parameters, + * or private data in its query string, and the returned string is going to be + * logged, then consider using g_uri_to_string_partial() to redact parts. + * + * Returns: (transfer full): a string representing @uri, which the caller + * must free. * Since: 2.66 */ @@ -36409,8 +36592,8 @@ * 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. + * Returns: (transfer full): a string representing @uri, which the caller + * must free. * Since: 2.66 */ @@ -36418,8 +36601,8 @@ /** * 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. + * @length: the length (in bytes) of @escaped_string to escape, or `-1` if it + * is nul-terminated. * @illegal_characters: (nullable): a string of illegal characters * not to be allowed, or %NULL. * @error: #GError for error reporting, or %NULL to ignore. @@ -36427,17 +36610,17 @@ * 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. + * nul bytes to appear in the output. * - * 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. + * If any of the characters in @illegal_characters 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: (transfer full): an unescaped version of @escaped_string or %NULL on - * error (if decoding failed, using %G_URI_ERROR_MISC error code). The returned - * #GBytes should be unreffed when no longer needed. + * error (if decoding failed, using %G_URI_ERROR_FAILED error code). The + * returned #GBytes should be unreffed when no longer needed. * Since: 2.66 */ |