Mercurial > pidgin
diff libgaim/savedstatuses.h @ 14192:60b1bc8dbf37
[gaim-migrate @ 16863]
Renamed 'core' to 'libgaim'
committer: Tailor Script <tailor@pidgin.im>
author | Evan Schoenberg <evan.s@dreskin.net> |
---|---|
date | Sat, 19 Aug 2006 01:50:10 +0000 |
parents | |
children | 8d9a473bbab9 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libgaim/savedstatuses.h Sat Aug 19 01:50:10 2006 +0000 @@ -0,0 +1,408 @@ +/** + * @file savedstatuses.h Saved Status API + * @ingroup core + * + * gaim + * + * Gaim 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef _GAIM_SAVEDSTATUSES_H_ +#define _GAIM_SAVEDSTATUSES_H_ + +/** + * Saved statuses don't really interact much with the rest of Gaim. It + * could really be a plugin. It's just a list of away states. When + * a user chooses one of the saved states, their Gaim 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. Gaim 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 GaimPresences. That's + * something we should look into once the status box gets fleshed + * out more. + */ + +typedef struct _GaimSavedStatus GaimSavedStatus; +typedef struct _GaimSavedStatusSub GaimSavedStatusSub; + +#include "status.h" + +/**************************************************************************/ +/** @name Saved status subsystem */ +/**************************************************************************/ +/*@{*/ + +/** + * 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. + */ +GaimSavedStatus *gaim_savedstatus_new(const char *title, + GaimStatusPrimitive type); + +/** + * Set the title for the given saved status. + * + * @param status The saved status. + * @param title The title of the saved status. + */ +void gaim_savedstatus_set_title(GaimSavedStatus *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 gaim_savedstatus_set_type(GaimSavedStatus *status, + GaimStatusPrimitive 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 gaim_savedstatus_set_message(GaimSavedStatus *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 gaim_savedstatus_set_substatus(GaimSavedStatus *status, + const GaimAccount *account, + const GaimStatusType *type, + const char *message); + +/** + * Unset a substatus for an account in a saved status. This clears + * the previosly set substatus for the GaimSavedStatus. 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 gaim_savedstatus_unset_substatus(GaimSavedStatus *saved_status, + const GaimAccount *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 gaim_savedstatus_delete(const char *title); + +/** + * Returns all saved statuses. + * + * @return A list of saved statuses. + */ +const GList *gaim_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. If the current status would + * normally show up in this list, then it is omited and instead + * the "how_many+1" saved status will appear in the list. Also + * 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 + * GaimSavedStatuses. This list should be + * g_list_free'd by the caller (but the + * GaimSavedStatuses must not be free'd). + */ +GList *gaim_savedstatuses_get_popular(unsigned int how_many); + +/** + * Returns the currently selected saved status. If we are idle + * then this returns gaim_savedstatus_get_idleaway(). Otherwise + * it returns gaim_savedstatus_get_default(). + * + * @return A pointer to the in-use GaimSavedStatus. + * This function never returns NULL. + */ +GaimSavedStatus *gaim_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 GaimSavedStatus. + * This function never returns NULL. + */ +GaimSavedStatus *gaim_savedstatus_get_default(void); + +/** + * Returns the saved status that is used when your + * accounts become idle-away. + * + * @return A pointer to the idle-away GaimSavedStatus. + * This function never returns NULL. + */ +GaimSavedStatus *gaim_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 gaim_savedstatus_is_idleaway(void); + +/** + * Set whether accounts in Gaim are idle-away or not. + * + * @param 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 gaim_savedstatus_set_idleaway(gboolean idleaway); + +/** + * Returns the status to be used when gaim is starting up + * + * @return A pointer to the startup GaimSavedStatus. + * This function never returns NULL. + */ +GaimSavedStatus *gaim_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. + */ +GaimSavedStatus *gaim_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. + */ +GaimSavedStatus *gaim_savedstatus_find_by_creation_time(time_t creation_time); + +/** + * Finds a saved status with the specified primitive and message. + * + * @param type The GaimStatusPrimitive 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. + */ +GaimSavedStatus *gaim_savedstatus_find_transient_by_type_and_message(GaimStatusPrimitive 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 Gaim restarts. + * + * @param saved_status The saved status. + * + * @return TRUE if the saved status is transient. + */ +gboolean gaim_savedstatus_is_transient(const GaimSavedStatus *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 *gaim_savedstatus_get_title(const GaimSavedStatus *saved_status); + +/** + * Return the type of a given saved status. + * + * @param saved_status The saved status. + * + * @return The name. + */ +GaimStatusPrimitive gaim_savedstatus_get_type(const GaimSavedStatus *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 + * Gaim's IMHTML (basically HTML markup). + */ +const char *gaim_savedstatus_get_message(const GaimSavedStatus *saved_status); + +/** + * Return the time in seconds-since-the-epoch when this + * saved status was created. Note: For any status created + * by Gaim 1.5.0 or older this value will be invalid and + * very small (close to 0). This is because Gaim 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 gaim_savedstatus_get_creation_time(const GaimSavedStatus *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 gaim_savedstatus_has_substatuses(const GaimSavedStatus *saved_status); + +/** + * Get the substatus for an account in a saved status. + * + * @param saved_status The saved status. + * @param account The account. + * + * @return The GaimSavedStatusSub for the account, or NULL if + * the given account does not have a substatus that + * differs from the default status of this GaimSavedStatus. + */ +GaimSavedStatusSub *gaim_savedstatus_get_substatus( + const GaimSavedStatus *saved_status, + const GaimAccount *account); + +/** + * Get the status type of a given substatus. + * + * @param substatus The substatus. + * + * @return The status type. + */ +const GaimStatusType *gaim_savedstatus_substatus_get_type(const GaimSavedStatusSub *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 *gaim_savedstatus_substatus_get_message(const GaimSavedStatusSub *substatus); + +/** + * Sets the statuses for all your accounts to those specified + * by the given saved_status. This function calls + * gaim_savedstatus_activate_for_account() for all your accounts. + * + * @param saved_status The status you want to set your accounts to. + */ +void gaim_savedstatus_activate(GaimSavedStatus *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 gaim_savedstatus_activate_for_account(const GaimSavedStatus *saved_status, GaimAccount *account); + +/** + * Get the handle for the status subsystem. + * + * @return the handle to the status subsystem + */ +void *gaim_savedstatuses_get_handle(void); + +/** + * Initializes the status subsystem. + */ +void gaim_savedstatuses_init(void); + +/** + * Uninitializes the status subsystem. + */ +void gaim_savedstatuses_uninit(void); + +/*@}*/ + +#endif /* _GAIM_SAVEDSTATUSES_H_ */