libpurple/status.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 program 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 program 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 program; 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_STATUS_H
#define PURPLE_STATUS_H

#define PURPLE_TYPE_STATUS (purple_status_get_type())
typedef struct _PurpleStatus PurpleStatus;

#define PURPLE_TYPE_STATUS_TYPE (purple_status_type_get_type())

/**
 * PurpleStatusType:
 *
 * PurpleStatusType's are created by each protocol.  They outline the
 * available statuses of the protocol.  AIM, for example, supports
 * an available state with an optional available message, an away
 * state with a mandatory message, and an invisible state (which is
 * technically "independent" of the other two, but we'll get into
 * that later).  PurpleStatusTypes are very permanent.  They are
 * hardcoded in each protocol and will not change often.  And because
 * they are hardcoded, they do not need to be saved to any XML file.
 */
typedef struct _PurpleStatusType PurpleStatusType;

#define PURPLE_TYPE_STATUS_ATTRIBUTE (purple_status_attribute_get_type())

/**
 * PurpleStatus:
 *
 * A PurpleStatus can be thought of as an "instance" of a PurpleStatusType.
 * If you're familiar with object-oriented programming languages
 * then this should be immediately clear.  Say, for example, that
 * one of your AIM buddies has set himself as "away."  You have a
 * PurpleBuddy node for this person in your buddy list.  Purple wants
 * to mark this buddy as "away," so it creates a new PurpleStatus.
 * The PurpleStatus has its PurpleStatusType set to the "away" state
 * for the oscar protocol.  The PurpleStatus also contains the buddy's
 * away message.  PurpleStatuses are sometimes saved, depending on
 * the context.  The current PurpleStatuses associated with each of
 * your accounts are saved so that the next time you start Purple,
 * your accounts will be set to their last known statuses.  There
 * is also a list of saved statuses that are written to the
 * status.xml file.  Also, each PurpleStatus has a "saveable" boolean.
 * If "saveable" is set to FALSE then the status is NEVER saved.
 * All PurpleStatuses should be inside a PurplePresence.
 *
 * A PurpleStatus is either "independent" or "exclusive."
 * Independent statuses can be active or inactive and they don't
 * affect anything else.  However, you can only have one exclusive
 * status per PurplePresence.  If you activate one exclusive status,
 * then the previous exclusive status is automatically deactivated.
 *
 * A PurplePresence is like a collection of PurpleStatuses (plus some
 * other random info).
 *
 * See <link linkend="libpurple-purplepresence">Presence API</link>
 */
typedef struct _PurpleStatusAttribute PurpleStatusAttribute;

/**
 * PurpleStatusPrimitive:
 * @PURPLE_STATUS_UNSET: The status is not set
 * @PURPLE_STATUS_OFFLINE: The status is offline
 * @PURPLE_STATUS_AVAILABLE: The status is available
 * @PURPLE_STATUS_UNAVAILABLE: The status is unavailable
 * @PURPLE_STATUS_INVISIBLE: The stuatus is invisible
 * @PURPLE_STATUS_AWAY: The status is away
 * @PURPLE_STATUS_EXTENDED_AWAY: The status is extended away/do not disturb
 * @PURPLE_STATUS_MOBILE: The status is mobile
 * @PURPLE_STATUS_NUM_PRIMITIVES: The number of #PurpleStatusPrimitive<!-- -->s
 *
 * A primitive defining the basic structure of a status type.
 */
/*
 * If you add a value to this enum, make sure you update
 * the status_primitive_map and primitive_scores arrays in status.c.
 */
typedef enum
{
	PURPLE_STATUS_UNSET = 0,
	PURPLE_STATUS_OFFLINE,
	PURPLE_STATUS_AVAILABLE,
	PURPLE_STATUS_UNAVAILABLE,
	PURPLE_STATUS_INVISIBLE,
	PURPLE_STATUS_AWAY,
	PURPLE_STATUS_EXTENDED_AWAY,
	PURPLE_STATUS_MOBILE,

	PURPLE_STATUS_NUM_PRIMITIVES, /*< skip >*/
} PurpleStatusPrimitive;

#include "purplepresence.h"

G_BEGIN_DECLS

/**************************************************************************/
/* PurpleStatusPrimitive API                                              */
/**************************************************************************/

/**
 * purple_primitive_get_id_from_type:
 * @type: A primitive status type.
 *
 * Lookup the id of a primitive status type based on the type.  This
 * ID is a unique plain-text name of the status, without spaces.
 *
 * Returns: The unique ID for this type.
 */
