libpurple/chat.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_CHAT_H
  23 #define PURPLE_CHAT_H
  24
  25 /**
  26  * SECTION:chat
  27  * @section_id: libpurple-chat
  28  * @short_description: <filename>chat.h</filename>
  29  * @title: Chat Object
  30  */
  31
  32 #define PURPLE_TYPE_CHAT             (purple_chat_get_type())
  33 #define PURPLE_CHAT(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_CHAT, PurpleChat))
  34 #define PURPLE_CHAT_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_CHAT, PurpleChatClass))
  35 #define PURPLE_IS_CHAT(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_CHAT))
  36 #define PURPLE_IS_CHAT_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_CHAT))
  37 #define PURPLE_CHAT_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_CHAT, PurpleChatClass))
  38
  39 typedef struct _PurpleChat PurpleChat;
  40 typedef struct _PurpleChatClass PurpleChatClass;
  41
  42 #include "blistnode.h"
  43 #include "group.h"
  44
  45 /**
  46  * PurpleChat:
  47  *
  48  * A chat on the buddy list.
  49  */
  50 struct _PurpleChat {
  51         PurpleBlistNode node;
  52 };
  53
  54 struct _PurpleChatClass {
  55         PurpleBlistNodeClass node_class;
  56
  57         /*< private >*/
  58         void (*_purple_reserved1)(void);
  59         void (*_purple_reserved2)(void);
  60         void (*_purple_reserved3)(void);
  61         void (*_purple_reserved4)(void);
  62 };
  63
  64 G_BEGIN_DECLS
  65
  66 /**
  67  * purple_chat_get_type:
  68  *
  69  * Returns: The #GType for the #PurpleChat object.
  70  */
  71 GType purple_chat_get_type(void);
  72
  73 /**
  74  * purple_chat_new:
  75  * @account:    The account this chat will get added to
  76  * @alias:      The alias of the new chat
  77  * @components: The info the protocol needs to join the chat.  The
  78  *                   hash function should be g_str_hash() and the
  79  *                   equal function should be g_str_equal().
  80  *
  81  * Creates a new chat for the buddy list
  82  *
  83  * Returns:           A newly allocated chat
  84  */
  85 PurpleChat *purple_chat_new(PurpleAccount *account, const char *alias, GHashTable *components);
  86
  87 /**
  88  * purple_chat_get_name:
  89  * @chat:   The chat whose name will be returned.
  90  *
  91  * Returns the correct name to display for a blist chat.
  92  *
  93  * Returns:       The alias (if set), or first component value.
  94  */
  95 const char *purple_chat_get_name(PurpleChat *chat);
  96
  97 /**
  98  * purple_chat_get_name_only:
  99  * @chat:   The chat whose name will be returned.
 100  *
 101  * Returns the name of the chat
 102  *
 103  * Returns:       The first component value.
 104  */
 105 const char *purple_chat_get_name_only(PurpleChat *chat);
 106
 107 /**
 108  * purple_chat_set_alias:
 109  * @chat:   The chat
 110  * @alias:  The alias
 111  *
 112  * Sets the alias for a blist chat.
 113  */
 114 void purple_chat_set_alias(PurpleChat *chat, const char *alias);
 115
 116 /**
 117  * purple_chat_get_group:
 118  * @chat: The chat.
 119  *
 120  * Returns the group of which the chat is a member.
 121  *
 122  * Returns: (transfer none): The parent group, or %NULL if the chat is not in a
 123  *          group.
 124  */
 125 PurpleGroup *purple_chat_get_group(PurpleChat *chat);
 126
 127 /**
 128  * purple_chat_get_account:
 129  * @chat:  The chat.
 130  *
 131  * Returns the account the chat belongs to.
 132  *
 133  * Returns: (transfer none): The account the chat belongs to.
 134  */
 135 PurpleAccount *purple_chat_get_account(PurpleChat *chat);
 136
 137 /**
 138  * purple_chat_get_components:
 139  * @chat:  The chat.
 140  *
 141  * Get a hashtable containing information about a chat.
 142  *
 143  * Returns: (transfer none):  The hashtable.
 144  */
 145 GHashTable *purple_chat_get_components(PurpleChat *chat);
 146
 147 G_END_DECLS
 148
 149 #endif /* PURPLE_CHAT_H */