GalagoCore

## 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.