libpurple/purplecommand.h

/*
 * 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_H
#define PURPLE_COMMAND_H

#include <glib.h>
#include <glib-object.h>

#include "purpleconversation.h"
#include "purpletags.h"
#include "purpleversion.h"

G_BEGIN_DECLS

/**
 * PurpleCommand:
 *
 * An object that represents a command.
 *
 * See the [Commands Overview](section-commands.html) for more information.
 *
 * Since: 3.0
 */

#define PURPLE_TYPE_COMMAND (purple_command_get_type())

PURPLE_AVAILABLE_IN_3_0
G_DECLARE_FINAL_TYPE(PurpleCommand, purple_command, PURPLE, COMMAND, GObject)

/**
 * purple_command_execute:
 * @command: The instance.
 * @conversation: (nullable): The conversation where the command was run.
 * @params: (nullable): The parameters for the command.
 *
 * Emits the [signal@Command::executed] signal.
 *
 * User interfaces should call this method when the user wants to execute the
 * command.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
void purple_command_execute(PurpleCommand *command, PurpleConversation *conversation, const char *params);

/**
 * purple_command_executev:
 * @command: The instance.
 * @conversation: (nullable): The conversation where the command was run.
 * @params: (nullable): The parameters for the command.
 *
 * Emits the [signal@Command::executed] signal.
 *
 * User interfaces should call this method when the user wants to execute the
 * command.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
void purple_command_executev(PurpleCommand *command, PurpleConversation *conversation, GStrv params);

/**
 * purple_command_get_icon_name:
 * @command: The instance.
 *
 * Gets the icon name of @command.
 *
 * Returns: (transfer none) (nullable): The icon-name if set, otherwise %NULL.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
const char *purple_command_get_icon_name(PurpleCommand *command);

/**
 * purple_command_get_last_used:
 * @command: The instance.
 *
 * Gets the last used date time of @command.
 *
 * Returns: (nullable): The time that @command was last used or %NULL.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
GDateTime *purple_command_get_last_used(PurpleCommand *command);

/**
 * purple_command_get_name:
 * @command: The instance.
 *
 * Gets the name of the command.
 *
 * Returns: The name of @command.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
const char *purple_command_get_name(PurpleCommand *command);

/**
 * purple_command_get_priority:
 * @command: The instance.
 *
 * Gets the priority of @command.
 *
 * Returns: The priority.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
int purple_command_get_priority(PurpleCommand *command);

/**
 * purple_command_get_source:
 * @command: The instance.
 *
 * Gets the source of @command.
 *
 * When presenting commands to the user, this value can be used to help them
 * determine where the command came from.
 *
 * Returns: The source.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
const char *purple_command_get_source(PurpleCommand *command);

/**
 * purple_command_get_summary:
 * @command: The instance.
 *
 * Gets the summary of @command.
 *
 * When presenting commands to the user, this value can be used to help them
 * determine exactly what this command will do.
 *
 * Returns: The summary.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
const char *purple_command_get_summary(PurpleCommand *command);

/**
 * purple_command_get_tags:
 * @command: The instance.
 *
 * Gets the [class@Tags] from @command.
 *
 * These tags will be matched against [property@Conversation:tags] using
 * [method@Tags.contains] to determine if command is available for a
 * [class@Conversation].
 *
 * If this is empty, it will match all conversations.
 *
 * Returns: (transfer none): The tags object.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
PurpleTags *purple_command_get_tags(PurpleCommand *command);

/**
 * purple_command_get_use_count:
 * @command: The instance.
 *
 * Gets the use count of @command.
 *
 * Returns: The use count of @command.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
guint purple_command_get_use_count(PurpleCommand *command);

/**
 * purple_command_new:
 * @name: The name of the command.
 * @source: The source of the command. This will be displayed to users and
 *          should be marked for translation.
 * @priority: The priority of the command.
 *
 * Creates a new command with the given properties.
 *
 * Returns: (transfer full): The new command.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
PurpleCommand *purple_command_new(const char *name, const char *source, int priority);

/**
 * purple_command_set_icon_name:
 * @command: The instance.
 * @icon_name: (nullable): The new icon name.
 *
 * Sets the icon name of @command to @icon_name.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
void purple_command_set_icon_name(PurpleCommand *command, const char *icon_name);

/**
 * purple_command_set_last_used:
 * @command: The instance.
 * @last_used: (nullable): The new last used time stamp.
 *
 * Sets the last used time of @command to @last_used.
 *
 * Typically this won't need to be called as the default handler for
 * [signal@Command::executed] will set it.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
void purple_command_set_last_used(PurpleCommand *command, GDateTime *last_used);

/**
 * purple_command_set_summary:
 * @command: The instance.
 * @summary: (nullable): The new summary.
 *
 * Sets the summary of @command to @summary.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
void purple_command_set_summary(PurpleCommand *command, const char *summary);

/**
 * purple_command_set_use_count:
 * @command: The instance.
 * @use_count: The new use count.
 *
 * Sets the use count of @command to @use_count.
 *
 * Typically this won't need to be called directly as the default handler for
 * [signal@Command::executed] will increment it.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
void purple_command_set_use_count(PurpleCommand *command, guint use_count);

G_END_DECLS

#endif /* PURPLE_COMMAND_H */