GalagoCore

GalagoCore — The core API.

Synopsis




#define             GALAGO_DBUS_CORE_INTERFACE
#define             GALAGO_DBUS_CORE_OBJECT
enum                GalagoInitFlags;
                    GalagoCore;
gboolean            galago_init                         (const char *name,
                                                         GalagoInitFlags flags);
void                galago_uninit                       (void);
gboolean            galago_is_initted                   (void);
gboolean            galago_is_connected                 (void);
gboolean            galago_is_registered                (void);
gboolean            galago_is_daemon_active             (void);
gboolean            galago_is_daemon                    (void);
DBusConnection*     galago_get_dbus_conn                (void);
const char*         galago_get_uid                      (void);
const char*         galago_get_client_obj_path          (void);
gboolean            galago_is_feed                      (void);
void                galago_set_watch_all                (gboolean watch_all);
gboolean            galago_get_watch_all                (void);
GalagoService*      galago_create_service               (const char *id,
                                                         const char *name,
                                                         GalagoServiceFlags flags);
GalagoService*      galago_get_service                  (const char *id,
                                                         GalagoOrigin origin,
                                                         gboolean query);
GList*              galago_get_services                 (GalagoOrigin origin,
                                                         gboolean query);
GalagoPerson*       galago_create_person                (const char *uid);
GalagoPerson*       galago_get_person                   (const char *uid,
                                                         GalagoOrigin origin,
                                                         gboolean query);
GList*              galago_get_people                   (GalagoOrigin origin,
                                                         gboolean query);
GalagoPerson*       galago_get_me                       (GalagoOrigin origin,
                                                         gboolean query);
GalagoCore*         galago_get_core                     (void);

Object Hierarchy


  GObject
   +----GalagoObject
         +----GalagoCore

Signals


  "calc-priority-account"                          : Run Last
  "person-added"                                   : Run Last / Action
  "person-removed"                                 : Run Last / Action
  "registered"                                     : Run Last / Action
  "service-added"                                  : Run Last / Action
  "service-removed"                                : Run Last / Action
  "unregistered"                                   : Run Last / Action

Description

The core API of Galago. These functions are used for initializing Galago, creating and retrieving top-level GalagoPerson and GalagoService objects, and listening to signals.

There is only one GalagoCore object, and it exists as long as Galago is initialized (by calling galago_init()). You can retrieve a pointer to it using galago_get_core().

Details

GALAGO_DBUS_CORE_INTERFACE

#define GALAGO_DBUS_CORE_INTERFACE "org.freedesktop.Galago.Core"

The D-BUS interface that GalagoCore maps to.


GALAGO_DBUS_CORE_OBJECT

#define GALAGO_DBUS_CORE_OBJECT    "/org/freedesktop/Galago/Core"

The D-BUS object path to the remote Core object.


enum GalagoInitFlags

typedef enum
{
	GALAGO_INIT_CLIENT      = 0,
	GALAGO_INIT_FEED        = 1 << 0,
	GALAGO_INIT_NO_ACTIVATION = 1 << 1

} GalagoInitFlags;

Initialization flags passed to galago_init().

GALAGO_INIT_CLIENT Initialize as a client. The connection will be used for querying data only.
GALAGO_INIT_FEED Initialize as a feed. The connection will feed service, account, person, and presence data to galago-daemon. This takes precedence over GALAGO_INIT_CLIENT.
GALAGO_INIT_NO_ACTIVATION Don't activate the Galago service automatically.

GalagoCore

typedef struct _GalagoCore GalagoCore;

The core object. Fields should not be used directly. Use the accessor functions below.


galago_init ()

gboolean            galago_init                         (const char *name,
                                                         GalagoInitFlags flags);

Initializes Galago.

name : The ID name used for this connection. It's often the name of the program, without spaces or special characters.
flags : The flags used for this connection.
Returns : TRUE if initialization was successful, or FALSE otherwise.

galago_uninit ()

void                galago_uninit                       (void);

Uninitializes Galago.

This will be called automatically on exit, but can be called manually.


galago_is_initted ()

gboolean            galago_is_initted                   (void);

Returns whether or not Galago has been initialized.

Returns : TRUE if Galago has been initialized, or FALSE otherwise.

galago_is_connected ()

gboolean            galago_is_connected                 (void);

Returns whether or not Galago is connected to the daemon.

Returns : TRUE if Galago is connected, or FALSE otherwise.

galago_is_registered ()

gboolean            galago_is_registered                (void);

Returns whether or not Galago is successfully registered to the daemon.

Returns : TRUE if this Galago connection is registered, or FALSE otherwise.

galago_is_daemon_active ()

gboolean            galago_is_daemon_active             (void);

Returns whether or not the Galago daemon is active.

Returns : TRUE if the daemon is active, or FALSE.

galago_is_daemon ()

gboolean            galago_is_daemon                    (void);

Returns whether or not this instance of Galago is the daemon.

Returns : TRUE if this is the daemon, or FALSE.

galago_get_dbus_conn ()

DBusConnection*     galago_get_dbus_conn                (void);

Returns Galago's D-BUS connection.

Returns : The D-BUS connection.

galago_get_uid ()

const char*         galago_get_uid                      (void);

Returns the local Galago connection's unique ID.

This ID is used in D-BUS object paths. The function is intended for internal purposes only.

Returns : This connection's unique ID.

galago_get_client_obj_path ()

const char*         galago_get_client_obj_path          (void);

Returns the D-BUS object path representing this connection.

Returns : This connection's D-BUS object path.

galago_is_feed ()

gboolean            galago_is_feed                      (void);

