OssoABookAggregator

OssoABookAggregator — Aggregated view of multiple EBook instances.

Synopsis

enum                OssoABookAggregatorState;
gboolean            (*OssoABookContactPredicate)        (OssoABookContact *contact,
                                                         gpointer user_data);
                    OssoABookAggregator;
OssoABookRoster*    osso_abook_aggregator_new           (EBook *book,
                                                         GError **error);
OssoABookRoster*    osso_abook_aggregator_new_with_query
                                                        (EBook *book,
                                                         EBookQuery *query,
                                                         GList *requested_fields,
                                                         int max_results,
                                                         GError **error);
OssoABookRoster*    osso_abook_aggregator_new_with_view (EBookView *view);
OssoABookRoster*    osso_abook_aggregator_get_default   (GError **error);
OssoABookAggregatorState osso_abook_aggregator_get_state
                                                        (OssoABookAggregator *aggregator);
GList*              osso_abook_aggregator_lookup        (OssoABookAggregator *aggregator,
                                                         const char *uid);
unsigned            osso_abook_aggregator_get_master_contact_count
                                                        (OssoABookAggregator *aggregator);
OssoABookRosterManager* osso_abook_aggregator_get_roster_manager
                                                        (OssoABookAggregator *aggregator);
void                osso_abook_aggregator_set_roster_manager
                                                        (OssoABookAggregator *aggregator,
                                                         OssoABookRosterManager *manager);
void                osso_abook_aggregator_add_filter    (OssoABookAggregator *aggregator,
                                                         OssoABookContactFilter *filter);
void                osso_abook_aggregator_remove_filter (OssoABookAggregator *aggregator,
                                                         OssoABookContactFilter *filter);

Object Hierarchy

  GObject
   +----OssoABookRoster
         +----OssoABookAggregator

Implemented Interfaces

OssoABookAggregator implements OssoABookWaitable.

Properties

  "master-contact-count"     guint                 : Read
  "roster-manager"           OssoABookRosterManager*  : Read / Write
  "state"                    OssoABookAggregatorState  : Read

Signals

  "ebook-status"                                   : Run Last
  "roster-sequence-complete"                       : Run Last
  "temporary-contact-saved"                        : Run First

Description

The OssoABookAggregator merges information from multiple EBook instances into one single view. One of the books is considered the master address book, the other books ("rosters") provide dynamic presence information.

Details

enum OssoABookAggregatorState

typedef enum {
        OSSO_ABOOK_AGGREGATOR_PENDING       = (0),
        OSSO_ABOOK_AGGREGATOR_RUNNING       = (1 << 0),
        OSSO_ABOOK_AGGREGATOR_MASTERS_READY = (1 << 1),
        OSSO_ABOOK_AGGREGATOR_ROSTERS_READY = (1 << 2),
        OSSO_ABOOK_AGGREGATOR_READY         = (OSSO_ABOOK_AGGREGATOR_MASTERS_READY | OSSO_ABOOK_AGGREGATOR_ROSTERS_READY),
} OssoABookAggregatorState;

OssoABookContactPredicate ()

gboolean            (*OssoABookContactPredicate)        (OssoABookContact *contact,
                                                         gpointer user_data);

OssoABookAggregator

typedef struct _OssoABookAggregator OssoABookAggregator;

All the fields of this structure are private to the object's implementation and should never be accessed directly.


osso_abook_aggregator_new ()

OssoABookRoster*    osso_abook_aggregator_new           (EBook *book,
                                                         GError **error);

Creates a new OssoABookAggregator on top of book.

book : the master addressbook
error : a return location for errors
Returns : A newly allocated OssoABookAggregator, or NULL on error.

osso_abook_aggregator_new_with_query ()

OssoABookRoster*    osso_abook_aggregator_new_with_query
                                                        (EBook *book,
                                                         EBookQuery *query,
                                                         GList *requested_fields,
                                                         int max_results,
                                                         GError **error);

Creates a new OssoABookAggregator on top of book, but only contacts matching the query are considered.

book : the master addressbook
query : the query for choosing contacts
requested_fields : a GList containing the names of fields to return, or NULL for all
max_results : the maximum number of contacts to show (or 0 for all)
error : a return location for errors
Returns : A newly allocated OssoABookAggregator, or NULL on error.

osso_abook_aggregator_new_with_view ()

OssoABookRoster*    osso_abook_aggregator_new_with_view (EBookView *view);

