@gtkx/ffi 0.1.45 → 0.1.47

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

@@ -1,10 +1,74 @@
 import * as GLib from "../glib/index.js";
+/**
+ * `GIcon` is a very minimal interface for icons. It provides functions
+ * for checking the equality of two icons, hashing of icons and
+ * serializing an icon to and from strings.
+ *
+ * `GIcon` does not provide the actual pixmap for the icon as this is out
+ * of GIO's scope, however implementations of `GIcon` may contain the name
+ * of an icon (see [class@Gio.ThemedIcon]), or the path to an icon
+ * (see [iface@Gio.LoadableIcon]).
+ *
+ * To obtain a hash of a `GIcon`, see [method@Gio.Icon.hash].
+ *
+ * To check if two `GIcon`s are equal, see [method@Gio.Icon.equal].
+ *
+ * For serializing a `GIcon`, use [method@Gio.Icon.serialize] and
+ * [func@Gio.Icon.deserialize].
+ *
+ * If you want to consume `GIcon` (for example, in a toolkit) you must
+ * be prepared to handle at least the three following cases:
+ * [iface@Gio.LoadableIcon], [class@Gio.ThemedIcon] and [class@Gio.EmblemedIcon].
+ * It may also make sense to have fast-paths for other cases (like handling
+ * `GdkPixbuf` directly,
+ * for example) but all compliant `GIcon` implementations outside of GIO must
+ * implement [iface@Gio.LoadableIcon].
+ *
+ * If your application or library provides one or more `GIcon`
+ * implementations you need to ensure that your new implementation also
+ * implements [iface@Gio.LoadableIcon].  Additionally, you must provide an
+ * implementation of [method@Gio.Icon.serialize] that gives a result that is
+ * understood by [func@Gio.Icon.deserialize], yielding one of the built-in
+ * icon types.
+ */
 export declare class Icon {
     ptr: unknown;
     protected constructor(ptr: unknown);
     static fromPtr(ptr: unknown): Icon;
+    /**
+     * 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;
 }

package/dist/generated/gio/icon.js

@@ -1,6 +1,38 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
+/**
+ * `GIcon` is a very minimal interface for icons. It provides functions
+ * for checking the equality of two icons, hashing of icons and
+ * serializing an icon to and from strings.
+ *
+ * `GIcon` does not provide the actual pixmap for the icon as this is out
+ * of GIO's scope, however implementations of `GIcon` may contain the name
+ * of an icon (see [class@Gio.ThemedIcon]), or the path to an icon
+ * (see [iface@Gio.LoadableIcon]).
+ *
+ * To obtain a hash of a `GIcon`, see [method@Gio.Icon.hash].
+ *
+ * To check if two `GIcon`s are equal, see [method@Gio.Icon.equal].
+ *
+ * For serializing a `GIcon`, use [method@Gio.Icon.serialize] and
+ * [func@Gio.Icon.deserialize].
+ *
+ * If you want to consume `GIcon` (for example, in a toolkit) you must
+ * be prepared to handle at least the three following cases:
+ * [iface@Gio.LoadableIcon], [class@Gio.ThemedIcon] and [class@Gio.EmblemedIcon].
+ * It may also make sense to have fast-paths for other cases (like handling
+ * `GdkPixbuf` directly,
+ * for example) but all compliant `GIcon` implementations outside of GIO must
+ * implement [iface@Gio.LoadableIcon].
+ *
+ * If your application or library provides one or more `GIcon`
+ * implementations you need to ensure that your new implementation also
+ * implements [iface@Gio.LoadableIcon].  Additionally, you must provide an
+ * implementation of [method@Gio.Icon.serialize] that gives a result that is
+ * understood by [func@Gio.Icon.deserialize], yielding one of the built-in
+ * icon types.
+ */
 export class Icon {
     ptr;
     constructor(ptr) {
@@ -9,6 +41,10 @@ export class Icon {
     static fromPtr(ptr) {
         return new Icon(ptr);
     }
+    /**
+     * Checks if two icons are equal.
+     * @param icon2 - pointer to the second #GIcon.
+     */
     equal(icon2) {
         return call("libgio-2.0.so.0", "g_icon_equal", [
             {
@@ -22,6 +58,9 @@ export class Icon {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets a hash for an icon.
+     */
     hash() {
         return call("libgio-2.0.so.0", "g_icon_hash", [
             {
@@ -30,6 +69,13 @@ export class Icon {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * 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() {
         const ptr = call("libgio-2.0.so.0", "g_icon_serialize", [
             {
@@ -46,6 +92,24 @@ export class Icon {
             return null;
         return getObject(ptr, GLib.Variant);
     }
+    /**
+     * 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() {
         return call("libgio-2.0.so.0", "g_icon_to_string", [
             {

package/dist/generated/gio/inet-address-mask.d.ts

@@ -2,17 +2,97 @@ import { SocketFamily } from "./enums.js";
 import { Cancellable } from "./cancellable.js";
 import { InetAddress } from "./inet-address.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GInetAddressMask` represents a range of IPv4 or IPv6 addresses
+ * described by a base address and a length indicating how many bits
+ * of the base address are relevant for matching purposes. These are
+ * often given in string form. For example, `10.0.0.0/8`, or `fe80::/10`.
+ */
 export declare class InetAddressMask extends GObject.GObject {
+    /**
+     * Creates a new #GInetAddressMask representing all addresses whose
+     * first `length` bits match @addr.
+     * @param addr - a #GInetAddress
+     * @param length - number of bits of `addr` to use
+     */
     constructor(addr: InetAddress, length: number);
     constructor(...args: unknown[]);
+    /**
+     * Parses `mask_string` as an IP address and (optional) length, and
+     * creates a new #GInetAddressMask. The length, if present, is
+     * delimited by a "/". If it is not present, then the length is
+     * assumed to be the full length of the address.
+     * @param maskString - an IP address or address/length string
+     */
     static addressMaskNewFromString(maskString: string): InetAddressMask;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Tests if `mask` and `mask2` are the same mask.
+     * @param mask2 - another #GInetAddressMask
+     */
     equal(mask2: InetAddressMask): boolean;
+    /**
+     * Gets @mask's base address
+     */
     getAddress(): InetAddress;
+    /**
+     * Gets the #GSocketFamily of @mask's address
+     */
     getFamily(): SocketFamily;
+    /**
+     * Gets @mask's length
+     */
     getLength(): number;
+    /**
+     * Tests if `address` falls within the range described by @mask.
+     * @param address - a #GInetAddress
+     */
     matches(address: InetAddress): boolean;
+    /**
+     * Converts `mask` back to its corresponding string form.
+     */
     toString(): string;
+    /**
+     * Initializes the object implementing the interface.
+     *
+     * This method is intended for language bindings. If writing in C,
+     * g_initable_new() should typically be used instead.
+     *
+     * The object must be initialized before any real use after initial
+     * construction, either with this function or g_async_initable_init_async().
+     *
+     * Implementations may also support cancellation. If `cancellable` is not %NULL,
+     * then initialization can be cancelled by triggering the cancellable object
+     * from another thread. If the operation was cancelled, the error
+     * %G_IO_ERROR_CANCELLED will be returned. If `cancellable` is not %NULL and
+     * the object doesn't support cancellable initialization the error
+     * %G_IO_ERROR_NOT_SUPPORTED will be returned.
+     *
+     * If the object is not initialized, or initialization returns with an
+     * error, then all operations on the object except g_object_ref() and
+     * g_object_unref() are considered to be invalid, and have undefined
+     * behaviour. See the [description][iface@Gio.Initable#description] for more details.
+     *
+     * Callers should not assume that a class which implements #GInitable can be
+     * initialized multiple times, unless the class explicitly documents itself as
+     * supporting this. Generally, a class’ implementation of init() can assume
+     * (and assert) that it will only be called once. Previously, this documentation
+     * recommended all #GInitable implementations should be idempotent; that
+     * recommendation was relaxed in GLib 2.54.
+     *
+     * If a class explicitly supports being initialized multiple times, it is
+     * recommended that the method is idempotent: multiple calls with the same
+     * arguments should return the same results. Only the first call initializes
+     * the object; further calls return the result of the first call.
+     *
+     * One reason why a class might need to support idempotent initialization is if
+     * it is designed to be used via the singleton pattern, with a
+     * #GObjectClass.constructor that sometimes returns an existing instance.
+     * In this pattern, a caller would expect to be able to call g_initable_init()
+     * on the result of g_object_new(), regardless of whether it is in fact a new
+     * instance.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     init(cancellable?: Cancellable | null): boolean;
     connect(signal: "notify", handler: (self: InetAddressMask, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gio/inet-address-mask.js

@@ -2,10 +2,23 @@ import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import { InetAddress } from "./inet-address.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GInetAddressMask` represents a range of IPv4 or IPv6 addresses
+ * described by a base address and a length indicating how many bits
+ * of the base address are relevant for matching purposes. These are
+ * often given in string form. For example, `10.0.0.0/8`, or `fe80::/10`.
+ */
 export class InetAddressMask extends GObject.GObject {
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Parses `mask_string` as an IP address and (optional) length, and
+     * creates a new #GInetAddressMask. The length, if present, is
+     * delimited by a "/". If it is not present, then the length is
+     * assumed to be the full length of the address.
+     * @param maskString - an IP address or address/length string
+     */
     static addressMaskNewFromString(maskString) {
         const ptr = call("libgio-2.0.so.0", "g_inet_address_mask_new_from_string", [
             {
@@ -28,6 +41,10 @@ export class InetAddressMask extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Tests if `mask` and `mask2` are the same mask.
+     * @param mask2 - another #GInetAddressMask
+     */
     equal(mask2) {
         return call("libgio-2.0.so.0", "g_inet_address_mask_equal", [
             {
@@ -40,6 +57,9 @@ export class InetAddressMask extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets @mask's base address
+     */
     getAddress() {
         const ptr = call("libgio-2.0.so.0", "g_inet_address_mask_get_address", [
             {
@@ -49,6 +69,9 @@ export class InetAddressMask extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, InetAddress);
     }
+    /**
+     * Gets the #GSocketFamily of @mask's address
+     */
     getFamily() {
         return call("libgio-2.0.so.0", "g_inet_address_mask_get_family", [
             {
@@ -57,6 +80,9 @@ export class InetAddressMask extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets @mask's length
+     */
     getLength() {
         return call("libgio-2.0.so.0", "g_inet_address_mask_get_length", [
             {
@@ -65,6 +91,10 @@ export class InetAddressMask extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Tests if `address` falls within the range described by @mask.
+     * @param address - a #GInetAddress
+     */
     matches(address) {
         return call("libgio-2.0.so.0", "g_inet_address_mask_matches", [
             {
@@ -77,6 +107,9 @@ export class InetAddressMask extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Converts `mask` back to its corresponding string form.
+     */
     toString() {
         return call("libgio-2.0.so.0", "g_inet_address_mask_to_string", [
             {
@@ -85,6 +118,47 @@ export class InetAddressMask extends GObject.GObject {
             },
         ], { type: "string" });
     }
+    /**
+     * Initializes the object implementing the interface.
+     *
+     * This method is intended for language bindings. If writing in C,
+     * g_initable_new() should typically be used instead.
+     *
+     * The object must be initialized before any real use after initial
+     * construction, either with this function or g_async_initable_init_async().
+     *
+     * Implementations may also support cancellation. If `cancellable` is not %NULL,
+     * then initialization can be cancelled by triggering the cancellable object
+     * from another thread. If the operation was cancelled, the error
+     * %G_IO_ERROR_CANCELLED will be returned. If `cancellable` is not %NULL and
+     * the object doesn't support cancellable initialization the error
+     * %G_IO_ERROR_NOT_SUPPORTED will be returned.
+     *
+     * If the object is not initialized, or initialization returns with an
+     * error, then all operations on the object except g_object_ref() and
+     * g_object_unref() are considered to be invalid, and have undefined
+     * behaviour. See the [description][iface@Gio.Initable#description] for more details.
+     *
+     * Callers should not assume that a class which implements #GInitable can be
+     * initialized multiple times, unless the class explicitly documents itself as
+     * supporting this. Generally, a class’ implementation of init() can assume
+     * (and assert) that it will only be called once. Previously, this documentation
+     * recommended all #GInitable implementations should be idempotent; that
+     * recommendation was relaxed in GLib 2.54.
+     *
+     * If a class explicitly supports being initialized multiple times, it is
+     * recommended that the method is idempotent: multiple calls with the same
+     * arguments should return the same results. Only the first call initializes
+     * the object; further calls return the result of the first call.
+     *
+     * One reason why a class might need to support idempotent initialization is if
+     * it is designed to be used via the singleton pattern, with a
+     * #GObjectClass.constructor that sometimes returns an existing instance.
+     * In this pattern, a caller would expect to be able to call g_initable_init()
+     * on the result of g_object_new(), regardless of whether it is in fact a new
+     * instance.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     init(cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_initable_init", [

package/dist/generated/gio/inet-address.d.ts

@@ -1,28 +1,128 @@
 import { SocketFamily } from "./enums.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GInetAddress` represents an IPv4 or IPv6 internet address. Use
+ * [method@Gio.Resolver.lookup_by_name] or
+ * [method@Gio.Resolver.lookup_by_name_async] to look up the `GInetAddress` for
+ * a hostname. Use [method@Gio.Resolver.lookup_by_address] or
+ * [method@Gio.Resolver.lookup_by_address_async] to look up the hostname for a
+ * `GInetAddress`.
+ *
+ * To actually connect to a remote host, you will need a
+ * [class@Gio.InetSocketAddress] (which includes a `GInetAddress` as well as a
+ * port number).
+ */
 export declare class InetAddress extends GObject.GObject {
+    /**
+     * Creates a #GInetAddress for the "any" address (unassigned/"don't
+     * care") for @family.
+     * @param family - the address family
+     */
     constructor(family: SocketFamily);
     constructor(...args: unknown[]);
+    /**
+     * Creates a new #GInetAddress from the given `family` and @bytes.
+     * `bytes` should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for
+     * %G_SOCKET_FAMILY_IPV6.
+     * @param bytes - raw address data
+     * @param family - the address family of @bytes
+     */
     static addressNewFromBytes(bytes: number[], family: SocketFamily): InetAddress;
+    /**
+     * Creates a new [class@Gio.InetAddress] from the given @family, `bytes` and @scope_id.
+     *
+     * `bytes` must be 4 bytes for [enum@Gio.SocketFamily.IPV4] and 16 bytes for
+     * [enum@Gio.SocketFamily.IPV6].
+     * @param bytes - raw address data
+     * @param family - the address family of @bytes
+     * @param scopeId - the scope-id of the address
+     */
     static addressNewFromBytesWithIpv6Info(bytes: number[], family: SocketFamily, flowinfo: number, scopeId: number): InetAddress;
+    /**
+     * Parses `string` as an IP address and creates a new #GInetAddress.
+     *
+     * If `address` is an IPv6 address, it can also contain a scope ID
+     * (separated from the address by a `%`). Note that currently this
+     * behavior is platform specific. This may change in a future release.
+     * @param string - a string representation of an IP address
+     */
     static addressNewFromString(string: string): InetAddress;
+    /**
+     * Creates a #GInetAddress for the loopback address for @family.
+     * @param family - the address family
+     */
     static addressNewLoopback(family: SocketFamily): InetAddress;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Checks if two #GInetAddress instances are equal, e.g. the same address.
+     * @param otherAddress - Another #GInetAddress.
+     */
     equal(otherAddress: InetAddress): boolean;
+    /**
+     * Gets @address's family
+     */
     getFamily(): SocketFamily;
+    /**
+     * Gets the value of [property@Gio.InetAddress:flowinfo].
+     */
     getFlowinfo(): number;
+    /**
+     * Tests whether `address` is the "any" address for its family.
+     */
     getIsAny(): boolean;
+    /**
+     * Tests whether `address` is a link-local address (that is, if it
+     * identifies a host on a local network that is not connected to the
+     * Internet).
+     */
     getIsLinkLocal(): boolean;
+    /**
+     * Tests whether `address` is the loopback address for its family.
+     */
     getIsLoopback(): boolean;
+    /**
+     * Tests whether `address` is a global multicast address.
+     */
     getIsMcGlobal(): boolean;
+    /**
+     * Tests whether `address` is a link-local multicast address.
+     */
     getIsMcLinkLocal(): boolean;
+    /**
+     * Tests whether `address` is a node-local multicast address.
+     */
     getIsMcNodeLocal(): boolean;
+    /**
+     * Tests whether `address` is an organization-local multicast address.
+     */
     getIsMcOrgLocal(): boolean;
+    /**
+     * Tests whether `address` is a site-local multicast address.
+     */
     getIsMcSiteLocal(): boolean;
+    /**
+     * Tests whether `address` is a multicast address.
+     */
     getIsMulticast(): boolean;
+    /**
+     * Tests whether `address` is a site-local address such as 10.0.0.1
+     * (that is, the address identifies a host on a local network that can
+     * not be reached directly from the Internet, but which may have
+     * outgoing Internet connectivity via a NAT or firewall).
+     */
     getIsSiteLocal(): boolean;
+    /**
+     * Gets the size of the native raw binary address for @address. This
+     * is the size of the data that you get from g_inet_address_to_bytes().
+     */
     getNativeSize(): number;
+    /**
+     * Gets the value of [property@Gio.InetAddress:scope-id].
+     */
     getScopeId(): number;
+    /**
+     * Converts `address` to string form.
+     */
     toString(): string;
     connect(signal: "notify", handler: (self: InetAddress, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;