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;
00034 typedef struct _PurpleAttentionType PurpleAttentionType;
00035 
00036 /**************************************************************************/
00038 /**************************************************************************/
00039 
00040 typedef enum {
00041     PURPLE_ICON_SCALE_DISPLAY = 0x01,       
00042     PURPLE_ICON_SCALE_SEND = 0x02           
00043 } PurpleIconScaleRules;
00044 
00045 
00051 typedef struct _PurpleBuddyIconSpec PurpleBuddyIconSpec;
00052 
00057 #define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}
00058 
00059 #ifdef HAVE_UNISTD_H
00060 #include <unistd.h>
00061 #endif
00062 
00063 #include "blist.h"
00064 #include "conversation.h"
00065 #include "ft.h"
00066 #include "imgstore.h"
00067 #include "notify.h"
00068 #include "proxy.h"
00069 #include "plugin.h"
00070 #include "roomlist.h"
00071 #include "status.h"
00072 #include "whiteboard.h"
00073 
00074 struct _PurpleBuddyIconSpec {
00075     char *format;                       
00078     int min_width;                          
00079     int min_height;                         
00080     int max_width;                          
00081     int max_height;                         
00082     size_t max_filesize;                     
00083     PurpleIconScaleRules scale_rules;       
00084 };
00085 
00086 struct proto_chat_entry {
00087     const char *label;
00088     const char *identifier;
00089     gboolean required;
00090     gboolean is_int;
00091     int min;
00092     int max;
00093     gboolean secret;
00094 };
00095 
00096 struct _PurpleAttentionType
00097 {
00098     const char *name;                  
00099     const char *incoming_description;  
00100     const char *outgoing_description;  
00101     const char *icon_name;             
00102     const char *unlocalized_name;      
00104     /* Reserved fields for future purposes */
00105     gpointer _reserved2;
00106     gpointer _reserved3;
00107     gpointer _reserved4;
00108 };
00109 
00115 typedef enum
00116 {
00124     OPT_PROTO_UNIQUE_CHATNAME = 0x00000004,
00125 
00131     OPT_PROTO_CHAT_TOPIC = 0x00000008,
00132 
00139     OPT_PROTO_NO_PASSWORD = 0x00000010,
00140 
00146     OPT_PROTO_MAIL_CHECK = 0x00000020,
00147 
00153     OPT_PROTO_IM_IMAGE = 0x00000040,
00154 
00161     OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080,
00162 
00168     OPT_PROTO_USE_POINTSIZE = 0x00000100,
00169 
00175     OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200,
00176 
00182     OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400,
00183 
00184 } PurpleProtocolOptions;
00185 
00193 struct _PurplePluginProtocolInfo
00194 {
00195     PurpleProtocolOptions options;  
00197     GList *user_splits;      
00198     GList *protocol_options; 
00200     PurpleBuddyIconSpec icon_spec; 
00210     const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
00211 
00216     const char *(*list_emblem)(PurpleBuddy *buddy);
00217 
00222     char *(*status_text)(PurpleBuddy *buddy);
00223 
00227     void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
00228 
00234     GList *(*status_types)(PurpleAccount *account);
00235 
00241     GList *(*blist_node_menu)(PurpleBlistNode *node);
00242     GList *(*chat_info)(PurpleConnection *);
00243     GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name);
00244 
00245     /* All the server-related functions */
00246 
00248     void (*login)(PurpleAccount *);
00249 
00251     void (*close)(PurpleConnection *);
00252 
00262     int  (*send_im)(PurpleConnection *, const char *who,
00263                     const char *message,
00264                     PurpleMessageFlags flags);
00265 
00266     void (*set_info)(PurpleConnection *, const char *info);
00267     unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleTypingState state);
00272     void (*get_info)(PurpleConnection *, const char *who);
00273     void (*set_status)(PurpleAccount *account, PurpleStatus *status);
00274 
00275     void (*set_idle)(PurpleConnection *, int idletime);
00276     void (*change_passwd)(PurpleConnection *, const char *old_pass,
00277                           const char *new_pass);
00278     void (*add_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
00279     void (*add_buddies)(PurpleConnection *, GList *buddies, GList *groups);
00280     void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
00281     void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
00282     void (*add_permit)(PurpleConnection *, const char *name);
00283     void (*add_deny)(PurpleConnection *, const char *name);
00284     void (*rem_permit)(PurpleConnection *, const char *name);
00285     void (*rem_deny)(PurpleConnection *, const char *name);
00286     void (*set_permit_deny)(PurpleConnection *);
00287     void (*join_chat)(PurpleConnection *, GHashTable *components);
00288     void (*reject_chat)(PurpleConnection *, GHashTable *components);
00289     char *(*get_chat_name)(GHashTable *components);
00290     void (*chat_invite)(PurpleConnection *, int id,
00291                         const char *message, const char *who);
00292     void (*chat_leave)(PurpleConnection *, int id);
00293     void (*chat_whisper)(PurpleConnection *, int id,
00294                          const char *who, const char *message);
00295     int  (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
00296 
00303     void (*keepalive)(PurpleConnection *);
00304 
00306     void (*register_user)(PurpleAccount *);
00307 
00311     void (*get_cb_info)(PurpleConnection *, int, const char *who);
00316     void (*get_cb_away)(PurpleConnection *, int, const char *who);
00317 
00319     void (*alias_buddy)(PurpleConnection *, const char *who,
00320                         const char *alias);
00321 
00323     void (*group_buddy)(PurpleConnection *, const char *who,
00324                         const char *old_group, const char *new_group);
00325 
00327     void (*rename_group)(PurpleConnection *, const char *old_name,
00328                          PurpleGroup *group, GList *moved_buddies);
00329 
00330     void (*buddy_free)(PurpleBuddy *);
00331 
00332     void (*convo_closed)(PurpleConnection *, const char *who);
00333 
00339     const char *(*normalize)(const PurpleAccount *, const char *who);
00340 
00346     void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
00347 
00348     void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
00349 
00359     char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who);
00360 
00361     void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic);
00362 
00363     PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
00364 
00365     /* room listing prpl callbacks */
00366     PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc);
00367     void (*roomlist_cancel)(PurpleRoomlist *list);
00368     void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category);
00369 
00370     /* file transfer callbacks */
00371     gboolean (*can_receive_file)(PurpleConnection *, const char *who);
00372     void (*send_file)(PurpleConnection *, const char *who, const char *filename);
00373     PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who);
00374 
00379     gboolean (*offline_message)(const PurpleBuddy *buddy);
00380 
00381     PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
00382 
00384     int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
00385 
00386     /* room list serialize */
00387     char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
00388 
00393     /* This is here rather than next to register_user for API compatibility
00394      * reasons.
00395      */
00396     void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
00397     
00398     /* Attention API for sending & receiving zaps/nudges/buzzes etc. */
00399     gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
00400     GList *(*get_attention_types)(PurpleAccount *acct);
00401 
00402     void (*_purple_reserved4)(void);
00403 };
00404 
00405 #define PURPLE_IS_PROTOCOL_PLUGIN(plugin) \
00406     ((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)
00407 
00408 #define PURPLE_PLUGIN_PROTOCOL_INFO(plugin) \
00409     ((PurplePluginProtocolInfo *)(plugin)->info->extra_info)
00410 
00411 #ifdef __cplusplus
00412 extern "C" {
00413 #endif
00414 
00415 /**************************************************************************/
00417 /**************************************************************************/
00433 PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
00434                                 const char *inc_desc, const char *out_desc);
00435 
00445 void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
00446 
00455 void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc);
00456 
00465 void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc);
00466 
00475 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
00476 
00486 void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname);
00487 
00495 const char *purple_attention_type_get_name(const PurpleAttentionType *type);
00496 
00504 const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
00505 
00513 const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
00514 
00523 const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
00524 
00532 const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
00533 
00536 /**************************************************************************/
00538 /**************************************************************************/
00550 void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle,
00551                                 time_t idle_time);
00552 
00561 void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time);
00562 
00573 void purple_prpl_got_account_status(PurpleAccount *account,
00574                                   const char *status_id, ...) G_GNUC_NULL_TERMINATED;
00587 void purple_prpl_got_user_idle(PurpleAccount *account, const char *name,
00588                              gboolean idle, time_t idle_time);
00589 
00599 void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name,
00600                                    time_t login_time);
00601 
00613 void purple_prpl_got_user_status(PurpleAccount *account, const char *name,
00614                                const char *status_id, ...) G_GNUC_NULL_TERMINATED;
00615 
00625 void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name,
00626                     const char *status_id);
00627  
00636 void purple_prpl_change_account_status(PurpleAccount *account,
00637                                      PurpleStatus *old_status,
00638                                      PurpleStatus *new_status);
00639 
00648 GList *purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence);
00649 
00652 /**************************************************************************/
00654 /**************************************************************************/
00662 PurplePlugin *purple_find_prpl(const char *id);
00663 
00666 #ifdef __cplusplus
00667 }
00668 #endif
00669 
00670 #endif /* _PRPL_H_ */