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 *);
  38
  39 #define PURPLE_TYPE_ATTENTION_TYPE  (purple_attention_type_get_type())
  40
  41 /**
  42  * PurpleAttentionType:
  43  *
  44  * Represents "nudges" and "buzzes" that you may send to a buddy to attract
  45  * their attention (or vice-versa).
  46  */
  47 typedef struct _PurpleAttentionType PurpleAttentionType;
  48
  49 /**************************************************************************/
  50 /* Basic Protocol Information                                             */
  51 /**************************************************************************/
  52
  53 typedef struct _PurpleProtocolChatEntry PurpleProtocolChatEntry;
  54
  55 /**
  56  * PurpleProtocolOptions:
  57  * @OPT_PROTO_UNIQUE_CHATNAME: User names are unique to a chat and are not
  58  *           shared between rooms.<sbr/>
  59  *           XMPP lets you choose what name you want in chats, so it shouldn't
  60  *           be pulling the aliases from the buddy list for the chat list; it
  61  *           gets annoying.
  62  * @OPT_PROTO_CHAT_TOPIC: Chat rooms have topics.<sbr/>
  63  *           IRC and XMPP support this.
  64  * @OPT_PROTO_NO_PASSWORD: Don't require passwords for sign-in.<sbr/>
  65  *           Zephyr doesn't require passwords, so there's no need for a
  66  *           password prompt.
  67  * @OPT_PROTO_MAIL_CHECK: Notify on new mail.<sbr/>
  68  *           MSN and Yahoo notify you when you have new mail.
  69  * @OPT_PROTO_PASSWORD_OPTIONAL: Allow passwords to be optional.<sbr/>
  70  *           Passwords in IRC are optional, and are needed for certain
  71  *           functionality.
  72  * @OPT_PROTO_USE_POINTSIZE: Allows font size to be specified in sane point
  73  *           size.<sbr/>
  74  *           Probably just XMPP and Y!M
  75  * @OPT_PROTO_REGISTER_NOSCREENNAME: Set the Register button active even when
  76  *           the username has not been specified.<sbr/>
  77  *           Gadu-Gadu doesn't need a username to register new account (because
  78  *           usernames are assigned by the server).
  79  * @OPT_PROTO_SLASH_COMMANDS_NATIVE: Indicates that slash commands are native
  80  *           to this protocol.<sbr/>
  81  *           Used as a hint that unknown commands should not be sent as
  82  *           messages.
  83  * @OPT_PROTO_INVITE_MESSAGE: Indicates that this protocol supports sending a
  84  *           user-supplied message along with an invitation.
  85  * @OPT_PROTO_AUTHORIZATION_GRANTED_MESSAGE: Indicates that this protocol
  86  *           supports sending a user-supplied message along with an
  87  *           authorization acceptance.
  88  * @OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE: Indicates that this protocol
  89  *           supports sending a user-supplied message along with an
  90  *           authorization denial.
  91  *
  92  * Protocol options
  93  *
  94  * These should all be stuff that some protocols can do and others can't.
  95  */
  96 typedef enum  /*< flags >*/
  97 {
  98         OPT_PROTO_UNIQUE_CHATNAME               = 0x00000004,
  99         OPT_PROTO_CHAT_TOPIC                    = 0x00000008,
 100         OPT_PROTO_NO_PASSWORD                   = 0x00000010,
 101         OPT_PROTO_MAIL_CHECK                    = 0x00000020,
 102         OPT_PROTO_PASSWORD_OPTIONAL             = 0x00000080,
 103         OPT_PROTO_USE_POINTSIZE                 = 0x00000100,
 104         OPT_PROTO_REGISTER_NOSCREENNAME         = 0x00000200,
 105         OPT_PROTO_SLASH_COMMANDS_NATIVE         = 0x00000400,
 106         OPT_PROTO_INVITE_MESSAGE                = 0x00000800,
 107         OPT_PROTO_AUTHORIZATION_GRANTED_MESSAGE = 0x00001000,
 108         OPT_PROTO_AUTHORIZATION_DENIED_MESSAGE  = 0x00002000
 109
 110 } PurpleProtocolOptions;
 111
 112 #include "media.h"
 113 #include "protocol.h"
 114 #include "status.h"
 115
 116 #define PURPLE_TYPE_PROTOCOL_CHAT_ENTRY  (purple_protocol_chat_entry_get_type())
 117
 118 /**
 119  * PurpleProtocolChatEntry:
 120  * @label:      User-friendly name of the entry
 121  * @identifier: Used by the protocol to identify the option
 122  * @required:   True if it's required
 123  * @is_int:     True if the entry expects an integer
 124  * @min:        Minimum value in case of integer
 125  * @max:        Maximum value in case of integer
 126  * @secret:     True if the entry is secret (password)
 127  *
 128  * Represents an entry containing information that must be supplied by the
 129  * user when joining a chat.
 130  */
 131 struct _PurpleProtocolChatEntry {
 132         const char *label;
 133         const char *identifier;
 134         gboolean required;
 135         gboolean is_int;
 136         int min;
 137         int max;
 138         gboolean secret;
 139 };
 140
 141 /**
 142  * PurpleProtocolAction:
 143  *
 144  * Represents an action that the protocol can perform. This shows up in the
 145  * Accounts menu, under a submenu with the name of the account.
 146  */
 147 struct _PurpleProtocolAction {
 148         char *label;
 149         PurpleProtocolActionCallback callback;
 150         PurpleConnection *connection;
 151         gpointer user_data;
 152 };
 153
 154 G_BEGIN_DECLS
 155
 156 /**************************************************************************/
 157 /* Attention Type API                                                     */
 158 /**************************************************************************/
 159
 160 /**
 161  * purple_attention_type_get_type:
 162  *
 163  * Returns: The #GType for the #PurpleAttentionType boxed structure.
 164  */
 165 GType purple_attention_type_get_type(void);
 166
 167 /**
 168  * purple_attention_type_new:
 169  * @ulname: A non-localized string that can be used by UIs in need of such
 170  *               non-localized strings.  This should be the same as @name,
 171  *               without localization.
 172  * @name: A localized string that the UI may display for the event. This
 173  *             should be the same string as @ulname, with localization.
 174  * @inc_desc: A localized description shown when the event is received.
 175  * @out_desc: A localized description shown when the event is sent.
 176  *
 177  * Creates a new #PurpleAttentionType object and sets its mandatory parameters.
 178  *
 179  * Returns: A pointer to the new object.
 180  */
 181 PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
 182                                                                 const char *inc_desc, const char *out_desc);
 183
 184 /**
 185  * purple_attention_type_set_name:
 186  * @type: The attention type.
 187  * @name: The localized name that will be displayed by UIs. This should be
 188  *             the same string given as the unlocalized name, but with
 189  *             localization.
 190  *
 191  * Sets the displayed name of the attention-demanding event.
 192  */
 193 void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
 194
 195 /**
 196  * purple_attention_type_set_incoming_desc:
 197  * @type: The attention type.
 198  * @desc: The localized description for incoming events.
 199  *
 200  * Sets the description of the attention-demanding event shown in  conversations
 201  * when the event is received.
 202  */
 203 void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc);
 204
 205 /**
 206  * purple_attention_type_set_outgoing_desc:
 207  * @type: The attention type.
 208  * @desc: The localized description for outgoing events.
 209  *
 210  * Sets the description of the attention-demanding event shown in conversations
 211  * when the event is sent.
 212  */
 213 void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc);
 214
 215 /**
 216  * purple_attention_type_set_icon_name:
 217  * @type: The attention type.
 218  * @name: The icon's name.
 219  *
 220  * Sets the name of the icon to display for the attention event; this is optional.
 221  *
 222  * Note: Icons are optional for attention events.
 223  */
 224 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
 225
 226 /**
 227  * purple_attention_type_set_unlocalized_name:
 228  * @type: The attention type.
 229  * @ulname: The unlocalized name.  This should be the same string given as
 230  *               the localized name, but without localization.
 231  *
 232  * Sets the unlocalized name of the attention event; some UIs may need this,
 233  * thus it is required.
 234  */
 235 void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname);
 236
 237 /**
 238  * purple_attention_type_get_name:
 239  * @type: The attention type.
 240  *
 241  * Get the attention type's name as displayed by the UI.
 242  *
 243  * Returns: The name.
 244  */
 245 const char *purple_attention_type_get_name(const PurpleAttentionType *type);
 246
 247 /**
 248  * purple_attention_type_get_incoming_desc:
 249  * @type: The attention type.
 250  *
 251  * Get the attention type's description shown when the event is received.
 252  *
 253  * Returns: The description.
 254  */
 255 const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
 256
 257 /**
 258  * purple_attention_type_get_outgoing_desc:
 259  * @type: The attention type.
 260  *
 261  * Get the attention type's description shown when the event is sent.
 262  *
 263  * Returns: The description.
 264  */
 265 const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
 266
 267 /**
 268  * purple_attention_type_get_icon_name:
 269  * @type: The attention type.
 270  *
 271  * Get the attention type's icon name.
 272  *
 273  * Note: Icons are optional for attention events.
 274  *
 275  * Returns: The icon name or %NULL if unset/empty.
 276  */
 277 const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
 278
 279 /**
 280  * purple_attention_type_get_unlocalized_name:
 281  * @type: The attention type
 282  *
 283  * Get the attention type's unlocalized name; this is useful for some UIs.
 284  *
 285  * Returns: The unlocalized name.
 286  */
 287 const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
 288
 289 /**************************************************************************/
 290 /* Protocol Action API                                                    */
 291 /**************************************************************************/
 292
 293 /**
 294  * purple_protocol_action_get_type:
 295  *
 296  * Returns: The #GType for the #PurpleProtocolAction boxed structure.
 297  */
 298 GType purple_protocol_action_get_type(void);
 299
 300 /**
 301  * purple_protocol_action_new:
 302  * @label:    The description of the action to show to the user.
 303  * @callback: (scope call): The callback to call when the user selects this
 304  *            action.
 305  *
 306  * Allocates and returns a new PurpleProtocolAction. Use this to add actions in
 307  * a list in the get_actions function of the protocol.
 308  */
 309 PurpleProtocolAction *purple_protocol_action_new(const char* label,
 310                 PurpleProtocolActionCallback callback);
 311
 312 /**
 313  * purple_protocol_action_free:
 314  * @action: The PurpleProtocolAction to free.
 315  *
 316  * Frees a PurpleProtocolAction
 317  */
 318 void purple_protocol_action_free(PurpleProtocolAction *action);
 319
 320 /**************************************************************************/
 321 /* Protocol Chat Entry API                                                */
 322 /**************************************************************************/
 323
 324 /**
 325  * purple_protocol_chat_entry_get_type:
 326  *
 327  * Returns: The #GType for the #PurpleProtocolChatEntry boxed structure.
 328  */
 329 GType purple_protocol_chat_entry_get_type(void);
 330
 331 /**************************************************************************/
 332 /* Protocol API                                                           */
 333 /**************************************************************************/
 334
 335 /**
 336  * purple_protocol_got_account_idle:
 337  * @account:   The account.
 338  * @idle:      The user's idle state.
 339  * @idle_time: The user's idle time.
 340  *
 341  * Notifies Purple that our account's idle state and time have changed.
 342  *
 343  * This is meant to be called from protocols.
 344  */
 345 void purple_protocol_got_account_idle(PurpleAccount *account, gboolean idle,
 346                                       time_t idle_time);
 347
 348 /**
 349  * purple_protocol_got_account_login_time:
 350  * @account:    The account the user is on.
 351  * @login_time: The user's log-in time.
 352  *
 353  * Notifies Purple of our account's log-in time.
 354  *
 355  * This is meant to be called from protocols.
 356  */
 357 void purple_protocol_got_account_login_time(PurpleAccount *account,
 358                                             time_t login_time);
 359
 360 /**
 361  * purple_protocol_got_account_status:
 362  * @account:   The account the user is on.
 363  * @status_id: The status ID.
 364  * @...:       A NULL-terminated list of attribute IDs and values,
 365  *             beginning with the value for <literal>attr_id</literal>.
 366  *
 367  * Notifies Purple that our account's status has changed.
 368  *
 369  * This is meant to be called from protocols.
 370  */
 371 void purple_protocol_got_account_status(PurpleAccount *account,
 372                                         const char *status_id, ...)
 373                                         G_GNUC_NULL_TERMINATED;
 374
 375 /**
 376  * purple_protocol_got_account_actions:
 377  * @account:   The account.
 378  *
 379  * Notifies Purple that our account's actions have changed. This is only
 380  * called after the initial connection. Emits the account-actions-changed
 381  * signal.
 382  *
 383  * This is meant to be called from protocols.
 384  *
 385  * See <link linkend="accounts-account-actions-changed"><literal>"account-actions-changed"</literal></link>
 386  */
 387 void purple_protocol_got_account_actions(PurpleAccount *account);
 388
 389 /**
 390  * purple_protocol_got_user_idle:
 391  * @account:   The account the user is on.
 392  * @name:      The name of the buddy.
 393  * @idle:      The user's idle state.
 394  * @idle_time: The user's idle time.  This is the time at
 395  *                  which the user became idle, in seconds since
 396  *                  the epoch.  If the protocol does not know this value
 397  *                  then it should pass 0.
 398  *
 399  * Notifies Purple that a buddy's idle state and time have changed.
 400  *
 401  * This is meant to be called from protocols.
 402  */
 403 void purple_protocol_got_user_idle(PurpleAccount *account, const char *name,
 404                                    gboolean idle, time_t idle_time);
 405
 406 /**
 407  * purple_protocol_got_user_login_time:
 408  * @account:    The account the user is on.
 409  * @name:       The name of the buddy.
 410  * @login_time: The user's log-in time.
 411  *
 412  * Notifies Purple of a buddy's log-in time.
 413  *
 414  * This is meant to be called from protocols.
 415  */
 416 void purple_protocol_got_user_login_time(PurpleAccount *account,
 417                                          const char *name, time_t login_time);
 418
 419 /**
 420  * purple_protocol_got_user_status:
 421  * @account:   The account the user is on.
 422  * @name:      The name of the buddy.
 423  * @status_id: The status ID.
 424  * @...:       A NULL-terminated list of attribute IDs and values,
 425  *             beginning with the value for <literal>attr_id</literal>.
 426  *
 427  * Notifies Purple that a buddy's status has been activated.
 428  *
 429  * This is meant to be called from protocols.
 430  */
 431 void purple_protocol_got_user_status(PurpleAccount *account, const char *name,
 432                                      const char *status_id, ...)
 433                                      G_GNUC_NULL_TERMINATED;
 434
 435 /**
 436  * purple_protocol_got_user_status_deactive:
 437  * @account:   The account the user is on.
 438  * @name:      The name of the buddy.
 439  * @status_id: The status ID.
 440  *
 441  * Notifies libpurple that a buddy's status has been deactivated
 442  *
 443  * This is meant to be called from protocols.
 444  */
 445 void purple_protocol_got_user_status_deactive(PurpleAccount *account,
 446                                               const char *name,
 447                                               const char *status_id);
 448
 449 /**
 450  * purple_protocol_change_account_status:
 451  * @account:    The account the user is on.
 452  * @old_status: The previous status.
 453  * @new_status: The status that was activated, or deactivated
 454  *                   (in the case of independent statuses).
 455  *
 456  * Informs the server that our account's status changed.
 457  */
 458 void purple_protocol_change_account_status(PurpleAccount *account,
 459                                            PurpleStatus *old_status,
 460                                            PurpleStatus *new_status);
 461
 462 /**
 463  * purple_protocol_get_statuses:
 464  * @account: The account the user is on.
 465  * @presence: The presence for which we're going to get statuses
 466  *
 467  * Retrieves the list of stock status types from a protocol.
 468  *
 469  * Returns: List of statuses
 470  */
 471 GList *purple_protocol_get_statuses(PurpleAccount *account,
 472                                     PurplePresence *presence);
 473
 474 /**
 475  * purple_protocol_send_attention:
 476  * @gc: The connection to send the message on.
 477  * @who: Whose attention to request.
 478  * @type_code: An index into the protocol's attention_types list determining the type
 479  *        of the attention request command to send. 0 if protocol only defines one
 480  *        (for example, Yahoo and MSN), but protocols are allowed to define more.
 481  *
 482  * Send an attention request message.
 483  *
 484  * Note that you can't send arbitrary PurpleAttentionType's, because there is
 485  * only a fixed set of attention commands.
 486  */
 487 void purple_protocol_send_attention(PurpleConnection *gc, const char *who,
 488                                     guint type_code);
 489
 490 /**
 491  * purple_protocol_got_attention:
 492  * @gc: The connection that received the attention message.
 493  * @who: Who requested your attention.
 494  * @type_code: An index into the protocol's attention_types list
 495  *                  determining the type of the attention request command to
 496  *                  send.
 497  *
 498  * Process an incoming attention message.
 499  */
 500 void purple_protocol_got_attention(PurpleConnection *gc, const char *who,
 501                                    guint type_code);
 502
 503 /**
 504  * purple_protocol_got_attention_in_chat:
 505  * @gc: The connection that received the attention message.
 506  * @id: The chat id.
 507  * @who: Who requested your attention.
 508  * @type_code: An index into the protocol's attention_types list
 509  *                  determining the type of the attention request command to
 510  *                  send.
 511  *
 512  * Process an incoming attention message in a chat.
 513  */
 514 void purple_protocol_got_attention_in_chat(PurpleConnection *gc, int id,
 515                                            const char *who, guint type_code);
 516
 517 /**
 518  * purple_protocol_get_media_caps:
 519  * @account: The account the user is on.
 520  * @who: The name of the contact to check capabilities for.
 521  *
 522  * Determines if the contact supports the given media session type.
 523  *
 524  * Returns: The media caps the contact supports.
 525  */
 526 PurpleMediaCaps purple_protocol_get_media_caps(PurpleAccount *account,
 527                                                const char *who);
 528
 529 /**
 530  * purple_protocol_initiate_media:
 531  * @account: The account the user is on.
 532  * @who: The name of the contact to start a session with.
 533  * @type: The type of media session to start.
 534  *
 535  * Initiates a media session with the given contact.
 536  *
 537  * Returns: TRUE if the call succeeded else FALSE. (Doesn't imply the media
 538  *          session or stream will be successfully created)
 539  */
 540 gboolean purple_protocol_initiate_media(PurpleAccount *account,
 541                                         const char *who,
 542                                         PurpleMediaSessionType type);
 543
 544 /**
 545  * purple_protocol_got_media_caps:
 546  * @account: The account the user is on.
 547  * @who: The name of the contact for which capabilities have been received.
 548  *
 549  * Signals that the protocol received capabilities for the given contact.
 550  *
 551  * This function is intended to be used only by protocols.
 552  */
 553 void purple_protocol_got_media_caps(PurpleAccount *account, const char *who);
 554
 555 /**
 556  * purple_protocol_get_max_message_size:
 557  * @protocol: The protocol to query.
 558  *
 559  * Gets the safe maximum message size in bytes for the protocol.
 560  *
 561  * See #PurpleProtocolClientIface's <literal>get_max_message_size</literal>.
 562  *
 563  * Returns: Maximum message size, 0 if unspecified, -1 for infinite.
 564  */
 565 gssize
 566 purple_protocol_get_max_message_size(PurpleProtocol *protocol);
 567
 568 /**************************************************************************/
 569 /* Protocols API                                                          */
 570 /**************************************************************************/
 571
 572 /**
 573  * purple_protocols_find:
 574  * @id: The protocol's ID.
 575  *
 576  * Finds a protocol by ID.
 577  */
 578 PurpleProtocol *purple_protocols_find(const char *id);
 579
 580 /**
 581  * purple_protocols_add:
 582  * @protocol_type:  The type of the protocol to add.
 583  * @error:  Return location for a #GError or %NULL. If provided, this
 584  *          will be set to the reason if adding fails.
 585  *
 586  * Adds a protocol to the list of protocols.
 587  *
 588  * Returns: The protocol instance if the protocol was added, else %NULL.
 589  */
 590 PurpleProtocol *purple_protocols_add(GType protocol_type, GError **error);
 591
 592 /**
 593  * purple_protocols_remove:
 594  * @protocol:  The protocol to remove.
 595  * @error:  Return location for a #GError or %NULL. If provided, this
 596  *          will be set to the reason if removing fails.
 597  *
 598  * Removes a protocol from the list of protocols. This will disconnect all
 599  * connected accounts using this protocol, and free the protocol's user splits
 600  * and protocol options.
 601  *
 602  * Returns: TRUE if the protocol was removed, else FALSE.
 603  */
 604 gboolean purple_protocols_remove(PurpleProtocol *protocol, GError **error);
 605
 606 /**
 607  * purple_protocols_get_all:
 608  *
 609  * Returns a list of all loaded protocols.
 610  *
 611  * Returns: A list of all loaded protocols. The list is owned by the caller, and
 612  *         must be g_list_free()d to avoid leaking the nodes.
 613  */
 614 GList *purple_protocols_get_all(void);
 615
 616 /**************************************************************************/
 617 /* Protocols Subsytem API                                                 */
 618 /**************************************************************************/
 619
 620 /**
 621  * purple_protocols_init:
 622  *
 623  * Initializes the protocols subsystem.
 624  */
 625 void purple_protocols_init(void);
 626
 627 /**
 628  * purple_protocols_get_handle:
 629  *
 630  * Returns the protocols subsystem handle.
 631  *
 632  * Returns: The protocols subsystem handle.
 633  */
 634 void *purple_protocols_get_handle(void);
 635
 636 /**
 637  * purple_protocols_uninit:
 638  *
 639  * Uninitializes the protocols subsystem.
 640  */
 641 void purple_protocols_uninit(void);
 642
 643 G_END_DECLS
 644
 645 #endif /* _PROTOCOLS_H_ */