@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/glib/iochannel.js

@@ -1,11 +1,74 @@
 import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
+/**
+ * The `GIOChannel` data type aims to provide a portable method for
+ * using file descriptors, pipes, and sockets, and integrating them
+ * into the main event loop (see [struct@GLib.MainContext]). Currently,
+ * full support is available on UNIX platforms; support for Windows
+ * is only partially complete.
+ *
+ * To create a new `GIOChannel` on UNIX systems use
+ * [ctor@GLib.IOChannel.unix_new]. This works for plain file descriptors,
+ * pipes and sockets. Alternatively, a channel can be created for a
+ * file in a system independent manner using [ctor@GLib.IOChannel.new_file].
+ *
+ * Once a `GIOChannel` has been created, it can be used in a generic
+ * manner with the functions [method@GLib.IOChannel.read_chars],
+ * [method@GLib.IOChannel.write_chars], [method@GLib.IOChannel.seek_position],
+ * and [method@GLib.IOChannel.shutdown].
+ *
+ * To add a `GIOChannel` to the main event loop, use [func@GLib.io_add_watch] or
+ * [func@GLib.io_add_watch_full]. Here you specify which events you are
+ * interested in on the `GIOChannel`, and provide a function to be called
+ * whenever these events occur.
+ *
+ * `GIOChannel` instances are created with an initial reference count of 1.
+ * [method@GLib.IOChannel.ref] and [method@GLib.IOChannel.unref] can be used to
+ * increment or decrement the reference count respectively. When the
+ * reference count falls to 0, the `GIOChannel` is freed. (Though it
+ * isn’t closed automatically, unless it was created using
+ * [ctor@GLib.IOChannel.new_file].) Using [func@GLib.io_add_watch] or
+ * [func@GLib.io_add_watch_full] increments a channel’s reference count.
+ *
+ * The new functions [method@GLib.IOChannel.read_chars],
+ * [method@GLib.IOChannel.read_line], [method@GLib.IOChannel.read_line_string],
+ * [method@GLib.IOChannel.read_to_end], [method@GLib.IOChannel.write_chars],
+ * [method@GLib.IOChannel.seek_position], and [method@GLib.IOChannel.flush]
+ * should not be mixed with the deprecated functions
+ * [method@GLib.IOChannel.read], [method@GLib.IOChannel.write], and
+ * [method@GLib.IOChannel.seek] on the same channel.
+ */
 export class IOChannel {
     ptr;
     constructor(...args) {
         const _args = args.length === 1 && Array.isArray(args[0]) ? args[0] : args;
         this.ptr = this.createPtr(_args);
     }
+    /**
+     * Creates a new #GIOChannel given a file descriptor. On UNIX systems
+     * this works for plain files, pipes, and sockets.
+     *
+     * The returned #GIOChannel has a reference count of 1.
+     *
+     * The default encoding for #GIOChannel is UTF-8. If your application
+     * is reading output from a command using via pipe, you may need to set
+     * the encoding to the encoding of the current locale (see
+     * g_get_charset()) with the g_io_channel_set_encoding() function.
+     * By default, the fd passed will not be closed when the final reference
+     * to the #GIOChannel data structure is dropped.
+     *
+     * If you want to read raw binary data without interpretation, then
+     * call the g_io_channel_set_encoding() function with %NULL for the
+     * encoding argument.
+     *
+     * This function is available in GLib on Windows, too, but you should
+     * avoid using it on Windows. The domain of file descriptors and
+     * sockets overlap. There is no way for GLib to know which one you mean
+     * in case the argument you pass to this function happens to be both a
+     * valid file descriptor and socket. If that happens a warning is
+     * issued, and GLib assumes that it is the file descriptor you mean.
+     * @param fd - a file descriptor.
+     */
     static channelUnixNew(fd) {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_unix_new", [
             {
@@ -28,6 +91,10 @@ export class IOChannel {
             },
         ], { type: "boxed", borrowed: true, innerType: "GIOChannel" });
     }
