prpl.h

Go to the documentation of this file.
00001 
00006 /* purple
00007  *
00008  * Purple is the legal property of its developers, whose names are too numerous
00009  * to list here.  Please refer to the COPYRIGHT file distributed with this
00010  * source distribution.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU General Public License as published by
00014  * the Free Software Foundation; either version 2 of the License, or
00015  * (at your option) any later version.
00016  *
00017  * This program is distributed in the hope that it will be useful,
00018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  * GNU General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU General Public License
00023  * along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
00025  */
00026 
00027 /* this file should be all that prpls need to include. therefore, by including
00028  * this file, they should get glib, proxy, purple_connection, prpl, etc. */
00029 
00030 #ifndef _PURPLE_PRPL_H_
00031 #define _PURPLE_PRPL_H_
00032 
00033 typedef struct _PurplePluginProtocolInfo PurplePluginProtocolInfo;
00035 typedef struct _PurpleAttentionType PurpleAttentionType;
00036 
00037 /**************************************************************************/
00039 /**************************************************************************/
00040 
00041 typedef enum {
00042     PURPLE_ICON_SCALE_DISPLAY = 0x01,       
00043     PURPLE_ICON_SCALE_SEND = 0x02           
00044 } PurpleIconScaleRules;
00045 
00046 
00052 typedef struct _PurpleBuddyIconSpec PurpleBuddyIconSpec;
00053 
00059 typedef struct _PurpleThumbnailSpec PurpleThumbnailSpec;
00060 
00065 #define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}
00066 
00067 #ifdef HAVE_UNISTD_H
00068 #include <unistd.h>
00069 #endif
00070 
00071 #include "blist.h"
00072 #include "conversation.h"
00073 #include "ft.h"
00074 #include "imgstore.h"
00075 #include "media.h"
00076 #include "notify.h"
00077 #include "proxy.h"
00078 #include "plugin.h"
00079 #include "roomlist.h"
00080 #include "status.h"
00081 #include "whiteboard.h"
00082 
00083 
00085 struct _PurpleBuddyIconSpec {
00091     char *format;
00092 
00093     int min_width;                     
00094     int min_height;                    
00095     int max_width;                     
00096     int max_height;                    
00097     size_t max_filesize;               
00098     PurpleIconScaleRules scale_rules;  
00099 };
00100 
00104 struct proto_chat_entry {
00105     const char *label;       
00106     const char *identifier;  
00107     gboolean required;       
00108     gboolean is_int;         
00109     int min;                 
00110     int max;                 
00111     gboolean secret;         
00112 };
00113 
00117 struct _PurpleAttentionType
00118 {
00119     const char *name;                  
00120     const char *incoming_description;  
00121     const char *outgoing_description;  
00122     const char *icon_name;             
00123     const char *unlocalized_name;      
00125     /* Reserved fields for future purposes */
00126     gpointer _reserved2;
00127     gpointer _reserved3;
00128     gpointer _reserved4;
00129 };
00130 
00136 typedef enum
00137 {
00145     OPT_PROTO_UNIQUE_CHATNAME = 0x00000004,
00146 
00152     OPT_PROTO_CHAT_TOPIC = 0x00000008,
00153 
00160     OPT_PROTO_NO_PASSWORD = 0x00000010,
00161 
00167     OPT_PROTO_MAIL_CHECK = 0x00000020,
00168 
00174     OPT_PROTO_IM_IMAGE = 0x00000040,
00175 
00182     OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080,
00183 
00189     OPT_PROTO_USE_POINTSIZE = 0x00000100,
00190 
00198     OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200,
00199 
00205     OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400,
00206 
00212     OPT_PROTO_INVITE_MESSAGE = 0x00000800
00213 
00214 } PurpleProtocolOptions;
00215 
00223 struct _PurplePluginProtocolInfo
00224 {
00225     PurpleProtocolOptions options;  
00227     GList *user_splits;      
00228     GList *protocol_options; 
00230     PurpleBuddyIconSpec icon_spec; 
00240     const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
00241 
00246     const char *(*list_emblem)(PurpleBuddy *buddy);
00247 
00252     char *(*status_text)(PurpleBuddy *buddy);
00253 
00257     void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
00258 
00264     GList *(*status_types)(PurpleAccount *account);
00265 
00271     GList *(*blist_node_menu)(PurpleBlistNode *node);
00272 
00280     GList *(*chat_info)(PurpleConnection *);
00281 
00292     GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name);
00293 
00294     /* All the server-related functions */
00295 
00297     void (*login)(PurpleAccount *);
00298 
00300     void (*close)(PurpleConnection *);
00301 
00311     int  (*send_im)(PurpleConnection *, const char *who,
00312                     const char *message,
00313                     PurpleMessageFlags flags);
00314 
00315     void (*set_info)(PurpleConnection *, const char *info);
00316 
00324     unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleTypingState state);
00325 
00330     void (*get_info)(PurpleConnection *, const char *who);
00331     void (*set_status)(PurpleAccount *account, PurpleStatus *status);
00332 
00333     void (*set_idle)(PurpleConnection *, int idletime);
00334     void (*change_passwd)(PurpleConnection *, const char *old_pass,
00335                           const char *new_pass);
00347     void (*add_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
00348     void (*add_buddies)(PurpleConnection *, GList *buddies, GList *groups);
00349     void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
00350     void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
00351     void (*add_permit)(PurpleConnection *, const char *name);
00352     void (*add_deny)(PurpleConnection *, const char *name);
00353     void (*rem_permit)(PurpleConnection *, const char *name);
00354     void (*rem_deny)(PurpleConnection *, const char *name);
00355     void (*set_permit_deny)(PurpleConnection *);
00356 
00367     void (*join_chat)(PurpleConnection *, GHashTable *components);
00368 
00375     void (*reject_chat)(PurpleConnection *, GHashTable *components);
00376 
00384     char *(*get_chat_name)(GHashTable *components);
00385 
00394     void (*chat_invite)(PurpleConnection *, int id,
00395                         const char *message, const char *who);
00401     void (*chat_leave)(PurpleConnection *, int id);
00402 
00410     void (*chat_whisper)(PurpleConnection *, int id,
00411                          const char *who, const char *message);
00412 
00429     int  (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
00430 
00437     void (*keepalive)(PurpleConnection *);
00438 
00440     void (*register_user)(PurpleAccount *);
00441 
00445     void (*get_cb_info)(PurpleConnection *, int, const char *who);
00450     void (*get_cb_away)(PurpleConnection *, int, const char *who);
00451 
00453     void (*alias_buddy)(PurpleConnection *, const char *who,
00454                         const char *alias);
00455 
00457     void (*group_buddy)(PurpleConnection *, const char *who,
00458                         const char *old_group, const char *new_group);
00459 
00461     void (*rename_group)(PurpleConnection *, const char *old_name,
00462                          PurpleGroup *group, GList *moved_buddies);
00463 
00464     void (*buddy_free)(PurpleBuddy *);
00465 
00466     void (*convo_closed)(PurpleConnection *, const char *who);
00467 
00473     const char *(*normalize)(const PurpleAccount *, const char *who);
00474 
00480     void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
00481 
00482     void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
00483 
00493     char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who);
00494 
00495     void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic);
00496 
00497     PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
00498 
00499     /* room listing prpl callbacks */
00500     PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc);
00501     void (*roomlist_cancel)(PurpleRoomlist *list);
00502     void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category);
00503 
00504     /* file transfer callbacks */
00505     gboolean (*can_receive_file)(PurpleConnection *, const char *who);
00506     void (*send_file)(PurpleConnection *, const char *who, const char *filename);
00507     PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who);
00508 
00513     gboolean (*offline_message)(const PurpleBuddy *buddy);
00514 
00515     PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
00516 
00518     int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
00519 
00520     /* room list serialize */
00521     char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
00522 
00527     /* This is here rather than next to register_user for API compatibility
00528      * reasons.
00529      */
00530     void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
00531 
00532     /* Attention API for sending & receiving zaps/nudges/buzzes etc. */
00533     gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
00534     GList *(*get_attention_types)(PurpleAccount *acct);
00535 
00540     unsigned long struct_size;
00541 
00542     /* NOTE:
00543      * If more functions are added, they should accessed using the following syntax:
00544      *
00545      *      if (PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, new_function))
00546      *          prpl->new_function(...);
00547      *
00548      * instead of
00549      *
00550      *      if (prpl->new_function != NULL)
00551      *          prpl->new_function(...);
00552      *
00553      * The PURPLE_PROTOCOL_PLUGIN_HAS_FUNC macro can be used for the older member
00554      * functions (e.g. login, send_im etc.) too.
00555      */
00556 
00566     GHashTable *(*get_account_text_table)(PurpleAccount *account);
00567 
00576     gboolean (*initiate_media)(PurpleAccount *account, const char *who,
00577                     PurpleMediaSessionType type);
00578 
00586     PurpleMediaCaps (*get_media_caps)(PurpleAccount *account,
00587                       const char *who);
00588 
00594     PurpleMood *(*get_moods)(PurpleAccount *account);
00595 
00614     void (*set_public_alias)(PurpleConnection *gc, const char *alias,
00615                              PurpleSetPublicAliasSuccessCallback success_cb,
00616                              PurpleSetPublicAliasFailureCallback failure_cb);
00631     void (*get_public_alias)(PurpleConnection *gc,
00632                              PurpleGetPublicAliasSuccessCallback success_cb,
00633                              PurpleGetPublicAliasFailureCallback failure_cb);
00634 
00647     void (*add_buddy_with_invite)(PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message);
00648     void (*add_buddies_with_invite)(PurpleConnection *pc, GList *buddies, GList *groups, const char *message);
00649 };
00650 
00651 #define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) \
00652     (((G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < G_STRUCT_OFFSET(PurplePluginProtocolInfo, struct_size)) \
00653       || (G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size)) && \
00654      prpl->member != NULL)
00655 
00656 
00657 #define PURPLE_IS_PROTOCOL_PLUGIN(plugin) \
00658     ((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)
00659 
00660 #define PURPLE_PLUGIN_PROTOCOL_INFO(plugin) \
00661     ((PurplePluginProtocolInfo *)(plugin)->info->extra_info)
00662 
00663 #ifdef __cplusplus
00664 extern "C" {
00665 #endif
00666 
00667 /**************************************************************************/
00669 /**************************************************************************/
00685 PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
00686                                 const char *inc_desc, const char *out_desc);
00687 
00697 void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
00698 
00707 void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc);
00708 
00717 void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc);
00718 
00727 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
00728 
00738 void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname);
00739 
00747 const char *purple_attention_type_get_name(const PurpleAttentionType *type);
00748 
00756 const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
00757 
00765 const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
00766 
00775 const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
00776 
00784 const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
00785 
00788 /**************************************************************************/
00790 /**************************************************************************/
00802 void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle,
00803                                 time_t idle_time);
00804 
00813 void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time);
00814 
00825 void purple_prpl_got_account_status(PurpleAccount *account,
00826                                   const char *status_id, ...) G_GNUC_NULL_TERMINATED;
00827 
00840 void purple_prpl_got_account_actions(PurpleAccount *account);
00841 
00855 void purple_prpl_got_user_idle(PurpleAccount *account, const char *name,
00856                              gboolean idle, time_t idle_time);
00857 
00867 void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name,
00868                                    time_t login_time);
00869 
00881 void purple_prpl_got_user_status(PurpleAccount *account, const char *name,
00882                                const char *status_id, ...) G_GNUC_NULL_TERMINATED;
00883 
00893 void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name,
00894                     const char *status_id);
00895 
00904 void purple_prpl_change_account_status(PurpleAccount *account,
00905                                      PurpleStatus *old_status,
00906                                      PurpleStatus *new_status);
00907 
00916 GList *purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence);
00917 
00932 void purple_prpl_send_attention(PurpleConnection *gc, const char *who, guint type_code);
00933 
00944 void purple_prpl_got_attention(PurpleConnection *gc, const char *who, guint type_code);
00945 
00957 void purple_prpl_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code);
00958 
00967 PurpleMediaCaps purple_prpl_get_media_caps(PurpleAccount *account,
00968                   const char *who);
00969 
00979 gboolean purple_prpl_initiate_media(PurpleAccount *account,
00980                     const char *who,
00981                     PurpleMediaSessionType type);
00982 
00992 void purple_prpl_got_media_caps(PurpleAccount *account, const char *who);
00993 
00996 /**************************************************************************/
00998 /**************************************************************************/
01006 PurplePlugin *purple_find_prpl(const char *id);
01007 
01010 #ifdef __cplusplus
01011 }
01012 #endif
01013 
01014 #endif /* _PRPL_H_ */