home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / prpl.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  15.4 KB  |  470 lines
  1. /**
  2.  * @file prpl.h Protocol Plugin functions
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25.  
  26. /* this file should be all that prpls need to include. therefore, by including
  27.  * this file, they should get glib, proxy, purple_connection, prpl, etc. */
  28.  
  29. #ifndef _PURPLE_PRPL_H_
  30. #define _PURPLE_PRPL_H_
  31.  
  32. typedef struct _PurplePluginProtocolInfo PurplePluginProtocolInfo;
  33.  
  34. /**************************************************************************/
  35. /** @name Basic Protocol Information                                      */
  36. /**************************************************************************/
  37.  
  38. typedef enum {
  39.     PURPLE_ICON_SCALE_DISPLAY = 0x01,        /**< We scale the icon when we display it */
  40.     PURPLE_ICON_SCALE_SEND = 0x02            /**< We scale the icon before we send it to the server */
  41. } PurpleIconScaleRules;
  42.  
  43.  
  44. /**
  45.  * A description of a Buddy Icon specification.  This tells Purple what kind of image file
  46.  * it should give this prpl, and what kind of image file it should expect back.
  47.  * Dimensions less than 1 should be ignored and the image not scaled.
  48.  */
  49. typedef struct _PurpleBuddyIconSpec PurpleBuddyIconSpec;
  50.  
  51. /**
  52.  * This \#define exists just to make it easier to fill out the buddy icon
  53.  * field in the prpl info struct for protocols that couldn't care less.
  54.  */
  55. #define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}
  56.  
  57. #include <unistd.h>
  58.  
  59. #include "blist.h"
  60. #include "conversation.h"
  61. #include "ft.h"
  62. #include "imgstore.h"
  63. #include "notify.h"
  64. #include "proxy.h"
  65. #include "plugin.h"
  66. #include "roomlist.h"
  67. #include "status.h"
  68. #include "whiteboard.h"
  69.  
  70. struct _PurpleBuddyIconSpec {
  71.     char *format;                       /**< This is a comma-delimited list of image formats or NULL if icons are not supported.
  72.                          * Neither the core nor the prpl will actually check to see if the data it's given matches this; it's
  73.                          * entirely up to the UI to do what it wants */
  74.     int min_width;                          /**< The minimum width of this icon  */
  75.     int min_height;                         /**< The minimum height of this icon */
  76.     int max_width;                          /**< The maximum width of this icon  */
  77.     int max_height;                         /**< The maximum height of this icon */
  78.     size_t max_filesize;                     /**< The maximum number of bytes    */
  79.     PurpleIconScaleRules scale_rules;        /**< How to stretch this icon */
  80. };
  81.  
  82. struct proto_chat_entry {
  83.     const char *label;
  84.     const char *identifier;
  85.     gboolean required;
  86.     gboolean is_int;
  87.     int min;
  88.     int max;
  89.     gboolean secret;
  90. };
  91.  
  92. /**
  93.  * Protocol options
  94.  *
  95.  * These should all be stuff that some plugins can do and others can't.
  96.  */
  97. typedef enum
  98. {
  99.     /**
  100.      * Use a unique name, not an alias, for chat rooms.
  101.      *
  102.      * Jabber lets you choose what name you want for chat.
  103.      * So it shouldn't be pulling the alias for when you're in chat;
  104.      * it gets annoying.
  105.      */
  106.     OPT_PROTO_UNIQUE_CHATNAME = 0x00000004,
  107.  
  108.     /**
  109.      * Chat rooms have topics.
  110.      *
  111.      * IRC and Jabber support this.
  112.      */
  113.     OPT_PROTO_CHAT_TOPIC = 0x00000008,
  114.  
  115.     /**
  116.      * Don't require passwords for sign-in.
  117.      *
  118.      * Zephyr doesn't require passwords, so there's no
  119.      * need for a password prompt.
  120.      */
  121.     OPT_PROTO_NO_PASSWORD = 0x00000010,
  122.  
  123.     /**
  124.      * Notify on new mail.
  125.      *
  126.      * MSN and Yahoo notify you when you have new mail.
  127.      */
  128.     OPT_PROTO_MAIL_CHECK = 0x00000020,
  129.  
  130.     /**
  131.      * Images in IMs.
  132.      *
  133.      * Oscar lets you send images in direct IMs.
  134.      */
  135.     OPT_PROTO_IM_IMAGE = 0x00000040,
  136.  
  137.     /**
  138.      * Allow passwords to be optional.
  139.      *
  140.      * Passwords in IRC are optional, and are needed for certain
  141.      * functionality.
  142.      */
  143.     OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080,
  144.  
  145.     /**
  146.      * Allows font size to be specified in sane point size
  147.      *
  148.      * Probably just Jabber and Y!M
  149.      */
  150.     OPT_PROTO_USE_POINTSIZE = 0x00000100,
  151.  
  152.     /**
  153.      * Set the Register button active when screenname is not given.
  154.      *
  155.      * Gadu-Gadu doesn't need a screenname to register new account.
  156.      */
  157.     OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200,
  158.  
  159. } PurpleProtocolOptions;
  160.  
  161. /**
  162.  * A protocol plugin information structure.
  163.  *
  164.  * Every protocol plugin initializes this structure. It is the gateway
  165.  * between purple and the protocol plugin.  Many of this callbacks can be
  166.  * NULL.  If a callback must be implemented, it has a comment indicating so.
  167.  */
  168. struct _PurplePluginProtocolInfo
  169. {
  170.     PurpleProtocolOptions options;  /**< Protocol options.          */
  171.  
  172.     GList *user_splits;      /* A GList of PurpleAccountUserSplit */
  173.     GList *protocol_options; /* A GList of PurpleAccountOption    */
  174.  
  175.     PurpleBuddyIconSpec icon_spec; /* The icon spec. */
  176.  
  177.     /**
  178.      * Returns the base icon name for the given buddy and account.
  179.      * If buddy is NULL and the account is non-NULL, it will return the 
  180.      * name to use for the account's icon. If both are NULL, it will
  181.      * return the name to use for the protocol's icon.
  182.      *
  183.      * This must be implemented.
  184.      */
  185.     const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
  186.  
  187.     /**
  188.      * Fills the four char**'s with string identifiers for "emblems"
  189.      * that the UI will interpret and display as relevant
  190.      */
  191.     const char *(*list_emblem)(PurpleBuddy *buddy);
  192.  
  193.     /**
  194.      * Gets a short string representing this buddy's status.  This will
  195.      * be shown on the buddy list.
  196.      */
  197.     char *(*status_text)(PurpleBuddy *buddy);
  198.  
  199.     /**
  200.      * Allows the prpl to add text to a buddy's tooltip.
  201.      */
  202.     void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
  203.  
  204.     /**
  205.      * This must be implemented, and must add at least the offline
  206.      * and online states.
  207.      */
  208.     GList *(*status_types)(PurpleAccount *account);
  209.  
  210.     GList *(*blist_node_menu)(PurpleBlistNode *node);
  211.     GList *(*chat_info)(PurpleConnection *);
  212.     GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name);
  213.  
  214.     /* All the server-related functions */
  215.  
  216.     /** This must be implemented. */
  217.     void (*login)(PurpleAccount *);
  218.  
  219.     /** This must be implemented. */
  220.     void (*close)(PurpleConnection *);
  221.  
  222.     /**
  223.      * This PRPL function should return a positive value on success.
  224.      * If the message is too big to be sent, return -E2BIG.  If
  225.      * the account is not connected, return -ENOTCONN.  If the
  226.      * PRPL is unable to send the message for another reason, return
  227.      * some other negative value.  You can use one of the valid
  228.      * errno values, or just big something.  If the message should
  229.      * not be echoed to the conversation window, return 0.
  230.      */
  231.     int  (*send_im)(PurpleConnection *, const char *who,
  232.                     const char *message,
  233.                     PurpleMessageFlags flags);
  234.  
  235.     void (*set_info)(PurpleConnection *, const char *info);
  236.     unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleTypingState state);
  237.     void (*get_info)(PurpleConnection *, const char *who);
  238.     void (*set_status)(PurpleAccount *account, PurpleStatus *status);
  239.  
  240.     void (*set_idle)(PurpleConnection *, int idletime);
  241.     void (*change_passwd)(PurpleConnection *, const char *old_pass,
  242.                           const char *new_pass);
  243.     void (*add_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
  244.     void (*add_buddies)(PurpleConnection *, GList *buddies, GList *groups);
  245.     void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
  246.     void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
  247.     void (*add_permit)(PurpleConnection *, const char *name);
  248.     void (*add_deny)(PurpleConnection *, const char *name);
  249.     void (*rem_permit)(PurpleConnection *, const char *name);
  250.     void (*rem_deny)(PurpleConnection *, const char *name);
  251.     void (*set_permit_deny)(PurpleConnection *);
  252.     void (*join_chat)(PurpleConnection *, GHashTable *components);
  253.     void (*reject_chat)(PurpleConnection *, GHashTable *components);
  254.     char *(*get_chat_name)(GHashTable *components);
  255.     void (*chat_invite)(PurpleConnection *, int id,
  256.                         const char *message, const char *who);
  257.     void (*chat_leave)(PurpleConnection *, int id);
  258.     void (*chat_whisper)(PurpleConnection *, int id,
  259.                          const char *who, const char *message);
  260.     int  (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
  261.     void (*keepalive)(PurpleConnection *);
  262.  
  263.     /* new user registration */
  264.     void (*register_user)(PurpleAccount *);
  265.  
  266.     /* get "chat buddy" info and away message */
  267.     void (*get_cb_info)(PurpleConnection *, int, const char *who);
  268.     void (*get_cb_away)(PurpleConnection *, int, const char *who);
  269.  
  270.     /* save/store buddy's alias on server list/roster */
  271.     void (*alias_buddy)(PurpleConnection *, const char *who,
  272.                         const char *alias);
  273.  
  274.     /* change a buddy's group on a server list/roster */
  275.     void (*group_buddy)(PurpleConnection *, const char *who,
  276.                         const char *old_group, const char *new_group);
  277.  
  278.     /* rename a group on a server list/roster */
  279.     void (*rename_group)(PurpleConnection *, const char *old_name,
  280.                          PurpleGroup *group, GList *moved_buddies);
  281.  
  282.     void (*buddy_free)(PurpleBuddy *);
  283.  
  284.     void (*convo_closed)(PurpleConnection *, const char *who);
  285.  
  286.     const char *(*normalize)(const PurpleAccount *, const char *);
  287.  
  288.     /* The prpl does NOT own a reference to img.  If it needs one, it
  289.      * must purple_imgstore_ref(img) itself. */
  290.     void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
  291.  
  292.     void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
  293.  
  294.     char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who);
  295.  
  296.     void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic);
  297.  
  298.     PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
  299.  
  300.     /* room listing prpl callbacks */
  301.     PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc);
  302.     void (*roomlist_cancel)(PurpleRoomlist *list);
  303.     void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category);
  304.  
  305.     /* file transfer callbacks */
  306.     gboolean (*can_receive_file)(PurpleConnection *, const char *who);
  307.     void (*send_file)(PurpleConnection *, const char *who, const char *filename);
  308.     PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who);
  309.     gboolean (*offline_message)(const PurpleBuddy *buddy);
  310.  
  311.     PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
  312.  
  313.     /* For use in plugins that may understand the underlying protocol */
  314.     int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
  315.  
  316.     /* room list serialize */
  317.     char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
  318.  
  319.     void (*_purple_reserved1)(void);
  320.     void (*_purple_reserved2)(void);
  321.     void (*_purple_reserved3)(void);
  322.     void (*_purple_reserved4)(void);
  323. };
  324.  
  325. #define PURPLE_IS_PROTOCOL_PLUGIN(plugin) \
  326.     ((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)
  327.  
  328. #define PURPLE_PLUGIN_PROTOCOL_INFO(plugin) \
  329.     ((PurplePluginProtocolInfo *)(plugin)->info->extra_info)
  330.  
  331. #ifdef __cplusplus
  332. extern "C" {
  333. #endif
  334.  
  335. /**************************************************************************/
  336. /** @name Protocol Plugin API                                             */
  337. /**************************************************************************/
  338. /*@{*/
  339.  
  340. /**
  341.  * Notifies Purple that an account's idle state and time have changed.
  342.  *
  343.  * This is meant to be called from protocol plugins.
  344.  *
  345.  * @param account   The account.
  346.  * @param idle      The user's idle state.
  347.  * @param idle_time The user's idle time.
  348.  */
  349. void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle,
  350.                                 time_t idle_time);
  351.  
  352. /**
  353.  * Notifies Purple of an account's log-in time.
  354.  *
  355.  * This is meant to be called from protocol plugins.
  356.  *
  357.  * @param account    The account the user is on.
  358.  * @param login_time The user's log-in time.
  359.  */
  360. void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time);
  361.  
  362. /**
  363.  * Notifies Purple that an account's status has changed.
  364.  *
  365.  * This is meant to be called from protocol plugins.
  366.  *
  367.  * @param account   The account the user is on.
  368.  * @param status_id The status ID.
  369.  * @param ...       A NULL-terminated list of attribute IDs and values,
  370.  *                  beginning with the value for @a attr_id.
  371.  */
  372. void purple_prpl_got_account_status(PurpleAccount *account,
  373.                                   const char *status_id, ...);
  374. /**
  375.  * Notifies Purple that a user's idle state and time have changed.
  376.  *
  377.  * This is meant to be called from protocol plugins.
  378.  *
  379.  * @param account   The account the user is on.
  380.  * @param name      The screen name of the user.
  381.  * @param idle      The user's idle state.
  382.  * @param idle_time The user's idle time.  This is the time at
  383.  *                  which the user became idle, in seconds since
  384.  *                  the epoch.
  385.  */
  386. void purple_prpl_got_user_idle(PurpleAccount *account, const char *name,
  387.                              gboolean idle, time_t idle_time);
  388.  
  389. /**
  390.  * Notifies Purple of a user's log-in time.
  391.  *
  392.  * This is meant to be called from protocol plugins.
  393.  *
  394.  * @param account    The account the user is on.
  395.  * @param name       The screen name of the user.
  396.  * @param login_time The user's log-in time.
  397.  */
  398. void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name,
  399.                                    time_t login_time);
  400.  
  401. /**
  402.  * Notifies Purple that a user's status has been activated.
  403.  *
  404.  * This is meant to be called from protocol plugins.
  405.  *
  406.  * @param account   The account the user is on.
  407.  * @param name      The screen name of the user.
  408.  * @param status_id The status ID.
  409.  * @param ...       A NULL-terminated list of attribute IDs and values,
  410.  *                  beginning with the value for @a attr_id.
  411.  */
  412. void purple_prpl_got_user_status(PurpleAccount *account, const char *name,
  413.                                const char *status_id, ...);
  414.  
  415. /**
  416.  * Notifies libpurple that a user's status has been deactivated
  417.  *
  418.  * This is meant to be called from protocol plugins.
  419.  *
  420.  * @param account   The account the user is on.
  421.  * @param name      The screen name of the user.
  422.  * @param status_id The status ID.
  423.  */
  424. void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name,
  425.                     const char *status_id);
  426.  
  427. /**
  428.  * Informs the server that an account's status changed.
  429.  *
  430.  * @param account    The account the user is on.
  431.  * @param old_status The previous status.
  432.  * @param new_status The status that was activated, or deactivated
  433.  *                   (in the case of independent statuses).
  434.  */
  435. void purple_prpl_change_account_status(PurpleAccount *account,
  436.                                      PurpleStatus *old_status,
  437.                                      PurpleStatus *new_status);
  438.  
  439. /**
  440.  * Retrieves the list of stock status types from a prpl.
  441.  *
  442.  * @param account The account the user is on.
  443.  * @param presence The presence for which we're going to get statuses
  444.  *
  445.  * @return List of statuses
  446.  */
  447. GList *purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence);
  448.  
  449. /*@}*/
  450.  
  451. /**************************************************************************/
  452. /** @name Protocol Plugin Subsystem API                                   */
  453. /**************************************************************************/
  454. /*@{*/
  455.  
  456. /**
  457.  * Finds a protocol plugin structure of the specified type.
  458.  *
  459.  * @param id The protocol plugin;
  460.  */
  461. PurplePlugin *purple_find_prpl(const char *id);
  462.  
  463. /*@}*/
  464.  
  465. #ifdef __cplusplus
  466. }
  467. #endif
  468.  
  469. #endif /* _PRPL_H_ */
  470.