Mercurial > pidgin3 / file comparison

comparison: libpurple/blistnodetypes.h

libpurple/blistnodetypes.h

branch
gtkdoc-conversion
changeset 35396
7bfe75a37af7
parent 35394
38facb8226d4
child 35433
8dcae6cd6628
child 37039
7d964cdccbb5
equal deleted inserted replaced
35395:bf3f004adbf1 35396:7bfe75a37af7
32 #define PURPLE_BUDDY_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_BUDDY, PurpleBuddyClass)) 32 #define PURPLE_BUDDY_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_BUDDY, PurpleBuddyClass))
33 #define PURPLE_IS_BUDDY(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_BUDDY)) 33 #define PURPLE_IS_BUDDY(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_BUDDY))
34 #define PURPLE_IS_BUDDY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_BUDDY)) 34 #define PURPLE_IS_BUDDY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_BUDDY))
35 #define PURPLE_BUDDY_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_BUDDY, PurpleBuddyClass)) 35 #define PURPLE_BUDDY_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_BUDDY, PurpleBuddyClass))
36 36
37 /** @copydoc _PurpleBuddy */
38 typedef struct _PurpleBuddy PurpleBuddy; 37 typedef struct _PurpleBuddy PurpleBuddy;
39 /** @copydoc _PurpleBuddyClass */
40 typedef struct _PurpleBuddyClass PurpleBuddyClass; 38 typedef struct _PurpleBuddyClass PurpleBuddyClass;
41 39
42 #define PURPLE_TYPE_CONTACT (purple_contact_get_type()) 40 #define PURPLE_TYPE_CONTACT (purple_contact_get_type())
43 #define PURPLE_CONTACT(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_CONTACT, PurpleContact)) 41 #define PURPLE_CONTACT(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_CONTACT, PurpleContact))
44 #define PURPLE_CONTACT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_CONTACT, PurpleContactClass)) 42 #define PURPLE_CONTACT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_CONTACT, PurpleContactClass))
45 #define PURPLE_IS_CONTACT(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_CONTACT)) 43 #define PURPLE_IS_CONTACT(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_CONTACT))
46 #define PURPLE_IS_CONTACT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_CONTACT)) 44 #define PURPLE_IS_CONTACT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_CONTACT))
47 #define PURPLE_CONTACT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_CONTACT, PurpleContactClass)) 45 #define PURPLE_CONTACT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_CONTACT, PurpleContactClass))
48 46
49 /** @copydoc _PurpleContact */
50 typedef struct _PurpleContact PurpleContact; 47 typedef struct _PurpleContact PurpleContact;
51 /** @copydoc _PurpleContactClass */
52 typedef struct _PurpleContactClass PurpleContactClass; 48 typedef struct _PurpleContactClass PurpleContactClass;
53 49
54 #define PURPLE_TYPE_GROUP (purple_group_get_type()) 50 #define PURPLE_TYPE_GROUP (purple_group_get_type())
55 #define PURPLE_GROUP(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_GROUP, PurpleGroup)) 51 #define PURPLE_GROUP(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_GROUP, PurpleGroup))
56 #define PURPLE_GROUP_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_GROUP, PurpleGroupClass)) 52 #define PURPLE_GROUP_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_GROUP, PurpleGroupClass))
57 #define PURPLE_IS_GROUP(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_GROUP)) 53 #define PURPLE_IS_GROUP(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_GROUP))
58 #define PURPLE_IS_GROUP_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_GROUP)) 54 #define PURPLE_IS_GROUP_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_GROUP))
59 #define PURPLE_GROUP_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_GROUP, PurpleGroupClass)) 55 #define PURPLE_GROUP_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_GROUP, PurpleGroupClass))
60 56
61 /** @copydoc _PurpleGroup */
62 typedef struct _PurpleGroup PurpleGroup; 57 typedef struct _PurpleGroup PurpleGroup;
63 /** @copydoc _PurpleGroupClass */
64 typedef struct _PurpleGroupClass PurpleGroupClass; 58 typedef struct _PurpleGroupClass PurpleGroupClass;
65 59
66 #define PURPLE_TYPE_CHAT (purple_chat_get_type()) 60 #define PURPLE_TYPE_CHAT (purple_chat_get_type())
67 #define PURPLE_CHAT(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_CHAT, PurpleChat)) 61 #define PURPLE_CHAT(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_CHAT, PurpleChat))
68 #define PURPLE_CHAT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_CHAT, PurpleChatClass)) 62 #define PURPLE_CHAT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_CHAT, PurpleChatClass))
69 #define PURPLE_IS_CHAT(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_CHAT)) 63 #define PURPLE_IS_CHAT(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_CHAT))
70 #define PURPLE_IS_CHAT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_CHAT)) 64 #define PURPLE_IS_CHAT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_CHAT))
71 #define PURPLE_CHAT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_CHAT, PurpleChatClass)) 65 #define PURPLE_CHAT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_CHAT, PurpleChatClass))
72 66
73 /** @copydoc _PurpleChat */
74 typedef struct _PurpleChat PurpleChat; 67 typedef struct _PurpleChat PurpleChat;
75 /** @copydoc _PurpleChatClass */
76 typedef struct _PurpleChatClass PurpleChatClass; 68 typedef struct _PurpleChatClass PurpleChatClass;
77 69
78 #include "account.h" 70 #include "account.h"
79 #include "buddyicon.h" 71 #include "buddyicon.h"
80 #include "media.h" 72 #include "media.h"
92 84
93 /**************************************************************************/ 85 /**************************************************************************/
94 /* Data Structures */ 86 /* Data Structures */
95 /**************************************************************************/ 87 /**************************************************************************/
96 /** 88 /**
89 * PurpleBuddy:
90 * @node: The node that this buddy inherits from
91 *
97 * A buddy on the buddy list. 92 * A buddy on the buddy list.
98 */ 93 */
99 struct _PurpleBuddy { 94 struct _PurpleBuddy {
100 /** The node that this buddy inherits from */
101 PurpleBlistNode node; 95 PurpleBlistNode node;
102 }; 96 };
103 97
104 /** The base class for all #PurpleBuddy's. */ 98 /**
99 * PurpleBuddyClass:
100 *
101 * The base class for all #PurpleBuddy's.
102 */
105 struct _PurpleBuddyClass { 103 struct _PurpleBuddyClass {
106 PurpleBlistNodeClass node_class; 104 PurpleBlistNodeClass node_class;
107 105
108 /*< private >*/ 106 /*< private >*/
109 void (*_purple_reserved1)(void); 107 void (*_purple_reserved1)(void);
111 void (*_purple_reserved3)(void); 109 void (*_purple_reserved3)(void);
112 void (*_purple_reserved4)(void); 110 void (*_purple_reserved4)(void);
113 }; 111 };
114 112
115 /** 113 /**
114 * PurpleContact:
115 * @counting: The counting node that this contact inherits from. This keeps
116 * track of the counts of the buddies under this contact.
117 *
116 * A contact on the buddy list. 118 * A contact on the buddy list.
117 */ 119 */
118 struct _PurpleContact { 120 struct _PurpleContact {
119 /**
120 * The counting node that this contact inherits from. This keeps track
121 * of the counts of the buddies under this contact.
122 */
123 PurpleCountingNode counting; 121 PurpleCountingNode counting;
124 }; 122 };
125 123
126 /** The base class for all #PurpleContact's. */ 124 /**
125 * PurpleContactClass:
126 *
127 * The base class for all #PurpleContact's.
128 */
127 struct _PurpleContactClass { 129 struct _PurpleContactClass {
128 PurpleCountingNodeClass counting_class; 130 PurpleCountingNodeClass counting_class;
129 131
130 /*< private >*/ 132 /*< private >*/
131 void (*_purple_reserved1)(void); 133 void (*_purple_reserved1)(void);
133 void (*_purple_reserved3)(void); 135 void (*_purple_reserved3)(void);
134 void (*_purple_reserved4)(void); 136 void (*_purple_reserved4)(void);
135 }; 137 };
136 138
137 /** 139 /**
140 * PurpleGroup:
141 * @counting: The counting node that this group inherits from. This keeps track
142 * of the counts of the chats and contacts under this group.
143 *
138 * A group on the buddy list. 144 * A group on the buddy list.
139 */ 145 */
140 struct _PurpleGroup { 146 struct _PurpleGroup {
141 /**
142 * The counting node that this group inherits from. This keeps track
143 * of the counts of the chats and contacts under this group.
144 */
145 PurpleCountingNode counting; 147 PurpleCountingNode counting;
146 }; 148 };
147 149
148 /** The base class for all #PurpleGroup's. */ 150 /**
151 * PurpleGroupClass:
152 *
153 * The base class for all #PurpleGroup's.
154 */
149 struct _PurpleGroupClass { 155 struct _PurpleGroupClass {
150 PurpleCountingNodeClass counting_class; 156 PurpleCountingNodeClass counting_class;
151 157
152 /*< private >*/ 158 /*< private >*/
153 void (*_purple_reserved1)(void); 159 void (*_purple_reserved1)(void);
155 void (*_purple_reserved3)(void); 161 void (*_purple_reserved3)(void);
156 void (*_purple_reserved4)(void); 162 void (*_purple_reserved4)(void);
157 }; 163 };
158 164
159 /** 165 /**
166 * PurpleChat:
167 * @node: The node that this chat inherits from
168 *
160 * A chat on the buddy list. 169 * A chat on the buddy list.
161 */ 170 */
162 struct _PurpleChat { 171 struct _PurpleChat {
163 /** The node that this chat inherits from */
164 PurpleBlistNode node; 172 PurpleBlistNode node;
165 }; 173 };
166 174
167 /** The base class for all #PurpleChat's. */ 175 /**
176 * PurpleChatClass:
177 *
178 * The base class for all #PurpleChat's.
179 */
168 struct _PurpleChatClass { 180 struct _PurpleChatClass {
169 PurpleBlistNodeClass node_class; 181 PurpleBlistNodeClass node_class;
170 182
171 /*< private >*/ 183 /*< private >*/
172 void (*_purple_reserved1)(void); 184 void (*_purple_reserved1)(void);
181 /** @name Buddy API */ 193 /** @name Buddy API */
182 /**************************************************************************/ 194 /**************************************************************************/
183 /*@{*/ 195 /*@{*/
184 196
185 /** 197 /**
198 * purple_buddy_get_type:
199 *
186 * Returns the GType for the PurpleBuddy object. 200 * Returns the GType for the PurpleBuddy object.
187 */ 201 */
188 GType purple_buddy_get_type(void); 202 GType purple_buddy_get_type(void);
189 203
190 /** 204 /**
205 * purple_buddy_new:
206 * @account: The account this buddy will get added to
207 * @name: The name of the new buddy
208 * @alias: The alias of the new buddy (or NULL if unaliased)
209 *
191 * Creates a new buddy. 210 * Creates a new buddy.
192 * 211 *
193 * This function only creates the PurpleBuddy. Use purple_blist_add_buddy 212 * This function only creates the PurpleBuddy. Use purple_blist_add_buddy
194 * to add the buddy to the list and purple_account_add_buddy to sync up 213 * to add the buddy to the list and purple_account_add_buddy to sync up
195 * with the server. 214 * with the server.
196 * 215 *
197 * @account: The account this buddy will get added to
198 * @name: The name of the new buddy
199 * @alias: The alias of the new buddy (or NULL if unaliased)
200 * Returns: A newly allocated buddy 216 * Returns: A newly allocated buddy
201 * 217 *
202 * @see purple_account_add_buddy 218 * @see purple_account_add_buddy
203 * @see purple_blist_add_buddy 219 * @see purple_blist_add_buddy
204 */ 220 */
205 PurpleBuddy *purple_buddy_new(PurpleAccount *account, const char *name, const char *alias); 221 PurpleBuddy *purple_buddy_new(PurpleAccount *account, const char *name, const char *alias);
206 222
207 /** 223 /**
224 * purple_buddy_set_icon:
225 * @buddy: The buddy.
226 * @icon: The buddy icon.
227 *
208 * Sets a buddy's icon. 228 * Sets a buddy's icon.
209 * 229 *
210 * This should only be called from within Purple. You probably want to 230 * This should only be called from within Purple. You probably want to
211 * call purple_buddy_icon_set_data(). 231 * call purple_buddy_icon_set_data().
212 * 232 *
213 * @buddy: The buddy.
214 * @icon: The buddy icon.
215 *
216 * @see purple_buddy_icon_set_data() 233 * @see purple_buddy_icon_set_data()
217 */ 234 */
218 void purple_buddy_set_icon(PurpleBuddy *buddy, PurpleBuddyIcon *icon); 235 void purple_buddy_set_icon(PurpleBuddy *buddy, PurpleBuddyIcon *icon);
219 236
220 /** 237 /**
238 * purple_buddy_get_icon:
239 * @buddy: The buddy.
240 *
221 * Returns a buddy's icon. 241 * Returns a buddy's icon.
222 * 242 *
223 * @buddy: The buddy.
224 *
225 * Returns: The buddy icon. 243 * Returns: The buddy icon.
226 */ 244 */
227 PurpleBuddyIcon *purple_buddy_get_icon(const PurpleBuddy *buddy); 245 PurpleBuddyIcon *purple_buddy_get_icon(const PurpleBuddy *buddy);
228 246
229 /** 247 /**
248 * purple_buddy_get_account:
249 * @buddy: The buddy.
250 *
230 * Returns a buddy's account. 251 * Returns a buddy's account.
231 * 252 *
232 * @buddy: The buddy.
233 *
234 * Returns: The account 253 * Returns: The account
235 */ 254 */
236 PurpleAccount *purple_buddy_get_account(const PurpleBuddy *buddy); 255 PurpleAccount *purple_buddy_get_account(const PurpleBuddy *buddy);
237 256
238 /** 257 /**
258 * purple_buddy_set_name:
259 * @buddy: The buddy.
260 * @name: The name.
261 *
239 * Sets a buddy's name 262 * Sets a buddy's name
240 *
241 * @buddy: The buddy.
242 * @name: The name.
243 */ 263 */
244 void purple_buddy_set_name(PurpleBuddy *buddy, const char *name); 264 void purple_buddy_set_name(PurpleBuddy *buddy, const char *name);
245 265
246 /** 266 /**
267 * purple_buddy_get_name:
268 * @buddy: The buddy.
269 *
247 * Returns a buddy's name 270 * Returns a buddy's name
248 * 271 *
249 * @buddy: The buddy.
250 *
251 * Returns: The name. 272 * Returns: The name.
252 */ 273 */
253 const char *purple_buddy_get_name(const PurpleBuddy *buddy); 274 const char *purple_buddy_get_name(const PurpleBuddy *buddy);
254 275
255 /** 276 /**
277 * purple_buddy_get_protocol_data:
278 * @buddy: The buddy.
279 *
256 * Returns a buddy's protocol-specific data. 280 * Returns a buddy's protocol-specific data.
257 * 281 *
258 * This should only be called from the associated prpl. 282 * This should only be called from the associated protocol.
259 * 283 *
260 * @buddy: The buddy.
261 * Returns: The protocol data. 284 * Returns: The protocol data.
262 * 285 *
263 * @see purple_buddy_set_protocol_data() 286 * @see purple_buddy_set_protocol_data()
264 */ 287 */
265 gpointer purple_buddy_get_protocol_data(const PurpleBuddy *buddy); 288 gpointer purple_buddy_get_protocol_data(const PurpleBuddy *buddy);
266 289
267 /** 290 /**
291 * purple_buddy_set_protocol_data:
292 * @buddy: The buddy.
293 * @data: The data.
294 *
268 * Sets a buddy's protocol-specific data. 295 * Sets a buddy's protocol-specific data.
269 * 296 *
270 * This should only be called from the associated prpl. 297 * This should only be called from the associated protocol.
271 *
272 * @buddy: The buddy.
273 * @data: The data.
274 * 298 *
275 * @see purple_buddy_get_protocol_data() 299 * @see purple_buddy_get_protocol_data()
276 */ 300 */
277 void purple_buddy_set_protocol_data(PurpleBuddy *buddy, gpointer data); 301 void purple_buddy_set_protocol_data(PurpleBuddy *buddy, gpointer data);
278 302
279 /** 303 /**
304 * purple_buddy_get_contact:
305 * @buddy: The buddy.
306 *
280 * Returns a buddy's contact. 307 * Returns a buddy's contact.
281 * 308 *
282 * @buddy: The buddy.
283 *
284 * Returns: The buddy's contact. 309 * Returns: The buddy's contact.
285 */ 310 */
286 PurpleContact *purple_buddy_get_contact(PurpleBuddy *buddy); 311 PurpleContact *purple_buddy_get_contact(PurpleBuddy *buddy);
287 312
288 /** 313 /**
314 * purple_buddy_get_presence:
315 * @buddy: The buddy.
316 *
289 * Returns a buddy's presence. 317 * Returns a buddy's presence.
290 * 318 *
291 * @buddy: The buddy.
292 *
293 * Returns: The buddy's presence. 319 * Returns: The buddy's presence.
294 */ 320 */
295 PurplePresence *purple_buddy_get_presence(const PurpleBuddy *buddy); 321 PurplePresence *purple_buddy_get_presence(const PurpleBuddy *buddy);
296 322
297 /** 323 /**
298 * Updates a buddy's status. 324 * purple_buddy_update_status:
299 *
300 * This should only be called from within Purple.
301 *
302 * @buddy: The buddy whose status has changed. 325 * @buddy: The buddy whose status has changed.
303 * @old_status: The status from which we are changing. 326 * @old_status: The status from which we are changing.
327 *
328 * Updates a buddy's status.
329 *
330 * This should only be called from within Purple.
304 */ 331 */
305 void purple_buddy_update_status(PurpleBuddy *buddy, PurpleStatus *old_status); 332 void purple_buddy_update_status(PurpleBuddy *buddy, PurpleStatus *old_status);
306 333
307 /** 334 /**
335 * purple_buddy_get_media_caps:
336 * @buddy: The buddy.
337 *
308 * Gets the media caps from a buddy. 338 * Gets the media caps from a buddy.
309 * 339 *
310 * @buddy: The buddy.
311 * Returns: The media caps. 340 * Returns: The media caps.
312 */ 341 */
313 PurpleMediaCaps purple_buddy_get_media_caps(const PurpleBuddy *buddy); 342 PurpleMediaCaps purple_buddy_get_media_caps(const PurpleBuddy *buddy);
314 343
315 /** 344 /**
316 * Sets the media caps for a buddy. 345 * purple_buddy_set_media_caps:
317 *
318 * @buddy: The PurpleBuddy. 346 * @buddy: The PurpleBuddy.
319 * @media_caps: The PurpleMediaCaps. 347 * @media_caps: The PurpleMediaCaps.
348 *
349 * Sets the media caps for a buddy.
320 */ 350 */
321 void purple_buddy_set_media_caps(PurpleBuddy *buddy, PurpleMediaCaps media_caps); 351 void purple_buddy_set_media_caps(PurpleBuddy *buddy, PurpleMediaCaps media_caps);
322 352
323 /** 353 /**
354 * purple_buddy_get_alias_only:
355 * @buddy: The buddy whose alias will be returned.
356 *
324 * Returns the alias of a buddy. 357 * Returns the alias of a buddy.
325 * 358 *
326 * @buddy: The buddy whose alias will be returned.
327 * Returns: The alias (if set), server alias (if set), 359 * Returns: The alias (if set), server alias (if set),
328 * or NULL. 360 * or NULL.
329 */ 361 */
330 const char *purple_buddy_get_alias_only(PurpleBuddy *buddy); 362 const char *purple_buddy_get_alias_only(PurpleBuddy *buddy);
331 363
332 /** 364 /**
333 * Sets the server alias for a buddy. 365 * purple_buddy_set_server_alias:
334 *
335 * @buddy: The buddy. 366 * @buddy: The buddy.
336 * @alias: The server alias to be set. 367 * @alias: The server alias to be set.
368 *
369 * Sets the server alias for a buddy.
337 */ 370 */
338 void purple_buddy_set_server_alias(PurpleBuddy *buddy, const char *alias); 371 void purple_buddy_set_server_alias(PurpleBuddy *buddy, const char *alias);
339 372
340 /** 373 /**
374 * purple_buddy_get_server_alias:
375 * @buddy: The buddy whose server alias will be returned
376 *
341 * Gets the server alias for a buddy. 377 * Gets the server alias for a buddy.
342 * 378 *
343 * @buddy: The buddy whose server alias will be returned
344 * Returns: The server alias, or NULL if it is not set. 379 * Returns: The server alias, or NULL if it is not set.
345 */ 380 */
346 const char *purple_buddy_get_server_alias(PurpleBuddy *buddy); 381 const char *purple_buddy_get_server_alias(PurpleBuddy *buddy);
347 382
348 /** 383 /**
384 * purple_buddy_get_contact_alias:
385 * @buddy: The buddy whose alias will be returned
386 *
349 * Returns the correct name to display for a buddy, taking the contact alias 387 * Returns the correct name to display for a buddy, taking the contact alias
350 * into account. In order of precedence: the buddy's alias; the buddy's 388 * into account. In order of precedence: the buddy's alias; the buddy's
351 * contact alias; the buddy's server alias; the buddy's user name. 389 * contact alias; the buddy's server alias; the buddy's user name.
352 * 390 *
353 * @buddy: The buddy whose alias will be returned
354 * Returns: The appropriate name or alias, or NULL. 391 * Returns: The appropriate name or alias, or NULL.
355 * 392 *
356 */ 393 */
357 const char *purple_buddy_get_contact_alias(PurpleBuddy *buddy); 394 const char *purple_buddy_get_contact_alias(PurpleBuddy *buddy);
358 395
359 /** 396 /**
397 * purple_buddy_get_alias:
398 * @buddy: The buddy whose alias will be returned.
399 *
360 * Returns the correct name to display for a buddy. In order of precedence: 400 * Returns the correct name to display for a buddy. In order of precedence:
361 * the buddy's local alias; the buddy's server alias; the buddy's contact alias; 401 * the buddy's local alias; the buddy's server alias; the buddy's contact alias;
362 * the buddy's user name. 402 * the buddy's user name.
363 * 403 *
364 * @buddy: The buddy whose alias will be returned.
365 * Returns: The appropriate name or alias, or NULL 404 * Returns: The appropriate name or alias, or NULL
366 */ 405 */
367 const char *purple_buddy_get_alias(PurpleBuddy *buddy); 406 const char *purple_buddy_get_alias(PurpleBuddy *buddy);
368 407
369 /** 408 /**
370 * Sets the local alias for the buddy. 409 * purple_buddy_set_local_alias:
371 *
372 * @buddy: The buddy 410 * @buddy: The buddy
373 * @alias: The local alias for the buddy 411 * @alias: The local alias for the buddy
412 *
413 * Sets the local alias for the buddy.
374 */ 414 */
375 void purple_buddy_set_local_alias(PurpleBuddy *buddy, const char *alias); 415 void purple_buddy_set_local_alias(PurpleBuddy *buddy, const char *alias);
376 416
377 /** 417 /**
418 * purple_buddy_get_local_alias:
419 * @buddy: The buddy
420 *
378 * Returns the local alias for the buddy, or %NULL if none exists. 421 * Returns the local alias for the buddy, or %NULL if none exists.
379 * 422 *
380 * @buddy: The buddy
381 * Returns: The local alias for the buddy 423 * Returns: The local alias for the buddy
382 */ 424 */
383 const char *purple_buddy_get_local_alias(PurpleBuddy *buddy); 425 const char *purple_buddy_get_local_alias(PurpleBuddy *buddy);
384 426
385 /** 427 /**
428 * purple_buddy_get_group:
429 * @buddy: The buddy
430 *
386 * Returns the group of which the buddy is a member. 431 * Returns the group of which the buddy is a member.
387 * 432 *
388 * @buddy: The buddy
389 * Returns: The group or NULL if the buddy is not in a group 433 * Returns: The group or NULL if the buddy is not in a group
390 */ 434 */
391 PurpleGroup *purple_buddy_get_group(PurpleBuddy *buddy); 435 PurpleGroup *purple_buddy_get_group(PurpleBuddy *buddy);
392 436
393 /*@}*/ 437 /*@}*/
396 /** @name Contact API */ 440 /** @name Contact API */
397 /**************************************************************************/ 441 /**************************************************************************/
398 /*@{*/ 442 /*@{*/
399 443
400 /** 444 /**
445 * purple_contact_get_type:
446 *
401 * Returns the GType for the PurpleContact object. 447 * Returns the GType for the PurpleContact object.
402 */ 448 */
403 GType purple_contact_get_type(void); 449 GType purple_contact_get_type(void);
404 450
405 /** 451 /**
452 * purple_contact_new:
453 *
406 * Creates a new contact 454 * Creates a new contact
407 * 455 *
408 * Returns: A new contact struct 456 * Returns: A new contact struct
409 */ 457 */
410 PurpleContact *purple_contact_new(void); 458 PurpleContact *purple_contact_new(void);
411 459
412 /** 460 /**
461 * purple_contact_get_group:
462 * @contact: The contact
463 *
413 * Gets the PurpleGroup from a PurpleContact 464 * Gets the PurpleGroup from a PurpleContact
414 * 465 *
466 * Returns: The group
467 */
468 PurpleGroup *purple_contact_get_group(const PurpleContact *contact);
469
470 /**
471 * purple_contact_get_priority_buddy:
415 * @contact: The contact 472 * @contact: The contact
416 * Returns: The group 473 *
417 */
418 PurpleGroup *purple_contact_get_group(const PurpleContact *contact);
419
420 /**
421 * Returns the highest priority buddy for a given contact. 474 * Returns the highest priority buddy for a given contact.
422 * 475 *
423 * @contact: The contact
424 * Returns: The highest priority buddy 476 * Returns: The highest priority buddy
425 */ 477 */
426 PurpleBuddy *purple_contact_get_priority_buddy(PurpleContact *contact); 478 PurpleBuddy *purple_contact_get_priority_buddy(PurpleContact *contact);
427 479
428 /** 480 /**
429 * Sets the alias for a contact. 481 * purple_contact_set_alias:
430 *
431 * @contact: The contact 482 * @contact: The contact
432 * @alias: The alias 483 * @alias: The alias
484 *
485 * Sets the alias for a contact.
433 */ 486 */
434 void purple_contact_set_alias(PurpleContact *contact, const char *alias); 487 void purple_contact_set_alias(PurpleContact *contact, const char *alias);
435 488
436 /** 489 /**
490 * purple_contact_get_alias:
491 * @contact: The contact
492 *
437 * Gets the alias for a contact. 493 * Gets the alias for a contact.
438 * 494 *
439 * @contact: The contact
440 * Returns: The alias, or NULL if it is not set. 495 * Returns: The alias, or NULL if it is not set.
441 */ 496 */
442 const char *purple_contact_get_alias(PurpleContact *contact); 497 const char *purple_contact_get_alias(PurpleContact *contact);
443 498
444 /** 499 /**
445 * Determines whether an account owns any buddies in a given contact 500 * purple_contact_on_account:
446 *
447 * @contact: The contact to search through. 501 * @contact: The contact to search through.
448 * @account: The account. 502 * @account: The account.
449 * 503 *
504 * Determines whether an account owns any buddies in a given contact
505 *
450 * Returns: TRUE if there are any buddies from account in the contact, or FALSE otherwise. 506 * Returns: TRUE if there are any buddies from account in the contact, or FALSE otherwise.
451 */ 507 */
452 gboolean purple_contact_on_account(PurpleContact *contact, PurpleAccount *account); 508 gboolean purple_contact_on_account(PurpleContact *contact, PurpleAccount *account);
453 509
454 /** 510 /**
511 * purple_contact_invalidate_priority_buddy:
512 * @contact: The contact
513 *
455 * Invalidates the priority buddy so that the next call to 514 * Invalidates the priority buddy so that the next call to
456 * purple_contact_get_priority_buddy recomputes it. 515 * purple_contact_get_priority_buddy recomputes it.
457 *
458 * @contact: The contact
459 */ 516 */
460 void purple_contact_invalidate_priority_buddy(PurpleContact *contact); 517 void purple_contact_invalidate_priority_buddy(PurpleContact *contact);
461 518
462 /** 519 /**
463 * Merges two contacts 520 * purple_contact_merge:
464 *
465 * All of the buddies from source will be moved to target
466 *
467 * @source: The contact to merge 521 * @source: The contact to merge
468 * @node: The place to merge to (a buddy or contact) 522 * @node: The place to merge to (a buddy or contact)
523 *
524 * Merges two contacts
525 *
526 * All of the buddies from source will be moved to target
469 */ 527 */
470 void purple_contact_merge(PurpleContact *source, PurpleBlistNode *node); 528 void purple_contact_merge(PurpleContact *source, PurpleBlistNode *node);
471 529
472 /*@}*/ 530 /*@}*/
473 531
475 /** @name Chat API */ 533 /** @name Chat API */
476 /**************************************************************************/ 534 /**************************************************************************/
477 /*@{*/ 535 /*@{*/
478 536
479 /** 537 /**
538 * purple_chat_get_type:
539 *
480 * Returns the GType for the PurpleChat object. 540 * Returns the GType for the PurpleChat object.
481 */ 541 */
482 GType purple_chat_get_type(void); 542 GType purple_chat_get_type(void);
483 543
484 /** 544 /**
485 * Creates a new chat for the buddy list 545 * purple_chat_new:
486 *
487 * @account: The account this chat will get added to 546 * @account: The account this chat will get added to
488 * @alias: The alias of the new chat 547 * @alias: The alias of the new chat
489 * @components: The info the prpl needs to join the chat. The 548 * @components: The info the protocol needs to join the chat. The
490 * hash function should be g_str_hash() and the 549 * hash function should be g_str_hash() and the
491 * equal function should be g_str_equal(). 550 * equal function should be g_str_equal().
551 *
552 * Creates a new chat for the buddy list
553 *
492 * Returns: A newly allocated chat 554 * Returns: A newly allocated chat
493 */ 555 */
494 PurpleChat *purple_chat_new(PurpleAccount *account, const char *alias, GHashTable *components); 556 PurpleChat *purple_chat_new(PurpleAccount *account, const char *alias, GHashTable *components);
495 557
496 /** 558 /**
559 * purple_chat_get_name:
560 * @chat: The chat whose name will be returned.
561 *
497 * Returns the correct name to display for a blist chat. 562 * Returns the correct name to display for a blist chat.
498 * 563 *
564 * Returns: The alias (if set), or first component value.
565 */
566 const char *purple_chat_get_name(PurpleChat *chat);
567
568 /**
569 * purple_chat_get_name_only:
499 * @chat: The chat whose name will be returned. 570 * @chat: The chat whose name will be returned.
500 * Returns: The alias (if set), or first component value. 571 *
501 */
502 const char *purple_chat_get_name(PurpleChat *chat);
503
504 /**
505 * Returns the name of the chat 572 * Returns the name of the chat
506 * 573 *
507 * @chat: The chat whose name will be returned.
508 * Returns: The first component value. 574 * Returns: The first component value.
509 */ 575 */
510 const char *purple_chat_get_name_only(PurpleChat *chat); 576 const char *purple_chat_get_name_only(PurpleChat *chat);
511 577
512 /** 578 /**
513 * Sets the alias for a blist chat. 579 * purple_chat_set_alias:
514 *
515 * @chat: The chat 580 * @chat: The chat
516 * @alias: The alias 581 * @alias: The alias
582 *
583 * Sets the alias for a blist chat.
517 */ 584 */
518 void purple_chat_set_alias(PurpleChat *chat, const char *alias); 585 void purple_chat_set_alias(PurpleChat *chat, const char *alias);
519 586
520 /** 587 /**
588 * purple_chat_get_group:
589 * @chat: The chat.
590 *
521 * Returns the group of which the chat is a member. 591 * Returns the group of which the chat is a member.
522 * 592 *
523 * @chat: The chat.
524 *
525 * Returns: The parent group, or %NULL if the chat is not in a group. 593 * Returns: The parent group, or %NULL if the chat is not in a group.
526 */ 594 */
527 PurpleGroup *purple_chat_get_group(PurpleChat *chat); 595 PurpleGroup *purple_chat_get_group(PurpleChat *chat);
528 596
529 /** 597 /**
598 * purple_chat_get_account:
599 * @chat: The chat.
600 *
530 * Returns the account the chat belongs to. 601 * Returns the account the chat belongs to.
531 * 602 *
603 * Returns: The account the chat belongs to.
604 */
605 PurpleAccount *purple_chat_get_account(PurpleChat *chat);
606
607 /**
608 * purple_chat_get_components:
532 * @chat: The chat. 609 * @chat: The chat.
533 * 610 *
534 * Returns: The account the chat belongs to.
535 */
536 PurpleAccount *purple_chat_get_account(PurpleChat *chat);
537
538 /**
539 * Get a hashtable containing information about a chat. 611 * Get a hashtable containing information about a chat.
540 * 612 *
541 * @chat: The chat.
542 *
543 * Returns: (transfer none): The hashtable. 613 * Returns: (transfer none): The hashtable.
544 */ 614 */
545 GHashTable *purple_chat_get_components(PurpleChat *chat); 615 GHashTable *purple_chat_get_components(PurpleChat *chat);
546 616
547 /*@}*/ 617 /*@}*/
550 /** @name Group API */ 620 /** @name Group API */
551 /**************************************************************************/ 621 /**************************************************************************/
552 /*@{*/ 622 /*@{*/
553 623
554 /** 624 /**
625 * purple_group_get_type:
626 *
555 * Returns the GType for the PurpleGroup object. 627 * Returns the GType for the PurpleGroup object.
556 */ 628 */
557 GType purple_group_get_type(void); 629 GType purple_group_get_type(void);
558 630
559 /** 631 /**
632 * purple_group_new:
633 * @name: The name of the new group
634 *
560 * Creates a new group 635 * Creates a new group
561 * 636 *
562 * You can't have more than one group with the same name. Sorry. If you pass 637 * You can't have more than one group with the same name. Sorry. If you pass
563 * this the name of a group that already exists, it will return that group. 638 * this the name of a group that already exists, it will return that group.
564 * 639 *
565 * @name: The name of the new group
566 * Returns: A new group struct 640 * Returns: A new group struct
567 */ 641 */
568 PurpleGroup *purple_group_new(const char *name); 642 PurpleGroup *purple_group_new(const char *name);
569 643
570 /** 644 /**
645 * purple_group_get_accounts:
646 * @g: The group
647 *
571 * Returns a list of accounts that have buddies in this group 648 * Returns a list of accounts that have buddies in this group
572 *
573 * @g: The group
574 * 649 *
575 * Returns: A GSList of accounts (which must be freed), or NULL if the group 650 * Returns: A GSList of accounts (which must be freed), or NULL if the group
576 * has no accounts. 651 * has no accounts.
577 */ 652 */
578 GSList *purple_group_get_accounts(PurpleGroup *g); 653 GSList *purple_group_get_accounts(PurpleGroup *g);
579 654
580 /** 655 /**
581 * Determines whether an account owns any buddies in a given group 656 * purple_group_on_account:
582 *
583 * @g: The group to search through. 657 * @g: The group to search through.
584 * @account: The account. 658 * @account: The account.
585 * 659 *
660 * Determines whether an account owns any buddies in a given group
661 *
586 * Returns: TRUE if there are any buddies in the group, or FALSE otherwise. 662 * Returns: TRUE if there are any buddies in the group, or FALSE otherwise.
587 */ 663 */
588 gboolean purple_group_on_account(PurpleGroup *g, PurpleAccount *account); 664 gboolean purple_group_on_account(PurpleGroup *g, PurpleAccount *account);
589 665
590 /** 666 /**
591 * Sets the name of a group. 667 * purple_group_set_name:
592 *
593 * @group: The group. 668 * @group: The group.
594 * @name: The name of the group. 669 * @name: The name of the group.
670 *
671 * Sets the name of a group.
595 */ 672 */
596 void purple_group_set_name(PurpleGroup *group, const char *name); 673 void purple_group_set_name(PurpleGroup *group, const char *name);
597 674
598 /** 675 /**
676 * purple_group_get_name:
677 * @group: The group.
678 *
599 * Returns the name of a group. 679 * Returns the name of a group.
600 * 680 *
601 * @group: The group.
602 *
603 * Returns: The name of the group. 681 * Returns: The name of the group.
604 */ 682 */
605 const char *purple_group_get_name(PurpleGroup *group); 683 const char *purple_group_get_name(PurpleGroup *group);
606 684
607 /*@}*/ 685 /*@}*/

Mercurial Repository: pidgin3

mercurial