Saved Status API. More...

#include "status.h"

Include dependency graph for savedstatuses.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef struct _PurpleSavedStatus	PurpleSavedStatus
	Saved statuses don't really interact much with the rest of Purple.

typedef struct _PurpleSavedStatusSub	PurpleSavedStatusSub

Functions
Saved status subsystem <br>
PurpleSavedStatus *	purple_savedstatus_new (const char *title, PurpleStatusPrimitive type)
	Create a new saved status.

void	purple_savedstatus_set_title (PurpleSavedStatus status, const char title)
	Set the title for the given saved status.

void	purple_savedstatus_set_type (PurpleSavedStatus *status, PurpleStatusPrimitive type)
	Set the type for the given saved status.

void	purple_savedstatus_set_message (PurpleSavedStatus status, const char message)
	Set the message for the given saved status.

void	purple_savedstatus_set_substatus (PurpleSavedStatus status, const PurpleAccount account, const PurpleStatusType type, const char message)
	Set a substatus for an account in a saved status.

void	purple_savedstatus_unset_substatus (PurpleSavedStatus saved_status, const PurpleAccount account)
	Unset a substatus for an account in a saved status.

gboolean	purple_savedstatus_delete (const char *title)
	Delete a saved status.

void	purple_savedstatus_delete_by_status (PurpleSavedStatus *saved_status)
	Delete a saved status.

GList *	purple_savedstatuses_get_all (void)
	Returns all saved statuses.

GList *	purple_savedstatuses_get_popular (unsigned int how_many)
	Returns the n most popular saved statuses.

PurpleSavedStatus *	purple_savedstatus_get_current (void)
	Returns the currently selected saved status.

PurpleSavedStatus *	purple_savedstatus_get_default (void)
	Returns the default saved status that is used when our accounts are not idle-away.

PurpleSavedStatus *	purple_savedstatus_get_idleaway (void)
	Returns the saved status that is used when your accounts become idle-away.

gboolean	purple_savedstatus_is_idleaway (void)
	Return TRUE if we are currently idle-away.

void	purple_savedstatus_set_idleaway (gboolean idleaway)
	Set whether accounts in Purple are idle-away or not.

PurpleSavedStatus *	purple_savedstatus_get_startup (void)
	Returns the status to be used when purple is starting up.

PurpleSavedStatus *	purple_savedstatus_find (const char *title)
	Finds a saved status with the specified title.

PurpleSavedStatus *	purple_savedstatus_find_by_creation_time (time_t creation_time)
	Finds a saved status with the specified creation time.

PurpleSavedStatus *	purple_savedstatus_find_transient_by_type_and_message (PurpleStatusPrimitive type, const char *message)
	Finds a saved status with the specified primitive and message.

gboolean	purple_savedstatus_is_transient (const PurpleSavedStatus *saved_status)
	Determines if a given saved status is "transient." A transient saved status is one that was not explicitly added by the user.

const char *	purple_savedstatus_get_title (const PurpleSavedStatus *saved_status)
	Return the name of a given saved status.

PurpleStatusPrimitive	purple_savedstatus_get_type (const PurpleSavedStatus *saved_status)
	Return the type of a given saved status.

const char *	purple_savedstatus_get_message (const PurpleSavedStatus *saved_status)
	Return the default message of a given saved status.

time_t	purple_savedstatus_get_creation_time (const PurpleSavedStatus *saved_status)
	Return the time in seconds-since-the-epoch when this saved status was created.

gboolean	purple_savedstatus_has_substatuses (const PurpleSavedStatus *saved_status)
	Determine if a given saved status has "substatuses," or if it is a simple status (the same for all accounts).

PurpleSavedStatusSub *	purple_savedstatus_get_substatus (const PurpleSavedStatus saved_status, const PurpleAccount account)
	Get the substatus for an account in a saved status.

const PurpleStatusType *	purple_savedstatus_substatus_get_type (const PurpleSavedStatusSub *substatus)
	Get the status type of a given substatus.

const char *	purple_savedstatus_substatus_get_message (const PurpleSavedStatusSub *substatus)
	Get the message of a given substatus.

void	purple_savedstatus_activate (PurpleSavedStatus *saved_status)
	Sets the statuses for all your accounts to those specified by the given saved_status.

void	purple_savedstatus_activate_for_account (const PurpleSavedStatus saved_status, PurpleAccount account)
	Sets the statuses for a given account to those specified by the given saved_status.

void *	purple_savedstatuses_get_handle (void)
	Get the handle for the status subsystem.

void	purple_savedstatuses_init (void)
	Initializes the status subsystem.

void	purple_savedstatuses_uninit (void)
	Uninitializes the status subsystem.

Detailed Description

Saved Status API.

See also: Saved Status Signals

Definition in file savedstatuses.h.

Typedef Documentation

◆ PurpleSavedStatus

typedef struct _PurpleSavedStatus PurpleSavedStatus

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.

Definition at line 58 of file savedstatuses.h.