Creates a new OssoABookAggregator on top of view. Usually it is more reasonable to call osso_abook_aggregator_new_with_query() or osso_abook_aggregator_new(), since those functions take care of the burden to open the EBook and the EBookView asynchroniously.

view : the EBookView providing contacts
Returns : A newly allocated OssoABookAggregator.

osso_abook_aggregator_get_default ()

OssoABookRoster*    osso_abook_aggregator_get_default   (GError **error);

osso_abook_aggregator_get_state ()

OssoABookAggregatorState osso_abook_aggregator_get_state
                                                        (OssoABookAggregator *aggregator);

osso_abook_aggregator_lookup ()

GList*              osso_abook_aggregator_lookup        (OssoABookAggregator *aggregator,
                                                         const char *uid);

Lists all master contacts currently known by the aggregator and matching the requested uid. When uid directly matches a master contact, only this contact is returned. When uid matches an attached roster contact all of its master contacts are returned.

aggregator : a OssoABookAggregator
uid : the contact's UID
Returns : A newly allocated list of OssoABookContact instances which has to be freed with g_list_free().

osso_abook_aggregator_get_master_contact_count ()

unsigned            osso_abook_aggregator_get_master_contact_count
                                                        (OssoABookAggregator *aggregator);

osso_abook_aggregator_get_roster_manager ()

OssoABookRosterManager* osso_abook_aggregator_get_roster_manager
                                                        (OssoABookAggregator *aggregator);

Retrieves the current value of the "roster-manager" property.

aggregator : a OssoABookAggregator
Returns : The current value of the property.

osso_abook_aggregator_set_roster_manager ()

void                osso_abook_aggregator_set_roster_manager
                                                        (OssoABookAggregator *aggregator,
                                                         OssoABookRosterManager *manager);

Changes the value of the "roster-manager" property.

aggregator : a OssoABookAggregator
manager : the new OssoABookRosterManager, or NULL

osso_abook_aggregator_add_filter ()

void                osso_abook_aggregator_add_filter    (OssoABookAggregator *aggregator,
                                                         OssoABookContactFilter *filter);

Adds another contact filter to the aggregator. Master contacts will not show up unless they are accepted by all filters. The aggregator will synthesize "contacts-remove" signals when the new filter rejects currently visible contacts.

aggregator : a OssoABookAggregator
filter : the OssoABookContactFilter to add

osso_abook_aggregator_remove_filter ()

void                osso_abook_aggregator_remove_filter (OssoABookAggregator *aggregator,
                                                         OssoABookContactFilter *filter);

Removes a contact filter from the aggregator. Master contacts will not show up unless they are accepted by all filters. The aggregator will synthesize "contacts-added" signals when the filter was the last one rejecting certain contacts.

aggregator : a OssoABookAggregator
filter : the OssoABookContactFilter to remove

Property Details

The "master-contact-count" property

  "master-contact-count"     guint                 : Read

Current number of master contacts in the aggregator.

Default value: 0


The "roster-manager" property

  "roster-manager"           OssoABookRosterManager*  : Read / Write

The OssoABookRosterManager informing this aggregator about new and removed rosters.


The "state" property

  "state"                    OssoABookAggregatorState  : Read

Current state of the aggregator.

Signal Details

The "ebook-status" signal

gboolean            user_function                      (OssoABookAggregator *aggregator,
                                                        guint                status,
                                                        gpointer             user_data)       : Run Last

This signal reports the EBookStatus that is returned when opening the EBook passed to osso_abook_aggregator_new

aggregator : a OssoABookAggregator
status : an EBookStatus
user_data : user data set when the signal handler was connected.

The "roster-sequence-complete" signal

void                user_function                      (OssoABookAggregator *aggregator,
                                                        OssoABookRoster     *roster,
                                                        guint                status,
                                                        gpointer             user_data)       : Run Last

This signal is emitted when on of the underlying rosters reports that there are currently no more contacts to send. It is emitted once after the initial set of "contacts-added" signals, and after every future change.

See also: "sequence-complete"

aggregator : a OssoABookAggregator
roster : the OssoABookRoster
status : an EBookViewStatus
user_data : user data set when the signal handler was connected.

The "temporary-contact-saved" signal

void                user_function                      (OssoABookAggregator *aggregator,
                                                        gchar               *temporary_uid,
                                                        GObject             *persistent,
                                                        gpointer             user_data)          : Run First

This signal is emitted when a temporary master contact was saved and turned into a regular master contact.

aggregator : a OssoABookAggregator
temporary_uid : the contact's temporary UID
persistent : the persistent master contact
user_data : user data set when the signal handler was connected.

See Also

EBookView