@gtkx/ffi 0.9.4 → 0.10.1

package/dist/generated/gio/dtls-server-connection.d.ts

@@ -1,4 +1,11 @@
 import { NativeObject } from "../../native/base.js";
+import { TlsCertificateFlags, TlsChannelBindingType, TlsProtocolVersion, TlsRehandshakeMode } from "./enums.js";
+import { AsyncResult } from "./async-result.js";
+import { Cancellable } from "./cancellable.js";
+import { TlsCertificate } from "./tls-certificate.js";
+import { TlsDatabase } from "./tls-database.js";
+import { TlsInteraction } from "./tls-interaction.js";
+import * as GLib from "../glib/index.js";
 /**
  * `GDtlsServerConnection` is the server-side subclass of
  * {@link Gio.DtlsConnection}, representing a server-side DTLS connection.
@@ -6,4 +13,465 @@ import { NativeObject } from "../../native/base.js";
 export declare class DtlsServerConnection extends NativeObject {
     static readonly glibTypeName: string;
     static readonly objectType: "interface";
+    /**
+     * Checks on the readiness of `datagram_based` to perform operations. The
+     * operations specified in `condition` are checked for and masked against the
+     * currently-satisfied conditions on `datagram_based`. The result is returned.
+     *
+     * %G_IO_IN will be set in the return value if data is available to read with
+     * g_datagram_based_receive_messages(), or if the connection is closed remotely
+     * (EOS); and if the datagram_based has not been closed locally using some
+     * implementation-specific method (such as g_socket_close() or
+     * g_socket_shutdown() with `shutdown_read` set, if it’s a #GSocket).
+     *
+     * If the connection is shut down or closed (by calling g_socket_close() or
+     * g_socket_shutdown() with `shutdown_read` set, if it’s a #GSocket, for
+     * example), all calls to this function will return %G_IO_ERROR_CLOSED.
+     *
+     * %G_IO_OUT will be set if it is expected that at least one byte can be sent
+     * using g_datagram_based_send_messages() without blocking. It will not be set
+     * if the datagram_based has been closed locally.
+     *
+     * %G_IO_HUP will be set if the connection has been closed locally.
+     *
+     * %G_IO_ERR will be set if there was an asynchronous error in transmitting data
+     * previously enqueued using g_datagram_based_send_messages().
+     *
+     * Note that on Windows, it is possible for an operation to return
+     * %G_IO_ERROR_WOULD_BLOCK even immediately after
+     * g_datagram_based_condition_check() has claimed that the #GDatagramBased is
+     * ready for writing. Rather than calling g_datagram_based_condition_check() and
+     * then writing to the #GDatagramBased if it succeeds, it is generally better to
+     * simply try writing right away, and try again later if the initial attempt
+     * returns %G_IO_ERROR_WOULD_BLOCK.
+     *
+     * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in `condition`; these
+     * conditions will always be set in the output if they are true. Apart from
+     * these flags, the output is guaranteed to be masked by `condition`.
+     *
+     * This call never blocks.
+     * @param condition - a #GIOCondition mask to check
+     */
+    conditionCheck(condition: GLib.IOCondition): GLib.IOCondition;
+    /**
+     * Waits for up to `timeout` microseconds for condition to become true on
+     * `datagram_based`. If the condition is met, %TRUE is returned.
+     *
+     * If `cancellable` is cancelled before the condition is met, or if `timeout` is
+     * reached before the condition is met, then %FALSE is returned and `error` is
+     * set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT).
+     * @param condition - a #GIOCondition mask to wait for
+     * @param timeout - the maximum time (in microseconds) to wait, 0 to not block, or -1
+     * @param cancellable - a #GCancellable
+     */
+    conditionWait(condition: GLib.IOCondition, timeout: number, cancellable?: Cancellable): boolean;
+    /**
+     * Creates a #GSource that can be attached to a #GMainContext to monitor for
+     * the availability of the specified `condition` on the #GDatagramBased. The
+     * #GSource keeps a reference to the `datagram_based`.
+     *
+     * The callback on the source is of the #GDatagramBasedSourceFunc type.
+     *
+     * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in `condition`; these
+     * conditions will always be reported in the callback if they are true.
+     *
+     * If non-%NULL, `cancellable` can be used to cancel the source, which will
+     * cause the source to trigger, reporting the current condition (which is
+     * likely 0 unless cancellation happened at the same time as a condition
+     * change). You can check for this in the callback using
+     * g_cancellable_is_cancelled().
+     * @param condition - a #GIOCondition mask to monitor
+     * @param cancellable - a #GCancellable
+     */
+    createSource(condition: GLib.IOCondition, cancellable?: Cancellable): GLib.Source;
+    /**
+     * Receive one or more data messages from `datagram_based` in one go.
+     *
+     * `messages` must point to an array of #GInputMessage structs and
+     * `num_messages` must be the length of this array. Each #GInputMessage
+     * contains a pointer to an array of #GInputVector structs describing the
+     * buffers that the data received in each message will be written to.
+     *
+     * `flags` modify how all messages are received. The commonly available
+     * arguments for this are available in the #GSocketMsgFlags enum, but the
+     * values there are the same as the system values, and the flags
+     * are passed in as-is, so you can pass in system-specific flags too. These
+     * flags affect the overall receive operation. Flags affecting individual
+     * messages are returned in #GInputMessage.flags.
+     *
+     * The other members of #GInputMessage are treated as described in its
+     * documentation.
+     *
+     * If `timeout` is negative the call will block until `num_messages` have been
+     * received, the connection is closed remotely (EOS), `cancellable` is cancelled,
+     * or an error occurs.
+     *
+     * If `timeout` is 0 the call will return up to `num_messages` without blocking,
+     * or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system
+     * to be received.
+     *
+     * If `timeout` is positive the call will block on the same conditions as if
+     * `timeout` were negative. If the timeout is reached
+     * before any messages are received, %G_IO_ERROR_TIMED_OUT is returned,
+     * otherwise it will return the number of messages received before timing out.
+     * (Note: This is effectively the behaviour of `MSG_WAITFORONE` with
+     * recvmmsg().)
+     *
+     * To be notified when messages are available, wait for the %G_IO_IN condition.
+     * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
+     * g_datagram_based_receive_messages() even if you were previously notified of a
+     * %G_IO_IN condition.
+     *
+     * If the remote peer closes the connection, any messages queued in the
+     * underlying receive buffer will be returned, and subsequent calls to
+     * g_datagram_based_receive_messages() will return 0 (with no error set).
+     *
+     * If the connection is shut down or closed (by calling g_socket_close() or
+     * g_socket_shutdown() with `shutdown_read` set, if it’s a #GSocket, for
+     * example), all calls to this function will return %G_IO_ERROR_CLOSED.
+     *
+     * On error -1 is returned and `error` is set accordingly. An error will only
+     * be returned if zero messages could be received; otherwise the number of
+     * messages successfully received before the error will be returned. If
+     * `cancellable` is cancelled, %G_IO_ERROR_CANCELLED is returned as with any
+     * other error.
+     * @param messages - an array of #GInputMessage structs
+     * @param numMessages - the number of elements in `messages`
+     * @param flags - an int containing #GSocketMsgFlags flags for the overall operation
+     * @param timeout - the maximum time (in microseconds) to wait, 0 to not block, or -1
+     * @param cancellable - a %GCancellable
+     */
+    receiveMessages(messages: number[], numMessages: number, flags: number, timeout: number, cancellable?: Cancellable): number;
+    /**
+     * Send one or more data messages from `datagram_based` in one go.
+     *
+     * `messages` must point to an array of #GOutputMessage structs and
+     * `num_messages` must be the length of this array. Each #GOutputMessage
+     * contains an address to send the data to, and a pointer to an array of
+     * #GOutputVector structs to describe the buffers that the data to be sent
+     * for each message will be gathered from.
+     *
+     * `flags` modify how the message is sent. The commonly available arguments
+     * for this are available in the #GSocketMsgFlags enum, but the
+     * values there are the same as the system values, and the flags
+     * are passed in as-is, so you can pass in system-specific flags too.
+     *
+     * The other members of #GOutputMessage are treated as described in its
+     * documentation.
+     *
+     * If `timeout` is negative the call will block until `num_messages` have been
+     * sent, `cancellable` is cancelled, or an error occurs.
+     *
+     * If `timeout` is 0 the call will send up to `num_messages` without blocking,
+     * or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages.
+     *
+     * If `timeout` is positive the call will block on the same conditions as if
+     * `timeout` were negative. If the timeout is reached before any messages are
+     * sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number
+     * of messages sent before timing out.
+     *
+     * To be notified when messages can be sent, wait for the %G_IO_OUT condition.
+     * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
+     * g_datagram_based_send_messages() even if you were previously notified of a
+     * %G_IO_OUT condition. (On Windows in particular, this is very common due to
+     * the way the underlying APIs work.)
+     *
+     * If the connection is shut down or closed (by calling g_socket_close() or
+     * g_socket_shutdown() with `shutdown_write` set, if it’s a #GSocket, for
+     * example), all calls to this function will return %G_IO_ERROR_CLOSED.
+     *
+     * On error -1 is returned and `error` is set accordingly. An error will only
+     * be returned if zero messages could be sent; otherwise the number of messages
+     * successfully sent before the error will be returned. If `cancellable` is
+     * cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error.
+     * @param messages - an array of #GOutputMessage structs
+     * @param numMessages - the number of elements in `messages`
+     * @param flags - an int containing #GSocketMsgFlags flags
+     * @param timeout - the maximum time (in microseconds) to wait, 0 to not block, or -1
+     * @param cancellable - a %GCancellable
+     */
+    sendMessages(messages: number[], numMessages: number, flags: number, timeout: number, cancellable?: Cancellable): number;
+    /**
+     * Close the DTLS connection. This is equivalent to calling
+     * g_dtls_connection_shutdown() to shut down both sides of the connection.
+     *
+     * Closing a #GDtlsConnection waits for all buffered but untransmitted data to
+     * be sent before it completes. It then sends a `close_notify` DTLS alert to the
+     * peer and may wait for a `close_notify` to be received from the peer. It does
+     * not close the underlying #GDtlsConnection:base-socket; that must be closed
+     * separately.
+     *
+     * Once `conn` is closed, all other operations will return %G_IO_ERROR_CLOSED.
+     * Closing a #GDtlsConnection multiple times will not return an error.
+     *
+     * #GDtlsConnections 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.
+     *
+     * If `cancellable` is cancelled, the #GDtlsConnection may be left
+     * partially-closed and any pending untransmitted data may be lost. Call
+     * g_dtls_connection_close() again to complete closing the #GDtlsConnection.
+     * @param cancellable - a #GCancellable, or %NULL
+     */
+    close(cancellable?: Cancellable): boolean;
+    /**
+     * Finish an asynchronous TLS close operation. See g_dtls_connection_close()
+     * for more information.
+     * @param result - a #GAsyncResult
+     */
+    closeFinish(result: AsyncResult): boolean;
+    /**
+     * Used by #GDtlsConnection implementations to emit the
+     * #GDtlsConnection::accept-certificate signal.
+     * @param peerCert - the peer's #GTlsCertificate
+     * @param errors - the problems with `peer_cert`
+     */
+    emitAcceptCertificate(peerCert: TlsCertificate, errors: TlsCertificateFlags): boolean;
+    /**
+     * Gets `conn`'s certificate, as set by
+     * g_dtls_connection_set_certificate().
+     */
+    getCertificate(): TlsCertificate | null;
+    /**
+     * Query the TLS backend for TLS channel binding data of `type` for `conn`.
+     *
+     * This call retrieves TLS channel binding data as specified in RFC
+     * [5056](https://tools.ietf.org/html/rfc5056), RFC
+     * [5929](https://tools.ietf.org/html/rfc5929), and related RFCs.  The
+     * binding data is returned in `data`.  The `data` is resized by the callee
+     * using #GByteArray buffer management and will be freed when the `data`
+     * is destroyed by g_byte_array_unref(). If `data` is %NULL, it will only
+     * check whether TLS backend is able to fetch the data (e.g. whether `type`
+     * is supported by the TLS backend). It does not guarantee that the data
+     * will be available though.  That could happen if TLS connection does not
+     * support `type` or the binding data is not available yet due to additional
+     * negotiation or input required.
+     * @param type - #GTlsChannelBindingType type of data to fetch
+     * @param data - #GByteArray is
+     */
+    getChannelBindingData(type: TlsChannelBindingType, data?: GLib.ByteArray): boolean;
+    /**
+     * Returns the name of the current DTLS ciphersuite, or %NULL if the
+     * connection has not handshaked or has been closed. Beware that the TLS
+     * backend may use any of multiple different naming conventions, because
+     * OpenSSL and GnuTLS have their own ciphersuite naming conventions that
+     * are different from each other and different from the standard, IANA-
+     * registered ciphersuite names. The ciphersuite name is intended to be
+     * displayed to the user for informative purposes only, and parsing it
+     * is not recommended.
+     */
+    getCiphersuiteName(): string | null;
+    /**
+     * Gets the certificate database that `conn` uses to verify
+     * peer certificates. See g_dtls_connection_set_database().
+     */
+    getDatabase(): TlsDatabase | null;
+    /**
+     * Get the object that will be used to interact with the user. It will be used
+     * for things like prompting the user for passwords. If %NULL is returned, then
+     * no user interaction will occur for this connection.
+     */
+    getInteraction(): TlsInteraction | null;
+    /**
+     * Gets the name of the application-layer protocol negotiated during
+     * the handshake.
+     *
+     * If the peer did not use the ALPN extension, or did not advertise a
+     * protocol that matched one of `conn`'s protocols, or the TLS backend
+     * does not support ALPN, then this will be %NULL. See
+     * g_dtls_connection_set_advertised_protocols().
+     */
+    getNegotiatedProtocol(): string | null;
+    /**
+     * Gets `conn`'s peer's certificate after the handshake has completed
+     * or failed. (It is not set during the emission of
+     * #GDtlsConnection::accept-certificate.)
+     */
+    getPeerCertificate(): TlsCertificate | null;
+    /**
+     * Gets the errors associated with validating `conn`'s peer's
+     * certificate, after the handshake has completed or failed. (It is
+     * not set during the emission of #GDtlsConnection::accept-certificate.)
+     */
+    getPeerCertificateErrors(): TlsCertificateFlags;
+    /**
+     * Returns the current DTLS protocol version, which may be
+     * %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or
+     * has been closed, or if the TLS backend has implemented a protocol version
+     * that is not a recognized #GTlsProtocolVersion.
+     */
+    getProtocolVersion(): TlsProtocolVersion;
+    /**
+     * Gets `conn` rehandshaking mode. See
+     * g_dtls_connection_set_rehandshake_mode() for details.
+     */
+    getRehandshakeMode(): TlsRehandshakeMode;
+    /**
+     * Tests whether or not `conn` expects a proper TLS close notification
+     * when the connection is closed. See
+     * g_dtls_connection_set_require_close_notify() for details.
+     */
+    getRequireCloseNotify(): boolean;
+    /**
+     * Attempts a TLS handshake on `conn`.
+     *
+     * On the client side, it is never necessary to call this method;
+     * although the connection needs to perform a handshake after
+     * connecting, #GDtlsConnection will handle this for you automatically
+     * when you try to send or receive data on the connection. You can call
+     * g_dtls_connection_handshake() manually if you want to know whether
+     * the initial handshake succeeded or failed (as opposed to just
+     * immediately trying to use `conn` to read or write, in which case,
+     * if it fails, it may not be possible to tell if it failed before
+     * or after completing the handshake), but beware that servers may reject
+     * client authentication after the handshake has completed, so a
+     * successful handshake does not indicate the connection will be usable.
+     *
+     * Likewise, on the server side, although a handshake is necessary at
+     * the beginning of the communication, you do not need to call this
+     * function explicitly unless you want clearer error reporting.
+     *
+     * Previously, calling g_dtls_connection_handshake() after the initial
+     * handshake would trigger a rehandshake; however, this usage was
+     * deprecated in GLib 2.60 because rehandshaking was removed from the
+     * TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after
+     * the initial handshake will no longer do anything.
+     *
+     * #GDtlsConnection::accept_certificate may be emitted during the
+     * handshake.
+     * @param cancellable - a #GCancellable, or %NULL
+     */
+    handshake(cancellable?: Cancellable): boolean;
+    /**
+     * Finish an asynchronous TLS handshake operation. See
+     * g_dtls_connection_handshake() for more information.
+     * @param result - a #GAsyncResult.
+     */
+    handshakeFinish(result: AsyncResult): boolean;
+    /**
+     * Sets the list of application-layer protocols to advertise that the
+     * caller is willing to speak on this connection. The
+     * Application-Layer Protocol Negotiation (ALPN) extension will be
+     * used to negotiate a compatible protocol with the peer; use
+     * g_dtls_connection_get_negotiated_protocol() to find the negotiated
+     * protocol after the handshake.  Specifying %NULL for the the value
+     * of `protocols` will disable ALPN negotiation.
+     *
+     * See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
+     * for a list of registered protocol IDs.
+     * @param protocols - a %NULL-terminated
+     */
+    setAdvertisedProtocols(protocols?: string[]): void;
+    /**
+     * This sets the certificate that `conn` will present to its peer
+     * during the TLS handshake. For a #GDtlsServerConnection, it is
+     * mandatory to set this, and that will normally be done at construct
+     * time.
+     *
+     * For a #GDtlsClientConnection, this is optional. If a handshake fails
+     * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
+     * requires a certificate, and if you try connecting again, you should
+     * call this method first. You can call
+     * g_dtls_client_connection_get_accepted_cas() on the failed connection
+     * to get a list of Certificate Authorities that the server will
+     * accept certificates from.
+     *
+     * (It is also possible that a server will allow the connection with
+     * or without a certificate; in that case, if you don't provide a
+     * certificate, you can tell that the server requested one by the fact
+     * that g_dtls_client_connection_get_accepted_cas() will return
+     * non-%NULL.)
+     * @param certificate - the certificate to use for `conn`
+     */
+    setCertificate(certificate: TlsCertificate): void;
+    /**
+     * Sets the certificate database that is used to verify peer certificates.
+     * This is set to the default database by default. See
+     * g_tls_backend_get_default_database(). If set to %NULL, then
+     * peer certificate validation will always set the
+     * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
+     * #GDtlsConnection::accept-certificate will always be emitted on
+     * client-side connections, unless that bit is not set in
+     * #GDtlsClientConnection:validation-flags).
+     *
+     * There are nonintuitive security implications when using a non-default
+     * database. See #GDtlsConnection:database for details.
+     * @param database - a #GTlsDatabase
+     */
+    setDatabase(database?: TlsDatabase): void;
+    /**
+     * Set the object that will be used to interact with the user. It will be used
+     * for things like prompting the user for passwords.
+     *
+     * The `interaction` argument will normally be a derived subclass of
+     * #GTlsInteraction. %NULL can also be provided if no user interaction
+     * should occur for this connection.
+     * @param interaction - an interaction object, or %NULL
+     */
+    setInteraction(interaction?: TlsInteraction): void;
+    /**
+     * Since GLib 2.64, changing the rehandshake mode is no longer supported
+     * and will have no effect. With TLS 1.3, rehandshaking has been removed from
+     * the TLS protocol, replaced by separate post-handshake authentication and
+     * rekey operations.
+     * @param mode - the rehandshaking mode
+     */
+    setRehandshakeMode(mode: TlsRehandshakeMode): void;
+    /**
+     * Sets whether or not `conn` expects a proper TLS close notification
+     * before the connection is closed. If this is %TRUE (the default),
+     * then `conn` will expect to receive a TLS close notification from its
+     * peer before the connection is closed, and will return a
+     * %G_TLS_ERROR_EOF error if the connection is closed without proper
+     * notification (since this may indicate a network error, or
+     * man-in-the-middle attack).
+     *
+     * In some protocols, the application will know whether or not the
+     * connection was closed cleanly based on application-level data
+     * (because the application-level data includes a length field, or is
+     * somehow self-delimiting); in this case, the close notify is
+     * redundant and may be omitted. You
+     * can use g_dtls_connection_set_require_close_notify() to tell `conn`
+     * to allow an "unannounced" connection close, in which case the close
+     * will show up as a 0-length read, as in a non-TLS
+     * #GDatagramBased, and it is up to the application to check that
+     * the data has been fully received.
+     *
+     * Note that this only affects the behavior when the peer closes the
+     * connection; when the application calls g_dtls_connection_close_async() on
+     * `conn` itself, this will send a close notification regardless of the
+     * setting of this property. If you explicitly want to do an unclean
+     * close, you can close `conn`'s #GDtlsConnection:base-socket rather
+     * than closing `conn` itself.
+     * @param requireCloseNotify - whether or not to require close notification
+     */
+    setRequireCloseNotify(requireCloseNotify: boolean): void;
+    /**
+     * Shut down part or all of a DTLS connection.
+     *
+     * If `shutdown_read` is %TRUE then the receiving side of the connection is shut
+     * down, and further reading is disallowed. Subsequent calls to
+     * g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED.
+     *
+     * If `shutdown_write` is %TRUE then the sending side of the connection is shut
+     * down, and further writing is disallowed. Subsequent calls to
+     * g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED.
+     *
+     * It is allowed for both `shutdown_read` and `shutdown_write` to be TRUE — this
+     * is equivalent to calling g_dtls_connection_close().
+     *
+     * If `cancellable` is cancelled, the #GDtlsConnection may be left
+     * partially-closed and any pending untransmitted data may be lost. Call
+     * g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection.
+     * @param shutdownRead - %TRUE to stop reception of incoming datagrams
+     * @param shutdownWrite - %TRUE to stop sending outgoing datagrams
+     * @param cancellable - a #GCancellable, or %NULL
+     */
+    shutdown(shutdownRead: boolean, shutdownWrite: boolean, cancellable?: Cancellable): boolean;
+    /**
+     * Finish an asynchronous TLS shutdown operation. See
+     * g_dtls_connection_shutdown() for more information.
+     * @param result - a #GAsyncResult
+     */
+    shutdownFinish(result: AsyncResult): boolean;
 }