◆ PurpleSavedStatusSub

typedef struct _PurpleSavedStatusSub PurpleSavedStatusSub

Definition at line 59 of file savedstatuses.h.

Function Documentation

◆ purple_savedstatus_activate()

void purple_savedstatus_activate ( PurpleSavedStatus * saved_status )

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.

Parameters

saved_status The status you want to set your accounts to.

◆ purple_savedstatus_activate_for_account()

void purple_savedstatus_activate_for_account	(	const PurpleSavedStatus *	saved_status,
		PurpleAccount *	account
	)

Sets the statuses for a given account to those specified by the given saved_status.

Parameters

saved_status	The status you want to set your accounts to.
account	The account whose statuses you want to change.

◆ purple_savedstatus_delete()

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.

Parameters

title The title of the saved status.

Returns: TRUE if the status was successfully deleted. FALSE if the status could not be deleted because no saved status exists with the given title.

◆ purple_savedstatus_delete_by_status()

void purple_savedstatus_delete_by_status ( PurpleSavedStatus * saved_status )

Delete a saved status.

This removes the saved status from the list of saved statuses, and writes the revised list to status.xml.

Parameters

saved_status the status to delete, the pointer is invalid after the call

◆ purple_savedstatus_find()

PurpleSavedStatus * purple_savedstatus_find ( const char * title )

Finds a saved status with the specified title.

Parameters

title The name of the saved status.

Returns: The saved status if found, or NULL.

◆ purple_savedstatus_find_by_creation_time()

PurpleSavedStatus * purple_savedstatus_find_by_creation_time ( time_t creation_time )

Finds a saved status with the specified creation time.

Parameters

creation_time The timestamp when the saved status was created.

Returns: The saved status if found, or NULL.

◆ purple_savedstatus_find_transient_by_type_and_message()

PurpleSavedStatus * purple_savedstatus_find_transient_by_type_and_message	(	PurpleStatusPrimitive	type,
		const char *	message
	)

Finds a saved status with the specified primitive and message.

Parameters

type	The PurpleStatusPrimitive for the status you're trying to find.
message	The message for the status you're trying to find.

Returns: The saved status if found, or NULL.

◆ purple_savedstatus_get_creation_time()

time_t purple_savedstatus_get_creation_time ( 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.

Parameters

saved_status The saved status.

Returns: The timestamp when this saved status was created.

◆ purple_savedstatus_get_current()

PurpleSavedStatus * purple_savedstatus_get_current ( void )

Returns the currently selected saved status.

If we are idle then this returns purple_savedstatus_get_idleaway(). Otherwise it returns purple_savedstatus_get_default().

Returns: A pointer to the in-use PurpleSavedStatus. This function never returns NULL.

◆ purple_savedstatus_get_default()

PurpleSavedStatus * purple_savedstatus_get_default ( void )

Returns the default saved status that is used when our accounts are not idle-away.

Returns: A pointer to the in-use PurpleSavedStatus. This function never returns NULL.

◆ purple_savedstatus_get_idleaway()

PurpleSavedStatus * purple_savedstatus_get_idleaway ( void )

Returns the saved status that is used when your accounts become idle-away.

Returns: A pointer to the idle-away PurpleSavedStatus. This function never returns NULL.

◆ purple_savedstatus_get_message()

const char * purple_savedstatus_get_message ( const PurpleSavedStatus * saved_status )

Return the default message of a given saved status.

Parameters

saved_status The saved status.

Returns: 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).

◆ purple_savedstatus_get_startup()

PurpleSavedStatus * purple_savedstatus_get_startup ( void )

Returns the status to be used when purple is starting up.

Returns: A pointer to the startup PurpleSavedStatus. This function never returns NULL.

◆ purple_savedstatus_get_substatus()

PurpleSavedStatusSub * purple_savedstatus_get_substatus	(	const PurpleSavedStatus *	saved_status,
		const PurpleAccount *	account
	)

Get the substatus for an account in a saved status.

Parameters

saved_status	The saved status.
account	The account.

Returns: 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.

◆ purple_savedstatus_get_title()

const char * purple_savedstatus_get_title ( const PurpleSavedStatus * saved_status )

Return the name of a given saved status.

Parameters

saved_status The saved status.

Returns: 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.

◆ purple_savedstatus_get_type()

PurpleStatusPrimitive purple_savedstatus_get_type ( const PurpleSavedStatus * saved_status )

Return the type of a given saved status.

Parameters

saved_status The saved status.

Returns: The name.

◆ purple_savedstatus_has_substatuses()

gboolean purple_savedstatus_has_substatuses ( const PurpleSavedStatus * saved_status )

Determine if a given saved status has "substatuses," or if it is a simple status (the same for all accounts).

Parameters

saved_status The saved status.

Returns: TRUE if the saved_status has substatuses. FALSE otherwise.

◆ purple_savedstatus_is_idleaway()

gboolean purple_savedstatus_is_idleaway ( void )

