@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/tcp-connection.d.ts

@@ -1,7 +1,27 @@
 import { SocketConnection } from "./socket-connection.js";
+/**
+ * This is the subclass of [class@Gio.SocketConnection] that is created
+ * for TCP/IP sockets.
+ */
 export declare class TcpConnection extends SocketConnection {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Checks if graceful disconnects are used. See
+     * g_tcp_connection_set_graceful_disconnect().
+     */
     getGracefulDisconnect(): boolean;
+    /**
+     * This enables graceful disconnects on close. A graceful disconnect
+     * means that we signal the receiving end that the connection is terminated
+     * and wait for it to close the connection before closing the connection.
+     *
+     * A graceful disconnect means that we can be sure that we successfully sent
+     * all the outstanding data to the other end, or get an error reported.
+     * However, it also means we have to wait for all the data to reach the
+     * other side and for it to acknowledge this by closing the socket, which may
+     * take a while. For this reason it is disabled by default.
+     * @param gracefulDisconnect - Whether to do graceful disconnects or not
+     */
     setGracefulDisconnect(gracefulDisconnect: boolean): void;
 }

package/dist/generated/gio/tcp-connection.js

@@ -1,5 +1,9 @@
 import { call } from "@gtkx/native";
 import { SocketConnection } from "./socket-connection.js";
