/*
 * 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_PRESENCE_MANAGER_H
#define PURPLE_PRESENCE_MANAGER_H

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

#include <gio/gio.h>

#include "purplepresencemanagerbackend.h"
#include "purplesavedpresence.h"
#include "purpleversion.h"

G_BEGIN_DECLS

#define PURPLE_TYPE_PRESENCE_MANAGER purple_presence_manager_get_type()

PURPLE_AVAILABLE_IN_3_0
G_DECLARE_FINAL_TYPE(PurplePresenceManager, purple_presence_manager, PURPLE,
                     PRESENCE_MANAGER, GObject)

/**
 * PurplePresenceManager:
 *
 * A manager for [class@SavedPresence]'s.
 *
 * Since: 3.0
 */

/**
 * purple_presence_manager_add:
 * @saved_presence: (transfer none): the saved presence to add
 *
 * Adds the saved presence to the manager.
 *
 * If a saved presence with the same id is already known to the manager, the
 * new one will not be added and false will be returned.
 *
 * Returns: true if the presence was added.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
gboolean purple_presence_manager_add(PurplePresenceManager *manager, PurpleSavedPresence *saved_presence);

/**
 * purple_presence_manager_find_with_id:
 * @id: the id to search for
 * @position: (out) (nullable): an optional return address for the position of
 *            the presence in the manager.
 *
 * Looks for a saved presence in the manager.
 *
 * If the saved presence is found, it will be returned and if position is not
 * %NULL it will be set to the position of the saved presence in the manager.
 *
 * Returns: (transfer none) (nullable): The item if found, otherwise %NULL.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
PurpleSavedPresence *purple_presence_manager_find_with_id(PurplePresenceManager *manager, const char *id, guint *position);

/**
 * purple_presence_manager_get_active_index:
 *
 * Gets the index of the currently active presence.
 *
 * If no item is active %G_MAXUINT will be returned.
 *
 * Returns: The index.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
guint purple_presence_manager_get_active_index(PurplePresenceManager *manager);

/**
 * purple_presence_manager_get_backend:
 *
 * Gets the backend being used for persistence.
 *
 * Returns: (transfer none) (nullable): The backend.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
PurplePresenceManagerBackend *purple_presence_manager_get_backend(PurplePresenceManager *manager);

/**
 * purple_presence_manager_get_active:
 * @manager: The instance.
 *
 * Gets the active [class@SavedPresence] from @manager.
 *
 * Returns: (transfer none) (nullable): The active presence if there is one,
 *          otherwise %NULL.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
PurpleSavedPresence *purple_presence_manager_get_active(PurplePresenceManager *manager);

/**
 * purple_presence_manager_remove:
 * @manager: The instance.
 * @id: The id of the [class@SavedPresence].
 *
 * Attempts to remove the [class@SavedPresence] identified by @id from
 * @manager.
 *
 * Returns: %TRUE if a [class@SavedPresence] was found with @id and removed,
 *          otherwise %FALSE.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
gboolean purple_presence_manager_remove(PurplePresenceManager *manager, const char *id);

/**
 * purple_presence_manager_set_active_from_index:
 * @index: the index of the item to make active
 *
 * Sets the presence at the given index as the active presence.
 *
 * The index is the index of the item exposed via the [iface@Gio.ListModel]
 * interface that the manager implements.
 *
 * If the given index is outside of the bounds of the manager, it will be
 * ignored.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
void purple_presence_manager_set_active_from_index(PurplePresenceManager *manager, guint index);

/**
 * purple_presence_manager_set_active_from_id:
 * @id: the id of the presence to set
 *
 * Sets the active presence to the saved presence with the given id.
 *
 * Returns: true if the presence was found and activated, otherwise false.
 *
 * Since: 3.0
 */
PURPLE_AVAILABLE_IN_3_0
gboolean purple_presence_manager_set_active_from_id(PurplePresenceManager *manager, const char *id);

G_END_DECLS

#endif /* PURPLE_PRESENCE_MANAGER_H */
