libpurple/accounts.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_ACCOUNTS_H_
  23 #define _PURPLE_ACCOUNTS_H_
  24 /**
  25  * SECTION:accounts
  26  * @section_id: libpurple-accounts
  27  * @short_description: <filename>accounts.h</filename>
  28  * @title: Accounts Subsystem API
  29  * @see_also: <link linkend="chapter-signals-account">Account signals</link>
  30  */
  31
  32 #include "account.h"
  33 #include "status.h"
  34
  35 #define PURPLE_TYPE_ACCOUNT_UI_OPS (purple_account_ui_ops_get_type())
  36
  37 typedef struct _PurpleAccountUiOps  PurpleAccountUiOps;
  38
  39 /**
  40  * PurpleAccountUiOps:
  41  * @notify_added:          A buddy who is already on this account's buddy list
  42  *                         added this account to their buddy list.
  43  * @status_changed:        This account's status changed.
  44  * @request_add:           Someone we don't have on our list added us; prompt
  45  *                         to add them.
  46  * @request_authorize:     Prompt for authorization when someone adds this
  47  *                         account to their buddy list.  To authorize them to
  48  *                         see this account's presence, call
  49  *                         @authorize_cb (@message, @user_data) otherwise call
  50  *                         @deny_cb (@message, @user_data).
  51  *                         <sbr/>Returns: A UI-specific handle, as passed to
  52  *                         @close_account_request.
  53  * @close_account_request: Close a pending request for authorization.
  54  *                         @ui_handle is a handle as returned by
  55  *                         @request_authorize.
  56  *
  57  * Account UI operations, used to notify the user of status changes and when
  58  * buddies add this account to their buddy lists.
  59  */
  60 struct _PurpleAccountUiOps
  61 {
  62         void (*notify_added)(PurpleAccount *account,
  63                              const char *remote_user,
  64                              const char *id,
  65                              const char *alias,
  66                              const char *message);
  67
  68         void (*status_changed)(PurpleAccount *account,
  69                                PurpleStatus *status);
  70
  71         void (*request_add)(PurpleAccount *account,
  72                             const char *remote_user,
  73                             const char *id,
  74                             const char *alias,
  75                             const char *message);
  76
  77         void *(*request_authorize)(PurpleAccount *account,
  78                                    const char *remote_user,
  79                                    const char *id,
  80                                    const char *alias,
  81                                    const char *message,
  82                                    gboolean on_list,
  83                                    PurpleAccountRequestAuthorizationCb authorize_cb,
  84                                    PurpleAccountRequestAuthorizationCb deny_cb,
  85                                    void *user_data);
  86
  87         void (*close_account_request)(void *ui_handle);
  88
  89         void (*permit_added)(PurpleAccount *account, const char *name);
  90         void (*permit_removed)(PurpleAccount *account, const char *name);
  91         void (*deny_added)(PurpleAccount *account, const char *name);
  92         void (*deny_removed)(PurpleAccount *account, const char *name);
  93
  94         /*< private >*/
  95         void (*_purple_reserved1)(void);
  96         void (*_purple_reserved2)(void);
  97         void (*_purple_reserved3)(void);
  98         void (*_purple_reserved4)(void);
  99 };
 100
 101 G_BEGIN_DECLS
 102
 103 /**************************************************************************/
 104 /* Accounts API                                                           */
 105 /**************************************************************************/
 106
 107 /**
 108  * purple_accounts_add:
 109  * @account: The account.
 110  *
 111  * Adds an account to the list of accounts.
 112  */
 113 void purple_accounts_add(PurpleAccount *account);
 114
 115 /**
 116  * purple_accounts_remove:
 117  * @account: The account.
 118  *
 119  * Removes an account from the list of accounts.
 120  */
 121 void purple_accounts_remove(PurpleAccount *account);
 122
 123 /**
 124  * purple_accounts_delete:
 125  * @account: The account.
 126  *
 127  * Deletes an account.
 128  *
 129  * This will remove any buddies from the buddy list that belong to this
 130  * account, buddy pounces that belong to this account, and will also
 131  * destroy @account.
 132  */
 133 void purple_accounts_delete(PurpleAccount *account);
 134
 135 /**
 136  * purple_accounts_reorder:
 137  * @account:   The account to reorder.
 138  * @new_index: The new index for the account.
 139  *
 140  * Reorders an account.
 141  */
 142 void purple_accounts_reorder(PurpleAccount *account, guint new_index);
 143
 144 /**
 145  * purple_accounts_get_all:
 146  *
 147  * Returns a list of all accounts.
 148  *
 149  * Returns: (transfer none): A list of all accounts.
 150  */
 151 GList *purple_accounts_get_all(void);
 152
 153 /**
 154  * purple_accounts_get_all_active:
 155  *
 156  * Returns a list of all enabled accounts
 157  *
 158  * Returns: A list of all enabled accounts. The list is owned
 159  *         by the caller, and must be g_list_free()d to avoid
 160  *         leaking the nodes.
 161  */
 162 GList *purple_accounts_get_all_active(void);
 163
 164 /**
 165  * purple_accounts_find:
 166  * @name:     The account username.
 167  * @protocol: The account protocol ID.
 168  *
 169  * Finds an account with the specified name and protocol id.
 170  *
 171  * Returns: The account, if found, or %FALSE otherwise.
 172  */
 173 PurpleAccount *purple_accounts_find(const char *name, const char *protocol);
 174
 175 /**
 176  * purple_accounts_restore_current_statuses:
 177  *
 178  * This is called by the core after all subsystems and what
 179  * not have been initialized.  It sets all enabled accounts
 180  * to their startup status by signing them on, setting them
 181  * away, etc.
 182  *
 183  * You probably shouldn't call this unless you really know
 184  * what you're doing.
 185  */
 186 void purple_accounts_restore_current_statuses(void);
 187
 188
 189 /**************************************************************************/
 190 /* UI Registration Functions                                              */
 191 /**************************************************************************/
 192
 193 /**
 194  * purple_account_ui_ops_get_type:
 195  *
 196  * Returns: The #GType for the #PurpleAccountUiOps boxed structure.
 197  */
 198 GType purple_account_ui_ops_get_type(void);
 199
 200 /**
 201  * purple_accounts_set_ui_ops:
 202  * @ops: The UI operations structure.
 203  *
 204  * Sets the UI operations structure to be used for accounts.
 205  */
 206 void purple_accounts_set_ui_ops(PurpleAccountUiOps *ops);
 207
 208 /**
 209  * purple_accounts_get_ui_ops:
 210  *
 211  * Returns the UI operations structure used for accounts.
 212  *
 213  * Returns: The UI operations structure in use.
 214  */
 215 PurpleAccountUiOps *purple_accounts_get_ui_ops(void);
 216
 217
 218 /**************************************************************************/
 219 /* Accounts Subsystem                                                     */
 220 /**************************************************************************/
 221
 222 /**
 223  * purple_accounts_get_handle:
 224  *
 225  * Returns the accounts subsystem handle.
 226  *
 227  * Returns: The accounts subsystem handle.
 228  */
 229 void *purple_accounts_get_handle(void);
 230
 231 /**
 232  * purple_accounts_init:
 233  *
 234  * Initializes the accounts subsystem.
 235  */
 236 void purple_accounts_init(void);
 237
 238 /**
 239  * purple_accounts_uninit:
 240  *
 241  * Uninitializes the accounts subsystem.
 242  */
 243 void purple_accounts_uninit(void);
 244
 245 /**
 246  * purple_accounts_schedule_save:
 247  *
 248  * Schedules saving of accounts
 249  */
 250 void purple_accounts_schedule_save(void);
 251
 252 G_END_DECLS
 253
 254 #endif /* _PURPLE_ACCOUNTS_H_ */