@gtkx/ffi 0.1.45 → 0.1.47

package/dist/generated/gio/dbus-method-invocation.d.ts

@@ -5,22 +5,170 @@ import { DBusMessage } from "./dbus-message.js";
 import { UnixFDList } from "./unix-fdlist.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * Instances of the `GDBusMethodInvocation` class are used when
+ * handling D-Bus method calls. It provides a way to asynchronously
+ * return results and errors.
+ *
+ * The normal way to obtain a `GDBusMethodInvocation` object is to receive
+ * it as an argument to the `handle_method_call()` function in a
+ * [type@Gio.DBusInterfaceVTable] that was passed to
+ * [method@Gio.DBusConnection.register_object].
+ */
 export declare class DBusMethodInvocation extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the #GDBusConnection the method was invoked on.
+     */
     getConnection(): DBusConnection;
+    /**
+     * Gets the name of the D-Bus interface the method was invoked on.
+     *
+     * This can be `NULL` if it was not specified by the sender. See
+     * [callback@Gio.DBusInterfaceMethodCallFunc] or the
+     * D-Bus Specification
+     * for details on when this can happen and how it should be handled.
+     *
+     * If this method call is a property Get, Set or GetAll call that has
+     * been redirected to the method call handler then
+     * "org.freedesktop.DBus.Properties" will be returned.  See
+     * #GDBusInterfaceVTable for more information.
+     */
     getInterfaceName(): string | null;
+    /**
+     * Gets the #GDBusMessage for the method invocation. This is useful if
+     * you need to use low-level protocol features, such as UNIX file
+     * descriptor passing, that cannot be properly expressed in the
+     * #GVariant API.
+     *
+     * See this [server][class@Gio.DBusConnection#an-example-d-bus-server]
+     * and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing]
+     * for an example of how to use this low-level API to send and receive
+     * UNIX file descriptors.
+     */
     getMessage(): DBusMessage;
+    /**
+     * Gets information about the method call, if any.
+     *
+     * If this method invocation is a property Get, Set or GetAll call that
+     * has been redirected to the method call handler then %NULL will be
+     * returned.  See g_dbus_method_invocation_get_property_info() and
+     * #GDBusInterfaceVTable for more information.
+     */
     getMethodInfo(): DBusMethodInfo | null;
+    /**
+     * Gets the name of the method that was invoked.
+     */
     getMethodName(): string;
+    /**
+     * Gets the object path the method was invoked on.
+     */
     getObjectPath(): string;
+    /**
+     * Gets the parameters of the method invocation. If there are no input
+     * parameters then this will return a GVariant with 0 children rather than NULL.
+     */
     getParameters(): GLib.Variant;
+    /**
+     * Gets information about the property that this method call is for, if
+     * any.
+     *
+     * This will only be set in the case of an invocation in response to a
+     * property Get or Set call that has been directed to the method call
+     * handler for an object on account of its property_get() or
+     * property_set() vtable pointers being unset.
+     *
+     * See #GDBusInterfaceVTable for more information.
+     *
+     * If the call was GetAll, %NULL will be returned.
+     */
     getPropertyInfo(): DBusPropertyInfo | null;
+    /**
+     * Gets the bus name that invoked the method.
+     *
+     * This can return %NULL if not specified by the caller, e.g. on peer-to-peer
+     * connections.
+     */
     getSender(): string | null;
+    /**
+     * Finishes handling a D-Bus method call by returning an error.
+     *
+     * This method will take ownership of @invocation. See
+     * #GDBusInterfaceVTable for more information about the ownership of
+     * @invocation.
+     * @param errorName - A valid D-Bus error name.
+     * @param errorMessage - A valid D-Bus error message.
+     */
     returnDbusError(errorName: string, errorMessage: string): void;
+    /**
+     * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
+     *
+     * This method will take ownership of @invocation. See
+     * #GDBusInterfaceVTable for more information about the ownership of
+     * @invocation.
+     * @param domain - A #GQuark for the #GError error domain.
+     * @param code - The error code.
+     * @param message - The error message.
+     */
     returnErrorLiteral(domain: number, code: number, message: string): void;
