diff options
author | Rico Tzschichholz <ricotz@ubuntu.com> | 2016-07-18 15:08:28 +0200 |
---|---|---|
committer | Rico Tzschichholz <ricotz@ubuntu.com> | 2016-07-18 15:08:28 +0200 |
commit | b260940f66877a511f728bc192ec644ce84bf4ad (patch) | |
tree | 440a4f68e6c06153d29438957b5ce9ce43294b28 /gir | |
parent | b86824f23ae111804f26ae296985120b306ba0cd (diff) | |
download | gobject-introspection-b260940f66877a511f728bc192ec644ce84bf4ad.tar.gz |
gir: Update annotations from GLib git master
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 877 | ||||
-rw-r--r-- | gir/glib-2.0.c | 339 |
2 files changed, 1213 insertions, 3 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 7a63564f..4ada3241 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -2734,6 +2734,9 @@ * This signal supports detailed connections. You can connect to the * detailed signal "changed::x" in order to only receive callbacks * when key "x" changes. + * + * Note that @settings only emits this signal if you have read @key at + * least once while a signal handler was already connected for @key. */ @@ -4170,6 +4173,196 @@ /** + * GXdpDocuments: + * + * Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link>. + */ + + +/** + * GXdpDocuments::handle-add: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @arg_o_path_fd: Argument passed by remote caller. + * @arg_reuse_existing: Argument passed by remote caller. + * @arg_persistent: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Add">Add()</link> D-Bus method. + * + * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_add() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * GXdpDocuments::handle-add-named: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @arg_o_path_parent_fd: Argument passed by remote caller. + * @arg_filename: Argument passed by remote caller. + * @arg_reuse_existing: Argument passed by remote caller. + * @arg_persistent: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.AddNamed">AddNamed()</link> D-Bus method. + * + * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_add_named() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * GXdpDocuments::handle-delete: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_doc_id: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Delete">Delete()</link> D-Bus method. + * + * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_delete() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * GXdpDocuments::handle-get-mount-point: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * + * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GetMountPoint">GetMountPoint()</link> D-Bus method. + * + * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_get_mount_point() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * GXdpDocuments::handle-grant-permissions: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_doc_id: Argument passed by remote caller. + * @arg_app_id: Argument passed by remote caller. + * @arg_permissions: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GrantPermissions">GrantPermissions()</link> D-Bus method. + * + * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_grant_permissions() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * GXdpDocuments::handle-info: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_doc_id: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Info">Info()</link> D-Bus method. + * + * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_info() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * GXdpDocuments::handle-list: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_app_id: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.List">List()</link> D-Bus method. + * + * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_list() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * GXdpDocuments::handle-lookup: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_filename: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Lookup">Lookup()</link> D-Bus method. + * + * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_lookup() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * GXdpDocuments::handle-revoke-permissions: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_doc_id: Argument passed by remote caller. + * @arg_app_id: Argument passed by remote caller. + * @arg_permissions: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.RevokePermissions">RevokePermissions()</link> D-Bus method. + * + * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_revoke_permissions() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * GXdpDocumentsIface: + * @parent_iface: The parent interface. + * @handle_add: Handler for the #GXdpDocuments::handle-add signal. + * @handle_add_named: Handler for the #GXdpDocuments::handle-add-named signal. + * @handle_delete: Handler for the #GXdpDocuments::handle-delete signal. + * @handle_get_mount_point: Handler for the #GXdpDocuments::handle-get-mount-point signal. + * @handle_grant_permissions: Handler for the #GXdpDocuments::handle-grant-permissions signal. + * @handle_info: Handler for the #GXdpDocuments::handle-info signal. + * @handle_list: Handler for the #GXdpDocuments::handle-list signal. + * @handle_lookup: Handler for the #GXdpDocuments::handle-lookup signal. + * @handle_revoke_permissions: Handler for the #GXdpDocuments::handle-revoke-permissions signal. + * + * Virtual table for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link>. + */ + + +/** + * GXdpDocumentsProxy: + * + * The #GXdpDocumentsProxy structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * GXdpDocumentsProxyClass: + * @parent_class: The parent class. + * + * Class structure for #GXdpDocumentsProxy. + */ + + +/** + * GXdpDocumentsSkeleton: + * + * The #GXdpDocumentsSkeleton structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * GXdpDocumentsSkeletonClass: + * @parent_class: The parent class. + * + * Class structure for #GXdpDocumentsSkeleton. + */ + + +/** * GXdpNetworkMonitor: * * Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-NetworkMonitor.top_of_page">org.freedesktop.portal.NetworkMonitor</link>. @@ -4388,6 +4581,15 @@ /** + * SECTION:GXdpDocuments + * @title: GXdpDocuments + * @short_description: Generated C code for the org.freedesktop.portal.Documents D-Bus interface + * + * This section contains code for working with the <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link> D-Bus interface in C. + */ + + +/** * SECTION:GXdpNetworkMonitor * @title: GXdpNetworkMonitor * @short_description: Generated C code for the org.freedesktop.portal.NetworkMonitor D-Bus interface @@ -36762,6 +36964,10 @@ * New listeners can be added with e.g. g_socket_listener_add_address() * or g_socket_listener_add_inet_port(). * + * New services are created active, there is no need to call + * g_socket_service_start(), unless g_socket_service_stop() has been + * called before. + * * Returns: a new #GSocketService. * Since: 2.22 */ @@ -36771,8 +36977,10 @@ * g_socket_service_start: * @service: a #GSocketService * - * Starts the service, i.e. start accepting connections - * from the added sockets when the mainloop runs. + * Restarts the service, i.e. start accepting connections + * from the added sockets when the mainloop runs. This only needs + * to be called after the service has been stopped from + * g_socket_service_stop(). * * This call is thread-safe, so it may be called from a thread * handling an incoming client request. @@ -36797,6 +37005,10 @@ * close the listening sockets, call g_socket_listener_close(). (This * will happen automatically when the #GSocketService is finalized.) * + * This must be called before calling g_socket_listener_close() as + * the socket service will start accepting connections immediately + * when a new socket is added. + * * Since: 2.22 */ @@ -42507,6 +42719,667 @@ /** + * gxdp_documents_call_add: + * @proxy: A #GXdpDocumentsProxy. + * @arg_o_path_fd: Argument to pass with the method invocation. + * @arg_reuse_existing: Argument to pass with the method invocation. + * @arg_persistent: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. + * + * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Add">Add()</link> D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. + * You can then call gxdp_documents_call_add_finish() to get the result of the operation. + * + * See gxdp_documents_call_add_sync() for the synchronous, blocking version of this method. + */ + + +/** + * gxdp_documents_call_add_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_doc_id: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_add(). + * @error: Return location for error or %NULL. + * + * Finishes an operation started with gxdp_documents_call_add(). + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_add_named: + * @proxy: A #GXdpDocumentsProxy. + * @arg_o_path_parent_fd: Argument to pass with the method invocation. + * @arg_filename: Argument to pass with the method invocation. + * @arg_reuse_existing: Argument to pass with the method invocation. + * @arg_persistent: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. + * + * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.AddNamed">AddNamed()</link> D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. + * You can then call gxdp_documents_call_add_named_finish() to get the result of the operation. + * + * See gxdp_documents_call_add_named_sync() for the synchronous, blocking version of this method. + */ + + +/** + * gxdp_documents_call_add_named_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_doc_id: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_add_named(). + * @error: Return location for error or %NULL. + * + * Finishes an operation started with gxdp_documents_call_add_named(). + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_add_named_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_o_path_parent_fd: Argument to pass with the method invocation. + * @arg_filename: Argument to pass with the method invocation. + * @arg_reuse_existing: Argument to pass with the method invocation. + * @arg_persistent: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @out_doc_id: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. + * + * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.AddNamed">AddNamed()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. + * + * See gxdp_documents_call_add_named() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_add_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_o_path_fd: Argument to pass with the method invocation. + * @arg_reuse_existing: Argument to pass with the method invocation. + * @arg_persistent: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @out_doc_id: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. + * + * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Add">Add()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. + * + * See gxdp_documents_call_add() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_delete: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. + * + * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Delete">Delete()</link> D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. + * You can then call gxdp_documents_call_delete_finish() to get the result of the operation. + * + * See gxdp_documents_call_delete_sync() for the synchronous, blocking version of this method. + */ + + +/** + * gxdp_documents_call_delete_finish: + * @proxy: A #GXdpDocumentsProxy. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_delete(). + * @error: Return location for error or %NULL. + * + * Finishes an operation started with gxdp_documents_call_delete(). + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_delete_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. + * + * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Delete">Delete()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. + * + * See gxdp_documents_call_delete() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_get_mount_point: + * @proxy: A #GXdpDocumentsProxy. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. + * + * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GetMountPoint">GetMountPoint()</link> D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. + * You can then call gxdp_documents_call_get_mount_point_finish() to get the result of the operation. + * + * See gxdp_documents_call_get_mount_point_sync() for the synchronous, blocking version of this method. + */ + + +/** + * gxdp_documents_call_get_mount_point_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_path: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_get_mount_point(). + * @error: Return location for error or %NULL. + * + * Finishes an operation started with gxdp_documents_call_get_mount_point(). + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_get_mount_point_sync: + * @proxy: A #GXdpDocumentsProxy. + * @out_path: (out): Return location for return parameter or %NULL to ignore. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. + * + * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GetMountPoint">GetMountPoint()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. + * + * See gxdp_documents_call_get_mount_point() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_grant_permissions: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @arg_app_id: Argument to pass with the method invocation. + * @arg_permissions: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. + * + * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GrantPermissions">GrantPermissions()</link> D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. + * You can then call gxdp_documents_call_grant_permissions_finish() to get the result of the operation. + * + * See gxdp_documents_call_grant_permissions_sync() for the synchronous, blocking version of this method. + */ + + +/** + * gxdp_documents_call_grant_permissions_finish: + * @proxy: A #GXdpDocumentsProxy. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_grant_permissions(). + * @error: Return location for error or %NULL. + * + * Finishes an operation started with gxdp_documents_call_grant_permissions(). + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_grant_permissions_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @arg_app_id: Argument to pass with the method invocation. + * @arg_permissions: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. + * + * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GrantPermissions">GrantPermissions()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. + * + * See gxdp_documents_call_grant_permissions() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_info: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. + * + * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Info">Info()</link> D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. + * You can then call gxdp_documents_call_info_finish() to get the result of the operation. + * + * See gxdp_documents_call_info_sync() for the synchronous, blocking version of this method. + */ + + +/** + * gxdp_documents_call_info_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_path: (out): Return location for return parameter or %NULL to ignore. + * @out_apps: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_info(). + * @error: Return location for error or %NULL. + * + * Finishes an operation started with gxdp_documents_call_info(). + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_info_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @out_path: (out): Return location for return parameter or %NULL to ignore. + * @out_apps: (out): Return location for return parameter or %NULL to ignore. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. + * + * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Info">Info()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. + * + * See gxdp_documents_call_info() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_list: + * @proxy: A #GXdpDocumentsProxy. + * @arg_app_id: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. + * + * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.List">List()</link> D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. + * You can then call gxdp_documents_call_list_finish() to get the result of the operation. + * + * See gxdp_documents_call_list_sync() for the synchronous, blocking version of this method. + */ + + +/** + * gxdp_documents_call_list_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_docs: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_list(). + * @error: Return location for error or %NULL. + * + * Finishes an operation started with gxdp_documents_call_list(). + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_list_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_app_id: Argument to pass with the method invocation. + * @out_docs: (out): Return location for return parameter or %NULL to ignore. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. + * + * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.List">List()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. + * + * See gxdp_documents_call_list() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_lookup: + * @proxy: A #GXdpDocumentsProxy. + * @arg_filename: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. + * + * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Lookup">Lookup()</link> D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. + * You can then call gxdp_documents_call_lookup_finish() to get the result of the operation. + * + * See gxdp_documents_call_lookup_sync() for the synchronous, blocking version of this method. + */ + + +/** + * gxdp_documents_call_lookup_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_doc_id: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_lookup(). + * @error: Return location for error or %NULL. + * + * Finishes an operation started with gxdp_documents_call_lookup(). + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_lookup_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_filename: Argument to pass with the method invocation. + * @out_doc_id: (out): Return location for return parameter or %NULL to ignore. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. + * + * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Lookup">Lookup()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. + * + * See gxdp_documents_call_lookup() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_revoke_permissions: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @arg_app_id: Argument to pass with the method invocation. + * @arg_permissions: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. + * + * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.RevokePermissions">RevokePermissions()</link> D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. + * You can then call gxdp_documents_call_revoke_permissions_finish() to get the result of the operation. + * + * See gxdp_documents_call_revoke_permissions_sync() for the synchronous, blocking version of this method. + */ + + +/** + * gxdp_documents_call_revoke_permissions_finish: + * @proxy: A #GXdpDocumentsProxy. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_revoke_permissions(). + * @error: Return location for error or %NULL. + * + * Finishes an operation started with gxdp_documents_call_revoke_permissions(). + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_revoke_permissions_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @arg_app_id: Argument to pass with the method invocation. + * @arg_permissions: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. + * + * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.RevokePermissions">RevokePermissions()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received. + * + * See gxdp_documents_call_revoke_permissions() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_complete_add: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @doc_id: Parameter to return. + * + * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Add">Add()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar. + * + * This method will free @invocation, you cannot use it afterwards. + */ + + +/** + * gxdp_documents_complete_add_named: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @doc_id: Parameter to return. + * + * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.AddNamed">AddNamed()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar. + * + * This method will free @invocation, you cannot use it afterwards. + */ + + +/** + * gxdp_documents_complete_delete: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * + * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Delete">Delete()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar. + * + * This method will free @invocation, you cannot use it afterwards. + */ + + +/** + * gxdp_documents_complete_get_mount_point: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @path: Parameter to return. + * + * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GetMountPoint">GetMountPoint()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar. + * + * This method will free @invocation, you cannot use it afterwards. + */ + + +/** + * gxdp_documents_complete_grant_permissions: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * + * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GrantPermissions">GrantPermissions()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar. + * + * This method will free @invocation, you cannot use it afterwards. + */ + + +/** + * gxdp_documents_complete_info: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @path: Parameter to return. + * @apps: Parameter to return. + * + * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Info">Info()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar. + * + * This method will free @invocation, you cannot use it afterwards. + */ + + +/** + * gxdp_documents_complete_list: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @docs: Parameter to return. + * + * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.List">List()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar. + * + * This method will free @invocation, you cannot use it afterwards. + */ + + +/** + * gxdp_documents_complete_lookup: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @doc_id: Parameter to return. + * + * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Lookup">Lookup()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar. + * + * This method will free @invocation, you cannot use it afterwards. + */ + + +/** + * gxdp_documents_complete_revoke_permissions: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * + * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.RevokePermissions">RevokePermissions()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar. + * + * This method will free @invocation, you cannot use it afterwards. + */ + + +/** + * gxdp_documents_interface_info: + * + * Gets a machine-readable description of the <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link> D-Bus interface. + * + * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free. + */ + + +/** + * gxdp_documents_override_properties: + * @klass: The class structure for a #GObject<!-- -->-derived class. + * @property_id_begin: The property id to assign to the first overridden property. + * + * Overrides all #GObject properties in the #GXdpDocuments interface for a concrete class. + * The properties are overridden in the order they are defined. + * + * Returns: The last property id. + */ + + +/** + * gxdp_documents_proxy_new: + * @connection: A #GDBusConnection. + * @flags: Flags from the #GDBusProxyFlags enumeration. + * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. + * @object_path: An object path. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied. + * @user_data: User data to pass to @callback. + * + * Asynchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link>. See g_dbus_proxy_new() for more details. + * + * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. + * You can then call gxdp_documents_proxy_new_finish() to get the result of the operation. + * + * See gxdp_documents_proxy_new_sync() for the synchronous, blocking version of this constructor. + */ + + +/** + * gxdp_documents_proxy_new_finish: + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_proxy_new(). + * @error: Return location for error or %NULL + * + * Finishes an operation started with gxdp_documents_proxy_new(). + * + * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set. + */ + + +/** + * gxdp_documents_proxy_new_for_bus: + * @bus_type: A #GBusType. + * @flags: Flags from the #GDBusProxyFlags enumeration. + * @name: A bus name (well-known or unique). + * @object_path: An object path. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied. + * @user_data: User data to pass to @callback. + * + * Like gxdp_documents_proxy_new() but takes a #GBusType instead of a #GDBusConnection. + * + * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from. + * You can then call gxdp_documents_proxy_new_for_bus_finish() to get the result of the operation. + * + * See gxdp_documents_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor. + */ + + +/** + * gxdp_documents_proxy_new_for_bus_finish: + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_proxy_new_for_bus(). + * @error: Return location for error or %NULL + * + * Finishes an operation started with gxdp_documents_proxy_new_for_bus(). + * + * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set. + */ + + +/** + * gxdp_documents_proxy_new_for_bus_sync: + * @bus_type: A #GBusType. + * @flags: Flags from the #GDBusProxyFlags enumeration. + * @name: A bus name (well-known or unique). + * @object_path: An object path. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL + * + * Like gxdp_documents_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. + * + * The calling thread is blocked until a reply is received. + * + * See gxdp_documents_proxy_new_for_bus() for the asynchronous version of this constructor. + * + * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set. + */ + + +/** + * gxdp_documents_proxy_new_sync: + * @connection: A #GDBusConnection. + * @flags: Flags from the #GDBusProxyFlags enumeration. + * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. + * @object_path: An object path. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL + * + * Synchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link>. See g_dbus_proxy_new_sync() for more details. + * + * The calling thread is blocked until a reply is received. + * + * See gxdp_documents_proxy_new() for the asynchronous version of this constructor. + * + * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set. + */ + + +/** + * gxdp_documents_skeleton_new: + * + * Creates a skeleton object for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link>. + * + * Returns: (transfer full) (type GXdpDocumentsSkeleton): The skeleton object. + */ + + +/** * gxdp_network_monitor_emit_changed: * @object: A #GXdpNetworkMonitor. * @arg_available: Argument to pass with the signal. diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 2280a86c..0ae171b1 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -8248,6 +8248,47 @@ * generally considered undefined after one of these checks fails. * They are not intended for normal control flow, only to give a * perhaps-helpful warning before giving up. + * + * Structured logging output is supported using g_log_structured(). This differs + * from the traditional g_log() API in that log messages are handled as a + * collection of key–value pairs representing individual pieces of information, + * rather than as a single string containing all the information in an arbitrary + * format. + * + * The support for structured logging was motivated by the following needs (some + * of which were supported previously; others weren’t): + * * Support for multiple logging levels. + * * Structured log support with the ability to add `MESSAGE_ID`s (see + * g_log_structured()). + * * Moving the responsibility for filtering log messages from the program to + * the log viewer — instead of libraries and programs installing log handlers + * (with g_log_set_handler()) which filter messages before output, all log + * messages are outputted, and the log viewer program (such as `journalctl`) + * must filter them. This is based on the idea that bugs are sometimes hard + * to reproduce, so it is better to log everything possible and then use + * tools to analyse the logs than it is to not be able to reproduce a bug to + * get additional log data. Code which uses logging in performance-critical + * sections should compile out the g_log_structured() calls in + * release builds, and compile them in in debugging builds. + * * A single writer function which handles all log messages in a process, from + * all libraries and program code; rather than multiple log handlers with + * poorly defined interactions between them. This allows a program to easily + * change its logging policy by changing the writer function, for example to + * log to an additional location or to change what logging output fallbacks + * are used. The log writer functions provided by GLib are exposed publicly + * so they can be used from programs’ log writers. This allows log writer + * policy and implementation to be kept separate. + * * If a library wants to add standard information to all of its log messages + * (such as library state) or to redact private data (such as passwords or + * network credentials), it should use a wrapper function around its + * g_log_structured() calls or implement that in the single log writer + * function. + * * If a program wants to pass context data from a g_log_structured() call to + * its log writer function so that, for example, it can use the correct + * server connection to submit logs to, that user data can be passed as a + * zero-length #GLogField to g_log_structured_array(). + * * Color output needed to be supported on the terminal, to make reading + * through logs easier. */ @@ -12085,11 +12126,29 @@ /** + * g_compute_hmac_for_bytes: + * @digest_type: a #GChecksumType to use for the HMAC + * @key: the key to use in the HMAC + * @data: binary blob to compute the HMAC of + * + * Computes the HMAC for a binary @data. This is a + * convenience wrapper for g_hmac_new(), g_hmac_get_string() + * and g_hmac_unref(). + * + * The hexadecimal string returned will be in lower case. + * + * Returns: the HMAC of the binary data as a string in hexadecimal. + * The returned string should be freed with g_free() when done using it. + * Since: 2.50 + */ + + +/** * g_compute_hmac_for_data: * @digest_type: a #GChecksumType to use for the HMAC * @key: (array length=key_len): the key to use in the HMAC * @key_len: the length of the key - * @data: binary blob to compute the HMAC of + * @data: (array length=length): binary blob to compute the HMAC of * @length: length of @data * * Computes the HMAC for a binary @data of @length. This is a @@ -19226,6 +19285,14 @@ * the `G_DEBUG` environment variable (see * [Running GLib Applications](glib-running.html)). * + * Libraries should not call this function, as it affects all messages logged + * by a process, including those from other libraries. + * + * Structured log messages (using g_log_structured() and + * g_log_structured_array()) are fatal only if the default log writer is used; + * otherwise it is up to the writer function to determine which log messages + * are fatal. + * * Returns: the old fatal mask */ @@ -19253,6 +19320,11 @@ * Sets the log levels which are fatal in the given domain. * %G_LOG_LEVEL_ERROR is always fatal. * + * This has no effect on structured log messages (using g_log_structured() or + * g_log_structured_array()). To change the fatal behaviour for specific log + * messages, programs must install a custom log writer function using + * g_log_set_writer_func(). + * * Returns: the old fatal mask for the log domain */ @@ -19320,6 +19392,263 @@ /** + * g_log_set_writer_func: + * @func: log writer function, which must not be %NULL + * @user_data: (closure func): user data to pass to @func + * @user_data_free: (destroy func): function to free @user_data once it’s + * finished with, if non-%NULL + * + * Set a writer function which will be called to format and write out each log + * message. Each program should set a writer function, or the default writer + * (g_log_writer_default()) will be used. + * + * Libraries **must not** call this function — only programs are allowed to + * install a writer function, as there must be a single, central point where + * log messages are formatted and outputted. + * + * There can only be one writer function. It is an error to set more than one. + * + * Since: 2.50 + */ + + +/** + * g_log_structured: + * @log_domain: log domain, usually %G_LOG_DOMAIN + * @log_level: log level, either from #GLogLevelFlags, or a user-defined + * level + * @format: message format, in printf() style + * @...: parameters to insert into the format string, followed by key–value + * pairs of structured data to add to the log message, terminated with a + * %NULL + * + * Log a message with structured data. The message will be passed through to the + * log writer set by the application using g_log_set_writer_func(). If the + * message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will + * be aborted at the end of this function. + * + * The structured data is provided as key–value pairs, where keys are UTF-8 + * strings, and values are arbitrary pointers — typically pointing to UTF-8 + * strings, but that is not a requirement. To pass binary (non-nul-terminated) + * structured data, use g_log_structured_array(). The keys for structured data + * should follow the [systemd journal + * fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html) + * specification. It is suggested that custom keys are namespaced according to + * the code which sets them. For example, custom keys from GLib all have a + * `GLIB_` prefix. + * + * The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will + * be converted into a `PRIORITY` field. @format will have its placeholders + * substituted for the provided values and be converted into a `MESSAGE` field. + * + * Other fields you may commonly want to pass into this function: + * + * * [`MESSAGE_ID`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=) + * * [`CODE_FILE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=) + * * [`CODE_LINE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_LINE=) + * * [`CODE_FUNC`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FUNC=) + * * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=) + * + * Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by + * the logging macros, g_debug_structured(), G_DEBUG_HERE(), + * g_message_structured(), g_warning_structured(), g_critical_structured() and + * g_error_structured(). + * + * For example: + * ``` + * g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, + * "This is a debug message about pointer %p and integer %u.", + * some_pointer, some_integer, + * "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", + * "MY_APPLICATION_CUSTOM_FIELD", "some debug string", + * NULL); + * ``` + * + * Note that each `MESSAGE_ID` **must** be [uniquely and randomly + * generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=). + * If adding a `MESSAGE_ID`, consider shipping a [message + * catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with + * your software. + * + * To pass a user data pointer to the log writer function which is specific to + * this logging call, you must use g_log_structured_array() and pass the pointer + * as a field with #GLogField.length set to zero, otherwise it will be + * interpreted as a string. + * + * For example: + * ``` + * const GLogField fields[] = { + * { "MESSAGE", "This is a debug message.", -1 }, + * { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 }, + * { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 }, + * { "MY_APPLICATION_STATE", state_object, 0 }, + * }; + * g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields)); + * ``` + * + * Note also that, even if no structured fields are specified, the argument list + * **must** be %NULL-terminated. + * + * The default writer function for `stdout` and `stderr` will automatically + * append a new-line character to the @format, so you should not add one + * manually. + * + * Since: 2.50 + */ + + +/** + * g_log_structured_array: + * @log_level: log level, either from #GLogLevelFlags, or a user-defined + * level + * @fields: (array length=n_fields): key–value pairs of structured data to add + * to the log message + * @n_fields: number of elements in the @fields array + * + * Log a message with structured data. The message will be passed through to the + * log writer set by the application using g_log_set_writer_func(). If the + * message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will + * be aborted at the end of this function. + * + * See g_log_structured() for more documentation. + * + * This assumes that @log_level is already present in @fields (typically as the + * `PRIORITY` field). + * + * Since: 2.50 + */ + + +/** + * g_log_writer_default: + * @log_level: log level, either from #GLogLevelFlags, or a user-defined + * level + * @fields: (array length=n_fields): key–value pairs of structured data forming + * the log message + * @n_fields: number of elements in the @fields array + * @user_data: user data passed to g_log_set_writer_func() + * + * Format a structured log message and output it to the default log destination + * for the platform. On Linux, this is typically the systemd journal, falling + * back to `stdout` or `stderr` if running from the terminal or if output is + * being redirected to a file. + * + * Support for other platform-specific logging mechanisms may be added in + * future. Distributors of GLib may modify this function to impose their own + * (documented) platform-specific log writing policies. + * + * This is suitable for use as a #GLogWriterFunc, and is the default writer used + * if no other is set using g_log_set_writer_func(). + * + * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + * Since: 2.50 + */ + + +/** + * g_log_writer_format_fields: + * @log_level: log level, either from #GLogLevelFlags, or a user-defined + * level + * @fields: (array length=n_fields): key–value pairs of structured data forming + * the log message + * @n_fields: number of elements in the @fields array + * @use_color: %TRUE to use ANSI color escape sequences when formatting the + * message, %FALSE to not + * + * Format a structured log message as a string suitable for outputting to the + * terminal (or elsewhere). This will include the values of all fields it knows + * how to interpret, which includes `MESSAGE` and `GLIB_DOMAIN` (see the + * documentation for g_log_structured()). It does not include values from + * unknown fields. + * + * The returned string does **not** have a trailing new-line character. It is + * encoded in the character set of the current locale, which is not necessarily + * UTF-8. + * + * Returns: (transfer full): string containing the formatted log message, in + * the character set of the current locale + * Since: 2.50 + */ + + +/** + * g_log_writer_is_journald: + * @output_fd: output file descriptor to check + * + * Check whether the given @output_fd file descriptor is a connection to the + * systemd journal, or something else (like a log file or `stdout` or + * `stderr`). + * + * Returns: %TRUE if @output_fd points to the journal, %FALSE otherwise + * Since: 2.50 + */ + + +/** + * g_log_writer_journald: + * @log_level: log level, either from #GLogLevelFlags, or a user-defined + * level + * @fields: (array length=n_fields): key–value pairs of structured data forming + * the log message + * @n_fields: number of elements in the @fields array + * @user_data: user data passed to g_log_set_writer_func() + * + * Format a structured log message and send it to the systemd journal as a set + * of key–value pairs. All fields are sent to the journal, but if a field has + * length zero (indicating program-specific data) then only its key will be + * sent. + * + * This is suitable for use as a #GLogWriterFunc. + * + * If GLib has been compiled without systemd support, this function is still + * defined, but will always return %G_LOG_WRITER_UNHANDLED. + * + * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + * Since: 2.50 + */ + + +/** + * g_log_writer_standard_streams: + * @log_level: log level, either from #GLogLevelFlags, or a user-defined + * level + * @fields: (array length=n_fields): key–value pairs of structured data forming + * the log message + * @n_fields: number of elements in the @fields array + * @user_data: user data passed to g_log_set_writer_func() + * + * Format a structured log message and print it to either `stdout` or `stderr`, + * depending on its log level. %G_LOG_LEVEL_INFO and %G_LOG_LEVEL_DEBUG messages + * are sent to `stdout`; all other log levels are sent to `stderr`. Only fields + * which are understood by this function are included in the formatted string + * which is printed. + * + * If the output stream supports ANSI color escape sequences, they will be used + * in the output. + * + * A trailing new-line character is added to the log message when it is printed. + * + * This is suitable for use as a #GLogWriterFunc. + * + * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + * Since: 2.50 + */ + + +/** + * g_log_writer_supports_color: + * @output_fd: output file descriptor to check + * + * Check whether the given @output_fd file descriptor supports ANSI color + * escape sequences. If so, they can safely be used when formatting log + * messages. + * + * Returns: %TRUE if ANSI color escapes are supported, %FALSE otherwise + * Since: 2.50 + */ + + +/** * g_logv: * @log_domain: (nullable): the log domain, or %NULL for the default "" * application domain @@ -29505,6 +29834,11 @@ * * This handler has no effect on g_error messages. * + * This handler also has no effect on structured log messages (using + * g_log_structured() or g_log_structured_array()). To change the fatal + * behaviour for specific log messages, programs must install a custom log + * writer function using g_log_set_writer_func(). + * * Since: 2.22 */ @@ -33782,6 +34116,9 @@ * the last byte then the returned string is the string, up to the first * such nul character. * + * g_variant_get_fixed_array() should be used instead if the array contains + * arbitrary data that could not be nul-terminated or could contain nul bytes. + * * It is an error to call this function with a @value that is not an * array of bytes. * |