blist.h

Go to the documentation of this file.
00001 
00007 /* purple
00008  *
00009  * Purple is the legal property of its developers, whose names are too numerous
00010  * to list here.  Please refer to the COPYRIGHT file distributed with this
00011  * source distribution.
00012  *
00013  * This program is free software; you can redistribute it and/or modify
00014  * it under the terms of the GNU General Public License as published by
00015  * the Free Software Foundation; either version 2 of the License, or
00016  * (at your option) any later version.
00017  *
00018  * This program is distributed in the hope that it will be useful,
00019  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00020  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00021  * GNU General Public License for more details.
00022  *
00023  * You should have received a copy of the GNU General Public License
00024  * along with this program; if not, write to the Free Software
00025  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
00026  */
00027 #ifndef _PURPLE_BLIST_H_
00028 #define _PURPLE_BLIST_H_
00029 
00030 /* I can't believe I let ChipX86 inspire me to write good code. -Sean */
00031 
00032 #include <glib.h>
00033 
00035 typedef struct _PurpleBuddyList PurpleBuddyList;
00037 typedef struct _PurpleBlistUiOps PurpleBlistUiOps;
00039 typedef struct _PurpleBlistNode PurpleBlistNode;
00040 
00042 typedef struct _PurpleChat PurpleChat;
00044 typedef struct _PurpleGroup PurpleGroup;
00046 typedef struct _PurpleContact PurpleContact;
00048 typedef struct _PurpleBuddy PurpleBuddy;
00049 
00050 /**************************************************************************/
00051 /* Enumerations                                                           */
00052 /**************************************************************************/
00053 typedef enum
00054 {
00055     PURPLE_BLIST_GROUP_NODE,
00056     PURPLE_BLIST_CONTACT_NODE,
00057     PURPLE_BLIST_BUDDY_NODE,
00058     PURPLE_BLIST_CHAT_NODE,
00059     PURPLE_BLIST_OTHER_NODE
00060 
00061 } PurpleBlistNodeType;
00062 
00063 #define PURPLE_BLIST_NODE_IS_CHAT(n)    (purple_blist_node_get_type(n) == PURPLE_BLIST_CHAT_NODE)
00064 #define PURPLE_BLIST_NODE_IS_BUDDY(n)   (purple_blist_node_get_type(n) == PURPLE_BLIST_BUDDY_NODE)
00065 #define PURPLE_BLIST_NODE_IS_CONTACT(n) (purple_blist_node_get_type(n) == PURPLE_BLIST_CONTACT_NODE)
00066 #define PURPLE_BLIST_NODE_IS_GROUP(n)   (purple_blist_node_get_type(n) == PURPLE_BLIST_GROUP_NODE)
00067 
00068 #define PURPLE_BUDDY_IS_ONLINE(b) \
00069     ((b) != NULL && purple_account_is_connected(purple_buddy_get_account(b)) && \
00070      purple_presence_is_online(purple_buddy_get_presence(b)))
00071 
00072 typedef enum
00073 {
00074     PURPLE_BLIST_NODE_FLAG_NO_SAVE      = 1 << 0 
00076 } PurpleBlistNodeFlags;
00077 
00081 #define PURPLE_BLIST_NODE(obj) ((PurpleBlistNode *)(obj))
00082 
00083 #define PURPLE_BLIST_NODE_HAS_FLAG(b, f) (purple_blist_node_get_flags((PurpleBlistNode*)(b)) & (f))
00084 #define PURPLE_BLIST_NODE_SHOULD_SAVE(b) (! PURPLE_BLIST_NODE_HAS_FLAG(b, PURPLE_BLIST_NODE_FLAG_NO_SAVE))
00085 
00086 #define PURPLE_BLIST_NODE_NAME(n) (purple_blist_node_get_type(n) == PURPLE_BLIST_CHAT_NODE  ? purple_chat_get_name((PurpleChat*)n) :        \
00087                      purple_blist_node_get_type(n) == PURPLE_BLIST_BUDDY_NODE ? purple_buddy_get_name((PurpleBuddy*)n) : NULL)
00088 
00092 #define PURPLE_GROUP(obj) ((PurpleGroup *)(obj))
00093 
00097 #define PURPLE_CONTACT(obj) ((PurpleContact *)(obj))
00098 
00102 #define PURPLE_BUDDY(obj) ((PurpleBuddy *)(obj))
00103 
00107 #define PURPLE_CHAT(obj) ((PurpleChat *)(obj))
00108 
00109 #include "account.h"
00110 #include "buddyicon.h"
00111 #include "media.h"
00112 #include "status.h"
00113 
00114 /**************************************************************************/
00115 /* Data Structures                                                        */
00116 /**************************************************************************/
00117 
00118 #if !(defined PURPLE_HIDE_STRUCTS) || (defined _PURPLE_BLIST_C_)
00119 
00124 struct _PurpleBlistNode {
00125     PurpleBlistNodeType type;             
00126     PurpleBlistNode *prev;                
00127     PurpleBlistNode *next;                
00128     PurpleBlistNode *parent;              
00129     PurpleBlistNode *child;               
00130     GHashTable *settings;               
00131     void          *ui_data;             
00132     PurpleBlistNodeFlags flags;           
00133 };
00134 
00138 struct _PurpleBuddy {
00139     PurpleBlistNode node;                     
00140     char *name;                             
00141     char *alias;                            
00142     char *server_alias;                     
00143     void *proto_data;                       
00144     PurpleBuddyIcon *icon;                    
00145     PurpleAccount *account;                 
00146     PurplePresence *presence;
00147     PurpleMediaCaps media_caps;     
00148 };
00149 
00153 struct _PurpleContact {
00154     PurpleBlistNode node;       
00155     char *alias;            
00156     int totalsize;          
00157     int currentsize;        
00158     int online;             
00159     PurpleBuddy *priority;    
00160     gboolean priority_valid; 
00161 };
00162 
00163 
00167 struct _PurpleGroup {
00168     PurpleBlistNode node;                    
00169     char *name;                            
00170     int totalsize;                 
00171     int currentsize;               
00172     int online;                
00173 };
00174 
00179 struct _PurpleChat {
00180     PurpleBlistNode node;      
00181     char *alias;             
00182     GHashTable *components;  
00183     PurpleAccount *account; 
00184 };
00185 
00189 struct _PurpleBuddyList {
00190     PurpleBlistNode *root;          
00191     GHashTable *buddies;          
00192     void *ui_data;                
00193 };
00194 
00195 #endif /* PURPLE_HIDE_STRUCTS && PURPLE_BLIST_STRUCTS */
00196 
00203 struct _PurpleBlistUiOps
00204 {
00205     void (*new_list)(PurpleBuddyList *list); 
00206     void (*new_node)(PurpleBlistNode *node); 
00207     void (*show)(PurpleBuddyList *list);     
00208     void (*update)(PurpleBuddyList *list,
00209                PurpleBlistNode *node);       
00210     void (*remove)(PurpleBuddyList *list,
00211                PurpleBlistNode *node);       
00212     void (*destroy)(PurpleBuddyList *list);  
00213     void (*set_visible)(PurpleBuddyList *list,
00214                 gboolean show);            
00215     void (*request_add_buddy)(PurpleAccount *account, const char *username,
00216                               const char *group, const char *alias);
00217     void (*request_add_chat)(PurpleAccount *account, PurpleGroup *group,
00218                              const char *alias, const char *name);
00219     void (*request_add_group)(void);
00220 
00232     void (*save_node)(PurpleBlistNode *node);
00233 
00246     void (*remove_node)(PurpleBlistNode *node);
00247 
00261     void (*save_account)(PurpleAccount *account);
00262 
00263     void (*_purple_reserved1)(void);
00264 };
00265 
00266 #ifdef __cplusplus
00267 extern "C" {
00268 #endif
00269 
00270 /**************************************************************************/
00272 /**************************************************************************/
00281 PurpleBuddyList *purple_blist_new(void);
00282 
00289 void purple_set_blist(PurpleBuddyList *blist);
00290 
00296 PurpleBuddyList *purple_get_blist(void);
00297 
00303 PurpleBlistNode *purple_blist_get_root(void);
00304 
00316 GSList *purple_blist_get_buddies(void);
00317 
00325 gpointer purple_blist_get_ui_data(void);
00326 
00334 void purple_blist_set_ui_data(gpointer ui_data);
00335 
00348 PurpleBlistNode *purple_blist_node_next(PurpleBlistNode *node, gboolean offline);
00349 
00361 PurpleBlistNode *purple_blist_node_get_parent(PurpleBlistNode *node);
00362 
00374 PurpleBlistNode *purple_blist_node_get_first_child(PurpleBlistNode *node);
00375 
00387 PurpleBlistNode *purple_blist_node_get_sibling_next(PurpleBlistNode *node);
00388 
00400 PurpleBlistNode *purple_blist_node_get_sibling_prev(PurpleBlistNode *node);
00401 
00409 gpointer purple_blist_node_get_ui_data(const PurpleBlistNode *node);
00410 
00419 void purple_blist_node_set_ui_data(PurpleBlistNode *node, gpointer ui_data);
00420 
00424 void purple_blist_show(void);
00425 
00426 
00434 void purple_blist_destroy(void);
00435 
00441 void purple_blist_set_visible(gboolean show);
00442 
00451 void purple_blist_update_buddy_status(PurpleBuddy *buddy, PurpleStatus *old_status);
00452 
00460 void purple_blist_update_node_icon(PurpleBlistNode *node);
00461 
00462 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_BLIST_C_)
00463 
00469 void purple_blist_update_buddy_icon(PurpleBuddy *buddy);
00470 #endif
00471 
00478 void purple_blist_rename_buddy(PurpleBuddy *buddy, const char *name);
00479 
00486 void purple_blist_alias_contact(PurpleContact *contact, const char *alias);
00487 
00494 void purple_blist_alias_buddy(PurpleBuddy *buddy, const char *alias);
00495 
00503 void purple_blist_server_alias_buddy(PurpleBuddy *buddy, const char *alias);
00504 
00511 void purple_blist_alias_chat(PurpleChat *chat, const char *alias);
00512 
00519 void purple_blist_rename_group(PurpleGroup *group, const char *name);
00520 
00531 PurpleChat *purple_chat_new(PurpleAccount *account, const char *alias, GHashTable *components);
00532 
00538 void purple_chat_destroy(PurpleChat *chat);
00539 
00551 void purple_blist_add_chat(PurpleChat *chat, PurpleGroup *group, PurpleBlistNode *node);
00552 
00568 PurpleBuddy *purple_buddy_new(PurpleAccount *account, const char *name, const char *alias);
00569 
00575 void purple_buddy_destroy(PurpleBuddy *buddy);
00576 
00588 void purple_buddy_set_icon(PurpleBuddy *buddy, PurpleBuddyIcon *icon);
00589 
00597 PurpleAccount *purple_buddy_get_account(const PurpleBuddy *buddy);
00598 
00606 const char *purple_buddy_get_name(const PurpleBuddy *buddy);
00607 
00615 PurpleBuddyIcon *purple_buddy_get_icon(const PurpleBuddy *buddy);
00616 
00628 gpointer purple_buddy_get_protocol_data(const PurpleBuddy *buddy);
00629 
00641 void purple_buddy_set_protocol_data(PurpleBuddy *buddy, gpointer data);
00642 
00650 PurpleContact *purple_buddy_get_contact(PurpleBuddy *buddy);
00651 
00659 PurplePresence *purple_buddy_get_presence(const PurpleBuddy *buddy);
00660 
00669 PurpleMediaCaps purple_buddy_get_media_caps(const PurpleBuddy *buddy);
00670 
00677 void purple_buddy_set_media_caps(PurpleBuddy *buddy, PurpleMediaCaps media_caps);
00678 
00692 void purple_blist_add_buddy(PurpleBuddy *buddy, PurpleContact *contact, PurpleGroup *group, PurpleBlistNode *node);
00693 
00703 PurpleGroup *purple_group_new(const char *name);
00704 
00710 void purple_group_destroy(PurpleGroup *group);
00711 
00721 void purple_blist_add_group(PurpleGroup *group, PurpleBlistNode *node);
00722 
00728 PurpleContact *purple_contact_new(void);
00729 
00735 void purple_contact_destroy(PurpleContact *contact);
00736 
00745 PurpleGroup *purple_contact_get_group(const PurpleContact *contact);
00746 
00757 void purple_blist_add_contact(PurpleContact *contact, PurpleGroup *group, PurpleBlistNode *node);
00758 
00767 void purple_blist_merge_contact(PurpleContact *source, PurpleBlistNode *node);
00768 
00775 PurpleBuddy *purple_contact_get_priority_buddy(PurpleContact *contact);
00776 
00777 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_BLIST_C_)
00778 
00786 void purple_contact_set_alias(PurpleContact *contact, const char *alias);
00787 #endif
00788 
00795 const char *purple_contact_get_alias(PurpleContact *contact);
00796 
00805 gboolean purple_contact_on_account(PurpleContact *contact, PurpleAccount *account);
00806 
00813 void purple_contact_invalidate_priority_buddy(PurpleContact *contact);
00814 
00823 void purple_blist_remove_buddy(PurpleBuddy *buddy);
00824 
00834 void purple_blist_remove_contact(PurpleContact *contact);
00835 
00841 void purple_blist_remove_chat(PurpleChat *chat);
00842 
00849 void purple_blist_remove_group(PurpleGroup *group);
00850 
00858 const char *purple_buddy_get_alias_only(PurpleBuddy *buddy);
00859 
00866 const char *purple_buddy_get_server_alias(PurpleBuddy *buddy);
00867 
00877 const char *purple_buddy_get_contact_alias(PurpleBuddy *buddy);
00878 
00879 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_BLIST_C_)
00880 
00889 const char *purple_buddy_get_local_alias(PurpleBuddy *buddy);
00890 #endif
00891 
00900 const char *purple_buddy_get_alias(PurpleBuddy *buddy);
00901 
00910 const char *purple_buddy_get_local_buddy_alias(PurpleBuddy *buddy);
00911 
00918 const char *purple_chat_get_name(PurpleChat *chat);
00919 
00927 PurpleBuddy *purple_find_buddy(PurpleAccount *account, const char *name);
00928 
00937 PurpleBuddy *purple_find_buddy_in_group(PurpleAccount *account, const char *name,
00938         PurpleGroup *group);
00939 
00948 GSList *purple_find_buddies(PurpleAccount *account, const char *name);
00949 
00950 
00957 PurpleGroup *purple_find_group(const char *name);
00958 
00967 PurpleChat *purple_blist_find_chat(PurpleAccount *account, const char *name);
00968 
00976 PurpleGroup *purple_chat_get_group(PurpleChat *chat);
00977 
00987 PurpleAccount *purple_chat_get_account(PurpleChat *chat);
00988 
00998 GHashTable *purple_chat_get_components(PurpleChat *chat);
00999 
01006 PurpleGroup *purple_buddy_get_group(PurpleBuddy *buddy);
01007 
01008 
01017 GSList *purple_group_get_accounts(PurpleGroup *g);
01018 
01027 gboolean purple_group_on_account(PurpleGroup *g, PurpleAccount *account);
01028 
01036 const char *purple_group_get_name(PurpleGroup *group);
01037 
01044 void purple_blist_add_account(PurpleAccount *account);
01045 
01046 
01053 void purple_blist_remove_account(PurpleAccount *account);
01054 
01055 
01063 int purple_blist_get_group_size(PurpleGroup *group, gboolean offline);
01064 
01071 int purple_blist_get_group_online_count(PurpleGroup *group);
01072 
01075 /****************************************************************************************/
01077 /****************************************************************************************/
01078 
01082 void purple_blist_load(void);
01083 
01091 void purple_blist_schedule_save(void);
01092 
01102 void purple_blist_request_add_buddy(PurpleAccount *account, const char *username,
01103                                   const char *group, const char *alias);
01104 
01114 void purple_blist_request_add_chat(PurpleAccount *account, PurpleGroup *group,
01115                                  const char *alias, const char *name);
01116 
01121 void purple_blist_request_add_group(void);
01122 
01130 void purple_blist_node_set_bool(PurpleBlistNode *node, const char *key, gboolean value);
01131 
01140 gboolean purple_blist_node_get_bool(PurpleBlistNode *node, const char *key);
01141 
01149 void purple_blist_node_set_int(PurpleBlistNode *node, const char *key, int value);
01150 
01159 int purple_blist_node_get_int(PurpleBlistNode *node, const char *key);
01160 
01168 void purple_blist_node_set_string(PurpleBlistNode *node, const char *key,
01169         const char *value);
01170 
01179 const char *purple_blist_node_get_string(PurpleBlistNode *node, const char *key);
01180 
01187 void purple_blist_node_remove_setting(PurpleBlistNode *node, const char *key);
01188 
01197 void purple_blist_node_set_flags(PurpleBlistNode *node, PurpleBlistNodeFlags flags);
01198 
01206 PurpleBlistNodeFlags purple_blist_node_get_flags(PurpleBlistNode *node);
01207 
01217 PurpleBlistNodeType purple_blist_node_get_type(PurpleBlistNode *node);
01218 
01227 GList *purple_blist_node_get_extended_menu(PurpleBlistNode *n);
01228 
01229 /**************************************************************************/
01231 /**************************************************************************/
01239 void purple_blist_set_ui_ops(PurpleBlistUiOps *ops);
01240 
01246 PurpleBlistUiOps *purple_blist_get_ui_ops(void);
01247 
01250 /**************************************************************************/
01252 /**************************************************************************/
01260 void *purple_blist_get_handle(void);
01261 
01265 void purple_blist_init(void);
01266 
01270 void purple_blist_uninit(void);
01271 
01274 #ifdef __cplusplus
01275 }
01276 #endif
01277 
01278 #endif /* _PURPLE_BLIST_H_ */