Data Structures | Typedefs | Functions
core.h File Reference

Startup and shutdown of libpurple. More...

Go to the source code of this file.

## Data Structures
struct | PurpleCoreUiOps
| Callbacks that fire at different points of the initialization and teardown of libpurple, along with a hook to return descriptive information about the UI. More...

## Typedefs
typedef struct PurpleCore | PurpleCore

## Functions
gboolean | purple_core_init (const char *ui)
| Initializes the core of purple. More...
void | purple_core_quit (void)
| Quits the core of purple, which, depending on the UI, may quit the application using the purple core.
gboolean | purple_core_quit_cb (gpointer unused)
const char * | purple_core_get_version (void)
| Returns the version of the core library. More...
const char * | purple_core_get_ui (void)
| Returns the ID of the UI that is using the core, as passed to purple_core_init(). More...
PurpleCore * | purple_get_core (void)
| Returns a handle to the purple core. More...
void | purple_core_set_ui_ops (PurpleCoreUiOps *ops)
| Sets the UI ops for the core. More...
PurpleCoreUiOps * | purple_core_get_ui_ops (void)
| Returns the UI ops for the core. More...
gboolean | purple_core_migrate (void)
| Migrates from `.gaim` to `.purple`. More...
gboolean | purple_core_ensure_single_instance (void)
| Ensures that only one instance is running. More...
GHashTable * | purple_core_get_ui_info (void)
| Returns a hash table containing various information about the UI. More...

## Detailed Description

Startup and shutdown of libpurple.

Definition in file core.h.

## Function Documentation

## ◆ purple_core_ensure_single_instance()

gboolean purple_core_ensure_single_instance | ( | void |  | ) |

Ensures that only one instance is running.

If libpurple is built with D-Bus support, this checks if another process owns the libpurple bus name and if so whether that process is using the same configuration directory as this process.

Returns
  `TRUE` if this is the first instance of libpurple running; `FALSE` if there is another instance running.

Since
  2.1.0

## ◆ purple_core_get_ui()

const char* purple_core_get_ui | ( | void |  | ) |

Returns the ID of the UI that is using the core, as passed to purple_core_init().

Returns
  The ID of the UI that is currently using the core.

## ◆ purple_core_get_ui_info()

GHashTable* purple_core_get_ui_info | ( | void |  | ) |

Returns a hash table containing various information about the UI.

The following well-known entries may be in the table (along with any others the UI might choose to include):

`name`

  the user-readable name for the UI.

`version`

  a user-readable description of the current version of the UI.

`website`

  the UI's website, such as http://pidgin.im.

`dev_website`

  the UI's development/support website, such as http://developer.pidgin.im.

`client_type`

  the type of UI. Possible values include 'pc', 'console', 'phone', 'handheld', 'web', and 'bot'. These values are compared programmatically and should not be localized.

Returns
  A GHashTable with strings for keys and values. This hash table must not be freed and should not be modified.

Since
  2.1.0

## ◆ purple_core_get_ui_ops()

PurpleCoreUiOps* purple_core_get_ui_ops | ( | void |  | ) |

Returns the UI ops for the core.

Returns
  The core's UI ops structure.

## ◆ purple_core_get_version()

const char* purple_core_get_version | ( | void |  | ) |

Returns the version of the core library.

Returns
  The version of the core library.

## ◆ purple_core_init()

gboolean purple_core_init | ( | const char * | ui | ) |

Initializes the core of purple.

This will setup preferences for all the core subsystems.

Parameters

  ui | The ID of the UI using the core. This should be a unique ID, registered with the purple team.

Returns
  `TRUE` if successful, or `FALSE` otherwise.

## ◆ purple_core_migrate()

gboolean purple_core_migrate | ( | void |  | ) |

Migrates from `.gaim` to `.purple`.

UIs must not call this if they have been told to use a custom user directory.

Returns
  A boolean indicating success or migration failure. On failure, the application must display an error to the user and then exit.

## ◆ purple_core_quit_cb()

gboolean purple_core_quit_cb | ( | gpointer | unused | ) |

Calls purple_core_quit(). This can be used as the function passed to purple_timeout_add() when you want to shutdown Purple in a specified amount of time. When shutting down Purple from a plugin, you must use this instead of purple_core_quit(); for an immediate exit, use a timeout value of 0:

`purple_timeout_add(0, purple_core_quitcb, NULL);`

This is ensures that code from your plugin is not being executed when purple_core_quit() is called. If the plugin called purple_core_quit() directly, you would get a core dump after purple_core_quit() executes and control returns to your plugin because purple_core_quit() frees all plugins.

## ◆ purple_core_set_ui_ops()

void purple_core_set_ui_ops | ( | PurpleCoreUiOps * | ops | ) |

Sets the UI ops for the core.

Parameters

  ops | A UI ops structure for the core.

## ◆ purple_get_core()

PurpleCore* purple_get_core | ( | void |  | ) |

Returns a handle to the purple core.

This is used to connect to core signals.