+    /**
+     * Converts an `errno` error number to a #GIOChannelError.
+     * @param en - an `errno` error number, e.g. `EINVAL`
+     */
     static errorFromErrno(en) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_error_from_errno", [
             {
@@ -39,6 +106,11 @@ export class IOChannel {
     static errorQuark() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_error_quark", [], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Close an IO channel. Any pending data to be written will be
+     * flushed, ignoring errors. The channel will not be freed until the
+     * last reference is dropped using g_io_channel_unref().
+     */
     close() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_close", [
             {
@@ -47,6 +119,9 @@ export class IOChannel {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Flushes the write buffer for the GIOChannel.
+     */
     flush() {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_flush", [
@@ -71,6 +146,11 @@ export class IOChannel {
         }
         return result;
     }
+    /**
+     * This function returns a #GIOCondition depending on whether there
+     * is data to be read/space to write data in the internal buffers in
+     * the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set.
+     */
     getBufferCondition() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_get_buffer_condition", [
             {
@@ -79,6 +159,9 @@ export class IOChannel {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the buffer size.
+     */
     getBufferSize() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_get_buffer_size", [
             {
@@ -87,6 +170,9 @@ export class IOChannel {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Returns whether `channel` is buffered.
+     */
     getBuffered() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_get_buffered", [
             {
@@ -95,6 +181,11 @@ export class IOChannel {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the file/socket/whatever associated with `channel` will be closed when `channel` receives its final unref and is
+     * destroyed. The default value of this is %TRUE for channels created
+     * by g_io_channel_new_file (), and %FALSE for all other channels.
+     */
     getCloseOnUnref() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_get_close_on_unref", [
             {
@@ -103,6 +194,11 @@ export class IOChannel {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the encoding for the input/output of the channel.
+     * The internal encoding is always UTF-8. The encoding %NULL
+     * makes the channel safe for binary data.
+     */
     getEncoding() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_get_encoding", [
             {
@@ -111,6 +207,17 @@ export class IOChannel {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the current flags for a #GIOChannel, including read-only
+     * flags such as %G_IO_FLAG_IS_READABLE.
+     *
+     * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE
+     * are cached for internal use by the channel when it is created.
+     * If they should change at some later point (e.g. partial shutdown
+     * of a socket with the UNIX shutdown() function), the user
+     * should immediately call g_io_channel_get_flags() to update
+     * the internal values of these flags.
+     */
     getFlags() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_get_flags", [
             {
@@ -119,6 +226,13 @@ export class IOChannel {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * This returns the string that #GIOChannel uses to determine
+     * where in the file a line break occurs. A value of %NULL
+     * indicates autodetection. Since 2.84, the return value is always
+     * nul-terminated.
+     * @param length - a location to return the length of the line terminator
+     */
     getLineTerm(length) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_get_line_term", [
             {
@@ -135,6 +249,13 @@ export class IOChannel {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Initializes a #GIOChannel struct.
+     *
+     * This is called by each of the above functions when creating a
+     * #GIOChannel, and so is not often needed by the application
+     * programmer (unless you are creating a new type of #GIOChannel).
+     */
     init() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_init", [
             {
@@ -143,6 +264,12 @@ export class IOChannel {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Reads data from a #GIOChannel.
+     * @param buf - a buffer to read the data into (which should be at least
+     * @param count - the number of bytes to read from the #GIOChannel
+     * @param bytesRead - returns the number of bytes actually read
+     */
     read(buf, count, bytesRead) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_read", [
             {
@@ -163,6 +290,12 @@ export class IOChannel {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Replacement for g_io_channel_read() with the new API.
+     * @param buf - a buffer to read data into
+     * @param count - the size of the buffer. Note that the buffer may not be
+     * @param bytesRead - The number of bytes read. This may be
+     */
     readChars(buf, count, bytesRead) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_read_chars", [
@@ -209,6 +342,15 @@ export class IOChannel {
         }
         return result;
     }
+    /**
+     * Reads a line, including the terminating character(s),
+     * from a #GIOChannel into a newly-allocated string.
+     * `str_return` will contain allocated memory if the return
+     * is %G_IO_STATUS_NORMAL.
+     * @param strReturn - The line read from the #GIOChannel, including the
+     * @param length - location to store length of the read data, or %NULL
+     * @param terminatorPos - location to store position of line terminator, or %NULL
+     */
     readLine(strReturn, length, terminatorPos) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_read_line", [
@@ -253,6 +395,11 @@ export class IOChannel {
         }
         return result;
     }
+    /**
+     * Reads a line from a #GIOChannel, using a #GString as a buffer.
+     * @param buffer - a #GString into which the line will be written.
+     * @param terminatorPos - location to store position of line terminator, or %NULL
+     */
     readLineString(buffer, terminatorPos) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_read_line_string", [
@@ -291,6 +438,11 @@ export class IOChannel {
         }
         return result;
     }
+    /**
+     * Reads all the remaining data from the file.
+     * @param strReturn - Location to
+     * @param length - location to store length of the data
+     */
     readToEnd(strReturn, length) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_read_to_end", [
@@ -332,6 +484,11 @@ export class IOChannel {
         }
         return result;
     }
+    /**
+     * Reads a Unicode character from @channel.
+     * This function cannot be called on a channel with %NULL encoding.
+     * @param thechar - a location to return a character
+     */
     readUnichar(thechar) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_read_unichar", [
@@ -363,6 +520,9 @@ export class IOChannel {
         }
         return result;
     }
+    /**
+     * Increments the reference count of a #GIOChannel.
+     */
     ref() {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_ref", [
             {
@@ -377,6 +537,12 @@ export class IOChannel {
         });
         return getObject(ptr, IOChannel);
     }
+    /**
+     * Sets the current position in the #GIOChannel, similar to the standard
+     * library function fseek().
+     * @param offset - an offset, in bytes, which is added to the position specified
+     * @param type - the position in the file, which can be %G_SEEK_CUR (the current
+     */
     seek(offset, type) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_seek", [
             {
@@ -393,6 +559,11 @@ export class IOChannel {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Replacement for g_io_channel_seek() with the new API.
+     * @param offset - The offset in bytes from the position specified by @type
+     * @param type - a #GSeekType. The type %G_SEEK_CUR is only allowed in those
+     */
     seekPosition(offset, type) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_seek_position", [
@@ -425,6 +596,10 @@ export class IOChannel {
         }
         return result;
     }
+    /**
+     * Sets the buffer size.
+     * @param size - the size of the buffer, or 0 to let GLib pick a good size
+     */
     setBufferSize(size) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_set_buffer_size", [
             {
@@ -437,6 +612,28 @@ export class IOChannel {
             },
         ], { type: "undefined" });
     }
+    /**
+     * The buffering state can only be set if the channel's encoding
+     * is %NULL. For any other encoding, the channel must be buffered.
+     *
+     * A buffered channel can only be set unbuffered if the channel's
+     * internal buffers have been flushed. Newly created channels or
+     * channels which have returned %G_IO_STATUS_EOF
+     * not require such a flush. For write-only channels, a call to
+     * g_io_channel_flush () is sufficient. For all other channels,
+     * the buffers may be flushed by a call to g_io_channel_seek_position ().
+     * This includes the possibility of seeking with seek type %G_SEEK_CUR
+     * and an offset of zero. Note that this means that socket-based
+     * channels cannot be set unbuffered once they have had data
+     * read from them.
+     *
+     * On unbuffered channels, it is safe to mix read and write
+     * calls from the new and old APIs, if this is necessary for
+     * maintaining old code.
+     *
+     * The default state of the channel is buffered.
+     * @param buffered - whether to set the channel buffered or unbuffered
+     */
     setBuffered(buffered) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_set_buffered", [
             {
@@ -449,6 +646,15 @@ export class IOChannel {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Whether to close the channel on the final unref of the #GIOChannel
+     * data structure. The default value of this is %TRUE for channels
+     * created by g_io_channel_new_file (), and %FALSE for all other channels.
+     *
+     * Setting this flag to %TRUE for a channel you have already closed
+     * can cause problems when the final reference to the #GIOChannel is dropped.
+     * @param doClose - Whether to close the channel on the final unref of
+     */
     setCloseOnUnref(doClose) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_set_close_on_unref", [
             {
@@ -461,6 +667,43 @@ export class IOChannel {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the encoding for the input/output of the channel.
+     * The internal encoding is always UTF-8. The default encoding
+     * for the external file is UTF-8.
+     *
+     * The encoding %NULL is safe to use with binary data.
+     *
+     * The encoding can only be set if one of the following conditions
+     * is true:
+     *
+     * - The channel was just created, and has not been written to or read from yet.
+     *
+     * - The channel is write-only.
+     *
+     * - The channel is a file, and the file pointer was just repositioned
+     * by a call to g_io_channel_seek_position(). (This flushes all the
+     * internal buffers.)
+     *
+     * - The current encoding is %NULL or UTF-8.
+     *
+     * - One of the (new API) read functions has just returned %G_IO_STATUS_EOF
+     * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
+     *
+     * -  One of the functions g_io_channel_read_chars() or
+     * g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or
+     * %G_IO_STATUS_ERROR. This may be useful in the case of
+     * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
+     * Returning one of these statuses from g_io_channel_read_line(),
+     * g_io_channel_read_line_string(), or g_io_channel_read_to_end()
+     * does not guarantee that the encoding can be changed.
+     *
+     * Channels which do not meet one of the above conditions cannot call
+     * g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if
+     * they are "seekable", cannot call g_io_channel_write_chars() after
+     * calling one of the API "read" functions.
+     * @param encoding - the encoding type
+     */
     setEncoding(encoding) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_set_encoding", [
@@ -490,6 +733,10 @@ export class IOChannel {
         }
         return result;
     }
+    /**
+     * Sets the (writeable) flags in `channel` to (`flags` & %G_IO_FLAG_SET_MASK).
+     * @param flags - the flags to set on the IO channel
+     */
     setFlags(flags) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_set_flags", [
@@ -518,6 +765,12 @@ export class IOChannel {
         }
         return result;
     }
+    /**
+     * This sets the string that #GIOChannel uses to determine
+     * where in the file a line break occurs.
+     * @param lineTerm - The line termination string. Use %NULL for
+     * @param length - The length of the termination string. If -1 is passed, the
+     */
     setLineTerm(length, lineTerm) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_set_line_term", [
             {
@@ -535,6 +788,12 @@ export class IOChannel {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Close an IO channel. Any pending data to be written will be
+     * flushed if `flush` is %TRUE. The channel will not be freed until the
+     * last reference is dropped using g_io_channel_unref().
+     * @param flush - if %TRUE, flush pending
+     */
     shutdown(flush) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_shutdown", [
@@ -563,6 +822,12 @@ export class IOChannel {
         }
         return result;
     }
+    /**
+     * Returns the file descriptor of the #GIOChannel.
+     *
+     * On Windows this function returns the file descriptor or socket of
+     * the #GIOChannel.
+     */
     unixGetFd() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_unix_get_fd", [
             {
@@ -571,6 +836,9 @@ export class IOChannel {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Decrements the reference count of a #GIOChannel.
+     */
     unref() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_unref", [
             {
@@ -579,6 +847,12 @@ export class IOChannel {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Writes data to a #GIOChannel.
+     * @param buf - the buffer containing the data to write
+     * @param count - the number of bytes to write
+     * @param bytesWritten - the number of bytes actually written
+     */
     write(buf, count, bytesWritten) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_write", [
             {
@@ -599,6 +873,17 @@ export class IOChannel {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Replacement for g_io_channel_write() with the new API.
+     *
+     * On seekable channels with encodings other than %NULL or UTF-8, generic
+     * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars ()
+     * may only be made on a channel from which data has been read in the
+     * cases described in the documentation for g_io_channel_set_encoding ().
+     * @param buf - a buffer to write data from
+     * @param count - the size of the buffer. If -1, the buffer
+     * @param bytesWritten - The number of bytes written. This can be nonzero
+     */
     writeChars(buf, count, bytesWritten) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_write_chars", [
@@ -641,6 +926,11 @@ export class IOChannel {
         }
         return result;
     }
+    /**
+     * Writes a Unicode character to @channel.
+     * This function cannot be called on a channel with %NULL encoding.
+     * @param thechar - a character
+     */
     writeUnichar(thechar) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_io_channel_write_unichar", [