Mercurial > pidgin3 / file comparison

comparison: libpurple/conversation.h

libpurple/conversation.h

branch
soc.2013.gobjectification.plugins
changeset 37023
d9bcdc9a91e6
parent 37021
04c99b24db84
child 37034
9d6765962b22
equal deleted inserted replaced
37022:d891503c8aa6 37023:d9bcdc9a91e6
121 /** 121 /**
122 * A core representation of a conversation between two or more people. 122 * A core representation of a conversation between two or more people.
123 * 123 *
124 * The conversation can be an IM or a chat. 124 * The conversation can be an IM or a chat.
125 * 125 *
126 * Note: When a conversation is destroyed with the last g_object_unref(), the 126 * @note When a conversation is destroyed with the last g_object_unref(), the
127 * specified conversation is removed from the parent window. If this 127 * specified conversation is removed from the parent window. If this
128 * conversation is the only one contained in the parent window, that 128 * conversation is the only one contained in the parent window, that
129 * window is also destroyed. 129 * window is also destroyed.
130 */ 130 */
131 struct _PurpleConversation 131 struct _PurpleConversation
176 */ 176 */
177 void (*create_conversation)(PurpleConversation *conv); 177 void (*create_conversation)(PurpleConversation *conv);
178 178
179 /** Called just before @a conv is freed. */ 179 /** Called just before @a conv is freed. */
180 void (*destroy_conversation)(PurpleConversation *conv); 180 void (*destroy_conversation)(PurpleConversation *conv);
181 /** Write a message to a chat. If this field is %NULL, libpurple will 181 /** Write a message to a chat. If this field is @c NULL, libpurple will
182 * fall back to using #write_conv. 182 * fall back to using #write_conv.
183 * @see purple_chat_conversation_write() 183 * @see purple_chat_conversation_write()
184 */ 184 */
185 void (*write_chat)(PurpleChatConversation *chat, const char *who, 185 void (*write_chat)(PurpleChatConversation *chat, const char *who,
186 const char *message, PurpleMessageFlags flags, 186 const char *message, PurpleMessageFlags flags,
187 time_t mtime); 187 time_t mtime);
188 /** Write a message to an IM conversation. If this field is %NULL, 188 /** Write a message to an IM conversation. If this field is @c NULL,
189 * libpurple will fall back to using #write_conv. 189 * libpurple will fall back to using #write_conv.
190 * @see purple_im_conversation_write() 190 * @see purple_im_conversation_write()
191 */ 191 */
192 void (*write_im)(PurpleIMConversation *im, const char *who, 192 void (*write_im)(PurpleIMConversation *im, const char *who,
193 const char *message, PurpleMessageFlags flags, 193 const char *message, PurpleMessageFlags flags,
206 const char *message, 206 const char *message,
207 PurpleMessageFlags flags, 207 PurpleMessageFlags flags,
208 time_t mtime); 208 time_t mtime);
209 209
210 /** Add @a cbuddies to a chat. 210 /** Add @a cbuddies to a chat.
211 * @cbuddies: A @c GList of #PurpleChatUser structs. 211 * @param cbuddies A @c GList of #PurpleChatUser structs.
212 * @new_arrivals: Whether join notices should be shown. 212 * @param new_arrivals Whether join notices should be shown.
213 * (Join notices are actually written to the 213 * (Join notices are actually written to the
214 * conversation by 214 * conversation by
215 * #purple_chat_conversation_add_users().) 215 * #purple_chat_conversation_add_users().)
216 */ 216 */
217 void (*chat_add_users)(PurpleChatConversation *chat, 217 void (*chat_add_users)(PurpleChatConversation *chat,
218 GList *cbuddies, 218 GList *cbuddies,
219 gboolean new_arrivals); 219 gboolean new_arrivals);
220 /** Rename the user in this chat named @a old_name to @a new_name. (The 220 /** Rename the user in this chat named @a old_name to @a new_name. (The
221 * rename message is written to the conversation by libpurple.) 221 * rename message is written to the conversation by libpurple.)
222 * @new_alias: @a new_name's new alias, if they have one. 222 * @param new_alias @a new_name's new alias, if they have one.
223 * @see purple_chat_conversation_add_users() 223 * @see purple_chat_conversation_add_users()
224 */ 224 */
225 void (*chat_rename_user)(PurpleChatConversation *chat, const char *old_name, 225 void (*chat_rename_user)(PurpleChatConversation *chat, const char *old_name,
226 const char *new_name, const char *new_alias); 226 const char *new_name, const char *new_alias);
227 /** Remove @a users from a chat. 227 /** Remove @a users from a chat.
228 * @users: A @c GList of <tt>const char *</tt>s. 228 * @param users A @c GList of <tt>const char *</tt>s.
229 * @see purple_chat_conversation_rename_user() 229 * @see purple_chat_conversation_rename_user()
230 */ 230 */
231 void (*chat_remove_users)(PurpleChatConversation *chat, GList *users); 231 void (*chat_remove_users)(PurpleChatConversation *chat, GList *users);
232 /** Called when a user's flags are changed. 232 /** Called when a user's flags are changed.
233 * @see purple_chat_user_set_flags() 233 * @see purple_chat_user_set_flags()
238 * the IM dialog. 238 * the IM dialog.
239 */ 239 */
240 void (*present)(PurpleConversation *conv); 240 void (*present)(PurpleConversation *conv);
241 241
242 /** If this UI has a concept of focus (as in a windowing system) and 242 /** If this UI has a concept of focus (as in a windowing system) and
243 * this conversation has the focus, return %TRUE; otherwise, return 243 * this conversation has the focus, return @c TRUE; otherwise, return
244 * %FALSE. 244 * @c FALSE.
245 */ 245 */
246 gboolean (*has_focus)(PurpleConversation *conv); 246 gboolean (*has_focus)(PurpleConversation *conv);
247 247
248 /* Custom Smileys */ 248 /* Custom Smileys */
249 gboolean (*custom_smiley_add)(PurpleConversation *conv, const char *smile, 249 gboolean (*custom_smiley_add)(PurpleConversation *conv, const char *smile,
252 const guchar *data, gsize size); 252 const guchar *data, gsize size);
253 void (*custom_smiley_close)(PurpleConversation *conv, const char *smile); 253 void (*custom_smiley_close)(PurpleConversation *conv, const char *smile);
254 254
255 /** Prompt the user for confirmation to send @a message. This function 255 /** Prompt the user for confirmation to send @a message. This function
256 * should arrange for the message to be sent if the user accepts. If 256 * should arrange for the message to be sent if the user accepts. If
257 * this field is %NULL, libpurple will fall back to using 257 * this field is @c NULL, libpurple will fall back to using
258 * #purple_request_action(). 258 * #purple_request_action().
259 */ 259 */
260 void (*send_confirm)(PurpleConversation *conv, const char *message); 260 void (*send_confirm)(PurpleConversation *conv, const char *message);
261 261
262 /*< private >*/ 262 /*< private >*/
279 GType purple_conversation_get_type(void); 279 GType purple_conversation_get_type(void);
280 280
281 /** 281 /**
282 * Present a conversation to the user. This allows core code to initiate a 282 * Present a conversation to the user. This allows core code to initiate a
283 * conversation by displaying the IM dialog. 283 * conversation by displaying the IM dialog.
284 * @conv: The conversation to present 284 * @param conv The conversation to present
285 */ 285 */
286 void purple_conversation_present(PurpleConversation *conv); 286 void purple_conversation_present(PurpleConversation *conv);
287 287
288 /** 288 /**
289 * Sets the specified conversation's UI operations structure. 289 * Sets the specified conversation's UI operations structure.
290 * 290 *
291 * @conv: The conversation. 291 * @param conv The conversation.
292 * @ops: The UI conversation operations structure. 292 * @param ops The UI conversation operations structure.
293 */ 293 */
294 void purple_conversation_set_ui_ops(PurpleConversation *conv, 294 void purple_conversation_set_ui_ops(PurpleConversation *conv,
295 PurpleConversationUiOps *ops); 295 PurpleConversationUiOps *ops);
296 296
297 /** 297 /**
298 * Returns the specified conversation's UI operations structure. 298 * Returns the specified conversation's UI operations structure.
299 * 299 *
300 * @conv: The conversation. 300 * @param conv The conversation.
301 * 301 *
302 * Returns: The operations structure. 302 * @return The operations structure.
303 */ 303 */
304 PurpleConversationUiOps *purple_conversation_get_ui_ops(const PurpleConversation *conv); 304 PurpleConversationUiOps *purple_conversation_get_ui_ops(const PurpleConversation *conv);
305 305
306 /** 306 /**
307 * Sets the specified conversation's purple_account. 307 * Sets the specified conversation's purple_account.
308 * 308 *
309 * This purple_account represents the user using purple, not the person the user 309 * This purple_account represents the user using purple, not the person the user
310 * is having a conversation/chat/flame with. 310 * is having a conversation/chat/flame with.
311 * 311 *
312 * @conv: The conversation. 312 * @param conv The conversation.
313 * @account: The purple_account. 313 * @param account The purple_account.
314 */ 314 */
315 void purple_conversation_set_account(PurpleConversation *conv, 315 void purple_conversation_set_account(PurpleConversation *conv,
316 PurpleAccount *account); 316 PurpleAccount *account);
317 317
318 /** 318 /**
319 * Returns the specified conversation's purple_account. 319 * Returns the specified conversation's purple_account.
320 * 320 *
321 * This purple_account represents the user using purple, not the person the user 321 * This purple_account represents the user using purple, not the person the user
322 * is having a conversation/chat/flame with. 322 * is having a conversation/chat/flame with.
323 * 323 *
324 * @conv: The conversation. 324 * @param conv The conversation.
325 * 325 *
326 * Returns: The conversation's purple_account. 326 * @return The conversation's purple_account.
327 */ 327 */
328 PurpleAccount *purple_conversation_get_account(const PurpleConversation *conv); 328 PurpleAccount *purple_conversation_get_account(const PurpleConversation *conv);
329 329
330 /** 330 /**
331 * Returns the specified conversation's purple_connection. 331 * Returns the specified conversation's purple_connection.
332 * 332 *
333 * @conv: The conversation. 333 * @param conv The conversation.
334 * 334 *
335 * Returns: The conversation's purple_connection. 335 * @return The conversation's purple_connection.
336 */ 336 */
337 PurpleConnection *purple_conversation_get_connection(const PurpleConversation *conv); 337 PurpleConnection *purple_conversation_get_connection(const PurpleConversation *conv);
338 338
339 /** 339 /**
340 * Sets the specified conversation's title. 340 * Sets the specified conversation's title.
341 * 341 *
342 * @conv: The conversation. 342 * @param conv The conversation.
343 * @title: The title. 343 * @param title The title.
344 */ 344 */
345 void purple_conversation_set_title(PurpleConversation *conv, const char *title); 345 void purple_conversation_set_title(PurpleConversation *conv, const char *title);
346 346
347 /** 347 /**
348 * Returns the specified conversation's title. 348 * Returns the specified conversation's title.
349 * 349 *
350 * @conv: The conversation. 350 * @param conv The conversation.
351 * 351 *
352 * Returns: The title. 352 * @return The title.
353 */ 353 */
354 const char *purple_conversation_get_title(const PurpleConversation *conv); 354 const char *purple_conversation_get_title(const PurpleConversation *conv);
355 355
356 /** 356 /**
357 * Automatically sets the specified conversation's title. 357 * Automatically sets the specified conversation's title.
358 * 358 *
359 * This function takes OPT_IM_ALIAS_TAB into account, as well as the 359 * This function takes OPT_IM_ALIAS_TAB into account, as well as the
360 * user's alias. 360 * user's alias.
361 * 361 *
362 * @conv: The conversation. 362 * @param conv The conversation.
363 */ 363 */
364 void purple_conversation_autoset_title(PurpleConversation *conv); 364 void purple_conversation_autoset_title(PurpleConversation *conv);
365 365
366 /** 366 /**
367 * Sets the specified conversation's name. 367 * Sets the specified conversation's name.
368 * 368 *
369 * @conv: The conversation. 369 * @param conv The conversation.
370 * @name: The conversation's name. 370 * @param name The conversation's name.
371 */ 371 */
372 void purple_conversation_set_name(PurpleConversation *conv, const char *name); 372 void purple_conversation_set_name(PurpleConversation *conv, const char *name);
373 373
374 /** 374 /**
375 * Returns the specified conversation's name. 375 * Returns the specified conversation's name.
376 * 376 *
377 * @conv: The conversation. 377 * @param conv The conversation.
378 * 378 *
379 * Returns: The conversation's name. If the conversation is an IM with a PurpleBuddy, 379 * @return The conversation's name. If the conversation is an IM with a PurpleBuddy,
380 * then it's the name of the PurpleBuddy. 380 * then it's the name of the PurpleBuddy.
381 */ 381 */
382 const char *purple_conversation_get_name(const PurpleConversation *conv); 382 const char *purple_conversation_get_name(const PurpleConversation *conv);
383 383
384 /** 384 /**
385 * Sets current E2EE state for the conversation. 385 * Sets current E2EE state for the conversation.
386 * 386 *
387 * @conv: The conversation. 387 * @param conv The conversation.
388 * @state: The E2EE state. 388 * @param state The E2EE state.
389 */ 389 */
390 void 390 void
391 purple_conversation_set_e2ee_state(PurpleConversation *conv, 391 purple_conversation_set_e2ee_state(PurpleConversation *conv,
392 PurpleE2eeState *state); 392 PurpleE2eeState *state);
393 393
394 /** 394 /**
395 * Gets current conversation's E2EE state. 395 * Gets current conversation's E2EE state.
396 * 396 *
397 * @conv: The conversation. 397 * @param conv The conversation.
398 * 398 *
399 * Returns: Current E2EE state for conversation. 399 * @return Current E2EE state for conversation.
400 */ 400 */
401 PurpleE2eeState * 401 PurpleE2eeState *
402 purple_conversation_get_e2ee_state(PurpleConversation *conv); 402 purple_conversation_get_e2ee_state(PurpleConversation *conv);
403 403
404 /** 404 /**
405 * Enables or disables logging for this conversation. 405 * Enables or disables logging for this conversation.
406 * 406 *
407 * @conv: The conversation. 407 * @param conv The conversation.
408 * @log: %TRUE if logging should be enabled, or %FALSE otherwise. 408 * @param log @c TRUE if logging should be enabled, or @c FALSE otherwise.
409 */ 409 */
410 void purple_conversation_set_logging(PurpleConversation *conv, gboolean log); 410 void purple_conversation_set_logging(PurpleConversation *conv, gboolean log);
411 411
412 /** 412 /**
413 * Returns whether or not logging is enabled for this conversation. 413 * Returns whether or not logging is enabled for this conversation.
414 * 414 *
415 * @conv: The conversation. 415 * @param conv The conversation.
416 * 416 *
417 * Returns: %TRUE if logging is enabled, or %FALSE otherwise. 417 * @return @c TRUE if logging is enabled, or @c FALSE otherwise.
418 */ 418 */
419 gboolean purple_conversation_is_logging(const PurpleConversation *conv); 419 gboolean purple_conversation_is_logging(const PurpleConversation *conv);
420 420
421 /** 421 /**
422 * Closes any open logs for this conversation. 422 * Closes any open logs for this conversation.
423 * 423 *
424 * Note that new logs will be opened as necessary (e.g. upon receipt of a 424 * Note that new logs will be opened as necessary (e.g. upon receipt of a
425 * message, if the conversation has logging enabled. To disable logging for 425 * message, if the conversation has logging enabled. To disable logging for
426 * the remainder of the conversation, use purple_conversation_set_logging(). 426 * the remainder of the conversation, use purple_conversation_set_logging().
427 * 427 *
428 * @conv: The conversation. 428 * @param conv The conversation.
429 */ 429 */
430 void purple_conversation_close_logs(PurpleConversation *conv); 430 void purple_conversation_close_logs(PurpleConversation *conv);
431 431
432 /** 432 /**
433 * Writes to a conversation window. 433 * Writes to a conversation window.
439 * IM. 439 * IM.
440 * 440 *
441 * This can be used to write generic messages, such as "so and so closed 441 * This can be used to write generic messages, such as "so and so closed
442 * the conversation window." 442 * the conversation window."
443 * 443 *
444 * @conv: The conversation. 444 * @param conv The conversation.
445 * @who: The user who sent the message. 445 * @param who The user who sent the message.
446 * @message: The message. 446 * @param message The message.
447 * @flags: The message flags. 447 * @param flags The message flags.
448 * @mtime: The time the message was sent. 448 * @param mtime The time the message was sent.
449 * 449 *
450 * @see purple_conversation_write_message() 450 * @see purple_conversation_write_message()
451 */ 451 */
452 void purple_conversation_write(PurpleConversation *conv, const char *who, 452 void purple_conversation_write(PurpleConversation *conv, const char *who,
453 const char *message, PurpleMessageFlags flags, 453 const char *message, PurpleMessageFlags flags,
454 time_t mtime); 454 time_t mtime);
455 455
456 /** 456 /**
457 * Writes to a chat or an IM. 457 * Writes to a chat or an IM.
458 * 458 *
459 * @conv: The conversation. 459 * @param conv The conversation.
460 * @who: The user who sent the message. 460 * @param who The user who sent the message.
461 * @message: The message to write. 461 * @param message The message to write.
462 * @flags: The message flags. 462 * @param flags The message flags.
463 * @mtime: The time the message was sent. 463 * @param mtime The time the message was sent.
464 */ 464 */
465 void purple_conversation_write_message(PurpleConversation *conv, 465 void purple_conversation_write_message(PurpleConversation *conv,
466 const char *who, const char *message, 466 const char *who, const char *message,
467 PurpleMessageFlags flags, time_t mtime); 467 PurpleMessageFlags flags, time_t mtime);
468 468
469 /** 469 /**
470 * Sends a message to this conversation. This function calls 470 * Sends a message to this conversation. This function calls
471 * purple_conversation_send_with_flags() with no additional flags. 471 * purple_conversation_send_with_flags() with no additional flags.
472 * 472 *
473 * @conv: The conversation. 473 * @param conv The conversation.
474 * @message: The message to send. 474 * @param message The message to send.
475 */ 475 */
476 void purple_conversation_send(PurpleConversation *conv, const char *message); 476 void purple_conversation_send(PurpleConversation *conv, const char *message);
477 477
478 /** 478 /**
479 * Sends a message to this conversation with specified flags. 479 * Sends a message to this conversation with specified flags.
480 * 480 *
481 * @conv: The conversation. 481 * @param conv The conversation.
482 * @message: The message to send. 482 * @param message The message to send.
483 * @flags: The PurpleMessageFlags flags to use in addition to 483 * @param flags The PurpleMessageFlags flags to use in addition to
484 * PURPLE_MESSAGE_SEND. 484 * PURPLE_MESSAGE_SEND.
485 */ 485 */
486 void purple_conversation_send_with_flags(PurpleConversation *conv, const char *message, 486 void purple_conversation_send_with_flags(PurpleConversation *conv, const char *message,
487 PurpleMessageFlags flags); 487 PurpleMessageFlags flags);
488 488
489 /** 489 /**
490 Set the features as supported for the given conversation. 490 Set the features as supported for the given conversation.
491 @conv: The conversation 491 @param conv The conversation
492 @features: Bitset defining supported features 492 @param features Bitset defining supported features
493 */ 493 */
494 void purple_conversation_set_features(PurpleConversation *conv, 494 void purple_conversation_set_features(PurpleConversation *conv,
495 PurpleConnectionFlags features); 495 PurpleConnectionFlags features);
496 496
497 497
498 /** 498 /**
499 Get the features supported by the given conversation. 499 Get the features supported by the given conversation.
500 @conv: The conversation 500 @param conv The conversation
501 */ 501 */
502 PurpleConnectionFlags purple_conversation_get_features(PurpleConversation *conv); 502 PurpleConnectionFlags purple_conversation_get_features(PurpleConversation *conv);
503 503
504 /** 504 /**
505 * Determines if a conversation has focus 505 * Determines if a conversation has focus
506 * 506 *
507 * @conv: The conversation. 507 * @param conv The conversation.
508 * 508 *
509 * Returns: %TRUE if the conversation has focus, %FALSE if 509 * @return @c TRUE if the conversation has focus, @c FALSE if
510 * it does not or the UI does not have a concept of conversation focus 510 * it does not or the UI does not have a concept of conversation focus
511 */ 511 */
512 gboolean purple_conversation_has_focus(PurpleConversation *conv); 512 gboolean purple_conversation_has_focus(PurpleConversation *conv);
513 513
514 /** 514 /**
515 * Updates the visual status and UI of a conversation. 515 * Updates the visual status and UI of a conversation.
516 * 516 *
517 * @conv: The conversation. 517 * @param conv The conversation.
518 * @type: The update type. 518 * @param type The update type.
519 */ 519 */
520 void purple_conversation_update(PurpleConversation *conv, PurpleConversationUpdateType type); 520 void purple_conversation_update(PurpleConversation *conv, PurpleConversationUpdateType type);
521 521
522 /** 522 /**
523 * Retrieve the message history of a conversation. 523 * Retrieve the message history of a conversation.
524 * 524 *
525 * @conv: The conversation 525 * @param conv The conversation
526 * 526 *
527 * Returns: A GList of PurpleConversationMessage's. The must not modify the list or the data within. 527 * @return A GList of PurpleConversationMessage's. The must not modify the list or the data within.
528 * The list contains the newest message at the beginning, and the oldest message at 528 * The list contains the newest message at the beginning, and the oldest message at
529 * the end. 529 * the end.
530 */ 530 */
531 GList *purple_conversation_get_message_history(PurpleConversation *conv); 531 GList *purple_conversation_get_message_history(PurpleConversation *conv);
532 532
533 /** 533 /**
534 * Clear the message history of a conversation. 534 * Clear the message history of a conversation.
535 * 535 *
536 * @conv: The conversation 536 * @param conv The conversation
537 */ 537 */
538 void purple_conversation_clear_message_history(PurpleConversation *conv); 538 void purple_conversation_clear_message_history(PurpleConversation *conv);
539 539
540 /** 540 /**
541 * Set the UI data associated with this conversation. 541 * Set the UI data associated with this conversation.
542 * 542 *
543 * @conv: The conversation. 543 * @param conv The conversation.
544 * @ui_data: A pointer to associate with this conversation. 544 * @param ui_data A pointer to associate with this conversation.
545 */ 545 */
546 void purple_conversation_set_ui_data(PurpleConversation *conv, gpointer ui_data); 546 void purple_conversation_set_ui_data(PurpleConversation *conv, gpointer ui_data);
547 547
548 /** 548 /**
549 * Get the UI data associated with this conversation. 549 * Get the UI data associated with this conversation.
550 * 550 *
551 * @conv: The conversation. 551 * @param conv The conversation.
552 * 552 *
553 * Returns: The UI data associated with this conversation. This is a 553 * @return The UI data associated with this conversation. This is a
554 * convenience field provided to the UIs--it is not 554 * convenience field provided to the UIs--it is not
555 * used by the libpurple core. 555 * used by the libpurple core.
556 */ 556 */
557 gpointer purple_conversation_get_ui_data(const PurpleConversation *conv); 557 gpointer purple_conversation_get_ui_data(const PurpleConversation *conv);
558 558
563 * This function is intended for use in cases where the user 563 * This function is intended for use in cases where the user
564 * hasn't explicitly and knowingly caused a message to be sent. 564 * hasn't explicitly and knowingly caused a message to be sent.
565 * The confirmation ensures that the user isn't sending a 565 * The confirmation ensures that the user isn't sending a
566 * message by mistake. 566 * message by mistake.
567 * 567 *
568 * @conv: The conversation. 568 * @param conv The conversation.
569 * @message: The message to send. 569 * @param message The message to send.
570 */ 570 */
571 void purple_conversation_send_confirm(PurpleConversation *conv, const char *message); 571 void purple_conversation_send_confirm(PurpleConversation *conv, const char *message);
572 572
573 /** 573 /**
574 * Adds a smiley to the conversation's smiley tree. If this returns 574 * Adds a smiley to the conversation's smiley tree. If this returns
575 * %TRUE you should call purple_conversation_custom_smiley_write() one or more 575 * @c TRUE you should call purple_conversation_custom_smiley_write() one or more
576 * times, and then purple_conversation_custom_smiley_close(). If this returns 576 * times, and then purple_conversation_custom_smiley_close(). If this returns
577 * %FALSE, either the conv or smile were invalid, or the icon was 577 * @c FALSE, either the conv or smile were invalid, or the icon was
578 * found in the cache. In either case, calling write or close would 578 * found in the cache. In either case, calling write or close would
579 * be an error. 579 * be an error.
580 * 580 *
581 * @conv: The conversation to associate the smiley with. 581 * @param conv The conversation to associate the smiley with.
582 * @smile: The text associated with the smiley 582 * @param smile The text associated with the smiley
583 * @cksum_type: The type of checksum. 583 * @param cksum_type The type of checksum.
584 * @chksum: The checksum, as a NUL terminated base64 string. 584 * @param chksum The checksum, as a NUL terminated base64 string.
585 * @remote: %TRUE if the custom smiley is set by the remote user (buddy). 585 * @param remote @c TRUE if the custom smiley is set by the remote user (buddy).
586 * Returns: %TRUE if an icon is expected, else FALSE. Note that 586 * @return @c TRUE if an icon is expected, else FALSE. Note that
587 * it is an error to never call purple_conversation_custom_smiley_close if 587 * it is an error to never call purple_conversation_custom_smiley_close if
588 * this function returns %TRUE, but an error to call it if 588 * this function returns @c TRUE, but an error to call it if
589 * %FALSE is returned. 589 * @c FALSE is returned.
590 */ 590 */
591 591
592 gboolean purple_conversation_custom_smiley_add(PurpleConversation *conv, const char *smile, 592 gboolean purple_conversation_custom_smiley_add(PurpleConversation *conv, const char *smile,
593 const char *cksum_type, const char *chksum, 593 const char *cksum_type, const char *chksum,
594 gboolean remote); 594 gboolean remote);
595 595
596 /** 596 /**
597 * Updates the image associated with the current smiley. 597 * Updates the image associated with the current smiley.
598 * 598 *
599 * @conv: The conversation associated with the smiley. 599 * @param conv The conversation associated with the smiley.
600 * @smile: The text associated with the smiley. 600 * @param smile The text associated with the smiley.
601 * @data: The actual image data. 601 * @param data The actual image data.
602 * @size: The length of the data. 602 * @param size The length of the data.
603 */ 603 */
604 604
605 void purple_conversation_custom_smiley_write(PurpleConversation *conv, 605 void purple_conversation_custom_smiley_write(PurpleConversation *conv,
606 const char *smile, 606 const char *smile,
607 const guchar *data, 607 const guchar *data,
610 /** 610 /**
611 * Close the custom smiley, all data has been written with 611 * Close the custom smiley, all data has been written with
612 * purple_conversation_custom_smiley_write, and it is no longer valid 612 * purple_conversation_custom_smiley_write, and it is no longer valid
613 * to call that function on that smiley. 613 * to call that function on that smiley.
614 * 614 *
615 * @conv: The purple conversation associated with the smiley. 615 * @param conv The purple conversation associated with the smiley.
616 * @smile: The text associated with the smiley 616 * @param smile The text associated with the smiley
617 */ 617 */
618 618
619 void purple_conversation_custom_smiley_close(PurpleConversation *conv, const char *smile); 619 void purple_conversation_custom_smiley_close(PurpleConversation *conv, const char *smile);
620 620
621 /** 621 /**
622 * Retrieves the extended menu items for the conversation. 622 * Retrieves the extended menu items for the conversation.
623 * 623 *
624 * @conv: The conversation. 624 * @param conv The conversation.
625 * 625 *
626 * Returns: A list of PurpleMenuAction items, harvested by the 626 * @return A list of PurpleMenuAction items, harvested by the
627 * chat-extended-menu signal. The list and the menuaction 627 * chat-extended-menu signal. The list and the menuaction
628 * items should be freed by the caller. 628 * items should be freed by the caller.
629 */ 629 */
630 GList * purple_conversation_get_extended_menu(PurpleConversation *conv); 630 GList * purple_conversation_get_extended_menu(PurpleConversation *conv);
631 631
632 /** 632 /**
633 * Perform a command in a conversation. Similar to @see purple_cmd_do_command 633 * Perform a command in a conversation. Similar to @see purple_cmd_do_command
634 * 634 *
635 * @conv: The conversation. 635 * @param conv The conversation.
636 * @cmdline: The entire command including the arguments. 636 * @param cmdline The entire command including the arguments.
637 * @markup: %NULL, or the formatted command line. 637 * @param markup @c NULL, or the formatted command line.
638 * @error: If the command failed errormsg is filled in with the appropriate error 638 * @param error If the command failed errormsg is filled in with the appropriate error
639 * message, if not %NULL. It must be freed by the caller with g_free(). 639 * message, if not @c NULL. It must be freed by the caller with g_free().
640 * 640 *
641 * Returns: %TRUE if the command was executed successfully, %FALSE otherwise. 641 * @return @c TRUE if the command was executed successfully, @c FALSE otherwise.
642 */ 642 */
643 gboolean purple_conversation_do_command(PurpleConversation *conv, 643 gboolean purple_conversation_do_command(PurpleConversation *conv,
644 const gchar *cmdline, const gchar *markup, gchar **error); 644 const gchar *cmdline, const gchar *markup, gchar **error);
645 645
646 /** 646 /**
647 * Gets the maximum message size in bytes for the conversation. 647 * Gets the maximum message size in bytes for the conversation.
648 * 648 *
649 * @see PurplePluginProtocolInfo#get_max_message_size 649 * @see PurplePluginProtocolInfo#get_max_message_size
650 * 650 *
651 * @conv: The conversation to query. 651 * @param conv The conversation to query.
652 * 652 *
653 * Returns: Maximum message size, 0 if unspecified, -1 for infinite. 653 * @return Maximum message size, 0 if unspecified, -1 for infinite.
654 */ 654 */
655 gssize 655 gssize
656 purple_conversation_get_max_message_size(PurpleConversation *conv); 656 purple_conversation_get_max_message_size(PurpleConversation *conv);
657 657
658 /*@}*/ 658 /*@}*/
668 * This is a helper function to find a conversation, write an error to it, and 668 * This is a helper function to find a conversation, write an error to it, and
669 * raise the window. If a conversation with this user doesn't already exist, 669 * raise the window. If a conversation with this user doesn't already exist,
670 * the function will return FALSE and the calling function can attempt to present 670 * the function will return FALSE and the calling function can attempt to present
671 * the error another way (purple_notify_error, most likely) 671 * the error another way (purple_notify_error, most likely)
672 * 672 *
673 * @who: The user this error is about 673 * @param who The user this error is about
674 * @account: The account this error is on 674 * @param account The account this error is on
675 * @what: The error 675 * @param what The error
676 * Returns: TRUE if the error was presented, else FALSE 676 * @return TRUE if the error was presented, else FALSE
677 */ 677 */
678 gboolean purple_conversation_present_error(const char *who, PurpleAccount *account, const char *what); 678 gboolean purple_conversation_present_error(const char *who, PurpleAccount *account, const char *what);
679 679
680 /*@}*/ 680 /*@}*/
681 681
690 GType purple_conversation_message_get_type(void); 690 GType purple_conversation_message_get_type(void);
691 691
692 /** 692 /**
693 * Get the sender from a PurpleConversationMessage 693 * Get the sender from a PurpleConversationMessage
694 * 694 *
695 * @msg: A PurpleConversationMessage 695 * @param msg A PurpleConversationMessage
696 * 696 *
697 * Returns: The name of the sender of the message 697 * @return The name of the sender of the message
698 */ 698 */
699 const char *purple_conversation_message_get_sender(const PurpleConversationMessage *msg); 699 const char *purple_conversation_message_get_sender(const PurpleConversationMessage *msg);
700 700
701 /** 701 /**
702 * Get the message from a PurpleConversationMessage 702 * Get the message from a PurpleConversationMessage
703 * 703 *
704 * @msg: A PurpleConversationMessage 704 * @param msg A PurpleConversationMessage
705 * 705 *
706 * Returns: The name of the sender of the message 706 * @return The name of the sender of the message
707 */ 707 */
708 const char *purple_conversation_message_get_message(const PurpleConversationMessage *msg); 708 const char *purple_conversation_message_get_message(const PurpleConversationMessage *msg);
709 709
710 /** 710 /**
711 * Get the message-flags of a PurpleConversationMessage 711 * Get the message-flags of a PurpleConversationMessage
712 * 712 *
713 * @msg: A PurpleConversationMessage 713 * @param msg A PurpleConversationMessage
714 * 714 *
715 * Returns: The message flags 715 * @return The message flags
716 */ 716 */
717 PurpleMessageFlags purple_conversation_message_get_flags(const PurpleConversationMessage *msg); 717 PurpleMessageFlags purple_conversation_message_get_flags(const PurpleConversationMessage *msg);
718 718
719 /** 719 /**
720 * Get the timestamp of a PurpleConversationMessage 720 * Get the timestamp of a PurpleConversationMessage
721 * 721 *
722 * @msg: A PurpleConversationMessage 722 * @param msg A PurpleConversationMessage
723 * 723 *
724 * Returns: The timestamp of the message 724 * @return The timestamp of the message
725 */ 725 */
726 time_t purple_conversation_message_get_timestamp(const PurpleConversationMessage *msg); 726 time_t purple_conversation_message_get_timestamp(const PurpleConversationMessage *msg);
727 727
728 /** 728 /**
729 * Get the alias from a PurpleConversationMessage 729 * Get the alias from a PurpleConversationMessage
730 * 730 *
731 * @msg: A PurpleConversationMessage 731 * @param msg A PurpleConversationMessage
732 * 732 *
733 * Returns: The alias of the sender of the message 733 * @return The alias of the sender of the message
734 */ 734 */
735 const char *purple_conversation_message_get_alias(const PurpleConversationMessage *msg); 735 const char *purple_conversation_message_get_alias(const PurpleConversationMessage *msg);
736 736
737 /** 737 /**
738 * Get the conversation associated with the PurpleConversationMessage 738 * Get the conversation associated with the PurpleConversationMessage
739 * 739 *
740 * @msg: A PurpleConversationMessage 740 * @param msg A PurpleConversationMessage
741 * 741 *
742 * Returns: The conversation 742 * @return The conversation
743 */ 743 */
744 PurpleConversation *purple_conversation_message_get_conversation(const PurpleConversationMessage *msg); 744 PurpleConversation *purple_conversation_message_get_conversation(const PurpleConversationMessage *msg);
745 745
746 /*@}*/ 746 /*@}*/
747 747

Mercurial Repository: pidgin3

mercurial