1.1 --- a/Frameworks/libpurple.framework/Versions/0.5.6/Headers/savedstatuses.h Sun Jun 21 22:04:11 2009 -0400
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,425 +0,0 @@
1.4 -/**
1.5 - * @file savedstatuses.h Saved Status API
1.6 - * @ingroup core
1.7 - * @see @ref savedstatus-signals
1.8 - */
1.9 -
1.10 -/* purple
1.11 - *
1.12 - * Purple is the legal property of its developers, whose names are too numerous
1.13 - * to list here. Please refer to the COPYRIGHT file distributed with this
1.14 - * source distribution.
1.15 - *
1.16 - * This program is free software; you can redistribute it and/or modify
1.17 - * it under the terms of the GNU General Public License as published by
1.18 - * the Free Software Foundation; either version 2 of the License, or
1.19 - * (at your option) any later version.
1.20 - *
1.21 - * This program is distributed in the hope that it will be useful,
1.22 - * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.23 - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.24 - * GNU General Public License for more details.
1.25 - *
1.26 - * You should have received a copy of the GNU General Public License
1.27 - * along with this program; if not, write to the Free Software
1.28 - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.29 - */
1.30 -#ifndef _PURPLE_SAVEDSTATUSES_H_
1.31 -#define _PURPLE_SAVEDSTATUSES_H_
1.32 -
1.33 -/**
1.34 - * Saved statuses don't really interact much with the rest of Purple. It
1.35 - * could really be a plugin. It's just a list of away states. When
1.36 - * a user chooses one of the saved states, their Purple accounts are set
1.37 - * to the settings of that state.
1.38 - *
1.39 - * In the savedstatus API, there is the concept of a 'transient'
1.40 - * saved status. A transient saved status is one that is not
1.41 - * permanent. Purple will removed it automatically if it isn't
1.42 - * used for a period of time. Transient saved statuses don't
1.43 - * have titles and they don't show up in the list of saved
1.44 - * statuses. In fact, if a saved status does not have a title
1.45 - * then it is transient. If it does have a title, then it is not
1.46 - * transient.
1.47 - *
1.48 - * What good is a transient status, you ask? They can be used to
1.49 - * keep track of the user's 5 most recently used statuses, for
1.50 - * example. Basically if they just set a message on the fly,
1.51 - * we'll cache it for them in case they want to use it again. If
1.52 - * they don't use it again, we'll just delete it.
1.53 - */
1.54 -
1.55 -/*
1.56 - * TODO: Hmm. We should probably just be saving PurplePresences. That's
1.57 - * something we should look into once the status box gets fleshed
1.58 - * out more.
1.59 - */
1.60 -
1.61 -typedef struct _PurpleSavedStatus PurpleSavedStatus;
1.62 -typedef struct _PurpleSavedStatusSub PurpleSavedStatusSub;
1.63 -
1.64 -#include "status.h"
1.65 -
1.66 -#ifdef __cplusplus
1.67 -extern "C" {
1.68 -#endif
1.69 -
1.70 -/**************************************************************************/
1.71 -/** @name Saved status subsystem */
1.72 -/**************************************************************************/
1.73 -/*@{*/
1.74 -
1.75 -/**
1.76 - * Create a new saved status. This will add the saved status to the
1.77 - * list of saved statuses and writes the revised list to status.xml.
1.78 - *
1.79 - * @param title The title of the saved status. This must be
1.80 - * unique. Or, if you want to create a transient
1.81 - * saved status, then pass in NULL.
1.82 - * @param type The type of saved status.
1.83 - *
1.84 - * @return The newly created saved status, or NULL if the title you
1.85 - * used was already taken.
1.86 - */
1.87 -PurpleSavedStatus *purple_savedstatus_new(const char *title,
1.88 - PurpleStatusPrimitive type);
1.89 -
1.90 -/**
1.91 - * Set the title for the given saved status.
1.92 - *
1.93 - * @param status The saved status.
1.94 - * @param title The title of the saved status.
1.95 - */
1.96 -void purple_savedstatus_set_title(PurpleSavedStatus *status,
1.97 - const char *title);
1.98 -
1.99 -/**
1.100 - * Set the type for the given saved status.
1.101 - *
1.102 - * @param status The saved status.
1.103 - * @param type The type of saved status.
1.104 - */
1.105 -void purple_savedstatus_set_type(PurpleSavedStatus *status,
1.106 - PurpleStatusPrimitive type);
1.107 -
1.108 -/**
1.109 - * Set the message for the given saved status.
1.110 - *
1.111 - * @param status The saved status.
1.112 - * @param message The message, or NULL if you want to unset the
1.113 - * message for this status.
1.114 - */
1.115 -void purple_savedstatus_set_message(PurpleSavedStatus *status,
1.116 - const char *message);
1.117 -
1.118 -/**
1.119 - * Set a substatus for an account in a saved status.
1.120 - *
1.121 - * @param status The saved status.
1.122 - * @param account The account.
1.123 - * @param type The status type for the account in the staved
1.124 - * status.
1.125 - * @param message The message for the account in the substatus.
1.126 - */
1.127 -void purple_savedstatus_set_substatus(PurpleSavedStatus *status,
1.128 - const PurpleAccount *account,
1.129 - const PurpleStatusType *type,
1.130 - const char *message);
1.131 -
1.132 -/**
1.133 - * Unset a substatus for an account in a saved status. This clears
1.134 - * the previosly set substatus for the PurpleSavedStatus. If this
1.135 - * saved status is activated then this account will use the default
1.136 - * status type and message.
1.137 - *
1.138 - * @param saved_status The saved status.
1.139 - * @param account The account.
1.140 -*/
1.141 -void purple_savedstatus_unset_substatus(PurpleSavedStatus *saved_status,
1.142 - const PurpleAccount *account);
1.143 -
1.144 -/**
1.145 - * Delete a saved status. This removes the saved status from the list
1.146 - * of saved statuses, and writes the revised list to status.xml.
1.147 - *
1.148 - * @param title The title of the saved status.
1.149 - *
1.150 - * @return TRUE if the status was successfully deleted. FALSE if the
1.151 - * status could not be deleted because no saved status exists
1.152 - * with the given title.
1.153 - */
1.154 -gboolean purple_savedstatus_delete(const char *title);
1.155 -
1.156 -/**
1.157 - * Delete a saved status. This removes the saved status from the list
1.158 - * of saved statuses, and writes the revised list to status.xml.
1.159 - *
1.160 - * @param saved_status the status to delete, the pointer is invalid after
1.161 - * the call
1.162 - *
1.163 - */
1.164 -void purple_savedstatus_delete_by_status(PurpleSavedStatus *saved_status);
1.165 -
1.166 -/**
1.167 - * Returns all saved statuses.
1.168 - *
1.169 - * @constreturn A list of saved statuses.
1.170 - */
1.171 -GList *purple_savedstatuses_get_all(void);
1.172 -
1.173 -/**
1.174 - * Returns the n most popular saved statuses. "Popularity" is
1.175 - * determined by when the last time a saved_status was used and
1.176 - * how many times it has been used. Transient statuses without
1.177 - * messages are not included in the list.
1.178 - *
1.179 - * @param how_many The maximum number of saved statuses
1.180 - * to return, or '0' to get all saved
1.181 - * statuses sorted by popularity.
1.182 - * @return A linked list containing at most how_many
1.183 - * PurpleSavedStatuses. This list should be
1.184 - * g_list_free'd by the caller (but the
1.185 - * PurpleSavedStatuses must not be free'd).
1.186 - */
1.187 -GList *purple_savedstatuses_get_popular(unsigned int how_many);
1.188 -
1.189 -/**
1.190 - * Returns the currently selected saved status. If we are idle
1.191 - * then this returns purple_savedstatus_get_idleaway(). Otherwise
1.192 - * it returns purple_savedstatus_get_default().
1.193 - *
1.194 - * @return A pointer to the in-use PurpleSavedStatus.
1.195 - * This function never returns NULL.
1.196 - */
1.197 -PurpleSavedStatus *purple_savedstatus_get_current(void);
1.198 -
1.199 -/**
1.200 - * Returns the default saved status that is used when our
1.201 - * accounts are not idle-away.
1.202 - *
1.203 - * @return A pointer to the in-use PurpleSavedStatus.
1.204 - * This function never returns NULL.
1.205 - */
1.206 -PurpleSavedStatus *purple_savedstatus_get_default(void);
1.207 -
1.208 -/**
1.209 - * Returns the saved status that is used when your
1.210 - * accounts become idle-away.
1.211 - *
1.212 - * @return A pointer to the idle-away PurpleSavedStatus.
1.213 - * This function never returns NULL.
1.214 - */
1.215 -PurpleSavedStatus *purple_savedstatus_get_idleaway(void);
1.216 -
1.217 -/**
1.218 - * Return TRUE if we are currently idle-away. Otherwise
1.219 - * returns FALSE.
1.220 - *
1.221 - * @return TRUE if our accounts have been set to idle-away.
1.222 - */
1.223 -gboolean purple_savedstatus_is_idleaway(void);
1.224 -
1.225 -/**
1.226 - * Set whether accounts in Purple are idle-away or not.
1.227 - *
1.228 - * @param idleaway TRUE if accounts should be switched to use the
1.229 - * idle-away saved status. FALSE if they should
1.230 - * be switched to use the default status.
1.231 - */
1.232 -void purple_savedstatus_set_idleaway(gboolean idleaway);
1.233 -
1.234 -/**
1.235 - * Returns the status to be used when purple is starting up
1.236 - *
1.237 - * @return A pointer to the startup PurpleSavedStatus.
1.238 - * This function never returns NULL.
1.239 - */
1.240 -PurpleSavedStatus *purple_savedstatus_get_startup(void);
1.241 -
1.242 -/**
1.243 - * Finds a saved status with the specified title.
1.244 - *
1.245 - * @param title The name of the saved status.
1.246 - *
1.247 - * @return The saved status if found, or NULL.
1.248 - */
1.249 -PurpleSavedStatus *purple_savedstatus_find(const char *title);
1.250 -
1.251 -/**
1.252 - * Finds a saved status with the specified creation time.
1.253 - *
1.254 - * @param creation_time The timestamp when the saved
1.255 - * status was created.
1.256 - *
1.257 - * @return The saved status if found, or NULL.
1.258 - */
1.259 -PurpleSavedStatus *purple_savedstatus_find_by_creation_time(time_t creation_time);
1.260 -
1.261 -/**
1.262 - * Finds a saved status with the specified primitive and message.
1.263 - *
1.264 - * @param type The PurpleStatusPrimitive for the status you're trying
1.265 - * to find.
1.266 - * @param message The message for the status you're trying
1.267 - * to find.
1.268 - *
1.269 - * @return The saved status if found, or NULL.
1.270 - */
1.271 -PurpleSavedStatus *purple_savedstatus_find_transient_by_type_and_message(PurpleStatusPrimitive type, const char *message);
1.272 -
1.273 -/**
1.274 - * Determines if a given saved status is "transient."
1.275 - * A transient saved status is one that was not
1.276 - * explicitly added by the user. Transient statuses
1.277 - * are automatically removed if they are not used
1.278 - * for a period of time.
1.279 - *
1.280 - * A transient saved statuses is automatically
1.281 - * created by the status box when the user sets himself
1.282 - * to one of the generic primitive statuses. The reason
1.283 - * we need to save this status information is so we can
1.284 - * restore it when Purple restarts.
1.285 - *
1.286 - * @param saved_status The saved status.
1.287 - *
1.288 - * @return TRUE if the saved status is transient.
1.289 - */
1.290 -gboolean purple_savedstatus_is_transient(const PurpleSavedStatus *saved_status);
1.291 -
1.292 -/**
1.293 - * Return the name of a given saved status.
1.294 - *
1.295 - * @param saved_status The saved status.
1.296 - *
1.297 - * @return The title. This value may be a static buffer which may
1.298 - * be overwritten on subsequent calls to this function. If
1.299 - * you need a reference to the title for prolonged use then
1.300 - * you should make a copy of it.
1.301 - */
1.302 -const char *purple_savedstatus_get_title(const PurpleSavedStatus *saved_status);
1.303 -
1.304 -/**
1.305 - * Return the type of a given saved status.
1.306 - *
1.307 - * @param saved_status The saved status.
1.308 - *
1.309 - * @return The name.
1.310 - */
1.311 -PurpleStatusPrimitive purple_savedstatus_get_type(const PurpleSavedStatus *saved_status);
1.312 -
1.313 -/**
1.314 - * Return the default message of a given saved status.
1.315 - *
1.316 - * @param saved_status The saved status.
1.317 - *
1.318 - * @return The message. This will return NULL if the saved
1.319 - * status does not have a message. This will
1.320 - * contain the normal markup that is created by
1.321 - * Purple's IMHTML (basically HTML markup).
1.322 - */
1.323 -const char *purple_savedstatus_get_message(const PurpleSavedStatus *saved_status);
1.324 -
1.325 -/**
1.326 - * Return the time in seconds-since-the-epoch when this
1.327 - * saved status was created. Note: For any status created
1.328 - * by Purple 1.5.0 or older this value will be invalid and
1.329 - * very small (close to 0). This is because Purple 1.5.0
1.330 - * and older did not record the timestamp when the status
1.331 - * was created.
1.332 - *
1.333 - * However, this value is guaranteed to be a unique
1.334 - * identifier for the given saved status.
1.335 - *
1.336 - * @param saved_status The saved status.
1.337 - *
1.338 - * @return The timestamp when this saved status was created.
1.339 - */
1.340 -time_t purple_savedstatus_get_creation_time(const PurpleSavedStatus *saved_status);
1.341 -
1.342 -/**
1.343 - * Determine if a given saved status has "substatuses,"
1.344 - * or if it is a simple status (the same for all
1.345 - * accounts).
1.346 - *
1.347 - * @param saved_status The saved status.
1.348 - *
1.349 - * @return TRUE if the saved_status has substatuses.
1.350 - * FALSE otherwise.
1.351 - */
1.352 -gboolean purple_savedstatus_has_substatuses(const PurpleSavedStatus *saved_status);
1.353 -
1.354 -/**
1.355 - * Get the substatus for an account in a saved status.
1.356 - *
1.357 - * @param saved_status The saved status.
1.358 - * @param account The account.
1.359 - *
1.360 - * @return The PurpleSavedStatusSub for the account, or NULL if
1.361 - * the given account does not have a substatus that
1.362 - * differs from the default status of this PurpleSavedStatus.
1.363 - */
1.364 -PurpleSavedStatusSub *purple_savedstatus_get_substatus(
1.365 - const PurpleSavedStatus *saved_status,
1.366 - const PurpleAccount *account);
1.367 -
1.368 -/**
1.369 - * Get the status type of a given substatus.
1.370 - *
1.371 - * @param substatus The substatus.
1.372 - *
1.373 - * @return The status type.
1.374 - */
1.375 -const PurpleStatusType *purple_savedstatus_substatus_get_type(const PurpleSavedStatusSub *substatus);
1.376 -
1.377 -/**
1.378 - * Get the message of a given substatus.
1.379 - *
1.380 - * @param substatus The substatus.
1.381 - *
1.382 - * @return The message of the substatus, or NULL if this substatus does
1.383 - * not have a message.
1.384 - */
1.385 -const char *purple_savedstatus_substatus_get_message(const PurpleSavedStatusSub *substatus);
1.386 -
1.387 -/**
1.388 - * Sets the statuses for all your accounts to those specified
1.389 - * by the given saved_status. This function calls
1.390 - * purple_savedstatus_activate_for_account() for all your accounts.
1.391 - *
1.392 - * @param saved_status The status you want to set your accounts to.
1.393 - */
1.394 -void purple_savedstatus_activate(PurpleSavedStatus *saved_status);
1.395 -
1.396 -/**
1.397 - * Sets the statuses for a given account to those specified
1.398 - * by the given saved_status.
1.399 - *
1.400 - * @param saved_status The status you want to set your accounts to.
1.401 - * @param account The account whose statuses you want to change.
1.402 - */
1.403 -void purple_savedstatus_activate_for_account(const PurpleSavedStatus *saved_status, PurpleAccount *account);
1.404 -
1.405 -/**
1.406 - * Get the handle for the status subsystem.
1.407 - *
1.408 - * @return the handle to the status subsystem
1.409 - */
1.410 -void *purple_savedstatuses_get_handle(void);
1.411 -
1.412 -/**
1.413 - * Initializes the status subsystem.
1.414 - */
1.415 -void purple_savedstatuses_init(void);
1.416 -
1.417 -/**
1.418 - * Uninitializes the status subsystem.
1.419 - */
1.420 -void purple_savedstatuses_uninit(void);
1.421 -
1.422 -/*@}*/
1.423 -
1.424 -#ifdef __cplusplus
1.425 -}
1.426 -#endif
1.427 -
1.428 -#endif /* _PURPLE_SAVEDSTATUSES_H_ */