Contacts Database

Contacts Database — API description for the GPE contacts database.

Synopsis




#define     CONFIG_PANEL
#define     CONFIG_LIST
int         db_open                         (gboolean open_vcard);
int         contacts_db_open                (gboolean open_vcard);
int         contacts_db_close               (void);
struct      contacts_tag_value;
struct contacts_tag_value* contacts_new_tag_value
                                            (gchar*,
                                             gchar*);
void        contacts_free_tag_values        (GSList*);
void        contacts_update_tag_value       (struct contacts_tag_value *t,
                                             gchar *value);
struct      contacts_person;
struct contacts_person* contacts_new_person (void);
gboolean    contacts_commit_person          (struct contacts_person*);
void        contacts_discard_person         (struct contacts_person*);
void        contacts_db_set_data            (struct contacts_person*,
                                             gchar *tag,
                                             gchar *value);
struct contacts_tag_value* contacts_db_find_tag
                                            (struct contacts_person *p,
                                             gchar *tag);
GSList*     contacts_db_get_entries         (void);
GSList*     contacts_db_get_entries_finddlg (const gchar *str,
                                             const gchar *cat);
GSList*     contacts_db_get_entries_list    (const gchar *name,
                                             const gchar *cat);
GSList*     contacts_db_get_entries_list_filtered
                                            (const gchar *str,
                                             const gchar *filter,
                                             const gchar *cat);
struct contacts_person* contacts_db_get_by_uid
                                            (guint uid);
gboolean    contacts_db_delete_by_uid       (guint uid);
void        contacts_db_set_multi_data      (struct contacts_person *p,
                                             gchar *tag,
                                             gchar *value);
void        contacts_db_delete_tag          (struct contacts_person *p,
                                             gchar *tag);
gint        contacts_db_get_tag_list        (gchar ***list);
gint        contacts_db_get_config_values   (gint group,
                                             gchar ***list);
void        contacts_db_add_config_values   (gint group,
                                             gchar *identifier,
                                             gchar *value);
void        contacts_db_delete_config_values
                                            (gint group,
                                             gchar *identifier);
void        contacts_db_update_config_values
                                            (gint group,
                                             gchar *identifier,
                                             gchar *value);
gchar*      contacts_db_get_config_tag      (gint group,
                                             const gchar *tagname);
void        contacts_db_free_result         (char **table);
gint        contacts_sort_entries           (struct contacts_person *a,
                                             struct contacts_person *b);
gchar*      contacts_db_compress            (void);
gint        contacts_db_size                (void);

Description

This section documents the GPE contacts database API. The current implementation of the database makes use of the SQLite in-process database engine for data storage.

Details

CONFIG_PANEL

#define CONFIG_PANEL 0

CONFIG_LIST

#define CONFIG_LIST  1

db_open ()

int         db_open                         (gboolean open_vcard);

open_vcard :
Returns :

contacts_db_open ()

int         contacts_db_open                (gboolean open_vcard);

Open and initalise the contacts database. This also performs an up-to-date check and if necessary a database update. If you open your personal vCard database you access the databse file that contains the personal vCard(s) used by other tools.

This API is likely to change soon.

open_vcard : Wether to open the personal vCard database.
Returns : 0 on success, error code otherwise.

contacts_db_close ()

int         contacts_db_close               (void);

Close the contacts database.

Returns : 0 on success

struct contacts_tag_value

struct contacts_tag_value {
  gchar *tag;
  gchar *value;
};

contacts_new_tag_value ()

struct contacts_tag_value* contacts_new_tag_value
                                            (gchar*,
                                             gchar*);

Param1 :
Param2 :
Returns :

contacts_free_tag_values ()

void        contacts_free_tag_values        (GSList*);

Param1 :

contacts_update_tag_value ()

void        contacts_update_tag_value       (struct contacts_tag_value *t,
                                             gchar *value);

Update a tag-value pair with a new string value.

t : Tag-value struct
value : New value

struct contacts_person

struct contacts_person {
  guint id;
  gchar *name;
  gchar *family_name;
  gchar *company;
  GSList *data;
};

contacts_new_person ()

