1.1 --- a/Frameworks/libpurple.framework/Versions/0.6.0/Headers/roomlist.h Fri Aug 21 13:24:36 2009 -0700
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,398 +0,0 @@
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_ */