1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/smiley.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,262 @@
1.4 +/**
1.5 + * @file smiley.h Smiley API
1.6 + * @ingroup core
1.7 + * @since 2.5.0
1.8 + */
1.9 +
1.10 +/* purple
1.11 + *
1.12 + * Purple is the legal property of its developers, whose names are too numerous
1.13 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.14 + * source distribution.
1.15 + *
1.16 + * This program is free software; you can redistribute it and/or modify
1.17 + * it under the terms of the GNU General Public License as published by
1.18 + * the Free Software Foundation; either version 2 of the License, or
1.19 + * (at your option) any later version.
1.20 + *
1.21 + * This program is distributed in the hope that it will be useful,
1.22 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.23 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.24 + * GNU General Public License for more details.
1.25 + *
1.26 + * You should have received a copy of the GNU General Public License
1.27 + * along with this program; if not, write to the Free Software
1.28 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.29 + *
1.30 + */
1.31 +
1.32 +#ifndef _PURPLE_SMILEY_H_
1.33 +#define _PURPLE_SMILEY_H_
1.34 +
1.35 +#include <glib-object.h>
1.36 +
1.37 +#include "imgstore.h"
1.38 +#include "util.h"
1.39 +
1.40 +/**
1.41 + * A custom smiley.
1.42 + * This contains everything Purple will ever need to know about a custom smiley.
1.43 + * Everything.
1.44 + *
1.45 + * PurpleSmiley is a GObject.
1.46 + */
1.47 +typedef struct _PurpleSmiley PurpleSmiley;
1.48 +typedef struct _PurpleSmileyClass PurpleSmileyClass;
1.49 +
1.50 +#define PURPLE_TYPE_SMILEY (purple_smiley_get_type ())
1.51 +#define PURPLE_SMILEY(smiley) (G_TYPE_CHECK_INSTANCE_CAST ((smiley), PURPLE_TYPE_SMILEY, PurpleSmiley))
1.52 +#define PURPLE_SMILEY_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), PURPLE_TYPE_SMILEY, PurpleSmileyClass))
1.53 +#define PURPLE_IS_SMILEY(smiley) (G_TYPE_CHECK_INSTANCE_TYPE ((smiley), PURPLE_TYPE_SMILEY))
1.54 +#define PURPLE_IS_SMILEY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PURPLE_TYPE_SMILEY))
1.55 +#define PURPLE_SMILEY_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), PURPLE_TYPE_SMILEY, PurpleSmileyClass))
1.56 +
1.57 +#ifdef __cplusplus
1.58 +extern "C" {
1.59 +#endif
1.60 +
1.61 +/**************************************************************************/
1.62 +/** @name Custom Smiley API */
1.63 +/**************************************************************************/
1.64 +/*@{*/
1.65 +
1.66 +/**
1.67 + * GObject-fu.
1.68 + * @internal.
1.69 + */
1.70 +GType purple_smiley_get_type(void);
1.71 +
1.72 +/**
1.73 + * Creates a new custom smiley from a PurpleStoredImage.
1.74 + *
1.75 + * If a custom smiley with the given shortcut already exists, it
1.76 + * will be automaticaly returned.
1.77 + *
1.78 + * @param img The image associated with the smiley.
1.79 + * @param shortcut The associated shortcut (e.g. "(homer)").
1.80 + *
1.81 + * @return The custom smiley.
1.82 + */
1.83 +PurpleSmiley *
1.84 +purple_smiley_new(PurpleStoredImage *img, const char *shortcut);
1.85 +
1.86 +/**
1.87 + * Creates a new custom smiley, reading the image data from a file.
1.88 + *
1.89 + * If a custom smiley with the given shortcut already exists, it
1.90 + * will be automaticaly returned.
1.91 + *
1.92 + * @param shortcut The associated shortcut (e.g. "(homer)").
1.93 + * @param filepath The image file.
1.94 + *
1.95 + * @return The custom smiley.
1.96 + */
1.97 +PurpleSmiley *
1.98 +purple_smiley_new_from_file(const char *shortcut, const char *filepath);
1.99 +
1.100 +/**
1.101 + * Destroys the custom smiley and release the associated resources.
1.102 + *
1.103 + * @param smiley The custom smiley.
1.104 + */
1.105 +void
1.106 +purple_smiley_delete(PurpleSmiley *smiley);
1.107 +
1.108 +/**
1.109 + * Changes the custom smiley's shortcut.
1.110 + *
1.111 + * @param smiley The custom smiley.
1.112 + * @param shortcut The new shortcut. A custom smiley with this shortcut
1.113 + * cannot already be in use.
1.114 + *
1.115 + * @return TRUE if the shortcut was changed. FALSE otherwise.
1.116 + */
1.117 +gboolean
1.118 +purple_smiley_set_shortcut(PurpleSmiley *smiley, const char *shortcut);
1.119 +
1.120 +/**
1.121 + * Changes the custom smiley's image data.
1.122 + *
1.123 + * @param smiley The custom smiley.
1.124 + * @param smiley_data The custom smiley data, which the smiley code
1.125 + * takes ownership of and will free.
1.126 + * @param smiley_data_len The length of the data in @a smiley_data.
1.127 + */
1.128 +void
1.129 +purple_smiley_set_data(PurpleSmiley *smiley, guchar *smiley_data,
1.130 + size_t smiley_data_len);
1.131 +
1.132 +/**
1.133 + * Returns the custom smiley's associated shortcut (e.g. "(homer)").
1.134 + *
1.135 + * @param smiley The custom smiley.
1.136 + *
1.137 + * @return The shortcut.
1.138 + */
1.139 +const char *purple_smiley_get_shortcut(const PurpleSmiley *smiley);
1.140 +
1.141 +/**
1.142 + * Returns the custom smiley data's checksum.
1.143 + *
1.144 + * @param smiley The custom smiley.
1.145 + *
1.146 + * @return The checksum.
1.147 + */
1.148 +const char *purple_smiley_get_checksum(const PurpleSmiley *smiley);
1.149 +
1.150 +/**
1.151 + * Returns the PurpleStoredImage with the reference counter incremented.
1.152 + *
1.153 + * The returned PurpleStoredImage reference counter must be decremented
1.154 + * when the caller is done using it.
1.155 + *
1.156 + * @param smiley The custom smiley.
1.157 + *
1.158 + * @return A PurpleStoredImage.
1.159 + */
1.160 +PurpleStoredImage *purple_smiley_get_stored_image(const PurpleSmiley *smiley);
1.161 +
1.162 +/**
1.163 + * Returns the custom smiley's data.
1.164 + *
1.165 + * @param smiley The custom smiley.
1.166 + * @param len If not @c NULL, the length of the image data returned
1.167 + * will be set in the location pointed to by this.
1.168 + *
1.169 + * @return A pointer to the custom smiley data.
1.170 + */
1.171 +gconstpointer purple_smiley_get_data(const PurpleSmiley *smiley, size_t *len);
1.172 +
1.173 +/**
1.174 + * Returns an extension corresponding to the custom smiley's file type.
1.175 + *
1.176 + * @param smiley The custom smiley.
1.177 + *
1.178 + * @return The custom smiley's extension, "icon" if unknown, or @c NULL if
1.179 + * the image data has disappeared.
1.180 + */
1.181 +const char *purple_smiley_get_extension(const PurpleSmiley *smiley);
1.182 +
1.183 +/**
1.184 + * Returns a full path to an custom smiley.
1.185 + *
1.186 + * If the custom smiley has data and the file exists in the cache, this
1.187 + * will return a full path to the cached file.
1.188 + *
1.189 + * In general, it is not appropriate to be poking in the file cached
1.190 + * directly. If you find yourself wanting to use this function, think
1.191 + * very long and hard about it, and then don't.
1.192 + *
1.193 + * Think some more.
1.194 + *
1.195 + * @param smiley The custom smiley.
1.196 + *
1.197 + * @return A full path to the file, or @c NULL under various conditions.
1.198 + * The caller should use #g_free to free the returned string.
1.199 + */
1.200 +char *purple_smiley_get_full_path(PurpleSmiley *smiley);
1.201 +
1.202 +/*@}*/
1.203 +
1.204 +
1.205 +/**************************************************************************/
1.206 +/** @name Custom Smiley Subsystem API */
1.207 +/**************************************************************************/
1.208 +/*@{*/
1.209 +
1.210 +/**
1.211 + * Returns a list of all custom smileys. The caller is responsible for freeing
1.212 + * the list.
1.213 + *
1.214 + * @return A list of all custom smileys.
1.215 + */
1.216 +GList *
1.217 +purple_smileys_get_all(void);
1.218 +
1.219 +/**
1.220 + * Returns a custom smiley given its shortcut.
1.221 + *
1.222 + * @param shortcut The custom smiley's shortcut.
1.223 + *
1.224 + * @return The custom smiley if found, or @c NULL if not found.
1.225 + */
1.226 +PurpleSmiley *
1.227 +purple_smileys_find_by_shortcut(const char *shortcut);
1.228 +
1.229 +/**
1.230 + * Returns a custom smiley given its checksum.
1.231 + *
1.232 + * @param checksum The custom smiley's checksum.
1.233 + *
1.234 + * @return The custom smiley if found, or @c NULL if not found.
1.235 + */
1.236 +PurpleSmiley *
1.237 +purple_smileys_find_by_checksum(const char *checksum);
1.238 +
1.239 +/**
1.240 + * Returns the directory used to store custom smiley cached files.
1.241 + *
1.242 + * The default directory is PURPLEDIR/custom_smiley.
1.243 + *
1.244 + * @return The directory in which to store custom smileys cached files.
1.245 + */
1.246 +const char *purple_smileys_get_storing_dir(void);
1.247 +
1.248 +/**
1.249 + * Initializes the custom smiley subsystem.
1.250 + */
1.251 +void purple_smileys_init(void);
1.252 +
1.253 +/**
1.254 + * Uninitializes the custom smiley subsystem.
1.255 + */
1.256 +void purple_smileys_uninit(void);
1.257 +
1.258 +/*@}*/
1.259 +
1.260 +#ifdef __cplusplus
1.261 +}
1.262 +#endif
1.263 +
1.264 +#endif /* _PURPLE_SMILEY_H_ */
1.265 +