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 
00058 #define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}
00059 
00060 #ifdef HAVE_UNISTD_H
00061 #include <unistd.h>
00062 #endif
00063 
00064 #include "blist.h"
00065 #include "conversation.h"
00066 #include "ft.h"
00067 #include "imgstore.h"
00068 #include "notify.h"
00069 #include "proxy.h"
00070 #include "plugin.h"
00071 #include "roomlist.h"
00072 #include "status.h"
00073 #include "whiteboard.h"
00074 
00075 
00077 struct _PurpleBuddyIconSpec {
00083     char *format;
00084 
00085     int min_width;                     
00086     int min_height;                    
00087     int max_width;                     
00088     int max_height;                    
00089     size_t max_filesize;               
00090     PurpleIconScaleRules scale_rules;  
00091 };
00092 
00093 struct proto_chat_entry {
00094     const char *label;
00095     const char *identifier;
00096     gboolean required;
00097     gboolean is_int;
00098     int min;
00099     int max;
00100     gboolean secret;
00101 };
00102 
00106 struct _PurpleAttentionType
00107 {
00108     const char *name;                  
00109     const char *incoming_description;  
00110     const char *outgoing_description;  
00111     const char *icon_name;             
00112     const char *unlocalized_name;      
00114     /* Reserved fields for future purposes */
00115     gpointer _reserved2;
00116     gpointer _reserved3;
00117     gpointer _reserved4;
00118 };
00119 
00125 typedef enum
00126 {
00134     OPT_PROTO_UNIQUE_CHATNAME = 0x00000004,
00135 
00141     OPT_PROTO_CHAT_TOPIC = 0x00000008,
00142 
00149     OPT_PROTO_NO_PASSWORD = 0x00000010,
00150 
00156     OPT_PROTO_MAIL_CHECK = 0x00000020,
00157 
00163     OPT_PROTO_IM_IMAGE = 0x00000040,
00164 
00171     OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080,
00172 
00178     OPT_PROTO_USE_POINTSIZE = 0x00000100,
00179 
00185     OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200,
00186 
00192     OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400,
00193 
00194 } PurpleProtocolOptions;
00195 
00203 struct _PurplePluginProtocolInfo
00204 {
00205     PurpleProtocolOptions options;  
00207     GList *user_splits;      
00208     GList *protocol_options; 
00210     PurpleBuddyIconSpec icon_spec; 
00220     const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
00221 
00226     const char *(*list_emblem)(PurpleBuddy *buddy);
00227 
00232     char *(*status_text)(PurpleBuddy *buddy);
00233 
00237     void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
00238 
00244     GList *(*status_types)(PurpleAccount *account);
00245 
00251     GList *(*blist_node_menu)(PurpleBlistNode *node);
00252     GList *(*chat_info)(PurpleConnection *);
00253     GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name);
00254 
00255     /* All the server-related functions */
00256 
00258     void (*login)(PurpleAccount *);
00259 
00261     void (*close)(PurpleConnection *);
00262 
00272     int  (*send_im)(PurpleConnection *, const char *who,
00273                     const char *message,
00274                     PurpleMessageFlags flags);
00275 
00276     void (*set_info)(PurpleConnection *, const char *info);
00277     unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleTypingState state);
00282     void (*get_info)(PurpleConnection *, const char *who);
00283     void (*set_status)(PurpleAccount *account, PurpleStatus *status);
00284 
00285     void (*set_idle)(PurpleConnection *, int idletime);
00286     void (*change_passwd)(PurpleConnection *, const char *old_pass,
00287                           const char *new_pass);
00288     void (*add_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
00289     void (*add_buddies)(PurpleConnection *, GList *buddies, GList *groups);
00290     void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
00291     void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
00292     void (*add_permit)(PurpleConnection *, const char *name);
00293     void (*add_deny)(PurpleConnection *, const char *name);
00294     void (*rem_permit)(PurpleConnection *, const char *name);
00295     void (*rem_deny)(PurpleConnection *, const char *name);
00296     void (*set_permit_deny)(PurpleConnection *);
00297     void (*join_chat)(PurpleConnection *, GHashTable *components);
00298     void (*reject_chat)(PurpleConnection *, GHashTable *components);
00299     char *(*get_chat_name)(GHashTable *components);
00300     void (*chat_invite)(PurpleConnection *, int id,
00301                         const char *message, const char *who);
00302     void (*chat_leave)(PurpleConnection *, int id);
00303     void (*chat_whisper)(PurpleConnection *, int id,
00304                          const char *who, const char *message);
00305     int  (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
00306 
00313     void (*keepalive)(PurpleConnection *);
00314 
00316     void (*register_user)(PurpleAccount *);
00317 
00321     void (*get_cb_info)(PurpleConnection *, int, const char *who);
00326     void (*get_cb_away)(PurpleConnection *, int, const char *who);
00327 
00329     void (*alias_buddy)(PurpleConnection *, const char *who,
00330                         const char *alias);
00331 
00333     void (*group_buddy)(PurpleConnection *, const char *who,
00334                         const char *old_group, const char *new_group);
00335 
00337     void (*rename_group)(PurpleConnection *, const char *old_name,
00338                          PurpleGroup *group, GList *moved_buddies);
00339 
00340     void (*buddy_free)(PurpleBuddy *);
00341 
00342     void (*convo_closed)(PurpleConnection *, const char *who);
00343 
00349     const char *(*normalize)(const PurpleAccount *, const char *who);
00350 
00356     void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
00357 
00358     void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
00359 
00369     char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who);
00370 
00371     void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic);
00372 
00373     PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
00374 
00375     /* room listing prpl callbacks */
00376     PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc);
00377     void (*roomlist_cancel)(PurpleRoomlist *list);
00378     void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category);
00379 
00380     /* file transfer callbacks */
00381     gboolean (*can_receive_file)(PurpleConnection *, const char *who);
00382     void (*send_file)(PurpleConnection *, const char *who, const char *filename);
00383     PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who);
00384 
00389     gboolean (*offline_message)(const PurpleBuddy *buddy);
00390 
00391     PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
00392 
00394     int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
00395 
00396     /* room list serialize */
00397     char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
00398 
00403     /* This is here rather than next to register_user for API compatibility
00404      * reasons.
00405      */
00406     void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
00407     
00408     /* Attention API for sending & receiving zaps/nudges/buzzes etc. */
00409     gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
00410     GList *(*get_attention_types)(PurpleAccount *acct);
00411 
00416     unsigned long struct_size;
00417 
00418     /* NOTE:
00419      * If more functions are added, they should accessed using the following syntax:
00420      *
00421      *      if (PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, new_function))
00422      *          prpl->new_function(...);
00423      *
00424      * instead of
00425      *
00426      *      if (prpl->new_function != NULL)
00427      *          prpl->new_function(...);
00428      *
00429      * The PURPLE_PROTOCOL_PLUGIN_HAS_FUNC macro can be used for the older member
00430      * functions (e.g. login, send_im etc.) too.
00431      */
00432 
00442     GHashTable *(*get_account_text_table)(PurpleAccount *account);
00443 };
00444 
00445 #define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) \
00446     (((G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < G_STRUCT_OFFSET(PurplePluginProtocolInfo, struct_size)) \
00447       || (G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size)) && \
00448      prpl->member != NULL)
00449 
00450 
00451 #define PURPLE_IS_PROTOCOL_PLUGIN(plugin) \
00452     ((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)
00453 
00454 #define PURPLE_PLUGIN_PROTOCOL_INFO(plugin) \
00455     ((PurplePluginProtocolInfo *)(plugin)->info->extra_info)
00456 
00457 #ifdef __cplusplus
00458 extern "C" {
00459 #endif
00460 
00461 /**************************************************************************/
00463 /**************************************************************************/
00479 PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
00480                                 const char *inc_desc, const char *out_desc);
00481 
00491 void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
00492 
00501 void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc);
00502 
00511 void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc);
00512 
00521 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
00522 
00532 void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname);
00533 
00541 const char *purple_attention_type_get_name(const PurpleAttentionType *type);
00542 
00550 const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
00551 
00559 const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
00560 
00569 const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
00570 
00578 const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
00579 
00582 /**************************************************************************/
00584 /**************************************************************************/
00596 void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle,
00597                                 time_t idle_time);
00598 
00607 void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time);
00608 
00619 void purple_prpl_got_account_status(PurpleAccount *account,
00620                                   const char *status_id, ...) G_GNUC_NULL_TERMINATED;
00633 void purple_prpl_got_user_idle(PurpleAccount *account, const char *name,
00634                              gboolean idle, time_t idle_time);
00635 
00645 void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name,
00646                                    time_t login_time);
00647 
00659 void purple_prpl_got_user_status(PurpleAccount *account, const char *name,
00660                                const char *status_id, ...) G_GNUC_NULL_TERMINATED;
00661 
00671 void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name,
00672                     const char *status_id);
00673  
00682 void purple_prpl_change_account_status(PurpleAccount *account,
00683                                      PurpleStatus *old_status,
00684                                      PurpleStatus *new_status);
00685 
00694 GList *purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence);
00695 
00708 void purple_prpl_send_attention(PurpleConnection *gc, const char *who, guint type_code);
00709 
00718 void purple_prpl_got_attention(PurpleConnection *gc, const char *who, guint type_code);
00719 
00729 void purple_prpl_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code);
00730 
00733 /**************************************************************************/
00735 /**************************************************************************/
00743 PurplePlugin *purple_find_prpl(const char *id);
00744 
00747 #ifdef __cplusplus
00748 }
00749 #endif
00750 
00751 #endif /* _PRPL_H_ */

Generated on Sun Sep 21 12:18:44 2008 for pidgin by  doxygen 1.5.5