prpl.h

Go to the documentation of this file.

 
/* purple
 *
 * Purple is the legal property of its developers, whose names are too numerous
 * to list here.  Please refer to the COPYRIGHT file distributed with this
 * source distribution.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
 */
 
/* this file should be all that prpls need to include. therefore, by including
 * this file, they should get glib, proxy, purple_connection, prpl, etc. */
 
#ifndef _PURPLE_PRPL_H_
#define _PURPLE_PRPL_H_
 
typedef struct _PurplePluginProtocolInfo PurplePluginProtocolInfo;
typedef struct _PurpleAttentionType PurpleAttentionType;
 
/**************************************************************************/
/**************************************************************************/
 
typedef enum {
    PURPLE_ICON_SCALE_DISPLAY = 0x01,       
    PURPLE_ICON_SCALE_SEND = 0x02           
} PurpleIconScaleRules;
 
 
typedef struct _PurpleBuddyIconSpec PurpleBuddyIconSpec;
 
typedef struct _PurpleThumbnailSpec PurpleThumbnailSpec;
 
#define NO_BUDDY_ICONS {NULL, 0, 0, 0, 0, 0, 0}
 
#ifdef HAVE_UNISTD_H
#include <unistd.h>
#endif
 
#include "blist.h"
#include "conversation.h"
#include "ft.h"
#include "imgstore.h"
#include "media.h"
#include "notify.h"
#include "proxy.h"
#include "plugin.h"
#include "roomlist.h"
#include "status.h"
#include "whiteboard.h"
 
 
struct _PurpleBuddyIconSpec {
    char *format;
 
    int min_width;                     
    int min_height;                    
    int max_width;                     
    int max_height;                    
    size_t max_filesize;               
    PurpleIconScaleRules scale_rules;  
};
 
struct proto_chat_entry {
    const char *label;       
    const char *identifier;  
    gboolean required;       
    gboolean is_int;         
    int min;                 
    int max;                 
    gboolean secret;         
};
 
struct _PurpleAttentionType
{
    const char *name;                  
    const char *incoming_description;  
    const char *outgoing_description;  
    const char *icon_name;             
    const char *unlocalized_name;      
    /* Reserved fields for future purposes */
    gpointer _reserved2;
    gpointer _reserved3;
    gpointer _reserved4;
};
 
typedef enum
{
    OPT_PROTO_UNIQUE_CHATNAME = 0x00000004,
 
    OPT_PROTO_CHAT_TOPIC = 0x00000008,
 
    OPT_PROTO_NO_PASSWORD = 0x00000010,
 
    OPT_PROTO_MAIL_CHECK = 0x00000020,
 
    OPT_PROTO_IM_IMAGE = 0x00000040,
 
    OPT_PROTO_PASSWORD_OPTIONAL = 0x00000080,
 
    OPT_PROTO_USE_POINTSIZE = 0x00000100,
 
    OPT_PROTO_REGISTER_NOSCREENNAME = 0x00000200,
 
    OPT_PROTO_SLASH_COMMANDS_NATIVE = 0x00000400,
 
    OPT_PROTO_INVITE_MESSAGE = 0x00000800,
 
    OPT_PROTO_TRANSIENT_BUDDIES = 0x00001000,
 
} PurpleProtocolOptions;
 
struct _PurplePluginProtocolInfo
{
    PurpleProtocolOptions options;  
    GList *user_splits;      
    GList *protocol_options; 
    PurpleBuddyIconSpec icon_spec; 
    const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
 
    const char *(*list_emblem)(PurpleBuddy *buddy);
 
    char *(*status_text)(PurpleBuddy *buddy);
 
    void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
 
    GList *(*status_types)(PurpleAccount *account);
 
    GList *(*blist_node_menu)(PurpleBlistNode *node);
 
    GList *(*chat_info)(PurpleConnection *);
 
    GHashTable *(*chat_info_defaults)(PurpleConnection *, const char *chat_name);
 
    /* All the server-related functions */
 
    void (*login)(PurpleAccount *);
 
    void (*close)(PurpleConnection *);
 
    int  (*send_im)(PurpleConnection *, const char *who,
                    const char *message,
                    PurpleMessageFlags flags);
 
    void (*set_info)(PurpleConnection *, const char *info);
 
    unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleTypingState state);
 
    void (*get_info)(PurpleConnection *, const char *who);
    void (*set_status)(PurpleAccount *account, PurpleStatus *status);
 
    void (*set_idle)(PurpleConnection *, int idletime);
    void (*change_passwd)(PurpleConnection *, const char *old_pass,
                          const char *new_pass);
    void (*add_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
    void (*add_buddies)(PurpleConnection *, GList *buddies, GList *groups);
    void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy, PurpleGroup *group);
    void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
    void (*add_permit)(PurpleConnection *, const char *name);
    void (*add_deny)(PurpleConnection *, const char *name);
    void (*rem_permit)(PurpleConnection *, const char *name);
    void (*rem_deny)(PurpleConnection *, const char *name);
    void (*set_permit_deny)(PurpleConnection *);
 
    void (*join_chat)(PurpleConnection *, GHashTable *components);
 
    void (*reject_chat)(PurpleConnection *, GHashTable *components);
 
    char *(*get_chat_name)(GHashTable *components);
 
    void (*chat_invite)(PurpleConnection *, int id,
                        const char *message, const char *who);
    void (*chat_leave)(PurpleConnection *, int id);
 
    void (*chat_whisper)(PurpleConnection *, int id,
                         const char *who, const char *message);
 
    int  (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
 
    void (*keepalive)(PurpleConnection *);
 
    void (*register_user)(PurpleAccount *);
 
    void (*get_cb_info)(PurpleConnection *, int, const char *who);
    void (*get_cb_away)(PurpleConnection *, int, const char *who);
 
    void (*alias_buddy)(PurpleConnection *, const char *who,
                        const char *alias);
 
    void (*group_buddy)(PurpleConnection *, const char *who,
                        const char *old_group, const char *new_group);
 
    void (*rename_group)(PurpleConnection *, const char *old_name,
                         PurpleGroup *group, GList *moved_buddies);
 
    void (*buddy_free)(PurpleBuddy *);
 
    void (*convo_closed)(PurpleConnection *, const char *who);
 
    const char *(*normalize)(const PurpleAccount *, const char *who);
 
    void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
 
    void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
 
    char *(*get_cb_real_name)(PurpleConnection *gc, int id, const char *who);
 
    void (*set_chat_topic)(PurpleConnection *gc, int id, const char *topic);
 
    PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
 
    /* room listing prpl callbacks */
    PurpleRoomlist *(*roomlist_get_list)(PurpleConnection *gc);
    void (*roomlist_cancel)(PurpleRoomlist *list);
    void (*roomlist_expand_category)(PurpleRoomlist *list, PurpleRoomlistRoom *category);
 
    /* file transfer callbacks */
    gboolean (*can_receive_file)(PurpleConnection *, const char *who);
    void (*send_file)(PurpleConnection *, const char *who, const char *filename);
    PurpleXfer *(*new_xfer)(PurpleConnection *, const char *who);
 
    gboolean (*offline_message)(const PurpleBuddy *buddy);
 
    PurpleWhiteboardPrplOps *whiteboard_prpl_ops;
 
    int (*send_raw)(PurpleConnection *gc, const char *buf, int len);
 
    /* room list serialize */
    char *(*roomlist_room_serialize)(PurpleRoomlistRoom *room);
 
    /* This is here rather than next to register_user for API compatibility
     * reasons.
     */
    void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb, void *user_data);
 
    /* Attention API for sending & receiving zaps/nudges/buzzes etc. */
    gboolean (*send_attention)(PurpleConnection *gc, const char *username, guint type);
    GList *(*get_attention_types)(PurpleAccount *acct);
 
    unsigned long struct_size;
 
    /* NOTE:
     * If more functions are added, they should accessed using the following syntax:
     *
     *      if (PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, new_function))
     *          prpl->new_function(...);
     *
     * instead of
     *
     *      if (prpl->new_function != NULL)
     *          prpl->new_function(...);
     *
     * The PURPLE_PROTOCOL_PLUGIN_HAS_FUNC macro can be used for the older member
     * functions (e.g. login, send_im etc.) too.
     */
 
    GHashTable *(*get_account_text_table)(PurpleAccount *account);
 
    gboolean (*initiate_media)(PurpleAccount *account, const char *who,
                    PurpleMediaSessionType type);
 
    PurpleMediaCaps (*get_media_caps)(PurpleAccount *account,
                      const char *who);
 
    PurpleMood *(*get_moods)(PurpleAccount *account);
 
    void (*set_public_alias)(PurpleConnection *gc, const char *alias,
                             PurpleSetPublicAliasSuccessCallback success_cb,
                             PurpleSetPublicAliasFailureCallback failure_cb);
    void (*get_public_alias)(PurpleConnection *gc,
                             PurpleGetPublicAliasSuccessCallback success_cb,
                             PurpleGetPublicAliasFailureCallback failure_cb);
 
    void (*add_buddy_with_invite)(PurpleConnection *pc, PurpleBuddy *buddy, PurpleGroup *group, const char *message);
    void (*add_buddies_with_invite)(PurpleConnection *pc, GList *buddies, GList *groups, const char *message);
 
    char *(*get_cb_alias)(PurpleConnection *gc, int id, const char *who);
 
 
    gboolean (*chat_can_receive_file)(PurpleConnection *, int id);
 
    void (*chat_send_file)(PurpleConnection *, int id, const char *filename);
 
};
 
