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