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: (element-type PurpleAccount) (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: (element-type PurpleAccount) (transfer container): A list of all
 159  *          enabled accounts.
 160  */
 161 GList *purple_accounts_get_all_active(void);
 162
 163 /**
 164  * purple_accounts_find:
 165  * @name:     The account username.
 166  * @protocol: The account protocol ID.
 167  *
 168  * Finds an account with the specified name and protocol id.
 169  *
 170  * Returns: (transfer none): The account, if found, or %NULL otherwise.
 171  */
 172 PurpleAccount *purple_accounts_find(const char *name, const char *protocol);
 173
 174 /**
 175  * purple_accounts_restore_current_statuses:
 176  *
 177  * This is called by the core after all subsystems and what
 178  * not have been initialized.  It sets all enabled accounts
 179  * to their startup status by signing them on, setting them
 180  * away, etc.
 181  *
 182  * You probably shouldn't call this unless you really know
 183  * what you're doing.
 184  */
 185 void purple_accounts_restore_current_statuses(void);
 186
 187
 188 /**************************************************************************/
 189 /* UI Registration Functions                                              */
 190 /**************************************************************************/
 191
 192 /**
 193  * purple_account_ui_ops_get_type:
 194  *
 195  * Returns: The #GType for the #PurpleAccountUiOps boxed structure.
 196  */
 197 GType purple_account_ui_ops_get_type(void);
 198
 199 /**
 200  * purple_accounts_set_ui_ops:
 201  * @ops: The UI operations structure.
 202  *
 203  * Sets the UI operations structure to be used for accounts.
 204  */
 205 void purple_accounts_set_ui_ops(PurpleAccountUiOps *ops);
 206
 207 /**
 208  * purple_accounts_get_ui_ops:
 209  *
 210  * Returns the UI operations structure used for accounts.
 211  *
 212  * Returns: The UI operations structure in use.
 213  */
 214 PurpleAccountUiOps *purple_accounts_get_ui_ops(void);
 215
 216
 217 /**************************************************************************/
 218 /* Accounts Subsystem                                                     */
 219 /**************************************************************************/
 220
 221 /**
 222  * purple_accounts_get_handle:
 223  *
 224  * Returns the accounts subsystem handle.
 225  *
 226  * Returns: The accounts subsystem handle.
 227  */
 228 void *purple_accounts_get_handle(void);
 229
 230 /**
 231  * purple_accounts_init:
 232  *
 233  * Initializes the accounts subsystem.
 234  */
 235 void purple_accounts_init(void);
 236
 237 /**
 238  * purple_accounts_uninit:
 239  *
 240  * Uninitializes the accounts subsystem.
 241  */
 242 void purple_accounts_uninit(void);
 243
 244 /**
 245  * purple_accounts_schedule_save:
 246  *
 247  * Schedules saving of accounts
 248  */
 249 void purple_accounts_schedule_save(void);
 250
 251 G_END_DECLS
 252
 253 #endif /* PURPLE_ACCOUNTS_H */