libpurple/savedstatuses.h

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