@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/srv-target.d.ts

@@ -1,12 +1,65 @@
+/**
+ * A single target host/port that a network service is running on.
+ *
+ * SRV (service) records are used by some network protocols to provide
+ * service-specific aliasing and load-balancing. For example, XMPP
+ * (Jabber) uses SRV records to locate the XMPP server for a domain;
+ * rather than connecting directly to ‘example.com’ or assuming a
+ * specific server hostname like ‘xmpp.example.com’, an XMPP client
+ * would look up the `xmpp-client` SRV record for ‘example.com’, and
+ * then connect to whatever host was pointed to by that record.
+ *
+ * You can use [method@Gio.Resolver.lookup_service] or
+ * [method@Gio.Resolver.lookup_service_async] to find the `GSrvTarget`s
+ * for a given service. However, if you are simply planning to connect
+ * to the remote service, you can use [class@Gio.NetworkService]’s
+ * [iface@Gio.SocketConnectable] interface and not need to worry about
+ * `GSrvTarget` at all.
+ */
 export declare class SrvTarget {
     ptr: unknown;
+    /**
+     * Creates a new #GSrvTarget with the given parameters.
+     *
+     * You should not need to use this; normally #GSrvTargets are
+     * created by #GResolver.
+     * @param hostname - the host that the service is running on
+     * @param port - the port that the service is running on
+     * @param priority - the target's priority
+     * @param weight - the target's weight
+     */
     constructor(hostname: string, port: number, priority: number, weight: number);
     constructor(_args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Copies @target
+     */
     copy(): SrvTarget;
+    /**
+     * Frees @target
+     */
     free(): void;
+    /**
+     * Gets @target's hostname (in ASCII form; if you are going to present
+     * this to the user, you should use g_hostname_is_ascii_encoded() to
+     * check if it contains encoded Unicode segments, and use
+     * g_hostname_to_unicode() to convert it if it does.)
+     */
     getHostname(): string;
+    /**
+     * Gets @target's port
+     */
     getPort(): number;
+    /**
+     * Gets @target's priority. You should not need to look at this;
+     * #GResolver already sorts the targets according to the algorithm in
+     * RFC 2782.
+     */
     getPriority(): number;
+    /**
+     * Gets @target's weight. You should not need to look at this;
+     * #GResolver already sorts the targets according to the algorithm in
+     * RFC 2782.
+     */
     getWeight(): number;
 }

package/dist/generated/gio/srv-target.js

@@ -1,5 +1,23 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * A single target host/port that a network service is running on.
+ *
+ * SRV (service) records are used by some network protocols to provide
+ * service-specific aliasing and load-balancing. For example, XMPP
+ * (Jabber) uses SRV records to locate the XMPP server for a domain;
+ * rather than connecting directly to ‘example.com’ or assuming a
+ * specific server hostname like ‘xmpp.example.com’, an XMPP client
+ * would look up the `xmpp-client` SRV record for ‘example.com’, and
+ * then connect to whatever host was pointed to by that record.
+ *
+ * You can use [method@Gio.Resolver.lookup_service] or
+ * [method@Gio.Resolver.lookup_service_async] to find the `GSrvTarget`s
+ * for a given service. However, if you are simply planning to connect
+ * to the remote service, you can use [class@Gio.NetworkService]’s
+ * [iface@Gio.SocketConnectable] interface and not need to worry about
+ * `GSrvTarget` at all.
+ */
 export class SrvTarget {
     ptr;
     constructor(...args) {
@@ -27,6 +45,9 @@ export class SrvTarget {
             },
         ], { type: "boxed", borrowed: true, innerType: "GSrvTarget" });
     }