const char *purple_primitive_get_id_from_type(PurpleStatusPrimitive type);

/**
 * purple_primitive_get_name_from_type:
 * @type: A primitive status type.
 *
 * Lookup the name of a primitive status type based on the type.  This
 * name is the plain-English name of the status type.  It is usually one
 * or two words.
 *
 * Returns: The name of this type, suitable for users to see.
 */
const char *purple_primitive_get_name_from_type(PurpleStatusPrimitive type);

/**
 * purple_primitive_get_type_from_id:
 * @id: The unique ID of a primitive status type.
 *
 * Lookup the value of a primitive status type based on the id.  The
 * ID is a unique plain-text name of the status, without spaces.
 *
 * Returns: The PurpleStatusPrimitive value.
 */
PurpleStatusPrimitive purple_primitive_get_type_from_id(const char *id);

/**************************************************************************/
/* PurpleStatusType API                                                   */
/**************************************************************************/

/**
 * purple_status_type_get_type:
 *
 * The standard _get_type function for #PurpleStatusType.
 *
 * Returns: The #GType for #PurpleStatusType.
 */
GType purple_status_type_get_type(void);

/**
 * purple_status_type_new_full:
 * @primitive: The primitive status type.
 * @id: The ID of the status type, or %NULL to use the id of the primitive
 *      status type.
 * @name: The name presented to the user, or %NULL to use the name of the
 *        primitive status type.
 * @saveable: %TRUE if the information set for this status by the user can be
 *            saved for future sessions.
 * @user_settable: %TRUE if this is a status the user can manually set.
 * @independent: %TRUE if this is an independent (non-exclusive) status type.
 *
 * Creates a new status type.
 *
 * Returns: (transfer full): A new status type.
 */
PurpleStatusType *purple_status_type_new_full(PurpleStatusPrimitive primitive,
										  const char *id, const char *name,
										  gboolean saveable,
										  gboolean user_settable,
										  gboolean independent);

/**
 * purple_status_type_new:
 * @primitive: The primitive status type.
 * @id: The ID of the status type, or %NULL to use the id of the primitive
 *      status type.
 * @name: The name presented to the user, or %NULL to use the name of the
 *        primitive status type.
 * @user_settable: %TRUE if this is a status the user can manually set.
 *
 * Creates a new status type with some default values (saveable and not
 * independent).
 *
 * Returns: (transfer full): A new status type.
 */
PurpleStatusType *purple_status_type_new(PurpleStatusPrimitive primitive,
									 const char *id, const char *name,
									 gboolean user_settable);

/**
 * purple_status_type_new_with_attrs:
 * @primitive: The primitive status type.
 * @id: The ID of the status type, or %NULL to use the id of the primitive
 *      status type.
 * @name: The name presented to the user, or %NULL to use the name of the
 *        primitive status type.
 * @saveable: %TRUE if the information set for this status by the user can be
 *            saved for future sessions.
 * @user_settable: %TRUE if this is a status the user can manually set.
 * @independent: %TRUE if this is an independent (non-exclusive) status type.
 * @attr_id: The ID of the first attribute.
 * @attr_name: The name of the first attribute.
 * @attr_value: The value type of the first attribute.
 * @...: Additional attribute information.
 *
 * Creates a new status type with attributes.
 *
 * Returns: (transfer full): A new status type.
 */
PurpleStatusType *purple_status_type_new_with_attrs(PurpleStatusPrimitive primitive,
												const char *id,
												const char *name,
												gboolean saveable,
												gboolean user_settable,
												gboolean independent,
												const char *attr_id,
												const char *attr_name,
												GValue *attr_value, ...) G_GNUC_NULL_TERMINATED;

/**
 * purple_status_type_new_with_attrsv: (rename-to purple_status_type_new_with_attrs):
 * @primitive: The primitive status type.
 * @id: The ID of the status type, or %NULL to use the id of the primitive
 *      status type.
 * @name: The name presented to the user, or %NULL to use the name of the
 *        primitive status type.
 * @saveable: %TRUE if the information set for this status by the user can be
 *            saved for future sessions.
 * @user_settable: %TRUE if this is a status the user can manually set.
 * @independent: %TRUE if this is an independent (non-exclusive) status type.
 * @n_attributes: The number of attributes.
 * @attr_id: (array length=n_attributes): The IDs of the attributes.
 * @attr_name: (array length=n_attributes): The names of the attributes.
 * @attr_value: (array length=n_attributes): The value types of the attributes.
 *
 * Creates a new status type with attributes.
 *
 * Returns: (transfer full): A new status type.
 *
 * Since: 3.0.0
 */
