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