+    /**
+     * Like g_dbus_method_invocation_return_error() but takes a #GError
+     * instead of the error domain, error code and message.
+     *
+     * This method will take ownership of @invocation. See
+     * #GDBusInterfaceVTable for more information about the ownership of
+     * @invocation.
+     * @param error - A #GError.
+     */
     returnGerror(error: GLib.GError): void;
+    /**
+     * Finishes handling a D-Bus method call by returning @parameters.
+     * If the `parameters` GVariant is floating, it is consumed.
+     *
+     * It is an error if `parameters` is not of the right format: it must be a tuple
+     * containing the out-parameters of the D-Bus method. Even if the method has a
+     * single out-parameter, it must be contained in a tuple. If the method has no
+     * out-parameters, `parameters` may be %NULL or an empty tuple.
+     *
+     * |[<!-- language="C" -->
+     * GDBusMethodInvocation *invocation = some_invocation;
+     * g_autofree gchar *result_string = NULL;
+     * g_autoptr (GError) error = NULL;
+     *
+     * result_string = calculate_result (&error);
+     *
+     * if (error != NULL)
+     * g_dbus_method_invocation_return_gerror (invocation, error);
+     * else
+     * g_dbus_method_invocation_return_value (invocation,
+     * g_variant_new ("(s)", result_string));
+     *
+     * // Do not free `invocation` here; returning a value does that
+     * ]|
+     *
+     * This method will take ownership of @invocation. See
+     * #GDBusInterfaceVTable for more information about the ownership of
+     * @invocation.
+     *
+     * Since 2.48, if the method call requested for a reply not to be sent
+     * then this call will sink `parameters` and free @invocation, but
+     * otherwise do nothing (as per the recommendations of the D-Bus
+     * specification).
+     * @param parameters - A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
+     */
     returnValue(parameters?: GLib.Variant | null): void;