PurpleStatusType *purple_status_type_new_with_attrsv(PurpleStatusPrimitive primitive,
                                                     const gchar *id,
                                                     const gchar *name,
                                                     gboolean saveable,
                                                     gboolean user_settable,
                                                     gboolean independent,
                                                     guint n_attributes,
                                                     const gchar *attr_id[],
                                                     const gchar *attr_name[],
                                                     GValue *attr_value[]);

/**
 * purple_status_type_destroy:
 * @status_type: The status type to destroy.
 *
 * Destroys a status type.
 */
void purple_status_type_destroy(PurpleStatusType *status_type);

/**
 * purple_status_type_get_primitive:
 * @status_type: The status type.
 *
 * Returns the primitive type of a status type.
 *
 * Returns: The primitive type of the status type.
 */
PurpleStatusPrimitive purple_status_type_get_primitive(
	const PurpleStatusType *status_type);

/**
 * purple_status_type_get_id:
 * @status_type: The status type.
 *
 * Returns the ID of a status type.
 *
 * Returns: The ID of the status type.
 */
const char *purple_status_type_get_id(const PurpleStatusType *status_type);

/**
 * purple_status_type_get_name:
 * @status_type: The status type.
 *
 * Returns the name of a status type.
 *
 * Returns: The name of the status type.
 */
const char *purple_status_type_get_name(const PurpleStatusType *status_type);

/**
 * purple_status_type_is_saveable:
 * @status_type: The status type.
 *
 * Returns whether or not the status type is saveable.
 *
 * Returns: TRUE if user-defined statuses based off this type are saveable.
 *         FALSE otherwise.
 */
gboolean purple_status_type_is_saveable(const PurpleStatusType *status_type);

/**
 * purple_status_type_is_user_settable:
 * @status_type: The status type.
 *
 * Returns whether or not the status type can be set or modified by the
 * user.
 *
 * Returns: TRUE if the status type can be set or modified by the user.
 *         FALSE if it's a protocol-set setting.
 */
gboolean purple_status_type_is_user_settable(const PurpleStatusType *status_type);

/**
 * purple_status_type_is_independent:
 * @status_type: The status type.
 *
 * Returns whether or not the status type is independent.
 *
 * Independent status types are non-exclusive. If other status types on
 * the same hierarchy level are set, this one will not be affected.
 *
 * Returns: TRUE if the status type is independent, or FALSE otherwise.
 */
gboolean purple_status_type_is_independent(const PurpleStatusType *status_type);

/**
 * purple_status_type_is_exclusive:
 * @status_type: The status type.
 *
 * Returns whether the status type is exclusive.
 *
 * Returns: TRUE if the status type is exclusive, FALSE otherwise.
 */
gboolean purple_status_type_is_exclusive(const PurpleStatusType *status_type);

/**
 * purple_status_type_is_available:
 * @status_type: The status type.
 *
 * Returns whether or not a status type is available.
 *
 * Available status types are online and possibly invisible, but not away.
 *
 * Returns: TRUE if the status is available, or FALSE otherwise.
 */
gboolean purple_status_type_is_available(const PurpleStatusType *status_type);

/**
 * purple_status_type_get_attr:
 * @status_type: The status type containing the attribute.
 * @id:          The ID of the desired attribute.
 *
 * Returns the attribute with the specified ID.
 *
 * Returns: The attribute, if found. NULL otherwise.
 */
PurpleStatusAttribute *purple_status_type_get_attr(const PurpleStatusType *status_type,
										  const char *id);

/**
 * purple_status_type_get_attrs:
 * @status_type: The status type.
 *
 * Returns a list of all attributes in a status type.
 *
 * Returns: (element-type PurpleStatusAttribute) (transfer none): The list of attributes.
 */
GList *purple_status_type_get_attrs(const PurpleStatusType *status_type);

/**
 * purple_status_type_find_with_id:
 * @status_types: (element-type PurpleStatus) (transfer none): A list of status
 *                types.  Often account->status_types.
 * @id: The unique ID of the status type you wish to find.
 *
 * Find the PurpleStatusType with the given id.
 *
 * Returns: The status type with the given ID, or NULL if one could
 *         not be found.
 */
