libpurple/protocols.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_PROTOCOLS_H_
  23 #define _PURPLE_PROTOCOLS_H_
  24 /**
  25  * SECTION:protocols
  26  * @section_id: libpurple-protocols
  27  * @short_description: <filename>protocols.h</filename>
  28  * @title: Protocols Subsystem API
  29  * @see_also: <link linkend="chapter-signals-protocol">Protocol signals</link>
  30  */
  31
  32 #define PURPLE_PROTOCOLS_DOMAIN  (g_quark_from_static_string("protocols"))
  33
  34 #define PURPLE_TYPE_PROTOCOL_ACTION  (purple_protocol_action_get_type())
  35
  36 typedef struct _PurpleProtocolAction PurpleProtocolAction;
  37 typedef void (*PurpleProtocolActionCallback)(PurpleProtocolAction *action);
  38
  39 /**************************************************************************/
  40 /* Basic Protocol Information                                             */
  41 /**************************************************************************/
  42
  43 typedef struct _PurpleProtocolChatEntry PurpleProtocolChatEntry;
  44
  45 /**
  46  * PurpleProtocolOptions:
  47  * @OPT_PROTO_UNIQUE_CHATNAME: User names are unique to a chat and are not
  48  *           shared between rooms.<sbr/>
  49  *           XMPP lets you choose what name you want in chats, so it shouldn't
  50  *           be pulling the aliases from the buddy list for the chat list; it
  51  *           gets annoying.
  52  * @OPT_PROTO_CHAT_TOPIC: Chat rooms have topics.<sbr/>
  53  *           IRC and XMPP support this.
  54  * @OPT_PROTO_NO_PASSWORD: Don't require passwords for sign-in.<sbr/>
  55  *           Zephyr doesn't require passwords, so there's no need for a
  56  *           password prompt.
  57  * @OPT_PROTO_MAIL_CHECK: Notify on new mail.<sbr/>
  58  *           MSN and Yahoo notify you when you have new mail.
  59  * @OPT_PROTO_PASSWORD_OPTIONAL: Allow passwords to be optional.<sbr/>
  60  *           Passwords in IRC are optional, and are needed for certain
  61  *           functionality.
  62  * @OPT_PROTO_USE_POINTSIZE: Allows font size to be specified in sane point
  63  *           size.<sbr/>
  64  *           Probably just XMPP and Y!M
  65  * @OPT_PROTO_REGISTER_NOSCREENNAME: Set the Register button active even when
  66  *           the username has not been specified.<sbr/>
  67  *           Gadu-Gadu doesn't need a username to register new account (because
  68  *           usernames are assigned by the server).
  69  * @OPT_PROTO_SLASH_COMMANDS_NATIVE: Indicates that slash commands are native
  70  *           to this protocol.<sbr/>
  71  *           Used as a hint that unknown commands should not be sent as
  72  *           messages.
  73  * @OPT_PROTO_INVITE_MESSAGE: Indicates that this protocol supports sending a
  74  *           user-supplied message along with an invitation.
  75  * @OPT_PROTO_AUTHORIZATION_GRANTED_MESSAGE: Indicates that this protocol
  76  *           supports sending a user-supplied message along with an
  77  *           authorization acceptance.
  78  * @OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE: Indicates that this protocol
  79  *           supports sending a user-supplied message along with an
  80  *           authorization denial.
  81  *
  82  * Protocol options
  83  *
  84  * These should all be stuff that some protocols can do and others can't.
  85  */
  86 typedef enum  /*< flags >*/
  87 {
  88         OPT_PROTO_UNIQUE_CHATNAME               = 0x00000004,
  89         OPT_PROTO_CHAT_TOPIC                    = 0x00000008,
  90         OPT_PROTO_NO_PASSWORD                   = 0x00000010,
  91         OPT_PROTO_MAIL_CHECK                    = 0x00000020,
  92         OPT_PROTO_PASSWORD_OPTIONAL             = 0x00000080,
  93         OPT_PROTO_USE_POINTSIZE                 = 0x00000100,
  94         OPT_PROTO_REGISTER_NOSCREENNAME         = 0x00000200,
  95         OPT_PROTO_SLASH_COMMANDS_NATIVE         = 0x00000400,
  96         OPT_PROTO_INVITE_MESSAGE                = 0x00000800,
  97         OPT_PROTO_AUTHORIZATION_GRANTED_MESSAGE = 0x00001000,
  98         OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE  = 0x00002000
  99
 100 } PurpleProtocolOptions;
 101
 102 #include "media.h"
 103 #include "protocol.h"
 104 #include "status.h"
 105
 106 #define PURPLE_TYPE_PROTOCOL_CHAT_ENTRY  (purple_protocol_chat_entry_get_type())
 107
 108 /**
 109  * PurpleProtocolChatEntry:
 110  * @label:      User-friendly name of the entry
 111  * @identifier: Used by the protocol to identify the option
 112  * @required:   True if it's required
 113  * @is_int:     True if the entry expects an integer
 114  * @min:        Minimum value in case of integer
 115  * @max:        Maximum value in case of integer
 116  * @secret:     True if the entry is secret (password)
 117  *
 118  * Represents an entry containing information that must be supplied by the
 119  * user when joining a chat.
 120  */
 121 struct _PurpleProtocolChatEntry {
 122         const char *label;
 123         const char *identifier;
 124         gboolean required;
 125         gboolean is_int;
 126         int min;
 127         int max;
 128         gboolean secret;
 129 };
 130
 131 /**
 132  * PurpleProtocolAction:
 133  *
 134  * Represents an action that the protocol can perform. This shows up in the
 135  * Accounts menu, under a submenu with the name of the account.
 136  */
 137 struct _PurpleProtocolAction {
 138         char *label;
 139         PurpleProtocolActionCallback callback;
 140         PurpleConnection *connection;
 141         gpointer user_data;
 142 };
 143
 144 G_BEGIN_DECLS
 145
 146 /**************************************************************************/
 147 /* Attention Type API                                                     */
 148 /**************************************************************************/
 149
 150 /**************************************************************************/
 151 /* Protocol Action API                                                    */
 152 /**************************************************************************/
 153
 154 /**
 155  * purple_protocol_action_get_type:
 156  *
 157  * Returns: The #GType for the #PurpleProtocolAction boxed structure.
 158  */
 159 GType purple_protocol_action_get_type(void);
 160
 161 /**
 162  * purple_protocol_action_new:
 163  * @label:    The description of the action to show to the user.
 164  * @callback: (scope call): The callback to call when the user selects this
 165  *            action.
 166  *
 167  * Allocates and returns a new PurpleProtocolAction. Use this to add actions in
 168  * a list in the get_actions function of the protocol.
 169  */
 170 PurpleProtocolAction *purple_protocol_action_new(const char* label,
 171                 PurpleProtocolActionCallback callback);
 172
 173 /**
 174  * purple_protocol_action_free:
 175  * @action: The PurpleProtocolAction to free.
 176  *
 177  * Frees a PurpleProtocolAction
 178  */
 179 void purple_protocol_action_free(PurpleProtocolAction *action);
 180
 181 /**************************************************************************/
 182 /* Protocol Chat Entry API                                                */
 183 /**************************************************************************/
 184
 185 /**
 186  * purple_protocol_chat_entry_get_type:
 187  *
 188  * Returns: The #GType for the #PurpleProtocolChatEntry boxed structure.
 189  */
 190 GType purple_protocol_chat_entry_get_type(void);
 191
 192 /**************************************************************************/
 193 /* Protocol API                                                           */
 194 /**************************************************************************/
 195
 196 /**
 197  * purple_protocol_got_account_idle:
 198  * @account:   The account.
 199  * @idle:      The user's idle state.
 200  * @idle_time: The user's idle time.
 201  *
 202  * Notifies Purple that our account's idle state and time have changed.
 203  *
 204  * This is meant to be called from protocols.
 205  */
 206 void purple_protocol_got_account_idle(PurpleAccount *account, gboolean idle,
 207                                       time_t idle_time);
 208
 209 /**
 210  * purple_protocol_got_account_login_time:
 211  * @account:    The account the user is on.
 212  * @login_time: The user's log-in time.
 213  *
 214  * Notifies Purple of our account's log-in time.
 215  *
 216  * This is meant to be called from protocols.
 217  */
 218 void purple_protocol_got_account_login_time(PurpleAccount *account,
 219                                             time_t login_time);
 220
 221 /**
 222  * purple_protocol_got_account_status:
 223  * @account:   The account the user is on.
 224  * @status_id: The status ID.
 225  * @...:       A NULL-terminated list of attribute IDs and values,
 226  *             beginning with the value for <literal>attr_id</literal>.
 227  *
 228  * Notifies Purple that our account's status has changed.
 229  *
 230  * This is meant to be called from protocols.
 231  */
 232 void purple_protocol_got_account_status(PurpleAccount *account,
 233                                         const char *status_id, ...)
 234                                         G_GNUC_NULL_TERMINATED;
 235
 236 /**
 237  * purple_protocol_got_account_actions:
 238  * @account:   The account.
 239  *
 240  * Notifies Purple that our account's actions have changed. This is only
 241  * called after the initial connection. Emits the account-actions-changed
 242  * signal.
 243  *
 244  * This is meant to be called from protocols.
 245  *
 246  * See <link linkend="accounts-account-actions-changed"><literal>"account-actions-changed"</literal></link>
 247  */
 248 void purple_protocol_got_account_actions(PurpleAccount *account);
 249
 250 /**
 251  * purple_protocol_got_user_idle:
 252  * @account:   The account the user is on.
 253  * @name:      The name of the buddy.
 254  * @idle:      The user's idle state.
 255  * @idle_time: The user's idle time.  This is the time at
 256  *                  which the user became idle, in seconds since
 257  *                  the epoch.  If the protocol does not know this value
 258  *                  then it should pass 0.
 259  *
 260  * Notifies Purple that a buddy's idle state and time have changed.
 261  *
 262  * This is meant to be called from protocols.
 263  */
 264 void purple_protocol_got_user_idle(PurpleAccount *account, const char *name,
 265                                    gboolean idle, time_t idle_time);
 266
 267 /**
 268  * purple_protocol_got_user_login_time:
 269  * @account:    The account the user is on.
 270  * @name:       The name of the buddy.
 271  * @login_time: The user's log-in time.
 272  *
 273  * Notifies Purple of a buddy's log-in time.
 274  *
 275  * This is meant to be called from protocols.
 276  */
 277 void purple_protocol_got_user_login_time(PurpleAccount *account,
 278                                          const char *name, time_t login_time);
 279
 280 /**
 281  * purple_protocol_got_user_status:
 282  * @account:   The account the user is on.
 283  * @name:      The name of the buddy.
 284  * @status_id: The status ID.
 285  * @...:       A NULL-terminated list of attribute IDs and values,
 286  *             beginning with the value for <literal>attr_id</literal>.
 287  *
 288  * Notifies Purple that a buddy's status has been activated.
 289  *
 290  * This is meant to be called from protocols.
 291  */
 292 void purple_protocol_got_user_status(PurpleAccount *account, const char *name,
 293                                      const char *status_id, ...)
 294                                      G_GNUC_NULL_TERMINATED;
 295
 296 /**
 297  * purple_protocol_got_user_status_deactive:
 298  * @account:   The account the user is on.
 299  * @name:      The name of the buddy.
 300  * @status_id: The status ID.
 301  *
 302  * Notifies libpurple that a buddy's status has been deactivated
 303  *
 304  * This is meant to be called from protocols.
 305  */
 306 void purple_protocol_got_user_status_deactive(PurpleAccount *account,
 307                                               const char *name,
 308                                               const char *status_id);
 309
 310 /**
 311  * purple_protocol_change_account_status:
 312  * @account:    The account the user is on.
 313  * @old_status: The previous status.
 314  * @new_status: The status that was activated, or deactivated
 315  *                   (in the case of independent statuses).
 316  *
 317  * Informs the server that our account's status changed.
 318  */
 319 void purple_protocol_change_account_status(PurpleAccount *account,
 320                                            PurpleStatus *old_status,
 321                                            PurpleStatus *new_status);
 322
 323 /**
 324  * purple_protocol_get_statuses:
 325  * @account: The account the user is on.
 326  * @presence: The presence for which we're going to get statuses
 327  *
 328  * Retrieves the list of stock status types from a protocol.
 329  *
 330  * Returns: (transfer full) (element-type PurpleStatus): List of statuses
 331  */
 332 GList *purple_protocol_get_statuses(PurpleAccount *account,
 333                                     PurplePresence *presence);
 334
 335 /**
 336  * purple_protocol_send_attention:
 337  * @gc: The connection to send the message on.
 338  * @who: Whose attention to request.
 339  * @type_code: An index into the protocol's attention_types list determining the type
 340  *        of the attention request command to send. 0 if protocol only defines one
 341  *        (for example, Yahoo and MSN), but protocols are allowed to define more.
 342  *
 343  * Send an attention request message.
 344  *
 345  * Note that you can't send arbitrary PurpleAttentionType's, because there is
 346  * only a fixed set of attention commands.
 347  */
 348 void purple_protocol_send_attention(PurpleConnection *gc, const char *who,
 349                                     guint type_code);
 350
 351 /**
 352  * purple_protocol_got_attention:
 353  * @gc: The connection that received the attention message.
 354  * @who: Who requested your attention.
 355  * @type_code: An index into the protocol's attention_types list
 356  *                  determining the type of the attention request command to
 357  *                  send.
 358  *
 359  * Process an incoming attention message.
 360  */
 361 void purple_protocol_got_attention(PurpleConnection *gc, const char *who,
 362                                    guint type_code);
 363
 364 /**
 365  * purple_protocol_got_attention_in_chat:
 366  * @gc: The connection that received the attention message.
 367  * @id: The chat id.
 368  * @who: Who requested your attention.
 369  * @type_code: An index into the protocol's attention_types list
 370  *                  determining the type of the attention request command to
 371  *                  send.
 372  *
 373  * Process an incoming attention message in a chat.
 374  */
 375 void purple_protocol_got_attention_in_chat(PurpleConnection *gc, int id,
 376                                            const char *who, guint type_code);
 377
 378 /**
 379  * purple_protocol_get_media_caps:
 380  * @account: The account the user is on.
 381  * @who: The name of the contact to check capabilities for.
 382  *
 383  * Determines if the contact supports the given media session type.
 384  *
 385  * Returns: The media caps the contact supports.
 386  */
 387 PurpleMediaCaps purple_protocol_get_media_caps(PurpleAccount *account,
 388                                                const char *who);
 389
 390 /**
 391  * purple_protocol_initiate_media:
 392  * @account: The account the user is on.
 393  * @who: The name of the contact to start a session with.
 394  * @type: The type of media session to start.
 395  *
 396  * Initiates a media session with the given contact.
 397  *
 398  * Returns: TRUE if the call succeeded else FALSE. (Doesn't imply the media
 399  *          session or stream will be successfully created)
 400  */
 401 gboolean purple_protocol_initiate_media(PurpleAccount *account,
 402                                         const char *who,
 403                                         PurpleMediaSessionType type);
 404
 405 /**
 406  * purple_protocol_got_media_caps:
 407  * @account: The account the user is on.
 408  * @who: The name of the contact for which capabilities have been received.
 409  *
 410  * Signals that the protocol received capabilities for the given contact.
 411  *
 412  * This function is intended to be used only by protocols.
 413  */
 414 void purple_protocol_got_media_caps(PurpleAccount *account, const char *who);
 415
 416 /**
 417  * purple_protocol_get_max_message_size:
 418  * @protocol: The protocol to query.
 419  *
 420  * Gets the safe maximum message size in bytes for the protocol.
 421  *
 422  * See #PurpleProtocolClientIface's <literal>get_max_message_size</literal>.
 423  *
 424  * Returns: Maximum message size, 0 if unspecified, -1 for infinite.
 425  */
 426 gssize
 427 purple_protocol_get_max_message_size(PurpleProtocol *protocol);
 428
 429 /**************************************************************************/
 430 /* Protocols API                                                          */
 431 /**************************************************************************/
 432
 433 /**
 434  * purple_protocols_find:
 435  * @id: The protocol's ID.
 436  *
 437  * Finds a protocol by ID.
 438  */
 439 PurpleProtocol *purple_protocols_find(const char *id);
 440
 441 /**
 442  * purple_protocols_add:
 443  * @protocol_type:  The type of the protocol to add.
 444  * @error:  Return location for a #GError or %NULL. If provided, this
 445  *          will be set to the reason if adding fails.
 446  *
 447  * Adds a protocol to the list of protocols.
 448  *
 449  * Returns: The protocol instance if the protocol was added, else %NULL.
 450  */
 451 PurpleProtocol *purple_protocols_add(GType protocol_type, GError **error);
 452
 453 /**
 454  * purple_protocols_remove:
 455  * @protocol:  The protocol to remove.
 456  * @error:  Return location for a #GError or %NULL. If provided, this
 457  *          will be set to the reason if removing fails.
 458  *
 459  * Removes a protocol from the list of protocols. This will disconnect all
 460  * connected accounts using this protocol, and free the protocol's user splits
 461  * and protocol options.
 462  *
 463  * Returns: TRUE if the protocol was removed, else FALSE.
 464  */
 465 gboolean purple_protocols_remove(PurpleProtocol *protocol, GError **error);
 466
 467 /**
 468  * purple_protocols_get_all:
 469  *
 470  * Returns a list of all loaded protocols.
 471  *
 472  * Returns: (element-type PurpleProtocol) (transfer container): A list of all
 473  *          loaded protocols.
 474  */
 475 GList *purple_protocols_get_all(void);
 476
 477 /**************************************************************************/
 478 /* Protocols Subsytem API                                                 */
 479 /**************************************************************************/
 480
 481 /**
 482  * purple_protocols_init:
 483  *
 484  * Initializes the protocols subsystem.
 485  */
 486 void purple_protocols_init(void);
 487
 488 /**
 489  * purple_protocols_get_handle:
 490  *
 491  * Returns the protocols subsystem handle.
 492  *
 493  * Returns: The protocols subsystem handle.
 494  */
 495 void *purple_protocols_get_handle(void);
 496
 497 /**
 498  * purple_protocols_uninit:
 499  *
 500  * Uninitializes the protocols subsystem.
 501  */
 502 void purple_protocols_uninit(void);
 503
 504 G_END_DECLS
 505
 506 #endif /* _PROTOCOLS_H_ */