libpurple/protocol.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_PROTOCOL_H
  23 #define PURPLE_PROTOCOL_H
  24 /**
  25  * SECTION:protocol
  26  * @section_id: libpurple-protocol
  27  * @short_description: <filename>protocol.h</filename>
  28  * @title: Protocol Object and Interfaces
  29  */
  30
  31 #define PURPLE_TYPE_PROTOCOL            (purple_protocol_get_type())
  32 #define PURPLE_PROTOCOL(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_PROTOCOL, PurpleProtocol))
  33 #define PURPLE_PROTOCOL_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_PROTOCOL, PurpleProtocolClass))
  34 #define PURPLE_IS_PROTOCOL(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL))
  35 #define PURPLE_IS_PROTOCOL_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_PROTOCOL))
  36 #define PURPLE_PROTOCOL_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_PROTOCOL, PurpleProtocolClass))
  37
  38 typedef struct _PurpleProtocol PurpleProtocol;
  39 typedef struct _PurpleProtocolClass PurpleProtocolClass;
  40
  41 #include "account.h"
  42 #include "buddyicon.h"
  43 #include "buddylist.h"
  44 #include "connection.h"
  45 #include "conversations.h"
  46 #include "debug.h"
  47 #include "xfer.h"
  48 #include "image.h"
  49 #include "media.h"
  50 #include "message.h"
  51 #include "notify.h"
  52 #include "plugins.h"
  53 #include "purpleaccountoption.h"
  54 #include "purpleaccountusersplit.h"
  55 #include "roomlist.h"
  56 #include "status.h"
  57 #include "whiteboard.h"
  58
  59 /**
  60  * PurpleProtocol:
  61  * @id:              Protocol ID
  62  * @name:            Translated name of the protocol
  63  * @options:         Protocol options
  64  * @user_splits:     A GList of PurpleAccountUserSplit
  65  * @account_options: A GList of PurpleAccountOption
  66  * @icon_spec:       The icon spec.
  67  * @whiteboard_ops:  Whiteboard operations
  68  *
  69  * Represents an instance of a protocol registered with the protocols
  70  * subsystem. Protocols must initialize the members to appropriate values.
  71  */
  72 struct _PurpleProtocol
  73 {
  74         GObject gparent;
  75
  76         /*< public >*/
  77         const char *id;
  78         const char *name;
  79
  80         PurpleProtocolOptions options;
  81
  82         GList *user_splits;
  83         GList *account_options;
  84
  85         PurpleBuddyIconSpec *icon_spec;
  86         PurpleWhiteboardOps *whiteboard_ops;
  87
  88         /*< private >*/
  89         void (*_purple_reserved1)(void);
  90         void (*_purple_reserved2)(void);
  91         void (*_purple_reserved3)(void);
  92         void (*_purple_reserved4)(void);
  93 };
  94
  95 /**
  96  * PurpleProtocolClass:
  97  * @login:        Log in to the server.
  98  * @close:        Close connection with the server.
  99  * @status_types: Returns a list of #PurpleStatusType which exist for this
 100  *                account; and must add at least the offline and online states.
 101  * @list_icon:    Returns the base icon name for the given buddy and account. If
 102  *                buddy is %NULL and the account is non-%NULL, it will return
 103  *                the name to use for the account's icon. If both are %NULL, it
 104  *                will return the name to use for the protocol's icon.
 105  *
 106  * The base class for all protocols.
 107  *
 108  * All protocol types must implement the methods in this class.
 109  */
 110 /* If adding new methods to this class, ensure you add checks for them in
 111    purple_protocols_add().
 112 */
 113 struct _PurpleProtocolClass
 114 {
 115         GObjectClass parent_class;
 116
 117         void (*login)(PurpleAccount *account);
 118
 119         void (*close)(PurpleConnection *connection);
 120
 121         GList *(*status_types)(PurpleAccount *account);
 122
 123         const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
 124
 125         /*< private >*/
 126         void (*_purple_reserved1)(void);
 127         void (*_purple_reserved2)(void);
 128         void (*_purple_reserved3)(void);
 129         void (*_purple_reserved4)(void);
 130 };
 131
 132 #define PURPLE_TYPE_PROTOCOL_CLIENT (purple_protocol_client_iface_get_type())
 133
 134 typedef struct _PurpleProtocolClientInterface PurpleProtocolClientInterface;
 135
 136 /**
 137  * PurpleProtocolClientInterface:
 138  * @get_actions:     Returns the actions the protocol can perform. These will
 139  *                   show up in the Accounts menu, under a submenu with the name
 140  *                   of the account.
 141  * @list_emblem:     Fills the four <type>char**</type>'s with string
 142  *                   identifiers for "emblems" that the UI will interpret and
 143  *                   display as relevant
 144  * @status_text:     Gets a short string representing this buddy's status. This
 145  *                   will be shown on the buddy list.
 146  * @tooltip_text:    Allows the protocol to add text to a buddy's tooltip.
 147  * @blist_node_menu: Returns a list of #PurpleActionMenu structs, which
 148  *                   represent extra actions to be shown in (for example) the
 149  *                   right-click menu for @node.
 150  * @normalize: Convert the username @who to its canonical form. Also checks for
 151  *             validity.
 152  *             <sbr/>For example, AIM treats "fOo BaR" and "foobar" as the same
 153  *             user; this function should return the same normalized string for
 154  *             both of those. On the other hand, both of these are invalid for
 155  *             protocols with number-based usernames, so function should return
 156  *             %NULL in such case.
 157  *             <sbr/>@account: The account the username is related to. Can be
 158  *                             %NULL.
 159  *             <sbr/>@who:     The username to convert.
 160  *             <sbr/>Returns:  Normalized username, or %NULL, if it's invalid.
 161  * @offline_message: Checks whether offline messages to @buddy are supported.
 162  *                   <sbr/>Returns: %TRUE if @buddy can be sent messages while
 163  *                                  they are offline, or %FALSE if not.
 164  * @get_account_text_table: This allows protocols to specify additional strings
 165  *                          to be used for various purposes. The idea is to
 166  *                          stuff a bunch of strings in this hash table instead
 167  *                          of expanding the struct for every addition. This
 168  *                          hash table is allocated every call and
 169  *                          <emphasis>MUST</emphasis> be unrefed by the caller.
 170  *                          <sbr/>@account: The account to specify.  This can be
 171  *                                          %NULL.
 172  *                          <sbr/>Returns:  The protocol's string hash table.
 173  *                                          The hash table should be destroyed
 174  *                                          by the caller when it's no longer
 175  *                                          needed.
 176  * @get_moods: Returns an array of #PurpleMood's, with the last one having
 177  *             "mood" set to %NULL.
 178  * @get_max_message_size: Gets the maximum message size in bytes for the
 179  *                        conversation.
 180  *                        <sbr/>It may depend on connection-specific or
 181  *                        conversation-specific variables, like channel or
 182  *                        buddy's name length.
 183  *                        <sbr/>This value is intended for plaintext message,
 184  *                              the exact value may be lower because of:
 185  *                        <sbr/> - used newlines (some protocols count them as
 186  *                                 more than one byte),
 187  *                        <sbr/> - formatting,
 188  *                        <sbr/> - used special characters.
 189  *                        <sbr/>@conv:   The conversation to query, or NULL to
 190  *                                       get safe minimum for the protocol.
 191  *                        <sbr/>Returns: Maximum message size, 0 if unspecified,
 192  *                                       -1 for infinite.
 193  *
 194  * The protocol client interface.
 195  *
 196  * This interface provides a gateway between purple and the protocol.
 197  */
 198 struct _PurpleProtocolClientInterface
 199 {
 200         /*< private >*/
 201         GTypeInterface parent_iface;
 202
 203         /*< public >*/
 204         GList *(*get_actions)(PurpleConnection *connection);
 205
 206         const char *(*list_emblem)(PurpleBuddy *buddy);
 207
 208         char *(*status_text)(PurpleBuddy *buddy);
 209
 210         void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info,
 211                                                  gboolean full);
 212
 213         GList *(*blist_node_menu)(PurpleBlistNode *node);
 214
 215         void (*buddy_free)(PurpleBuddy *buddy);
 216
 217         void (*convo_closed)(PurpleConnection *connection, const char *who);
 218
 219         const char *(*normalize)(const PurpleAccount *account, const char *who);
 220
 221         PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
 222
 223         gboolean (*offline_message)(const PurpleBuddy *buddy);
 224
 225         GHashTable *(*get_account_text_table)(PurpleAccount *account);
 226
 227         PurpleMood *(*get_moods)(PurpleAccount *account);
 228
 229         gssize (*get_max_message_size)(PurpleConversation *conv);
 230 };
 231
 232 #define PURPLE_IS_PROTOCOL_CLIENT(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_CLIENT))
 233 #define PURPLE_PROTOCOL_CLIENT_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_CLIENT, \
 234                                                PurpleProtocolClientInterface))
 235
 236 #define PURPLE_TYPE_PROTOCOL_SERVER (purple_protocol_server_iface_get_type())
 237
 238 typedef struct _PurpleProtocolServerInterface PurpleProtocolServerInterface;
 239
 240 /**
 241  * PurpleProtocolServerInterface:
 242  * @register_user:   New user registration
 243  * @unregister_user: Remove the user from the server. The account can either be
 244  *                   connected or disconnected. After the removal is finished,
 245  *                   the connection will stay open and has to be closed!
 246  * @get_info:        Should arrange for purple_notify_userinfo() to be called
 247  *                   with @who's user info.
 248  * @add_buddy:       Add a buddy to a group on the server.
 249  *                   <sbr/>This protocol function may be called in situations in
 250  *                   which the buddy is already in the specified group. If the
 251  *                   protocol supports authorization and the user is not already
 252  *                   authorized to see the status of @buddy, @add_buddy should
 253  *                   request authorization.
 254  *                   <sbr/>If authorization is required, then use the supplied
 255  *                   invite message.
 256  * @keepalive:       If implemented, this will be called regularly for this
 257  *                   protocol's active connections. You'd want to do this if you
 258  *                   need to repeatedly send some kind of keepalive packet to
 259  *                   the server to avoid being disconnected. ("Regularly" is
 260  *                   defined to be 30 unless get_keepalive_interval() is
 261  *                   implemented to override it).
 262  *                   <filename>libpurple/connection.c</filename>.)
 263  * @get_keepalive_interval: If implemented, this will override the default
 264  *                          keepalive interval.
 265  * @alias_buddy:     Save/store buddy's alias on server list/roster
 266  * @group_buddy:     Change a buddy's group on a server list/roster
 267  * @rename_group:    Rename a group on a server list/roster
 268  * @set_buddy_icon:  Set the buddy icon for the given connection to @img. The
 269  *                   protocol does <emphasis>NOT</emphasis> own a reference to
 270  *                   @img; if it needs one, it must #g_object_ref(@img)
 271  *                   itself.
 272  * @send_raw:        For use in plugins that may understand the underlying
 273  *                   protocol
 274  * @set_public_alias: Set the user's "friendly name" (or alias or nickname or
 275  *                    whatever term you want to call it) on the server. The
 276  *                    protocol should call @success_cb or @failure_cb
 277  *                    <emphasis>asynchronously</emphasis> (if it knows
 278  *                    immediately that the set will fail, call one of the
 279  *                    callbacks from an idle/0-second timeout) depending on if
 280  *                    the nickname is set successfully. See
 281  *                    purple_account_set_public_alias().
 282  *                    <sbr/>@gc:    The connection for which to set an alias
 283  *                    <sbr/>@alias: The new server-side alias/nickname for this
 284  *                                  account, or %NULL to unset the
 285  *                                  alias/nickname (or return it to a
 286  *                                  protocol-specific "default").
 287  *                    <sbr/>@success_cb: Callback to be called if the public
 288  *                                       alias is set
 289  *                    <sbr/>@failure_cb: Callback to be called if setting the
 290  *                                       public alias fails
 291  * @get_public_alias: Retrieve the user's "friendly name" as set on the server.
 292  *                    The protocol should call @success_cb or @failure_cb
 293  *                    <emphasis>asynchronously</emphasis> (even if it knows
 294  *                    immediately that the get will fail, call one of the
 295  *                    callbacks from an idle/0-second timeout) depending on if
 296  *                    the nickname is retrieved. See
 297  *                    purple_account_get_public_alias().
 298  *                    <sbr/>@gc:         The connection for which to retireve
 299  *                                       the alias
 300  *                    <sbr/>@success_cb: Callback to be called with the
 301  *                                       retrieved alias
 302  *                    <sbr/>@failure_cb: Callback to be called if the protocol
 303  *                                       is unable to retrieve the alias
 304  *
 305  * The protocol server interface.
 306  *
 307  * This interface provides a gateway between purple and the protocol's server.
 308  */
 309 struct _PurpleProtocolServerInterface
 310 {
 311         /*< private >*/
 312         GTypeInterface parent_iface;
 313
 314         /*< public >*/
 315         void (*register_user)(PurpleAccount *account);
 316
 317         void (*unregister_user)(PurpleAccount *account, PurpleAccountUnregistrationCb cb,
 318                                                         void *user_data);
 319
 320         void (*set_info)(PurpleConnection *connection, const char *info);
 321
 322         void (*get_info)(PurpleConnection *connection, const char *who);
 323
 324         void (*set_status)(PurpleAccount *account, PurpleStatus *status);
 325
 326         void (*set_idle)(PurpleConnection *connection, int idletime);
 327
 328         void (*change_passwd)(PurpleConnection *connection, const char *old_pass,
 329                                                   const char *new_pass);
 330
 331         void (*add_buddy)(PurpleConnection *pc, PurpleBuddy *buddy,
 332                                           PurpleGroup *group, const char *message);
 333
 334         void (*add_buddies)(PurpleConnection *pc, GList *buddies, GList *groups,
 335                                                 const char *message);
 336
 337         void (*remove_buddy)(PurpleConnection *connection, PurpleBuddy *buddy,
 338                                                  PurpleGroup *group);
 339
 340         void (*remove_buddies)(PurpleConnection *connection, GList *buddies, GList *groups);
 341
 342         void (*keepalive)(PurpleConnection *connection);
 343
 344         int (*get_keepalive_interval)(void);
 345
 346         void (*alias_buddy)(PurpleConnection *connection, const char *who,
 347                                                 const char *alias);
 348
 349         void (*group_buddy)(PurpleConnection *connection, const char *who,
 350                                         const char *old_group, const char *new_group);
 351
 352         void (*rename_group)(PurpleConnection *connection, const char *old_name,
 353                                          PurpleGroup *group, GList *moved_buddies);
 354
 355         void (*set_buddy_icon)(PurpleConnection *connection, PurpleImage *img);
 356
 357         void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
 358
 359         int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
 360
 361         void (*set_public_alias)(PurpleConnection *gc, const char *alias,
 362                                  PurpleSetPublicAliasSuccessCallback success_cb,
 363                                  PurpleSetPublicAliasFailureCallback failure_cb);
 364
 365         void (*get_public_alias)(PurpleConnection *gc,
 366                                  PurpleGetPublicAliasSuccessCallback success_cb,
 367                                  PurpleGetPublicAliasFailureCallback failure_cb);
 368 };
 369
 370 #define PURPLE_IS_PROTOCOL_SERVER(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_SERVER))
 371 #define PURPLE_PROTOCOL_SERVER_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_SERVER, \
 372                                                PurpleProtocolServerInterface))
 373
 374 #define PURPLE_TYPE_PROTOCOL_IM (purple_protocol_im_iface_get_type())
 375
 376 typedef struct _PurpleProtocolIMInterface PurpleProtocolIMInterface;
 377
 378 /**
 379  * PurpleProtocolIMInterface:
 380  * @send:        This protocol function should return a positive value on
 381  *               success. If the message is too big to be sent, return
 382  *               <literal>-E2BIG</literal>. If the account is not connected,
 383  *               return <literal>-ENOTCONN</literal>. If the protocol is unable
 384  *               to send the message for another reason, return some other
 385  *               negative value. You can use one of the valid #errno values, or
 386  *               just big something. If the message should not be echoed to the
 387  *               conversation window, return 0.
 388  * @send_typing: If this protocol requires the #PURPLE_IM_TYPING message to be
 389  *               sent repeatedly to signify that the user is still typing, then
 390  *               the protocol should return the number of seconds to wait before
 391  *               sending a subsequent notification. Otherwise the protocol
 392  *               should return 0.
 393  *
 394  * The protocol IM interface.
 395  *
 396  * This interface provides callbacks needed by protocols that implement IMs.
 397  */
 398 struct _PurpleProtocolIMInterface
 399 {
 400         /*< private >*/
 401         GTypeInterface parent_iface;
 402
 403         /*< public >*/
 404         int  (*send)(PurpleConnection *connection, PurpleMessage *msg);
 405
 406         unsigned int (*send_typing)(PurpleConnection *connection, const char *name,
 407                                                         PurpleIMTypingState state);
 408 };
 409
 410 #define PURPLE_IS_PROTOCOL_IM(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_IM))
 411 #define PURPLE_PROTOCOL_IM_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_IM, \
 412                                            PurpleProtocolIMInterface))
 413
 414 #define PURPLE_TYPE_PROTOCOL_CHAT (purple_protocol_chat_iface_get_type())
 415
 416 typedef struct _PurpleProtocolChatInterface PurpleProtocolChatInterface;
 417
 418 /**
 419  * PurpleProtocolChatInterface:
 420  * @info: Returns a list of #PurpleProtocolChatEntry structs, which represent
 421  *        information required by the protocol to join a chat. libpurple will
 422  *        call join_chat along with the information filled by the user.
 423  *        <sbr/>Returns: A list of #PurpleProtocolChatEntry's
 424  * @info_defaults: Returns a hashtable which maps #PurpleProtocolChatEntry
 425  *                 struct identifiers to default options as strings based on
 426  *                 @chat_name. The resulting hashtable should be created with
 427  *                 #g_hash_table_new_full(#g_str_hash, #g_str_equal, %NULL,
 428  *                 #g_free). Use @get_name if you instead need to extract a chat
 429  *                 name from a hashtable.
 430  *                 <sbr/>@chat_name: The chat name to be turned into components
 431  *                 <sbr/>Returns: Hashtable containing the information extracted
 432  *                                from @chat_name
 433  * @join: Called when the user requests joining a chat. Should arrange for
 434  *        purple_serv_got_joined_chat() to be called.
 435  *        <sbr/>@components: A hashtable containing information required to join
 436  *                           the chat as described by the entries returned by
 437  *                           @info. It may also be called when accepting an
 438  *                           invitation, in which case this matches the data
 439  *                           parameter passed to purple_serv_got_chat_invite().
 440  * @reject: Called when the user refuses a chat invitation.
 441  *          <sbr/>@components: A hashtable containing information required to
 442  *                            join the chat as passed to purple_serv_got_chat_invite().
 443  * @get_name: Returns a chat name based on the information in components. Use
 444  *            @info_defaults if you instead need to generate a hashtable from a
 445  *            chat name.
 446  *            <sbr/>@components: A hashtable containing information about the
 447  *                               chat.
 448  * @invite: Invite a user to join a chat.
 449  *          <sbr/>@id:      The id of the chat to invite the user to.
 450  *          <sbr/>@message: A message displayed to the user when the invitation
 451  *                          is received.
 452  *          <sbr/>@who:     The name of the user to send the invation to.
 453  * @leave: Called when the user requests leaving a chat.
 454  *         <sbr/>@id: The id of the chat to leave
 455  * @send: Send a message to a chat.
 456  *              <sbr/>This protocol function should return a positive value on
 457  *              success. If the message is too big to be sent, return
 458  *              <literal>-E2BIG</literal>. If the account is not connected,
 459  *              return <literal>-ENOTCONN</literal>. If the protocol is unable
 460  *              to send the message for another reason, return some other
 461  *              negative value. You can use one of the valid #errno values, or
 462  *              just big something.
 463  *              <sbr/>@id:      The id of the chat to send the message to.
 464  *              <sbr/>@msg:     The message to send to the chat.
 465  *              <sbr/>Returns:  A positive number or 0 in case of success, a
 466  *                              negative error number in case of failure.
 467  * @get_user_real_name: Gets the real name of a participant in a chat. For
 468  *                      example, on XMPP this turns a chat room nick
 469  *                      <literal>foo</literal> into
 470  *                      <literal>room\@server/foo</literal>.
 471  *                      <sbr/>@gc:  the connection on which the room is.
 472  *                      <sbr/>@id:  the ID of the chat room.
 473  *                      <sbr/>@who: the nickname of the chat participant.
 474  *                      <sbr/>Returns: the real name of the participant. This
 475  *                                     string must be freed by the caller.
 476  *
 477  * The protocol chat interface.
 478  *
 479  * This interface provides callbacks needed by protocols that implement chats.
 480  */
 481 struct _PurpleProtocolChatInterface
 482 {
 483         /*< private >*/
 484         GTypeInterface parent_iface;
 485
 486         /*< public >*/
 487         GList *(*info)(PurpleConnection *connection);
 488
 489         GHashTable *(*info_defaults)(PurpleConnection *connection, const char *chat_name);
 490
 491         void (*join)(PurpleConnection *connection, GHashTable *components);
 492
 493         void (*reject)(PurpleConnection *connection, GHashTable *components);
 494
 495         char *(*get_name)(GHashTable *components);
 496
 497         void (*invite)(PurpleConnection *connection, int id,
 498                                         const char *message, const char *who);
 499
 500         void (*leave)(PurpleConnection *connection, int id);
 501
 502         int  (*send)(PurpleConnection *connection, int id, PurpleMessage *msg);
 503
 504         char *(*get_user_real_name)(PurpleConnection *gc, int id, const char *who);
 505
 506         void (*set_topic)(PurpleConnection *gc, int id, const char *topic);
 507 };
 508
 509 #define PURPLE_IS_PROTOCOL_CHAT(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_CHAT))
 510 #define PURPLE_PROTOCOL_CHAT_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_CHAT, \
 511                                              PurpleProtocolChatInterface))
 512
 513 #define PURPLE_TYPE_PROTOCOL_PRIVACY (purple_protocol_privacy_iface_get_type())
 514
 515 typedef struct _PurpleProtocolPrivacyInterface PurpleProtocolPrivacyInterface;
 516
 517 /**
 518  * PurpleProtocolPrivacyInterface:
 519  * @add_permit:         Add the buddy on the required authorized list.
 520  * @add_deny:           Add the buddy on the required blocked list.
 521  * @rem_permit:         Remove the buddy from the requried authorized list.
 522  * @rem_deny:           Remove the buddy from the required blocked list.
 523  * @set_permit_deny:Update the server with the privacy information on the permit and deny lists.
 524  *
 525  * The protocol privacy interface.
 526  *
 527  * This interface provides privacy callbacks such as to permit/deny users.
 528  */
 529 struct _PurpleProtocolPrivacyInterface
 530 {
 531         /*< private >*/
 532         GTypeInterface parent_iface;
 533
 534         /*< public >*/
 535         void (*add_permit)(PurpleConnection *gc, const char *name);
 536
 537         void (*add_deny)(PurpleConnection *gc, const char *name);
 538
 539         void (*rem_permit)(PurpleConnection *gc, const char *name);
 540
 541         void (*rem_deny)(PurpleConnection *gc, const char *name);
 542
 543         void (*set_permit_deny)(PurpleConnection *gc);
 544 };
 545
 546 #define PURPLE_IS_PROTOCOL_PRIVACY(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_PRIVACY))
 547 #define PURPLE_PROTOCOL_PRIVACY_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_PRIVACY, \
 548                                                 PurpleProtocolPrivacyInterface))
 549
 550 #define PURPLE_TYPE_PROTOCOL_MEDIA (purple_protocol_media_iface_get_type())
 551
 552 typedef struct _PurpleProtocolMediaInterface PurpleProtocolMediaInterface;
 553
 554 /**
 555  * PurpleProtocolMediaInterface:
 556  * @initiate_session: Initiate a media session with the given contact.
 557  *                    <sbr/>@account: The account to initiate the media session
 558  *                                    on.
 559  *                    <sbr/>@who: The remote user to initiate the session with.
 560  *                    <sbr/>@type: The type of media session to initiate.
 561  *                    <sbr/>Returns: %TRUE if the call succeeded else %FALSE.
 562  *                                   (Doesn't imply the media session or stream
 563  *                                   will be successfully created)
 564  * @get_caps: Checks to see if the given contact supports the given type of
 565  *            media session.
 566  *            <sbr/>@account: The account the contact is on.
 567  *            <sbr/>@who: The remote user to check for media capability with.
 568  *            <sbr/>Returns: The media caps the contact supports.
 569  * @send_dtmf: Sends DTMF codes out-of-band in a protocol-specific way if the
 570  *             protocol supports it, or failing that in-band if the media backend
 571  *             can do so. See purple_media_send_dtmf().
 572  *
 573  * The protocol media interface.
 574  *
 575  * This interface provides callbacks for media sessions on the protocol.
 576  */
 577 struct _PurpleProtocolMediaInterface
 578 {
 579         /*< private >*/
 580         GTypeInterface parent_iface;
 581
 582         /*< public >*/
 583         gboolean (*initiate_session)(PurpleAccount *account, const char *who,
 584                                         PurpleMediaSessionType type);
 585
 586         PurpleMediaCaps (*get_caps)(PurpleAccount *account,
 587                                           const char *who);
 588
 589         gboolean (*send_dtmf)(PurpleMedia *media, gchar dtmf,
 590                                     guint8 volume, guint8 duration);
 591 };
 592
 593 #define PURPLE_IS_PROTOCOL_MEDIA(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_MEDIA))
 594 #define PURPLE_PROTOCOL_MEDIA_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_MEDIA, \
 595                                               PurpleProtocolMediaInterface))
 596
 597 #define PURPLE_TYPE_PROTOCOL_FACTORY (purple_protocol_factory_iface_get_type())
 598
 599 typedef struct _PurpleProtocolFactoryInterface PurpleProtocolFactoryInterface;
 600
 601 /**
 602  * PurpleProtocolFactoryInterface:
 603  * @connection_new: Creates a new protocol-specific connection object that
 604  *                  inherits #PurpleConnection.
 605  * @roomlist_new:   Creates a new protocol-specific room list object that
 606  *                  inherits #PurpleRoomlist.
 607  * @whiteboard_new: Creates a new protocol-specific whiteboard object that
 608  *                  inherits #PurpleWhiteboard.
 609  * @xfer_new:       Creates a new protocol-specific file transfer object that
 610  *                  inherits #PurpleXfer.
 611  *
 612  * The protocol factory interface.
 613  *
 614  * This interface provides callbacks for construction of protocol-specific
 615  * subclasses of some purple objects.
 616  */
 617 struct _PurpleProtocolFactoryInterface
 618 {
 619         /*< private >*/
 620         GTypeInterface parent_iface;
 621
 622         /*< public >*/
 623         PurpleConnection *(*connection_new)(PurpleProtocol *protocol,
 624                                             PurpleAccount *account,
 625                                             const char *password);
 626
 627         PurpleRoomlist *(*roomlist_new)(PurpleAccount *account);
 628
 629         PurpleWhiteboard *(*whiteboard_new)(PurpleAccount *account,
 630                                             const char *who, int state);
 631 };
 632
 633 #define PURPLE_IS_PROTOCOL_FACTORY(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_FACTORY))
 634 #define PURPLE_PROTOCOL_FACTORY_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE((obj), PURPLE_TYPE_PROTOCOL_FACTORY, \
 635                                                 PurpleProtocolFactoryInterface))
 636
 637 /**
 638  * PURPLE_PROTOCOL_IMPLEMENTS:
 639  * @protocol: The protocol in which to check
 640  * @IFACE:    The interface name in caps. e.g. <literal>CLIENT</literal>
 641  * @func:     The function to check
 642  *
 643  * Returns: %TRUE if a protocol implements a function in an interface,
 644  *          %FALSE otherwise.
 645  */
 646 #define PURPLE_PROTOCOL_IMPLEMENTS(protocol, IFACE, func) \
 647         (PURPLE_IS_PROTOCOL_##IFACE(protocol) && \
 648          PURPLE_PROTOCOL_##IFACE##_GET_IFACE(protocol)->func != NULL)
 649
 650 G_BEGIN_DECLS
 651
 652 /**************************************************************************/
 653 /* Protocol Object API                                                    */
 654 /**************************************************************************/
 655
 656 /**
 657  * purple_protocol_get_type:
 658  *
 659  * Returns: The #GType for #PurpleProtocol.
 660  */
 661 GType purple_protocol_get_type(void);
 662
 663 /**
 664  * purple_protocol_get_id:
 665  * @protocol: The protocol.
 666  *
 667  * Returns the ID of a protocol.
 668  *
 669  * Returns: The ID of the protocol.
 670  */
 671 const char *purple_protocol_get_id(const PurpleProtocol *protocol);
 672
 673 /**
 674  * purple_protocol_get_name:
 675  * @protocol: The protocol.
 676  *
 677  * Returns the translated name of a protocol.
 678  *
 679  * Returns: The translated name of the protocol.
 680  */
 681 const char *purple_protocol_get_name(const PurpleProtocol *protocol);
 682
 683 /**
 684  * purple_protocol_get_options:
 685  * @protocol: The protocol.
 686  *
 687  * Returns the options of a protocol.
 688  *
 689  * Returns: The options of the protocol.
 690  */
 691 PurpleProtocolOptions purple_protocol_get_options(const PurpleProtocol *protocol);
 692
 693 /**
 694  * purple_protocol_get_user_splits:
 695  * @protocol: The protocol.
 696  *
 697  * Returns the user splits of a protocol.
 698  *
 699  * Returns: (element-type PurpleAccountUserSplit) (transfer none): The user
 700  *          splits of the protocol.
 701  */
 702 GList *purple_protocol_get_user_splits(const PurpleProtocol *protocol);
 703
 704 /**
 705  * purple_protocol_get_account_options:
 706  * @protocol: The protocol.
 707  *
 708  * Returns the account options for a protocol.
 709  *
 710  * Returns: (element-type PurpleAccountOption) (transfer none): The account
 711  *          options for the protocol.
 712  */
 713 GList *purple_protocol_get_account_options(const PurpleProtocol *protocol);
 714
 715 /**
 716  * purple_protocol_get_icon_spec:
 717  * @protocol: The protocol.
 718  *
 719  * Returns the icon spec of a protocol.
 720  *
 721  * Returns: The icon spec of the protocol.
 722  */
 723 PurpleBuddyIconSpec *purple_protocol_get_icon_spec(const PurpleProtocol *protocol);
 724
 725 /**
 726  * purple_protocol_get_whiteboard_ops:
 727  * @protocol: The protocol.
 728  *
 729  * Returns the whiteboard ops of a protocol.
 730  *
 731  * Returns: The whiteboard ops of the protocol.
 732  */
 733 PurpleWhiteboardOps *purple_protocol_get_whiteboard_ops(const PurpleProtocol *protocol);
 734
 735 /**************************************************************************/
 736 /* Protocol Class API                                                     */
 737 /**************************************************************************/
 738
 739 void purple_protocol_class_login(PurpleProtocol *protocol, PurpleAccount *account);
 740
 741 void purple_protocol_class_close(PurpleProtocol *protocol, PurpleConnection *connection);
 742
 743 GList *purple_protocol_class_status_types(PurpleProtocol *protocol,
 744                 PurpleAccount *account);
 745
 746 const char *purple_protocol_class_list_icon(PurpleProtocol *protocol,
 747                 PurpleAccount *account, PurpleBuddy *buddy);
 748
 749 /**************************************************************************/
 750 /* Protocol Client Interface API                                          */
 751 /**************************************************************************/
 752
 753 /**
 754  * purple_protocol_client_iface_get_type:
 755  *
 756  * Returns: The #GType for the protocol client interface.
 757  *
 758  * Since: 3.0.0
 759  */
 760 GType purple_protocol_client_iface_get_type(void);
 761
 762 /**
 763  * purple_protocol_client_iface_get_actions:
 764  * @protocol: The #PurpleProtocol instance.
 765  * @connection: The #PurpleConnection instance.
 766  *
 767  * Gets a list of actions for @connection.
 768  *
 769  * Returns: (transfer full) (element-type PurpleProtocolAction): The list of actions for @connection.
 770  *
 771  * Since: 3.0.0
 772  */
 773 GList *purple_protocol_client_iface_get_actions(PurpleProtocol *protocol,
 774                 PurpleConnection *connection);
 775
 776 /**
 777  * purple_protocol_client_iface_list_emblem:
 778  * @protocol: The #PurpleProtocol instance.
 779  * @buddy: The #PurpleBuddy instance.
 780  *
 781  * Gets the icon name of the emblem that should be used for @buddy.
 782  *
 783  * Returns: The icon name of the emblem or NULL.
 784  *
 785  * Since: 3.0.0
 786  */
 787 const char *purple_protocol_client_iface_list_emblem(PurpleProtocol *protocol,
 788                 PurpleBuddy *buddy);
 789
 790 /**
 791  * purple_protocol_client_iface_status_text:
 792  * @protocol: The #PurpleProtocol instance.
 793  * @buddy: The #PurpleBuddy instance.
 794  *
 795  * Gets the status text for @buddy.
 796  *
 797  * Returns: (transfer full): The status text for @buddy or NULL.
 798  *
 799  * Since: 3.0.0
 800  */
 801 char *purple_protocol_client_iface_status_text(PurpleProtocol *protocol,
 802                 PurpleBuddy *buddy);
 803
 804 /**
 805  * purple_protocol_client_iface_tooltip_text:
 806  * @protocol: The #PurpleProtocol instance.
 807  * @buddy: The #PurpleBuddy instance.
 808  * @user_info: The #PurpleNotifyUserInfo instance.
 809  * @full: Whether or not additional info should be added.
 810  *
 811  * Asks @protocol to update @user_info for @buddy.  If @full is %TRUE then
 812  * more detailed information will added.
 813  *
 814  * Since: 3.0.0
 815  */
 816 void purple_protocol_client_iface_tooltip_text(PurpleProtocol *protocol,
 817                 PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
 818
 819 GList *purple_protocol_client_iface_blist_node_menu(PurpleProtocol *protocol,
 820                 PurpleBlistNode *node);
 821
 822 void purple_protocol_client_iface_buddy_free(PurpleProtocol *protocol, PurpleBuddy *buddy);
 823
 824 void purple_protocol_client_iface_convo_closed(PurpleProtocol *protocol,
 825                 PurpleConnection *connection, const char *who);
 826
 827 const char *purple_protocol_client_iface_normalize(PurpleProtocol *protocol,
 828                 const PurpleAccount *account, const char *who);
 829
 830 PurpleChat *purple_protocol_client_iface_find_blist_chat(PurpleProtocol *protocol,
 831                 PurpleAccount *account, const char *name);
 832
 833 gboolean purple_protocol_client_iface_offline_message(PurpleProtocol *protocol,
 834                 const PurpleBuddy *buddy);
 835
 836 GHashTable *purple_protocol_client_iface_get_account_text_table(PurpleProtocol *protocol,
 837                 PurpleAccount *account);
 838
 839 PurpleMood *purple_protocol_client_iface_get_moods(PurpleProtocol *protocol,
 840                 PurpleAccount *account);
 841
 842 gssize purple_protocol_client_iface_get_max_message_size(PurpleProtocol *protocol,
 843                 PurpleConversation *conv);
 844
 845 /**************************************************************************/
 846 /* Protocol Server Interface API                                          */
 847 /**************************************************************************/
 848
 849 /**
 850  * purple_protocol_server_iface_get_type:
 851  *
 852  * Returns: The #GType for the protocol server interface.
 853  */
 854 GType purple_protocol_server_iface_get_type(void);
 855
 856 void purple_protocol_server_iface_register_user(PurpleProtocol *protocol,
 857                 PurpleAccount *account);
 858
 859 /**
 860  * purple_protocol_server_iface_unregister_user:
 861  * @cb: (scope call):
 862  */
 863 void purple_protocol_server_iface_unregister_user(PurpleProtocol *protocol,
 864                 PurpleAccount *account, PurpleAccountUnregistrationCb cb, void *user_data);
 865
 866 void purple_protocol_server_iface_set_info(PurpleProtocol *protocol, PurpleConnection *connection,
 867                 const char *info);
 868
 869 void purple_protocol_server_iface_get_info(PurpleProtocol *protocol, PurpleConnection *connection,
 870                 const char *who);
 871
 872 void purple_protocol_server_iface_set_status(PurpleProtocol *protocol,
 873                 PurpleAccount *account, PurpleStatus *status);
 874
 875 void purple_protocol_server_iface_set_idle(PurpleProtocol *protocol, PurpleConnection *connection,
 876                 int idletime);
 877
 878 void purple_protocol_server_iface_change_passwd(PurpleProtocol *protocol,
 879                 PurpleConnection *connection, const char *old_pass, const char *new_pass);
 880
 881 void purple_protocol_server_iface_add_buddy(PurpleProtocol *protocol,
 882                 PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group,
 883                 const char *message);
 884
 885 void purple_protocol_server_iface_add_buddies(PurpleProtocol *protocol,
 886                 PurpleConnection *pc, GList *buddies, GList *groups,
 887                 const char *message);
 888
 889 void purple_protocol_server_iface_remove_buddy(PurpleProtocol *protocol,
 890                 PurpleConnection *connection, PurpleBuddy *buddy, PurpleGroup *group);
 891
 892 void purple_protocol_server_iface_remove_buddies(PurpleProtocol *protocol,
 893                 PurpleConnection *connection, GList *buddies, GList *groups);
 894
 895 void purple_protocol_server_iface_keepalive(PurpleProtocol *protocol,
 896                 PurpleConnection *connection);
 897
 898 int purple_protocol_server_iface_get_keepalive_interval(PurpleProtocol *protocol);
 899
 900 void purple_protocol_server_iface_alias_buddy(PurpleProtocol *protocol,
 901                 PurpleConnection *connection, const char *who, const char *alias);
 902
 903 void purple_protocol_server_iface_group_buddy(PurpleProtocol *protocol,
 904                 PurpleConnection *connection, const char *who, const char *old_group,
 905                 const char *new_group);
 906
 907 void purple_protocol_server_iface_rename_group(PurpleProtocol *protocol,
 908                 PurpleConnection *connection, const char *old_name, PurpleGroup *group,
 909                 GList *moved_buddies);
 910
 911 void purple_protocol_server_iface_set_buddy_icon(PurpleProtocol *protocol,
 912                 PurpleConnection *connection, PurpleImage *img);
 913
 914 void purple_protocol_server_iface_remove_group(PurpleProtocol *protocol,
 915                 PurpleConnection *gc, PurpleGroup *group);
 916
 917 int purple_protocol_server_iface_send_raw(PurpleProtocol *protocol,
 918                 PurpleConnection *gc, const char *buf, int len);
 919
 920 /**
 921  * purple_protocol_server_iface_set_public_alias:
 922  * @success_cb: (scope call):
 923  * @failure_cb: (scope call):
 924  */
 925 void purple_protocol_server_iface_set_public_alias(PurpleProtocol *protocol,
 926                 PurpleConnection *gc, const char *alias,
 927                 PurpleSetPublicAliasSuccessCallback success_cb,
 928                 PurpleSetPublicAliasFailureCallback failure_cb);
 929
 930 /**
 931  * purple_protocol_server_iface_get_public_alias:
 932  * @success_cb: (scope call):
 933  * @failure_cb: (scope call):
 934  */
 935 void purple_protocol_server_iface_get_public_alias(PurpleProtocol *protocol,
 936                 PurpleConnection *gc, PurpleGetPublicAliasSuccessCallback success_cb,
 937                 PurpleGetPublicAliasFailureCallback failure_cb);
 938
 939 /**************************************************************************/
 940 /* Protocol IM Interface API                                              */
 941 /**************************************************************************/
 942
 943 /**
 944  * purple_protocol_im_iface_get_type:
 945  *
 946  * Returns: The #GType for the protocol IM interface.
 947  */
 948 GType purple_protocol_im_iface_get_type(void);
 949
 950 int purple_protocol_im_iface_send(PurpleProtocol *protocol, PurpleConnection *connection,
 951                  PurpleMessage *msg);
 952
 953 unsigned int purple_protocol_im_iface_send_typing(PurpleProtocol *protocol,
 954                 PurpleConnection *connection, const char *name, PurpleIMTypingState state);
 955
 956 /**************************************************************************/
 957 /* Protocol Chat Interface API                                            */
 958 /**************************************************************************/
 959
 960 /**
 961  * purple_protocol_chat_iface_get_type:
 962  *
 963  * Returns: The #GType for the protocol chat interface.
 964  *
 965  * Since: 3.0.0
 966  */
 967 GType purple_protocol_chat_iface_get_type(void);
 968
 969 /**
 970  * purple_protocol_chat_iface_info:
 971  * @protocol: The #PurpleProtocol instance.
 972  * @connection: The #PurpleConnection instance.
 973  *
 974  * Gets the list of #PurpleProtocolChatEntry's that are required to join a
 975  * multi user chat.
 976  *
 977  * Returns: (transfer full) (element-type PurpleProtocolChatEntry): The list
 978  *          of #PurpleProtocolChatEntry's that are used to join a chat.
 979  *
 980  * Since: 3.0.0
 981  */
 982 GList *purple_protocol_chat_iface_info(PurpleProtocol *protocol,
 983                 PurpleConnection *connection);
 984
 985 /**
 986  * purple_protocol_chat_iface_info_defaults:
 987  * @protocol: The #PurpleProtocol instance
 988  * @connection: The #PurpleConnection instance
 989  * @chat_name: The name of the chat
 990  *
 991  * Returns a #GHashTable of the default protocol dependent components that will
 992  * be passed to #purple_protocol_chat_iface_join.
 993  *
 994  * Returns: (transfer full) (element-type utf8 utf8): The values that will be
 995  *          used to join the chat.
 996  *
 997  * Since: 3.0.0
 998  */
 999 GHashTable *purple_protocol_chat_iface_info_defaults(PurpleProtocol *protocol,
1000                 PurpleConnection *connection, const char *chat_name);
1001
1002 /**
1003  * purple_protocol_chat_iface_join:
1004  * @protocol: The #PurpleProtocol instance
1005  * @connection: The #PurpleConnection instance
1006  * @components: (element-type utf8 utf8): The protocol dependent join
1007  *              components
1008  *
1009  * Joins the chat described in @components.
1010  *
1011  * Since: 3.0.0
1012  */
1013 void purple_protocol_chat_iface_join(PurpleProtocol *protocol, PurpleConnection *connection,
1014                 GHashTable *components);
1015
1016 /**
1017  * purple_protocol_chat_iface_reject:
1018  * @protocol: The #PurpleProtocol instance
1019  * @connection: The #PurpleConnection instance
1020  * @components: (element-type utf8 utf8): The protocol dependent join
1021  *              components
1022  *
1023  * Not quite sure exactly what this does or where it's used.  Please fill in
1024  * the details if you know.
1025  *
1026  * Since: 3.0.0
1027  */
1028 void purple_protocol_chat_iface_reject(PurpleProtocol *protocol,
1029                 PurpleConnection *connection, GHashTable *components);
1030
1031 /**
1032  * purple_protocol_chat_iface_get_name:
1033  * @protocol: The #PurpleProtocol instance
1034  * @components: (element-type utf8 utf8): The protocol dependent join
1035  *              components
1036  *
1037  * Gets the name from @components.
1038  *
1039  * Returns: (transfer full): The chat name from @components.
1040  *
1041  * Since: 3.0.0
1042  */
1043 char *purple_protocol_chat_iface_get_name(PurpleProtocol *protocol,
1044                 GHashTable *components);
1045
1046 /**
1047  * purple_protocol_chat_iface_invite:
1048  * @protocol: The #PurpleProtocol instance
1049  * @connection: The #PurpleConnection instance
1050  * @id: The id of the chat
1051  * @message: The invite message
1052  * @who: The target of the invite
1053  *
1054  * Sends an invite to @who with @message.
1055  *
1056  * Since: 3.0.0
1057  */
1058 void purple_protocol_chat_iface_invite(PurpleProtocol *protocol,
1059                 PurpleConnection *connection, int id, const char *message, const char *who);
1060
1061 /**
1062  * purple_protocol_chat_iface_leave:
1063  * @protocol: The #PurpleProtocol instance
1064  * @connection: The #PurpleConnection instance
1065  * @id: The id of the chat
1066  *
1067  * Leaves the chat identified by @id.
1068  *
1069  * Since: 3.0.0
1070  */
1071 void purple_protocol_chat_iface_leave(PurpleProtocol *protocol, PurpleConnection *connection,
1072                 int id);
1073
1074 /**
1075  * purple_protocol_chat_iface_send:
1076  * @protocol: The #PurpleProtocol instance
1077  * @connection: The #PurpleConnection instance
1078  * @id: The id of the chat
1079  * @msg: The message to send
1080  *
1081  * Sends @msg to the chat identified by @id.
1082  *
1083  * Returns: 0 on success, non-zero on failure.
1084  *
1085  * Since: 3.0.0
1086  */
1087 int  purple_protocol_chat_iface_send(PurpleProtocol *protocol, PurpleConnection *connection,
1088                 int id, PurpleMessage *msg);
1089
1090 /**
1091  * purple_protocol_chat_iface_get_user_real_name:
1092  * @protocol: The #PurpleProtocol instance
1093  * @gc: The #PurpleConnection instance
1094  * @id: The id of the chat
1095  * @who: The username
1096  *
1097  * Gets the real name of @who.
1098  *
1099  * Returns: (transfer full): The realname of @who.
1100  *
1101  * Since: 3.0.0
1102  */
1103 char *purple_protocol_chat_iface_get_user_real_name(PurpleProtocol *protocol,
1104                 PurpleConnection *gc, int id, const char *who);
1105
1106 /**
1107  * purple_protocol_chat_iface_set_topic:
1108  * @protocol: The #PurpleProtocol instance
1109  * @gc: The #PurpleConnection instance
1110  * @id: The id of the chat
1111  * @topic: The new topic
1112  *
1113  * Sets the topic for the chat with id @id to @topic.
1114  *
1115  * Since: 3.0.0
1116  */
1117 void purple_protocol_chat_iface_set_topic(PurpleProtocol *protocol,
1118                 PurpleConnection *gc, int id, const char *topic);
1119
1120 /**************************************************************************/
1121 /* Protocol Privacy Interface API                                         */
1122 /**************************************************************************/
1123
1124 /**
1125  * purple_protocol_privacy_iface_get_type:
1126  *
1127  * Returns: The #GType for the protocol privacy interface.
1128  *
1129  * Since: 3.0.0
1130  */
1131 GType purple_protocol_privacy_iface_get_type(void);
1132
1133 /**
1134  * purple_protocol_privacy_iface_add_permit:
1135  * @protocol: The #PurpleProtocol instance.
1136  * @connection: The #PurpleConnection instance.
1137  * @name: The username to permit.
1138  *
1139  * Adds a permit to the privacy settings for @connection to allow @name to
1140  * contact the user.
1141  *
1142  * Since: 3.0.0
1143  */
1144 void purple_protocol_privacy_iface_add_permit(PurpleProtocol *protocol,
1145                 PurpleConnection *connection, const char *name);
1146
1147 /**
1148  * purple_protocol_privacy_iface_add_deny:
1149  * @protocol: The #PurpleProtocol instance.
1150  * @connection: The #PurpleConnection instance.
1151  * @name: The username to deny.
1152  *
1153  * Adds a deny to the privacy settings for @connection to deny @name from
1154  * contacting the user.
1155  *
1156  * Since: 3.0.0
1157  */
1158 void purple_protocol_privacy_iface_add_deny(PurpleProtocol *protocol,
1159                 PurpleConnection *connection, const char *name);
1160
1161 /**
1162  * purple_protocol_privacy_iface_rem_permit:
1163  * @protocol: The #PurpleProtocol instance.
1164  * @connection: The #PurpleConnection instance.
1165  * @name: The username to remove from the permit privacy settings.
1166  *
1167  * Removes an existing permit for @name.
1168  *
1169  * Since: 3.0.0
1170  */
1171 void purple_protocol_privacy_iface_rem_permit(PurpleProtocol *protocol,
1172                 PurpleConnection *connection, const char *name);
1173
1174 /**
1175  * purple_protocol_privacy_iface_rem_deny:
1176  * @protocol: The #PurpleProtocol instance.
1177  * @connection: The #PurpleConnection instance.
1178  * @name: The username to remove from the deny privacy settings.
1179  *
1180  * Removes an existing deny for @name.
1181  *
1182  * Since: 3.0.0
1183  */
1184 void purple_protocol_privacy_iface_rem_deny(PurpleProtocol *protocol,
1185                 PurpleConnection *connection, const char *name);
1186
1187 /**
1188  * purple_protocol_privacy_iface_set_permit_deny:
1189  * @protocol: The #PurpleProtocol instance.
1190  * @connection: The #PurpleConnection instance.
1191  *
1192  * Forces a sync of the privacy settings with server.
1193  *
1194  * Since: 3.0.0
1195  */
1196 void purple_protocol_privacy_iface_set_permit_deny(PurpleProtocol *protocol,
1197                 PurpleConnection *connection);
1198
1199 /**************************************************************************/
1200 /* Protocol Media Interface API                                           */
1201 /**************************************************************************/
1202
1203 /**
1204  * purple_protocol_media_iface_get_type:
1205  *
1206  * Returns: The #GType for the protocol media interface.
1207  *
1208  * Since: 3.0.0
1209  */
1210 GType purple_protocol_media_iface_get_type(void);
1211
1212 /**
1213  * purple_protocol_media_iface_initiate_session:
1214  * @protocol: The #PurpleProtocol instance.
1215  * @account: The #PurpleAccount instance.
1216  * @who: The user to initiate a media session with.
1217  * @type: The type of media session to create.
1218  *
1219  * Initiates a media connection of @type to @who.
1220  *
1221  * Returns: TRUE if successful, FALSE otherwise.
1222  *
1223  * Since: 3.0.0
1224  */
1225 gboolean purple_protocol_media_iface_initiate_session(PurpleProtocol *protocol,
1226                 PurpleAccount *account, const char *who, PurpleMediaSessionType type);
1227
1228 /**
1229  * purple_protocol_media_iface_get_caps:
1230  * @protocol: The #PurpleProtocol instance.
1231  * @account: The #PurpleAccount instance.
1232  * @who: The user to get the media capabilites for.
1233  *
1234  * Gets the #PurpleMediaCaps for @who which determine what types of media are
1235  * available.
1236  *
1237  * Returns: the media capabilities of @who.
1238  *
1239  * Since: 3.0.0
1240  */
1241 PurpleMediaCaps purple_protocol_media_iface_get_caps(PurpleProtocol *protocol,
1242                 PurpleAccount *account, const char *who);
1243
1244 /**
1245  * purple_protocol_media_iface_send_dtmf:
1246  * @protocol: The #PurpleProtocol instance.
1247  * @media: The #PurpleMedia instance.
1248  * @dtmf: A DTMF to send.
1249  * @volume: The volume to send @dtmf at.
1250  * @duration: The duration to send @dtmf (in ms?)
1251  *
1252  * Sends a DTMF (dual-tone multi-frequency) signal via the established @media
1253  * for the given @duration at the given @volume.
1254  *
1255  * It is up to the specific implementation if DTMF is send in or out of band.
1256  *
1257  * Returns: TRUE if successful, FALSE otherwise.
1258  *
1259  * Since: 3.0.0
1260  */
1261 gboolean purple_protocol_media_iface_send_dtmf(PurpleProtocol *protocol,
1262                 PurpleMedia *media, gchar dtmf, guint8 volume, guint8 duration);
1263
1264 /**************************************************************************/
1265 /* Protocol Factory Interface API                                         */
1266 /**************************************************************************/
1267
1268 /**
1269  * purple_protocol_factory_iface_get_type:
1270  *
1271  * Returns: The #GType for the protocol factory interface.
1272  */
1273 GType purple_protocol_factory_iface_get_type(void);
1274
1275 /**
1276  * purple_protocol_factory_iface_connection_new: (skip)
1277  */
1278 PurpleConnection *purple_protocol_factory_iface_connection_new(PurpleProtocol *protocol,
1279                 PurpleAccount *account, const char *password);
1280
1281 /**
1282  * purple_protocol_factory_iface_roomlist_new: (skip)
1283  */
1284 PurpleRoomlist *purple_protocol_factory_iface_roomlist_new(PurpleProtocol *protocol,
1285                 PurpleAccount *account);
1286
1287 /**
1288  * purple_protocol_factory_iface_whiteboard_new: (skip)
1289  */
1290 PurpleWhiteboard *purple_protocol_factory_iface_whiteboard_new(PurpleProtocol *protocol,
1291                 PurpleAccount *account, const char *who, int state);
1292
1293 G_END_DECLS
1294
1295 #endif /* PURPLE_PROTOCOL_H */