const PurpleStatusType *purple_status_type_find_with_id(GList *status_types,
													const char *id);

/**************************************************************************/
/* PurpleStatusAttribute API                                              */
/**************************************************************************/

/**
 * purple_status_attribute_get_type:
 *
 * The standard _get_type function for #PurpleStatusAttribute.
 *
 * Returns: The #GType for the #PurpleStatusAttribute boxed structure.
 */
GType purple_status_attribute_get_type(void);

/**
 * purple_status_attribute_new:
 * @id:         The ID of the attribute.
 * @name:       The name presented to the user.
 * @value_type: The type of data contained in the attribute.
 *
 * Creates a new status attribute.
 *
 * Returns: A new status attribute.
 */
PurpleStatusAttribute *purple_status_attribute_new(const char *id, const char *name,
									 GValue *value_type);

/**
 * purple_status_attribute_destroy:
 * @attr: The status attribute to destroy.
 *
 * Destroys a status attribute.
 */
void purple_status_attribute_destroy(PurpleStatusAttribute *attr);

/**
 * purple_status_attribute_get_id:
 * @attr: The status attribute.
 *
 * Returns the ID of a status attribute.
 *
 * Returns: The status attribute's ID.
 */
const char *purple_status_attribute_get_id(const PurpleStatusAttribute *attr);

/**
 * purple_status_attribute_get_name:
 * @attr: The status attribute.
 *
 * Returns the name of a status attribute.
 *
 * Returns: The status attribute's name.
 */
const char *purple_status_attribute_get_name(const PurpleStatusAttribute *attr);

/**
 * purple_status_attribute_get_value:
 * @attr: The status attribute.
 *
 * Returns the value of a status attribute.
 *
 * Returns: The status attribute's value.
 */
GValue *purple_status_attribute_get_value(const PurpleStatusAttribute *attr);

/**************************************************************************/
/* PurpleStatus API                                                       */
/**************************************************************************/

/**
 * purple_status_get_type:
 *
 * The standard _get_type function for #PurpleStatus.
 *
 * Returns: The #GType for #PurpleStatus.
 */
G_DECLARE_FINAL_TYPE(PurpleStatus, purple_status, PURPLE, STATUS, GObject)

/**
 * purple_status_new:
 * @status_type: The type of status.
 * @presence:    The parent presence.
 *
 * Creates a new status.
 *
 * Returns: The new status.
 */
PurpleStatus *purple_status_new(PurpleStatusType *status_type,
							PurplePresence *presence);

/**
 * purple_status_set_active:
 * @status: The status.
 * @active: The active state.
 *
 * Sets whether or not a status is active.
 *
 * This should only be called by the account, conversation, and buddy APIs.
 */
void purple_status_set_active(PurpleStatus *status, gboolean active);

/**
 * purple_status_set_active_with_attributes:
 * @status: The status.
 * @active: The active state.
 * @attrs: (nullable) (element-type utf8 gpointer): A hash table of attributes
 *         to set on the status. This hash table's keys are valid attribute
 *         names for this PurpleStatusType. The hash table is not modified or
 *         freed by this function.
 *
 * Sets whether or not a status is active.
 *
 * This should only be called by the account, conversation, and buddy APIs.
 *
 * Since: 3.0.0
 */
void purple_status_set_active_with_attributes(PurpleStatus *status, gboolean active, GHashTable *attrs);

/**
 * purple_status_get_status_type:
 * @status: The status.
 *
 * Returns the status's type.
 *
 * Returns: The status's type.
 */
PurpleStatusType *purple_status_get_status_type(PurpleStatus *status);

/**
 * purple_status_get_presence:
 * @status: The status.
 *
 * Returns the status's presence.
 *
 * Returns: (transfer none): The status's presence.
 */
PurplePresence *purple_status_get_presence(PurpleStatus *status);

/**
 * purple_status_get_id:
 * @status: The status.
 *
 * Returns the status's type ID.
 *
 * This is a convenience method for
 * purple_status_type_get_id(purple_status_get_status_type(status)).
 *
 * Returns: The status's ID.
 */
const char *purple_status_get_id(PurpleStatus *status);

/**
 * purple_status_get_name:
 * @status: The status.
 *
 * Returns the status's name.
 *
 * This is a convenience method for
 * purple_status_type_get_name(purple_status_get_status_type(status)).
 *
 * Returns: The status's name.
 */
const char *purple_status_get_name(PurpleStatus *status);