Return TRUE if we are currently idle-away.

Otherwise returns FALSE.

Returns: TRUE if our accounts have been set to idle-away.

◆ purple_savedstatus_is_transient()

gboolean purple_savedstatus_is_transient ( const PurpleSavedStatus * saved_status )

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.

Parameters

saved_status The saved status.

Returns: TRUE if the saved status is transient.

◆ purple_savedstatus_new()

PurpleSavedStatus * purple_savedstatus_new	(	const char *	title,
		PurpleStatusPrimitive	type
	)

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.

Parameters

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.
type	The type of saved status.

Returns: The newly created saved status, or NULL if the title you used was already taken.

◆ purple_savedstatus_set_idleaway()

void purple_savedstatus_set_idleaway ( gboolean idleaway )

Set whether accounts in Purple are idle-away or not.

Parameters

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.

◆ purple_savedstatus_set_message()

void purple_savedstatus_set_message	(	PurpleSavedStatus *	status,
		const char *	message
	)

Set the message for the given saved status.

Parameters

status	The saved status.
message	The message, or NULL if you want to unset the message for this status.

◆ purple_savedstatus_set_substatus()

void purple_savedstatus_set_substatus	(	PurpleSavedStatus *	status,
		const PurpleAccount *	account,
		const PurpleStatusType *	type,
		const char *	message
	)

Set a substatus for an account in a saved status.

Parameters

status	The saved status.
account	The account.
type	The status type for the account in the staved status.
message	The message for the account in the substatus.

◆ purple_savedstatus_set_title()

void purple_savedstatus_set_title	(	PurpleSavedStatus *	status,
		const char *	title
	)

Set the title for the given saved status.

Parameters

status	The saved status.
title	The title of the saved status.

◆ purple_savedstatus_set_type()

void purple_savedstatus_set_type	(	PurpleSavedStatus *	status,
		PurpleStatusPrimitive	type
	)

Set the type for the given saved status.

Parameters

status	The saved status.
type	The type of saved status.

◆ purple_savedstatus_substatus_get_message()

const char * purple_savedstatus_substatus_get_message ( const PurpleSavedStatusSub * substatus )

Get the message of a given substatus.

Parameters

substatus The substatus.

Returns: The message of the substatus, or NULL if this substatus does not have a message.

◆ purple_savedstatus_substatus_get_type()

const PurpleStatusType * purple_savedstatus_substatus_get_type ( const PurpleSavedStatusSub * substatus )

Get the status type of a given substatus.

Parameters

substatus The substatus.

Returns: The status type.

◆ purple_savedstatus_unset_substatus()

void purple_savedstatus_unset_substatus	(	PurpleSavedStatus *	saved_status,
		const PurpleAccount *	account
	)

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.

Parameters

saved_status	The saved status.
account	The account.

◆ purple_savedstatuses_get_all()

GList * purple_savedstatuses_get_all ( void )

Returns all saved statuses.

Note: The return value of this function must not be modified or freed.

Returns: A list of saved statuses.

◆ purple_savedstatuses_get_handle()

void * purple_savedstatuses_get_handle ( void )

Get the handle for the status subsystem.

Returns: the handle to the status subsystem

◆ purple_savedstatuses_get_popular()

GList * purple_savedstatuses_get_popular ( unsigned int how_many )

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.

Parameters

how_many The maximum number of saved statuses to return, or '0' to get all saved statuses sorted by popularity.

Returns: 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).

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ PurpleSavedStatus

◆ PurpleSavedStatusSub

Function Documentation

◆ purple_savedstatus_activate()

◆ purple_savedstatus_activate_for_account()

◆ purple_savedstatus_delete()

◆ purple_savedstatus_delete_by_status()

◆ purple_savedstatus_find()

◆ purple_savedstatus_find_by_creation_time()

◆ purple_savedstatus_find_transient_by_type_and_message()

◆ purple_savedstatus_get_creation_time()

◆ purple_savedstatus_get_current()

◆ purple_savedstatus_get_default()

◆ purple_savedstatus_get_idleaway()

◆ purple_savedstatus_get_message()

◆ purple_savedstatus_get_startup()

◆ purple_savedstatus_get_substatus()

◆ purple_savedstatus_get_title()

◆ purple_savedstatus_get_type()

◆ purple_savedstatus_has_substatuses()

◆ purple_savedstatus_is_idleaway()

◆ purple_savedstatus_is_transient()

◆ purple_savedstatus_new()

◆ purple_savedstatus_set_idleaway()

◆ purple_savedstatus_set_message()

◆ purple_savedstatus_set_substatus()

◆ purple_savedstatus_set_title()

◆ purple_savedstatus_set_type()

◆ purple_savedstatus_substatus_get_message()

◆ purple_savedstatus_substatus_get_type()

◆ purple_savedstatus_unset_substatus()

◆ purple_savedstatuses_get_all()

◆ purple_savedstatuses_get_handle()

◆ purple_savedstatuses_get_popular()