qulogic/pidgin
Clone
Summary
Browse
Changes
Graph
Add birb as a subproject and make IRCv3 use it
6 months ago, Gary Kramlich
7a4558293dca
Add birb as a subproject and make IRCv3 use it
Testing Done:
Connected an IRCv3 account to twitch without issue.
Reviewed at https://reviews.imfreedom.org/r/2877/
/*
* 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_SAVEDSTATUSES_H
#define PURPLE_SAVEDSTATUSES_H
#define PURPLE_TYPE_SAVEDSTATUS (purple_savedstatus_get_type())
/**
* 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.
*
* Since: 2.0.0
*/
/*
* TODO: Hmm. We should probably just be saving PurplePresences. That's
* something we should look into once the status box gets fleshed
* out more.
*/
typedef
struct
_PurpleSavedStatus
PurpleSavedStatus
;
typedef
struct
_PurpleSavedStatusSub
PurpleSavedStatusSub
;
#include
"status.h"
#include
"purpleversion.h"
G_BEGIN_DECLS
/**************************************************************************/
/* Saved status subsystem */
/**************************************************************************/
/**
* purple_savedstatus_get_type:
*
* The standard _get_type function for #PurpleSavedStatus.
*
* 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.
*/
PURPLE_AVAILABLE_IN_3_0
GType
purple_savedstatus_get_type
(
void
);
/**
* purple_savedstatus_new:
* @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.
*
* 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.
*
* Returns: The newly created saved status, or NULL if the title you
* used was already taken.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleSavedStatus
*
purple_savedstatus_new
(
const
char
*
title
,
PurpleStatusPrimitive
type
);
/**
* purple_savedstatus_set_title:
* @status: The saved status.
* @title: The title of the saved status.
*
* Set the title for the given saved status.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
purple_savedstatus_set_title
(
PurpleSavedStatus
*
status
,
const
char
*
title
);
/**
* purple_savedstatus_set_primitive_type:
* @status: The saved status.
* @type: The type of saved status.
*
* Set the type for the given saved status.
*
* Since: 3.0.0
*/
PURPLE_AVAILABLE_IN_3_0
void
purple_savedstatus_set_primitive_type
(
PurpleSavedStatus
*
status
,
PurpleStatusPrimitive
type
);
/**
* purple_savedstatus_set_message:
* @status: The saved status.
* @message: The message, or NULL if you want to unset the
* message for this status.
*
* Set the message for the given saved status.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
purple_savedstatus_set_message
(
PurpleSavedStatus
*
status
,
const
char
*
message
);
/**
* purple_savedstatus_set_substatus:
* @status: The saved status.
* @account: The account.
* @type: The status type for the account in the saved
* status.
* @message: The message for the account in the substatus.
*
* Set a substatus for an account in a saved status.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
purple_savedstatus_set_substatus
(
PurpleSavedStatus
*
status
,
const
PurpleAccount
*
account
,
const
PurpleStatusType
*
type
,
const
char
*
message
);
/**
* purple_savedstatus_unset_substatus:
* @saved_status: The saved status.
* @account: The account.
*
* Unset a substatus for an account in a saved status. This clears
* the previously set substatus for the PurpleSavedStatus. If this
* saved status is activated then this account will use the default
* status type and message.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
purple_savedstatus_unset_substatus
(
PurpleSavedStatus
*
saved_status
,
const
PurpleAccount
*
account
);
/**
* purple_savedstatus_delete:
* @title: The title of the 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.
*
* 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.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
gboolean
purple_savedstatus_delete
(
const
char
*
title
);
/**
* purple_savedstatus_delete_by_status:
* @saved_status: the status to delete, the pointer is invalid after
* the call
*
* Delete a saved status. This removes the saved status from the list
* of saved statuses, and writes the revised list to status.xml.
*
* Since: 2.1.0
*/
PURPLE_AVAILABLE_IN_2_1
void
purple_savedstatus_delete_by_status
(
PurpleSavedStatus
*
saved_status
);
/**
* purple_savedstatuses_get_all:
*
* Returns all saved statuses.
*
* Returns: (element-type PurpleSavedStatus) (transfer none): A list of saved
* statuses.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
GList
*
purple_savedstatuses_get_all
(
void
);
/**
* purple_savedstatuses_get_popular:
* @how_many: The maximum number of saved statuses
* to return, or '0' to get all saved
* statuses sorted by popularity.
*
* 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.
*
* Returns: (element-type PurpleSavedStatus) (transfer container): A list containing
* at most how_many saved statuses.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
GList
*
purple_savedstatuses_get_popular
(
unsigned
int
how_many
);
/**
* purple_savedstatus_get_current:
*
* 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.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleSavedStatus
*
purple_savedstatus_get_current
(
void
);
/**
* purple_savedstatus_get_default:
*
* 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.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleSavedStatus
*
purple_savedstatus_get_default
(
void
);
/**
* purple_savedstatus_get_idleaway:
*
* 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.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleSavedStatus
*
purple_savedstatus_get_idleaway
(
void
);
/**
* purple_savedstatus_is_idleaway:
*
* Return TRUE if we are currently idle-away. Otherwise
* returns FALSE.
*
* Returns: TRUE if our accounts have been set to idle-away.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
gboolean
purple_savedstatus_is_idleaway
(
void
);
/**
* purple_savedstatus_set_idleaway:
* @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.
*
* Set whether accounts in Purple are idle-away or not.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
purple_savedstatus_set_idleaway
(
gboolean
idleaway
);
/**
* purple_savedstatus_get_startup:
*
* Returns the status to be used when purple is starting up
*
* Returns: A pointer to the startup PurpleSavedStatus.
* This function never returns NULL.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleSavedStatus
*
purple_savedstatus_get_startup
(
void
);
/**
* purple_savedstatus_find:
* @title: The name of the saved status.
*
* Finds a saved status with the specified title.
*
* Returns: The saved status if found, or NULL.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleSavedStatus
*
purple_savedstatus_find
(
const
char
*
title
);
/**
* purple_savedstatus_find_by_creation_time:
* @creation_time: The timestamp when the saved
* status was created.
*
* Finds a saved status with the specified creation time.
*
* Returns: The saved status if found, or NULL.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleSavedStatus
*
purple_savedstatus_find_by_creation_time
(
time_t
creation_time
);
/**
* purple_savedstatus_find_transient_by_type_and_message:
* @type: The PurpleStatusPrimitive for the status you're trying
* to find.
* @message: The message for the status you're trying
* to find.
*
* Finds a saved status with the specified primitive and message.
*
* Returns: The saved status if found, or NULL.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleSavedStatus
*
purple_savedstatus_find_transient_by_type_and_message
(
PurpleStatusPrimitive
type
,
const
char
*
message
);
/**
* purple_savedstatus_is_transient:
* @saved_status: The 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.
*
* Returns: TRUE if the saved status is transient.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
gboolean
purple_savedstatus_is_transient
(
const
PurpleSavedStatus
*
saved_status
);
/**
* purple_savedstatus_get_title:
* @saved_status: The saved status.
*
* Return the name of a given 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.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
const
char
*
purple_savedstatus_get_title
(
const
PurpleSavedStatus
*
saved_status
);
/**
* purple_savedstatus_get_primitive_type:
* @saved_status: The saved status.
*
* Return the type of a given saved status.
*
* Returns: The primitive type.
*
* Since: 3.0.0
*/
PURPLE_AVAILABLE_IN_3_0
PurpleStatusPrimitive
purple_savedstatus_get_primitive_type
(
const
PurpleSavedStatus
*
saved_status
);
/**
* purple_savedstatus_get_message:
* @saved_status: The saved status.
*
* Return the default message of a given 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).
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
const
char
*
purple_savedstatus_get_message
(
const
PurpleSavedStatus
*
saved_status
);
/**
* purple_savedstatus_get_creation_time:
* @saved_status: The 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.
*
* Returns: The timestamp when this saved status was created.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
time_t
purple_savedstatus_get_creation_time
(
const
PurpleSavedStatus
*
saved_status
);
/**
* purple_savedstatus_has_substatuses:
* @saved_status: The saved status.
*
* Determine if a given saved status has "substatuses,"
* or if it is a simple status (the same for all
* accounts).
*
* Returns: TRUE if the saved_status has substatuses.
* FALSE otherwise.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
gboolean
purple_savedstatus_has_substatuses
(
const
PurpleSavedStatus
*
saved_status
);
/**
* purple_savedstatus_get_substatus:
* @saved_status: The saved status.
* @account: The account.
*
* Get the substatus for an account in a saved status.
*
* Returns: (transfer none): 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.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
PurpleSavedStatusSub
*
purple_savedstatus_get_substatus
(
const
PurpleSavedStatus
*
saved_status
,
const
PurpleAccount
*
account
);
/**
* purple_savedstatus_substatus_get_status_type:
* @substatus: The substatus.
*
* Get the status type of a given substatus.
*
* Returns: The status type.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
const
PurpleStatusType
*
purple_savedstatus_substatus_get_status_type
(
const
PurpleSavedStatusSub
*
substatus
);
/**
* purple_savedstatus_substatus_get_message:
* @substatus: The substatus.
*
* Get the message of a given substatus.
*
* Returns: The message of the substatus, or NULL if this substatus does
* not have a message.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
const
char
*
purple_savedstatus_substatus_get_message
(
const
PurpleSavedStatusSub
*
substatus
);
/**
* purple_savedstatus_activate:
* @saved_status: The status you want to set your accounts to.
*
* 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.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
purple_savedstatus_activate
(
PurpleSavedStatus
*
saved_status
);
/**
* purple_savedstatus_activate_for_account:
* @saved_status: The status you want to set your accounts to.
* @account: The account whose statuses you want to change.
*
* Sets the statuses for a given account to those specified
* by the given saved_status.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
purple_savedstatus_activate_for_account
(
const
PurpleSavedStatus
*
saved_status
,
PurpleAccount
*
account
);
/**
* purple_savedstatuses_get_handle:
*
* Get the handle for the status subsystem.
*
* Returns: the handle to the status subsystem
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
*
purple_savedstatuses_get_handle
(
void
);
/**
* purple_savedstatuses_init:
*
* Initializes the status subsystem.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
purple_savedstatuses_init
(
void
);
/**
* purple_savedstatuses_uninit:
*
* Uninitializes the status subsystem.
*
* Since: 2.0.0
*/
PURPLE_AVAILABLE_IN_ALL
void
purple_savedstatuses_uninit
(
void
);
G_END_DECLS
#endif
/* PURPLE_SAVEDSTATUSES_H */