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"
            GalagoAccount*user_function      (GalagoCore   *core,
                                            GalagoPerson *person,
                                            gpointer      user_data)      : Run last
"person-added"
            void        user_function      (GalagoCore   *core,
                                            GalagoPerson *person,
                                            gpointer      user_data)      : Run last / Action
"person-removed"
            void        user_function      (GalagoCore   *core,
                                            GalagoPerson *person,
                                            gpointer      user_data)      : Run last / Action
"registered"
            void        user_function      (GalagoCore *core,
                                            gpointer    user_data)      : Run last / Action
"service-added"
            void        user_function      (GalagoCore    *core,
                                            GalagoService *service,
                                            gpointer       user_data)      : Run last / Action
"service-removed"
            void        user_function      (GalagoCore    *core,
                                            GalagoService *service,
                                            gpointer       user_data)      : Run last / Action
"unregistered"
            void        user_function      (GalagoCore *core,
                                            gpointer    user_data)      : 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

The D-BUS interface that GalagoCore maps to.

GALAGO_DBUS_CORE_OBJECT

#define     GALAGO_DBUS_CORE_OBJECT

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.