summaryrefslogtreecommitdiff
path: root/gir/gio-2.0.c
diff options
context:
space:
mode:
Diffstat (limited to 'gir/gio-2.0.c')
-rw-r--r--gir/gio-2.0.c274
1 files changed, 210 insertions, 64 deletions
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
*/