Remove unused Meson option for enchant.
[pidgin-git.git] / libpurple / buddy.h
blobf43b424ab52154ab68f589e1990caea3a7585dac
1 /* purple
3 * Purple is the legal property of its developers, whose names are too numerous
4 * to list here. Please refer to the COPYRIGHT file distributed with this
5 * source distribution.
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
22 #ifndef PURPLE_BUDDY_H
23 #define PURPLE_BUDDY_H
25 /**
26 * SECTION:buddy
27 * @section_id: libpurple-buddy
28 * @short_description: <filename>buddy.h</filename>
29 * @title: Buddy Object
32 #define PURPLE_TYPE_BUDDY (purple_buddy_get_type())
33 #define PURPLE_BUDDY(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_BUDDY, PurpleBuddy))
34 #define PURPLE_BUDDY_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_BUDDY, PurpleBuddyClass))
35 #define PURPLE_IS_BUDDY(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_BUDDY))
36 #define PURPLE_IS_BUDDY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_BUDDY))
37 #define PURPLE_BUDDY_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_BUDDY, PurpleBuddyClass))
39 typedef struct _PurpleBuddy PurpleBuddy;
40 typedef struct _PurpleBuddyClass PurpleBuddyClass;
42 #include "account.h"
43 #include "blistnode.h"
44 #include "buddyicon.h"
45 #include "chat.h"
46 #include "contact.h"
47 #include "group.h"
48 #include "media.h"
49 #include "presence.h"
50 #include "status.h"
52 #define PURPLE_BUDDY_IS_ONLINE(b) \
53 (PURPLE_IS_BUDDY(b) \
54 && purple_account_is_connected(purple_buddy_get_account(PURPLE_BUDDY(b))) \
55 && purple_presence_is_online(purple_buddy_get_presence(PURPLE_BUDDY(b))))
57 #define PURPLE_BLIST_NODE_NAME(n) \
58 (PURPLE_IS_CHAT(n) ? purple_chat_get_name(PURPLE_CHAT(n)) : \
59 PURPLE_IS_BUDDY(n) ? purple_buddy_get_name(PURPLE_BUDDY(n)) : NULL)
61 /**************************************************************************/
62 /* Data Structures */
63 /**************************************************************************/
64 /**
65 * PurpleBuddy:
67 * A buddy on the buddy list.
69 struct _PurpleBuddy {
70 PurpleBlistNode node;
73 struct _PurpleBuddyClass {
74 PurpleBlistNodeClass node_class;
76 /*< private >*/
77 void (*_purple_reserved1)(void);
78 void (*_purple_reserved2)(void);
79 void (*_purple_reserved3)(void);
80 void (*_purple_reserved4)(void);
83 G_BEGIN_DECLS
85 /**************************************************************************/
86 /* Buddy API */
87 /**************************************************************************/
89 /**
90 * purple_buddy_get_type:
92 * Returns: The #GType for the #PurpleBuddy object.
94 GType purple_buddy_get_type(void);
96 /**
97 * purple_buddy_new:
98 * @account: The account this buddy will get added to
99 * @name: The name of the new buddy
100 * @alias: The alias of the new buddy (or NULL if unaliased)
102 * Creates a new buddy.
104 * This function only creates the #PurpleBuddy. Use purple_blist_add_buddy()
105 * to add the buddy to the list and purple_account_add_buddy() to sync up
106 * with the server.
108 * See purple_account_add_buddy(), purple_blist_add_buddy().
110 * Returns: A newly allocated buddy
112 PurpleBuddy *purple_buddy_new(PurpleAccount *account, const char *name, const char *alias);
115 * purple_buddy_set_icon:
116 * @buddy: The buddy.
117 * @icon: The buddy icon.
119 * Sets a buddy's icon.
121 * This should only be called from within Purple. You probably want to
122 * call purple_buddy_icon_set_data().
124 * See purple_buddy_icon_set_data().
126 void purple_buddy_set_icon(PurpleBuddy *buddy, PurpleBuddyIcon *icon);
129 * purple_buddy_get_icon:
130 * @buddy: The buddy.
132 * Returns a buddy's icon.
134 * Returns: The buddy icon.
136 PurpleBuddyIcon *purple_buddy_get_icon(PurpleBuddy *buddy);
139 * purple_buddy_get_account:
140 * @buddy: The buddy.
142 * Returns a buddy's account.
144 * Returns: (transfer none): The account.
146 PurpleAccount *purple_buddy_get_account(PurpleBuddy *buddy);
149 * purple_buddy_set_name:
150 * @buddy: The buddy.
151 * @name: The name.
153 * Sets a buddy's name
155 void purple_buddy_set_name(PurpleBuddy *buddy, const char *name);
158 * purple_buddy_get_name:
159 * @buddy: The buddy.
161 * Returns a buddy's name
163 * Returns: The name.
165 const char *purple_buddy_get_name(PurpleBuddy *buddy);
168 * purple_buddy_get_protocol_data:
169 * @buddy: The buddy.
171 * Returns a buddy's protocol-specific data.
173 * This should only be called from the associated protocol.
175 * See purple_buddy_set_protocol_data().
177 * Returns: The protocol data.
179 gpointer purple_buddy_get_protocol_data(PurpleBuddy *buddy);
182 * purple_buddy_set_protocol_data:
183 * @buddy: The buddy.
184 * @data: The data.
186 * Sets a buddy's protocol-specific data.
188 * This should only be called from the associated protocol.
190 * See purple_buddy_get_protocol_data().
192 void purple_buddy_set_protocol_data(PurpleBuddy *buddy, gpointer data);
195 * purple_buddy_get_contact:
196 * @buddy: The buddy.
198 * Returns a buddy's contact.
200 * Returns: (transfer none): The buddy's contact.
202 PurpleContact *purple_buddy_get_contact(PurpleBuddy *buddy);
205 * purple_buddy_get_presence:
206 * @buddy: The buddy.
208 * Returns a buddy's presence.
210 * Returns: (transfer none): The buddy's presence.
212 PurplePresence *purple_buddy_get_presence(PurpleBuddy *buddy);
215 * purple_buddy_update_status:
216 * @buddy: The buddy whose status has changed.
217 * @old_status: The status from which we are changing.
219 * Updates a buddy's status.
221 * This should only be called from within Purple.
223 void purple_buddy_update_status(PurpleBuddy *buddy, PurpleStatus *old_status);
226 * purple_buddy_get_media_caps:
227 * @buddy: The buddy.
229 * Gets the media caps from a buddy.
231 * Returns: The media caps.
233 PurpleMediaCaps purple_buddy_get_media_caps(PurpleBuddy *buddy);
236 * purple_buddy_set_media_caps:
237 * @buddy: The PurpleBuddy.
238 * @media_caps: The PurpleMediaCaps.
240 * Sets the media caps for a buddy.
242 void purple_buddy_set_media_caps(PurpleBuddy *buddy, PurpleMediaCaps media_caps);
245 * purple_buddy_get_alias_only:
246 * @buddy: The buddy whose alias will be returned.
248 * Returns the alias of a buddy.
250 * Returns: The alias (if set), server alias (if set),
251 * or NULL.
253 const char *purple_buddy_get_alias_only(PurpleBuddy *buddy);
256 * purple_buddy_set_server_alias:
257 * @buddy: The buddy.
258 * @alias: The server alias to be set.
260 * Sets the server alias for a buddy.
262 void purple_buddy_set_server_alias(PurpleBuddy *buddy, const char *alias);
265 * purple_buddy_get_server_alias:
266 * @buddy: The buddy whose server alias will be returned
268 * Gets the server alias for a buddy.
270 * Returns: The server alias, or NULL if it is not set.
272 const char *purple_buddy_get_server_alias(PurpleBuddy *buddy);
275 * purple_buddy_get_contact_alias:
276 * @buddy: The buddy whose alias will be returned
278 * Returns the correct name to display for a buddy, taking the contact alias
279 * into account. In order of precedence: the buddy's alias; the buddy's
280 * contact alias; the buddy's server alias; the buddy's user name.
282 * Returns: The appropriate name or alias, or NULL.
285 const char *purple_buddy_get_contact_alias(PurpleBuddy *buddy);
288 * purple_buddy_get_alias:
289 * @buddy: The buddy whose alias will be returned.
291 * Returns the correct name to display for a buddy. In order of precedence:
292 * the buddy's local alias; the buddy's server alias; the buddy's contact alias;
293 * the buddy's user name.
295 * Returns: The appropriate name or alias, or NULL
297 const char *purple_buddy_get_alias(PurpleBuddy *buddy);
300 * purple_buddy_set_local_alias:
301 * @buddy: The buddy
302 * @alias: The local alias for the buddy
304 * Sets the local alias for the buddy.
306 void purple_buddy_set_local_alias(PurpleBuddy *buddy, const char *alias);
309 * purple_buddy_get_local_alias:
310 * @buddy: The buddy
312 * Returns the local alias for the buddy, or %NULL if none exists.
314 * Returns: The local alias for the buddy
316 const char *purple_buddy_get_local_alias(PurpleBuddy *buddy);
319 * purple_buddy_get_group:
320 * @buddy: The buddy
322 * Returns the group of which the buddy is a member.
324 * Returns: (transfer none): The group or %NULL if the buddy is not in a group.
326 PurpleGroup *purple_buddy_get_group(PurpleBuddy *buddy);
328 G_END_DECLS
330 #endif /* PURPLE_BUDDY_H */