#define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) \
    (((G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < G_STRUCT_OFFSET(PurplePluginProtocolInfo, struct_size)) \
      || (G_STRUCT_OFFSET(PurplePluginProtocolInfo, member) < prpl->struct_size)) && \
     prpl->member != NULL)
 
 
#define PURPLE_IS_PROTOCOL_PLUGIN(plugin) \
    ((plugin)->info->type == PURPLE_PLUGIN_PROTOCOL)
 
#define PURPLE_PLUGIN_PROTOCOL_INFO(plugin) \
    ((PurplePluginProtocolInfo *)(plugin)->info->extra_info)
 
#ifdef __cplusplus
extern "C" {
#endif
 
/**************************************************************************/
/**************************************************************************/
PurpleAttentionType *purple_attention_type_new(const char *ulname, const char *name,
                                const char *inc_desc, const char *out_desc);
 
void purple_attention_type_set_name(PurpleAttentionType *type, const char *name);
 
void purple_attention_type_set_incoming_desc(PurpleAttentionType *type, const char *desc);
 
void purple_attention_type_set_outgoing_desc(PurpleAttentionType *type, const char *desc);
 
void purple_attention_type_set_icon_name(PurpleAttentionType *type, const char *name);
 
void purple_attention_type_set_unlocalized_name(PurpleAttentionType *type, const char *ulname);
 
const char *purple_attention_type_get_name(const PurpleAttentionType *type);
 
const char *purple_attention_type_get_incoming_desc(const PurpleAttentionType *type);
 
const char *purple_attention_type_get_outgoing_desc(const PurpleAttentionType *type);
 
const char *purple_attention_type_get_icon_name(const PurpleAttentionType *type);
 
const char *purple_attention_type_get_unlocalized_name(const PurpleAttentionType *type);
 
/**************************************************************************/
/**************************************************************************/
void purple_prpl_got_account_idle(PurpleAccount *account, gboolean idle,
                                time_t idle_time);
 
void purple_prpl_got_account_login_time(PurpleAccount *account, time_t login_time);
 
void purple_prpl_got_account_status(PurpleAccount *account,
                                  const char *status_id, ...) G_GNUC_NULL_TERMINATED;
 
void purple_prpl_got_account_actions(PurpleAccount *account);
 
void purple_prpl_got_user_idle(PurpleAccount *account, const char *name,
                             gboolean idle, time_t idle_time);
 
void purple_prpl_got_user_login_time(PurpleAccount *account, const char *name,
                                   time_t login_time);
 
void purple_prpl_got_user_status(PurpleAccount *account, const char *name,
                               const char *status_id, ...) G_GNUC_NULL_TERMINATED;
 
void purple_prpl_got_user_status_deactive(PurpleAccount *account, const char *name,
                    const char *status_id);
 
void purple_prpl_change_account_status(PurpleAccount *account,
                                     PurpleStatus *old_status,
                                     PurpleStatus *new_status);
 
GList *purple_prpl_get_statuses(PurpleAccount *account, PurplePresence *presence);
 
void purple_prpl_send_attention(PurpleConnection *gc, const char *who, guint type_code);
 
void purple_prpl_got_attention(PurpleConnection *gc, const char *who, guint type_code);
 
void purple_prpl_got_attention_in_chat(PurpleConnection *gc, int id, const char *who, guint type_code);
 
PurpleMediaCaps purple_prpl_get_media_caps(PurpleAccount *account,
                  const char *who);
 
gboolean purple_prpl_initiate_media(PurpleAccount *account,
                    const char *who,
                    PurpleMediaSessionType type);
 
void purple_prpl_got_media_caps(PurpleAccount *account, const char *who);
 
/**************************************************************************/
/**************************************************************************/
PurplePlugin *purple_find_prpl(const char *id);
 
#ifdef __cplusplus
}
#endif
 
#ifdef __COVERITY__
#undef PURPLE_PROTOCOL_PLUGIN_HAS_FUNC
#define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) (prpl->member != NULL)
#endif
 
#endif /* _PRPL_H_ */