1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/savedstatuses.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,425 @@
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_ */