1.1 --- a/Frameworks/libpurple.framework/Versions/0.5.6/Headers/status.h Sun Jun 21 22:04:11 2009 -0400
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,1034 +0,0 @@
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 "savable" boolean.
1.57 - * If "savable" 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 "indepedent" or "exclusive."
1.62 - * Independent statuses can be active or inactive and it doesn't
1.63 - * affect anything else. However, you can only have one exclusive
1.64 - * status per PurplePresence. If you activate one exlusive 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 you're chatting with, 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 relevent
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 what the presence applies to.
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 -/**
1.259 - * Sets a status type's primary attribute.
1.260 - *
1.261 - * The value for the primary attribute is used as the description for
1.262 - * the particular status type. An example is an away message. The message
1.263 - * would be the primary attribute.
1.264 - *
1.265 - * @param status_type The status type.
1.266 - * @param attr_id The ID of the primary attribute.
1.267 - */
1.268 -void purple_status_type_set_primary_attr(PurpleStatusType *status_type,
1.269 - const char *attr_id);
1.270 -
1.271 -/**
1.272 - * Adds an attribute to a status type.
1.273 - *
1.274 - * @param status_type The status type to add the attribute to.
1.275 - * @param id The ID of the attribute.
1.276 - * @param name The name presented to the user.
1.277 - * @param value The value type of this attribute.
1.278 - */
1.279 -void purple_status_type_add_attr(PurpleStatusType *status_type, const char *id,
1.280 - const char *name, PurpleValue *value);
1.281 -
1.282 -/**
1.283 - * Adds multiple attributes to a status type.
1.284 - *
1.285 - * @param status_type The status type to add the attribute to.
1.286 - * @param id The ID of the first attribute.
1.287 - * @param name The description of the first attribute.
1.288 - * @param value The value type of the first attribute attribute.
1.289 - * @param ... Additional attribute information.
1.290 - */
1.291 -void purple_status_type_add_attrs(PurpleStatusType *status_type, const char *id,
1.292 - const char *name, PurpleValue *value, ...) G_GNUC_NULL_TERMINATED;
1.293 -
1.294 -/**
1.295 - * Adds multiple attributes to a status type using a va_list.
1.296 - *
1.297 - * @param status_type The status type to add the attribute to.
1.298 - * @param args The va_list of attributes.
1.299 - */
1.300 -void purple_status_type_add_attrs_vargs(PurpleStatusType *status_type,
1.301 - va_list args);
1.302 -
1.303 -/**
1.304 - * Returns the primitive type of a status type.
1.305 - *
1.306 - * @param status_type The status type.
1.307 - *
1.308 - * @return The primitive type of the status type.
1.309 - */
1.310 -PurpleStatusPrimitive purple_status_type_get_primitive(
1.311 - const PurpleStatusType *status_type);
1.312 -
1.313 -/**
1.314 - * Returns the ID of a status type.
1.315 - *
1.316 - * @param status_type The status type.
1.317 - *
1.318 - * @return The ID of the status type.
1.319 - */
1.320 -const char *purple_status_type_get_id(const PurpleStatusType *status_type);
1.321 -
1.322 -/**
1.323 - * Returns the name of a status type.
1.324 - *
1.325 - * @param status_type The status type.
1.326 - *
1.327 - * @return The name of the status type.
1.328 - */
1.329 -const char *purple_status_type_get_name(const PurpleStatusType *status_type);
1.330 -
1.331 -/**
1.332 - * Returns whether or not the status type is saveable.
1.333 - *
1.334 - * @param status_type The status type.
1.335 - *
1.336 - * @return TRUE if user-defined statuses based off this type are saveable.
1.337 - * FALSE otherwise.
1.338 - */
1.339 -gboolean purple_status_type_is_saveable(const PurpleStatusType *status_type);
1.340 -
1.341 -/**
1.342 - * Returns whether or not the status type can be set or modified by the
1.343 - * user.
1.344 - *
1.345 - * @param status_type The status type.
1.346 - *
1.347 - * @return TRUE if the status type can be set or modified by the user.
1.348 - * FALSE if it's a protocol-set setting.
1.349 - */
1.350 -gboolean purple_status_type_is_user_settable(const PurpleStatusType *status_type);
1.351 -
1.352 -/**
1.353 - * Returns whether or not the status type is independent.
1.354 - *
1.355 - * Independent status types are non-exclusive. If other status types on
1.356 - * the same hierarchy level are set, this one will not be affected.
1.357 - *
1.358 - * @param status_type The status type.
1.359 - *
1.360 - * @return TRUE if the status type is independent, or FALSE otherwise.
1.361 - */
1.362 -gboolean purple_status_type_is_independent(const PurpleStatusType *status_type);
1.363 -
1.364 -/**
1.365 - * Returns whether the status type is exclusive.
1.366 - *
1.367 - * @param status_type The status type.
1.368 - *
1.369 - * @return TRUE if the status type is exclusive, FALSE otherwise.
1.370 - */
1.371 -gboolean purple_status_type_is_exclusive(const PurpleStatusType *status_type);
1.372 -
1.373 -/**
1.374 - * Returns whether or not a status type is available.
1.375 - *
1.376 - * Available status types are online and possibly invisible, but not away.
1.377 - *
1.378 - * @param status_type The status type.
1.379 - *
1.380 - * @return TRUE if the status is available, or FALSE otherwise.
1.381 - */
1.382 -gboolean purple_status_type_is_available(const PurpleStatusType *status_type);
1.383 -
1.384 -/**
1.385 - * Returns a status type's primary attribute ID.
1.386 - *
1.387 - * @param type The status type.
1.388 - *
1.389 - * @return The primary attribute's ID.
1.390 - */
1.391 -const char *purple_status_type_get_primary_attr(const PurpleStatusType *type);
1.392 -
1.393 -/**
1.394 - * Returns the attribute with the specified ID.
1.395 - *
1.396 - * @param status_type The status type containing the attribute.
1.397 - * @param id The ID of the desired attribute.
1.398 - *
1.399 - * @return The attribute, if found. NULL otherwise.
1.400 - */
1.401 -PurpleStatusAttr *purple_status_type_get_attr(const PurpleStatusType *status_type,
1.402 - const char *id);
1.403 -
1.404 -/**
1.405 - * Returns a list of all attributes in a status type.
1.406 - *
1.407 - * @param status_type The status type.
1.408 - *
1.409 - * @constreturn The list of attributes.
1.410 - */
1.411 -GList *purple_status_type_get_attrs(const PurpleStatusType *status_type);
1.412 -
1.413 -/**
1.414 - * Find the PurpleStatusType with the given id.
1.415 - *
1.416 - * @param status_types A list of status types. Often account->status_types.
1.417 - * @param id The unique ID of the status type you wish to find.
1.418 - *
1.419 - * @return The status type with the given ID, or NULL if one could
1.420 - * not be found.
1.421 - */
1.422 -const PurpleStatusType *purple_status_type_find_with_id(GList *status_types,
1.423 - const char *id);
1.424 -
1.425 -/*@}*/
1.426 -
1.427 -/**************************************************************************/
1.428 -/** @name PurpleStatusAttr API */
1.429 -/**************************************************************************/
1.430 -/*@{*/
1.431 -
1.432 -/**
1.433 - * Creates a new status attribute.
1.434 - *
1.435 - * @param id The ID of the attribute.
1.436 - * @param name The name presented to the user.
1.437 - * @param value_type The type of data contained in the attribute.
1.438 - *
1.439 - * @return A new status attribute.
1.440 - */
1.441 -PurpleStatusAttr *purple_status_attr_new(const char *id, const char *name,
1.442 - PurpleValue *value_type);
1.443 -
1.444 -/**
1.445 - * Destroys a status attribute.
1.446 - *
1.447 - * @param attr The status attribute to destroy.
1.448 - */
1.449 -void purple_status_attr_destroy(PurpleStatusAttr *attr);
1.450 -
1.451 -/**
1.452 - * Returns the ID of a status attribute.
1.453 - *
1.454 - * @param attr The status attribute.
1.455 - *
1.456 - * @return The status attribute's ID.
1.457 - */
1.458 -const char *purple_status_attr_get_id(const PurpleStatusAttr *attr);
1.459 -
1.460 -/**
1.461 - * Returns the name of a status attribute.
1.462 - *
1.463 - * @param attr The status attribute.
1.464 - *
1.465 - * @return The status attribute's name.
1.466 - */
1.467 -const char *purple_status_attr_get_name(const PurpleStatusAttr *attr);
1.468 -
1.469 -/**
1.470 - * Returns the value of a status attribute.
1.471 - *
1.472 - * @param attr The status attribute.
1.473 - *
1.474 - * @return The status attribute's value.
1.475 - */
1.476 -PurpleValue *purple_status_attr_get_value(const PurpleStatusAttr *attr);
1.477 -
1.478 -/*@}*/
1.479 -
1.480 -/**************************************************************************/
1.481 -/** @name PurpleStatus API */
1.482 -/**************************************************************************/
1.483 -/*@{*/
1.484 -
1.485 -/**
1.486 - * Creates a new status.
1.487 - *
1.488 - * @param status_type The type of status.
1.489 - * @param presence The parent presence.
1.490 - *
1.491 - * @return The new status.
1.492 - */
1.493 -PurpleStatus *purple_status_new(PurpleStatusType *status_type,
1.494 - PurplePresence *presence);
1.495 -
1.496 -/**
1.497 - * Destroys a status.
1.498 - *
1.499 - * @param status The status to destroy.
1.500 - */
1.501 -void purple_status_destroy(PurpleStatus *status);
1.502 -
1.503 -/**
1.504 - * Sets whether or not a status is active.
1.505 - *
1.506 - * This should only be called by the account, conversation, and buddy APIs.
1.507 - *
1.508 - * @param status The status.
1.509 - * @param active The active state.
1.510 - */
1.511 -void purple_status_set_active(PurpleStatus *status, gboolean active);
1.512 -
1.513 -/**
1.514 - * Sets whether or not a status is active.
1.515 - *
1.516 - * This should only be called by the account, conversation, and buddy APIs.
1.517 - *
1.518 - * @param status The status.
1.519 - * @param active The active state.
1.520 - * @param args A list of attributes to set on the status. This list is
1.521 - * composed of key/value pairs, where each key is a valid
1.522 - * attribute name for this PurpleStatusType. The list should
1.523 - * be NULL terminated.
1.524 - */
1.525 -void purple_status_set_active_with_attrs(PurpleStatus *status, gboolean active,
1.526 - va_list args);
1.527 -
1.528 -/**
1.529 - * Sets whether or not a status is active.
1.530 - *
1.531 - * This should only be called by the account, conversation, and buddy APIs.
1.532 - *
1.533 - * @param status The status.
1.534 - * @param active The active state.
1.535 - * @param attrs A list of attributes to set on the status. This list is
1.536 - * composed of key/value pairs, where each key is a valid
1.537 - * attribute name for this PurpleStatusType. The list is
1.538 - * not modified or freed by this function.
1.539 - */
1.540 -void purple_status_set_active_with_attrs_list(PurpleStatus *status, gboolean active,
1.541 - GList *attrs);
1.542 -
1.543 -/**
1.544 - * Sets the boolean value of an attribute in a status with the specified ID.
1.545 - *
1.546 - * @param status The status.
1.547 - * @param id The attribute ID.
1.548 - * @param value The boolean value.
1.549 - */
1.550 -void purple_status_set_attr_boolean(PurpleStatus *status, const char *id,
1.551 - gboolean value);
1.552 -
1.553 -/**
1.554 - * Sets the integer value of an attribute in a status with the specified ID.
1.555 - *
1.556 - * @param status The status.
1.557 - * @param id The attribute ID.
1.558 - * @param value The integer value.
1.559 - */
1.560 -void purple_status_set_attr_int(PurpleStatus *status, const char *id,
1.561 - int value);
1.562 -
1.563 -/**
1.564 - * Sets the string value of an attribute in a status with the specified ID.
1.565 - *
1.566 - * @param status The status.
1.567 - * @param id The attribute ID.
1.568 - * @param value The string value.
1.569 - */
1.570 -void purple_status_set_attr_string(PurpleStatus *status, const char *id,
1.571 - const char *value);
1.572 -
1.573 -/**
1.574 - * Returns the status's type.
1.575 - *
1.576 - * @param status The status.
1.577 - *
1.578 - * @return The status's type.
1.579 - */
1.580 -PurpleStatusType *purple_status_get_type(const PurpleStatus *status);
1.581 -
1.582 -/**
1.583 - * Returns the status's presence.
1.584 - *
1.585 - * @param status The status.
1.586 - *
1.587 - * @return The status's presence.
1.588 - */
1.589 -PurplePresence *purple_status_get_presence(const PurpleStatus *status);
1.590 -
1.591 -/**
1.592 - * Returns the status's type ID.
1.593 - *
1.594 - * This is a convenience method for
1.595 - * purple_status_type_get_id(purple_status_get_type(status)).
1.596 - *
1.597 - * @param status The status.
1.598 - *
1.599 - * @return The status's ID.
1.600 - */
1.601 -const char *purple_status_get_id(const PurpleStatus *status);
1.602 -
1.603 -/**
1.604 - * Returns the status's name.
1.605 - *
1.606 - * This is a convenience method for
1.607 - * purple_status_type_get_name(purple_status_get_type(status)).
1.608 - *
1.609 - * @param status The status.
1.610 - *
1.611 - * @return The status's name.
1.612 - */
1.613 -const char *purple_status_get_name(const PurpleStatus *status);
1.614 -
1.615 -/**
1.616 - * Returns whether or not a status is independent.
1.617 - *
1.618 - * This is a convenience method for
1.619 - * purple_status_type_is_independent(purple_status_get_type(status)).
1.620 - *
1.621 - * @param status The status.
1.622 - *
1.623 - * @return TRUE if the status is independent, or FALSE otherwise.
1.624 - */
1.625 -gboolean purple_status_is_independent(const PurpleStatus *status);
1.626 -
1.627 -/**
1.628 - * Returns whether or not a status is exclusive.
1.629 - *
1.630 - * This is a convenience method for
1.631 - * purple_status_type_is_exclusive(purple_status_get_type(status)).
1.632 - *
1.633 - * @param status The status.
1.634 - *
1.635 - * @return TRUE if the status is exclusive, FALSE otherwise.
1.636 - */
1.637 -gboolean purple_status_is_exclusive(const PurpleStatus *status);
1.638 -
1.639 -/**
1.640 - * Returns whether or not a status is available.
1.641 - *
1.642 - * Available statuses are online and possibly invisible, but not away or idle.
1.643 - *
1.644 - * This is a convenience method for
1.645 - * purple_status_type_is_available(purple_status_get_type(status)).
1.646 - *
1.647 - * @param status The status.
1.648 - *
1.649 - * @return TRUE if the status is available, or FALSE otherwise.
1.650 - */
1.651 -gboolean purple_status_is_available(const PurpleStatus *status);
1.652 -
1.653 -/**
1.654 - * Returns the active state of a status.
1.655 - *
1.656 - * @param status The status.
1.657 - *
1.658 - * @return The active state of the status.
1.659 - */
1.660 -gboolean purple_status_is_active(const PurpleStatus *status);
1.661 -
1.662 -/**
1.663 - * Returns whether or not a status is considered 'online'
1.664 - *
1.665 - * @param status The status.
1.666 - *
1.667 - * @return TRUE if the status is considered online, FALSE otherwise
1.668 - */
1.669 -gboolean purple_status_is_online(const PurpleStatus *status);
1.670 -
1.671 -/**
1.672 - * Returns the value of an attribute in a status with the specified ID.
1.673 - *
1.674 - * @param status The status.
1.675 - * @param id The attribute ID.
1.676 - *
1.677 - * @return The value of the attribute.
1.678 - */
1.679 -PurpleValue *purple_status_get_attr_value(const PurpleStatus *status,
1.680 - const char *id);
1.681 -
1.682 -/**
1.683 - * Returns the boolean value of an attribute in a status with the specified ID.
1.684 - *
1.685 - * @param status The status.
1.686 - * @param id The attribute ID.
1.687 - *
1.688 - * @return The boolean value of the attribute.
1.689 - */
1.690 -gboolean purple_status_get_attr_boolean(const PurpleStatus *status,
1.691 - const char *id);
1.692 -
1.693 -/**
1.694 - * Returns the integer value of an attribute in a status with the specified ID.
1.695 - *
1.696 - * @param status The status.
1.697 - * @param id The attribute ID.
1.698 - *
1.699 - * @return The integer value of the attribute.
1.700 - */
1.701 -int purple_status_get_attr_int(const PurpleStatus *status, const char *id);
1.702 -
1.703 -/**
1.704 - * Returns the string value of an attribute in a status with the specified ID.
1.705 - *
1.706 - * @param status The status.
1.707 - * @param id The attribute ID.
1.708 - *
1.709 - * @return The string value of the attribute.
1.710 - */
1.711 -const char *purple_status_get_attr_string(const PurpleStatus *status,
1.712 - const char *id);
1.713 -
1.714 -/**
1.715 - * Compares two statuses for availability.
1.716 - *
1.717 - * @param status1 The first status.
1.718 - * @param status2 The second status.
1.719 - *
1.720 - * @return -1 if @a status1 is more available than @a status2.
1.721 - * 0 if @a status1 is equal to @a status2.
1.722 - * 1 if @a status2 is more available than @a status1.
1.723 - */
1.724 -gint purple_status_compare(const PurpleStatus *status1, const PurpleStatus *status2);
1.725 -
1.726 -/*@}*/
1.727 -
1.728 -/**************************************************************************/
1.729 -/** @name PurplePresence API */
1.730 -/**************************************************************************/
1.731 -/*@{*/
1.732 -
1.733 -/**
1.734 - * Creates a new presence.
1.735 - *
1.736 - * @param context The presence context.
1.737 - *
1.738 - * @return A new presence.
1.739 - */
1.740 -PurplePresence *purple_presence_new(PurplePresenceContext context);
1.741 -
1.742 -/**
1.743 - * Creates a presence for an account.
1.744 - *
1.745 - * @param account The account.
1.746 - *
1.747 - * @return The new presence.
1.748 - */
1.749 -PurplePresence *purple_presence_new_for_account(PurpleAccount *account);
1.750 -
1.751 -/**
1.752 - * Creates a presence for a conversation.
1.753 - *
1.754 - * @param conv The conversation.
1.755 - *
1.756 - * @return The new presence.
1.757 - */
1.758 -PurplePresence *purple_presence_new_for_conv(PurpleConversation *conv);
1.759 -
1.760 -/**
1.761 - * Creates a presence for a buddy.
1.762 - *
1.763 - * @param buddy The buddy.
1.764 - *
1.765 - * @return The new presence.
1.766 - */
1.767 -PurplePresence *purple_presence_new_for_buddy(PurpleBuddy *buddy);
1.768 -
1.769 -/**
1.770 - * Destroys a presence.
1.771 - *
1.772 - * All statuses added to this list will be destroyed along with
1.773 - * the presence.
1.774 - *
1.775 - * @param presence The presence to destroy.
1.776 - */
1.777 -void purple_presence_destroy(PurplePresence *presence);
1.778 -
1.779 -/**
1.780 - * Adds a status to a presence.
1.781 - *
1.782 - * @param presence The presence.
1.783 - * @param status The status to add.
1.784 - */
1.785 -void purple_presence_add_status(PurplePresence *presence, PurpleStatus *status);
1.786 -
1.787 -/**
1.788 - * Adds a list of statuses to the presence.
1.789 - *
1.790 - * @param presence The presence.
1.791 - * @param source_list The source list of statuses to add, which is not
1.792 - * modified or freed by this function.
1.793 - */
1.794 -void purple_presence_add_list(PurplePresence *presence, GList *source_list);
1.795 -
1.796 -/**
1.797 - * Sets the active state of a status in a presence.
1.798 - *
1.799 - * Only independent statuses can be set unactive. Normal statuses can only
1.800 - * be set active, so if you wish to disable a status, set another
1.801 - * non-independent status to active, or use purple_presence_switch_status().
1.802 - *
1.803 - * @param presence The presence.
1.804 - * @param status_id The ID of the status.
1.805 - * @param active The active state.
1.806 - */
1.807 -void purple_presence_set_status_active(PurplePresence *presence,
1.808 - const char *status_id, gboolean active);
1.809 -
1.810 -/**
1.811 - * Switches the active status in a presence.
1.812 - *
1.813 - * This is similar to purple_presence_set_status_active(), except it won't
1.814 - * activate independent statuses.
1.815 - *
1.816 - * @param presence The presence.
1.817 - * @param status_id The status ID to switch to.
1.818 - */
1.819 -void purple_presence_switch_status(PurplePresence *presence,
1.820 - const char *status_id);
1.821 -
1.822 -/**
1.823 - * Sets the idle state and time on a presence.
1.824 - *
1.825 - * @param presence The presence.
1.826 - * @param idle The idle state.
1.827 - * @param idle_time The idle time, if @a idle is TRUE. This
1.828 - * is the time at which the user became idle,
1.829 - * in seconds since the epoch. If this value is
1.830 - * unknown then 0 should be used.
1.831 - */
1.832 -void purple_presence_set_idle(PurplePresence *presence, gboolean idle,
1.833 - time_t idle_time);
1.834 -
1.835 -/**
1.836 - * Sets the login time on a presence.
1.837 - *
1.838 - * @param presence The presence.
1.839 - * @param login_time The login time.
1.840 - */
1.841 -void purple_presence_set_login_time(PurplePresence *presence, time_t login_time);
1.842 -
1.843 -
1.844 -/**
1.845 - * Returns the presence's context.
1.846 - *
1.847 - * @param presence The presence.
1.848 - *
1.849 - * @return The presence's context.
1.850 - */
1.851 -PurplePresenceContext purple_presence_get_context(const PurplePresence *presence);
1.852 -
1.853 -/**
1.854 - * Returns a presence's account.
1.855 - *
1.856 - * @param presence The presence.
1.857 - *
1.858 - * @return The presence's account.
1.859 - */
1.860 -PurpleAccount *purple_presence_get_account(const PurplePresence *presence);
1.861 -
1.862 -/**
1.863 - * Returns a presence's conversation.
1.864 - *
1.865 - * @param presence The presence.
1.866 - *
1.867 - * @return The presence's conversation.
1.868 - */
1.869 -PurpleConversation *purple_presence_get_conversation(const PurplePresence *presence);
1.870 -
1.871 -/**
1.872 - * Returns a presence's chat user.
1.873 - *
1.874 - * @param presence The presence.
1.875 - *
1.876 - * @return The chat's user.
1.877 - */
1.878 -const char *purple_presence_get_chat_user(const PurplePresence *presence);
1.879 -
1.880 -/**
1.881 - * Returns the presence's buddy.
1.882 - *
1.883 - * @param presence The presence.
1.884 - *
1.885 - * @return The presence's buddy.
1.886 - */
1.887 -PurpleBuddy *purple_presence_get_buddy(const PurplePresence *presence);
1.888 -
1.889 -/**
1.890 - * Returns all the statuses in a presence.
1.891 - *
1.892 - * @param presence The presence.
1.893 - *
1.894 - * @constreturn The statuses.
1.895 - */
1.896 -GList *purple_presence_get_statuses(const PurplePresence *presence);
1.897 -
1.898 -/**
1.899 - * Returns the status with the specified ID from a presence.
1.900 - *
1.901 - * @param presence The presence.
1.902 - * @param status_id The ID of the status.
1.903 - *
1.904 - * @return The status if found, or NULL.
1.905 - */
1.906 -PurpleStatus *purple_presence_get_status(const PurplePresence *presence,
1.907 - const char *status_id);
1.908 -
1.909 -/**
1.910 - * Returns the active exclusive status from a presence.
1.911 - *
1.912 - * @param presence The presence.
1.913 - *
1.914 - * @return The active exclusive status.
1.915 - */
1.916 -PurpleStatus *purple_presence_get_active_status(const PurplePresence *presence);
1.917 -
1.918 -/**
1.919 - * Returns whether or not a presence is available.
1.920 - *
1.921 - * Available presences are online and possibly invisible, but not away or idle.
1.922 - *
1.923 - * @param presence The presence.
1.924 - *
1.925 - * @return TRUE if the presence is available, or FALSE otherwise.
1.926 - */
1.927 -gboolean purple_presence_is_available(const PurplePresence *presence);
1.928 -
1.929 -/**
1.930 - * Returns whether or not a presence is online.
1.931 - *
1.932 - * @param presence The presence.
1.933 - *
1.934 - * @return TRUE if the presence is online, or FALSE otherwise.
1.935 - */
1.936 -gboolean purple_presence_is_online(const PurplePresence *presence);
1.937 -
1.938 -/**
1.939 - * Returns whether or not a status in a presence is active.
1.940 - *
1.941 - * A status is active if itself or any of its sub-statuses are active.
1.942 - *
1.943 - * @param presence The presence.
1.944 - * @param status_id The ID of the status.
1.945 - *
1.946 - * @return TRUE if the status is active, or FALSE.
1.947 - */
1.948 -gboolean purple_presence_is_status_active(const PurplePresence *presence,
1.949 - const char *status_id);
1.950 -
1.951 -/**
1.952 - * Returns whether or not a status with the specified primitive type
1.953 - * in a presence is active.
1.954 - *
1.955 - * A status is active if itself or any of its sub-statuses are active.
1.956 - *
1.957 - * @param presence The presence.
1.958 - * @param primitive The status primitive.
1.959 - *
1.960 - * @return TRUE if the status is active, or FALSE.
1.961 - */
1.962 -gboolean purple_presence_is_status_primitive_active(
1.963 - const PurplePresence *presence, PurpleStatusPrimitive primitive);
1.964 -
1.965 -/**
1.966 - * Returns whether or not a presence is idle.
1.967 - *
1.968 - * @param presence The presence.
1.969 - *
1.970 - * @return TRUE if the presence is idle, or FALSE otherwise.
1.971 - * If the presence is offline (purple_presence_is_online()
1.972 - * returns FALSE) then FALSE is returned.
1.973 - */
1.974 -gboolean purple_presence_is_idle(const PurplePresence *presence);
1.975 -
1.976 -/**
1.977 - * Returns the presence's idle time.
1.978 - *
1.979 - * @param presence The presence.
1.980 - *
1.981 - * @return The presence's idle time.
1.982 - */
1.983 -time_t purple_presence_get_idle_time(const PurplePresence *presence);
1.984 -
1.985 -/**
1.986 - * Returns the presence's login time.
1.987 - *
1.988 - * @param presence The presence.
1.989 - *
1.990 - * @return The presence's login time.
1.991 - */
1.992 -time_t purple_presence_get_login_time(const PurplePresence *presence);
1.993 -
1.994 -/**
1.995 - * Compares two presences for availability.
1.996 - *
1.997 - * @param presence1 The first presence.
1.998 - * @param presence2 The second presence.
1.999 - *
1.1000 - * @return -1 if @a presence1 is more available than @a presence2.
1.1001 - * 0 if @a presence1 is equal to @a presence2.
1.1002 - * 1 if @a presence1 is less available than @a presence2.
1.1003 - */
1.1004 -gint purple_presence_compare(const PurplePresence *presence1,
1.1005 - const PurplePresence *presence2);
1.1006 -
1.1007 -/*@}*/
1.1008 -
1.1009 -/**************************************************************************/
1.1010 -/** @name Status subsystem */
1.1011 -/**************************************************************************/
1.1012 -/*@{*/
1.1013 -
1.1014 -/**
1.1015 - * Get the handle for the status subsystem.
1.1016 - *
1.1017 - * @return the handle to the status subsystem
1.1018 - */
1.1019 -void *purple_status_get_handle(void);
1.1020 -
1.1021 -/**
1.1022 - * Initializes the status subsystem.
1.1023 - */
1.1024 -void purple_status_init(void);
1.1025 -
1.1026 -/**
1.1027 - * Uninitializes the status subsystem.
1.1028 - */
1.1029 -void purple_status_uninit(void);
1.1030 -
1.1031 -/*@}*/
1.1032 -
1.1033 -#ifdef __cplusplus
1.1034 -}
1.1035 -#endif
1.1036 -
1.1037 -#endif /* _PURPLE_STATUS_H_ */