--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/libpurple/purplecommandmanager.h Mon Nov 04 20:12:42 2024 -0600
@@ -0,0 +1,228 @@
+/*
+ * 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_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
+# error "only <purple.h> may be included directly"
+#endif
+
+#ifndef PURPLE_COMMAND_MANAGER_H
+#define PURPLE_COMMAND_MANAGER_H
+
+#include <glib.h>
+#include <glib-object.h>
+
+#include "purplecommand.h"
+#include "purpleconversation.h"
+#include "purpleversion.h"
+
+G_BEGIN_DECLS
+
+/**
+ * PurpleCommandManager:
+ *
+ * A manager of [class@Command] objects.
+ *
+ * libpurple, user interfaces, and plugins can manage the commands that are
+ * available with [method@CommandManager.add] and
+ * [method@CommandManager.remove].
+ *
+ * User interfaces can use [method@CommandManager.find_and_execute] to quickly
+ * find and execute a command. They can also use
+ * [method@CommandManager.find_all] to get a list of all commands which can be
+ * presented to a user.
+ *
+ * Both [method@CommandManager.find] and [method@CommandManager.find_all] take
+ * an optional [class@Conversation] parameter. If it is not %NULL, its
+ * [property@Conversation:tags] property will be searched with
+ * [method@Tags.contains] using the [property@Command:tags] as the needle to
+ * determine which commands are available for the [class@Conversation].
+ *
+ * When plugins are being unloaded, they should call
+ * [method@CommandManager.remove_all_with_source] to remove their commands.
+ *
+ * Since: 3.0
+ */
+
+#define PURPLE_TYPE_COMMAND_MANAGER (purple_command_manager_get_type())
+
+PURPLE_AVAILABLE_IN_3_0
+G_DECLARE_FINAL_TYPE(PurpleCommandManager, purple_command_manager, PURPLE,
+ COMMAND_MANAGER, GObject)
+
+/**
+ * purple_command_manager_add:
+ * @manager: The instance.
+ * @command: (transfer full): The new command to add.
+ *
+ * Adds @command to @manager.
+ *
+ * If @manager already has a command with a matching name and source, @command
+ * will not be added but ownership will still be taken.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_command_manager_add(PurpleCommandManager *manager, PurpleCommand *command);
+
+/**
+ * purple_command_manager_find:
+ * @manager: The instance.
+ * @conversation: (nullable): An optional conversation.
+ * @name: The name of the command.
+ *
+ * Finds the command with a name of @name with the highest priority.
+ *
+ * If @conversation is not %NULL commands will be filtered to only include
+ * those that are valid for @conversation by using [method@Tags.contains] on
+ * @conversation with the tags of the found commands.
+ *
+ * Returns: (transfer none): The command if found, otherwise %NULL.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+PurpleCommand *purple_command_manager_find(PurpleCommandManager *manager, PurpleConversation *conversation, const char *name);
+
+/**
+ * purple_command_manager_find_all:
+ * @manager: The instance.
+ * @conversation: (nullable): An optional conversation.
+ * @name: The name of the command.
+ *
+ * Finds all commands that match @name in @manager.
+ *
+ * If @conversation is not %NULL, [method@Tags.contains] will be used to filter
+ * out commands whose tags don't match @conversation.
+ *
+ * Returns: (transfer full): The list of found plugins which could be empty.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+GListModel *purple_command_manager_find_all(PurpleCommandManager *manager, PurpleConversation *conversation, const char *name);
+
+/**
+ * purple_command_manager_find_and_execute:
+ * @manager: The instance.
+ * @conversation: The conversation to use.
+ * @command_line: The command line including the name and arguments.
+ *
+ * Attempts to find a [class@Command] in @manager and execute it.
+ *
+ * @command_line should be a space separate string of the command name and any
+ * arguments. It should not include a leading `/` or any other prefix.
+ *
+ * This method is a helper around [method@CommandManager.find] and
+ * [method@Command.execute].
+ *
+ * Returns: %TRUE if a command was found and executed, otherwise %FALSE.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+gboolean purple_command_manager_find_and_execute(PurpleCommandManager *manager, PurpleConversation *conversation, const char *command_line);
+
+/**
+ * purple_command_manager_get_commands_for_conversation:
+ * @manager: The instance.
+ * @conversation: The conversation.
+ *
+ * Gets a list of [class@Command]'s that are available for @conversation.
+ *
+ * Internally this filters the list of commands with [method@Tags.contains] to
+ * check that all of [property@Command:tags] are contained in
+ * [property@Conversation:tags].
+ *
+ * Returns: (transfer full): The list of commands, which may be empty.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+GListModel *purple_command_manager_get_commands_for_conversation(PurpleCommandManager *manager, PurpleConversation *conversation);
+
+/**
+ * purple_command_manager_get_default:
+ *
+ * Gets the default instance that libpurple is using.
+ *
+ * Returns: (transfer none): The instance.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+PurpleCommandManager *purple_command_manager_get_default(void);
+
+/**
+ * purple_command_manager_get_default_as_model:
+ *
+ * Gets the default instance of the manager but cast to [iface@Gio.ListModel].
+ *
+ * Returns: (transfer none): The manager cast as a [iface@Gio.ListModel].
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+GListModel *purple_command_manager_get_default_as_model(void);
+
+/**
+ * purple_command_manager_new:
+ *
+ * Creates a new instance.
+ *
+ * This is typically only used by libpurple but you can get the default
+ * instance that libpurple is using with [func@CommandManager.get_default].
+ *
+ * Returns: (transfer full): The new instance.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+PurpleCommandManager *purple_command_manager_new(void);
+
+/**
+ * purple_command_manager_remove:
+ * @manager: The instance.
+ * @name: The name of the command.
+ * @source: The source of the command.
+ *
+ * Attempts to remove the first command with @name and @source from @manager.
+ *
+ * Returns: %TRUE if a command is found and removed, otherwise %FALSE.
+ */
+PURPLE_AVAILABLE_IN_3_0
+gboolean purple_command_manager_remove(PurpleCommandManager *manager, const char *name, const char *source);
+
+/**
+ * purple_command_manager_remove_all_with_source:
+ * @manager: The instance.
+ * @source: The source whose commands to remove.
+ *
+ * Removes all commands from @manager that have a source of @source.
+ *
+ * Since: 3.0
+ */
+PURPLE_AVAILABLE_IN_3_0
+void purple_command_manager_remove_all_with_source(PurpleCommandManager *manager, const char *source);
+
+G_END_DECLS
+
+#endif /* PURPLE_COMMAND_MANAGER_H */
