libpurple/conversationtypes.h

   1 /* purple
   2  *
   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.
   6  *
   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.
  11  *
  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.
  16  *
  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
  20  */
  21
  22 #ifndef _PURPLE_CONVERSATION_TYPES_H_
  23 #define _PURPLE_CONVERSATION_TYPES_H_
  24 /**
  25  * SECTION:conversationtypes
  26  * @section_id: libpurple-conversationtypes
  27  * @short_description: <filename>conversationtypes.h</filename>
  28  * @title: Chat and IM Conversation Objects
  29  */
  30
  31 /**************************************************************************/
  32 /* Data Structures                                                        */
  33 /**************************************************************************/
  34
  35 #define PURPLE_TYPE_IM_CONVERSATION              (purple_im_conversation_get_type())
  36 #define PURPLE_IM_CONVERSATION(obj)              (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_IM_CONVERSATION, PurpleIMConversation))
  37 #define PURPLE_IM_CONVERSATION_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_IM_CONVERSATION, PurpleIMConversationClass))
  38 #define PURPLE_IS_IM_CONVERSATION(obj)           (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_IM_CONVERSATION))
  39 #define PURPLE_IS_IM_CONVERSATION_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_IM_CONVERSATION))
  40 #define PURPLE_IM_CONVERSATION_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_IM_CONVERSATION, PurpleIMConversationClass))
  41
  42 typedef struct _PurpleIMConversation         PurpleIMConversation;
  43 typedef struct _PurpleIMConversationClass    PurpleIMConversationClass;
  44
  45 #define PURPLE_TYPE_CHAT_CONVERSATION            (purple_chat_conversation_get_type())
  46 #define PURPLE_CHAT_CONVERSATION(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_CHAT_CONVERSATION, PurpleChatConversation))
  47 #define PURPLE_CHAT_CONVERSATION_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_CHAT_CONVERSATION, PurpleChatConversationClass))
  48 #define PURPLE_IS_CHAT_CONVERSATION(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_CHAT_CONVERSATION))
  49 #define PURPLE_IS_CHAT_CONVERSATION_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_CHAT_CONVERSATION))
  50 #define PURPLE_CHAT_CONVERSATION_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_CHAT_CONVERSATION, PurpleChatConversationClass))
  51
  52 typedef struct _PurpleChatConversation       PurpleChatConversation;
  53 typedef struct _PurpleChatConversationClass  PurpleChatConversationClass;
  54
  55 #define PURPLE_TYPE_CHAT_USER                    (purple_chat_user_get_type())
  56 #define PURPLE_CHAT_USER(obj)                    (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_CHAT_USER, PurpleChatUser))
  57 #define PURPLE_CHAT_USER_CLASS(klass)            (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_CHAT_USER, PurpleChatUserClass))
  58 #define PURPLE_IS_CHAT_USER(obj)                 (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_CHAT_USER))
  59 #define PURPLE_IS_CHAT_USER_CLASS(klass)         (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_CHAT_USER))
  60 #define PURPLE_CHAT_USER_GET_CLASS(obj)          (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_CHAT_USER, PurpleChatUserClass))
  61
  62 typedef struct _PurpleChatUser       PurpleChatUser;
  63 typedef struct _PurpleChatUserClass  PurpleChatUserClass;
  64
  65 /**
  66  * PurpleIMTypingState:
  67  * @PURPLE_IM_NOT_TYPING: Not typing.
  68  * @PURPLE_IM_TYPING:     Currently typing.
  69  * @PURPLE_IM_TYPED:      Stopped typing momentarily.
  70  *
  71  * The typing state of a user.
  72  */
  73 typedef enum
  74 {
  75         PURPLE_IM_NOT_TYPING = 0,
  76         PURPLE_IM_TYPING,
  77         PURPLE_IM_TYPED
  78
  79 } PurpleIMTypingState;
  80
  81 /**
  82  * PurpleChatUserFlags:
  83  * @PURPLE_CHAT_USER_NONE:    No flags
  84  * @PURPLE_CHAT_USER_VOICE:   Voiced user or "Participant"
  85  * @PURPLE_CHAT_USER_HALFOP:  Half-op
  86  * @PURPLE_CHAT_USER_OP:      Channel Op or Moderator
  87  * @PURPLE_CHAT_USER_FOUNDER: Channel Founder
  88  * @PURPLE_CHAT_USER_TYPING:  Currently typing
  89  * @PURPLE_CHAT_USER_AWAY:    Currently away.
  90  *
  91  * Flags applicable to users in Chats.
  92  */
  93 typedef enum /*< flags >*/
  94 {
  95         PURPLE_CHAT_USER_NONE     = 0x0000,
  96         PURPLE_CHAT_USER_VOICE    = 0x0001,
  97         PURPLE_CHAT_USER_HALFOP   = 0x0002,
  98         PURPLE_CHAT_USER_OP       = 0x0004,
  99         PURPLE_CHAT_USER_FOUNDER  = 0x0008,
 100         PURPLE_CHAT_USER_TYPING   = 0x0010,
 101         PURPLE_CHAT_USER_AWAY     = 0x0020
 102
 103 } PurpleChatUserFlags;
 104
 105 #include "conversation.h"
 106
 107 /**************************************************************************/
 108 /* PurpleIMConversation                                                   */
 109 /**************************************************************************/
 110 /**
 111  * PurpleIMConversation:
 112  *
 113  * Structure representing an IM conversation instance.
 114  */
 115 struct _PurpleIMConversation
 116 {
 117         PurpleConversation parent_object;
 118 };
 119
 120 /**
 121  * PurpleIMConversationClass:
 122  *
 123  * Base class for all #PurpleIMConversation's
 124  */
 125 struct _PurpleIMConversationClass {
 126         PurpleConversationClass parent_class;
 127
 128         /*< private >*/
 129         void (*_purple_reserved1)(void);
 130         void (*_purple_reserved2)(void);
 131         void (*_purple_reserved3)(void);
 132         void (*_purple_reserved4)(void);
 133 };
 134
 135 /**************************************************************************/
 136 /* PurpleChatConversation                                                 */
 137 /**************************************************************************/
 138 /**
 139  * PurpleChatConversation:
 140  *
 141  * Structure representing a chat conversation instance.
 142  */
 143 struct _PurpleChatConversation
 144 {
 145         PurpleConversation parent_object;
 146 };
 147
 148 /**
 149  * PurpleChatConversationClass:
 150  *
 151  * Base class for all #PurpleChatConversation's
 152  */
 153 struct _PurpleChatConversationClass {
 154         PurpleConversationClass parent_class;
 155
 156         /*< private >*/
 157         void (*_purple_reserved1)(void);
 158         void (*_purple_reserved2)(void);
 159         void (*_purple_reserved3)(void);
 160         void (*_purple_reserved4)(void);
 161 };
 162
 163 /**************************************************************************/
 164 /* PurpleChatUser                                                         */
 165 /**************************************************************************/
 166 /**
 167  * PurpleChatUser:
 168  * @ui_data: The UI data associated with this chat user. This is a convenience
 169  *           field provided to the UIs -- it is not used by the libpurple core.
 170  *
 171  * Structure representing a chat user instance.
 172  */
 173 struct _PurpleChatUser
 174 {
 175         GObject gparent;
 176
 177         /*< public >*/
 178         gpointer ui_data;
 179 };
 180
 181 /**
 182  * PurpleChatUserClass:
 183  *
 184  * Base class for all #PurpleChatUser's
 185  */
 186 struct _PurpleChatUserClass {
 187         GObjectClass parent_class;
 188
 189         /*< private >*/
 190         void (*_purple_reserved1)(void);
 191         void (*_purple_reserved2)(void);
 192         void (*_purple_reserved3)(void);
 193         void (*_purple_reserved4)(void);
 194 };
 195
 196 G_BEGIN_DECLS
 197
 198 /**************************************************************************/
 199 /* IM Conversation API                                                    */
 200 /**************************************************************************/
 201
 202 /**
 203  * purple_im_conversation_get_type:
 204  *
 205  * Returns: The #GType for the IMConversation object.
 206  */
 207 GType purple_im_conversation_get_type(void);
 208
 209 /**
 210  * purple_im_conversation_new:
 211  * @account: The account opening the conversation window on the purple
 212  *                user's end.
 213  * @name:    Name of the buddy.
 214  *
 215  * Creates a new IM conversation.
 216  *
 217  * Returns: The new conversation.
 218  */
 219 PurpleIMConversation *purple_im_conversation_new(PurpleAccount *account,
 220                 const char *name);
 221
 222 /**
 223  * purple_im_conversation_set_icon:
 224  * @im:   The IM.
 225  * @icon: The buddy icon.
 226  *
 227  * Sets the IM's buddy icon.
 228  *
 229  * This should only be called from within Purple. You probably want to
 230  * call purple_buddy_icon_set_data().
 231  *
 232  * See purple_buddy_icon_set_data().
 233  */
 234 void purple_im_conversation_set_icon(PurpleIMConversation *im, PurpleBuddyIcon *icon);
 235
 236 /**
 237  * purple_im_conversation_get_icon:
 238  * @im: The IM.
 239  *
 240  * Returns the IM's buddy icon.
 241  *
 242  * Returns: The buddy icon.
 243  */
 244 PurpleBuddyIcon *purple_im_conversation_get_icon(const PurpleIMConversation *im);
 245
 246 /**
 247  * purple_im_conversation_set_typing_state:
 248  * @im:    The IM.
 249  * @state: The typing state.
 250  *
 251  * Sets the IM's typing state.
 252  */
 253 void purple_im_conversation_set_typing_state(PurpleIMConversation *im, PurpleIMTypingState state);
 254
 255 /**
 256  * purple_im_conversation_get_typing_state:
 257  * @im: The IM.
 258  *
 259  * Returns the IM's typing state.
 260  *
 261  * Returns: The IM's typing state.
 262  */
 263 PurpleIMTypingState purple_im_conversation_get_typing_state(const PurpleIMConversation *im);
 264
 265 /**
 266  * purple_im_conversation_start_typing_timeout:
 267  * @im:      The IM.
 268  * @timeout: How long in seconds to wait before setting the typing state
 269  *        to PURPLE_IM_NOT_TYPING.
 270  *
 271  * Starts the IM's typing timeout.
 272  */
 273 void purple_im_conversation_start_typing_timeout(PurpleIMConversation *im, int timeout);
 274
 275 /**
 276  * purple_im_conversation_stop_typing_timeout:
 277  * @im: The IM.
 278  *
 279  * Stops the IM's typing timeout.
 280  */
 281 void purple_im_conversation_stop_typing_timeout(PurpleIMConversation *im);
 282
 283 /**
 284  * purple_im_conversation_get_typing_timeout:
 285  * @im: The IM.
 286  *
 287  * Returns the IM's typing timeout.
 288  *
 289  * Returns: The timeout.
 290  */
 291 guint purple_im_conversation_get_typing_timeout(const PurpleIMConversation *im);
 292
 293 /**
 294  * purple_im_conversation_set_type_again:
 295  * @im:  The IM.
 296  * @val: The number of seconds to wait before allowing another
 297  *            PURPLE_IM_TYPING message to be sent to the user.  Or 0 to
 298  *            not send another PURPLE_IM_TYPING message.
 299  *
 300  * Sets the quiet-time when no PURPLE_IM_TYPING messages will be sent.
 301  * Few protocols need this (maybe only MSN).  If the user is still
 302  * typing after this quiet-period, then another PURPLE_IM_TYPING message
 303  * will be sent.
 304  */
 305 void purple_im_conversation_set_type_again(PurpleIMConversation *im, unsigned int val);
 306
 307 /**
 308  * purple_im_conversation_get_type_again:
 309  * @im: The IM.
 310  *
 311  * Returns the time after which another PURPLE_IM_TYPING message should be sent.
 312  *
 313  * Returns: The time in seconds since the epoch.  Or 0 if no additional
 314  *         PURPLE_IM_TYPING message should be sent.
 315  */
 316 time_t purple_im_conversation_get_type_again(const PurpleIMConversation *im);
 317
 318 /**
 319  * purple_im_conversation_start_send_typed_timeout:
 320  * @im:      The IM.
 321  *
 322  * Starts the IM's type again timeout.
 323  */
 324 void purple_im_conversation_start_send_typed_timeout(PurpleIMConversation *im);
 325
 326 /**
 327  * purple_im_conversation_stop_send_typed_timeout:
 328  * @im: The IM.
 329  *
 330  * Stops the IM's type again timeout.
 331  */
 332 void purple_im_conversation_stop_send_typed_timeout(PurpleIMConversation *im);
 333
 334 /**
 335  * purple_im_conversation_get_send_typed_timeout:
 336  * @im: The IM.
 337  *
 338  * Returns the IM's type again timeout interval.
 339  *
 340  * Returns: The type again timeout interval.
 341  */
 342 guint purple_im_conversation_get_send_typed_timeout(const PurpleIMConversation *im);
 343
 344 /**
 345  * purple_im_conversation_update_typing:
 346  * @im: The IM.
 347  *
 348  * Updates the visual typing notification for an IM conversation.
 349  */
 350 void purple_im_conversation_update_typing(PurpleIMConversation *im);
 351
 352 /**************************************************************************/
 353 /* Chat Conversation API                                                  */
 354 /**************************************************************************/
 355
 356 /**
 357  * purple_chat_conversation_get_type:
 358  *
 359  * Returns: The #GType for the ChatConversation object.
 360  */
 361 GType purple_chat_conversation_get_type(void);
 362
 363 /**
 364  * purple_chat_conversation_new:
 365  * @account: The account opening the conversation window on the purple
 366  *                user's end.
 367  * @name:    The name of the conversation.
 368  *
 369  * Creates a new chat conversation.
 370  *
 371  * Returns: The new conversation.
 372  */
 373 PurpleChatConversation *purple_chat_conversation_new(PurpleAccount *account,
 374                 const char *name);
 375
 376 /**
 377  * purple_chat_conversation_get_users:
 378  * @chat: The chat.
 379  *
 380  * Returns a list of users in the chat room.  The members of the list
 381  * are PurpleChatUser objects.
 382  *
 383  * Returns: (element-type PurpleChatUser) (transfer container):
 384  *          The list of users. Use g_list_free() when done
 385  *          using the list.
 386  */
 387 GList *purple_chat_conversation_get_users(const PurpleChatConversation *chat);
 388
 389 /**
 390  * purple_chat_conversation_get_users_count:
 391  * @chat: The chat.
 392  *
 393  * Returns count of users in the chat room.
 394  *
 395  * Returns: The count of users in the chat room.
 396  */
 397 guint
 398 purple_chat_conversation_get_users_count(const PurpleChatConversation *chat);
 399
 400 /**
 401  * purple_chat_conversation_ignore:
 402  * @chat: The chat.
 403  * @name: The name of the user.
 404  *
 405  * Ignores a user in a chat room.
 406  */
 407 void purple_chat_conversation_ignore(PurpleChatConversation *chat, const char *name);
 408
 409 /**
 410  * purple_chat_conversation_unignore:
 411  * @chat: The chat.
 412  * @name: The name of the user.
 413  *
 414  * Unignores a user in a chat room.
 415  */
 416 void purple_chat_conversation_unignore(PurpleChatConversation *chat, const char *name);
 417
 418 /**
 419  * purple_chat_conversation_set_ignored:
 420  * @chat:    The chat.
 421  * @ignored: (element-type char*):
 422  *           The list of ignored users.
 423  *
 424  * Sets the list of ignored users in the chat room.
 425  *
 426  * Returns: (element-type char*) (transfer none):
 427  *          The list passed.
 428  */
 429 GList *purple_chat_conversation_set_ignored(PurpleChatConversation *chat, GList *ignored);
 430
 431 /**
 432  * purple_chat_conversation_get_ignored:
 433  * @chat: The chat.
 434  *
 435  * Returns the list of ignored users in the chat room.
 436  *
 437  * Returns: (element-type char*) (transfer none):
 438  *          The list of ignored users.
 439  */
 440 GList *purple_chat_conversation_get_ignored(const PurpleChatConversation *chat);
 441
 442 /**
 443  * purple_chat_conversation_get_ignored_user:
 444  * @chat: The chat.
 445  * @user: The user to check in the ignore list.
 446  *
 447  * Returns the actual name of the specified ignored user, if it exists in
 448  * the ignore list.
 449  *
 450  * If the user found contains a prefix, such as '+' or '\@', this is also
 451  * returned. The username passed to the function does not have to have this
 452  * formatting.
 453  *
 454  * Returns: The ignored user if found, complete with prefixes, or %NULL
 455  *         if not found.
 456  */
 457 const char *purple_chat_conversation_get_ignored_user(const PurpleChatConversation *chat,
 458                                                                                         const char *user);
 459
 460 /**
 461  * purple_chat_conversation_is_ignored_user:
 462  * @chat: The chat.
 463  * @user: The user.
 464  *
 465  * Returns %TRUE if the specified user is ignored.
 466  *
 467  * Returns: %TRUE if the user is in the ignore list; %FALSE otherwise.
 468  */
 469 gboolean purple_chat_conversation_is_ignored_user(const PurpleChatConversation *chat,
 470                                                                                 const char *user);
 471
 472 /**
 473  * purple_chat_conversation_set_topic:
 474  * @chat:  The chat.
 475  * @who:   The user that set the topic.
 476  * @topic: The topic.
 477  *
 478  * Sets the chat room's topic.
 479  */
 480 void purple_chat_conversation_set_topic(PurpleChatConversation *chat, const char *who,
 481                                                           const char *topic);
 482
 483 /**
 484  * purple_chat_conversation_get_topic:
 485  * @chat: The chat.
 486  *
 487  * Returns the chat room's topic.
 488  *
 489  * Returns: The chat's topic.
 490  */
 491 const char *purple_chat_conversation_get_topic(const PurpleChatConversation *chat);
 492
 493 /**
 494  * purple_chat_conversation_get_topic_who:
 495  * @chat: The chat.
 496  *
 497  * Returns who set the chat room's topic.
 498  *
 499  * Returns: Who set the topic.
 500  */
 501 const char *purple_chat_conversation_get_topic_who(const PurpleChatConversation *chat);
 502
 503 /**
 504  * purple_chat_conversation_set_id:
 505  * @chat: The chat.
 506  * @id:   The ID.
 507  *
 508  * Sets the chat room's ID.
 509  */
 510 void purple_chat_conversation_set_id(PurpleChatConversation *chat, int id);
 511
 512 /**
 513  * purple_chat_conversation_get_id:
 514  * @chat: The chat.
 515  *
 516  * Returns the chat room's ID.
 517  *
 518  * Returns: The ID.
 519  */
 520 int purple_chat_conversation_get_id(const PurpleChatConversation *chat);
 521
 522 /**
 523  * purple_chat_conversation_add_user:
 524  * @chat:        The chat.
 525  * @user:        The user to add.
 526  * @extra_msg:   An extra message to display with the join message.
 527  * @flags:       The users flags
 528  * @new_arrival: Decides whether or not to show a join notice.
 529  *
 530  * Adds a user to a chat.
 531  */
 532 void purple_chat_conversation_add_user(PurpleChatConversation *chat, const char *user,
 533                                                          const char *extra_msg, PurpleChatUserFlags flags,
 534                                                          gboolean new_arrival);
 535
 536 /**
 537  * purple_chat_conversation_add_users:
 538  * @chat:         The chat.
 539  * @users: (element-type char*):
 540  *                The list of users to add.
 541  * @extra_msgs: (element-type char*) (nullable):
 542  *                An extra message to display with the join message for each
 543  *                     user.  This list may be shorter than @users, in which
 544  *                     case, the users after the end of extra_msgs will not have
 545  *                     an extra message.  By extension, this means that extra_msgs
 546  *                     can simply be %NULL and none of the users will have an
 547  *                     extra message.
 548  * @flags: (element-type PurpleChatUserFlags):
 549  *                The list of flags for each user.
 550  *                This list data should be an int converted to pointer using
 551  *                GINT_TO_POINTER(flag)
 552  * @new_arrivals: Decides whether or not to show join notices.
 553  *
 554  * Adds a list of users to a chat.
 555  *
 556  * The data is copied from @users, @extra_msgs, and @flags, so it is up to
 557  * the caller to free this list after calling this function.
 558  */
 559 void purple_chat_conversation_add_users(PurpleChatConversation *chat,
 560                 GList *users, GList *extra_msgs, GList *flags, gboolean new_arrivals);
 561
 562 /**
 563  * purple_chat_conversation_rename_user:
 564  * @chat:     The chat.
 565  * @old_user: The old username.
 566  * @new_user: The new username.
 567  *
 568  * Renames a user in a chat.
 569  */
 570 void purple_chat_conversation_rename_user(PurpleChatConversation *chat,
 571                 const char *old_user, const char *new_user);
 572
 573 /**
 574  * purple_chat_conversation_remove_user:
 575  * @chat:   The chat.
 576  * @user:   The user that is being removed.
 577  * @reason: The optional reason given for the removal. Can be %NULL.
 578  *
 579  * Removes a user from a chat, optionally with a reason.
 580  *
 581  * It is up to the developer to free this list after calling this function.
 582  */
 583 void purple_chat_conversation_remove_user(PurpleChatConversation *chat,
 584                 const char *user, const char *reason);
 585
 586 /**
 587  * purple_chat_conversation_remove_users:
 588  * @chat:   The chat.
 589  * @users: (element-type char*)
 590  *          The users that are being removed.
 591  * @reason: The optional reason given for the removal. Can be %NULL.
 592  *
 593  * Removes a list of users from a chat, optionally with a single reason.
 594  */
 595 void purple_chat_conversation_remove_users(PurpleChatConversation *chat,
 596                 GList *users, const char *reason);
 597
 598 /**
 599  * purple_chat_conversation_has_user:
 600  * @chat:   The chat.
 601  * @user:   The user to look for.
 602  *
 603  * Checks if a user is in a chat
 604  *
 605  * Returns: TRUE if the user is in the chat, FALSE if not
 606  */
 607 gboolean purple_chat_conversation_has_user(PurpleChatConversation *chat,
 608                 const char *user);
 609
 610 /**
 611  * purple_chat_conversation_clear_users:
 612  * @chat: The chat.
 613  *
 614  * Clears all users from a chat.
 615  */
 616 void purple_chat_conversation_clear_users(PurpleChatConversation *chat);
 617
 618 /**
 619  * purple_chat_conversation_set_nick:
 620  * @chat: The chat.
 621  * @nick: The nick.
 622  *
 623  * Sets your nickname (used for hilighting) for a chat.
 624  */
 625 void purple_chat_conversation_set_nick(PurpleChatConversation *chat,
 626                 const char *nick);
 627
 628 /**
 629  * purple_chat_conversation_get_nick:
 630  * @chat: The chat.
 631  *
 632  * Gets your nickname (used for hilighting) for a chat.
 633  *
 634  * Returns:  The nick.
 635  */
 636 const char *purple_chat_conversation_get_nick(PurpleChatConversation *chat);
 637
 638 /**
 639  * purple_chat_conversation_leave:
 640  * @chat: The chat.
 641  *
 642  * Lets the core know we left a chat, without destroying it.
 643  * Called from purple_serv_got_chat_left().
 644  */
 645 void purple_chat_conversation_leave(PurpleChatConversation *chat);
 646
 647 /**
 648  * purple_chat_conversation_find_user:
 649  * @chat: The chat.
 650  * @name: The name of the chat user to find.
 651  *
 652  * Find a chat user in a chat
 653  *
 654  * Returns: (transfer none):
 655  *         The @PurpleChatUser with the name refered by @name.
 656  */
 657 PurpleChatUser *purple_chat_conversation_find_user(PurpleChatConversation *chat,
 658                 const char *name);
 659
 660 /**
 661  * purple_chat_conversation_invite_user:
 662  * @chat:     The chat.
 663  * @user:     The user to invite to the chat.
 664  * @message:  The message to send with the invitation.
 665  * @confirm:  Prompt before sending the invitation. The user is always
 666  *            prompted if either \a user or \a message is %NULL.
 667  *
 668  * Invite a user to a chat.
 669  * The user will be prompted to enter the user's name or a message if one is
 670  * not given.
 671  */
 672 void purple_chat_conversation_invite_user(PurpleChatConversation *chat,
 673                 const char *user, const char *message, gboolean confirm);
 674
 675 /**
 676  * purple_chat_conversation_has_left:
 677  * @chat: The chat.
 678  *
 679  * Returns true if we're no longer in this chat,
 680  * and just left the window open.
 681  *
 682  * Returns: %TRUE if we left the chat already, %FALSE if
 683  * we're still there.
 684  */
 685 gboolean purple_chat_conversation_has_left(PurpleChatConversation *chat);
 686
 687 /**************************************************************************/
 688 /* Chat Conversation User API                                             */
 689 /**************************************************************************/
 690
 691 /**
 692  * purple_chat_user_get_type:
 693  *
 694  * Returns: The #GType for the ChatConversationBuddy object.
 695  */
 696 GType purple_chat_user_get_type(void);
 697
 698 /**
 699  * purple_chat_user_set_chat:
 700  * @cb: The chat user
 701  * @chat:       The chat conversation that the buddy belongs to.
 702  *
 703  * Set the chat conversation associated with this chat user.
 704  */
 705 void purple_chat_user_set_chat(PurpleChatUser *cb,
 706                 PurpleChatConversation *chat);
 707
 708 /**
 709  * purple_chat_user_get_chat:
 710  * @cb: The chat user.
 711  *
 712  * Get the chat conversation associated with this chat user.
 713  *
 714  * Returns: (transfer none):
 715  *          The chat conversation that the buddy belongs to.
 716  */
 717 PurpleChatConversation *purple_chat_user_get_chat(const PurpleChatUser *cb);
 718
 719 /**
 720  * purple_chat_user_new:
 721  * @chat: The chat that the buddy belongs to.
 722  * @name: The name.
 723  * @alias: The alias.
 724  * @flags: The flags.
 725  *
 726  * Creates a new chat user
 727  *
 728  * Returns: The new chat user
 729  */
 730 PurpleChatUser *purple_chat_user_new(PurpleChatConversation *chat,
 731                 const char *name, const char *alias, PurpleChatUserFlags flags);
 732
 733 /**
 734  * purple_chat_user_set_ui_data:
 735  * @cb:                 The chat user
 736  * @ui_data:            A pointer to associate with this chat user.
 737  *
 738  * Set the UI data associated with this chat user.
 739  */
 740 void purple_chat_user_set_ui_data(PurpleChatUser *cb, gpointer ui_data);
 741
 742 /**
 743  * purple_chat_user_get_ui_data:
 744  * @cb:                 The chat user.
 745  *
 746  * Get the UI data associated with this chat user.
 747  *
 748  * Returns: (transfer none):
 749  *         The UI data associated with this chat user.  This is a
 750  *         convenience field provided to the UIs--it is not
 751  *         used by the libpurple core.
 752  */
 753 gpointer purple_chat_user_get_ui_data(const PurpleChatUser *cb);
 754
 755 /**
 756  * purple_chat_user_get_alias:
 757  * @cb:    The chat user.
 758  *
 759  * Get the alias of a chat user
 760  *
 761  * Returns: The alias of the chat user.
 762  */
 763 const char *purple_chat_user_get_alias(const PurpleChatUser *cb);
 764
 765 /**
 766  * purple_chat_user_get_name:
 767  * @cb:    The chat user.
 768  *
 769  * Get the name of a chat user
 770  *
 771  * Returns: The name of the chat user.
 772  */
 773 const char *purple_chat_user_get_name(const PurpleChatUser *cb);
 774
 775 /**
 776  * purple_chat_user_set_flags:
 777  * @cb:     The chat user.
 778  * @flags:  The new flags.
 779  *
 780  * Set the flags of a chat user.
 781  */
 782 void purple_chat_user_set_flags(PurpleChatUser *cb, PurpleChatUserFlags flags);
 783
 784 /**
 785  * purple_chat_user_get_flags:
 786  * @cb: The chat user.
 787  *
 788  * Get the flags of a chat user.
 789  *
 790  * Returns: The flags of the chat user.
 791  */
 792 PurpleChatUserFlags purple_chat_user_get_flags(const PurpleChatUser *cb);
 793
 794 /**
 795  * purple_chat_user_is_buddy:
 796  * @cb: The chat user.
 797  *
 798  * Indicates if this chat user is on the buddy list.
 799  *
 800  * Returns: TRUE if the chat user is on the buddy list.
 801  */
 802 gboolean purple_chat_user_is_buddy(const PurpleChatUser *cb);
 803
 804 G_END_DECLS
 805
 806 #endif /* _PURPLE_CONVERSATION_TYPES_H_ */