prpl.h
Go to the documentation of this file.
1 
6 /* purple
7  *
8  * Purple is the legal property of its developers, whose names are too numerous
9  * to list here. Please refer to the COPYRIGHT file distributed with this
10  * source distribution.
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU General Public License as published by
14  * the Free Software Foundation; either version 2 of the License, or
15  * (at your option) any later version.
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20  * GNU General Public License for more details.
21  *
22  * You should have received a copy of the GNU General Public License
23  * along with this program; if not, write to the Free Software
24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
25  */
26 
27 /* this file should be all that prpls need to include. therefore, by including
28  * this file, they should get glib, proxy, purple_connection, prpl, etc. */
29 
30 #ifndef _PURPLE_PRPL_H_
31 #define _PURPLE_PRPL_H_
32 
36 
37 /**************************************************************************/
39 /**************************************************************************/
40 
41 typedef enum {
45 
46 
53 
59 typedef struct _PurpleThumbnailSpec PurpleThumbnailSpec;
60 
65 #define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}
66 
67 #ifdef HAVE_UNISTD_H
68 #include <unistd.h>
69 #endif
70 
71 #include "blist.h"
72 #include "conversation.h"
73 #include "ft.h"
74 #include "imgstore.h"
75 #include "media.h"
76 #include "notify.h"
77 #include "proxy.h"
78 #include "plugin.h"
79 #include "roomlist.h"
80 #include "status.h"
81 #include "whiteboard.h"
82 
83 
91  char *format;
92 
93  int min_width;
94  int min_height;
95  int max_width;
96  int max_height;
97  size_t max_filesize;
99 };
100 
105  const char *label;
106  const char *identifier;
107  gboolean required;
108  gboolean is_int;
109  int min;
110  int max;
111  gboolean secret;
112 };
113 
118 {
119  const char *name;
120  const char *incoming_description;
121  const char *outgoing_description;
122  const char *icon_name;
123  const char *unlocalized_name;
125  /* Reserved fields for future purposes */
126  gpointer _reserved2;
127  gpointer _reserved3;
128  gpointer _reserved4;
129 };
130 
136 typedef enum
137 {
146 
152  OPT_PROTO_CHAT_TOPIC = 0x00000008,
153 
160  OPT_PROTO_NO_PASSWORD = 0x00000010,
161 
167  OPT_PROTO_MAIL_CHECK = 0x00000020,
168 
174  OPT_PROTO_IM_IMAGE = 0x00000040,
175 
183 
190 
199 
206 
213 
215 
224 {
227  GList *user_splits;
240  const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
241 
246  const char *(*list_emblem)(PurpleBuddy *buddy);
247 
252  char *(*status_text)(PurpleBuddy *buddy);
253 
257  void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
258 
264  GList *(*status_types)(PurpleAccount *account);
265 
271  GList *(*blist_node_menu)(PurpleBlistNode *node);
272 
280  GList *(*chat_info)(PurpleConnection *);
281 
292  GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name);
293 
294  /* All the server-related functions */
295 
297  void (*login)(PurpleAccount *);
298 
301 
311  int (*send_im)(PurpleConnection *, const char *who,
312  const char *message,
313  PurpleMessageFlags flags);
314 
315  void (*set_info)(PurpleConnection *, const char *info);
316 
324  unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleTypingState state);
325 
330  void (*get_info)(PurpleConnection *, const char *who);
331  void (*set_status)(PurpleAccount *account, PurpleStatus *status);
332 
333  void (*set_idle)(PurpleConnection *, int idletime);
334  void (*change_passwd)(PurpleConnection *, const char *old_pass,
335  const char *new_pass);
347  void (*add_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
348  void (*add_buddies)(PurpleConnection *, GList *buddies, GList *groups);
349  void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
350  void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
351  void (*add_permit)(PurpleConnection *, const char *name);
352  void (*add_deny)(PurpleConnection *, const char *name);
353  void (*rem_permit)(PurpleConnection *, const char *name);
354  void (*rem_deny)(PurpleConnection *, const char *name);
355  void (*set_permit_deny)(PurpleConnection *);
356 
367  void (*join_chat)(PurpleConnection *, GHashTable *components);
368 
375  void (*reject_chat)(PurpleConnection *, GHashTable *components);
376 
384  char *(*get_chat_name)(GHashTable *components);
385 
394  void (*chat_invite)(PurpleConnection *, int id,
395  const char *message, const char *who);
401  void (*chat_leave)(PurpleConnection *, int id);
402 
410  void (*chat_whisper)(PurpleConnection *, int id,
411  const char *who, const char *message);
412 
430  int (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
431 
439 
442 
446  void (*get_cb_info)(PurpleConnection *, int, const char *who);
451  void (*get_cb_away)(PurpleConnection *, int, const char *who);
452 
454  void (*alias_buddy)(PurpleConnection *, const char *who,
455  const char *alias);
456 
458  void (*group_buddy)(PurpleConnection *, const char *who,
459  const char *old_group, const char *new_group);
460 
462  void (*rename_group)(PurpleConnection *, const char *old_name,
463  PurpleGroup *group, GList *moved_buddies);
464 
465  void (*buddy_free)(PurpleBuddy *);
466 
467  void (*convo_closed)(PurpleConnection *, const char *who);
468 
474  const char *(*normalize)(const PurpleAccount *, const char *who);
475 
482 
483  void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
484 
494  char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who);
495 
496  void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic);
497 
498  PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
499 
500  /* room listing prpl callbacks */
501  PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc);
502  void (*roomlist_cancel)(PurpleRoomlist *list);
503  void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category);
504 
505  /* file transfer callbacks */
506  gboolean (*can_receive_file)(PurpleConnection *, const char *who);
507  void (*send_file)(PurpleConnection *, const char *who, const char *filename);
508  PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who);
509 
514  gboolean (*offline_message)(const PurpleBuddy *buddy);
515 
516  PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
517 
519  int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
520 
521  /* room list serialize */
522  char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
523 
528  /* This is here rather than next to register_user for API compatibility
529  * reasons.
530  */
531  void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
532 
533  /* Attention API for sending & receiving zaps/nudges/buzzes etc. */
534  gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
535  GList *(*get_attention_types)(PurpleAccount *acct);
536 
541  unsigned long struct_size;
542 
543  /* NOTE:
544  * If more functions are added, they should accessed using the following syntax:
545  *
546  * if (PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, new_function))
547  * prpl->new_function(...);
548  *
549  * instead of
550  *
551  * if (prpl->new_function != NULL)
552  * prpl->new_function(...);
553  *
554  * The PURPLE_PROTOCOL_PLUGIN_HAS_FUNC macro can be used for the older member
555  * functions (e.g. login, send_im etc.) too.
556  */
557 
567  GHashTable *(*get_account_text_table)(PurpleAccount *account);
568 
577  gboolean (*initiate_media)(PurpleAccount *account, const char *who,
578  PurpleMediaSessionType type);
579 
587  PurpleMediaCaps (*get_media_caps)(PurpleAccount *account,
588  const char *who);
589 
595  PurpleMood *(*get_moods)(PurpleAccount *account);
596 
615  void (*set_public_alias)(PurpleConnection *gc, const char *alias,
616  PurpleSetPublicAliasSuccessCallback success_cb,
617  PurpleSetPublicAliasFailureCallback failure_cb);
633  PurpleGetPublicAliasSuccessCallback success_cb,
634  PurpleGetPublicAliasFailureCallback failure_cb);
635 
648  void (*add_buddy_with_invite)(PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message);
649  void (*add_buddies_with_invite)(PurpleConnection *pc, GList *buddies, GList *groups, const char *message);
650 };
651 
652 #define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) \
653  (((G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < G_STRUCT_OFFSET(PurplePluginProtocolInfo, struct_size)) \
654  || (G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size)) && \
655  prpl->member != NULL)
656 
657 
658 #define PURPLE_IS_PROTOCOL_PLUGIN(plugin) \
659  ((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)
660 
661 #define PURPLE_PLUGIN_PROTOCOL_INFO(plugin) \
662  ((PurplePluginProtocolInfo *)(plugin)->info->extra_info)
663 
664 #ifdef __cplusplus
665 extern "C" {
666 #endif
667 
668 /**************************************************************************/
670 /**************************************************************************/
686 PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
687  const char *inc_desc, const char *out_desc);
688 
698 void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
699 
709 
719 
728 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
729 
740 
748 const char *purple_attention_type_get_name(const PurpleAttentionType *type);
749 
758 
767 
777 
786 
789 /**************************************************************************/
791 /**************************************************************************/
803 void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle,
804  time_t idle_time);
805 
814 void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time);
815 
827  const char *status_id, ...) G_GNUC_NULL_TERMINATED;
828 
842 
856 void purple_prpl_got_user_idle(PurpleAccount *account, const char *name,
857  gboolean idle, time_t idle_time);
858 
868 void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name,
869  time_t login_time);
870 
882 void purple_prpl_got_user_status(PurpleAccount *account, const char *name,
883  const char *status_id, ...) G_GNUC_NULL_TERMINATED;
884 
894 void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name,
895  const char *status_id);
896 
906  PurpleStatus *old_status,
907  PurpleStatus *new_status);
908 
917 GList *purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence);
918 
933 void purple_prpl_send_attention(PurpleConnection *gc, const char *who, guint type_code);
934 
945 void purple_prpl_got_attention(PurpleConnection *gc, const char *who, guint type_code);
946 
958 void purple_prpl_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code);
959 
968 PurpleMediaCaps purple_prpl_get_media_caps(PurpleAccount *account,
969  const char *who);
970 
980 gboolean purple_prpl_initiate_media(PurpleAccount *account,
981  const char *who,
982  PurpleMediaSessionType type);
983 
993 void purple_prpl_got_media_caps(PurpleAccount *account, const char *who);
994 
997 /**************************************************************************/
999 /**************************************************************************/
1007 PurplePlugin *purple_find_prpl(const char *id);
1008 
1011 #ifdef __cplusplus
1012 }
1013 #endif
1014 
1015 #endif /* _PRPL_H_ */