libpurple/savedstatuses.h

   1 /**
   2  * @file savedstatuses.h Saved Status API
   3  * @ingroup core
   4  * @see @ref savedstatus-signals
   5  */
   6
   7 /* purple
   8  *
   9  * Purple is the legal property of its developers, whose names are too numerous
  10  * to list here.  Please refer to the COPYRIGHT file distributed with this
  11  * source distribution.
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with this program; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  26  */
  27 #ifndef _PURPLE_SAVEDSTATUSES_H_
  28 #define _PURPLE_SAVEDSTATUSES_H_
  29
  30 /**
  31  * Saved statuses don't really interact much with the rest of Purple.  It
  32  * could really be a plugin.  It's just a list of away states.  When
  33  * a user chooses one of the saved states, their Purple accounts are set
  34  * to the settings of that state.
  35  *
  36  * In the savedstatus API, there is the concept of a 'transient'
  37  * saved status.  A transient saved status is one that is not
  38  * permanent.  Purple will removed it automatically if it isn't
  39  * used for a period of time.  Transient saved statuses don't
  40  * have titles and they don't show up in the list of saved
  41  * statuses.  In fact, if a saved status does not have a title
  42  * then it is transient.  If it does have a title, then it is not
  43  * transient.
  44  *
  45  * What good is a transient status, you ask?  They can be used to
  46  * keep track of the user's 5 most recently used statuses, for
  47  * example.  Basically if they just set a message on the fly,
  48  * we'll cache it for them in case they want to use it again.  If
  49  * they don't use it again, we'll just delete it.
  50  */
  51
  52 /*
  53  * TODO: Hmm.  We should probably just be saving PurplePresences.  That's
  54  *       something we should look into once the status box gets fleshed
  55  *       out more.
  56  */
  57
  58 typedef struct _PurpleSavedStatus     PurpleSavedStatus;
  59 typedef struct _PurpleSavedStatusSub  PurpleSavedStatusSub;
  60
  61 #include "status.h"
  62
  63 #ifdef __cplusplus
  64 extern "C" {
  65 #endif
  66
  67 /**************************************************************************/
  68 /** @name Saved status subsystem                                          */
  69 /**************************************************************************/
  70 /*@{*/
  71
  72 /**
  73  * Create a new saved status.  This will add the saved status to the
  74  * list of saved statuses and writes the revised list to status.xml.
  75  *
  76  * @param title     The title of the saved status.  This must be
  77  *                  unique.  Or, if you want to create a transient
  78  *                  saved status, then pass in NULL.
  79  * @param type      The type of saved status.
  80  *
  81  * @return The newly created saved status, or NULL if the title you
  82  *         used was already taken.
  83  */
  84 PurpleSavedStatus *purple_savedstatus_new(const char *title,
  85                                                                           PurpleStatusPrimitive type);
  86
  87 /**
  88  * Set the title for the given saved status.
  89  *
  90  * @param status  The saved status.
  91  * @param title   The title of the saved status.
  92  */
  93 void purple_savedstatus_set_title(PurpleSavedStatus *status,
  94                                                                 const char *title);
  95
  96 /**
  97  * Set the type for the given saved status.
  98  *
  99  * @param status  The saved status.
 100  * @param type    The type of saved status.
 101  */
 102 void purple_savedstatus_set_type(PurpleSavedStatus *status,
 103                                                            PurpleStatusPrimitive type);
 104
 105 /**
 106  * Set the message for the given saved status.
 107  *
 108  * @param status  The saved status.
 109  * @param message The message, or NULL if you want to unset the
 110  *                message for this status.
 111  */
 112 void purple_savedstatus_set_message(PurpleSavedStatus *status,
 113                                                                   const char *message);
 114
 115 /**
 116  * Set a substatus for an account in a saved status.
 117  *
 118  * @param status        The saved status.
 119  * @param account       The account.
 120  * @param type          The status type for the account in the staved
 121  *                  status.
 122  * @param message       The message for the account in the substatus.
 123  */
 124 void purple_savedstatus_set_substatus(PurpleSavedStatus *status,
 125                                                                         const PurpleAccount *account,
 126                                                                         const PurpleStatusType *type,
 127                                                                         const char *message);
 128
 129 /**
 130  * Unset a substatus for an account in a saved status.  This clears
 131  * the previosly set substatus for the PurpleSavedStatus.  If this
 132  * saved status is activated then this account will use the default
 133  * status type and message.
 134  *
 135  * @param saved_status The saved status.
 136  * @param account      The account.
 137 */
 138 void purple_savedstatus_unset_substatus(PurpleSavedStatus *saved_status,
 139                                                                                                   const PurpleAccount *account);
 140
 141 /**
 142  * Delete a saved status.  This removes the saved status from the list
 143  * of saved statuses, and writes the revised list to status.xml.
 144  *
 145  * @param title The title of the saved status.
 146  *
 147  * @return TRUE if the status was successfully deleted.  FALSE if the
 148  *         status could not be deleted because no saved status exists
 149  *         with the given title.
 150  */
 151 gboolean purple_savedstatus_delete(const char *title);
 152
 153 /**
 154  * Delete a saved status.  This removes the saved status from the list
 155  * of saved statuses, and writes the revised list to status.xml.
 156  *
 157  * @param saved_status the status to delete, the pointer is invalid after
 158  *        the call
 159  *
 160  */
 161 void purple_savedstatus_delete_by_status(PurpleSavedStatus *saved_status);
 162
 163 /**
 164  * Returns all saved statuses.
 165  *
 166  * @constreturn A list of saved statuses.
 167  */
 168 GList *purple_savedstatuses_get_all(void);
 169
 170 /**
 171  * Returns the n most popular saved statuses.  "Popularity" is
 172  * determined by when the last time a saved_status was used and
 173  * how many times it has been used. Transient statuses without
 174  * messages are not included in the list.
 175  *
 176  * @param how_many The maximum number of saved statuses
 177  *                 to return, or '0' to get all saved
 178  *                 statuses sorted by popularity.
 179  * @return A linked list containing at most how_many
 180  *         PurpleSavedStatuses.  This list should be
 181  *         g_list_free'd by the caller (but the
 182  *         PurpleSavedStatuses must not be free'd).
 183  */
 184 GList *purple_savedstatuses_get_popular(unsigned int how_many);
 185
 186 /**
 187  * Returns the currently selected saved status.  If we are idle
 188  * then this returns purple_savedstatus_get_idleaway().  Otherwise
 189  * it returns purple_savedstatus_get_default().
 190  *
 191  * @return A pointer to the in-use PurpleSavedStatus.
 192  *         This function never returns NULL.
 193  */
 194 PurpleSavedStatus *purple_savedstatus_get_current(void);
 195
 196 /**
 197  * Returns the default saved status that is used when our
 198  * accounts are not idle-away.
 199  *
 200  * @return A pointer to the in-use PurpleSavedStatus.
 201  *         This function never returns NULL.
 202  */
 203 PurpleSavedStatus *purple_savedstatus_get_default(void);
 204
 205 /**
 206  * Returns the saved status that is used when your
 207  * accounts become idle-away.
 208  *
 209  * @return A pointer to the idle-away PurpleSavedStatus.
 210  *         This function never returns NULL.
 211  */
 212 PurpleSavedStatus *purple_savedstatus_get_idleaway(void);
 213
 214 /**
 215  * Return TRUE if we are currently idle-away.  Otherwise
 216  * returns FALSE.
 217  *
 218  * @return TRUE if our accounts have been set to idle-away.
 219  */
 220 gboolean purple_savedstatus_is_idleaway(void);
 221
 222 /**
 223  * Set whether accounts in Purple are idle-away or not.
 224  *
 225  * @param idleaway TRUE if accounts should be switched to use the
 226  *                 idle-away saved status.  FALSE if they should
 227  *                 be switched to use the default status.
 228  */
 229 void purple_savedstatus_set_idleaway(gboolean idleaway);
 230
 231 /**
 232  * Returns the status to be used when purple is starting up
 233  *
 234  * @return A pointer to the startup PurpleSavedStatus.
 235  *         This function never returns NULL.
 236  */
 237 PurpleSavedStatus *purple_savedstatus_get_startup(void);
 238
 239 /**
 240  * Finds a saved status with the specified title.
 241  *
 242  * @param title The name of the saved status.
 243  *
 244  * @return The saved status if found, or NULL.
 245  */
 246 PurpleSavedStatus *purple_savedstatus_find(const char *title);
 247
 248 /**
 249  * Finds a saved status with the specified creation time.
 250  *
 251  * @param creation_time The timestamp when the saved
 252  *        status was created.
 253  *
 254  * @return The saved status if found, or NULL.
 255  */
 256 PurpleSavedStatus *purple_savedstatus_find_by_creation_time(time_t creation_time);
 257
 258 /**
 259  * Finds a saved status with the specified primitive and message.
 260  *
 261  * @param type The PurpleStatusPrimitive for the status you're trying
 262  *        to find.
 263  * @param message The message for the status you're trying
 264  *        to find.
 265  *
 266  * @return The saved status if found, or NULL.
 267  */
 268 PurpleSavedStatus *purple_savedstatus_find_transient_by_type_and_message(PurpleStatusPrimitive type, const char *message);
 269
 270 /**
 271  * Determines if a given saved status is "transient."
 272  * A transient saved status is one that was not
 273  * explicitly added by the user.  Transient statuses
 274  * are automatically removed if they are not used
 275  * for a period of time.
 276  *
 277  * A transient saved statuses is automatically
 278  * created by the status box when the user sets himself
 279  * to one of the generic primitive statuses.  The reason
 280  * we need to save this status information is so we can
 281  * restore it when Purple restarts.
 282  *
 283  * @param saved_status The saved status.
 284  *
 285  * @return TRUE if the saved status is transient.
 286  */
 287 gboolean purple_savedstatus_is_transient(const PurpleSavedStatus *saved_status);
 288
 289 /**
 290  * Return the name of a given saved status.
 291  *
 292  * @param saved_status The saved status.
 293  *
 294  * @return The title.  This value may be a static buffer which may
 295  *         be overwritten on subsequent calls to this function.  If
 296  *         you need a reference to the title for prolonged use then
 297  *         you should make a copy of it.
 298  */
 299 const char *purple_savedstatus_get_title(const PurpleSavedStatus *saved_status);
 300
 301 /**
 302  * Return the type of a given saved status.
 303  *
 304  * @param saved_status The saved status.
 305  *
 306  * @return The name.
 307  */
 308 PurpleStatusPrimitive purple_savedstatus_get_type(const PurpleSavedStatus *saved_status);
 309
 310 /**
 311  * Return the default message of a given saved status.
 312  *
 313  * @param saved_status The saved status.
 314  *
 315  * @return The message.  This will return NULL if the saved
 316  *         status does not have a message.  This will
 317  *         contain the normal markup that is created by
 318  *         Purple's IMHTML (basically HTML markup).
 319  */
 320 const char *purple_savedstatus_get_message(const PurpleSavedStatus *saved_status);
 321
 322 /**
 323  * Return the time in seconds-since-the-epoch when this
 324  * saved status was created.  Note: For any status created
 325  * by Purple 1.5.0 or older this value will be invalid and
 326  * very small (close to 0).  This is because Purple 1.5.0
 327  * and older did not record the timestamp when the status
 328  * was created.
 329  *
 330  * However, this value is guaranteed to be a unique
 331  * identifier for the given saved status.
 332  *
 333  * @param saved_status The saved status.
 334  *
 335  * @return The timestamp when this saved status was created.
 336  */
 337 time_t purple_savedstatus_get_creation_time(const PurpleSavedStatus *saved_status);
 338
 339 /**
 340  * Determine if a given saved status has "substatuses,"
 341  * or if it is a simple status (the same for all
 342  * accounts).
 343  *
 344  * @param saved_status The saved status.
 345  *
 346  * @return TRUE if the saved_status has substatuses.
 347  *         FALSE otherwise.
 348  */
 349 gboolean purple_savedstatus_has_substatuses(const PurpleSavedStatus *saved_status);
 350
 351 /**
 352  * Get the substatus for an account in a saved status.
 353  *
 354  * @param saved_status The saved status.
 355  * @param account      The account.
 356  *
 357  * @return The PurpleSavedStatusSub for the account, or NULL if
 358  *         the given account does not have a substatus that
 359  *         differs from the default status of this PurpleSavedStatus.
 360  */
 361 PurpleSavedStatusSub *purple_savedstatus_get_substatus(
 362                                                                         const PurpleSavedStatus *saved_status,
 363                                                                         const PurpleAccount *account);
 364
 365 /**
 366  * Get the status type of a given substatus.
 367  *
 368  * @param substatus The substatus.
 369  *
 370  * @return The status type.
 371  */
 372 const PurpleStatusType *purple_savedstatus_substatus_get_type(const PurpleSavedStatusSub *substatus);
 373
 374 /**
 375  * Get the message of a given substatus.
 376  *
 377  * @param substatus The substatus.
 378  *
 379  * @return The message of the substatus, or NULL if this substatus does
 380  *         not have a message.
 381  */
 382 const char *purple_savedstatus_substatus_get_message(const PurpleSavedStatusSub *substatus);
 383
 384 /**
 385  * Sets the statuses for all your accounts to those specified
 386  * by the given saved_status.  This function calls
 387  * purple_savedstatus_activate_for_account() for all your accounts.
 388  *
 389  * @param saved_status The status you want to set your accounts to.
 390  */
 391 void purple_savedstatus_activate(PurpleSavedStatus *saved_status);
 392
 393 /**
 394  * Sets the statuses for a given account to those specified
 395  * by the given saved_status.
 396  *
 397  * @param saved_status The status you want to set your accounts to.
 398  * @param account      The account whose statuses you want to change.
 399  */
 400 void purple_savedstatus_activate_for_account(const PurpleSavedStatus *saved_status, PurpleAccount *account);
 401
 402 /**
 403  * Get the handle for the status subsystem.
 404  *
 405  * @return the handle to the status subsystem
 406  */
 407 void *purple_savedstatuses_get_handle(void);
 408
 409 /**
 410  * Initializes the status subsystem.
 411  */
 412 void purple_savedstatuses_init(void);
 413
 414 /**
 415  * Uninitializes the status subsystem.
 416  */
 417 void purple_savedstatuses_uninit(void);
 418
 419 /*@}*/
 420
 421 #ifdef __cplusplus
 422 }
 423 #endif
 424
 425 #endif /* _PURPLE_SAVEDSTATUSES_H_ */