Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/savedstatuses.h
branchadium-1.5.11-merge
changeset 6013 f8d0dc659e3f
parent 5941 307f53385811
parent 6012 200a01709ba4
child 6014 fcb71cb71a3d
child 6015 2b01cc935b7c
equal deleted inserted replaced
5941:307f53385811 6013:f8d0dc659e3f
     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_ */