+/**
+ * This is the subclass of [class@Gio.SocketConnection] that is created
+ * for TCP/IP sockets.
+ */
 export class TcpConnection extends SocketConnection {
     constructor(...args) {
         super(...args);
@@ -15,6 +19,10 @@ export class TcpConnection extends SocketConnection {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Checks if graceful disconnects are used. See
+     * g_tcp_connection_set_graceful_disconnect().
+     */
     getGracefulDisconnect() {
         return call("libgio-2.0.so.0", "g_tcp_connection_get_graceful_disconnect", [
             {
@@ -23,6 +31,18 @@ export class TcpConnection extends SocketConnection {
             },
         ], { type: "boolean" });
     }
+    /**
+     * This enables graceful disconnects on close. A graceful disconnect
+     * means that we signal the receiving end that the connection is terminated
+     * and wait for it to close the connection before closing the connection.
+     *
+     * A graceful disconnect means that we can be sure that we successfully sent
+     * all the outstanding data to the other end, or get an error reported.
+     * However, it also means we have to wait for all the data to reach the
+     * other side and for it to acknowledge this by closing the socket, which may
+     * take a while. For this reason it is disabled by default.
+     * @param gracefulDisconnect - Whether to do graceful disconnects or not
+     */
     setGracefulDisconnect(gracefulDisconnect) {
         call("libgio-2.0.so.0", "g_tcp_connection_set_graceful_disconnect", [
             {

package/dist/generated/gio/tcp-wrapper-connection.d.ts

@@ -1,9 +1,25 @@
 import { IOStream } from "./iostream.js";
 import { Socket } from "./socket.js";
 import { TcpConnection } from "./tcp-connection.js";
+/**
+ * A `GTcpWrapperConnection` can be used to wrap a [class@Gio.IOStream] that is
+ * based on a [class@Gio.Socket], but which is not actually a
+ * [class@Gio.SocketConnection]. This is used by [class@Gio.SocketClient] so
+ * that it can always return a [class@Gio.SocketConnection], even when the
+ * connection it has actually created is not directly a
+ * [class@Gio.SocketConnection].
+ */
 export declare class TcpWrapperConnection extends TcpConnection {
+    /**
+     * Wraps `base_io_stream` and `socket` together as a #GSocketConnection.
+     * @param baseIoStream - the #GIOStream to wrap
+     * @param socket - the #GSocket associated with @base_io_stream
+     */
     constructor(baseIoStream: IOStream, socket: Socket);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Gets @conn's base #GIOStream
+     */
     getBaseIoStream(): IOStream;
 }

package/dist/generated/gio/tcp-wrapper-connection.js

@@ -2,6 +2,14 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { IOStream } from "./iostream.js";
 import { TcpConnection } from "./tcp-connection.js";
+/**
+ * A `GTcpWrapperConnection` can be used to wrap a [class@Gio.IOStream] that is
+ * based on a [class@Gio.Socket], but which is not actually a
+ * [class@Gio.SocketConnection]. This is used by [class@Gio.SocketClient] so
+ * that it can always return a [class@Gio.SocketConnection], even when the
+ * connection it has actually created is not directly a
+ * [class@Gio.SocketConnection].
+ */
 export class TcpWrapperConnection extends TcpConnection {
     constructor(...args) {
         super(...args);
@@ -19,6 +27,9 @@ export class TcpWrapperConnection extends TcpConnection {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets @conn's base #GIOStream
+     */
     getBaseIoStream() {
         const ptr = call("libgio-2.0.so.0", "g_tcp_wrapper_connection_get_base_io_stream", [
             {

package/dist/generated/gio/test-dbus.d.ts

@@ -1,15 +1,146 @@
 import { TestDBusFlags } from "./enums.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * A helper class for testing code which uses D-Bus without touching the user’s
+ * session bus.
+ *
+ * Note that `GTestDBus` modifies the user’s environment, calling
+ * [`setenv()`](man:setenv(3)). This is not thread-safe, so all `GTestDBus`
+ * calls should be completed before threads are spawned, or should have
+ * appropriate locking to ensure no access conflicts to environment variables
+ * shared between `GTestDBus` and other threads.
+ *
+ * ## Creating unit tests using `GTestDBus`
+ *
+ * Testing of D-Bus services can be tricky because normally we only ever run
+ * D-Bus services over an existing instance of the D-Bus daemon thus we
+ * usually don’t activate D-Bus services that are not yet installed into the
+ * target system. The `GTestDBus` object makes this easier for us by taking care
+ * of the lower level tasks such as running a private D-Bus daemon and looking
+ * up uninstalled services in customizable locations, typically in your source
+ * code tree.
+ *
+ * The first thing you will need is a separate service description file for the
+ * D-Bus daemon. Typically a `services` subdirectory of your `tests` directory
+ * is a good place to put this file.
+ *
+ * The service file should list your service along with an absolute path to the
+ * uninstalled service executable in your source tree. Using autotools we would
+ * achieve this by adding a file such as `my-server.service.in` in the services
+ * directory and have it processed by configure.
+ *
+ * ```
+ * [D-BUS Service]
+ * Name=org.gtk.GDBus.Examples.ObjectManager
+ * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
+ * ```
+ *
+ * You will also need to indicate this service directory in your test
+ * fixtures, so you will need to pass the path while compiling your
+ * test cases. Typically this is done with autotools with an added
+ * preprocessor flag specified to compile your tests such as:
+ *
+ * ```
+ * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
+ * ```
+ *
+ * Once you have a service definition file which is local to your source tree,
+ * you can proceed to set up a GTest fixture using the `GTestDBus` scaffolding.
+ *
+ * An example of a test fixture for D-Bus services can be found
+ * here:
+ * [gdbus-test-fixture.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-test-fixture.c)
+ *
+ * Note that these examples only deal with isolating the D-Bus aspect of your
+ * service. To successfully run isolated unit tests on your service you may need
+ * some additional modifications to your test case fixture. For example; if your
+ * service uses [class@Gio.Settings] and installs a schema then it is important
+ * that your test service not load the schema in the ordinary installed location
+ * (chances are that your service and schema files are not yet installed, or
+ * worse; there is an older version of the schema file sitting in the install
+ * location).
+ *
+ * Most of the time we can work around these obstacles using the
+ * environment. Since the environment is inherited by the D-Bus daemon
+ * created by `GTestDBus` and then in turn inherited by any services the
+ * D-Bus daemon activates, using the setup routine for your fixture is
+ * a practical place to help sandbox your runtime environment. For the
+ * rather typical GSettings case we can work around this by setting
+ * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
+ * in the above `fixture_setup()` routine.
+ *
+ * The GSettings schemas need to be locally pre-compiled for this to work. This
+ * can be achieved by compiling the schemas locally as a step before running
+ * test cases, an autotools setup might do the following in the directory
+ * holding schemas:
+ *
+ * ```
+ * all-am:
+ * $(GLIB_COMPILE_SCHEMAS) .
+ *
+ * CLEANFILES += gschemas.compiled
+ * ```
+ */
 export declare class TestDBus extends GObject.GObject {
+    /**
+     * Create a new #GTestDBus object.
+     * @param flags - a #GTestDBusFlags
+     */
     constructor(flags: TestDBusFlags);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
+     * won't use user's session bus.
+     *
+     * This is useful for unit tests that want to verify behaviour when no session
+     * bus is running. It is not necessary to call this if unit test already calls
+     * g_test_dbus_up() before acquiring the session bus.
+     */
     static unset(): void;
+    /**
+     * Add a path where dbus-daemon will look up .service files. This can't be
+     * called after g_test_dbus_up().
+     * @param path - path to a directory containing .service files
+     */
     addServiceDir(path: string): void;
+    /**
+     * Stop the session bus started by g_test_dbus_up().
+     *
+     * This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
+     * to be destroyed. This is done to ensure that the next unit test won't get a
+     * leaked singleton from this test.
+     */
     down(): void;
+    /**
+     * Get the address on which dbus-daemon is running. If g_test_dbus_up() has not
+     * been called yet, %NULL is returned. This can be used with
+     * g_dbus_connection_new_for_address().
+     */
     getBusAddress(): string | null;
+    /**
+     * Get the flags of the #GTestDBus object.
+     */
     getFlags(): TestDBusFlags;
+    /**
+     * Stop the session bus started by g_test_dbus_up().
+     *
+     * Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
+     * singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
+     * tests wanting to verify behaviour after the session bus has been stopped
+     * can use this function but should still call g_test_dbus_down() when done.
+     */
     stop(): void;
+    /**
+     * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
+     * call, it is safe for unit tests to start sending messages on the session bus.
+     *
+     * If this function is called from setup callback of g_test_add(),
+     * g_test_dbus_down() must be called in its teardown callback.
+     *
+     * If this function is called from unit test's main(), then g_test_dbus_down()
+     * must be called after g_test_run().
+     */
     up(): void;
     connect(signal: "notify", handler: (self: TestDBus, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gio/test-dbus.js

@@ -1,6 +1,87 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * A helper class for testing code which uses D-Bus without touching the user’s
+ * session bus.
+ *
+ * Note that `GTestDBus` modifies the user’s environment, calling
+ * [`setenv()`](man:setenv(3)). This is not thread-safe, so all `GTestDBus`
+ * calls should be completed before threads are spawned, or should have
+ * appropriate locking to ensure no access conflicts to environment variables
+ * shared between `GTestDBus` and other threads.
+ *
+ * ## Creating unit tests using `GTestDBus`
+ *
+ * Testing of D-Bus services can be tricky because normally we only ever run
+ * D-Bus services over an existing instance of the D-Bus daemon thus we
+ * usually don’t activate D-Bus services that are not yet installed into the
+ * target system. The `GTestDBus` object makes this easier for us by taking care
+ * of the lower level tasks such as running a private D-Bus daemon and looking
+ * up uninstalled services in customizable locations, typically in your source
+ * code tree.
+ *
+ * The first thing you will need is a separate service description file for the
+ * D-Bus daemon. Typically a `services` subdirectory of your `tests` directory
+ * is a good place to put this file.
+ *
+ * The service file should list your service along with an absolute path to the
+ * uninstalled service executable in your source tree. Using autotools we would
+ * achieve this by adding a file such as `my-server.service.in` in the services
+ * directory and have it processed by configure.
+ *
+ * ```
+ * [D-BUS Service]
+ * Name=org.gtk.GDBus.Examples.ObjectManager
+ * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
+ * ```
+ *
+ * You will also need to indicate this service directory in your test
+ * fixtures, so you will need to pass the path while compiling your
+ * test cases. Typically this is done with autotools with an added
+ * preprocessor flag specified to compile your tests such as:
+ *
+ * ```
+ * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
+ * ```
+ *
+ * Once you have a service definition file which is local to your source tree,
+ * you can proceed to set up a GTest fixture using the `GTestDBus` scaffolding.
+ *
+ * An example of a test fixture for D-Bus services can be found
+ * here:
+ * [gdbus-test-fixture.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-test-fixture.c)
+ *
+ * Note that these examples only deal with isolating the D-Bus aspect of your
+ * service. To successfully run isolated unit tests on your service you may need
+ * some additional modifications to your test case fixture. For example; if your
+ * service uses [class@Gio.Settings] and installs a schema then it is important
+ * that your test service not load the schema in the ordinary installed location
+ * (chances are that your service and schema files are not yet installed, or
+ * worse; there is an older version of the schema file sitting in the install
+ * location).
+ *
+ * Most of the time we can work around these obstacles using the
+ * environment. Since the environment is inherited by the D-Bus daemon
+ * created by `GTestDBus` and then in turn inherited by any services the
+ * D-Bus daemon activates, using the setup routine for your fixture is
+ * a practical place to help sandbox your runtime environment. For the
+ * rather typical GSettings case we can work around this by setting
+ * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
+ * in the above `fixture_setup()` routine.
+ *
+ * The GSettings schemas need to be locally pre-compiled for this to work. This
+ * can be achieved by compiling the schemas locally as a step before running
+ * test cases, an autotools setup might do the following in the directory
+ * holding schemas:
+ *
+ * ```
+ * all-am:
+ * $(GLIB_COMPILE_SCHEMAS) .
+ *
+ * CLEANFILES += gschemas.compiled
+ * ```
+ */
 export class TestDBus extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -14,9 +95,22 @@ export class TestDBus extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
+     * won't use user's session bus.
+     *
+     * This is useful for unit tests that want to verify behaviour when no session
+     * bus is running. It is not necessary to call this if unit test already calls
+     * g_test_dbus_up() before acquiring the session bus.
+     */
     static unset() {
         call("libgio-2.0.so.0", "g_test_dbus_unset", [], { type: "undefined" });
     }
+    /**
+     * Add a path where dbus-daemon will look up .service files. This can't be
+     * called after g_test_dbus_up().
+     * @param path - path to a directory containing .service files
+     */
     addServiceDir(path) {
         call("libgio-2.0.so.0", "g_test_dbus_add_service_dir", [
             {
@@ -29,6 +123,13 @@ export class TestDBus extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Stop the session bus started by g_test_dbus_up().
+     *
+     * This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
+     * to be destroyed. This is done to ensure that the next unit test won't get a
+     * leaked singleton from this test.
+     */
     down() {
         call("libgio-2.0.so.0", "g_test_dbus_down", [
             {
@@ -37,6 +138,11 @@ export class TestDBus extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Get the address on which dbus-daemon is running. If g_test_dbus_up() has not
+     * been called yet, %NULL is returned. This can be used with
+     * g_dbus_connection_new_for_address().
+     */
     getBusAddress() {
         return call("libgio-2.0.so.0", "g_test_dbus_get_bus_address", [
             {
@@ -45,6 +151,9 @@ export class TestDBus extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Get the flags of the #GTestDBus object.
+     */
     getFlags() {
         return call("libgio-2.0.so.0", "g_test_dbus_get_flags", [
             {
@@ -53,6 +162,14 @@ export class TestDBus extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Stop the session bus started by g_test_dbus_up().
+     *
+     * Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
+     * singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
+     * tests wanting to verify behaviour after the session bus has been stopped
+     * can use this function but should still call g_test_dbus_down() when done.
+     */
     stop() {
         call("libgio-2.0.so.0", "g_test_dbus_stop", [
             {
@@ -61,6 +178,16 @@ export class TestDBus extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
+     * call, it is safe for unit tests to start sending messages on the session bus.
+     *
+     * If this function is called from setup callback of g_test_add(),
+     * g_test_dbus_down() must be called in its teardown callback.
+     *
+     * If this function is called from unit test's main(), then g_test_dbus_down()
+     * must be called after g_test_run().
+     */
     up() {
         call("libgio-2.0.so.0", "g_test_dbus_up", [
             {

package/dist/generated/gio/themed-icon.d.ts

@@ -1,18 +1,105 @@
 import { Icon } from "./icon.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GThemedIcon` is an implementation of [iface@Gio.Icon] that supports icon
+ * themes.
+ *
+ * `GThemedIcon` contains a list of all of the icons present in an icon
+ * theme, so that icons can be looked up quickly. `GThemedIcon` does
+ * not provide actual pixmaps for icons, just the icon names.
+ * Ideally something like [method@Gtk.IconTheme.choose_icon] should be used to
+ * resolve the list of names so that fallback icons work nicely with
+ * themes that inherit other themes.
+ */
 export declare class ThemedIcon extends GObject.GObject {
+    /**
+     * Creates a new themed icon for @iconname.
+     * @param iconname - a string containing an icon name.
+     */
     constructor(iconname: string);
     constructor(...args: unknown[]);
+    /**
+     * Creates a new themed icon for @iconnames.
+     * @param iconnames - an array of strings containing icon names.
+     * @param len - the length of the `iconnames` array, or -1 if `iconnames` is
+     */
     static iconNewFromNames(iconnames: string[], len: number): ThemedIcon;
+    /**
+     * Creates a new themed icon for @iconname, and all the names
+     * that can be created by shortening `iconname` at '-' characters.
+     *
+     * In the following example, `icon1` and `icon2` are equivalent:
+     * |[<!-- language="C" -->
+     * const char *names[] = {
+     * "gnome-dev-cdrom-audio",
+     * "gnome-dev-cdrom",
+     * "gnome-dev",
+     * "gnome"
+     * };
+     *
+     * icon1 = g_themed_icon_new_from_names (names, 4);
+     * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
+     * ]|
+     * @param iconname - a string containing an icon name
+     */
     static iconNewWithDefaultFallbacks(iconname: string): ThemedIcon;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Append a name to the list of icons from within @icon.
+     *
+     * Note that doing so invalidates the hash computed by prior calls
+     * to g_icon_hash().
+     * @param iconname - name of icon to append to list of icons from within @icon.
+     */
     appendName(iconname: string): void;
+    /**
+     * Gets the names of icons from within @icon.
+     */
     getNames(): string[];
+    /**
+     * Prepend a name to the list of icons from within @icon.
+     *
+     * Note that doing so invalidates the hash computed by prior calls
+     * to g_icon_hash().
+     * @param iconname - name of icon to prepend to list of icons from within @icon.
+     */
     prependName(iconname: string): void;
+    /**
+     * Checks if two icons are equal.
+     * @param icon2 - pointer to the second #GIcon.
+     */
     equal(icon2?: Icon | null): boolean;
+    /**
+     * Gets a hash for an icon.
+     */
     hash(): number;
+    /**
+     * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
+     * back by calling g_icon_deserialize() on the returned value.
+     * As serialization will avoid using raw icon data when possible, it only
+     * makes sense to transfer the #GVariant between processes on the same machine,
+     * (as opposed to over the network), and within the same file system namespace.
+     */
     serialize(): GLib.Variant | null;
+    /**
+     * Generates a textual representation of `icon` that can be used for
+     * serialization such as when passing `icon` to a different process or
+     * saving it to persistent storage. Use g_icon_new_for_string() to
+     * get `icon` back from the returned string.
+     *
+     * The encoding of the returned string is proprietary to #GIcon except
+     * in the following two cases
+     *
+     * - If `icon` is a #GFileIcon, the returned string is a native path
+     * (such as `/path/to/my icon.png`) without escaping
+     * if the #GFile for `icon` is a native file.  If the file is not
+     * native, the returned string is the result of g_file_get_uri()
+     * (such as `sftp://path/to/my%20icon.png`).
+     *
+     * - If `icon` is a #GThemedIcon with exactly one name and no fallbacks,
+     * the encoding is simply the name (such as `network-server`).
+     */
     toString(): string | null;
     connect(signal: "notify", handler: (self: ThemedIcon, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;