1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/core.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,241 @@
1.4 +/**
1.5 + * @file core.h Startup and shutdown of libpurple
1.6 + * @defgroup core libpurple
1.7 + * @see @ref core-signals
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 +#ifndef _PURPLE_CORE_H_
1.31 +#define _PURPLE_CORE_H_
1.32 +
1.33 +typedef struct PurpleCore PurpleCore;
1.34 +
1.35 +/** Callbacks that fire at different points of the initialization and teardown
1.36 + * of libpurple, along with a hook to return descriptive information about the
1.37 + * UI.
1.38 + */
1.39 +typedef struct
1.40 +{
1.41 + /** Called just after the preferences subsystem is initialized; the UI
1.42 + * could use this callback to add some preferences it needs to be in
1.43 + * place when other subsystems are initialized.
1.44 + */
1.45 + void (*ui_prefs_init)(void);
1.46 + /** Called just after the debug subsystem is initialized, but before
1.47 + * just about every other component's initialization. The UI should
1.48 + * use this hook to call purple_debug_set_ui_ops() so that debugging
1.49 + * information for other components can be logged during their
1.50 + * initialization.
1.51 + */
1.52 + void (*debug_ui_init)(void);
1.53 + /** Called after all of libpurple has been initialized. The UI should
1.54 + * use this hook to set all other necessary UiOps structures.
1.55 + *
1.56 + * @see @ref ui-ops
1.57 + */
1.58 + void (*ui_init)(void);
1.59 + /** Called after most of libpurple has been uninitialized. */
1.60 + void (*quit)(void);
1.61 +
1.62 + /** Called by purple_core_get_ui_info(); should return the information
1.63 + * documented there.
1.64 + */
1.65 + GHashTable* (*get_ui_info)(void);
1.66 +
1.67 + void (*_purple_reserved1)(void);
1.68 + void (*_purple_reserved2)(void);
1.69 + void (*_purple_reserved3)(void);
1.70 +} PurpleCoreUiOps;
1.71 +
1.72 +#ifdef __cplusplus
1.73 +extern "C" {
1.74 +#endif
1.75 +
1.76 +/**
1.77 + * Initializes the core of purple.
1.78 + *
1.79 + * This will setup preferences for all the core subsystems.
1.80 + *
1.81 + * @param ui The ID of the UI using the core. This should be a
1.82 + * unique ID, registered with the purple team.
1.83 + *
1.84 + * @return @c TRUE if successful, or @c FALSE otherwise.
1.85 + */
1.86 +gboolean purple_core_init(const char *ui);
1.87 +
1.88 +/**
1.89 + * Quits the core of purple, which, depending on the UI, may quit the
1.90 + * application using the purple core.
1.91 + */
1.92 +void purple_core_quit(void);
1.93 +
1.94 +/**
1.95 + * <p>
1.96 + * Calls purple_core_quit(). This can be used as the function
1.97 + * passed to purple_timeout_add() when you want to shutdown Purple
1.98 + * in a specified amount of time. When shutting down Purple
1.99 + * from a plugin, you must use this instead of purple_core_quit();
1.100 + * for an immediate exit, use a timeout value of 0:
1.101 + * </p>
1.102 + *
1.103 + * <code>purple_timeout_add(0, purple_core_quitcb, NULL);</code>
1.104 + *
1.105 + * <p>
1.106 + * This is ensures that code from your plugin is not being
1.107 + * executed when purple_core_quit() is called. If the plugin
1.108 + * called purple_core_quit() directly, you would get a core dump
1.109 + * after purple_core_quit() executes and control returns to your
1.110 + * plugin because purple_core_quit() frees all plugins.
1.111 + * </p>
1.112 + */
1.113 +gboolean purple_core_quit_cb(gpointer unused);
1.114 +
1.115 +/**
1.116 + * Returns the version of the core library.
1.117 + *
1.118 + * @return The version of the core library.
1.119 + */
1.120 +const char *purple_core_get_version(void);
1.121 +
1.122 +/**
1.123 + * Returns the ID of the UI that is using the core, as passed to
1.124 + * purple_core_init().
1.125 + *
1.126 + * @return The ID of the UI that is currently using the core.
1.127 + */
1.128 +const char *purple_core_get_ui(void);
1.129 +
1.130 +/**
1.131 + * Returns a handle to the purple core.
1.132 + *
1.133 + * This is used to connect to @ref core-signals "core signals".
1.134 + */
1.135 +PurpleCore *purple_get_core(void);
1.136 +
1.137 +/**
1.138 + * Sets the UI ops for the core.
1.139 + *
1.140 + * @param ops A UI ops structure for the core.
1.141 + */
1.142 +void purple_core_set_ui_ops(PurpleCoreUiOps *ops);
1.143 +
1.144 +/**
1.145 + * Returns the UI ops for the core.
1.146 + *
1.147 + * @return The core's UI ops structure.
1.148 + */
1.149 +PurpleCoreUiOps *purple_core_get_ui_ops(void);
1.150 +
1.151 +/**
1.152 + * Migrates from <tt>.gaim</tt> to <tt>.purple</tt>.
1.153 + *
1.154 + * UIs <strong>must not</strong> call this if they have been told to use a
1.155 + * custom user directory.
1.156 + *
1.157 + * @return A boolean indicating success or migration failure. On failure,
1.158 + * the application must display an error to the user and then exit.
1.159 + */
1.160 +gboolean purple_core_migrate(void);
1.161 +
1.162 +/**
1.163 + * Ensures that only one instance is running. If libpurple is built with D-Bus
1.164 + * support, this checks if another process owns the libpurple bus name and if
1.165 + * so whether that process is using the same configuration directory as this
1.166 + * process.
1.167 + *
1.168 + * @return @c TRUE if this is the first instance of libpurple running;
1.169 + * @c FALSE if there is another instance running.
1.170 + *
1.171 + * @since 2.1.0
1.172 + */
1.173 +gboolean purple_core_ensure_single_instance(void);
1.174 +
1.175 +/**
1.176 + * Returns a hash table containing various information about the UI. The
1.177 + * following well-known entries may be in the table (along with any others the
1.178 + * UI might choose to include):
1.179 + *
1.180 + * <dl>
1.181 + * <dt><tt>name</tt></dt>
1.182 + * <dd>the user-readable name for the UI.</dd>
1.183 + *
1.184 + * <dt><tt>version</tt></dt>
1.185 + * <dd>a user-readable description of the current version of the UI.</dd>
1.186 + *
1.187 + * <dt><tt>website</tt></dt>
1.188 + * <dd>the UI's website, such as http://pidgin.im.</dd>
1.189 + *
1.190 + * <dt><tt>dev_website</tt></dt>
1.191 + * <dd>the UI's development/support website, such as http://developer.pidgin.im.</dd>
1.192 + *
1.193 + * <dt><tt>client_type</tt></dt>
1.194 + * <dd>the type of UI. Possible values include 'pc', 'console', 'phone',
1.195 + * 'handheld', 'web', and 'bot'. These values are compared
1.196 + * programmatically and should not be localized.</dd>
1.197 + *
1.198 + * </dl>
1.199 + *
1.200 + * @return A GHashTable with strings for keys and values. This
1.201 + * hash table must not be freed and should not be modified.
1.202 + *
1.203 + * @since 2.1.0
1.204 + *
1.205 + */
1.206 +GHashTable* purple_core_get_ui_info(void);
1.207 +
1.208 +#ifdef __cplusplus
1.209 +}
1.210 +#endif
1.211 +
1.212 +#endif /* _PURPLE_CORE_H_ */
1.213 +
1.214 +/*
1.215 +
1.216 + /===-
1.217 + `//"\\ """"`---.___.-""
1.218 + ______-==| | | \\ _-"`
1.219 + __--""" ,-/-==\\ | | `\ ,'
1.220 + _-" /' | \\ ___ / / \ /
1.221 + .' / | \\ /" "\ /' / \ /'
1.222 + / ____ / | \`\.__/-"" D O \_/' / \/'
1.223 +/-'" """""---__ | "-/" O G R /' _--"`
1.224 + \_| / R __--_ t ), __--""
1.225 + '""--_/ T _-"_>--<_\ h '-" \
1.226 + {\__--_/} / \\__>--<__\ e B \
1.227 + /' (_/ _-" | |__>--<__| U |
1.228 + | _/) )-" | |__>--<__| R |
1.229 + / /" ,_/ / /__>---<__/ N |
1.230 + o-o _// /-"_>---<__-" I /
1.231 + (^(" /"_>---<__- N _-"
1.232 + ,/| /__>--<__/ A _-"
1.233 + ,//('( |__>--<__| T / .----_
1.234 + ( ( ')) |__>--<__| | /' _---_"\
1.235 + `-)) )) ( |__>--<__| O | /' / "\`\
1.236 + ,/,'//( ( \__>--<__\ R \ /' // ||
1.237 + ,( ( ((, )) "-__>--<_"-_ "--____---"' _/'/ /'
1.238 + `"/ )` ) ,/| "-_">--<_/-__ __-" _/
1.239 + ._-"//( )/ )) ` ""-'_/_/ /"""""""__--"
1.240 + ;'( ')/ ,)( """"""""""
1.241 + ' ') '( (/
1.242 + ' ' `
1.243 +
1.244 +*/