@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/zlib-compressor.js

@@ -3,6 +3,10 @@ import { NativeError, getObject } from "@gtkx/ffi";
 import { FileInfo } from "./file-info.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GZlibCompressor` is an implementation of [iface@Gio.Converter] that
+ * compresses data using zlib.
+ */
 export class ZlibCompressor extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -20,6 +24,9 @@ export class ZlibCompressor extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets the [property@Gio.ZlibCompressor:file-info] property.
+     */
     getFileInfo() {
         const ptr = call("libgio-2.0.so.0", "g_zlib_compressor_get_file_info", [
             {
@@ -31,6 +38,9 @@ export class ZlibCompressor extends GObject.GObject {
             return null;
         return getObject(ptr, FileInfo);
     }
+    /**
+     * Gets the [property@Gio.ZlibCompressor:os] property.
+     */
     getOs() {
         return call("libgio-2.0.so.0", "g_zlib_compressor_get_os", [
             {
@@ -39,6 +49,14 @@ export class ZlibCompressor extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Sets the [property@Gio.ZlibCompressor:file-info] property.
+     *
+     * Note: it is an error to call this function while a compression is in
+     * progress; it may only be called immediately after creation of @compressor,
+     * or after resetting it with [method@Gio.Converter.reset].
+     * @param fileInfo - file info for the gzip header
+     */
     setFileInfo(fileInfo) {
         call("libgio-2.0.so.0", "g_zlib_compressor_set_file_info", [
             {
@@ -52,6 +70,14 @@ export class ZlibCompressor extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the [property@Gio.ZlibCompressor:os] property.
+     *
+     * Note: it is an error to call this function while a compression is in
+     * progress; it may only be called immediately after creation of @compressor,
+     * or after resetting it with [method@Gio.Converter.reset].
+     * @param os - the OS code to use, or `-1` to unset
+     */
     setOs(os) {
         call("libgio-2.0.so.0", "g_zlib_compressor_set_os", [
             {
@@ -64,6 +90,97 @@ export class ZlibCompressor extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * This is the main operation used when converting data. It is to be called
+     * multiple times in a loop, and each time it will do some work, i.e.
+     * producing some output (in @outbuf) or consuming some input (from @inbuf) or
+     * both. If its not possible to do any work an error is returned.
+     *
+     * Note that a single call may not consume all input (or any input at all).
+     * Also a call may produce output even if given no input, due to state stored
+     * in the converter producing output.
+     *
+     * If any data was either produced or consumed, and then an error happens, then
+     * only the successful conversion is reported and the error is returned on the
+     * next call.
+     *
+     * A full conversion loop involves calling this method repeatedly, each time
+     * giving it new input and space output space. When there is no more input
+     * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
+     * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
+     * each time until all data is consumed and all output is produced, then
+     * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
+     * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
+     * in a decompression converter where the end of data is detectable from the
+     * data (and there might even be other data after the end of the compressed data).
+     *
+     * When some data has successfully been converted `bytes_read` and is set to
+     * the number of bytes read from @inbuf, and `bytes_written` is set to indicate
+     * how many bytes was written to @outbuf. If there are more data to output
+     * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
+     * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
+     * then %G_CONVERTER_FINISHED is returned.
+     *
+     * On error %G_CONVERTER_ERROR is returned and `error` is set accordingly.
+     * Some errors need special handling:
+     *
+     * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
+     * to write the resulting converted data, the application should
+     * call the function again with a larger `outbuf` to continue.
+     *
+     * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
+     * input to fully determine what the conversion should produce,
+     * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
+     * example with an incomplete multibyte sequence when converting text,
+     * or when a regexp matches up to the end of the input (and may match
+     * further input). It may also happen when `inbuf_size` is zero and
+     * there is no more data to produce.
+     *
+     * When this happens the application should read more input and then
+     * call the function again. If further input shows that there is no
+     * more data call the function again with the same data but with
+     * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
+     * to finish as e.g. in the regexp match case (or, to fail again with
+     * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
+     * input is actually partial).
+     *
+     * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
+     * converter object is in an invalid state where its not allowed
+     * to call g_converter_convert() anymore. At this time you can only
+     * free the object or call g_converter_reset() to reset it to the
+     * initial state.
+     *
+     * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
+     * to try to write out all internal state to the output. The application
+     * has to call the function multiple times with the flag set, and when
+     * the available input has been consumed and all internal state has
+     * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
+     * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
+     * This is somewhat similar to what happens at the end of the input stream,
+     * but done in the middle of the data.
+     *
+     * This has different meanings for different conversions. For instance
+     * in a compression converter it would mean that we flush all the
+     * compression state into output such that if you uncompress the
+     * compressed data you get back all the input data. Doing this may
+     * make the final file larger due to padding though. Another example
+     * is a regexp conversion, where if you at the end of the flushed data
+     * have a match, but there is also a potential longer match. In the
+     * non-flushed case we would ask for more input, but when flushing we
+     * treat this as the end of input and do the match.
+     *
+     * Flushing is not always possible (like if a charset converter flushes
+     * at a partial multibyte sequence). Converters are supposed to try
+     * to produce as much output as possible and then return an error
+     * (typically %G_IO_ERROR_PARTIAL_INPUT).
+     * @param inbuf - the buffer
+     * @param inbufSize - the number of bytes in @inbuf
+     * @param outbuf - a
+     * @param outbufSize - the number of bytes in @outbuf, must be at least one
+     * @param flags - a #GConverterFlags controlling the conversion details
+     * @param bytesRead - will be set to the number of bytes read
+     * @param bytesWritten - will be set to the number of bytes
+     */
     convert(inbuf, inbufSize, outbuf, outbufSize, flags, bytesRead, bytesWritten) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_converter_convert", [
@@ -128,6 +245,10 @@ export class ZlibCompressor extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Applies `converter` to the data in @bytes.
+     * @param bytes - the data to convert
+     */
     convertBytes(bytes) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_converter_convert_bytes", [
@@ -166,6 +287,11 @@ export class ZlibCompressor extends GObject.GObject {
         }
         return getObject(ptr, GLib.Bytes);
     }
+    /**
+     * Resets all internal state in the converter, making it behave
+     * as if it was just created. If the converter has any internal
+     * state that would produce output then that output is lost.
+     */
     reset() {
         call("libgio-2.0.so.0", "g_converter_reset", [
             {

package/dist/generated/gio/zlib-decompressor.d.ts

@@ -3,13 +3,124 @@ import { ConverterFlags, ConverterResult, ZlibCompressorFormat } from "./enums.j
 import { FileInfo } from "./file-info.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GZlibDecompressor` is an implementation of [iface@Gio.Converter] that
+ * decompresses data compressed with zlib.
+ */
 export declare class ZlibDecompressor extends GObject.GObject {
+    /**
+     * Creates a new decompressor.
+     * @param format - the format to use for the compressed data
+     */
     constructor(format: ZlibCompressorFormat);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Gets the [property@Gio.ZlibDecompressor:file-info] property.
+     */
     getFileInfo(): FileInfo | null;
+    /**
+     * This is the main operation used when converting data. It is to be called
+     * multiple times in a loop, and each time it will do some work, i.e.
+     * producing some output (in @outbuf) or consuming some input (from @inbuf) or
+     * both. If its not possible to do any work an error is returned.
+     *
+     * Note that a single call may not consume all input (or any input at all).
+     * Also a call may produce output even if given no input, due to state stored
+     * in the converter producing output.
+     *
+     * If any data was either produced or consumed, and then an error happens, then
+     * only the successful conversion is reported and the error is returned on the
+     * next call.
+     *
+     * A full conversion loop involves calling this method repeatedly, each time
+     * giving it new input and space output space. When there is no more input
+     * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
+     * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
+     * each time until all data is consumed and all output is produced, then
+     * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
+     * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
+     * in a decompression converter where the end of data is detectable from the
+     * data (and there might even be other data after the end of the compressed data).
+     *
+     * When some data has successfully been converted `bytes_read` and is set to
+     * the number of bytes read from @inbuf, and `bytes_written` is set to indicate
+     * how many bytes was written to @outbuf. If there are more data to output
+     * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
+     * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
+     * then %G_CONVERTER_FINISHED is returned.
+     *
+     * On error %G_CONVERTER_ERROR is returned and `error` is set accordingly.
+     * Some errors need special handling:
+     *
+     * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
+     * to write the resulting converted data, the application should
+     * call the function again with a larger `outbuf` to continue.
+     *
+     * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
+     * input to fully determine what the conversion should produce,
+     * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
+     * example with an incomplete multibyte sequence when converting text,
+     * or when a regexp matches up to the end of the input (and may match
+     * further input). It may also happen when `inbuf_size` is zero and
+     * there is no more data to produce.
+     *
+     * When this happens the application should read more input and then
+     * call the function again. If further input shows that there is no
+     * more data call the function again with the same data but with
+     * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
+     * to finish as e.g. in the regexp match case (or, to fail again with
+     * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
+     * input is actually partial).
+     *
+     * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
+     * converter object is in an invalid state where its not allowed
+     * to call g_converter_convert() anymore. At this time you can only
+     * free the object or call g_converter_reset() to reset it to the
+     * initial state.
+     *
+     * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
+     * to try to write out all internal state to the output. The application
+     * has to call the function multiple times with the flag set, and when
+     * the available input has been consumed and all internal state has
+     * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
+     * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
+     * This is somewhat similar to what happens at the end of the input stream,
+     * but done in the middle of the data.
+     *
+     * This has different meanings for different conversions. For instance
+     * in a compression converter it would mean that we flush all the
+     * compression state into output such that if you uncompress the
+     * compressed data you get back all the input data. Doing this may
+     * make the final file larger due to padding though. Another example
+     * is a regexp conversion, where if you at the end of the flushed data
+     * have a match, but there is also a potential longer match. In the
+     * non-flushed case we would ask for more input, but when flushing we
+     * treat this as the end of input and do the match.
+     *
+     * Flushing is not always possible (like if a charset converter flushes
+     * at a partial multibyte sequence). Converters are supposed to try
+     * to produce as much output as possible and then return an error
+     * (typically %G_IO_ERROR_PARTIAL_INPUT).
+     * @param inbuf - the buffer
+     * @param inbufSize - the number of bytes in @inbuf
+     * @param outbuf - a
+     * @param outbufSize - the number of bytes in @outbuf, must be at least one
+     * @param flags - a #GConverterFlags controlling the conversion details
+     * @param bytesRead - will be set to the number of bytes read
+     * @param bytesWritten - will be set to the number of bytes
+     */
     convert(inbuf: number[], inbufSize: number, outbuf: number[], outbufSize: number, flags: ConverterFlags, bytesRead: Ref<number>, bytesWritten: Ref<number>): ConverterResult;
+    /**
+     * Applies `converter` to the data in @bytes.
+     * @param bytes - the data to convert
+     */
     convertBytes(bytes: GLib.Bytes): GLib.Bytes;
+    /**
+     * Resets all internal state in the converter, making it behave
+     * as if it was just created. If the converter has any internal
+     * state that would produce output then that output is lost.
+     */
     reset(): void;
     connect(signal: "notify", handler: (self: ZlibDecompressor, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gio/zlib-decompressor.js

@@ -3,6 +3,10 @@ import { NativeError, getObject } from "@gtkx/ffi";
 import { FileInfo } from "./file-info.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GZlibDecompressor` is an implementation of [iface@Gio.Converter] that
+ * decompresses data compressed with zlib.
+ */
 export class ZlibDecompressor extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -16,6 +20,9 @@ export class ZlibDecompressor extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets the [property@Gio.ZlibDecompressor:file-info] property.
+     */
     getFileInfo() {
         const ptr = call("libgio-2.0.so.0", "g_zlib_decompressor_get_file_info", [
             {
@@ -27,6 +34,97 @@ export class ZlibDecompressor extends GObject.GObject {
             return null;
         return getObject(ptr, FileInfo);
     }
+    /**
+     * This is the main operation used when converting data. It is to be called
+     * multiple times in a loop, and each time it will do some work, i.e.
+     * producing some output (in @outbuf) or consuming some input (from @inbuf) or
+     * both. If its not possible to do any work an error is returned.
+     *
+     * Note that a single call may not consume all input (or any input at all).
+     * Also a call may produce output even if given no input, due to state stored
+     * in the converter producing output.
+     *
+     * If any data was either produced or consumed, and then an error happens, then
+     * only the successful conversion is reported and the error is returned on the
+     * next call.
+     *
+     * A full conversion loop involves calling this method repeatedly, each time
+     * giving it new input and space output space. When there is no more input
+     * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
+     * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
+     * each time until all data is consumed and all output is produced, then
+     * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
+     * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
+     * in a decompression converter where the end of data is detectable from the
+     * data (and there might even be other data after the end of the compressed data).
+     *
+     * When some data has successfully been converted `bytes_read` and is set to
+     * the number of bytes read from @inbuf, and `bytes_written` is set to indicate
+     * how many bytes was written to @outbuf. If there are more data to output
+     * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
+     * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
+     * then %G_CONVERTER_FINISHED is returned.
+     *
+     * On error %G_CONVERTER_ERROR is returned and `error` is set accordingly.
+     * Some errors need special handling:
+     *
+     * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
+     * to write the resulting converted data, the application should
+     * call the function again with a larger `outbuf` to continue.
+     *
+     * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
+     * input to fully determine what the conversion should produce,
+     * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
+     * example with an incomplete multibyte sequence when converting text,
+     * or when a regexp matches up to the end of the input (and may match
+     * further input). It may also happen when `inbuf_size` is zero and
+     * there is no more data to produce.
+     *
+     * When this happens the application should read more input and then
+     * call the function again. If further input shows that there is no
+     * more data call the function again with the same data but with
+     * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
+     * to finish as e.g. in the regexp match case (or, to fail again with
+     * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
+     * input is actually partial).
+     *
+     * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
+     * converter object is in an invalid state where its not allowed
+     * to call g_converter_convert() anymore. At this time you can only
+     * free the object or call g_converter_reset() to reset it to the
+     * initial state.
+     *
+     * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
+     * to try to write out all internal state to the output. The application
+     * has to call the function multiple times with the flag set, and when
+     * the available input has been consumed and all internal state has
+     * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
+     * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
+     * This is somewhat similar to what happens at the end of the input stream,
+     * but done in the middle of the data.
+     *
+     * This has different meanings for different conversions. For instance
+     * in a compression converter it would mean that we flush all the
+     * compression state into output such that if you uncompress the
+     * compressed data you get back all the input data. Doing this may
+     * make the final file larger due to padding though. Another example
+     * is a regexp conversion, where if you at the end of the flushed data
+     * have a match, but there is also a potential longer match. In the
+     * non-flushed case we would ask for more input, but when flushing we
+     * treat this as the end of input and do the match.
+     *
+     * Flushing is not always possible (like if a charset converter flushes
+     * at a partial multibyte sequence). Converters are supposed to try
+     * to produce as much output as possible and then return an error
+     * (typically %G_IO_ERROR_PARTIAL_INPUT).
+     * @param inbuf - the buffer
+     * @param inbufSize - the number of bytes in @inbuf
+     * @param outbuf - a
+     * @param outbufSize - the number of bytes in @outbuf, must be at least one
+     * @param flags - a #GConverterFlags controlling the conversion details
+     * @param bytesRead - will be set to the number of bytes read
+     * @param bytesWritten - will be set to the number of bytes
+     */
     convert(inbuf, inbufSize, outbuf, outbufSize, flags, bytesRead, bytesWritten) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_converter_convert", [
@@ -91,6 +189,10 @@ export class ZlibDecompressor extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Applies `converter` to the data in @bytes.
+     * @param bytes - the data to convert
+     */
     convertBytes(bytes) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_converter_convert_bytes", [
@@ -129,6 +231,11 @@ export class ZlibDecompressor extends GObject.GObject {
         }
         return getObject(ptr, GLib.Bytes);
     }
+    /**
+     * Resets all internal state in the converter, making it behave
+     * as if it was just created. If the converter has any internal
+     * state that would produce output then that output is lost.
+     */
     reset() {
         call("libgio-2.0.so.0", "g_converter_reset", [
             {

package/dist/generated/glib/array.d.ts

@@ -1,11 +1,20 @@
 export interface ArrayInit {
     len?: number;
 }
+/** Contains the public fields of a `GArray`. */
 export declare class Array {
     ptr: unknown;
     constructor(init?: ArrayInit);
     protected createPtr(init: ArrayInit): unknown;
+    /**
+     * a pointer to the element data. The data may be moved as
+     * elements are added to the `GArray`.
+     */
     get data(): string;
+    /**
+     * the number of elements in the `GArray` not including the
+     * possible terminating zero element
+     */
     get len(): number;
     set len(value: number);
 }

package/dist/generated/glib/array.js

@@ -1,4 +1,5 @@
 import { alloc, read, write } from "@gtkx/native";
+/** Contains the public fields of a `GArray`. */
 export class Array {
     ptr;
     constructor(init = {}) {
@@ -10,9 +11,17 @@ export class Array {
             write(ptr, { type: "int", size: 32, unsigned: true }, 8, init.len);
         return ptr;
     }
+    /**
+     * a pointer to the element data. The data may be moved as
+     * elements are added to the `GArray`.
+     */
     get data() {
         return read(this.ptr, { type: "string" }, 0);
     }
+    /**
+     * the number of elements in the `GArray` not including the
+     * possible terminating zero element
+     */
     get len() {
         return read(this.ptr, { type: "int", size: 32, unsigned: true }, 8);
     }