@gtkx/ffi 0.7.0 → 0.9.0

package/dist/generated/gio/simple-async-result.js

@@ -1,585 +0,0 @@
-import { call, NativeError, getObject, isInstantiating, setInstantiating, registerType, } from "@gtkx/ffi";
-import * as GObject from "../gobject/index.js";
-/**
- * As of GLib 2.46, `GSimpleAsyncResult` is deprecated in favor of
- * [class@Gio.Task], which provides a simpler API.
- *
- * `GSimpleAsyncResult` implements [iface@Gio.AsyncResult].
- *
- * `GSimpleAsyncResult` handles [type@Gio.AsyncReadyCallback]s, error
- * reporting, operation cancellation and the final state of an operation,
- * completely transparent to the application. Results can be returned
- * as a pointer e.g. for functions that return data that is collected
- * asynchronously, a boolean value for checking the success or failure
- * of an operation, or a `gssize` for operations which return the number
- * of bytes modified by the operation; all of the simple return cases
- * are covered.
- *
- * Most of the time, an application will not need to know of the details
- * of this API; it is handled transparently, and any necessary operations
- * are handled by [iface@Gio.AsyncResult]’s interface. However, if implementing
- * a new GIO module, for writing language bindings, or for complex
- * applications that need better control of how asynchronous operations
- * are completed, it is important to understand this functionality.
- *
- * `GSimpleAsyncResult`s are tagged with the calling function to ensure
- * that asynchronous functions and their finishing functions are used
- * together correctly.
- *
- * To create a new `GSimpleAsyncResult`, call [ctor@Gio.SimpleAsyncResult.new].
- * If the result needs to be created for a `GError`, use
- * [ctor@Gio.SimpleAsyncResult.new_from_error] or
- * [ctor@Gio.SimpleAsyncResult.new_take_error]. If a `GError` is not available
- * (e.g. the asynchronous operation doesn’t take a `GError` argument),
- * but the result still needs to be created for an error condition, use
- * [ctor@Gio.SimpleAsyncResult.new_error] (or
- * [method@Gio.SimpleAsyncResult.set_error_va] if your application or binding
- * requires passing a variable argument list directly), and the error can then
- * be propagated through the use of
- * [method@Gio.SimpleAsyncResult.propagate_error].
- *
- * An asynchronous operation can be made to ignore a cancellation event by
- * calling [method@Gio.SimpleAsyncResult.set_handle_cancellation] with a
- * `GSimpleAsyncResult` for the operation and `FALSE`. This is useful for
- * operations that are dangerous to cancel, such as close (which would
- * cause a leak if cancelled before being run).
- *
- * `GSimpleAsyncResult` can integrate into GLib’s event loop,
- * [type@GLib.MainLoop], or it can use [type@GLib.Thread]s.
- * [method@Gio.SimpleAsyncResult.complete] will finish an I/O task directly
- * from the point where it is called.
- * [method@Gio.SimpleAsyncResult.complete_in_idle] will finish it from an idle
- * handler in the  thread-default main context (see
- * [method@GLib.MainContext.push_thread_default]) where the `GSimpleAsyncResult`
- * was created. [method@Gio.SimpleAsyncResult.run_in_thread] will run the job in
- * a separate thread and then use
- * [method@Gio.SimpleAsyncResult.complete_in_idle] to deliver the result.
- *
- * To set the results of an asynchronous function,
- * [method@Gio.SimpleAsyncResult.set_op_res_gpointer],
- * [method@Gio.SimpleAsyncResult.set_op_res_gboolean], and
- * [method@Gio.SimpleAsyncResult.set_op_res_gssize]
- * are provided, setting the operation's result to a `gpointer`, `gboolean`, or
- * `gssize`, respectively.
- *
- * Likewise, to get the result of an asynchronous function,
- * [method@Gio.SimpleAsyncResult.get_op_res_gpointer],
- * [method@Gio.SimpleAsyncResult.get_op_res_gboolean], and
- * [method@Gio.SimpleAsyncResult.get_op_res_gssize] are
- * provided, getting the operation’s result as a `gpointer`, `gboolean`, and
- * `gssize`, respectively.
- *
- * For the details of the requirements implementations must respect, see
- * [iface@Gio.AsyncResult].  A typical implementation of an asynchronous
- * operation using `GSimpleAsyncResult` looks something like this:
- *
- * ```c
- * static void
- * baked_cb (Cake    *cake,
- * gpointer user_data)
- * {
- * // In this example, this callback is not given a reference to the cake,
- * // so the GSimpleAsyncResult has to take a reference to it.
- * GSimpleAsyncResult *result = user_data;
- *
- * if (cake == NULL)
- * g_simple_async_result_set_error (result,
- * BAKER_ERRORS,
- * BAKER_ERROR_NO_FLOUR,
- * "Go to the supermarket");
- * else
- * g_simple_async_result_set_op_res_gpointer (result,
- * g_object_ref (cake),
- * g_object_unref);
- *
- *
- * // In this example, we assume that baked_cb is called as a callback from
- * // the mainloop, so it's safe to complete the operation synchronously here.
- * // If, however, _baker_prepare_cake () might call its callback without
- * // first returning to the mainloop — inadvisable, but some APIs do so —
- * // we would need to use g_simple_async_result_complete_in_idle().
- * g_simple_async_result_complete (result);
- * g_object_unref (result);
- * }
- *
- * void
- * baker_bake_cake_async (Baker              *self,
- * guint               radius,
- * GAsyncReadyCallback callback,
- * gpointer            user_data)
- * {
- * GSimpleAsyncResult *simple;
- * Cake               *cake;
- *
- * if (radius < 3)
- * {
- * g_simple_async_report_error_in_idle (G_OBJECT (self),
- * callback,
- * user_data,
- * BAKER_ERRORS,
- * BAKER_ERROR_TOO_SMALL,
- * "%ucm radius cakes are silly",
- * radius);
- * return;
- * }
- *
- * simple = g_simple_async_result_new (G_OBJECT (self),
- * callback,
- * user_data,
- * baker_bake_cake_async);
- * cake = _baker_get_cached_cake (self, radius);
- *
- * if (cake != NULL)
- * {
- * g_simple_async_result_set_op_res_gpointer (simple,
- * g_object_ref (cake),
- * g_object_unref);
- * g_simple_async_result_complete_in_idle (simple);
- * g_object_unref (simple);
- * // Drop the reference returned by _baker_get_cached_cake();
- * // the GSimpleAsyncResult has taken its own reference.
- * g_object_unref (cake);
- * return;
- * }
- *
- * _baker_prepare_cake (self, radius, baked_cb, simple);
- * }
- *
- * Cake *
- * baker_bake_cake_finish (Baker        *self,
- * GAsyncResult *result,
- * GError      **error)
- * {
- * GSimpleAsyncResult *simple;
- * Cake               *cake;
- *
- * g_return_val_if_fail (g_simple_async_result_is_valid (result,
- * G_OBJECT (self),
- * baker_bake_cake_async),
- * NULL);
- *
- * simple = (GSimpleAsyncResult *) result;
- *
- * if (g_simple_async_result_propagate_error (simple, error))
- * return NULL;
- *
- * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
- * return g_object_ref (cake);
- * }
- * ```
- */
-export class SimpleAsyncResult extends GObject.GObject {
-    static glibTypeName = "GSimpleAsyncResult";
-    /**
-     * Creates a #GSimpleAsyncResult.
-     *
-     * The common convention is to create the #GSimpleAsyncResult in the
-     * function that starts the asynchronous operation and use that same
-     * function as the @source_tag.
-     *
-     * If your operation supports cancellation with #GCancellable (which it
-     * probably should) then you should provide the user's cancellable to
-     * g_simple_async_result_set_check_cancellable() immediately after
-     * this function returns.
-     * @param sourceObject - a #GObject, or %NULL.
-     * @param callback - a #GAsyncReadyCallback.
-     * @param userData - user data passed to @callback.
-     * @param sourceTag - the asynchronous function.
-     */
-    constructor(sourceObject, callback, userData, sourceTag) {
-        if (!isInstantiating) {
-            setInstantiating(true);
-            // @ts-ignore
-            super();
-            setInstantiating(false);
-            this.id = call("libgio-2.0.so.0", "g_simple_async_result_new", [
-                {
-                    type: { type: "gobject", borrowed: true },
-                    value: sourceObject?.id ?? sourceObject,
-                    optional: true,
-                },
-                {
-                    type: { type: "callback" },
-                    value: callback,
-                    optional: true,
-                },
-                {
-                    type: { type: "int", size: 64, unsigned: true },
-                    value: userData,
-                    optional: true,
-                },
-                {
-                    type: { type: "int", size: 64, unsigned: true },
-                    value: sourceTag,
-                    optional: true,
-                },
-            ], { type: "gobject", borrowed: true });
-        }
-        else {
-            // @ts-ignore
-            super();
-        }
-    }
-    /**
-     * Creates a #GSimpleAsyncResult from an error condition.
-     * @param sourceObject - a #GObject, or %NULL.
-     * @param callback - a #GAsyncReadyCallback.
-     * @param userData - user data passed to @callback.
-     * @param error - a #GError
-     */
-    static asyncResultNewFromError(error, sourceObject, callback, userData) {
-        const ptr = call("libgio-2.0.so.0", "g_simple_async_result_new_from_error", [
-            {
-                type: { type: "gobject", borrowed: true },
-                value: sourceObject?.id ?? sourceObject,
-                optional: true,
-            },
-            {
-                type: { type: "callback" },
-                value: callback,
-                optional: true,
-            },
-            {
-                type: { type: "int", size: 64, unsigned: true },
-                value: userData,
-                optional: true,
-            },
-            {
-                type: {
-                    type: "boxed",
-                    borrowed: true,
-                    innerType: "GError",
-                    lib: "libgio-2.0.so.0",
-                },
-                value: error?.id ?? error,
-            },
-        ], { type: "gobject", borrowed: false });
-        return getObject(ptr);
-    }
-    /**
-     * Ensures that the data passed to the _finish function of an async
-     * operation is consistent.  Three checks are performed.
-     *
-     * First, `result` is checked to ensure that it is really a
-     * #GSimpleAsyncResult.  Second, `source` is checked to ensure that it
-     * matches the source object of @result.  Third, `source_tag` is
-     * checked to ensure that it is equal to the `source_tag` argument given
-     * to g_simple_async_result_new() (which, by convention, is a pointer
-     * to the _async function corresponding to the _finish function from
-     * which this function is called).  (Alternatively, if either
-     * `source_tag` or @result's source tag is %NULL, then the source tag
-     * check is skipped.)
-     * @param result - the #GAsyncResult passed to the _finish function.
-     * @param source - the #GObject passed to the _finish function.
-     * @param sourceTag - the asynchronous function.
-     */
-    static isValid(result, source, sourceTag) {
-        return call("libgio-2.0.so.0", "g_simple_async_result_is_valid", [
-            {
-                type: { type: "gobject", borrowed: true },
-                value: result?.id ?? result,
-            },
-            {
-                type: { type: "gobject", borrowed: true },
-                value: source?.id ?? source,
-                optional: true,
-            },
-            {
-                type: { type: "int", size: 64, unsigned: true },
-                value: sourceTag,
-                optional: true,
-            },
-        ], { type: "boolean" });
-    }
-    /**
-     * Completes an asynchronous I/O job immediately. Must be called in
-     * the thread where the asynchronous result was to be delivered, as it
-     * invokes the callback directly. If you are in a different thread use
-     * g_simple_async_result_complete_in_idle().
-     *
-     * Calling this function takes a reference to `simple` for as long as
-     * is needed to complete the call.
-     */
-    complete() {
-        call("libgio-2.0.so.0", "g_simple_async_result_complete", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-        ], { type: "undefined" });
-    }
-    /**
-     * Completes an asynchronous function in an idle handler in the
-     * thread-default main context (see [method@GLib.MainContext.push_thread_default])
-     * of the thread that `simple` was initially created in
-     * (and re-pushes that context around the invocation of the callback).
-     *
-     * Calling this function takes a reference to `simple` for as long as
-     * is needed to complete the call.
-     */
-    completeInIdle() {
-        call("libgio-2.0.so.0", "g_simple_async_result_complete_in_idle", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-        ], { type: "undefined" });
-    }
-    /**
-     * Gets the operation result boolean from within the asynchronous result.
-     */
-    getOpResGboolean() {
-        return call("libgio-2.0.so.0", "g_simple_async_result_get_op_res_gboolean", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-        ], { type: "boolean" });
-    }
-    /**
-     * Gets a gssize from the asynchronous result.
-     */
-    getOpResGssize() {
-        return call("libgio-2.0.so.0", "g_simple_async_result_get_op_res_gssize", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-        ], { type: "int", size: 64, unsigned: false });
-    }
-    /**
-     * Propagates an error from within the simple asynchronous result to
-     * a given destination.
-     *
-     * If the #GCancellable given to a prior call to
-     * g_simple_async_result_set_check_cancellable() is cancelled then this
-     * function will return %TRUE with `dest` set appropriately.
-     */
-    propagateError() {
-        const error = { value: null };
-        const result = call("libgio-2.0.so.0", "g_simple_async_result_propagate_error", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-            {
-                type: {
-                    type: "ref",
-                    innerType: {
-                        type: "boxed",
-                        innerType: "GError",
-                        lib: "libglib-2.0.so.0",
-                    },
-                },
-                value: error,
-            },
-        ], { type: "boolean" });
-        if (error.value !== null) {
-            throw new NativeError(error.value);
-        }
-        return result;
-    }
-    /**
-     * Sets a #GCancellable to check before dispatching results.
-     *
-     * This function has one very specific purpose: the provided cancellable
-     * is checked at the time of g_simple_async_result_propagate_error() If
-     * it is cancelled, these functions will return an "Operation was
-     * cancelled" error (%G_IO_ERROR_CANCELLED).
-     *
-     * Implementors of cancellable asynchronous functions should use this in
-     * order to provide a guarantee to their callers that cancelling an
-     * async operation will reliably result in an error being returned for
-     * that operation (even if a positive result for the operation has
-     * already been sent as an idle to the main context to be dispatched).
-     *
-     * The checking described above is done regardless of any call to the
-     * unrelated g_simple_async_result_set_handle_cancellation() function.
-     * @param checkCancellable - a #GCancellable to check, or %NULL to unset
-     */
-    setCheckCancellable(checkCancellable) {
-        call("libgio-2.0.so.0", "g_simple_async_result_set_check_cancellable", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-            {
-                type: { type: "gobject", borrowed: true },
-                value: checkCancellable?.id ?? checkCancellable,
-                optional: true,
-            },
-        ], { type: "undefined" });
-    }
-    /**
-     * Sets the result from a #GError.
-     * @param error - #GError.
-     */
-    setFromError(error) {
-        call("libgio-2.0.so.0", "g_simple_async_result_set_from_error", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-            {
-                type: {
-                    type: "boxed",
-                    borrowed: true,
-                    innerType: "GError",
-                    lib: "libgio-2.0.so.0",
-                },
-                value: error?.id ?? error,
-            },
-        ], { type: "undefined" });
-    }
-    /**
-     * Sets whether to handle cancellation within the asynchronous operation.
-     *
-     * This function has nothing to do with
-     * g_simple_async_result_set_check_cancellable().  It only refers to the
-     * #GCancellable passed to g_simple_async_result_run_in_thread().
-     * @param handleCancellation - a #gboolean.
-     */
-    setHandleCancellation(handleCancellation) {
-        call("libgio-2.0.so.0", "g_simple_async_result_set_handle_cancellation", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-            {
-                type: { type: "boolean" },
-                value: handleCancellation,
-            },
-        ], { type: "undefined" });
-    }
-    /**
-     * Sets the operation result to a boolean within the asynchronous result.
-     * @param opRes - a #gboolean.
-     */
-    setOpResGboolean(opRes) {
-        call("libgio-2.0.so.0", "g_simple_async_result_set_op_res_gboolean", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-            {
-                type: { type: "boolean" },
-                value: opRes,
-            },
-        ], { type: "undefined" });
-    }
-    /**
-     * Sets the operation result within the asynchronous result to
-     * the given @op_res.
-     * @param opRes - a #gssize.
-     */
-    setOpResGssize(opRes) {
-        call("libgio-2.0.so.0", "g_simple_async_result_set_op_res_gssize", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-            {
-                type: { type: "int", size: 64, unsigned: false },
-                value: opRes,
-            },
-        ], { type: "undefined" });
-    }
-    /**
-     * Gets the source object from a [iface@Gio.AsyncResult].
-     */
-    getSourceObject() {
-        const ptr = call("libgio-2.0.so.0", "g_async_result_get_source_object", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-        ], { type: "gobject", borrowed: true });
-        if (ptr === null)
-            return null;
-        return getObject(ptr);
-    }
-    /**
-     * Gets the user data from a [iface@Gio.AsyncResult].
-     */
-    getUserData() {
-        return call("libgio-2.0.so.0", "g_async_result_get_user_data", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-        ], { type: "int", size: 64, unsigned: true });
-    }
-    /**
-     * Checks if `res` has the given `source_tag` (generally a function
-     * pointer indicating the function `res` was created by).
-     * @param sourceTag - an application-defined tag
-     */
-    isTagged(sourceTag) {
-        return call("libgio-2.0.so.0", "g_async_result_is_tagged", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-            {
-                type: { type: "int", size: 64, unsigned: true },
-                value: sourceTag,
-                optional: true,
-            },
-        ], { type: "boolean" });
-    }
-    /**
-     * If `res` is a [class@Gio.SimpleAsyncResult], this is equivalent to
-     * [method@Gio.SimpleAsyncResult.propagate_error]. Otherwise it returns
-     * `FALSE`.
-     *
-     * This can be used for legacy error handling in async `*_finish()`
-     * wrapper functions that traditionally handled [class@Gio.SimpleAsyncResult]
-     * error returns themselves rather than calling into the virtual method.
-     * This should not be used in new code; [iface@Gio.AsyncResult] errors that are
-     * set by virtual methods should also be extracted by virtual methods,
-     * to enable subclasses to chain up correctly.
-     */
-    legacyPropagateError() {
-        const error = { value: null };
-        const result = call("libgio-2.0.so.0", "g_async_result_legacy_propagate_error", [
-            {
-                type: { type: "gobject" },
-                value: this.id,
-            },
-            {
-                type: {
-                    type: "ref",
-                    innerType: {
-                        type: "boxed",
-                        innerType: "GError",
-                        lib: "libglib-2.0.so.0",
-                    },
-                },
-                value: error,
-            },
-        ], { type: "boolean" });
-        if (error.value !== null) {
-            throw new NativeError(error.value);
-        }
-        return result;
-    }
-    connect(signal, handler, after = false) {
-        const selfType = { type: "gobject", borrowed: true };
-        const argTypes = [selfType];
-        const returnType = undefined;
-        const wrappedHandler = (...args) => {
-            const self = getObject(args[0]);
-            return handler(self, ...args.slice(1));
-        };
-        return call("libgio-2.0.so.0", "g_signal_connect_closure", [
-            { type: { type: "gobject" }, value: this.id },
-            { type: { type: "string" }, value: signal },
-            {
-                type: { type: "callback", argTypes, returnType },
-                value: wrappedHandler,
-            },
-            { type: { type: "boolean" }, value: after },
-        ], { type: "int", size: 64, unsigned: true });
-    }
-}
-registerType(SimpleAsyncResult);