1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/roomlist.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,398 @@
1.4 +/**
1.5 + * @file roomlist.h Room List API
1.6 + * @ingroup core
1.7 + */
1.8 +
1.9 +/* purple
1.10 + *
1.11 + * Purple is the legal property of its developers, whose names are too numerous
1.12 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.13 + * source distribution.
1.14 + *
1.15 + * This program is free software; you can redistribute it and/or modify
1.16 + * it under the terms of the GNU General Public License as published by
1.17 + * the Free Software Foundation; either version 2 of the License, or
1.18 + * (at your option) any later version.
1.19 + *
1.20 + * This program is distributed in the hope that it will be useful,
1.21 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.22 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.23 + * GNU General Public License for more details.
1.24 + *
1.25 + * You should have received a copy of the GNU General Public License
1.26 + * along with this program; if not, write to the Free Software
1.27 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.28 + */
1.29 +
1.30 +#ifndef _PURPLE_ROOMLIST_H_
1.31 +#define _PURPLE_ROOMLIST_H_
1.32 +
1.33 +typedef struct _PurpleRoomlist PurpleRoomlist;
1.34 +typedef struct _PurpleRoomlistRoom PurpleRoomlistRoom;
1.35 +typedef struct _PurpleRoomlistField PurpleRoomlistField;
1.36 +/** @copydoc _PurpleRoomlistUiOps */
1.37 +typedef struct _PurpleRoomlistUiOps PurpleRoomlistUiOps;
1.38 +
1.39 +/**
1.40 + * The types of rooms.
1.41 + *
1.42 + * These are ORable flags.
1.43 + */
1.44 +typedef enum
1.45 +{
1.46 + PURPLE_ROOMLIST_ROOMTYPE_CATEGORY = 0x01, /**< It's a category, but not a room you can join. */
1.47 + PURPLE_ROOMLIST_ROOMTYPE_ROOM = 0x02 /**< It's a room, like the kind you can join. */
1.48 +
1.49 +} PurpleRoomlistRoomType;
1.50 +
1.51 +/**
1.52 + * The types of fields.
1.53 + */
1.54 +typedef enum
1.55 +{
1.56 + PURPLE_ROOMLIST_FIELD_BOOL,
1.57 + PURPLE_ROOMLIST_FIELD_INT,
1.58 + PURPLE_ROOMLIST_FIELD_STRING /**< We do a g_strdup on the passed value if it's this type. */
1.59 +
1.60 +} PurpleRoomlistFieldType;
1.61 +
1.62 +#include "account.h"
1.63 +#include "glib.h"
1.64 +
1.65 +/**************************************************************************/
1.66 +/** Data Structures */
1.67 +/**************************************************************************/
1.68 +
1.69 +/**
1.70 + * Represents a list of rooms for a given connection on a given protocol.
1.71 + */
1.72 +struct _PurpleRoomlist {
1.73 + PurpleAccount *account; /**< The account this list belongs to. */
1.74 + GList *fields; /**< The fields. */
1.75 + GList *rooms; /**< The list of rooms. */
1.76 + gboolean in_progress; /**< The listing is in progress. */
1.77 + gpointer ui_data; /**< UI private data. */
1.78 + gpointer proto_data; /** Prpl private data. */
1.79 + guint ref; /**< The reference count. */
1.80 +};
1.81 +
1.82 +/**
1.83 + * Represents a room.
1.84 + */
1.85 +struct _PurpleRoomlistRoom {
1.86 + PurpleRoomlistRoomType type; /**< The type of room. */
1.87 + gchar *name; /**< The name of the room. */
1.88 + GList *fields; /**< Other fields. */
1.89 + PurpleRoomlistRoom *parent; /**< The parent room, or NULL. */
1.90 + gboolean expanded_once; /**< A flag the UI uses to avoid multiple expand prpl cbs. */
1.91 +};
1.92 +
1.93 +/**
1.94 + * A field a room might have.
1.95 + */
1.96 +struct _PurpleRoomlistField {
1.97 + PurpleRoomlistFieldType type; /**< The type of field. */
1.98 + gchar *label; /**< The i18n user displayed name of the field. */
1.99 + gchar *name; /**< The internal name of the field. */
1.100 + gboolean hidden; /**< Hidden? */
1.101 +};
1.102 +
1.103 +/**
1.104 + * The room list ops to be filled out by the UI.
1.105 + */
1.106 +struct _PurpleRoomlistUiOps {
1.107 + void (*show_with_account)(PurpleAccount *account); /**< Force the ui to pop up a dialog and get the list */
1.108 + void (*create)(PurpleRoomlist *list); /**< A new list was created. */
1.109 + void (*set_fields)(PurpleRoomlist *list, GList *fields); /**< Sets the columns. */
1.110 + void (*add_room)(PurpleRoomlist *list, PurpleRoomlistRoom *room); /**< Add a room to the list. */
1.111 + void (*in_progress)(PurpleRoomlist *list, gboolean flag); /**< Are we fetching stuff still? */
1.112 + void (*destroy)(PurpleRoomlist *list); /**< We're destroying list. */
1.113 +
1.114 + void (*_purple_reserved1)(void);
1.115 + void (*_purple_reserved2)(void);
1.116 + void (*_purple_reserved3)(void);
1.117 + void (*_purple_reserved4)(void);
1.118 +};
1.119 +
1.120 +
1.121 +#ifdef __cplusplus
1.122 +extern "C" {
1.123 +#endif
1.124 +
1.125 +/**************************************************************************/
1.126 +/** @name Room List API */
1.127 +/**************************************************************************/
1.128 +/*@{*/
1.129 +
1.130 +/**
1.131 + * This is used to get the room list on an account, asking the UI
1.132 + * to pop up a dialog with the specified account already selected,
1.133 + * and pretend the user clicked the get list button.
1.134 + * While we're pretending, predend I didn't say anything about dialogs
1.135 + * or buttons, since this is the core.
1.136 + *
1.137 + * @param account The account to get the list on.
1.138 + */
1.139 +void purple_roomlist_show_with_account(PurpleAccount *account);
1.140 +
1.141 +/**
1.142 + * Returns a newly created room list object.
1.143 + *
1.144 + * It has an initial reference count of 1.
1.145 + *
1.146 + * @param account The account that's listing rooms.
1.147 + * @return The new room list handle.
1.148 + */
1.149 +PurpleRoomlist *purple_roomlist_new(PurpleAccount *account);
1.150 +
1.151 +/**
1.152 + * Increases the reference count on the room list.
1.153 + *
1.154 + * @param list The object to ref.
1.155 + */
1.156 +void purple_roomlist_ref(PurpleRoomlist *list);
1.157 +
1.158 +/**
1.159 + * Decreases the reference count on the room list.
1.160 + *
1.161 + * The room list will be destroyed when this reaches 0.
1.162 + *
1.163 + * @param list The room list object to unref and possibly
1.164 + * destroy.
1.165 + */
1.166 +void purple_roomlist_unref(PurpleRoomlist *list);
1.167 +
1.168 +/**
1.169 + * Set the different field types and their names for this protocol.
1.170 + *
1.171 + * This must be called before purple_roomlist_room_add().
1.172 + *
1.173 + * @param list The room list.
1.174 + * @param fields A GList of PurpleRoomlistField's. UI's are encouraged
1.175 + * to default to displaying them in the order given.
1.176 + */
1.177 +void purple_roomlist_set_fields(PurpleRoomlist *list, GList *fields);
1.178 +
1.179 +/**
1.180 + * Set the "in progress" state of the room list.
1.181 + *
1.182 + * The UI is encouraged to somehow hint to the user
1.183 + * whether or not we're busy downloading a room list or not.
1.184 + *
1.185 + * @param list The room list.
1.186 + * @param in_progress We're downloading it, or we're not.
1.187 + */
1.188 +void purple_roomlist_set_in_progress(PurpleRoomlist *list, gboolean in_progress);
1.189 +
1.190 +/**
1.191 + * Gets the "in progress" state of the room list.
1.192 + *
1.193 + * The UI is encouraged to somehow hint to the user
1.194 + * whether or not we're busy downloading a room list or not.
1.195 + *
1.196 + * @param list The room list.
1.197 + * @return True if we're downloading it, or false if we're not.
1.198 + */
1.199 +gboolean purple_roomlist_get_in_progress(PurpleRoomlist *list);
1.200 +
1.201 +/**
1.202 + * Adds a room to the list of them.
1.203 + *
1.204 + * @param list The room list.
1.205 + * @param room The room to add to the list. The GList of fields must be in the same
1.206 + order as was given in purple_roomlist_set_fields().
1.207 +*/
1.208 +void purple_roomlist_room_add(PurpleRoomlist *list, PurpleRoomlistRoom *room);
1.209 +
1.210 +/**
1.211 + * Returns a PurpleRoomlist structure from the prpl, and
1.212 + * instructs the prpl to start fetching the list.
1.213 + *
1.214 + * @param gc The PurpleConnection to have get a list.
1.215 + *
1.216 + * @return A PurpleRoomlist* or @c NULL if the protocol
1.217 + * doesn't support that.
1.218 + */
1.219 +PurpleRoomlist *purple_roomlist_get_list(PurpleConnection *gc);
1.220 +
1.221 +/**
1.222 + * Tells the prpl to stop fetching the list.
1.223 + * If this is possible and done, the prpl will
1.224 + * call set_in_progress with @c FALSE and possibly
1.225 + * unref the list if it took a reference.
1.226 + *
1.227 + * @param list The room list to cancel a get_list on.
1.228 + */
1.229 +void purple_roomlist_cancel_get_list(PurpleRoomlist *list);
1.230 +
1.231 +/**
1.232 + * Tells the prpl that a category was expanded.
1.233 + *
1.234 + * On some protocols, the rooms in the category
1.235 + * won't be fetched until this is called.
1.236 + *
1.237 + * @param list The room list.
1.238 + * @param category The category that was expanded. The expression
1.239 + * (category->type & PURPLE_ROOMLIST_ROOMTYPE_CATEGORY)
1.240 + * must be true.
1.241 + */
1.242 +void purple_roomlist_expand_category(PurpleRoomlist *list, PurpleRoomlistRoom *category);
1.243 +
1.244 +/**
1.245 + * Get the list of fields for a roomlist.
1.246 + *
1.247 + * @param roomlist The roomlist, which must not be @c NULL.
1.248 + * @constreturn A list of fields
1.249 + * @since 2.4.0
1.250 + */
1.251 +GList * purple_roomlist_get_fields(PurpleRoomlist *roomlist);
1.252 +
1.253 +/*@}*/
1.254 +
1.255 +/**************************************************************************/
1.256 +/** @name Room API */
1.257 +/**************************************************************************/
1.258 +/*@{*/
1.259 +
1.260 +/**
1.261 + * Creates a new room, to be added to the list.
1.262 + *
1.263 + * @param type The type of room.
1.264 + * @param name The name of the room.
1.265 + * @param parent The room's parent, if any.
1.266 + *
1.267 + * @return A new room.
1.268 + */
1.269 +PurpleRoomlistRoom *purple_roomlist_room_new(PurpleRoomlistRoomType type, const gchar *name,
1.270 + PurpleRoomlistRoom *parent);
1.271 +
1.272 +/**
1.273 + * Adds a field to a room.
1.274 + *
1.275 + * @param list The room list the room belongs to.
1.276 + * @param room The room.
1.277 + * @param field The field to append. Strings get g_strdup'd internally.
1.278 + */
1.279 +void purple_roomlist_room_add_field(PurpleRoomlist *list, PurpleRoomlistRoom *room, gconstpointer field);
1.280 +
1.281 +/**
1.282 + * Join a room, given a PurpleRoomlistRoom and it's associated PurpleRoomlist.
1.283 + *
1.284 + * @param list The room list the room belongs to.
1.285 + * @param room The room to join.
1.286 + */
1.287 +void purple_roomlist_room_join(PurpleRoomlist *list, PurpleRoomlistRoom *room);
1.288 +
1.289 +/**
1.290 + * Get the type of a room.
1.291 + * @param room The room, which must not be @c NULL.
1.292 + * @return The type of the room.
1.293 + * @since 2.4.0
1.294 + */
1.295 +PurpleRoomlistRoomType purple_roomlist_room_get_type(PurpleRoomlistRoom *room);
1.296 +
1.297 +/**
1.298 + * Get the name of a room.
1.299 + * @param room The room, which must not be @c NULL.
1.300 + * @return The name of the room.
1.301 + * @since 2.4.0
1.302 + */
1.303 +const char * purple_roomlist_room_get_name(PurpleRoomlistRoom *room);
1.304 +
1.305 +/**
1.306 + * Get the parent of a room.
1.307 + * @param room The room, which must not be @c NULL.
1.308 + * @return The parent of the room, which can be @c NULL.
1.309 + * @since 2.4.0
1.310 + */
1.311 +PurpleRoomlistRoom * purple_roomlist_room_get_parent(PurpleRoomlistRoom *room);
1.312 +
1.313 +/**
1.314 + * Get the list of fields for a room.
1.315 + *
1.316 + * @param room The room, which must not be @c NULL.
1.317 + * @constreturn A list of fields
1.318 + * @since 2.4.0
1.319 + */
1.320 +GList * purple_roomlist_room_get_fields(PurpleRoomlistRoom *room);
1.321 +
1.322 +/*@}*/
1.323 +
1.324 +/**************************************************************************/
1.325 +/** @name Room Field API */
1.326 +/**************************************************************************/
1.327 +/*@{*/
1.328 +
1.329 +/**
1.330 + * Creates a new field.
1.331 + *
1.332 + * @param type The type of the field.
1.333 + * @param label The i18n'ed, user displayable name.
1.334 + * @param name The internal name of the field.
1.335 + * @param hidden Hide the field.
1.336 + *
1.337 + * @return A new PurpleRoomlistField, ready to be added to a GList and passed to
1.338 + * purple_roomlist_set_fields().
1.339 + */
1.340 +PurpleRoomlistField *purple_roomlist_field_new(PurpleRoomlistFieldType type,
1.341 + const gchar *label, const gchar *name,
1.342 + gboolean hidden);
1.343 +
1.344 +/**
1.345 + * Get the type of a field.
1.346 + *
1.347 + * @param field A PurpleRoomlistField, which must not be @c NULL.
1.348 + *
1.349 + * @return The type of the field.
1.350 + * @since 2.4.0
1.351 + */
1.352 +PurpleRoomlistFieldType purple_roomlist_field_get_type(PurpleRoomlistField *field);
1.353 +
1.354 +/**
1.355 + * Get the label of a field.
1.356 + *
1.357 + * @param field A PurpleRoomlistField, which must not be @c NULL.
1.358 + *
1.359 + * @return The label of the field.
1.360 + * @since 2.4.0
1.361 + */
1.362 +const char * purple_roomlist_field_get_label(PurpleRoomlistField *field);
1.363 +
1.364 +/**
1.365 + * Check whether a roomlist-field is hidden.
1.366 + * @param field A PurpleRoomlistField, which must not be @c NULL.
1.367 + *
1.368 + * @return @c TRUE if the field is hidden, @c FALSE otherwise.
1.369 + * @since 2.4.0
1.370 + */
1.371 +gboolean purple_roomlist_field_get_hidden(PurpleRoomlistField *field);
1.372 +
1.373 +/*@}*/
1.374 +
1.375 +/**************************************************************************/
1.376 +/** @name UI Registration Functions */
1.377 +/**************************************************************************/
1.378 +/*@{*/
1.379 +
1.380 +/**
1.381 + * Sets the UI operations structure to be used in all purple room lists.
1.382 + *
1.383 + * @param ops The UI operations structure.
1.384 + */
1.385 +void purple_roomlist_set_ui_ops(PurpleRoomlistUiOps *ops);
1.386 +
1.387 +/**
1.388 + * Returns the purple window UI operations structure to be used in
1.389 + * new windows.
1.390 + *
1.391 + * @return A filled-out PurpleRoomlistUiOps structure.
1.392 + */
1.393 +PurpleRoomlistUiOps *purple_roomlist_get_ui_ops(void);
1.394 +
1.395 +/*@}*/
1.396 +
1.397 +#ifdef __cplusplus
1.398 +}
1.399 +#endif
1.400 +
1.401 +#endif /* _PURPLE_ROOMLIST_H_ */