1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/status.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,1084 @@
1.4 +/*
1.5 + * purple
1.6 + *
1.7 + * Purple is the legal property of its developers, whose names are too numerous
1.8 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.9 + * source distribution.
1.10 + *
1.11 + * This program is free software; you can redistribute it and/or modify
1.12 + * it under the terms of the GNU General Public License as published by
1.13 + * the Free Software Foundation; either version 2 of the License, or
1.14 + * (at your option) any later version.
1.15 + *
1.16 + * This program is distributed in the hope that it will be useful,
1.17 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.18 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.19 + * GNU General Public License for more details.
1.20 + *
1.21 + * You should have received a copy of the GNU General Public License
1.22 + * along with this program; if not, write to the Free Software
1.23 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.24 + */
1.25 +#ifndef _PURPLE_STATUS_H_
1.26 +#define _PURPLE_STATUS_H_
1.27 +
1.28 +/**
1.29 + * @file status.h Status API
1.30 + * @ingroup core
1.31 + *
1.32 + * A brief explanation of the status API:
1.33 + *
1.34 + * PurpleStatusType's are created by each PRPL. They outline the
1.35 + * available statuses of the protocol. AIM, for example, supports
1.36 + * an available state with an optional available message, an away
1.37 + * state with a mandatory message, and an invisible state (which is
1.38 + * technically "independent" of the other two, but we'll get into
1.39 + * that later). PurpleStatusTypes are very permanent. They are
1.40 + * hardcoded in each PRPL and will not change often. And because
1.41 + * they are hardcoded, they do not need to be saved to any XML file.
1.42 + *
1.43 + * A PurpleStatus can be thought of as an "instance" of a PurpleStatusType.
1.44 + * If you're familiar with object-oriented programming languages
1.45 + * then this should be immediately clear. Say, for example, that
1.46 + * one of your AIM buddies has set himself as "away." You have a
1.47 + * PurpleBuddy node for this person in your buddy list. Purple wants
1.48 + * to mark this buddy as "away," so it creates a new PurpleStatus.
1.49 + * The PurpleStatus has its PurpleStatusType set to the "away" state
1.50 + * for the oscar PRPL. The PurpleStatus also contains the buddy's
1.51 + * away message. PurpleStatuses are sometimes saved, depending on
1.52 + * the context. The current PurpleStatuses associated with each of
1.53 + * your accounts are saved so that the next time you start Purple,
1.54 + * your accounts will be set to their last known statuses. There
1.55 + * is also a list of saved statuses that are written to the
1.56 + * status.xml file. Also, each PurpleStatus has a "saveable" boolean.
1.57 + * If "saveable" is set to FALSE then the status is NEVER saved.
1.58 + * All PurpleStatuses should be inside a PurplePresence.
1.59 + *
1.60 + *
1.61 + * A PurpleStatus is either "independent" or "exclusive."
1.62 + * Independent statuses can be active or inactive and they don't
1.63 + * affect anything else. However, you can only have one exclusive
1.64 + * status per PurplePresence. If you activate one exclusive status,
1.65 + * then the previous exclusive status is automatically deactivated.
1.66 + *
1.67 + * A PurplePresence is like a collection of PurpleStatuses (plus some
1.68 + * other random info). For any buddy, or for any one of your accounts,
1.69 + * or for any person with which you're chatting, you may know various
1.70 + * amounts of information. This information is all contained in
1.71 + * one PurplePresence. If one of your buddies is away and idle,
1.72 + * then the presence contains the PurpleStatus for their awayness,
1.73 + * and it contains their current idle time. PurplePresences are
1.74 + * never saved to disk. The information they contain is only relevant
1.75 + * for the current PurpleSession.
1.76 + */
1.77 +
1.78 +typedef struct _PurpleStatusType PurpleStatusType;
1.79 +typedef struct _PurpleStatusAttr PurpleStatusAttr;
1.80 +typedef struct _PurplePresence PurplePresence;
1.81 +typedef struct _PurpleStatus PurpleStatus;
1.82 +
1.83 +/**
1.84 + * A context for a presence.
1.85 + *
1.86 + * The context indicates to what the presence applies.
1.87 + */
1.88 +typedef enum
1.89 +{
1.90 + PURPLE_PRESENCE_CONTEXT_UNSET = 0,
1.91 + PURPLE_PRESENCE_CONTEXT_ACCOUNT,
1.92 + PURPLE_PRESENCE_CONTEXT_CONV,
1.93 + PURPLE_PRESENCE_CONTEXT_BUDDY
1.94 +
1.95 +} PurplePresenceContext;
1.96 +
1.97 +/**
1.98 + * A primitive defining the basic structure of a status type.
1.99 + */
1.100 +/*
1.101 + * If you add a value to this enum, make sure you update
1.102 + * the status_primitive_map array in status.c and the special-cases for idle
1.103 + * and offline-messagable just below it.
1.104 + */
1.105 +typedef enum
1.106 +{
1.107 + PURPLE_STATUS_UNSET = 0,
1.108 + PURPLE_STATUS_OFFLINE,
1.109 + PURPLE_STATUS_AVAILABLE,
1.110 + PURPLE_STATUS_UNAVAILABLE,
1.111 + PURPLE_STATUS_INVISIBLE,
1.112 + PURPLE_STATUS_AWAY,
1.113 + PURPLE_STATUS_EXTENDED_AWAY,
1.114 + PURPLE_STATUS_MOBILE,
1.115 + PURPLE_STATUS_TUNE,
1.116 + PURPLE_STATUS_NUM_PRIMITIVES
1.117 +} PurpleStatusPrimitive;
1.118 +
1.119 +#include "account.h"
1.120 +#include "blist.h"
1.121 +#include "conversation.h"
1.122 +#include "value.h"
1.123 +
1.124 +#define PURPLE_TUNE_ARTIST "tune_artist"
1.125 +#define PURPLE_TUNE_TITLE "tune_title"
1.126 +#define PURPLE_TUNE_ALBUM "tune_album"
1.127 +#define PURPLE_TUNE_GENRE "tune_genre"
1.128 +#define PURPLE_TUNE_COMMENT "tune_comment"
1.129 +#define PURPLE_TUNE_TRACK "tune_track"
1.130 +#define PURPLE_TUNE_TIME "tune_time"
1.131 +#define PURPLE_TUNE_YEAR "tune_year"
1.132 +#define PURPLE_TUNE_URL "tune_url"
1.133 +#define PURPLE_TUNE_FULL "tune_full"
1.134 +
1.135 +#ifdef __cplusplus
1.136 +extern "C" {
1.137 +#endif
1.138 +
1.139 +/**************************************************************************/
1.140 +/** @name PurpleStatusPrimitive API */
1.141 +/**************************************************************************/
1.142 +/*@{*/
1.143 +
1.144 +/**
1.145 + * Lookup the id of a primitive status type based on the type. This
1.146 + * ID is a unique plain-text name of the status, without spaces.
1.147 + *
1.148 + * @param type A primitive status type.
1.149 + *
1.150 + * @return The unique ID for this type.
1.151 + */
1.152 +const char *purple_primitive_get_id_from_type(PurpleStatusPrimitive type);
1.153 +
1.154 +/**
1.155 + * Lookup the name of a primitive status type based on the type. This
1.156 + * name is the plain-English name of the status type. It is usually one
1.157 + * or two words.
1.158 + *
1.159 + * @param type A primitive status type.
1.160 + *
1.161 + * @return The name of this type, suitable for users to see.
1.162 + */
1.163 +const char *purple_primitive_get_name_from_type(PurpleStatusPrimitive type);
1.164 +
1.165 +/**
1.166 + * Lookup the value of a primitive status type based on the id. The
1.167 + * ID is a unique plain-text name of the status, without spaces.
1.168 + *
1.169 + * @param id The unique ID of a primitive status type.
1.170 + *
1.171 + * @return The PurpleStatusPrimitive value.
1.172 + */
1.173 +PurpleStatusPrimitive purple_primitive_get_type_from_id(const char *id);
1.174 +
1.175 +/*@}*/
1.176 +
1.177 +/**************************************************************************/
1.178 +/** @name PurpleStatusType API */
1.179 +/**************************************************************************/
1.180 +/*@{*/
1.181 +
1.182 +/**
1.183 + * Creates a new status type.
1.184 + *
1.185 + * @param primitive The primitive status type.
1.186 + * @param id The ID of the status type, or @c NULL to use the id of
1.187 + * the primitive status type.
1.188 + * @param name The name presented to the user, or @c NULL to use the
1.189 + * name of the primitive status type.
1.190 + * @param saveable TRUE if the information set for this status by the
1.191 + * user can be saved for future sessions.
1.192 + * @param user_settable TRUE if this is a status the user can manually set.
1.193 + * @param independent TRUE if this is an independent (non-exclusive)
1.194 + * status type.
1.195 + *
1.196 + * @return A new status type.
1.197 + */
1.198 +PurpleStatusType *purple_status_type_new_full(PurpleStatusPrimitive primitive,
1.199 + const char *id, const char *name,
1.200 + gboolean saveable,
1.201 + gboolean user_settable,
1.202 + gboolean independent);
1.203 +
1.204 +/**
1.205 + * Creates a new status type with some default values (
1.206 + * saveable and not independent).
1.207 + *
1.208 + * @param primitive The primitive status type.
1.209 + * @param id The ID of the status type, or @c NULL to use the id of
1.210 + * the primitive status type.
1.211 + * @param name The name presented to the user, or @c NULL to use the
1.212 + * name of the primitive status type.
1.213 + * @param user_settable TRUE if this is a status the user can manually set.
1.214 + *
1.215 + * @return A new status type.
1.216 + */
1.217 +PurpleStatusType *purple_status_type_new(PurpleStatusPrimitive primitive,
1.218 + const char *id, const char *name,
1.219 + gboolean user_settable);
1.220 +
1.221 +/**
1.222 + * Creates a new status type with attributes.
1.223 + *
1.224 + * @param primitive The primitive status type.
1.225 + * @param id The ID of the status type, or @c NULL to use the id of
1.226 + * the primitive status type.
1.227 + * @param name The name presented to the user, or @c NULL to use the
1.228 + * name of the primitive status type.
1.229 + * @param saveable TRUE if the information set for this status by the
1.230 + * user can be saved for future sessions.
1.231 + * @param user_settable TRUE if this is a status the user can manually set.
1.232 + * @param independent TRUE if this is an independent (non-exclusive)
1.233 + * status type.
1.234 + * @param attr_id The ID of the first attribute.
1.235 + * @param attr_name The name of the first attribute.
1.236 + * @param attr_value The value type of the first attribute attribute.
1.237 + * @param ... Additional attribute information.
1.238 + *
1.239 + * @return A new status type.
1.240 + */
1.241 +PurpleStatusType *purple_status_type_new_with_attrs(PurpleStatusPrimitive primitive,
1.242 + const char *id,
1.243 + const char *name,
1.244 + gboolean saveable,
1.245 + gboolean user_settable,
1.246 + gboolean independent,
1.247 + const char *attr_id,
1.248 + const char *attr_name,
1.249 + PurpleValue *attr_value, ...) G_GNUC_NULL_TERMINATED;
1.250 +
1.251 +/**
1.252 + * Destroys a status type.
1.253 + *
1.254 + * @param status_type The status type to destroy.
1.255 + */
1.256 +void purple_status_type_destroy(PurpleStatusType *status_type);
1.257 +
1.258 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_)
1.259 +/**
1.260 + * Sets a status type's primary attribute.
1.261 + *
1.262 + * The value for the primary attribute is used as the description for
1.263 + * the particular status type. An example is an away message. The message
1.264 + * would be the primary attribute.
1.265 + *
1.266 + * @param status_type The status type.
1.267 + * @param attr_id The ID of the primary attribute.
1.268 + *
1.269 + * @deprecated This function isn't used and should be removed in 3.0.0.
1.270 + */
1.271 +void purple_status_type_set_primary_attr(PurpleStatusType *status_type,
1.272 + const char *attr_id);
1.273 +#endif
1.274 +
1.275 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_)
1.276 +/**
1.277 + * Adds an attribute to a status type.
1.278 + *
1.279 + * @param status_type The status type to add the attribute to.
1.280 + * @param id The ID of the attribute.
1.281 + * @param name The name presented to the user.
1.282 + * @param value The value type of this attribute.
1.283 + *
1.284 + * @deprecated This function isn't needed and should be removed in 3.0.0.
1.285 + * Status type attributes should be set when the status type
1.286 + * is created, in the call to purple_status_type_new_with_attrs.
1.287 + */
1.288 +void purple_status_type_add_attr(PurpleStatusType *status_type, const char *id,
1.289 + const char *name, PurpleValue *value);
1.290 +#endif
1.291 +
1.292 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_)
1.293 +/**
1.294 + * Adds multiple attributes to a status type.
1.295 + *
1.296 + * @param status_type The status type to add the attribute to.
1.297 + * @param id The ID of the first attribute.
1.298 + * @param name The description of the first attribute.
1.299 + * @param value The value type of the first attribute attribute.
1.300 + * @param ... Additional attribute information.
1.301 + *
1.302 + * @deprecated This function isn't needed and should be removed in 3.0.0.
1.303 + * Status type attributes should be set when the status type
1.304 + * is created, in the call to purple_status_type_new_with_attrs.
1.305 + */
1.306 +void purple_status_type_add_attrs(PurpleStatusType *status_type, const char *id,
1.307 + const char *name, PurpleValue *value, ...) G_GNUC_NULL_TERMINATED;
1.308 +#endif
1.309 +
1.310 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_)
1.311 +/**
1.312 + * Adds multiple attributes to a status type using a va_list.
1.313 + *
1.314 + * @param status_type The status type to add the attribute to.
1.315 + * @param args The va_list of attributes.
1.316 + *
1.317 + * @deprecated This function isn't needed and should be removed in 3.0.0.
1.318 + * Status type attributes should be set when the status type
1.319 + * is created, in the call to purple_status_type_new_with_attrs.
1.320 + */
1.321 +void purple_status_type_add_attrs_vargs(PurpleStatusType *status_type,
1.322 + va_list args);
1.323 +#endif
1.324 +
1.325 +/**
1.326 + * Returns the primitive type of a status type.
1.327 + *
1.328 + * @param status_type The status type.
1.329 + *
1.330 + * @return The primitive type of the status type.
1.331 + */
1.332 +PurpleStatusPrimitive purple_status_type_get_primitive(
1.333 + const PurpleStatusType *status_type);
1.334 +
1.335 +/**
1.336 + * Returns the ID of a status type.
1.337 + *
1.338 + * @param status_type The status type.
1.339 + *
1.340 + * @return The ID of the status type.
1.341 + */
1.342 +const char *purple_status_type_get_id(const PurpleStatusType *status_type);
1.343 +
1.344 +/**
1.345 + * Returns the name of a status type.
1.346 + *
1.347 + * @param status_type The status type.
1.348 + *
1.349 + * @return The name of the status type.
1.350 + */
1.351 +const char *purple_status_type_get_name(const PurpleStatusType *status_type);
1.352 +
1.353 +/**
1.354 + * Returns whether or not the status type is saveable.
1.355 + *
1.356 + * @param status_type The status type.
1.357 + *
1.358 + * @return TRUE if user-defined statuses based off this type are saveable.
1.359 + * FALSE otherwise.
1.360 + */
1.361 +gboolean purple_status_type_is_saveable(const PurpleStatusType *status_type);
1.362 +
1.363 +/**
1.364 + * Returns whether or not the status type can be set or modified by the
1.365 + * user.
1.366 + *
1.367 + * @param status_type The status type.
1.368 + *
1.369 + * @return TRUE if the status type can be set or modified by the user.
1.370 + * FALSE if it's a protocol-set setting.
1.371 + */
1.372 +gboolean purple_status_type_is_user_settable(const PurpleStatusType *status_type);
1.373 +
1.374 +/**
1.375 + * Returns whether or not the status type is independent.
1.376 + *
1.377 + * Independent status types are non-exclusive. If other status types on
1.378 + * the same hierarchy level are set, this one will not be affected.
1.379 + *
1.380 + * @param status_type The status type.
1.381 + *
1.382 + * @return TRUE if the status type is independent, or FALSE otherwise.
1.383 + */
1.384 +gboolean purple_status_type_is_independent(const PurpleStatusType *status_type);
1.385 +
1.386 +/**
1.387 + * Returns whether the status type is exclusive.
1.388 + *
1.389 + * @param status_type The status type.
1.390 + *
1.391 + * @return TRUE if the status type is exclusive, FALSE otherwise.
1.392 + */
1.393 +gboolean purple_status_type_is_exclusive(const PurpleStatusType *status_type);
1.394 +
1.395 +/**
1.396 + * Returns whether or not a status type is available.
1.397 + *
1.398 + * Available status types are online and possibly invisible, but not away.
1.399 + *
1.400 + * @param status_type The status type.
1.401 + *
1.402 + * @return TRUE if the status is available, or FALSE otherwise.
1.403 + */
1.404 +gboolean purple_status_type_is_available(const PurpleStatusType *status_type);
1.405 +
1.406 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_)
1.407 +/**
1.408 + * Returns a status type's primary attribute ID.
1.409 + *
1.410 + * @param type The status type.
1.411 + *
1.412 + * @return The primary attribute's ID.
1.413 + *
1.414 + * @deprecated This function isn't used and should be removed in 3.0.0.
1.415 + */
1.416 +const char *purple_status_type_get_primary_attr(const PurpleStatusType *type);
1.417 +#endif
1.418 +
1.419 +/**
1.420 + * Returns the attribute with the specified ID.
1.421 + *
1.422 + * @param status_type The status type containing the attribute.
1.423 + * @param id The ID of the desired attribute.
1.424 + *
1.425 + * @return The attribute, if found. NULL otherwise.
1.426 + */
1.427 +PurpleStatusAttr *purple_status_type_get_attr(const PurpleStatusType *status_type,
1.428 + const char *id);
1.429 +
1.430 +/**
1.431 + * Returns a list of all attributes in a status type.
1.432 + *
1.433 + * @param status_type The status type.
1.434 + *
1.435 + * @constreturn The list of attributes.
1.436 + */
1.437 +GList *purple_status_type_get_attrs(const PurpleStatusType *status_type);
1.438 +
1.439 +/**
1.440 + * Find the PurpleStatusType with the given id.
1.441 + *
1.442 + * @param status_types A list of status types. Often account->status_types.
1.443 + * @param id The unique ID of the status type you wish to find.
1.444 + *
1.445 + * @return The status type with the given ID, or NULL if one could
1.446 + * not be found.
1.447 + */
1.448 +const PurpleStatusType *purple_status_type_find_with_id(GList *status_types,
1.449 + const char *id);
1.450 +
1.451 +/*@}*/
1.452 +
1.453 +/**************************************************************************/
1.454 +/** @name PurpleStatusAttr API */
1.455 +/**************************************************************************/
1.456 +/*@{*/
1.457 +
1.458 +/**
1.459 + * Creates a new status attribute.
1.460 + *
1.461 + * @param id The ID of the attribute.
1.462 + * @param name The name presented to the user.
1.463 + * @param value_type The type of data contained in the attribute.
1.464 + *
1.465 + * @return A new status attribute.
1.466 + */
1.467 +PurpleStatusAttr *purple_status_attr_new(const char *id, const char *name,
1.468 + PurpleValue *value_type);
1.469 +
1.470 +/**
1.471 + * Destroys a status attribute.
1.472 + *
1.473 + * @param attr The status attribute to destroy.
1.474 + */
1.475 +void purple_status_attr_destroy(PurpleStatusAttr *attr);
1.476 +
1.477 +/**
1.478 + * Returns the ID of a status attribute.
1.479 + *
1.480 + * @param attr The status attribute.
1.481 + *
1.482 + * @return The status attribute's ID.
1.483 + */
1.484 +const char *purple_status_attr_get_id(const PurpleStatusAttr *attr);
1.485 +
1.486 +/**
1.487 + * Returns the name of a status attribute.
1.488 + *
1.489 + * @param attr The status attribute.
1.490 + *
1.491 + * @return The status attribute's name.
1.492 + */
1.493 +const char *purple_status_attr_get_name(const PurpleStatusAttr *attr);
1.494 +
1.495 +/**
1.496 + * Returns the value of a status attribute.
1.497 + *
1.498 + * @param attr The status attribute.
1.499 + *
1.500 + * @return The status attribute's value.
1.501 + */
1.502 +PurpleValue *purple_status_attr_get_value(const PurpleStatusAttr *attr);
1.503 +
1.504 +/*@}*/
1.505 +
1.506 +/**************************************************************************/
1.507 +/** @name PurpleStatus API */
1.508 +/**************************************************************************/
1.509 +/*@{*/
1.510 +
1.511 +/**
1.512 + * Creates a new status.
1.513 + *
1.514 + * @param status_type The type of status.
1.515 + * @param presence The parent presence.
1.516 + *
1.517 + * @return The new status.
1.518 + */
1.519 +PurpleStatus *purple_status_new(PurpleStatusType *status_type,
1.520 + PurplePresence *presence);
1.521 +
1.522 +/**
1.523 + * Destroys a status.
1.524 + *
1.525 + * @param status The status to destroy.
1.526 + */
1.527 +void purple_status_destroy(PurpleStatus *status);
1.528 +
1.529 +/**
1.530 + * Sets whether or not a status is active.
1.531 + *
1.532 + * This should only be called by the account, conversation, and buddy APIs.
1.533 + *
1.534 + * @param status The status.
1.535 + * @param active The active state.
1.536 + */
1.537 +void purple_status_set_active(PurpleStatus *status, gboolean active);
1.538 +
1.539 +/**
1.540 + * Sets whether or not a status is active.
1.541 + *
1.542 + * This should only be called by the account, conversation, and buddy APIs.
1.543 + *
1.544 + * @param status The status.
1.545 + * @param active The active state.
1.546 + * @param args A list of attributes to set on the status. This list is
1.547 + * composed of key/value pairs, where each key is a valid
1.548 + * attribute name for this PurpleStatusType. The list should
1.549 + * be NULL terminated.
1.550 + */
1.551 +void purple_status_set_active_with_attrs(PurpleStatus *status, gboolean active,
1.552 + va_list args);
1.553 +
1.554 +/**
1.555 + * Sets whether or not a status is active.
1.556 + *
1.557 + * This should only be called by the account, conversation, and buddy APIs.
1.558 + *
1.559 + * @param status The status.
1.560 + * @param active The active state.
1.561 + * @param attrs A list of attributes to set on the status. This list is
1.562 + * composed of key/value pairs, where each key is a valid
1.563 + * attribute name for this PurpleStatusType. The list is
1.564 + * not modified or freed by this function.
1.565 + */
1.566 +void purple_status_set_active_with_attrs_list(PurpleStatus *status, gboolean active,
1.567 + GList *attrs);
1.568 +
1.569 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_)
1.570 +/**
1.571 + * Sets the boolean value of an attribute in a status with the specified ID.
1.572 + *
1.573 + * @param status The status.
1.574 + * @param id The attribute ID.
1.575 + * @param value The boolean value.
1.576 + *
1.577 + * @deprecated This function is only used by status.c and should be made
1.578 + * static in 3.0.0.
1.579 + */
1.580 +void purple_status_set_attr_boolean(PurpleStatus *status, const char *id,
1.581 + gboolean value);
1.582 +#endif
1.583 +
1.584 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_)
1.585 +/**
1.586 + * Sets the integer value of an attribute in a status with the specified ID.
1.587 + *
1.588 + * @param status The status.
1.589 + * @param id The attribute ID.
1.590 + * @param value The integer value.
1.591 + *
1.592 + * @deprecated This function is only used by status.c and should be made
1.593 + * static in 3.0.0.
1.594 + */
1.595 +void purple_status_set_attr_int(PurpleStatus *status, const char *id,
1.596 + int value);
1.597 +#endif
1.598 +
1.599 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_)
1.600 +/**
1.601 + * Sets the string value of an attribute in a status with the specified ID.
1.602 + *
1.603 + * @param status The status.
1.604 + * @param id The attribute ID.
1.605 + * @param value The string value.
1.606 + *
1.607 + * @deprecated This function is only used by status.c and should be made
1.608 + * static in 3.0.0.
1.609 + */
1.610 +void purple_status_set_attr_string(PurpleStatus *status, const char *id,
1.611 + const char *value);
1.612 +#endif
1.613 +
1.614 +/**
1.615 + * Returns the status's type.
1.616 + *
1.617 + * @param status The status.
1.618 + *
1.619 + * @return The status's type.
1.620 + */
1.621 +PurpleStatusType *purple_status_get_type(const PurpleStatus *status);
1.622 +
1.623 +/**
1.624 + * Returns the status's presence.
1.625 + *
1.626 + * @param status The status.
1.627 + *
1.628 + * @return The status's presence.
1.629 + */
1.630 +PurplePresence *purple_status_get_presence(const PurpleStatus *status);
1.631 +
1.632 +/**
1.633 + * Returns the status's type ID.
1.634 + *
1.635 + * This is a convenience method for
1.636 + * purple_status_type_get_id(purple_status_get_type(status)).
1.637 + *
1.638 + * @param status The status.
1.639 + *
1.640 + * @return The status's ID.
1.641 + */
1.642 +const char *purple_status_get_id(const PurpleStatus *status);
1.643 +
1.644 +/**
1.645 + * Returns the status's name.
1.646 + *
1.647 + * This is a convenience method for
1.648 + * purple_status_type_get_name(purple_status_get_type(status)).
1.649 + *
1.650 + * @param status The status.
1.651 + *
1.652 + * @return The status's name.
1.653 + */
1.654 +const char *purple_status_get_name(const PurpleStatus *status);
1.655 +
1.656 +/**
1.657 + * Returns whether or not a status is independent.
1.658 + *
1.659 + * This is a convenience method for
1.660 + * purple_status_type_is_independent(purple_status_get_type(status)).
1.661 + *
1.662 + * @param status The status.
1.663 + *
1.664 + * @return TRUE if the status is independent, or FALSE otherwise.
1.665 + */
1.666 +gboolean purple_status_is_independent(const PurpleStatus *status);
1.667 +
1.668 +/**
1.669 + * Returns whether or not a status is exclusive.
1.670 + *
1.671 + * This is a convenience method for
1.672 + * purple_status_type_is_exclusive(purple_status_get_type(status)).
1.673 + *
1.674 + * @param status The status.
1.675 + *
1.676 + * @return TRUE if the status is exclusive, FALSE otherwise.
1.677 + */
1.678 +gboolean purple_status_is_exclusive(const PurpleStatus *status);
1.679 +
1.680 +/**
1.681 + * Returns whether or not a status is available.
1.682 + *
1.683 + * Available statuses are online and possibly invisible, but not away or idle.
1.684 + *
1.685 + * This is a convenience method for
1.686 + * purple_status_type_is_available(purple_status_get_type(status)).
1.687 + *
1.688 + * @param status The status.
1.689 + *
1.690 + * @return TRUE if the status is available, or FALSE otherwise.
1.691 + */
1.692 +gboolean purple_status_is_available(const PurpleStatus *status);
1.693 +
1.694 +/**
1.695 + * Returns the active state of a status.
1.696 + *
1.697 + * @param status The status.
1.698 + *
1.699 + * @return The active state of the status.
1.700 + */
1.701 +gboolean purple_status_is_active(const PurpleStatus *status);
1.702 +
1.703 +/**
1.704 + * Returns whether or not a status is considered 'online'
1.705 + *
1.706 + * @param status The status.
1.707 + *
1.708 + * @return TRUE if the status is considered online, FALSE otherwise
1.709 + */
1.710 +gboolean purple_status_is_online(const PurpleStatus *status);
1.711 +
1.712 +/**
1.713 + * Returns the value of an attribute in a status with the specified ID.
1.714 + *
1.715 + * @param status The status.
1.716 + * @param id The attribute ID.
1.717 + *
1.718 + * @return The value of the attribute.
1.719 + */
1.720 +PurpleValue *purple_status_get_attr_value(const PurpleStatus *status,
1.721 + const char *id);
1.722 +
1.723 +/**
1.724 + * Returns the boolean value of an attribute in a status with the specified ID.
1.725 + *
1.726 + * @param status The status.
1.727 + * @param id The attribute ID.
1.728 + *
1.729 + * @return The boolean value of the attribute.
1.730 + */
1.731 +gboolean purple_status_get_attr_boolean(const PurpleStatus *status,
1.732 + const char *id);
1.733 +
1.734 +/**
1.735 + * Returns the integer value of an attribute in a status with the specified ID.
1.736 + *
1.737 + * @param status The status.
1.738 + * @param id The attribute ID.
1.739 + *
1.740 + * @return The integer value of the attribute.
1.741 + */
1.742 +int purple_status_get_attr_int(const PurpleStatus *status, const char *id);
1.743 +
1.744 +/**
1.745 + * Returns the string value of an attribute in a status with the specified ID.
1.746 + *
1.747 + * @param status The status.
1.748 + * @param id The attribute ID.
1.749 + *
1.750 + * @return The string value of the attribute.
1.751 + */
1.752 +const char *purple_status_get_attr_string(const PurpleStatus *status,
1.753 + const char *id);
1.754 +
1.755 +/**
1.756 + * Compares two statuses for availability.
1.757 + *
1.758 + * @param status1 The first status.
1.759 + * @param status2 The second status.
1.760 + *
1.761 + * @return -1 if @a status1 is more available than @a status2.
1.762 + * 0 if @a status1 is equal to @a status2.
1.763 + * 1 if @a status2 is more available than @a status1.
1.764 + */
1.765 +gint purple_status_compare(const PurpleStatus *status1, const PurpleStatus *status2);
1.766 +
1.767 +/*@}*/
1.768 +
1.769 +/**************************************************************************/
1.770 +/** @name PurplePresence API */
1.771 +/**************************************************************************/
1.772 +/*@{*/
1.773 +
1.774 +/**
1.775 + * Creates a new presence.
1.776 + *
1.777 + * @param context The presence context.
1.778 + *
1.779 + * @return A new presence.
1.780 + */
1.781 +PurplePresence *purple_presence_new(PurplePresenceContext context);
1.782 +
1.783 +/**
1.784 + * Creates a presence for an account.
1.785 + *
1.786 + * @param account The account.
1.787 + *
1.788 + * @return The new presence.
1.789 + */
1.790 +PurplePresence *purple_presence_new_for_account(PurpleAccount *account);
1.791 +
1.792 +/**
1.793 + * Creates a presence for a conversation.
1.794 + *
1.795 + * @param conv The conversation.
1.796 + *
1.797 + * @return The new presence.
1.798 + */
1.799 +PurplePresence *purple_presence_new_for_conv(PurpleConversation *conv);
1.800 +
1.801 +/**
1.802 + * Creates a presence for a buddy.
1.803 + *
1.804 + * @param buddy The buddy.
1.805 + *
1.806 + * @return The new presence.
1.807 + */
1.808 +PurplePresence *purple_presence_new_for_buddy(PurpleBuddy *buddy);
1.809 +
1.810 +/**
1.811 + * Destroys a presence.
1.812 + *
1.813 + * All statuses added to this list will be destroyed along with
1.814 + * the presence.
1.815 + *
1.816 + * @param presence The presence to destroy.
1.817 + */
1.818 +void purple_presence_destroy(PurplePresence *presence);
1.819 +
1.820 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_)
1.821 +/**
1.822 + * Adds a status to a presence.
1.823 + *
1.824 + * @param presence The presence.
1.825 + * @param status The status to add.
1.826 + *
1.827 + * @deprecated This function is only used by purple_presence_add_list,
1.828 + * and both should be removed in 3.0.0.
1.829 + */
1.830 +void purple_presence_add_status(PurplePresence *presence, PurpleStatus *status);
1.831 +#endif
1.832 +
1.833 +#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_STATUS_C_)
1.834 +/**
1.835 + * Adds a list of statuses to the presence.
1.836 + *
1.837 + * @param presence The presence.
1.838 + * @param source_list The source list of statuses to add, which is not
1.839 + * modified or freed by this function.
1.840 + *
1.841 + * @deprecated This function isn't used and should be removed in 3.0.0.
1.842 + */
1.843 +void purple_presence_add_list(PurplePresence *presence, GList *source_list);
1.844 +#endif
1.845 +
1.846 +/**
1.847 + * Sets the active state of a status in a presence.
1.848 + *
1.849 + * Only independent statuses can be set unactive. Normal statuses can only
1.850 + * be set active, so if you wish to disable a status, set another
1.851 + * non-independent status to active, or use purple_presence_switch_status().
1.852 + *
1.853 + * @param presence The presence.
1.854 + * @param status_id The ID of the status.
1.855 + * @param active The active state.
1.856 + */
1.857 +void purple_presence_set_status_active(PurplePresence *presence,
1.858 + const char *status_id, gboolean active);
1.859 +
1.860 +/**
1.861 + * Switches the active status in a presence.
1.862 + *
1.863 + * This is similar to purple_presence_set_status_active(), except it won't
1.864 + * activate independent statuses.
1.865 + *
1.866 + * @param presence The presence.
1.867 + * @param status_id The status ID to switch to.
1.868 + */
1.869 +void purple_presence_switch_status(PurplePresence *presence,
1.870 + const char *status_id);
1.871 +
1.872 +/**
1.873 + * Sets the idle state and time on a presence.
1.874 + *
1.875 + * @param presence The presence.
1.876 + * @param idle The idle state.
1.877 + * @param idle_time The idle time, if @a idle is TRUE. This
1.878 + * is the time at which the user became idle,
1.879 + * in seconds since the epoch. If this value is
1.880 + * unknown then 0 should be used.
1.881 + */
1.882 +void purple_presence_set_idle(PurplePresence *presence, gboolean idle,
1.883 + time_t idle_time);
1.884 +
1.885 +/**
1.886 + * Sets the login time on a presence.
1.887 + *
1.888 + * @param presence The presence.
1.889 + * @param login_time The login time.
1.890 + */
1.891 +void purple_presence_set_login_time(PurplePresence *presence, time_t login_time);
1.892 +
1.893 +
1.894 +/**
1.895 + * Returns the presence's context.
1.896 + *
1.897 + * @param presence The presence.
1.898 + *
1.899 + * @return The presence's context.
1.900 + */
1.901 +PurplePresenceContext purple_presence_get_context(const PurplePresence *presence);
1.902 +
1.903 +/**
1.904 + * Returns a presence's account.
1.905 + *
1.906 + * @param presence The presence.
1.907 + *
1.908 + * @return The presence's account.
1.909 + */
1.910 +PurpleAccount *purple_presence_get_account(const PurplePresence *presence);
1.911 +
1.912 +/**
1.913 + * Returns a presence's conversation.
1.914 + *
1.915 + * @param presence The presence.
1.916 + *
1.917 + * @return The presence's conversation.
1.918 + */
1.919 +PurpleConversation *purple_presence_get_conversation(const PurplePresence *presence);
1.920 +
1.921 +/**
1.922 + * Returns a presence's chat user.
1.923 + *
1.924 + * @param presence The presence.
1.925 + *
1.926 + * @return The chat's user.
1.927 + */
1.928 +const char *purple_presence_get_chat_user(const PurplePresence *presence);
1.929 +
1.930 +/**
1.931 + * Returns the presence's buddy.
1.932 + *
1.933 + * @param presence The presence.
1.934 + *
1.935 + * @return The presence's buddy.
1.936 + */
1.937 +PurpleBuddy *purple_presence_get_buddy(const PurplePresence *presence);
1.938 +
1.939 +/**
1.940 + * Returns all the statuses in a presence.
1.941 + *
1.942 + * @param presence The presence.
1.943 + *
1.944 + * @constreturn The statuses.
1.945 + */
1.946 +GList *purple_presence_get_statuses(const PurplePresence *presence);
1.947 +
1.948 +/**
1.949 + * Returns the status with the specified ID from a presence.
1.950 + *
1.951 + * @param presence The presence.
1.952 + * @param status_id The ID of the status.
1.953 + *
1.954 + * @return The status if found, or NULL.
1.955 + */
1.956 +PurpleStatus *purple_presence_get_status(const PurplePresence *presence,
1.957 + const char *status_id);
1.958 +
1.959 +/**
1.960 + * Returns the active exclusive status from a presence.
1.961 + *
1.962 + * @param presence The presence.
1.963 + *
1.964 + * @return The active exclusive status.
1.965 + */
1.966 +PurpleStatus *purple_presence_get_active_status(const PurplePresence *presence);
1.967 +
1.968 +/**
1.969 + * Returns whether or not a presence is available.
1.970 + *
1.971 + * Available presences are online and possibly invisible, but not away or idle.
1.972 + *
1.973 + * @param presence The presence.
1.974 + *
1.975 + * @return TRUE if the presence is available, or FALSE otherwise.
1.976 + */
1.977 +gboolean purple_presence_is_available(const PurplePresence *presence);
1.978 +
1.979 +/**
1.980 + * Returns whether or not a presence is online.
1.981 + *
1.982 + * @param presence The presence.
1.983 + *
1.984 + * @return TRUE if the presence is online, or FALSE otherwise.
1.985 + */
1.986 +gboolean purple_presence_is_online(const PurplePresence *presence);
1.987 +
1.988 +/**
1.989 + * Returns whether or not a status in a presence is active.
1.990 + *
1.991 + * A status is active if itself or any of its sub-statuses are active.
1.992 + *
1.993 + * @param presence The presence.
1.994 + * @param status_id The ID of the status.
1.995 + *
1.996 + * @return TRUE if the status is active, or FALSE.
1.997 + */
1.998 +gboolean purple_presence_is_status_active(const PurplePresence *presence,
1.999 + const char *status_id);
1.1000 +
1.1001 +/**
1.1002 + * Returns whether or not a status with the specified primitive type
1.1003 + * in a presence is active.
1.1004 + *
1.1005 + * A status is active if itself or any of its sub-statuses are active.
1.1006 + *
1.1007 + * @param presence The presence.
1.1008 + * @param primitive The status primitive.
1.1009 + *
1.1010 + * @return TRUE if the status is active, or FALSE.
1.1011 + */
1.1012 +gboolean purple_presence_is_status_primitive_active(
1.1013 + const PurplePresence *presence, PurpleStatusPrimitive primitive);
1.1014 +
1.1015 +/**
1.1016 + * Returns whether or not a presence is idle.
1.1017 + *
1.1018 + * @param presence The presence.
1.1019 + *
1.1020 + * @return TRUE if the presence is idle, or FALSE otherwise.
1.1021 + * If the presence is offline (purple_presence_is_online()
1.1022 + * returns FALSE) then FALSE is returned.
1.1023 + */
1.1024 +gboolean purple_presence_is_idle(const PurplePresence *presence);
1.1025 +
1.1026 +/**
1.1027 + * Returns the presence's idle time.
1.1028 + *
1.1029 + * @param presence The presence.
1.1030 + *
1.1031 + * @return The presence's idle time.
1.1032 + */
1.1033 +time_t purple_presence_get_idle_time(const PurplePresence *presence);
1.1034 +
1.1035 +/**
1.1036 + * Returns the presence's login time.
1.1037 + *
1.1038 + * @param presence The presence.
1.1039 + *
1.1040 + * @return The presence's login time.
1.1041 + */
1.1042 +time_t purple_presence_get_login_time(const PurplePresence *presence);
1.1043 +
1.1044 +/**
1.1045 + * Compares two presences for availability.
1.1046 + *
1.1047 + * @param presence1 The first presence.
1.1048 + * @param presence2 The second presence.
1.1049 + *
1.1050 + * @return -1 if @a presence1 is more available than @a presence2.
1.1051 + * 0 if @a presence1 is equal to @a presence2.
1.1052 + * 1 if @a presence1 is less available than @a presence2.
1.1053 + */
1.1054 +gint purple_presence_compare(const PurplePresence *presence1,
1.1055 + const PurplePresence *presence2);
1.1056 +
1.1057 +/*@}*/
1.1058 +
1.1059 +/**************************************************************************/
1.1060 +/** @name Status subsystem */
1.1061 +/**************************************************************************/
1.1062 +/*@{*/
1.1063 +
1.1064 +/**
1.1065 + * Get the handle for the status subsystem.
1.1066 + *
1.1067 + * @return the handle to the status subsystem
1.1068 + */
1.1069 +void *purple_status_get_handle(void);
1.1070 +
1.1071 +/**
1.1072 + * Initializes the status subsystem.
1.1073 + */
1.1074 +void purple_status_init(void);
1.1075 +
1.1076 +/**
1.1077 + * Uninitializes the status subsystem.
1.1078 + */
1.1079 +void purple_status_uninit(void);
1.1080 +
1.1081 +/*@}*/
1.1082 +
1.1083 +#ifdef __cplusplus
1.1084 +}
1.1085 +#endif
1.1086 +
1.1087 +#endif /* _PURPLE_STATUS_H_ */