1 /** 2 * @file core.h Startup and shutdown of libpurple 3 * @defgroup core libpurple 4 * @see @ref core-signals 5 */ 6 7 /* purple 8 * 9 * Purple is the legal property of its developers, whose names are too numerous 10 * to list here. Please refer to the COPYRIGHT file distributed with this 11 * source distribution. 12 * 13 * This program is free software; you can redistribute it and/or modify 14 * it under the terms of the GNU General Public License as published by 15 * the Free Software Foundation; either version 2 of the License, or 16 * (at your option) any later version. 17 * 18 * This program is distributed in the hope that it will be useful, 19 * but WITHOUT ANY WARRANTY; without even the implied warranty of 20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 21 * GNU General Public License for more details. 22 * 23 * You should have received a copy of the GNU General Public License 24 * along with this program; if not, write to the Free Software 25 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA 26 */ 27 28 /*! @mainpage Pidgin/Finch/libpurple API Documentation 29 * 30 * <a href="group__core.html">libpurple</a> is intended to be the core of an IM 31 * program. <a href="group__pidgin.html">Pidgin</a> is a GTK+ frontend 32 * to libpurple, and <a href="group__finch.html">Finch</a> is an ncurses 33 * frontend built using <a href="group__gnt.html">libgnt</a> 34 * (GLib Ncurses Toolkit). 35 */ 36 37 #ifndef _PURPLE_CORE_H_ 38 #define _PURPLE_CORE_H_ 39 40 typedef struct PurpleCore PurpleCore; 41 42 /** Callbacks that fire at different points of the initialization and teardown 43 * of libpurple, along with a hook to return descriptive information about the 44 * UI. 45 */ 46 typedef struct 47 { 48 /** Called just after the preferences subsystem is initialized; the UI 49 * could use this callback to add some preferences it needs to be in 50 * place when other subsystems are initialized. 51 */ 52 void (*ui_prefs_init)(void); 53 /** Called just after the debug subsystem is initialized, but before 54 * just about every other component's initialization. The UI should 55 * use this hook to call purple_debug_set_ui_ops() so that debugging 56 * information for other components can be logged during their 57 * initialization. 58 */ 59 void (*debug_ui_init)(void); 60 /** Called after all of libpurple has been initialized. The UI should 61 * use this hook to set all other necessary UiOps structures. 62 * 63 * @see @ref ui-ops 64 */ 65 void (*ui_init)(void); 66 /** Called after most of libpurple has been uninitialized. */ 67 void (*quit)(void); 68 69 /** Called by purple_core_get_ui_info(); should return the information 70 * documented there. 71 */ 72 GHashTable* (*get_ui_info)(void); 73 74 void (*_purple_reserved1)(void); 75 void (*_purple_reserved2)(void); 76 void (*_purple_reserved3)(void); 77 } PurpleCoreUiOps; 78 79 #ifdef __cplusplus 80 extern "C" { 81 #endif 82 83 /** 84 * Initializes the core of purple. 85 * 86 * This will setup preferences for all the core subsystems. 87 * 88 * @param ui The ID of the UI using the core. This should be a 89 * unique ID, registered with the purple team. 90 * 91 * @return @c TRUE if successful, or @c FALSE otherwise. 92 */ 93 gboolean purple_core_init(const char *ui); 94 95 /** 96 * Quits the core of purple, which, depending on the UI, may quit the 97 * application using the purple core. 98 */ 99 void purple_core_quit(void); 100 101 /** 102 * <p> 103 * Calls purple_core_quit(). This can be used as the function 104 * passed to purple_timeout_add() when you want to shutdown Purple 105 * in a specified amount of time. When shutting down Purple 106 * from a plugin, you must use this instead of purple_core_quit(); 107 * for an immediate exit, use a timeout value of 0: 108 * </p> 109 * 110 * <code>purple_timeout_add(0, purple_core_quitcb, NULL);</code> 111 * 112 * <p> 113 * This is ensures that code from your plugin is not being 114 * executed when purple_core_quit() is called. If the plugin 115 * called purple_core_quit() directly, you would get a core dump 116 * after purple_core_quit() executes and control returns to your 117 * plugin because purple_core_quit() frees all plugins. 118 * </p> 119 */ 120 gboolean purple_core_quit_cb(gpointer unused); 121 122 /** 123 * Returns the version of the core library. 124 * 125 * @return The version of the core library. 126 */ 127 const char *purple_core_get_version(void); 128 129 /** 130 * Returns the ID of the UI that is using the core, as passed to 131 * purple_core_init(). 132 * 133 * @return The ID of the UI that is currently using the core. 134 */ 135 const char *purple_core_get_ui(void); 136 137 /** 138 * Returns a handle to the purple core. 139 * 140 * This is used to connect to @ref core-signals "core signals". 141 */ 142 PurpleCore *purple_get_core(void); 143 144 /** 145 * Sets the UI ops for the core. 146 * 147 * @param ops A UI ops structure for the core. 148 */ 149 void purple_core_set_ui_ops(PurpleCoreUiOps *ops); 150 151 /** 152 * Returns the UI ops for the core. 153 * 154 * @return The core's UI ops structure. 155 */ 156 PurpleCoreUiOps *purple_core_get_ui_ops(void); 157 158 /** 159 * Migrates from <tt>.gaim</tt> to <tt>.purple</tt>. 160 * 161 * UIs <strong>must not</strong> call this if they have been told to use a 162 * custom user directory. 163 * 164 * @return A boolean indicating success or migration failure. On failure, 165 * the application must display an error to the user and then exit. 166 */ 167 gboolean purple_core_migrate(void); 168 169 /** 170 * Ensures that only one instance is running. If libpurple is built with D-Bus 171 * support, this checks if another process owns the libpurple bus name and if 172 * so whether that process is using the same configuration directory as this 173 * process. 174 * 175 * @return @c TRUE if this is the first instance of libpurple running; 176 * @c FALSE if there is another instance running. 177 * 178 * @since 2.1.0 179 */ 180 gboolean purple_core_ensure_single_instance(void); 181 182 /** 183 * Returns a hash table containing various information about the UI. The 184 * following well-known entries may be in the table (along with any others the 185 * UI might choose to include): 186 * 187 * <dl> 188 * <dt><tt>name</tt></dt> 189 * <dd>the user-readable name for the UI.</dd> 190 * 191 * <dt><tt>version</tt></dt> 192 * <dd>a user-readable description of the current version of the UI.</dd> 193 * 194 * <dt><tt>website</tt></dt> 195 * <dd>the UI's website, such as http://pidgin.im.</dd> 196 * 197 * <dt><tt>dev_website</tt></dt> 198 * <dd>the UI's development/support website, such as http://developer.pidgin.im.</dd> 199 * 200 * <dt><tt>client_type</tt></dt> 201 * <dd>the type of UI. Possible values include 'pc', 'console', 'phone', 202 * 'handheld', 'web', and 'bot'. These values are compared 203 * programmatically and should not be localized.</dd> 204 * 205 * </dl> 206 * 207 * @return A GHashTable with strings for keys and values. This 208 * hash table must not be freed and should not be modified. 209 * 210 * @since 2.1.0 211 * 212 */ 213 GHashTable* purple_core_get_ui_info(void); 214 215 #ifdef __cplusplus 216 } 217 #endif 218 219 #endif /* _PURPLE_CORE_H_ */ 220 221 /* 222 223 /===- 224 `//"\\ """"`---.___.-"" 225 ______-==| | | \\ _-"` 226 __--""" ,-/-==\\ | | `\ ,' 227 _-" /' | \\ ___ / / \ / 228 .' / | \\ /" "\ /' / \ /' 229 / ____ / | \`\.__/-"" D O \_/' / \/' 230 /-'" """""---__ | "-/" O G R /' _--"` 231 \_| / R __--_ t ), __--"" 232 '""--_/ T _-"_>--<_\ h '-" \ 233 {\__--_/} / \\__>--<__\ e B \ 234 /' (_/ _-" | |__>--<__| U | 235 | _/) )-" | |__>--<__| R | 236 / /" ,_/ / /__>---<__/ N | 237 o-o _// /-"_>---<__-" I / 238 (^(" /"_>---<__- N _-" 239 ,/| /__>--<__/ A _-" 240 ,//('( |__>--<__| T / .----_ 241 ( ( ')) |__>--<__| | /' _---_"\ 242 `-)) )) ( |__>--<__| O | /' / "\`\ 243 ,/,'//( ( \__>--<__\ R \ /' // || 244 ,( ( ((, )) "-__>--<_"-_ "--____---"' _/'/ /' 245 `"/ )` ) ,/| "-_">--<_/-__ __-" _/ 246 ._-"//( )/ )) ` ""-'_/_/ /"""""""__--" 247 ;'( ')/ ,)( """""""""" 248 ' ') '( (/ 249 ' ' ` 250 251 */ 252