libpurple/core.h

   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 */