libpurple/core.h

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