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 
300  void (*close)(PurpleConnection *);
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 
429  int (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
430 
437  void (*keepalive)(PurpleConnection *);
438 
440  void (*register_user)(PurpleAccount *);
441 
445  void (*get_cb_info)(PurpleConnection *, int, const char *who);
450  void (*get_cb_away)(PurpleConnection *, int, const char *who);
451 
453  void (*alias_buddy)(PurpleConnection *, const char *who,
454  const char *alias);
455 
457  void (*group_buddy)(PurpleConnection *, const char *who,
458  const char *old_group, const char *new_group);
459 
461  void (*rename_group)(PurpleConnection *, const char *old_name,
462  PurpleGroup *group, GList *moved_buddies);
463 
464  void (*buddy_free)(PurpleBuddy *);
465 
466  void (*convo_closed)(PurpleConnection *, const char *who);
467 
473  const char *(*normalize)(const PurpleAccount *, const char *who);
474 
480  void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
481 
482  void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
483 
493  char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who);
494 
495  void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic);
496 
497  PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
498 
499  /* room listing prpl callbacks */
500  PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc);
501  void (*roomlist_cancel)(PurpleRoomlist *list);
502  void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category);
503 
504  /* file transfer callbacks */
505  gboolean (*can_receive_file)(PurpleConnection *, const char *who);
506  void (*send_file)(PurpleConnection *, const char *who, const char *filename);
507  PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who);
508 
513  gboolean (*offline_message)(const PurpleBuddy *buddy);
514 
515  PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
516 
518  int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
519 
520  /* room list serialize */
521  char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
522 
527  /* This is here rather than next to register_user for API compatibility
528  * reasons.
529  */
530  void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
531 
532  /* Attention API for sending & receiving zaps/nudges/buzzes etc. */
533  gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
534  GList *(*get_attention_types)(PurpleAccount *acct);
535 
540  unsigned long struct_size;
541 
542  /* NOTE:
543  * If more functions are added, they should accessed using the following syntax:
544  *
545  * if (PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, new_function))
546  * prpl->new_function(...);
547  *
548  * instead of
549  *
550  * if (prpl->new_function != NULL)
551  * prpl->new_function(...);
552  *
553  * The PURPLE_PROTOCOL_PLUGIN_HAS_FUNC macro can be used for the older member
554  * functions (e.g. login, send_im etc.) too.
555  */
556 
566  GHashTable *(*get_account_text_table)(PurpleAccount *account);
567 
576  gboolean (*initiate_media)(PurpleAccount *account, const char *who,
577  PurpleMediaSessionType type);
578 
586  PurpleMediaCaps (*get_media_caps)(PurpleAccount *account,
587  const char *who);
588 
594  PurpleMood *(*get_moods)(PurpleAccount *account);
595 
614  void (*set_public_alias)(PurpleConnection *gc, const char *alias,
615  PurpleSetPublicAliasSuccessCallback success_cb,
616  PurpleSetPublicAliasFailureCallback failure_cb);
631  void (*get_public_alias)(PurpleConnection *gc,
632  PurpleGetPublicAliasSuccessCallback success_cb,
633  PurpleGetPublicAliasFailureCallback failure_cb);
634 
647  void (*add_buddy_with_invite)(PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message);
648  void (*add_buddies_with_invite)(PurpleConnection *pc, GList *buddies, GList *groups, const char *message);
649 };
650 
651 #define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) \
652  (((G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < G_STRUCT_OFFSET(PurplePluginProtocolInfo, struct_size)) \
653  || (G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size)) && \
654  prpl->member != NULL)
655 
656 
657 #define PURPLE_IS_PROTOCOL_PLUGIN(plugin) \
658  ((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)
659 
660 #define PURPLE_PLUGIN_PROTOCOL_INFO(plugin) \
661  ((PurplePluginProtocolInfo *)(plugin)->info->extra_info)
662 
663 #ifdef __cplusplus
664 extern "C" {
665 #endif
666 
667 /**************************************************************************/
669 /**************************************************************************/
685 PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
686  const char *inc_desc, const char *out_desc);
687 
697 void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
698 
708 
718 
727 void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
728 
739 
747 const char *purple_attention_type_get_name(const PurpleAttentionType *type);
748 
757 
766 
776 
785 
788 /**************************************************************************/
790 /**************************************************************************/
802 void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle,
803  time_t idle_time);
804 
813 void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time);
814 
826  const char *status_id, ...) G_GNUC_NULL_TERMINATED;
827 
841 
855 void purple_prpl_got_user_idle(PurpleAccount *account, const char *name,
856  gboolean idle, time_t idle_time);
857 
867 void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name,
868  time_t login_time);
869 
881 void purple_prpl_got_user_status(PurpleAccount *account, const char *name,
882  const char *status_id, ...) G_GNUC_NULL_TERMINATED;
883 
893 void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name,
894  const char *status_id);
895 
905  PurpleStatus *old_status,
906  PurpleStatus *new_status);
907 
916 GList *purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence);
917 
932 void purple_prpl_send_attention(PurpleConnection *gc, const char *who, guint type_code);
933 
944 void purple_prpl_got_attention(PurpleConnection *gc, const char *who, guint type_code);
945 
957 void purple_prpl_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code);
958 
967 PurpleMediaCaps purple_prpl_get_media_caps(PurpleAccount *account,
968  const char *who);
969 
979 gboolean purple_prpl_initiate_media(PurpleAccount *account,
980  const char *who,
981  PurpleMediaSessionType type);
982 
992 void purple_prpl_got_media_caps(PurpleAccount *account, const char *who);
993 
996 /**************************************************************************/
998 /**************************************************************************/
1006 PurplePlugin *purple_find_prpl(const char *id);
1007 
1010 #ifdef __cplusplus
1011 }
1012 #endif
1013 
1014 #ifdef __COVERITY__
1015 #undef PURPLE_PROTOCOL_PLUGIN_HAS_FUNC
1016 #define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) (prpl->member != NULL)
1017 #endif
1018 
1019 #endif /* _PRPL_H_ */
Notification API.
const char * label
User-friendly name of the entry.
Definition: prpl.h:105
A group.
Definition: blist.h:167
PurpleMessageFlags
Flags applicable to a message.
Definition: conversation.h:105
PurpleAttentionType * purple_attention_type_new(const char *ulname, const char *name, const char *inc_desc, const char *out_desc)
Creates a new PurpleAttentionType object and sets its mandatory parameters.
const char * purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type)
Get the attention type&#39;s description shown when the event is sent.
PurpleProtocolOptions
Protocol options.
Definition: prpl.h:136
size_t max_filesize
Maximum size in bytes.
Definition: prpl.h:97
A Buddy list node.
Definition: blist.h:124
Room List API.
File Transfer API.
void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name, const char *status_id)
Notifies libpurple that a buddy&#39;s status has been deactivated.
Conversation API.
PurpleMediaCaps purple_prpl_get_media_caps(PurpleAccount *account, const char *who)
Determines if the contact supports the given media session type.
struct _PurpleStoredImage PurpleStoredImage
A set of utility functions that provide a reference-counted immutable wrapper around an image&#39;s data ...
Definition: imgstore.h:37
void purple_prpl_got_media_caps(PurpleAccount *account, const char *who)
Signals that the prpl received capabilities for the given contact.
GList * user_splits
A GList of PurpleAccountUserSplit.
Definition: prpl.h:227
void purple_prpl_got_account_status(PurpleAccount *account, const char *status_id,...) G_GNUC_NULL_TERMINATED
Notifies Purple that our account&#39;s status has changed.
Plugin API.
Media API.
const char * purple_attention_type_get_name(const PurpleAttentionType *type)
Get the attention type&#39;s name as displayed by the UI.
unsigned long struct_size
The size of the PurplePluginProtocolInfo.
Definition: prpl.h:540
const char * name
Shown in GUI elements.
Definition: prpl.h:119
void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name, time_t login_time)
Notifies Purple of a buddy&#39;s log-in time.
const char * purple_attention_type_get_icon_name(const PurpleAttentionType *type)
Get the attention type&#39;s icon name.
Structure representing an account.
Definition: account.h:126
Notify on new mail.
Definition: prpl.h:167
void purple_prpl_send_attention(PurpleConnection *gc, const char *who, guint type_code)
Send an attention request message.
A plugin handle.
Definition: plugin.h:151
void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc)
Sets the description of the attention-demanding event shown in conversations when the event is sent...
void purple_prpl_got_attention(PurpleConnection *gc, const char *who, guint type_code)
Process an incoming attention message.
We scale the icon when we display it.
Definition: prpl.h:42
Set the Register button active even when the username has not been specified.
Definition: prpl.h:198
PurpleTypingState
The typing state of a user.
Definition: conversation.h:94
void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time)
Notifies Purple of our account&#39;s log-in time.
PurpleProtocolOptions options
Protocol options.
Definition: prpl.h:225
void purple_prpl_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code)
Process an incoming attention message in a chat.
gboolean required
True if it&#39;s required.
Definition: prpl.h:107
Buddy List API.
gboolean purple_prpl_initiate_media(PurpleAccount *account, const char *who, PurpleMediaSessionType type)
Initiates a media session with the given contact.
Allow passwords to be optional.
Definition: prpl.h:182
void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle, time_t idle_time)
Notifies Purple that our account&#39;s idle state and time have changed.
A protocol plugin information structure.
Definition: prpl.h:223
We scale the icon before we send it to the server.
Definition: prpl.h:43
Represents an entry containing information that must be supplied by the user when joining a chat...
Definition: prpl.h:104
Don&#39;t require passwords for sign-in.
Definition: prpl.h:160
int max_height
Maximum height of this icon.
Definition: prpl.h:96
Indicates that slash commands are native to this protocol.
Definition: prpl.h:205
Represents "nudges" and "buzzes" that you may send to a buddy to attract their attention (or vice-ver...
Definition: prpl.h:117
Images in IMs.
Definition: prpl.h:174
PurpleBuddyIconSpec icon_spec
The icon spec.
Definition: prpl.h:230
const char * purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type)
Get the attention type&#39;s unlocalized name; this is useful for some UIs.
const char * incoming_description
Shown when sent.
Definition: prpl.h:120
PurpleIconScaleRules
Definition: prpl.h:41
A chat.
Definition: blist.h:179
PurpleWhiteboard PRPL Operations.
Definition: whiteboard.h:78
PurplePlugin * purple_find_prpl(const char *id)
Finds a protocol plugin structure of the specified type.
void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc)
Sets the description of the attention-demanding event shown in conversations when the event is receiv...
GList * protocol_options
A GList of PurpleAccountOption.
Definition: prpl.h:228
const char * icon_name
Icon to display (optional)
Definition: prpl.h:122
char * format
This is a comma-delimited list of image formats or NULL if icons are not supported.
Definition: prpl.h:91
Proxy API.
Indicates that this protocol supports sending a user-supplied message along with an invitation...
Definition: prpl.h:212
int max_width
Maximum width of this icon.
Definition: prpl.h:95
int max
Maximum value in case of integer.
Definition: prpl.h:110
int min
Minimum value in case of integer.
Definition: prpl.h:109
Status APIA brief explanation of the status API:
GList * purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence)
Retrieves the list of stock status types from a prpl.
PurpleIconScaleRules scale_rules
How to stretch this icon.
Definition: prpl.h:98
void purple_prpl_change_account_status(PurpleAccount *account, PurpleStatus *old_status, PurpleStatus *new_status)
Informs the server that our account&#39;s status changed.
A description of a Buddy Icon specification.
Definition: prpl.h:85
void purple_prpl_got_user_status(PurpleAccount *account, const char *name, const char *status_id,...) G_GNUC_NULL_TERMINATED
Notifies Purple that a buddy&#39;s status has been activated.
int min_width
Minimum width of this icon.
Definition: prpl.h:93
User names are unique to a chat and are not shared between rooms.
Definition: prpl.h:145
The PurpleWhiteboard core object.
Data Structures.
Definition: roomlist.h:69
void purple_attention_type_set_name(PurpleAttentionType *type, const char *name)
Sets the displayed name of the attention-demanding event.
IM Image Store API.
const char * purple_attention_type_get_incoming_desc(const PurpleAttentionType *type)
Get the attention type&#39;s description shown when the event is received.
A buddy.
Definition: blist.h:138
gboolean secret
True if the entry is secret (password)
Definition: prpl.h:111
const char * outgoing_description
Shown when receied.
Definition: prpl.h:121
int min_height
Minimum height of this icon.
Definition: prpl.h:94
const char * unlocalized_name
Unlocalized name for UIs needing it.
Definition: prpl.h:123
Represents a room.
Definition: roomlist.h:82
void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname)
Sets the unlocalized name of the attention event; some UIs may need this, thus it is required...
Allows font size to be specified in sane point size.
Definition: prpl.h:189
void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name)
Sets the name of the icon to display for the attention event; this is optional.
Chat rooms have topics.
Definition: prpl.h:152
void purple_prpl_got_user_idle(PurpleAccount *account, const char *name, gboolean idle, time_t idle_time)
Notifies Purple that a buddy&#39;s idle state and time have changed.
struct _PurpleThumbnailSpec PurpleThumbnailSpec
A description of a file transfer thumbnail specification.
Definition: prpl.h:59
gboolean is_int
True if the entry expects an integer.
Definition: prpl.h:108
A core representation of a file transfer.
Definition: ft.h:134
void purple_prpl_got_account_actions(PurpleAccount *account)
Notifies Purple that our account&#39;s actions have changed.
const char * identifier
Used by the PRPL to identify the option.
Definition: prpl.h:106