/**
 * purple_status_is_independent:
 * @status: The status.
 *
 * Returns whether or not a status is independent.
 *
 * This is a convenience method for
 * purple_status_type_is_independent(purple_status_get_status_type(status)).
 *
 * Returns: TRUE if the status is independent, or FALSE otherwise.
 */
gboolean purple_status_is_independent(PurpleStatus *status);

/**
 * purple_status_is_exclusive:
 * @status: The status.
 *
 * Returns whether or not a status is exclusive.
 *
 * This is a convenience method for
 * purple_status_type_is_exclusive(purple_status_get_status_type(status)).
 *
 * Returns: TRUE if the status is exclusive, FALSE otherwise.
 */
gboolean purple_status_is_exclusive(PurpleStatus *status);

/**
 * purple_status_is_available:
 * @status: The status.
 *
 * Returns whether or not a status is available.
 *
 * Available statuses are online and possibly invisible, but not away or idle.
 *
 * This is a convenience method for
 * purple_status_type_is_available(purple_status_get_status_type(status)).
 *
 * Returns: TRUE if the status is available, or FALSE otherwise.
 */
gboolean purple_status_is_available(PurpleStatus *status);

/**
 * purple_status_is_active:
 * @status: The status.
 *
 * Returns the active state of a status.
 *
 * Returns: The active state of the status.
 */
gboolean purple_status_is_active(PurpleStatus *status);

/**
 * purple_status_is_online:
 * @status: The status.
 *
 * Returns whether or not a status is considered 'online'
 *
 * Returns: TRUE if the status is considered online, FALSE otherwise
 */
gboolean purple_status_is_online(PurpleStatus *status);

/**
 * purple_status_get_attr_value:
 * @status: The status.
 * @id:     The attribute ID.
 *
 * Returns the value of an attribute in a status with the specified ID.
 *
 * Returns: The value of the attribute.
 */
GValue *purple_status_get_attr_value(PurpleStatus *status,
									 const char *id);

/**
 * purple_status_get_attr_boolean:
 * @status: The status.
 * @id:     The attribute ID.
 *
 * Returns the boolean value of an attribute in a status with the specified ID.
 *
 * Returns: The boolean value of the attribute.
 */
gboolean purple_status_get_attr_boolean(PurpleStatus *status,
									    const char *id);

/**
 * purple_status_get_attr_int:
 * @status: The status.
 * @id:     The attribute ID.
 *
 * Returns the integer value of an attribute in a status with the specified ID.
 *
 * Returns: The integer value of the attribute.
 */
int purple_status_get_attr_int(PurpleStatus *status, const char *id);

/**
 * purple_status_get_attr_string:
 * @status: The status.
 * @id:     The attribute ID.
 *
 * Returns the string value of an attribute in a status with the specified ID.
 *
 * Returns: The string value of the attribute.
 */
const char *purple_status_get_attr_string(PurpleStatus *status, const char *id);

/**
 * purple_status_compare:
 * @status1: The first status.
 * @status2: The second status.
 *
 * Compares two statuses for availability.
 *
 * Returns: -1 if @status1 is more available than @status2.
 *           0 if @status1 is equal to @status2.
 *           1 if @status2 is more available than @status1.
 */
gint purple_status_compare(PurpleStatus *status1, PurpleStatus *status2);

/**************************************************************************/
/* Statuses subsystem                                                     */
/**************************************************************************/

/**
 * purple_statuses_get_handle:
 *
 * Get the handle for the status subsystem.
 *
 * Returns: the handle to the status subsystem
 */
void *purple_statuses_get_handle(void);

/**
 * purple_statuses_init:
 *
 * Initializes the status subsystem.
 */
void purple_statuses_init(void);

/**
 * purple_statuses_uninit:
 *
 * Uninitializes the status subsystem.
 */
void purple_statuses_uninit(void);

/**************************************************************************/
/* Helpers                                                                */
/**************************************************************************/

/**
 * purple_attrs_from_vargs:
 * @args:   A list of attributes to parse.  This list is
 *               composed of key/value pairs, where each key is a valid
 *               attribute name for this PurpleStatusType.  The list should
 *               be NULL terminated.
 *
 * Returns a hash table of attributes constructed from args.
 *
 * Returns: (element-type utf8 gpointer) (transfer container): The hash table of attributes.
 *
 * Since: 3.0.0
 */
GHashTable *purple_attrs_from_vargs(va_list args);

G_END_DECLS

#endif /* PURPLE_STATUS_H */