@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/network-address.js

@@ -2,10 +2,37 @@ import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import { SocketAddressEnumerator } from "./socket-address-enumerator.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GNetworkAddress` provides an easy way to resolve a hostname and
+ * then attempt to connect to that host, handling the possibility of
+ * multiple IP addresses and multiple address families.
+ *
+ * The enumeration results of resolved addresses *may* be cached as long
+ * as this object is kept alive which may have unexpected results if
+ * alive for too long.
+ *
+ * See [iface@Gio.SocketConnectable] for an example of using the connectable
+ * interface.
+ */
 export class NetworkAddress extends GObject.GObject {
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a new #GSocketConnectable for connecting to the local host
+     * over a loopback connection to the given @port. This is intended for
+     * use in connecting to local services which may be running on IPv4 or
+     * IPv6.
+     *
+     * The connectable will return IPv4 and IPv6 loopback addresses,
+     * regardless of how the host resolves `localhost`. By contrast,
+     * g_network_address_new() will often only return an IPv4 address when
+     * resolving `localhost`, and an IPv6 address for `localhost6`.
+     *
+     * g_network_address_get_hostname() will always return `localhost` for
+     * a #GNetworkAddress created with this constructor.
+     * @param port - the port
+     */
     static addressNewLoopback(port) {
         const ptr = call("libgio-2.0.so.0", "g_network_address_new_loopback", [
             {
@@ -28,6 +55,31 @@ export class NetworkAddress extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Creates a new #GSocketConnectable for connecting to the given
+     * `hostname` and @port. May fail and return %NULL in case
+     * parsing `host_and_port` fails.
+     *
+     * `host_and_port` may be in any of a number of recognised formats; an IPv6
+     * address, an IPv4 address, or a domain name (in which case a DNS
+     * lookup is performed). Quoting with [] is supported for all address
+     * types. A port override may be specified in the usual way with a
+     * colon.
+     *
+     * If no port is specified in `host_and_port` then `default_port` will be
+     * used as the port number to connect to.
+     *
+     * In general, `host_and_port` is expected to be provided by the user
+     * (allowing them to give the hostname, and a port override if necessary)
+     * and `default_port` is expected to be provided by the application.
+     *
+     * (The port component of `host_and_port` can also be specified as a
+     * service name rather than as a numeric port, but this functionality
+     * is deprecated, because it depends on the contents of /etc/services,
+     * which is generally quite sparse on platforms other than Linux.)
+     * @param hostAndPort - the hostname and optionally a port
+     * @param defaultPort - the default port if not in @host_and_port
+     */
     static parse(hostAndPort, defaultPort) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_network_address_parse", [
@@ -56,6 +108,16 @@ export class NetworkAddress extends GObject.GObject {
         }
         return getObject(ptr, NetworkAddress);
     }
+    /**
+     * Creates a new #GSocketConnectable for connecting to the given
+     * @uri. May fail and return %NULL in case parsing `uri` fails.
+     *
+     * Using this rather than g_network_address_new() or
+     * g_network_address_parse() allows #GSocketClient to determine
+     * when to use application-specific proxy protocols.
+     * @param uri - the hostname and optionally a port
+     * @param defaultPort - The default port if none is found in the URI
+     */
     static parseUri(uri, defaultPort) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_network_address_parse_uri", [
@@ -84,6 +146,10 @@ export class NetworkAddress extends GObject.GObject {
         }
         return getObject(ptr, NetworkAddress);
     }
+    /**
+     * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded,
+     * depending on what `addr` was created with.
+     */
     getHostname() {
         return call("libgio-2.0.so.0", "g_network_address_get_hostname", [
             {
@@ -92,6 +158,9 @@ export class NetworkAddress extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets @addr's port number
+     */
     getPort() {
         return call("libgio-2.0.so.0", "g_network_address_get_port", [
             {
@@ -100,6 +169,9 @@ export class NetworkAddress extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Gets @addr's scheme
+     */
     getScheme() {
         return call("libgio-2.0.so.0", "g_network_address_get_scheme", [
             {
@@ -108,6 +180,9 @@ export class NetworkAddress extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Creates a #GSocketAddressEnumerator for @connectable.
+     */
     enumerate() {
         const ptr = call("libgio-2.0.so.0", "g_socket_connectable_enumerate", [
             {
@@ -117,6 +192,15 @@ export class NetworkAddress extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, SocketAddressEnumerator);
     }
+    /**
+     * Creates a #GSocketAddressEnumerator for `connectable` that will
+     * return a #GProxyAddress for each of its addresses that you must connect
+     * to via a proxy.
+     *
+     * If `connectable` does not implement
+     * g_socket_connectable_proxy_enumerate(), this will fall back to
+     * calling g_socket_connectable_enumerate().
+     */
     proxyEnumerate() {
         const ptr = call("libgio-2.0.so.0", "g_socket_connectable_proxy_enumerate", [
             {
@@ -126,6 +210,15 @@ export class NetworkAddress extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, SocketAddressEnumerator);
     }
+    /**
+     * Format a #GSocketConnectable as a string. This is a human-readable format for
+     * use in debugging output, and is not a stable serialization format. It is not
+     * suitable for use in user interfaces as it exposes too much information for a
+     * user.
+     *
+     * If the #GSocketConnectable implementation does not support string formatting,
+     * the implementation’s type name will be returned as a fallback.
+     */
     toString() {
         return call("libgio-2.0.so.0", "g_socket_connectable_to_string", [
             {

package/dist/generated/gio/network-monitor.d.ts

@@ -2,14 +2,93 @@ import { NetworkConnectivity } from "./enums.js";
 import { AsyncResult } from "./async-result.js";
 import { Cancellable } from "./cancellable.js";
 import { SocketConnectable } from "./socket-connectable.js";
+/**
+ * `GNetworkMonitor` provides an easy-to-use cross-platform API
+ * for monitoring network connectivity. On Linux, the available
+ * implementations are based on the kernel's netlink interface and
+ * on NetworkManager.
+ *
+ * There is also an implementation for use inside Flatpak sandboxes.
+ */
 export declare class NetworkMonitor {
     ptr: unknown;
     protected constructor(ptr: unknown);
     static fromPtr(ptr: unknown): NetworkMonitor;
+    /**
+     * Attempts to determine whether or not the host pointed to by
+     * `connectable` can be reached, without actually trying to connect to
+     * it.
+     *
+     * This may return %TRUE even when #GNetworkMonitor:network-available
+     * is %FALSE, if, for example, `monitor` can determine that
+     * `connectable` refers to a host on a local network.
+     *
+     * If `monitor` believes that an attempt to connect to `connectable` will succeed, it will return %TRUE. Otherwise, it will return
+     * %FALSE and set `error` to an appropriate error (such as
+     * %G_IO_ERROR_HOST_UNREACHABLE).
+     *
+     * Note that although this does not attempt to connect to
+     * @connectable, it may still block for a brief period of time (eg,
+     * trying to do multicast DNS on the local network), so if you do not
+     * want to block, you should use g_network_monitor_can_reach_async().
+     * @param connectable - a #GSocketConnectable
+     * @param cancellable - a #GCancellable, or %NULL
+     */
     canReach(connectable: SocketConnectable, cancellable?: Cancellable | null): boolean;
+    /**
+     * Asynchronously attempts to determine whether or not the host
+     * pointed to by `connectable` can be reached, without actually
+     * trying to connect to it.
+     *
+     * For more details, see g_network_monitor_can_reach().
+     *
+     * When the operation is finished, `callback` will be called.
+     * You can then call g_network_monitor_can_reach_finish()
+     * to get the result of the operation.
+     * @param connectable - a #GSocketConnectable
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     canReachAsync(connectable: SocketConnectable, cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finishes an async network connectivity test.
+     * See g_network_monitor_can_reach_async().
+     * @param result - a #GAsyncResult
+     */
     canReachFinish(result: AsyncResult): boolean;
+    /**
+     * Gets a more detailed networking state than
+     * g_network_monitor_get_network_available().
+     *
+     * If #GNetworkMonitor:network-available is %FALSE, then the
+     * connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL.
+     *
+     * If #GNetworkMonitor:network-available is %TRUE, then the
+     * connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there
+     * is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if
+     * the host has a default route, but appears to be unable to actually
+     * reach the full Internet), or %G_NETWORK_CONNECTIVITY_PORTAL (if the
+     * host is trapped behind a "captive portal" that requires some sort
+     * of login or acknowledgement before allowing full Internet access).
+     *
+     * Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and
+     * %G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are
+     * reachable but others are not. In this case, applications can
+     * attempt to connect to remote servers, but should gracefully fall
+     * back to their "offline" behavior if the connection attempt fails.
+     */
     getConnectivity(): NetworkConnectivity;
+    /**
+     * Checks if the network is available. "Available" here means that the
+     * system has a default route available for at least one of IPv4 or
+     * IPv6. It does not necessarily imply that the public Internet is
+     * reachable. See #GNetworkMonitor:network-available for more details.
+     */
     getNetworkAvailable(): boolean;
+    /**
+     * Checks if the network is metered.
+     * See #GNetworkMonitor:network-metered for more details.
+     */
     getNetworkMetered(): boolean;
 }

package/dist/generated/gio/network-monitor.js

@@ -1,5 +1,13 @@
 import { call } from "@gtkx/native";
 import { NativeError } from "@gtkx/ffi";
+/**
+ * `GNetworkMonitor` provides an easy-to-use cross-platform API
+ * for monitoring network connectivity. On Linux, the available
+ * implementations are based on the kernel's netlink interface and
+ * on NetworkManager.
+ *
+ * There is also an implementation for use inside Flatpak sandboxes.
+ */
 export class NetworkMonitor {
     ptr;
     constructor(ptr) {
@@ -8,6 +16,26 @@ export class NetworkMonitor {
     static fromPtr(ptr) {
         return new NetworkMonitor(ptr);
     }
+    /**
+     * Attempts to determine whether or not the host pointed to by
+     * `connectable` can be reached, without actually trying to connect to
+     * it.
+     *
+     * This may return %TRUE even when #GNetworkMonitor:network-available
+     * is %FALSE, if, for example, `monitor` can determine that
+     * `connectable` refers to a host on a local network.
+     *
+     * If `monitor` believes that an attempt to connect to `connectable` will succeed, it will return %TRUE. Otherwise, it will return
+     * %FALSE and set `error` to an appropriate error (such as
+     * %G_IO_ERROR_HOST_UNREACHABLE).
+     *
+     * Note that although this does not attempt to connect to
+     * @connectable, it may still block for a brief period of time (eg,
+     * trying to do multicast DNS on the local network), so if you do not
+     * want to block, you should use g_network_monitor_can_reach_async().
+     * @param connectable - a #GSocketConnectable
+     * @param cancellable - a #GCancellable, or %NULL
+     */
     canReach(connectable, cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_network_monitor_can_reach", [
@@ -41,6 +69,21 @@ export class NetworkMonitor {
         }
         return result;
     }
+    /**
+     * Asynchronously attempts to determine whether or not the host
+     * pointed to by `connectable` can be reached, without actually
+     * trying to connect to it.
+     *
+     * For more details, see g_network_monitor_can_reach().
+     *
+     * When the operation is finished, `callback` will be called.
+     * You can then call g_network_monitor_can_reach_finish()
+     * to get the result of the operation.
+     * @param connectable - a #GSocketConnectable
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     canReachAsync(connectable, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_network_monitor_can_reach_async", [
             {
@@ -68,6 +111,11 @@ export class NetworkMonitor {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes an async network connectivity test.
+     * See g_network_monitor_can_reach_async().
+     * @param result - a #GAsyncResult
+     */
     canReachFinish(result) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_network_monitor_can_reach_finish", [
@@ -96,6 +144,27 @@ export class NetworkMonitor {
         }
         return _result;
     }
+    /**
+     * Gets a more detailed networking state than
+     * g_network_monitor_get_network_available().
+     *
+     * If #GNetworkMonitor:network-available is %FALSE, then the
+     * connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL.
+     *
+     * If #GNetworkMonitor:network-available is %TRUE, then the
+     * connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there
+     * is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if
+     * the host has a default route, but appears to be unable to actually
+     * reach the full Internet), or %G_NETWORK_CONNECTIVITY_PORTAL (if the
+     * host is trapped behind a "captive portal" that requires some sort
+     * of login or acknowledgement before allowing full Internet access).
+     *
+     * Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and
+     * %G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are
+     * reachable but others are not. In this case, applications can
+     * attempt to connect to remote servers, but should gracefully fall
+     * back to their "offline" behavior if the connection attempt fails.
+     */
     getConnectivity() {
         return call("libgio-2.0.so.0", "g_network_monitor_get_connectivity", [
             {
@@ -104,6 +173,12 @@ export class NetworkMonitor {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Checks if the network is available. "Available" here means that the
+     * system has a default route available for at least one of IPv4 or
+     * IPv6. It does not necessarily imply that the public Internet is
+     * reachable. See #GNetworkMonitor:network-available for more details.
+     */
     getNetworkAvailable() {
         return call("libgio-2.0.so.0", "g_network_monitor_get_network_available", [
             {
@@ -112,6 +187,10 @@ export class NetworkMonitor {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if the network is metered.
+     * See #GNetworkMonitor:network-metered for more details.
+     */
     getNetworkMetered() {
         return call("libgio-2.0.so.0", "g_network_monitor_get_network_metered", [
             {

package/dist/generated/gio/network-service.d.ts

@@ -1,16 +1,75 @@
 import { SocketAddressEnumerator } from "./socket-address-enumerator.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * Like [class@Gio.NetworkAddress] does with hostnames, `GNetworkService`
+ * provides an easy way to resolve a SRV record, and then attempt to
+ * connect to one of the hosts that implements that service, handling
+ * service priority/weighting, multiple IP addresses, and multiple
+ * address families.
+ *
+ * See [struct@Gio.SrvTarget] for more information about SRV records, and see
+ * [iface@Gio.SocketConnectable] for an example of using the connectable
+ * interface.
+ */
 export declare class NetworkService extends GObject.GObject {
+    /**
+     * Creates a new #GNetworkService representing the given @service,
+     * @protocol, and @domain. This will initially be unresolved; use the
+     * #GSocketConnectable interface to resolve it.
+     * @param service - the service type to look up (eg, "ldap")
+     * @param protocol - the networking protocol to use for `service` (eg, "tcp")
+     * @param domain - the DNS domain to look up the service in
+     */
     constructor(service: string, protocol: string, domain: string);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Gets the domain that `srv` serves. This might be either UTF-8 or
+     * ASCII-encoded, depending on what `srv` was created with.
+     */
     getDomain(): string;
+    /**
+     * Gets @srv's protocol name (eg, "tcp").
+     */
     getProtocol(): string;
+    /**
+     * Gets the URI scheme used to resolve proxies. By default, the service name
+     * is used as scheme.
+     */
     getScheme(): string;
+    /**
+     * Gets @srv's service name (eg, "ldap").
+     */
     getService(): string;
+    /**
+     * Set's the URI scheme used to resolve proxies. By default, the service name
+     * is used as scheme.
+     * @param scheme - a URI scheme
+     */
     setScheme(scheme: string): void;
+    /**
+     * Creates a #GSocketAddressEnumerator for @connectable.
+     */
     enumerate(): SocketAddressEnumerator;
+    /**
+     * Creates a #GSocketAddressEnumerator for `connectable` that will
+     * return a #GProxyAddress for each of its addresses that you must connect
+     * to via a proxy.
+     *
+     * If `connectable` does not implement
+     * g_socket_connectable_proxy_enumerate(), this will fall back to
+     * calling g_socket_connectable_enumerate().
+     */
     proxyEnumerate(): SocketAddressEnumerator;
+    /**
+     * Format a #GSocketConnectable as a string. This is a human-readable format for
+     * use in debugging output, and is not a stable serialization format. It is not
+     * suitable for use in user interfaces as it exposes too much information for a
+     * user.
+     *
+     * If the #GSocketConnectable implementation does not support string formatting,
+     * the implementation’s type name will be returned as a fallback.
+     */
     toString(): string;
     connect(signal: "notify", handler: (self: NetworkService, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gio/network-service.js

@@ -2,6 +2,17 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { SocketAddressEnumerator } from "./socket-address-enumerator.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * Like [class@Gio.NetworkAddress] does with hostnames, `GNetworkService`
+ * provides an easy way to resolve a SRV record, and then attempt to
+ * connect to one of the hosts that implements that service, handling
+ * service priority/weighting, multiple IP addresses, and multiple
+ * address families.
+ *
+ * See [struct@Gio.SrvTarget] for more information about SRV records, and see
+ * [iface@Gio.SocketConnectable] for an example of using the connectable
+ * interface.
+ */
 export class NetworkService extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -23,6 +34,10 @@ export class NetworkService extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets the domain that `srv` serves. This might be either UTF-8 or
+     * ASCII-encoded, depending on what `srv` was created with.
+     */
     getDomain() {
         return call("libgio-2.0.so.0", "g_network_service_get_domain", [
             {
@@ -31,6 +46,9 @@ export class NetworkService extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets @srv's protocol name (eg, "tcp").
+     */
     getProtocol() {
         return call("libgio-2.0.so.0", "g_network_service_get_protocol", [
             {
@@ -39,6 +57,10 @@ export class NetworkService extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the URI scheme used to resolve proxies. By default, the service name
+     * is used as scheme.
+     */
     getScheme() {
         return call("libgio-2.0.so.0", "g_network_service_get_scheme", [
             {
@@ -47,6 +69,9 @@ export class NetworkService extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets @srv's service name (eg, "ldap").
+     */
     getService() {
         return call("libgio-2.0.so.0", "g_network_service_get_service", [
             {
@@ -55,6 +80,11 @@ export class NetworkService extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Set's the URI scheme used to resolve proxies. By default, the service name
+     * is used as scheme.
+     * @param scheme - a URI scheme
+     */
     setScheme(scheme) {
         call("libgio-2.0.so.0", "g_network_service_set_scheme", [
             {
@@ -67,6 +97,9 @@ export class NetworkService extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Creates a #GSocketAddressEnumerator for @connectable.
+     */
     enumerate() {
         const ptr = call("libgio-2.0.so.0", "g_socket_connectable_enumerate", [
             {
@@ -76,6 +109,15 @@ export class NetworkService extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, SocketAddressEnumerator);
     }
+    /**
+     * Creates a #GSocketAddressEnumerator for `connectable` that will
+     * return a #GProxyAddress for each of its addresses that you must connect
+     * to via a proxy.
+     *
+     * If `connectable` does not implement
+     * g_socket_connectable_proxy_enumerate(), this will fall back to
+     * calling g_socket_connectable_enumerate().
+     */
     proxyEnumerate() {
         const ptr = call("libgio-2.0.so.0", "g_socket_connectable_proxy_enumerate", [
             {
@@ -85,6 +127,15 @@ export class NetworkService extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, SocketAddressEnumerator);
     }
+    /**
+     * Format a #GSocketConnectable as a string. This is a human-readable format for
+     * use in debugging output, and is not a stable serialization format. It is not
+     * suitable for use in user interfaces as it exposes too much information for a
+     * user.
+     *
+     * If the #GSocketConnectable implementation does not support string formatting,
+     * the implementation’s type name will be returned as a fallback.
+     */
     toString() {
         return call("libgio-2.0.so.0", "g_socket_connectable_to_string", [
             {