@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/socket-connectable.js

@@ -1,6 +1,65 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { SocketAddressEnumerator } from "./socket-address-enumerator.js";
+/**
+ * Objects that describe one or more potential socket endpoints
+ * implement `GSocketConnectable`. Callers can then use
+ * [method@Gio.SocketConnectable.enumerate] to get a
+ * [class@Gio.SocketAddressEnumerator] to try out each socket address in turn
+ * until one succeeds, as shown in the sample code below.
+ *
+ * ```c
+ * MyConnectionType *
+ * connect_to_host (const char    *hostname,
+ * guint16        port,
+ * GCancellable  *cancellable,
+ * GError       **error)
+ * {
+ * MyConnection *conn = NULL;
+ * GSocketConnectable *addr;
+ * GSocketAddressEnumerator *enumerator;
+ * GSocketAddress *sockaddr;
+ * GError *conn_error = NULL;
+ *
+ * addr = g_network_address_new (hostname, port);
+ * enumerator = g_socket_connectable_enumerate (addr);
+ * g_object_unref (addr);
+ *
+ * // Try each sockaddr until we succeed. Record the first connection error,
+ * // but not any further ones (since they'll probably be basically the same
+ * // as the first).
+ * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
+ * {
+ * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
+ * g_object_unref (sockaddr);
+ * }
+ * g_object_unref (enumerator);
+ *
+ * if (conn)
+ * {
+ * if (conn_error)
+ * {
+ * // We couldn't connect to the first address, but we succeeded
+ * // in connecting to a later address.
+ * g_error_free (conn_error);
+ * }
+ * return conn;
+ * }
+ * else if (error)
+ * {
+ * /// Either initial lookup failed, or else the caller cancelled us.
+ * if (conn_error)
+ * g_error_free (conn_error);
+ * return NULL;
+ * }
+ * else
+ * {
+ * g_error_propagate (error, conn_error);
+ * return NULL;
+ * }
+ * }
+ * ```
+ */
 export class SocketConnectable {
     ptr;
     constructor(ptr) {
@@ -9,6 +68,9 @@ export class SocketConnectable {
     static fromPtr(ptr) {
         return new SocketConnectable(ptr);
     }
+    /**
+     * Creates a #GSocketAddressEnumerator for @connectable.
+     */
     enumerate() {
         const ptr = call("libgio-2.0.so.0", "g_socket_connectable_enumerate", [
             {
@@ -18,6 +80,15 @@ export class SocketConnectable {
         ], { 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", [
             {
@@ -27,6 +98,15 @@ export class SocketConnectable {
         ], { 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/socket-connection.d.ts

@@ -4,16 +4,100 @@ import { Cancellable } from "./cancellable.js";
 import { Socket } from "./socket.js";
 import { SocketAddress } from "./socket-address.js";
 import { IOStream } from "./iostream.js";
+/**
+ * `GSocketConnection` is a [class@Gio.IOStream] for a connected socket. They
+ * can be created either by [class@Gio.SocketClient] when connecting to a host,
+ * or by [class@Gio.SocketListener] when accepting a new client.
+ *
+ * The type of the `GSocketConnection` object returned from these calls
+ * depends on the type of the underlying socket that is in use. For
+ * instance, for a TCP/IP connection it will be a [class@Gio.TcpConnection].
+ *
+ * Choosing what type of object to construct is done with the socket
+ * connection factory, and it is possible for third parties to register
+ * custom socket connection types for specific combination of socket
+ * family/type/protocol using [func@Gio.SocketConnection.factory_register_type].
+ *
+ * To close a `GSocketConnection`, use [method@Gio.IOStream.close]. Closing both
+ * substreams of the [class@Gio.IOStream] separately will not close the
+ * underlying [class@Gio.Socket].
+ */
 export declare class SocketConnection extends IOStream {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Looks up the #GType to be used when creating socket connections on
+     * sockets with the specified @family, `type` and @protocol_id.
+     *
+     * If no type is registered, the #GSocketConnection base type is returned.
+     * @param family - a #GSocketFamily
+     * @param type - a #GSocketType
+     * @param protocolId - a protocol id
+     */
     static factoryLookupType(family: SocketFamily, type: SocketType, protocolId: number): number;
+    /**
+     * Looks up the #GType to be used when creating socket connections on
+     * sockets with the specified @family, `type` and @protocol.
+     *
+     * If no type is registered, the #GSocketConnection base type is returned.
+     * @param gType - a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
+     * @param family - a #GSocketFamily
+     * @param type - a #GSocketType
+     * @param protocol - a protocol id
+     */
     static factoryRegisterType(gType: number, family: SocketFamily, type: SocketType, protocol: number): void;
+    /**
+     * Connect `connection` to the specified remote address.
+     * @param address - a #GSocketAddress specifying the remote address.
+     * @param cancellable - a %GCancellable or %NULL
+     */
     connectTo(address: SocketAddress, cancellable?: Cancellable | null): boolean;
+    /**
+     * Asynchronously connect `connection` to the specified remote address.
+     *
+     * This clears the #GSocket:blocking flag on @connection's underlying
+     * socket if it is currently set.
+     *
+     * If #GSocket:timeout is set, the operation will time out and return
+     * %G_IO_ERROR_TIMED_OUT after that period. Otherwise, it will continue
+     * indefinitely until operating system timeouts (if any) are hit.
+     *
+     * Use g_socket_connection_connect_finish() to retrieve the result.
+     * @param address - a #GSocketAddress specifying the remote address.
+     * @param cancellable - a %GCancellable or %NULL
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - user data for the callback
+     */
     connectAsync(address: SocketAddress, cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Gets the result of a g_socket_connection_connect_async() call.
+     * @param result - the #GAsyncResult
+     */
     connectFinish(result: AsyncResult): boolean;
+    /**
+     * Try to get the local address of a socket connection.
+     */
     getLocalAddress(): SocketAddress;
+    /**
+     * Try to get the remote address of a socket connection.
+     *
+     * Since GLib 2.40, when used with g_socket_client_connect() or
+     * g_socket_client_connect_async(), during emission of
+     * %G_SOCKET_CLIENT_CONNECTING, this function will return the remote
+     * address that will be used for the connection.  This allows
+     * applications to print e.g. "Connecting to example.com
+     * (10.42.77.3)...".
+     */
     getRemoteAddress(): SocketAddress;
+    /**
+     * Gets the underlying #GSocket object of the connection.
+     * This can be useful if you want to do something unusual on it
+     * not supported by the #GSocketConnection APIs.
+     */
     getSocket(): Socket;
+    /**
+     * Checks if `connection` is connected. This is equivalent to calling
+     * g_socket_is_connected() on @connection's underlying #GSocket.
+     */
     isConnected(): boolean;
 }

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

@@ -3,6 +3,24 @@ import { NativeError, getObject } from "@gtkx/ffi";
 import { Socket } from "./socket.js";
 import { SocketAddress } from "./socket-address.js";
 import { IOStream } from "./iostream.js";
+/**
+ * `GSocketConnection` is a [class@Gio.IOStream] for a connected socket. They
+ * can be created either by [class@Gio.SocketClient] when connecting to a host,
+ * or by [class@Gio.SocketListener] when accepting a new client.
+ *
+ * The type of the `GSocketConnection` object returned from these calls
+ * depends on the type of the underlying socket that is in use. For
+ * instance, for a TCP/IP connection it will be a [class@Gio.TcpConnection].
+ *
+ * Choosing what type of object to construct is done with the socket
+ * connection factory, and it is possible for third parties to register
+ * custom socket connection types for specific combination of socket
+ * family/type/protocol using [func@Gio.SocketConnection.factory_register_type].
+ *
+ * To close a `GSocketConnection`, use [method@Gio.IOStream.close]. Closing both
+ * substreams of the [class@Gio.IOStream] separately will not close the
+ * underlying [class@Gio.Socket].
+ */
 export class SocketConnection extends IOStream {
     constructor(...args) {
         super(...args);
@@ -18,6 +36,15 @@ export class SocketConnection extends IOStream {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Looks up the #GType to be used when creating socket connections on
+     * sockets with the specified @family, `type` and @protocol_id.
+     *
+     * If no type is registered, the #GSocketConnection base type is returned.
+     * @param family - a #GSocketFamily
+     * @param type - a #GSocketType
+     * @param protocolId - a protocol id
+     */
     static factoryLookupType(family, type, protocolId) {
         return call("libgio-2.0.so.0", "g_socket_connection_factory_lookup_type", [
             {
@@ -34,6 +61,16 @@ export class SocketConnection extends IOStream {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Looks up the #GType to be used when creating socket connections on
+     * sockets with the specified @family, `type` and @protocol.
+     *
+     * If no type is registered, the #GSocketConnection base type is returned.
+     * @param gType - a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
+     * @param family - a #GSocketFamily
+     * @param type - a #GSocketType
+     * @param protocol - a protocol id
+     */
     static factoryRegisterType(gType, family, type, protocol) {
         call("libgio-2.0.so.0", "g_socket_connection_factory_register_type", [
             {
@@ -54,6 +91,11 @@ export class SocketConnection extends IOStream {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Connect `connection` to the specified remote address.
+     * @param address - a #GSocketAddress specifying the remote address.
+     * @param cancellable - a %GCancellable or %NULL
+     */
     connectTo(address, cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_socket_connection_connect", [
@@ -87,6 +129,22 @@ export class SocketConnection extends IOStream {
         }
         return result;
     }
+    /**
+     * Asynchronously connect `connection` to the specified remote address.
+     *
+     * This clears the #GSocket:blocking flag on @connection's underlying
+     * socket if it is currently set.
+     *
+     * If #GSocket:timeout is set, the operation will time out and return
+     * %G_IO_ERROR_TIMED_OUT after that period. Otherwise, it will continue
+     * indefinitely until operating system timeouts (if any) are hit.
+     *
+     * Use g_socket_connection_connect_finish() to retrieve the result.
+     * @param address - a #GSocketAddress specifying the remote address.
+     * @param cancellable - a %GCancellable or %NULL
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - user data for the callback
+     */
     connectAsync(address, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_socket_connection_connect_async", [
             {
@@ -114,6 +172,10 @@ export class SocketConnection extends IOStream {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the result of a g_socket_connection_connect_async() call.
+     * @param result - the #GAsyncResult
+     */
     connectFinish(result) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_socket_connection_connect_finish", [
@@ -142,6 +204,9 @@ export class SocketConnection extends IOStream {
         }
         return _result;
     }
+    /**
+     * Try to get the local address of a socket connection.
+     */
     getLocalAddress() {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_socket_connection_get_local_address", [
@@ -166,6 +231,16 @@ export class SocketConnection extends IOStream {
         }
         return getObject(ptr, SocketAddress);
     }
+    /**
+     * Try to get the remote address of a socket connection.
+     *
+     * Since GLib 2.40, when used with g_socket_client_connect() or
+     * g_socket_client_connect_async(), during emission of
+     * %G_SOCKET_CLIENT_CONNECTING, this function will return the remote
+     * address that will be used for the connection.  This allows
+     * applications to print e.g. "Connecting to example.com
+     * (10.42.77.3)...".
+     */
     getRemoteAddress() {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_socket_connection_get_remote_address", [
@@ -190,6 +265,11 @@ export class SocketConnection extends IOStream {
         }
         return getObject(ptr, SocketAddress);
     }
+    /**
+     * Gets the underlying #GSocket object of the connection.
+     * This can be useful if you want to do something unusual on it
+     * not supported by the #GSocketConnection APIs.
+     */
     getSocket() {
         const ptr = call("libgio-2.0.so.0", "g_socket_connection_get_socket", [
             {
@@ -199,6 +279,10 @@ export class SocketConnection extends IOStream {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Socket);
     }
+    /**
+     * Checks if `connection` is connected. This is equivalent to calling
+     * g_socket_is_connected() on @connection's underlying #GSocket.
+     */
     isConnected() {
         return call("libgio-2.0.so.0", "g_socket_connection_is_connected", [
             {

package/dist/generated/gio/socket-control-message.d.ts

@@ -1,11 +1,67 @@
 import * as GObject from "../gobject/index.js";
+/**
+ * A `GSocketControlMessage` is a special-purpose utility message that
+ * can be sent to or received from a [class@Gio.Socket]. These types of
+ * messages are often called ‘ancillary data’.
+ *
+ * The message can represent some sort of special instruction to or
+ * information from the socket or can represent a special kind of
+ * transfer to the peer (for example, sending a file descriptor over
+ * a UNIX socket).
+ *
+ * These messages are sent with [method@Gio.Socket.send_message] and received
+ * with [method@Gio.Socket.receive_message].
+ *
+ * To extend the set of control message that can be sent, subclass this
+ * class and override the `get_size`, `get_level`, `get_type` and `serialize`
+ * methods.
+ *
+ * To extend the set of control messages that can be received, subclass
+ * this class and implement the `deserialize` method. Also, make sure your
+ * class is registered with the [type@GObject.Type] type system before calling
+ * [method@Gio.Socket.receive_message] to read such a message.
+ */
 export declare class SocketControlMessage extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Tries to deserialize a socket control message of a given
+     * `level` and @type. This will ask all known (to GType) subclasses
+     * of #GSocketControlMessage if they can understand this kind
+     * of message and if so deserialize it into a #GSocketControlMessage.
+     *
+     * If there is no implementation for this kind of control message, %NULL
+     * will be returned.
+     * @param level - a socket level
+     * @param type - a socket control message type for the given @level
+     * @param size - the size of the data in bytes
+     * @param data - pointer to the message data
+     */
     static deserialize(level: number, type: number, size: number, data: number[]): SocketControlMessage;
+    /**
+     * Returns the "level" (i.e. the originating protocol) of the control message.
+     * This is often SOL_SOCKET.
+     */
     getLevel(): number;
+    /**
+     * Returns the protocol specific type of the control message.
+     * For instance, for UNIX fd passing this would be SCM_RIGHTS.
+     */
     getMsgType(): number;
+    /**
+     * Returns the space required for the control message, not including
+     * headers or alignment.
+     */
     getSize(): number;
+    /**
+     * Converts the data in the message to bytes placed in the
+     * message.
+     *
+     * `data` is guaranteed to have enough space to fit the size
+     * returned by g_socket_control_message_get_size() on this
+     * object.
+     * @param data - A buffer to write data to
+     */
     serialize(data: number): void;
     connect(signal: "notify", handler: (self: SocketControlMessage, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gio/socket-control-message.js

@@ -1,6 +1,28 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * A `GSocketControlMessage` is a special-purpose utility message that
+ * can be sent to or received from a [class@Gio.Socket]. These types of
+ * messages are often called ‘ancillary data’.
+ *
+ * The message can represent some sort of special instruction to or
+ * information from the socket or can represent a special kind of
+ * transfer to the peer (for example, sending a file descriptor over
+ * a UNIX socket).
+ *
+ * These messages are sent with [method@Gio.Socket.send_message] and received
+ * with [method@Gio.Socket.receive_message].
+ *
+ * To extend the set of control message that can be sent, subclass this
+ * class and override the `get_size`, `get_level`, `get_type` and `serialize`
+ * methods.
+ *
+ * To extend the set of control messages that can be received, subclass
+ * this class and implement the `deserialize` method. Also, make sure your
+ * class is registered with the [type@GObject.Type] type system before calling
+ * [method@Gio.Socket.receive_message] to read such a message.
+ */
 export class SocketControlMessage extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -12,6 +34,19 @@ export class SocketControlMessage extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Tries to deserialize a socket control message of a given
+     * `level` and @type. This will ask all known (to GType) subclasses
+     * of #GSocketControlMessage if they can understand this kind
+     * of message and if so deserialize it into a #GSocketControlMessage.
+     *
+     * If there is no implementation for this kind of control message, %NULL
+     * will be returned.
+     * @param level - a socket level
+     * @param type - a socket control message type for the given @level
+     * @param size - the size of the data in bytes
+     * @param data - pointer to the message data
+     */
     static deserialize(level, type, size, data) {
         const ptr = call("libgio-2.0.so.0", "g_socket_control_message_deserialize", [
             {
@@ -36,6 +71,10 @@ export class SocketControlMessage extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, SocketControlMessage);
     }
+    /**
+     * Returns the "level" (i.e. the originating protocol) of the control message.
+     * This is often SOL_SOCKET.
+     */
     getLevel() {
         return call("libgio-2.0.so.0", "g_socket_control_message_get_level", [
             {
@@ -44,6 +83,10 @@ export class SocketControlMessage extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns the protocol specific type of the control message.
+     * For instance, for UNIX fd passing this would be SCM_RIGHTS.
+     */
     getMsgType() {
         return call("libgio-2.0.so.0", "g_socket_control_message_get_msg_type", [
             {
@@ -52,6 +95,10 @@ export class SocketControlMessage extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns the space required for the control message, not including
+     * headers or alignment.
+     */
     getSize() {
         return call("libgio-2.0.so.0", "g_socket_control_message_get_size", [
             {
@@ -60,6 +107,15 @@ export class SocketControlMessage extends GObject.GObject {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Converts the data in the message to bytes placed in the
+     * message.
+     *
+     * `data` is guaranteed to have enough space to fit the size
+     * returned by g_socket_control_message_get_size() on this
+     * object.
+     * @param data - A buffer to write data to
+     */
     serialize(data) {
         call("libgio-2.0.so.0", "g_socket_control_message_serialize", [
             {