Returns whether or not this Galago connection works as a feed.

Returns : TRUE if this connection works as a feed, or FALSE if not.

galago_set_watch_all ()

void                galago_set_watch_all                (gboolean watch_all);

Sets whether or not all services, accounts, etc. should be watched for property updates.

This will only add accounts, persons, presences, etc. that have a known parent object. That is, if a signal arrives for an account on a service that the local program does not know about, it will be ignored. If you wish to get information on every single object, call the list query functions first.

watch_all : TRUE if everything should be watched, or FALSE.

galago_get_watch_all ()

gboolean            galago_get_watch_all                (void);

Returns whether or not all services, accounts, etc. is being watched for property updates.

Returns : TRUE if everything is being watched, or FALSE.

galago_create_service ()

GalagoService*      galago_create_service               (const char *id,
                                                         const char *name,
                                                         GalagoServiceFlags flags);

Creates a service and adds it to the local cache.

The name and flags will be computed if the ID is understood internally. Otherwise, they will have to be provided.

id : The service ID.
name : The service name.
flags : The flags.
Returns : The new service, or a pointer to an existing one of the same ID.

galago_get_service ()

GalagoService*      galago_get_service                  (const char *id,
                                                         GalagoOrigin origin,
                                                         gboolean query);

Returns the service with the specified ID.

id : The service ID.
origin : The desired service's origin.
query : TRUE if a remote query should be done if there is no local service found, or FALSE.
Returns : The service, if found, or NULL.

galago_get_services ()

GList*              galago_get_services                 (GalagoOrigin origin,
                                                         gboolean query);

Returns a list of known services.

This may emit a service-added signal for every object that returns. If your code connects to this signal and calls galago_get_services() as a result, you will want to add a lock so that you don't end up with unwanted side-effects.

origin : The desired origin.
query : TRUE if a remote query should be done if there are no local services found, or FALSE.
Returns : The list of services, or NULL.

galago_create_person ()

GalagoPerson*       galago_create_person                (const char *uid);

Creates a person and adds it to the local cache.

uid : The person UID.
Returns : The new person, or an existing one if one already exists with this UID.

galago_get_person ()

GalagoPerson*       galago_get_person                   (const char *uid,
                                                         GalagoOrigin origin,
                                                         gboolean query);

Returns the person with the specified UID.

uid : The person's UID.
origin : The desired person's origin.
query : TRUE if a remote query should be done if there is no local person found, or FALSE.
Returns : The person, if found, or NULL.

galago_get_people ()

GList*              galago_get_people                   (GalagoOrigin origin,
                                                         gboolean query);

Returns a list of known people.

This may emit a person-added signal for every object that returns. If your code connects to this signal and calls galago_get_people() as a result, you will want to add a lock so that you don't end up with unwanted side-effects.

origin : The desired origin.
query : TRUE if a remote query should be done if there is no local people found, or FALSE.
Returns : The people, if found, or NULL.

galago_get_me ()

GalagoPerson*       galago_get_me                       (GalagoOrigin origin,
                                                         gboolean query);

Returns the "Me" person.

If origin is GALAGO_LOCAL, this will always return a "Me" person. In the remote case, it will only return one if query is TRUE, or if it has already retrieved a remote "Me" person.

origin : The desired person's origin.
query : TRUE if a remote query should be done if there is no local person found, or FALSE.
Returns : The "Me" person, if found, or NULL.

galago_get_core ()

GalagoCore*         galago_get_core                     (void);

Returns the core object.

This is needed for signals.

Returns : The core object.

Signal Details

The "calc-priority-account" signal

GalagoAccount*      user_function                      (GalagoCore   *core,
                                                        GalagoPerson *person,
                                                        gpointer      user_data)      : Run Last

Emitted when the priority account for a person needs to be calculated. The callback function should return the account that is considered the priority, which is by default the most available one.

core : The object which received the signal.
person : The person the priority account is being calculated for.
user_data : user data set when the signal handler was connected.
Returns : The priority account.

The "person-added" signal

void                user_function                      (GalagoCore   *core,
                                                        GalagoPerson *person,
                                                        gpointer      user_data)      : Run Last / Action

Emitted when a person is added.

core : The object which received the signal.
person : The person added.
user_data : user data set when the signal handler was connected.

The "person-removed" signal

void                user_function                      (GalagoCore   *core,
                                                        GalagoPerson *person,
                                                        gpointer      user_data)      : Run Last / Action

Emitted when a person is removed.

core : The object which received the signal.
person : The person removed.
user_data : user data set when the signal handler was connected.

The "registered" signal

void                user_function                      (GalagoCore *core,
                                                        gpointer    user_data)      : Run Last / Action

Emitted when the application successfully registers with the daemon.

core : The object which received the signal.
user_data : user data set when the signal handler was connected.

The "service-added" signal

void                user_function                      (GalagoCore    *core,
                                                        GalagoService *service,
                                                        gpointer       user_data)      : Run Last / Action

Emitted when a service is added.

core : The object which received the signal.
service : The service added.
user_data : user data set when the signal handler was connected.

The "service-removed" signal

void                user_function                      (GalagoCore    *core,
                                                        GalagoService *service,
                                                        gpointer       user_data)      : Run Last / Action

Emitted when a service is removed.

core : The object which received the signal.
service : The service removed.
user_data : user data set when the signal handler was connected.

The "unregistered" signal

void                user_function                      (GalagoCore *core,
                                                        gpointer    user_data)      : Run Last / Action

Emitted when the application unregisters with the daemon.

core : The object which received the signal.
user_data : user data set when the signal handler was connected.