![]() |
![]() |
![]() |
Osso Addressbook Reference Manual | ![]() |
---|---|---|---|---|
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); 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);
"master-contact-count" guint : Read "roster-manager" OssoABookRosterManager* : Read / Write "state" OssoABookAggregatorState : Read
"ebook-status" : Run Last "roster-sequence-complete" : Run Last "temporary-contact-saved" : Run First
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.
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
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 |
typedef struct _OssoABookAggregator OssoABookAggregator;
All the fields of this structure are private to the object's implementation and should never be accessed directly.
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.
|
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.
|
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. |
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 |
OssoABookAggregatorState osso_abook_aggregator_get_state (OssoABookAggregator *aggregator);
Gets the current state of aggregator
aggregator : |
a OssoABookAggregator |
Returns : | a set of OssoABookAggregatorState flags |
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() .
|
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() .
|
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() .
|
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() .
|
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 |
GList* osso_abook_aggregator_find_contacts_full (OssoABookAggregator *aggregator, OssoABookContactPredicatepredicate , gpointer user_data);
Finds all contacts in aggregator
that satisfy predicate
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() .
|
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() .
|
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() .
|
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() .
|
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() .
|
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
|
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
|
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 |
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 |
"master-contact-count"
property"master-contact-count" guint : Read
Current number of master contacts in the aggregator.
Default value: 0
"roster-manager"
property"roster-manager" OssoABookRosterManager* : Read / Write
The OssoABookRosterManager informing this aggregator about new and removed rosters.
"ebook-status"
signalgboolean 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. |
"roster-sequence-complete"
signalvoid 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. |
"temporary-contact-saved"
signalvoid 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. |