struct contacts_person* contacts_new_person (void);

Allocates and initializes a new contacts_person data structure. The returend value needs to be destroyed with contacts_discard_person.

Returns : A new allocated contacts_person structure.

contacts_commit_person ()

gboolean    contacts_commit_person          (struct contacts_person*);

Param1 :
Returns :

contacts_discard_person ()

void        contacts_discard_person         (struct contacts_person*);

Frees all memory allocated by a person struct.

Param1 :

contacts_db_set_data ()

void        contacts_db_set_data            (struct contacts_person*,
                                             gchar *tag,
                                             gchar *value);

Param1 :
tag :
value :

contacts_db_find_tag ()

struct contacts_tag_value* contacts_db_find_tag
                                            (struct contacts_person *p,
                                             gchar *tag);

p :
tag :
Returns :

contacts_db_get_entries ()

GSList*     contacts_db_get_entries         (void);

Retrieve all entries from the contacts database.

Returns : A GSList of new allocated person structs on success. NULL on failure or if the database is empty.

contacts_db_get_entries_finddlg ()

GSList*     contacts_db_get_entries_finddlg (const gchar *str,
                                             const gchar *cat);

Works like contacts_db_get_entries_list but all data fields are searched for the pattern in str.

str : Pattern
cat : Category pattern
Returns : A GSList of new allocated person structs on success. NULL on failure or if no person matches the given criteria.

contacts_db_get_entries_list ()

GSList*     contacts_db_get_entries_list    (const gchar *name,
                                             const gchar *cat);

Retrieve entries from the contacts database matching certain criteria: If name is given some basic fields (name, family_name, company) are searched if they contain the string given by name. If name is NULL, this parameter is ignored. The cat parameter can be used to specify a category to cut down the result on entries of the given category. Like name this parameter is ignored if set to NULL.

name : Name search criterion
cat : Category pattern
Returns : A GSList of new allocated person structs on success. NULL on failure or if no person matches the given criteria.

contacts_db_get_entries_list_filtered ()

GSList*     contacts_db_get_entries_list_filtered
                                            (const gchar *str,
                                             const gchar *filter,
                                             const gchar *cat);

str :
filter :
cat :
Returns :

contacts_db_get_by_uid ()

struct contacts_person* contacts_db_get_by_uid
                                            (guint uid);

uid :
Returns :

contacts_db_delete_by_uid ()

gboolean    contacts_db_delete_by_uid       (guint uid);

uid :
Returns :

contacts_db_set_multi_data ()

void        contacts_db_set_multi_data      (struct contacts_person *p,
                                             gchar *tag,
                                             gchar *value);

p :
tag :
value :

contacts_db_delete_tag ()

void        contacts_db_delete_tag          (struct contacts_person *p,
                                             gchar *tag);

p :
tag :

contacts_db_get_tag_list ()

gint        contacts_db_get_tag_list        (gchar ***list);

list :
Returns :

contacts_db_get_config_values ()

gint        contacts_db_get_config_values   (gint group,
                                             gchar ***list);

group :
list :
Returns :

contacts_db_add_config_values ()

void        contacts_db_add_config_values   (gint group,
                                             gchar *identifier,
                                             gchar *value);

group :
identifier :
value :

contacts_db_delete_config_values ()

void        contacts_db_delete_config_values
                                            (gint group,
                                             gchar *identifier);

group :
identifier :

contacts_db_update_config_values ()

void        contacts_db_update_config_values
                                            (gint group,
                                             gchar *identifier,
                                             gchar *value);

group :
identifier :
value :

contacts_db_get_config_tag ()

gchar*      contacts_db_get_config_tag      (gint group,
                                             const gchar *tagname);

group :
tagname :
Returns :

contacts_db_free_result ()

void        contacts_db_free_result         (char **table);

table :

contacts_sort_entries ()

gint        contacts_sort_entries           (struct contacts_person *a,
                                             struct contacts_person *b);

a :
b :
Returns :

contacts_db_compress ()

gchar*      contacts_db_compress            (void);

Returns :

contacts_db_size ()

gint        contacts_db_size                (void);

Returns :