--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/protocols/ircv3/purpleircv3capabilities.h Mon Mar 25 21:43:28 2024 -0500
@@ -0,0 +1,172 @@
+/*
+ * Purple - Internet Messaging Library
+ * Copyright (C) Pidgin Developers <devel@pidgin.im>
+ *
+ * Purple is the legal property of its developers, whose names are too numerous
+ * to list here. Please refer to the COPYRIGHT file distributed with this
+ * source distribution.
+ *
+ * This library is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this library; if not, see <https://www.gnu.org/licenses/>.
+ */
+
+#if !defined(PURPLE_IRCV3_GLOBAL_HEADER_INSIDE) && \
+ !defined(PURPLE_IRCV3_COMPILATION)
+# error "only <libpurple/protocols/ircv3.h> may be included directly"
+#endif
+
+#ifndef PURPLE_IRCV3_CAPABILITIES_H
+#define PURPLE_IRCV3_CAPABILITIES_H
+
+#include <glib.h>
+#include <glib-object.h>
+
+#include <gplugin.h>
+#include <gplugin-native.h>
+
+#include <purple.h>
+
+#include "purpleircv3version.h"
+
+G_BEGIN_DECLS
+
+/* https://ircv3.net/specs/extensions/capability-negotiation */
+#define PURPLE_IRCV3_CAPABILITY_CAP_LS_VERSION "302"
+
+/* https://ircv3.net/specs/extensions/sasl-3.2 */
+#define PURPLE_IRCV3_CAPABILITY_SASL "sasl"
+
+/* https://ircv3.net/specs/extensions/server-time */
+#define PURPLE_IRCV3_CAPABILITY_SERVER_TIME "server-time"
+
+#define PURPLE_IRCV3_TYPE_CAPABILITIES (purple_ircv3_capabilities_get_type())
+
+PURPLE_IRCV3_AVAILABLE_IN_ALL
+G_DECLARE_FINAL_TYPE(PurpleIRCv3Capabilities, purple_ircv3_capabilities,
+ PURPLE_IRCV3, CAPABILITIES, GObject)
+
+#include "purpleircv3connection.h"
+#include "purpleircv3message.h"
+
+/**
+ * purple_ircv3_capabilities_register: (skip)
+ * @plugin: The [class@GPlugin.NativePlugin] instance.
+ *
+ * Dynamically registers the PurpleIRCv3Capabilities type.
+ *
+ * Since: 3.0
+ */
+G_GNUC_INTERNAL void purple_ircv3_capabilities_register(GPluginNativePlugin *plugin);
+
+G_GNUC_INTERNAL PurpleIRCv3Capabilities *purple_ircv3_capabilities_new(PurpleIRCv3Connection *connection);
+
+G_GNUC_INTERNAL void purple_ircv3_capabilities_start(PurpleIRCv3Capabilities *capabilities);
+
+G_GNUC_INTERNAL gboolean purple_ircv3_capabilities_message_handler(PurpleIRCv3Message *message, GError **error, gpointer data);
+
+/**
+ * purple_ircv3_capabilities_get_connection:
+ * @capabilities: The instance.
+ *
+ * Gets the PurpleIRCv3Connection object that @capabilities was created with.
+ *
+ * Returns: (transfer none): The connection instance.
+ *
+ * Since: 3.0
+ */
+PURPLE_IRCV3_AVAILABLE_IN_ALL
+PurpleIRCv3Connection *purple_ircv3_capabilities_get_connection(PurpleIRCv3Capabilities *capabilities);
+
+/**
+ * purple_ircv3_capabilities_request:
+ * @capabilities: The instance.
+ * @capability: The capabilities to request.
+ *
+ * This method will send `CAP REQ @capability` to the server. Listen to the
+ * `::ack` and `::nak` signals which will contain the contents of @capability
+ * that was passed in here.
+ *
+ * Since: 3.0
+ */
+PURPLE_IRCV3_AVAILABLE_IN_ALL
+void purple_ircv3_capabilities_request(PurpleIRCv3Capabilities *capabilities, const char *capability);
+
+/**
+ * purple_ircv3_capabilities_lookup:
+ * @capabilities: The instance.
+ * @name: The name of the capability to look for.
+ * @found: (out) (nullable): A return address for a boolean on whether the
+ * capability was advertised or not.
+ *
+ * Gets the value that the @name capability provided if it was advertised. To
+ * determine if the capability was advertised use the @found parameter.
+ *
+ * Returns: The value of the capability named @name.
+ *
+ * Since: 3.0
+ */
+PURPLE_IRCV3_AVAILABLE_IN_ALL
+const char *purple_ircv3_capabilities_lookup(PurpleIRCv3Capabilities *capabilities, const char *name, gboolean *found);
+
+/**
+ * purple_ircv3_capabilities_lookup_and_request:
+ * @capabilities: The instance.
+ * @name: The name of the capability to look for.
+ *
+ * A helper function to call [method@PurpleIRCv3.Capabilities.Lookup] and if
+ * found, call [method@PurpleIRCv3.Capabilities.Request].
+ *
+ * This method ignores the advertised value, so to get that you'll need to call
+ * [method@PurpleIRCv3.Capabilities.Lookup] yourself.
+ *
+ * Also if you need to do something when the server ACK's or NAK's your
+ * request, you're probably better off just using the methods yourself.
+ *
+ * Returns: %TRUE if @name was found and requested, %FALSE otherwise.
+ *
+ * Since: 3.0
+ */
+PURPLE_IRCV3_AVAILABLE_IN_ALL
+gboolean purple_ircv3_capabilities_lookup_and_request(PurpleIRCv3Capabilities *capabilities, const char *name);
+
+/**
+ * purple_ircv3_capabilties_add_wait:
+ * @capabilities: The instance.
+ *
+ * Adds a wait counter to @capabilities. This counter is used to delay the
+ * call of `CAP END` until all capability negotiation has completed. This is
+ * necessary for SASL and may be necessary for other capabilities as well.
+ *
+ * Since: 3.0
+ */
+PURPLE_IRCV3_AVAILABLE_IN_ALL
+void purple_ircv3_capabilities_add_wait(PurpleIRCv3Capabilities *capabilities);
+
+/**
+ * purple_ircv3_capabilties_remove_wait:
+ * @capabilities: The instance.
+ *
+ * Removes a wait counter from @capabilities. Only when this counter reaches 0,
+ * will `CAP END` be called and registration completed.
+ *
+ * This is necessary for SASL and may be necessary for other capabilities as
+ * well.
+ *
+ * Since: 3.0
+ */
+PURPLE_IRCV3_AVAILABLE_IN_ALL
+void purple_ircv3_capabilities_remove_wait(PurpleIRCv3Capabilities *capabilities);
+
+G_END_DECLS
+
+#endif /* PURPLE_IRCV3_CAPABILITIES_H */
