pidgin/pidgin
Clone
Summary
Browse
Changes
Graph
Include glib.h before using GLIB_CHECK_VERSION
2014-01-29, Ankit Vani
dc0a29ff7087
Include glib.h before using GLIB_CHECK_VERSION
/**
* @file savedstatuses.h Saved Status API
* @ingroup core
* @see @ref savedstatus-signals
*/
/* purple
*
* 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, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*/
#ifndef _PURPLE_SAVEDSTATUSES_H_
#define _PURPLE_SAVEDSTATUSES_H_
/**
* Saved statuses don't really interact much with the rest of Purple. It
* could really be a plugin. It's just a list of away states. When
* a user chooses one of the saved states, their Purple accounts are set
* to the settings of that state.
*
* In the savedstatus API, there is the concept of a 'transient'
* saved status. A transient saved status is one that is not
* permanent. Purple will removed it automatically if it isn't
* used for a period of time. Transient saved statuses don't
* have titles and they don't show up in the list of saved
* statuses. In fact, if a saved status does not have a title
* then it is transient. If it does have a title, then it is not
* transient.
*
* What good is a transient status, you ask? They can be used to
* keep track of the user's 5 most recently used statuses, for
* example. Basically if they just set a message on the fly,
* we'll cache it for them in case they want to use it again. If
* they don't use it again, we'll just delete it.
*/
/*
* TODO: Hmm. We should probably just be saving PurplePresences. That's
* something we should look into once the status box gets fleshed
* out more.
*/
#define PURPLE_TYPE_SAVEDSTATUS (purple_savedstatus_get_g_type())
typedef
struct
_PurpleSavedStatus
PurpleSavedStatus
;
typedef
struct
_PurpleSavedStatusSub
PurpleSavedStatusSub
;
#include
"status.h"
G_BEGIN_DECLS
/**************************************************************************/
/** @name Saved status subsystem */
/**************************************************************************/
/*@{*/
/**
* Returns the GType for the PurpleSavedStatus boxed structure.
* TODO Boxing of PurpleSavedStatus is a temporary solution to having a GType
* for saved statuses. This should rather be a GObject instead of a GBoxed.
*/
GType
purple_savedstatus_get_g_type
(
void
);
/**
* Create a new saved status. This will add the saved status to the
* list of saved statuses and writes the revised list to status.xml.
*
* @param title The title of the saved status. This must be
* unique. Or, if you want to create a transient
* saved status, then pass in NULL.
* @param type The type of saved status.
*
* @return The newly created saved status, or NULL if the title you
* used was already taken.
*/
PurpleSavedStatus
*
purple_savedstatus_new
(
const
char
*
title
,
PurpleStatusPrimitive
type
);
/**
* Set the title for the given saved status.
*
* @param status The saved status.
* @param title The title of the saved status.
*/
void
purple_savedstatus_set_title
(
PurpleSavedStatus
*
status
,
const
char
*
title
);
/**
* Set the type for the given saved status.
*
* @param status The saved status.
* @param type The type of saved status.
*/
void
purple_savedstatus_set_type
(
PurpleSavedStatus
*
status
,
PurpleStatusPrimitive
type
);
/**
* Set the message for the given saved status.
*
* @param status The saved status.
* @param message The message, or NULL if you want to unset the
* message for this status.
*/
void
purple_savedstatus_set_message
(
PurpleSavedStatus
*
status
,
const
char
*
message
);
/**
* Set a substatus for an account in a saved status.
*
* @param status The saved status.
* @param account The account.
* @param type The status type for the account in the staved
* status.
* @param message The message for the account in the substatus.
*/
void
purple_savedstatus_set_substatus
(
PurpleSavedStatus
*
status
,
const
PurpleAccount
*
account
,
const
PurpleStatusType
*
type
,
const
char
*
message
);
/**
* Unset a substatus for an account in a saved status. This clears
* the previosly set substatus for the PurpleSavedStatus. If this
* saved status is activated then this account will use the default
* status type and message.
*
* @param saved_status The saved status.
* @param account The account.
*/
void
purple_savedstatus_unset_substatus
(
PurpleSavedStatus
*
saved_status
,
const
PurpleAccount
*
account
);
/**
* Delete a saved status. This removes the saved status from the list
* of saved statuses, and writes the revised list to status.xml.
*
* @param title The title of the saved status.
*
* @return TRUE if the status was successfully deleted. FALSE if the
* status could not be deleted because no saved status exists
* with the given title.
*/
gboolean
purple_savedstatus_delete
(
const
char
*
title
);
/**
* Delete a saved status. This removes the saved status from the list
* of saved statuses, and writes the revised list to status.xml.
*
* @param saved_status the status to delete, the pointer is invalid after
* the call
*
*/
void
purple_savedstatus_delete_by_status
(
PurpleSavedStatus
*
saved_status
);
/**
* Returns all saved statuses.
*
* @constreturn A list of saved statuses.
*/
GList
*
purple_savedstatuses_get_all
(
void
);
/**
* Returns the n most popular saved statuses. "Popularity" is
* determined by when the last time a saved_status was used and
* how many times it has been used. Transient statuses without
* messages are not included in the list.
*
* @param how_many The maximum number of saved statuses
* to return, or '0' to get all saved
* statuses sorted by popularity.
* @return A linked list containing at most how_many
* PurpleSavedStatuses. This list should be
* g_list_free'd by the caller (but the
* PurpleSavedStatuses must not be free'd).
*/
GList
*
purple_savedstatuses_get_popular
(
unsigned
int
how_many
);
/**
* Returns the currently selected saved status. If we are idle
* then this returns purple_savedstatus_get_idleaway(). Otherwise
* it returns purple_savedstatus_get_default().
*
* @return A pointer to the in-use PurpleSavedStatus.
* This function never returns NULL.
*/
PurpleSavedStatus
*
purple_savedstatus_get_current
(
void
);
/**
* Returns the default saved status that is used when our
* accounts are not idle-away.
*
* @return A pointer to the in-use PurpleSavedStatus.
* This function never returns NULL.
*/
PurpleSavedStatus
*
purple_savedstatus_get_default
(
void
);
/**
* Returns the saved status that is used when your
* accounts become idle-away.
*
* @return A pointer to the idle-away PurpleSavedStatus.
* This function never returns NULL.
*/
PurpleSavedStatus
*
purple_savedstatus_get_idleaway
(
void
);
/**
* Return TRUE if we are currently idle-away. Otherwise
* returns FALSE.
*
* @return TRUE if our accounts have been set to idle-away.
*/
gboolean
purple_savedstatus_is_idleaway
(
void
);
/**
* Set whether accounts in Purple are idle-away or not.
*
* @param idleaway TRUE if accounts should be switched to use the
* idle-away saved status. FALSE if they should
* be switched to use the default status.
*/
void
purple_savedstatus_set_idleaway
(
gboolean
idleaway
);
/**
* Returns the status to be used when purple is starting up
*
* @return A pointer to the startup PurpleSavedStatus.
* This function never returns NULL.
*/
PurpleSavedStatus
*
purple_savedstatus_get_startup
(
void
);
/**
* Finds a saved status with the specified title.
*
* @param title The name of the saved status.
*
* @return The saved status if found, or NULL.
*/
PurpleSavedStatus
*
purple_savedstatus_find
(
const
char
*
title
);
/**
* Finds a saved status with the specified creation time.
*
* @param creation_time The timestamp when the saved
* status was created.
*
* @return The saved status if found, or NULL.
*/
PurpleSavedStatus
*
purple_savedstatus_find_by_creation_time
(
time_t
creation_time
);
/**
* Finds a saved status with the specified primitive and message.
*
* @param type The PurpleStatusPrimitive for the status you're trying
* to find.
* @param message The message for the status you're trying
* to find.
*
* @return The saved status if found, or NULL.
*/
PurpleSavedStatus
*
purple_savedstatus_find_transient_by_type_and_message
(
PurpleStatusPrimitive
type
,
const
char
*
message
);
/**
* Determines if a given saved status is "transient."
* A transient saved status is one that was not
* explicitly added by the user. Transient statuses
* are automatically removed if they are not used
* for a period of time.
*
* A transient saved statuses is automatically
* created by the status box when the user sets himself
* to one of the generic primitive statuses. The reason
* we need to save this status information is so we can
* restore it when Purple restarts.
*
* @param saved_status The saved status.
*
* @return TRUE if the saved status is transient.
*/
gboolean
purple_savedstatus_is_transient
(
const
PurpleSavedStatus
*
saved_status
);
/**
* Return the name of a given saved status.
*
* @param saved_status The saved status.
*
* @return The title. This value may be a static buffer which may
* be overwritten on subsequent calls to this function. If
* you need a reference to the title for prolonged use then
* you should make a copy of it.
*/
const
char
*
purple_savedstatus_get_title
(
const
PurpleSavedStatus
*
saved_status
);
/**
* Return the type of a given saved status.
*
* @param saved_status The saved status.
*
* @return The name.
*/
PurpleStatusPrimitive
purple_savedstatus_get_type
(
const
PurpleSavedStatus
*
saved_status
);
/**
* Return the default message of a given saved status.
*
* @param saved_status The saved status.
*
* @return The message. This will return NULL if the saved
* status does not have a message. This will
* contain the normal markup that is created by
* Purple's IMHTML (basically HTML markup).
*/
const
char
*
purple_savedstatus_get_message
(
const
PurpleSavedStatus
*
saved_status
);
/**
* Return the time in seconds-since-the-epoch when this
* saved status was created. Note: For any status created
* by Purple 1.5.0 or older this value will be invalid and
* very small (close to 0). This is because Purple 1.5.0
* and older did not record the timestamp when the status
* was created.
*
* However, this value is guaranteed to be a unique
* identifier for the given saved status.
*
* @param saved_status The saved status.
*
* @return The timestamp when this saved status was created.
*/
time_t
purple_savedstatus_get_creation_time
(
const
PurpleSavedStatus
*
saved_status
);
/**
* Determine if a given saved status has "substatuses,"
* or if it is a simple status (the same for all
* accounts).
*
* @param saved_status The saved status.
*
* @return TRUE if the saved_status has substatuses.
* FALSE otherwise.
*/
gboolean
purple_savedstatus_has_substatuses
(
const
PurpleSavedStatus
*
saved_status
);
/**
* Get the substatus for an account in a saved status.
*
* @param saved_status The saved status.
* @param account The account.
*
* @return The PurpleSavedStatusSub for the account, or NULL if
* the given account does not have a substatus that
* differs from the default status of this PurpleSavedStatus.
*/
PurpleSavedStatusSub
*
purple_savedstatus_get_substatus
(
const
PurpleSavedStatus
*
saved_status
,
const
PurpleAccount
*
account
);
/**
* Get the status type of a given substatus.
*
* @param substatus The substatus.
*
* @return The status type.
*/
const
PurpleStatusType
*
purple_savedstatus_substatus_get_type
(
const
PurpleSavedStatusSub
*
substatus
);
/**
* Get the message of a given substatus.
*
* @param substatus The substatus.
*
* @return The message of the substatus, or NULL if this substatus does
* not have a message.
*/
const
char
*
purple_savedstatus_substatus_get_message
(
const
PurpleSavedStatusSub
*
substatus
);
/**
* Sets the statuses for all your accounts to those specified
* by the given saved_status. This function calls
* purple_savedstatus_activate_for_account() for all your accounts.
*
* @param saved_status The status you want to set your accounts to.
*/
void
purple_savedstatus_activate
(
PurpleSavedStatus
*
saved_status
);
/**
* Sets the statuses for a given account to those specified
* by the given saved_status.
*
* @param saved_status The status you want to set your accounts to.
* @param account The account whose statuses you want to change.
*/
void
purple_savedstatus_activate_for_account
(
const
PurpleSavedStatus
*
saved_status
,
PurpleAccount
*
account
);
/**
* Get the handle for the status subsystem.
*
* @return the handle to the status subsystem
*/
void
*
purple_savedstatuses_get_handle
(
void
);
/**
* Initializes the status subsystem.
*/
void
purple_savedstatuses_init
(
void
);
/**
* Uninitializes the status subsystem.
*/
void
purple_savedstatuses_uninit
(
void
);
/*@}*/
G_END_DECLS
#endif
/* _PURPLE_SAVEDSTATUSES_H_ */