@gtkx/ffi 0.1.45 → 0.1.47

package/dist/generated/gio/input-stream.js

@@ -2,6 +2,21 @@ import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GInputStream` is a base class for implementing streaming input.
+ *
+ * It has functions to read from a stream ([method@Gio.InputStream.read]),
+ * to close a stream ([method@Gio.InputStream.close]) and to skip some content
+ * ([method@Gio.InputStream.skip]).
+ *
+ * To copy the content of an input stream to an output stream without
+ * manually handling the reads and writes, use [method@Gio.OutputStream.splice].
+ *
+ * See the documentation for [class@Gio.IOStream] for details of thread safety
+ * of streaming APIs.
+ *
+ * All of these functions have async variants too.
+ */
 export class InputStream extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -17,6 +32,9 @@ export class InputStream extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Clears the pending flag on @stream.
+     */
     clearPending() {
         call("libgio-2.0.so.0", "g_input_stream_clear_pending", [
             {
@@ -25,6 +43,32 @@ export class InputStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Closes the stream, releasing resources related to it.
+     *
+     * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
+     * Closing a stream multiple times will not return an error.
+     *
+     * Streams will be automatically closed when the last reference
+     * is dropped, but you might want to call this function to make sure
+     * resources are released as early as possible.
+     *
+     * Some streams might keep the backing store of the stream (e.g. a file descriptor)
+     * open after the stream is closed. See the documentation for the individual
+     * stream for details.
+     *
+     * On failure the first error that happened will be reported, but the close
+     * operation will finish as much as possible. A stream that failed to
+     * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
+     * is important to check and report the error to the user.
+     *
+     * If `cancellable` is not %NULL, then the operation 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.
+     * Cancelling a close will still leave the stream closed, but some streams
+     * can use a faster close that doesn't block to e.g. check errors.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     close(cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_input_stream_close", [
@@ -54,6 +98,22 @@ export class InputStream extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Requests an asynchronous closes of the stream, releasing resources related to it.
+     * When the operation is finished `callback` will be called.
+     * You can then call g_input_stream_close_finish() to get the result of the
+     * operation.
+     *
+     * For behaviour details see g_input_stream_close().
+     *
+     * The asynchronous methods have a default fallback that uses threads to implement
+     * asynchronicity, so they are optional for inheriting classes. However, if you
+     * override one you must override all.
+     * @param ioPriority - the I/O priority of the request
+     * @param cancellable - optional cancellable object
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     closeAsync(ioPriority, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_input_stream_close_async", [
             {
@@ -81,6 +141,10 @@ export class InputStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
+     * @param result - a #GAsyncResult.
+     */
     closeFinish(result) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_input_stream_close_finish", [
@@ -109,6 +173,9 @@ export class InputStream extends GObject.GObject {
         }
         return _result;
     }
+    /**
+     * Checks if an input stream has pending actions.
+     */
     hasPending() {
         return call("libgio-2.0.so.0", "g_input_stream_has_pending", [
             {
@@ -117,6 +184,9 @@ export class InputStream extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if an input stream is closed.
+     */
     isClosed() {
         return call("libgio-2.0.so.0", "g_input_stream_is_closed", [
             {
@@ -125,6 +195,31 @@ export class InputStream extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Tries to read `count` bytes from the stream into the buffer starting at
+     * @buffer. Will block during this read.
+     *
+     * If count is zero returns zero and does nothing. A value of `count` larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+     *
+     * On success, the number of bytes read into the buffer is returned.
+     * It is not an error if this is not the same as the requested size, as it
+     * can happen e.g. near the end of a file. Zero is returned on end of file
+     * (or if `count` is zero),  but never otherwise.
+     *
+     * The returned `buffer` is not a nul-terminated string, it can contain nul bytes
+     * at any position, and this function doesn't nul-terminate the @buffer.
+     *
+     * If `cancellable` is not %NULL, then the operation 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 an
+     * operation was partially finished when the operation was cancelled the
+     * partial result will be returned, without an error.
+     *
+     * On error -1 is returned and `error` is set accordingly.
+     * @param buffer - a buffer to read data into (which should be at least count bytes long).
+     * @param count - the number of bytes that will be read from the stream
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     read(buffer, count, cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_input_stream_read", [
@@ -168,6 +263,30 @@ export class InputStream extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Tries to read `count` bytes from the stream into the buffer starting at
+     * @buffer. Will block during this read.
+     *
+     * This function is similar to g_input_stream_read(), except it tries to
+     * read as many bytes as requested, only stopping on an error or end of stream.
+     *
+     * On a successful read of `count` bytes, or if we reached the end of the
+     * stream,  %TRUE is returned, and `bytes_read` is set to the number of bytes
+     * read into @buffer.
+     *
+     * If there is an error during the operation %FALSE is returned and `error` is set to indicate the error status.
+     *
+     * As a special exception to the normal conventions for functions that
+     * use #GError, if this function returns %FALSE (and sets @error) then
+     * `bytes_read` will be set to the number of bytes that were successfully
+     * read before the error was encountered.  This functionality is only
+     * available from C.  If you need it from another language then you must
+     * write your own loop around g_input_stream_read().
+     * @param buffer - a buffer to read data into (which should be at least count bytes long).
+     * @param count - the number of bytes that will be read from the stream
+     * @param bytesRead - location to store the number of bytes that was read from the stream
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     readAll(buffer, count, bytesRead, cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_input_stream_read_all", [
@@ -218,6 +337,24 @@ export class InputStream extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Request an asynchronous read of `count` bytes from the stream into the
+     * buffer starting at @buffer.
+     *
+     * This is the asynchronous equivalent of [method@InputStream.read_all].
+     *
+     * Call [method@InputStream.read_all_finish] to collect the result.
+     *
+     * Any outstanding I/O request with higher priority (lower numerical
+     * value) will be executed before an outstanding request with lower
+     * priority. Default priority is %G_PRIORITY_DEFAULT.
+     * @param buffer - a buffer to read data into (which should be at least count bytes long)
+     * @param count - the number of bytes that will be read from the stream
+     * @param ioPriority - the I/O priority of the request
+     * @param cancellable - optional #GCancellable object, %NULL to ignore
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     readAllAsync(buffer, count, ioPriority, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_input_stream_read_all_async", [
             {
@@ -259,6 +396,19 @@ export class InputStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes an asynchronous stream read operation started with
+     * [method@InputStream.read_all_async].
+     *
+     * As a special exception to the normal conventions for functions that
+     * use #GError, if this function returns %FALSE (and sets @error) then
+     * `bytes_read` will be set to the number of bytes that were successfully
+     * read before the error was encountered.  This functionality is only
+     * available from C.  If you need it from another language then you must
+     * write your own loop around g_input_stream_read_async().
+     * @param result - a #GAsyncResult
+     * @param bytesRead - location to store the number of bytes that was read from the stream
+     */
     readAllFinish(result, bytesRead) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_input_stream_read_all_finish", [
@@ -294,6 +444,37 @@ export class InputStream extends GObject.GObject {
         }
         return _result;
     }
+    /**
+     * Request an asynchronous read of `count` bytes from the stream into the buffer
+     * starting at @buffer. When the operation is finished `callback` will be called.
+     * You can then call g_input_stream_read_finish() to get the result of the
+     * operation.
+     *
+     * During an async request no other sync and async calls are allowed on @stream, and will
+     * result in %G_IO_ERROR_PENDING errors.
+     *
+     * A value of `count` larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+     *
+     * On success, the number of bytes read into the buffer will be passed to the
+     * callback. It is not an error if this is not the same as the requested size, as it
+     * can happen e.g. near the end of a file, but generally we try to read
+     * as many bytes as requested. Zero is returned on end of file
+     * (or if `count` is zero),  but never otherwise.
+     *
+     * Any outstanding i/o request with higher priority (lower numerical value) will
+     * be executed before an outstanding request with lower priority. Default
+     * priority is %G_PRIORITY_DEFAULT.
+     *
+     * The asynchronous methods have a default fallback that uses threads to implement
+     * asynchronicity, so they are optional for inheriting classes. However, if you
+     * override one you must override all.
+     * @param buffer - a buffer to read data into (which should be at least count bytes long).
+     * @param count - the number of bytes that will be read from the stream
+     * @param ioPriority - the I/O priority
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     readAsync(buffer, count, ioPriority, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_input_stream_read_async", [
             {
@@ -335,6 +516,33 @@ export class InputStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Like g_input_stream_read(), this tries to read `count` bytes from
+     * the stream in a blocking fashion. However, rather than reading into
+     * a user-supplied buffer, this will create a new #GBytes containing
+     * the data that was read. This may be easier to use from language
+     * bindings.
+     *
+     * If count is zero, returns a zero-length #GBytes and does nothing. A
+     * value of `count` larger than %G_MAXSSIZE will cause a
+     * %G_IO_ERROR_INVALID_ARGUMENT error.
+     *
+     * On success, a new #GBytes is returned. It is not an error if the
+     * size of this object is not the same as the requested size, as it
+     * can happen e.g. near the end of a file. A zero-length #GBytes is
+     * returned on end of file (or if `count` is zero), but never
+     * otherwise.
+     *
+     * If `cancellable` is not %NULL, then the operation 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 an
+     * operation was partially finished when the operation was cancelled the
+     * partial result will be returned, without an error.
+     *
+     * On error %NULL is returned and `error` is set accordingly.
+     * @param count - maximum number of bytes that will be read from the stream. Common
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     readBytes(count, cancellable) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_input_stream_read_bytes", [
@@ -373,6 +581,33 @@ export class InputStream extends GObject.GObject {
         }
         return getObject(ptr, GLib.Bytes);
     }
+    /**
+     * Request an asynchronous read of `count` bytes from the stream into a
+     * new #GBytes. When the operation is finished `callback` will be
+     * called. You can then call g_input_stream_read_bytes_finish() to get the
+     * result of the operation.
+     *
+     * During an async request no other sync and async calls are allowed
+     * on @stream, and will result in %G_IO_ERROR_PENDING errors.
+     *
+     * A value of `count` larger than %G_MAXSSIZE will cause a
+     * %G_IO_ERROR_INVALID_ARGUMENT error.
+     *
+     * On success, the new #GBytes will be passed to the callback. It is
+     * not an error if this is smaller than the requested size, as it can
+     * happen e.g. near the end of a file, but generally we try to read as
+     * many bytes as requested. Zero is returned on end of file (or if
+     * `count` is zero), but never otherwise.
+     *
+     * Any outstanding I/O request with higher priority (lower numerical
+     * value) will be executed before an outstanding request with lower
+     * priority. Default priority is %G_PRIORITY_DEFAULT.
+     * @param count - the number of bytes that will be read from the stream
+     * @param ioPriority - the I/O priority of the request
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     readBytesAsync(count, ioPriority, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_input_stream_read_bytes_async", [
             {
@@ -404,6 +639,10 @@ export class InputStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes an asynchronous stream read-into-#GBytes operation.
+     * @param result - a #GAsyncResult.
+     */
     readBytesFinish(result) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_input_stream_read_bytes_finish", [
@@ -437,6 +676,10 @@ export class InputStream extends GObject.GObject {
         }
         return getObject(ptr, GLib.Bytes);
     }
+    /**
+     * Finishes an asynchronous stream read operation.
+     * @param result - a #GAsyncResult.
+     */
     readFinish(result) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_input_stream_read_finish", [
@@ -465,6 +708,11 @@ export class InputStream extends GObject.GObject {
         }
         return _result;
     }
+    /**
+     * Sets `stream` to have actions pending. If the pending flag is
+     * already set or `stream` is closed, it will return %FALSE and set
+     * @error.
+     */
     setPending() {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_input_stream_set_pending", [
@@ -489,6 +737,24 @@ export class InputStream extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Tries to skip `count` bytes from the stream. Will block during the operation.
+     *
+     * This is identical to g_input_stream_read(), from a behaviour standpoint,
+     * but the bytes that are skipped are not returned to the user. Some
+     * streams have an implementation that is more efficient than reading the data.
+     *
+     * This function is optional for inherited classes, as the default implementation
+     * emulates it using read.
+     *
+     * If `cancellable` is not %NULL, then the operation 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 an
+     * operation was partially finished when the operation was cancelled the
+     * partial result will be returned, without an error.
+     * @param count - the number of bytes that will be skipped from the stream
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     skip(count, cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_input_stream_skip", [
@@ -522,6 +788,36 @@ export class InputStream extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Request an asynchronous skip of `count` bytes from the stream.
+     * When the operation is finished `callback` will be called.
+     * You can then call g_input_stream_skip_finish() to get the result
+     * of the operation.
+     *
+     * During an async request no other sync and async calls are allowed,
+     * and will result in %G_IO_ERROR_PENDING errors.
+     *
+     * A value of `count` larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+     *
+     * On success, the number of bytes skipped will be passed to the callback.
+     * It is not an error if this is not the same as the requested size, as it
+     * can happen e.g. near the end of a file, but generally we try to skip
+     * as many bytes as requested. Zero is returned on end of file
+     * (or if `count` is zero), but never otherwise.
+     *
+     * Any outstanding i/o request with higher priority (lower numerical value)
+     * will be executed before an outstanding request with lower priority.
+     * Default priority is %G_PRIORITY_DEFAULT.
+     *
+     * The asynchronous methods have a default fallback that uses threads to
+     * implement asynchronicity, so they are optional for inheriting classes.
+     * However, if you override one, you must override all.
+     * @param count - the number of bytes that will be skipped from the stream
+     * @param ioPriority - the I/O priority of the request
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     skipAsync(count, ioPriority, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_input_stream_skip_async", [
             {
@@ -553,6 +849,10 @@ export class InputStream extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes a stream skip operation.
+     * @param result - a #GAsyncResult.
+     */
     skipFinish(result) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_input_stream_skip_finish", [

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

@@ -1,8 +1,51 @@
 import * as GObject from "../gobject/index.js";
+/**
+ * Provides an interface and default functions for loading and unloading
+ * modules. This is used internally to make GIO extensible, but can also
+ * be used by others to implement module loading.
+ */
 export declare class IOModule extends GObject.TypeModule {
+    /**
+     * Creates a new GIOModule that will load the specific
+     * shared library when in use.
+     * @param filename - filename of the shared library module.
+     */
     constructor(filename: string);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Optional API for GIO modules to implement.
+     *
+     * Should return a list of all the extension points that may be
+     * implemented in this module.
+     *
+     * This method will not be called in normal use, however it may be
+     * called when probing existing modules and recording which extension
+     * points that this model is used for. This means we won't have to
+     * load and initialize this module unless its needed.
+     *
+     * If this function is not implemented by the module the module will
+     * always be loaded, initialized and then unloaded on application
+     * startup so that it can register its extension points during init.
+     *
+     * Note that a module need not actually implement all the extension
+     * points that g_io_module_query() returns, since the exact list of
+     * extension may depend on runtime issues. However all extension
+     * points actually implemented must be returned by g_io_module_query()
+     * (if defined).
+     *
+     * When installing a module that implements g_io_module_query() you must
+     * run gio-querymodules in order to build the cache files required for
+     * lazy loading.
+     *
+     * Since 2.56, this function should be named `g_io_<modulename>_query`, where
+     * `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
+     * everything after the first dot removed, and with `-` replaced with `_`
+     * throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
+     * Using the new symbol names avoids name clashes when building modules
+     * statically. The old symbol names continue to be supported, but cannot be used
+     * for static builds.
+     */
     static query(): string[];
     connect(signal: "notify", handler: (self: IOModule, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gio/iomodule.js

@@ -1,6 +1,11 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * Provides an interface and default functions for loading and unloading
+ * modules. This is used internally to make GIO extensible, but can also
+ * be used by others to implement module loading.
+ */
 export class IOModule extends GObject.TypeModule {
     constructor(...args) {
         super(...args);
@@ -14,6 +19,39 @@ export class IOModule extends GObject.TypeModule {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Optional API for GIO modules to implement.
+     *
+     * Should return a list of all the extension points that may be
+     * implemented in this module.
+     *
+     * This method will not be called in normal use, however it may be
+     * called when probing existing modules and recording which extension
+     * points that this model is used for. This means we won't have to
+     * load and initialize this module unless its needed.
+     *
+     * If this function is not implemented by the module the module will
+     * always be loaded, initialized and then unloaded on application
+     * startup so that it can register its extension points during init.
+     *
+     * Note that a module need not actually implement all the extension
+     * points that g_io_module_query() returns, since the exact list of
+     * extension may depend on runtime issues. However all extension
+     * points actually implemented must be returned by g_io_module_query()
+     * (if defined).
+     *
+     * When installing a module that implements g_io_module_query() you must
+     * run gio-querymodules in order to build the cache files required for
+     * lazy loading.
+     *
+     * Since 2.56, this function should be named `g_io_<modulename>_query`, where
+     * `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
+     * everything after the first dot removed, and with `-` replaced with `_`
+     * throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
+     * Using the new symbol names avoids name clashes when building modules
+     * statically. The old symbol names continue to be supported, but cannot be used
+     * for static builds.
+     */
     static query() {
         return call("libgio-2.0.so.0", "g_io_module_query", [], {
             type: "array",