+    /**
+     * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
+     *
+     * This method is only available on UNIX.
+     *
+     * This method will take ownership of @invocation. See
+     * #GDBusInterfaceVTable for more information about the ownership of
+     * @invocation.
+     * @param parameters - A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
+     * @param fdList - A #GUnixFDList or %NULL.
+     */
     returnValueWithUnixFdList(parameters?: GLib.Variant | null, fdList?: UnixFDList | null): void;
     connect(signal: "notify", handler: (self: DBusMethodInvocation, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gio/dbus-method-invocation.js

@@ -6,6 +6,16 @@ import { DBusConnection } from "./dbus-connection.js";
 import { DBusMessage } from "./dbus-message.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * Instances of the `GDBusMethodInvocation` class are used when
+ * handling D-Bus method calls. It provides a way to asynchronously
+ * return results and errors.
+ *
+ * The normal way to obtain a `GDBusMethodInvocation` object is to receive
+ * it as an argument to the `handle_method_call()` function in a
+ * [type@Gio.DBusInterfaceVTable] that was passed to
+ * [method@Gio.DBusConnection.register_object].
+ */
 export class DBusMethodInvocation extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -17,6 +27,9 @@ export class DBusMethodInvocation extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Gets the #GDBusConnection the method was invoked on.
+     */
     getConnection() {
         const ptr = call("libgio-2.0.so.0", "g_dbus_method_invocation_get_connection", [
             {
@@ -26,6 +39,19 @@ export class DBusMethodInvocation extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, DBusConnection);
     }
+    /**
+     * Gets the name of the D-Bus interface the method was invoked on.
+     *
+     * This can be `NULL` if it was not specified by the sender. See
+     * [callback@Gio.DBusInterfaceMethodCallFunc] or the
+     * D-Bus Specification
+     * for details on when this can happen and how it should be handled.
+     *
+     * If this method call is a property Get, Set or GetAll call that has
+     * been redirected to the method call handler then
+     * "org.freedesktop.DBus.Properties" will be returned.  See
+     * #GDBusInterfaceVTable for more information.
+     */
     getInterfaceName() {
         return call("libgio-2.0.so.0", "g_dbus_method_invocation_get_interface_name", [
             {
@@ -34,6 +60,17 @@ export class DBusMethodInvocation extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the #GDBusMessage for the method invocation. This is useful if
+     * you need to use low-level protocol features, such as UNIX file
+     * descriptor passing, that cannot be properly expressed in the
+     * #GVariant API.
+     *
+     * See this [server][class@Gio.DBusConnection#an-example-d-bus-server]
+     * and [client][class@Gio.DBusConnection#an-example-for-file-descriptor-passing]
+     * for an example of how to use this low-level API to send and receive
+     * UNIX file descriptors.
+     */
     getMessage() {
         const ptr = call("libgio-2.0.so.0", "g_dbus_method_invocation_get_message", [
             {
@@ -43,6 +80,14 @@ export class DBusMethodInvocation extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, DBusMessage);
     }
+    /**
+     * Gets information about the method call, if any.
+     *
+     * If this method invocation is a property Get, Set or GetAll call that
+     * has been redirected to the method call handler then %NULL will be
+     * returned.  See g_dbus_method_invocation_get_property_info() and
+     * #GDBusInterfaceVTable for more information.
+     */
     getMethodInfo() {
         const ptr = call("libgio-2.0.so.0", "g_dbus_method_invocation_get_method_info", [
             {
@@ -59,6 +104,9 @@ export class DBusMethodInvocation extends GObject.GObject {
             return null;
         return getObject(ptr, DBusMethodInfo);
     }
+    /**
+     * Gets the name of the method that was invoked.
+     */
     getMethodName() {
         return call("libgio-2.0.so.0", "g_dbus_method_invocation_get_method_name", [
             {
@@ -67,6 +115,9 @@ export class DBusMethodInvocation extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the object path the method was invoked on.
+     */
     getObjectPath() {
         return call("libgio-2.0.so.0", "g_dbus_method_invocation_get_object_path", [
             {
@@ -75,6 +126,10 @@ export class DBusMethodInvocation extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the parameters of the method invocation. If there are no input
+     * parameters then this will return a GVariant with 0 children rather than NULL.
+     */
     getParameters() {
         const ptr = call("libgio-2.0.so.0", "g_dbus_method_invocation_get_parameters", [
             {
@@ -89,6 +144,19 @@ export class DBusMethodInvocation extends GObject.GObject {
         });
         return getObject(ptr, GLib.Variant);
     }
+    /**
+     * Gets information about the property that this method call is for, if
+     * any.
+     *
+     * This will only be set in the case of an invocation in response to a
+     * property Get or Set call that has been directed to the method call
+     * handler for an object on account of its property_get() or
+     * property_set() vtable pointers being unset.
+     *
+     * See #GDBusInterfaceVTable for more information.
+     *
+     * If the call was GetAll, %NULL will be returned.
+     */
     getPropertyInfo() {
         const ptr = call("libgio-2.0.so.0", "g_dbus_method_invocation_get_property_info", [
             {
@@ -105,6 +173,12 @@ export class DBusMethodInvocation extends GObject.GObject {
             return null;
         return getObject(ptr, DBusPropertyInfo);
     }
+    /**
+     * Gets the bus name that invoked the method.
+     *
+     * This can return %NULL if not specified by the caller, e.g. on peer-to-peer
+     * connections.
+     */
     getSender() {
         return call("libgio-2.0.so.0", "g_dbus_method_invocation_get_sender", [
             {
@@ -113,6 +187,15 @@ export class DBusMethodInvocation extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Finishes handling a D-Bus method call by returning an error.
+     *
+     * This method will take ownership of @invocation. See
+     * #GDBusInterfaceVTable for more information about the ownership of
+     * @invocation.
+     * @param errorName - A valid D-Bus error name.
+     * @param errorMessage - A valid D-Bus error message.
+     */
     returnDbusError(errorName, errorMessage) {
         call("libgio-2.0.so.0", "g_dbus_method_invocation_return_dbus_error", [
             {
@@ -129,6 +212,16 @@ export class DBusMethodInvocation extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
+     *
+     * This method will take ownership of @invocation. See
+     * #GDBusInterfaceVTable for more information about the ownership of
+     * @invocation.
+     * @param domain - A #GQuark for the #GError error domain.
+     * @param code - The error code.
+     * @param message - The error message.
+     */
     returnErrorLiteral(domain, code, message) {
         call("libgio-2.0.so.0", "g_dbus_method_invocation_return_error_literal", [
             {
@@ -149,6 +242,15 @@ export class DBusMethodInvocation extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Like g_dbus_method_invocation_return_error() but takes a #GError
+     * instead of the error domain, error code and message.
+     *
+     * This method will take ownership of @invocation. See
+     * #GDBusInterfaceVTable for more information about the ownership of
+     * @invocation.
+     * @param error - A #GError.
+     */
     returnGerror(error) {
         call("libgio-2.0.so.0", "g_dbus_method_invocation_return_gerror", [
             {
@@ -166,6 +268,41 @@ export class DBusMethodInvocation extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes handling a D-Bus method call by returning @parameters.
+     * If the `parameters` GVariant is floating, it is consumed.
+     *
+     * It is an error if `parameters` is not of the right format: it must be a tuple
+     * containing the out-parameters of the D-Bus method. Even if the method has a
+     * single out-parameter, it must be contained in a tuple. If the method has no
+     * out-parameters, `parameters` may be %NULL or an empty tuple.
+     *
+     * |[<!-- language="C" -->
+     * GDBusMethodInvocation *invocation = some_invocation;
+     * g_autofree gchar *result_string = NULL;
+     * g_autoptr (GError) error = NULL;
+     *
+     * result_string = calculate_result (&error);
+     *
+     * if (error != NULL)
+     * g_dbus_method_invocation_return_gerror (invocation, error);
+     * else
+     * g_dbus_method_invocation_return_value (invocation,
+     * g_variant_new ("(s)", result_string));
+     *
+     * // Do not free `invocation` here; returning a value does that
+     * ]|
+     *
+     * This method will take ownership of @invocation. See
+     * #GDBusInterfaceVTable for more information about the ownership of
+     * @invocation.
+     *
+     * Since 2.48, if the method call requested for a reply not to be sent
+     * then this call will sink `parameters` and free @invocation, but
+     * otherwise do nothing (as per the recommendations of the D-Bus
+     * specification).
+     * @param parameters - A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
+     */
     returnValue(parameters) {
         call("libgio-2.0.so.0", "g_dbus_method_invocation_return_value", [
             {
@@ -184,6 +321,17 @@ export class DBusMethodInvocation extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
+     *
+     * This method is only available on UNIX.
+     *
+     * This method will take ownership of @invocation. See
+     * #GDBusInterfaceVTable for more information about the ownership of
+     * @invocation.
+     * @param parameters - A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
+     * @param fdList - A #GUnixFDList or %NULL.
+     */
     returnValueWithUnixFdList(parameters, fdList) {
         call("libgio-2.0.so.0", "g_dbus_method_invocation_return_value_with_unix_fd_list", [
             {

package/dist/generated/gio/dbus-node-info.d.ts

@@ -1,19 +1,67 @@
 import { DBusAnnotationInfo } from "./dbus-annotation-info.js";
 import { DBusInterfaceInfo } from "./dbus-interface-info.js";
 import * as GLib from "../glib/index.js";
+/** Information about nodes in a remote object hierarchy. */
 export declare class DBusNodeInfo {
     ptr: unknown;
+    /**
+     * Parses `xml_data` and returns a #GDBusNodeInfo representing the data.
+     *
+     * The introspection XML must contain exactly one top-level
+     * `<node>` element.
+     *
+     * Note that this routine is using a
+     * GMarkup-based
+     * parser that only accepts a subset of valid XML documents.
+     * @param xmlData - Valid D-Bus introspection XML.
+     */
     constructor(xmlData: string);
     constructor(_args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Appends an XML representation of `info` (and its children) to @string_builder.
+     *
+     * This function is typically used for generating introspection XML documents at run-time for
+     * handling the `org.freedesktop.DBus.Introspectable.Introspect`  method.
+     * @param indent - Indentation level.
+     * @param stringBuilder - A #GString to to append XML data to.
+     */
     generateXml(indent: number, stringBuilder: GLib.String): void;
+    /**
+     * Looks up information about an interface.
+     *
+     * The cost of this function is O(n) in number of interfaces.
+     * @param name - A D-Bus interface name.
+     */
     lookupInterface(name: string): DBusInterfaceInfo | null;
+    /**
+     * If `info` is statically allocated does nothing. Otherwise increases
+     * the reference count.
+     */
     ref(): DBusNodeInfo;
+    /**
+     * If `info` is statically allocated, does nothing. Otherwise decreases
+     * the reference count of @info. When its reference count drops to 0,
+     * the memory used is freed.
+     */
     unref(): void;
+    /** The reference count or -1 if statically allocated. */
     get refCount(): number;
     set refCount(value: number);
+    /**
+     * The path of the node or %NULL if omitted. Note that this may be a relative path. See the D-Bus specification for more details.
+     */
     get path(): string;
+    /**
+     * A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces.
+     */
     get interfaces(): DBusInterfaceInfo[];
+    /**
+     * A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes.
+     */
     get nodes(): DBusNodeInfo[];
+    /**
+     * A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+     */
     get annotations(): DBusAnnotationInfo[];
 }

package/dist/generated/gio/dbus-node-info.js

@@ -1,6 +1,7 @@
 import { call, read, write } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { DBusInterfaceInfo } from "./dbus-interface-info.js";
+/** Information about nodes in a remote object hierarchy. */
 export class DBusNodeInfo {
     ptr;
     constructor(...args) {
@@ -16,6 +17,14 @@ export class DBusNodeInfo {
             },
         ], { type: "boxed", borrowed: true, innerType: "GDBusNodeInfo" });
     }
+    /**
+     * Appends an XML representation of `info` (and its children) to @string_builder.
+     *
+     * This function is typically used for generating introspection XML documents at run-time for
+     * handling the `org.freedesktop.DBus.Introspectable.Introspect`  method.
+     * @param indent - Indentation level.
+     * @param stringBuilder - A #GString to to append XML data to.
+     */
     generateXml(indent, stringBuilder) {
         call("libgio-2.0.so.0", "g_dbus_node_info_generate_xml", [
             {
@@ -37,6 +46,12 @@ export class DBusNodeInfo {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Looks up information about an interface.
+     *
+     * The cost of this function is O(n) in number of interfaces.
+     * @param name - A D-Bus interface name.
+     */
     lookupInterface(name) {
         const ptr = call("libgio-2.0.so.0", "g_dbus_node_info_lookup_interface", [
             {
@@ -57,6 +72,10 @@ export class DBusNodeInfo {
             return null;
         return getObject(ptr, DBusInterfaceInfo);
     }
+    /**
+     * If `info` is statically allocated does nothing. Otherwise increases
+     * the reference count.
+     */
     ref() {
         const ptr = call("libgio-2.0.so.0", "g_dbus_node_info_ref", [
             {
@@ -71,6 +90,11 @@ export class DBusNodeInfo {
         });
         return getObject(ptr, DBusNodeInfo);
     }
+    /**
+     * If `info` is statically allocated, does nothing. Otherwise decreases
+     * the reference count of @info. When its reference count drops to 0,
+     * the memory used is freed.
+     */
     unref() {
         call("libgio-2.0.so.0", "g_dbus_node_info_unref", [
             {
@@ -79,15 +103,22 @@ export class DBusNodeInfo {
             },
         ], { type: "undefined" });
     }
+    /** The reference count or -1 if statically allocated. */
     get refCount() {
         return read(this.ptr, { type: "int", size: 32, unsigned: false }, 0);
     }
     set refCount(value) {
         write(this.ptr, { type: "int", size: 32, unsigned: false }, 0, value);
     }
+    /**
+     * The path of the node or %NULL if omitted. Note that this may be a relative path. See the D-Bus specification for more details.
+     */
     get path() {
         return read(this.ptr, { type: "string" }, 8);
     }
+    /**
+     * A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces.
+     */
     get interfaces() {
         return read(this.ptr, {
             type: "array",
@@ -98,6 +129,9 @@ export class DBusNodeInfo {
             },
         }, 16);
     }
+    /**
+     * A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes.
+     */
     get nodes() {
         return read(this.ptr, {
             type: "array",
@@ -108,6 +142,9 @@ export class DBusNodeInfo {
             },
         }, 24);
     }
+    /**
+     * A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+     */
     get annotations() {
         return read(this.ptr, {
             type: "array",