core.h File Reference

Startup and shutdown of libpurple. More...

This graph shows which files directly or indirectly include this file:

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.
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.
const char * purple_core_get_ui (void)
 Returns the ID of the UI that is using the core, as passed to purple_core_init().
PurpleCore * purple_get_core (void)
 Returns a handle to the purple core.
void purple_core_set_ui_ops (PurpleCoreUiOps *ops)
 Sets the UI ops for the core.
PurpleCoreUiOpspurple_core_get_ui_ops (void)
 Returns the UI ops for the core.
gboolean purple_core_migrate (void)
 Migrates from .gaim to .purple.
gboolean purple_core_ensure_single_instance (void)
 Ensures that only one instance is running.
GHashTable * purple_core_get_ui_info (void)
 Returns a hash table containing various information about the UI.


Detailed Description

Startup and shutdown of libpurple.

Definition in file core.h.


Function Documentation

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

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.

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

PurpleCoreUiOps* purple_core_get_ui_ops ( void   ) 

Returns the UI ops for the core.

Returns:
The core's UI ops structure.

const char* purple_core_get_version ( void   ) 

Returns the version of the core library.

Returns:
The version of the core library.

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.

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.

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.

void purple_core_set_ui_ops ( PurpleCoreUiOps ops  ) 

Sets the UI ops for the core.

Parameters:
ops A UI ops structure for the core.

PurpleCore* purple_get_core ( void   ) 

Returns a handle to the purple core.

This is used to connect to core signals.