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);
GList*              osso_abook_aggregator_resolve_master_contacts
                                                        (OssoABookAggregator *aggregator,
                                                         OssoABookContact *contact);
GList*              osso_abook_aggregator_list_master_contacts
                                                        (OssoABookAggregator *aggregator);
GList*              osso_abook_aggregator_list_roster_contacts
                                                        (OssoABookAggregator *aggregator);
unsigned            osso_abook_aggregator_get_master_contact_count
                                                        (OssoABookAggregator *aggregator);
GList*              osso_abook_aggregator_find_contacts_full
                                                        (OssoABookAggregator *aggregator,
                                                         OssoABookContactPredicatepredicate ,
                                                         gpointer user_data);
GList*              osso_abook_aggregator_find_contacts (OssoABookAggregator *aggregator,
                                                         EBookQuery *query);
GList*              osso_abook_aggregator_find_contacts_for_phone_number
                                                        (OssoABookAggregator *aggregator,
                                                         const char *phone_number,
                                                         gboolean fuzzy_match);
GList*              osso_abook_aggregator_find_contacts_for_im_contact
                                                        (OssoABookAggregator *aggregator,
                                                         const char *username,
                                                         McAccount *account);
GList*              osso_abook_aggregator_find_contacts_for_email_address
                                                        (OssoABookAggregator *aggregator,
                                                         const char *address);
GList*              osso_abook_aggregator_find_contacts_for_sip_address
                                                        (OssoABookAggregator *aggregator,
                                                         const char *address);
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;

Flags representing the current state of an aggregator

OSSO_ABOOK_AGGREGATOR_PENDING the aggregator is not yet running
OSSO_ABOOK_AGGREGATOR_RUNNING the aggregator is running
OSSO_ABOOK_AGGREGATOR_MASTERS_READY the master contacts are ready
OSSO_ABOOK_AGGREGATOR_ROSTERS_READY the roster contacts are ready
OSSO_ABOOK_AGGREGATOR_READY The aggregator is ready

OssoABookContactPredicate ()

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

A function that can be used to select or reject a contact.

contact : a contact to operate on
user_data : additional user data passed to the function

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 simpler to call osso_abook_aggregator_new_with_query() or osso_abook_aggregator_new(), since those functions handle the burden of opening the EBook and the EBookView asynchronously.

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

osso_abook_aggregator_get_default ()

OssoABookRoster*    osso_abook_aggregator_get_default   (GError **error);

Gets the default aggregator, which aggregates the system addressbook

error : a return location for errors
Returns : the default aggregator, owned by libosso-abook

osso_abook_aggregator_get_state ()

OssoABookAggregatorState osso_abook_aggregator_get_state
                                                        (OssoABookAggregator *aggregator);

Gets the current state of aggregator

aggregator : a OssoABookAggregator
Returns : a set of OssoABookAggregatorState flags

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. The contents of the list are owned by aggregator, but the list itself must be freed with g_list_free().

osso_abook_aggregator_resolve_master_contacts ()

GList*              osso_abook_aggregator_resolve_master_contacts
                                                        (OssoABookAggregator *aggregator,
                                                         OssoABookContact *contact);

Resolves the master contacts associated with some roster contact, as far as this aggregator knows them.

aggregator : a OssoABookAggregator
contact : the contact for which to resolve the master contacts
Returns : A newly allocated list of OssoABookContact instances. The contents of the list are owned by aggregator, but the list itself must be freed with g_list_free().

osso_abook_aggregator_list_master_contacts ()

GList*              osso_abook_aggregator_list_master_contacts
                                                        (OssoABookAggregator *aggregator);

Lists all currently known master contacts.

aggregator : a OssoABookAggregator
Returns : A newly allocated list of OssoABookContact instances. The contents of the list are owned by aggregator, but the list itself must be freed with g_list_free().

osso_abook_aggregator_list_roster_contacts ()