+    /**
+     * Copies @target
+     */
     copy() {
         const ptr = call("libgio-2.0.so.0", "g_srv_target_copy", [
             {
@@ -41,6 +62,9 @@ export class SrvTarget {
         });
         return getObject(ptr, SrvTarget);
     }
+    /**
+     * Frees @target
+     */
     free() {
         call("libgio-2.0.so.0", "g_srv_target_free", [
             {
@@ -49,6 +73,12 @@ export class SrvTarget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets @target's hostname (in ASCII form; if you are going to present
+     * this to the user, you should use g_hostname_is_ascii_encoded() to
+     * check if it contains encoded Unicode segments, and use
+     * g_hostname_to_unicode() to convert it if it does.)
+     */
     getHostname() {
         return call("libgio-2.0.so.0", "g_srv_target_get_hostname", [
             {
@@ -57,6 +87,9 @@ export class SrvTarget {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets @target's port
+     */
     getPort() {
         return call("libgio-2.0.so.0", "g_srv_target_get_port", [
             {
@@ -65,6 +98,11 @@ export class SrvTarget {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Gets @target's priority. You should not need to look at this;
+     * #GResolver already sorts the targets according to the algorithm in
+     * RFC 2782.
+     */
     getPriority() {
         return call("libgio-2.0.so.0", "g_srv_target_get_priority", [
             {
@@ -73,6 +111,11 @@ export class SrvTarget {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Gets @target's weight. You should not need to look at this;
+     * #GResolver already sorts the targets according to the algorithm in
+     * RFC 2782.
+     */
     getWeight() {
         return call("libgio-2.0.so.0", "g_srv_target_get_weight", [
             {

package/dist/generated/gio/subprocess-launcher.d.ts

@@ -1,24 +1,250 @@
 import { SubprocessFlags } from "./enums.js";
 import { Subprocess } from "./subprocess.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * This class contains a set of options for launching child processes,
+ * such as where its standard input and output will be directed, the
+ * argument list, the environment, and more.
+ *
+ * While the [class@Gio.Subprocess] class has high level functions covering
+ * popular cases, use of this class allows access to more advanced
+ * options.  It can also be used to launch multiple subprocesses with
+ * a similar configuration.
+ */
 export declare class SubprocessLauncher extends GObject.GObject {
+    /**
+     * Creates a new #GSubprocessLauncher.
+     *
+     * The launcher is created with the default options.  A copy of the
+     * environment of the calling process is made at the time of this call
+     * and will be used as the environment that the process is launched in.
+     * @param flags - #GSubprocessFlags
+     */
     constructor(flags: SubprocessFlags);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Closes all the file descriptors previously passed to the object with
+     * g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc.
+     *
+     * After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or g_subprocess_launcher_spawnv() will
+     * return %G_IO_ERROR_CLOSED. This method is idempotent if
+     * called more than once.
+     *
+     * This function is called automatically when the #GSubprocessLauncher
+     * is disposed, but is provided separately so that garbage collected
+     * language bindings can call it earlier to guarantee when FDs are closed.
+     */
     close(): void;
+    /**
+     * Returns the value of the environment variable `variable` in the
+     * environment of processes launched from this launcher.
+     *
+     * On UNIX, the returned string can be an arbitrary byte string.
+     * On Windows, it will be UTF-8.
+     * @param variable - the environment variable to get
+     */
     getenv(variable: string): string | null;
+    /**
+     * Sets the current working directory that processes will be launched
+     * with.
+     *
+     * By default processes are launched with the current working directory
+     * of the launching process at the time of launch.
+     * @param cwd - the cwd for launched processes
+     */
     setCwd(cwd: string): void;
+    /**
+     * Replace the entire environment of processes launched from this
+     * launcher with the given 'environ' variable.
+     *
+     * Typically you will build this variable by using g_listenv() to copy
+     * the process 'environ' and using the functions g_environ_setenv(),
+     * g_environ_unsetenv(), etc.
+     *
+     * As an alternative, you can use g_subprocess_launcher_setenv(),
+     * g_subprocess_launcher_unsetenv(), etc.
+     *
+     * Pass an empty array to set an empty environment. Pass %NULL to inherit the
+     * parent process’ environment. As of GLib 2.54, the parent process’ environment
+     * will be copied when g_subprocess_launcher_set_environ() is called.
+     * Previously, it was copied when the subprocess was executed. This means the
+     * copied environment may now be modified (using g_subprocess_launcher_setenv(),
+     * etc.) before launching the subprocess.
+     *
+     * On UNIX, all strings in this array can be arbitrary byte strings.
+     * On Windows, they should be in UTF-8.
+     * @param env - the replacement environment
+     */
     setEnviron(env: string[]): void;
+    /**
+     * Sets the flags on the launcher.
+     *
+     * The default flags are %G_SUBPROCESS_FLAGS_NONE.
+     *
+     * You may not set flags that specify conflicting options for how to
+     * handle a particular stdio stream (eg: specifying both
+     * %G_SUBPROCESS_FLAGS_STDIN_PIPE and
+     * %G_SUBPROCESS_FLAGS_STDIN_INHERIT).
+     *
+     * You may also not set a flag that conflicts with a previous call to a
+     * function like g_subprocess_launcher_set_stdin_file_path() or
+     * g_subprocess_launcher_take_stdout_fd().
+     * @param flags - #GSubprocessFlags
+     */
     setFlags(flags: SubprocessFlags): void;
+    /**
+     * Sets the file path to use as the stderr for spawned processes.
+     *
+     * If `path` is %NULL then any previously given path is unset.
+     *
+     * The file will be created or truncated when the process is spawned, as
+     * would be the case if using '2>' at the shell.
+     *
+     * If you want to send both stdout and stderr to the same file then use
+     * %G_SUBPROCESS_FLAGS_STDERR_MERGE.
+     *
+     * You may not set a stderr file path if a stderr fd is already set or
+     * if the launcher flags contain any flags directing stderr elsewhere.
+     *
+     * This feature is only available on UNIX.
+     * @param path - a filename or %NULL
+     */
     setStderrFilePath(path?: string | null): void;
+    /**
+     * Sets the file path to use as the stdin for spawned processes.
+     *
+     * If `path` is %NULL then any previously given path is unset.
+     *
+     * The file must exist or spawning the process will fail.
+     *
+     * You may not set a stdin file path if a stdin fd is already set or if
+     * the launcher flags contain any flags directing stdin elsewhere.
+     *
+     * This feature is only available on UNIX.
+     * @param path - a filename or %NULL
+     */
     setStdinFilePath(path?: string | null): void;
+    /**
+     * Sets the file path to use as the stdout for spawned processes.
+     *
+     * If `path` is %NULL then any previously given path is unset.
+     *
+     * The file will be created or truncated when the process is spawned, as
+     * would be the case if using '>' at the shell.
+     *
+     * You may not set a stdout file path if a stdout fd is already set or
+     * if the launcher flags contain any flags directing stdout elsewhere.
+     *
+     * This feature is only available on UNIX.
+     * @param path - a filename or %NULL
+     */
     setStdoutFilePath(path?: string | null): void;
+    /**
+     * Sets the environment variable `variable` in the environment of
+     * processes launched from this launcher.
+     *
+     * On UNIX, both the variable's name and value can be arbitrary byte
+     * strings, except that the variable's name cannot contain '='.
+     * On Windows, they should be in UTF-8.
+     * @param variable - the environment variable to set,
+     * @param value - the new value for the variable
+     * @param overwrite - whether to change the variable if it already exists
+     */
     setenv(variable: string, value: string, overwrite: boolean): void;
+    /**
+     * Creates a #GSubprocess given a provided array of arguments.
+     * @param argv - Command line arguments
+     */
     spawnv(argv: string[]): Subprocess;
+    /**
+     * Transfer an arbitrary file descriptor from parent process to the
+     * child.  This function takes ownership of the @source_fd; it will be closed
+     * in the parent when `self` is freed.
+     *
+     * By default, all file descriptors from the parent will be closed.
+     * This function allows you to create (for example) a custom `pipe()` or
+     * `socketpair()` before launching the process, and choose the target
+     * descriptor in the child.
+     *
+     * An example use case is GNUPG, which has a command line argument
+     * `--passphrase-fd` providing a file descriptor number where it expects
+     * the passphrase to be written.
+     * @param sourceFd - File descriptor in parent process
+     * @param targetFd - Target descriptor for child process
+     */
     takeFd(sourceFd: number, targetFd: number): void;
+    /**
+     * Sets the file descriptor to use as the stderr for spawned processes.
+     *
+     * If `fd` is -1 then any previously given fd is unset.
+     *
+     * Note that the default behaviour is to pass stderr through to the
+     * stderr of the parent process.
+     *
+     * The passed `fd` belongs to the #GSubprocessLauncher.  It will be
+     * automatically closed when the launcher is finalized.  The file
+     * descriptor will also be closed on the child side when executing the
+     * spawned process.
+     *
+     * You may not set a stderr fd if a stderr file path is already set or
+     * if the launcher flags contain any flags directing stderr elsewhere.
+     *
+     * This feature is only available on UNIX.
+     * @param fd - a file descriptor, or -1
+     */
     takeStderrFd(fd: number): void;
+    /**
+     * Sets the file descriptor to use as the stdin for spawned processes.
+     *
+     * If `fd` is -1 then any previously given fd is unset.
+     *
+     * Note that if your intention is to have the stdin of the calling
+     * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT
+     * is a better way to go about doing that.
+     *
+     * The passed `fd` is noted but will not be touched in the current
+     * process.  It is therefore necessary that it be kept open by the
+     * caller until the subprocess is spawned.  The file descriptor will
+     * also not be explicitly closed on the child side, so it must be marked
+     * O_CLOEXEC if that's what you want.
+     *
+     * You may not set a stdin fd if a stdin file path is already set or if
+     * the launcher flags contain any flags directing stdin elsewhere.
+     *
+     * This feature is only available on UNIX.
+     * @param fd - a file descriptor, or -1
+     */
     takeStdinFd(fd: number): void;
+    /**
+     * Sets the file descriptor to use as the stdout for spawned processes.
+     *
+     * If `fd` is -1 then any previously given fd is unset.
+     *
+     * Note that the default behaviour is to pass stdout through to the
+     * stdout of the parent process.
+     *
+     * The passed `fd` is noted but will not be touched in the current
+     * process.  It is therefore necessary that it be kept open by the
+     * caller until the subprocess is spawned.  The file descriptor will
+     * also not be explicitly closed on the child side, so it must be marked
+     * O_CLOEXEC if that's what you want.
+     *
+     * You may not set a stdout fd if a stdout file path is already set or
+     * if the launcher flags contain any flags directing stdout elsewhere.
+     *
+     * This feature is only available on UNIX.
+     * @param fd - a file descriptor, or -1
+     */
     takeStdoutFd(fd: number): void;
+    /**
+     * Removes the environment variable `variable` from the environment of
+     * processes launched from this launcher.
+     *
+     * On UNIX, the variable's name can be an arbitrary byte string not
+     * containing '='. On Windows, it should be in UTF-8.
+     * @param variable - the environment variable to unset,
+     */
     unsetenv(variable: string): void;
     connect(signal: "notify", handler: (self: SubprocessLauncher, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;