1.1 --- a/Frameworks/libpurple.framework/Versions/0.6.0/Headers/status.h Fri Aug 21 13:24:36 2009 -0700
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,1084 +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 -#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_ */