GList*              osso_abook_aggregator_list_roster_contacts
                                                        (OssoABookAggregator *aggregator);

Lists all currently known roster contacts.

aggregator : a OssoABookAggregator
Returns : A newly allocated list of OssoABookContact instances. The contents of the list are owned by aggregator, but the list itself must be freed with g_list_free().

osso_abook_aggregator_get_master_contact_count ()

unsigned            osso_abook_aggregator_get_master_contact_count
                                                        (OssoABookAggregator *aggregator);

Gets the total number of master contacts in aggregator

aggregator : a OssoABookAggregator
Returns : the number of master contacts

osso_abook_aggregator_find_contacts_full ()

GList*              osso_abook_aggregator_find_contacts_full
                                                        (OssoABookAggregator *aggregator,
                                                         OssoABookContactPredicatepredicate ,
                                                         gpointer user_data);

Finds all contacts in aggregator that satisfy predicate. Note that the returned contacts could not match directly the predicate, but are still returned because one of the associated roster contacts matches it.

aggregator : a OssoABookAggregator
predicate : a predicate function to filter contacts
user_data : additional data to pass to predicate
Returns : A newly allocated list of OssoABookContact instances. The contents of the list are owned by aggregator, but the list itself must be freed with g_list_free().

osso_abook_aggregator_find_contacts ()

GList*              osso_abook_aggregator_find_contacts (OssoABookAggregator *aggregator,
                                                         EBookQuery *query);

Finds all contacts in aggregator that satisfy query

aggregator : a OssoABookAggregator
query : a EBookQuery to filter contacts
Returns : A newly allocated list of OssoABookContact instances. The contents of the list are owned by aggregator, but the list itself must be freed with g_list_free().

osso_abook_aggregator_find_contacts_for_phone_number ()

GList*              osso_abook_aggregator_find_contacts_for_phone_number
                                                        (OssoABookAggregator *aggregator,
                                                         const char *phone_number,
                                                         gboolean fuzzy_match);

Finds all contacts in aggregator that contain the specified phone_number. For details about fuzzy_match, see osso_abook_query_phone_number()

aggregator : a OssoABookAggregator
phone_number : a phone number as a string
fuzzy_match : whether fuzzy matching is wanted
Returns : A newly allocated list of OssoABookContact instances. The contents of the list are owned by aggregator, but the list itself must be freed with g_list_free().

osso_abook_aggregator_find_contacts_for_im_contact ()

GList*              osso_abook_aggregator_find_contacts_for_im_contact
                                                        (OssoABookAggregator *aggregator,
                                                         const char *username,
                                                         McAccount *account);

Finds all contacts in aggregator that contain the specified username. If account is not NULL, the returned contacts must match the account in addition to the username.

aggregator : a OssoABookAggregator
username : an IM username
account : an optional account for username
Returns : A newly allocated list of OssoABookContact instances. The contents of the list are owned by aggregator, but the list itself must be freed with g_list_free().

osso_abook_aggregator_find_contacts_for_email_address ()

GList*              osso_abook_aggregator_find_contacts_for_email_address
                                                        (OssoABookAggregator *aggregator,
                                                         const char *address);

Finds all contacts in aggregator that contain the specified address.

aggregator : a OssoABookAggregator
address : an email address
Returns : A newly allocated list of OssoABookContact instances. The contents of the list are owned by aggregator, but the list itself must be freed with g_list_free().

osso_abook_aggregator_find_contacts_for_sip_address ()

GList*              osso_abook_aggregator_find_contacts_for_sip_address
                                                        (OssoABookAggregator *aggregator,
                                                         const char *address);

Finds all contacts in aggregator that contain the specified address.

aggregator : a OssoABookAggregator
address : an sip address
Returns : A newly allocated list of OssoABookContact instances. The contents of the list are owned by aggregator, but the list itself must be freed with g_list_free().

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, owned by aggregator

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 a contact.

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
Generated by GTK-Doc V1.10