RAbook

RAbook — The addressbook manager object

Synopsis




#define             R_ABOOK_TYPE
#define             R_ABOOK                             (obj)
#define             R_ABOOK_CLASS                       (klass)
#define             IS_R_ABOOK                          (obj)
#define             IS_R_ABOOK_CLASS                    (klass)
#define             R_ABOOK_GET_CLASS                   (klass)
                    RAbookPrivate;
                    RAbook;
GType               r_abook_get_type                    (void);
RAbook*             r_abook_new                         (void);
void                r_abook_free                        (RAbook *abook);
gboolean            r_abook_open_file                   (RAbook *abook,
                                                         gchar *fname);
gboolean            r_abook_save_file                   (RAbook *abook,
                                                         gchar *fname,
                                                         gint compression_rate);
gboolean            r_abook_overwrite_file              (RAbook *abook,
                                                         gboolean backup,
                                                         gint compression_rate);
RAbook*             r_abook_copy                        (RAbook *abook);
gboolean            r_abook_plugin_from_file            (RAbook *abook,
                                                         gchar *filename);
gboolean            r_abook_load_plugin                 (RAbook *abook,
                                                         const gchar *plugin_name);
gchar*              r_abook_get_plugin_extension        (RAbook *abook);
gpointer            r_abook_get_plugin                  (RAbook *abook);
gpointer            r_abook_get_r_plugin                (RAbook *abook);
gint                r_abook_get_items                   (RAbook *abook);
gint                r_abook_get_deleted                 (RAbook *abook);
gboolean            r_abook_is_empty                    (RAbook *abook);
void                r_abook_add_card                    (RAbook *abook,
                                                         RCard *card);
void                r_abook_add_loaded_card             (RAbook *abook,
                                                         RCard *card);
void                r_abook_paste_card                  (RAbook *abook,
                                                         RCard *card);
void                r_abook_empty_trash                 (RAbook *abook);
void                r_abook_delete_card                 (RAbook *abook,
                                                         RCard *card);
void                r_abook_destroy_card                (RAbook *abook,
                                                         RCard *card);
gboolean            r_abook_recovery_card               (RAbook *abook,
                                                         RCard *card);
void                r_abook_replace_card                (RAbook *abook,
                                                         RCard *old,
                                                         RCard *new);
gpointer            r_abook_get_card                    (RAbook *abook);
gpointer            r_abook_get_next_card               (RAbook *abook);
gpointer            r_abook_get_prev_card               (RAbook *abook);
void                r_abook_reset_book                  (RAbook *abook);
void                r_abook_foreach_card                (RAbook *abook,
                                                         RFunc func,
                                                         gpointer data);
gpointer            r_abook_get_card_by_id              (RAbook *abook,
                                                         glong id);
gpointer            r_abook_get_selected_card           (RAbook *abook);
void                r_abook_unselect_cards              (RAbook *abook);
gpointer            r_abook_get_groups_box              (RAbook *abook);
GList*              r_abook_find_cards_by_group         (RAbook *abook,
                                                         const gchar *group_name);
GList*              r_abook_find_cards_by_type          (RAbook *abook,
                                                         const gchar *type);
GList*              r_abook_find_cards_by_genre         (RAbook *abook,
                                                         const gchar *genre);
GList*              r_abook_find_cards_by_rate          (RAbook *abook,
                                                         RRate rate);
GList*              r_abook_search                      (RAbook *abook,
                                                         const gchar *str);
GList*              r_abook_search_date                 (RAbook *abook,
                                                         gint date,
                                                         SearchType type);
GList*              r_abook_search_between              (RAbook *abook,
                                                         gint first,
                                                         gint second,
                                                         SearchType type);

Object Hierarchy


  GObject
   +----RAbook

Properties


  "addressbook-name"         gchararray            : Read / Write / Construct
  "addressbook-path"         gchararray            : Read / Write / Construct
  "deleted-cards"            gint                  : Read
  "file-filter"              gchararray            : Read / Write / Construct
  "selected-id"              glong                 : Read / Write / Construct

Signals


  "addressbook-changed"                            : Run Last
  "addressbook-closed"                             : Run Last
  "addressbook-read"                               : Run Last
  "addressbook-saved"                              : Run Last
  "card-added"                                     : Run Last
  "card-cutted"                                    : Run Last
  "card-deleted"                                   : Run Last
  "card-destroyed"                                 : Run Last
  "card-read"                                      : Run Last
  "card-recovered"                                 : Run Last
  "card-replaced"                                  : Run Last
  "need-name"                                      : Run Last
  "open-fail"                                      : Run Last
  "save-fail"                                      : Run Last

Description

Descrizione lunga

Details

R_ABOOK_TYPE

#define R_ABOOK_TYPE             (r_abook_get_type())

the RAbook type


R_ABOOK()

#define             R_ABOOK(obj)

obj :

R_ABOOK_CLASS()

#define             R_ABOOK_CLASS(klass)

klass :

IS_R_ABOOK()

#define             IS_R_ABOOK(obj)

obj :

IS_R_ABOOK_CLASS()

#define             IS_R_ABOOK_CLASS(klass)

klass :

R_ABOOK_GET_CLASS()

#define             R_ABOOK_GET_CLASS(klass)

klass :

RAbookPrivate

typedef struct _RAbookPrivate RAbookPrivate;

only private members


RAbook

typedef struct _RAbook RAbook;


r_abook_get_type ()

GType               r_abook_get_type                    (void);

Returns :

r_abook_new ()

RAbook*             r_abook_new                         (void);

create a RAbook

Returns : a new RAbook

r_abook_free ()

void                r_abook_free                        (RAbook *abook);

free the RAbook The "addressbook_closed" signal is emitted

abook : a RAbook

r_abook_open_file ()

gboolean            r_abook_open_file                   (RAbook *abook,
                                                         gchar *fname);

open the addressbook with given name

abook : a RAbook
fname : the name of the addressbook
Returns : TRUE if file is opened successfully, FALSE otherwise

r_abook_save_file ()

gboolean            r_abook_save_file                   (RAbook *abook,
                                                         gchar *fname,
                                                         gint compression_rate);

save the addressbook with given filename

abook : a RAbook
fname : the name of file
compression_rate :
Returns : TRUE if file is saved successfully, FALSE otherwise

r_abook_overwrite_file ()

gboolean            r_abook_overwrite_file              (RAbook *abook,
                                                         gboolean backup,
                                                         gint compression_rate);

overwrite an existing addressbook with a new one. If backup is TRUE the old addressbook is backuped.

abook : a RAbook
backup : boolean
compression_rate :
Returns : a TRUE if old addressbook was successfully overwited, FALSE otherwise

r_abook_copy ()

RAbook*             r_abook_copy                        (RAbook *abook);

copy the addressbook pointed by abook

abook : a RAbook
Returns : a new RAbook

r_abook_plugin_from_file ()

gboolean            r_abook_plugin_from_file            (RAbook *abook,
                                                         gchar *filename);

Try to load the plugin using the file extension. If the file has a known extension the rigth plugin is loaded.

abook : a RAbook
filename : gchar*
Returns : TRUE if plugin is loaded, FALSE otherwise

r_abook_load_plugin ()

gboolean            r_abook_load_plugin                 (RAbook *abook,
                                                         const gchar *plugin_name);

Load the "plugin_name" plugin.

abook : a RAbook
plugin_name : const gchar*
Returns : TRUE if plugin is loaded, FALSE otherwise

r_abook_get_plugin_extension ()

gchar*              r_abook_get_plugin_extension        (RAbook *abook);

Get the extension that is associate to the current active plugin

abook : a RAbook
Returns : a gchar* or NULL if an error occured

r_abook_get_plugin ()

gpointer            r_abook_get_plugin                  (RAbook *abook);

Get the currently active plugin (the real plugin)

abook : a RAbook
Returns : a gpointer to the plugin

r_abook_get_r_plugin ()

gpointer            r_abook_get_r_plugin                (RAbook *abook);

Get the currently active plugin (ptr to an RPlugin struct)

abook : a RAbook
Returns : a gpointer to the plugin

r_abook_get_items ()

gint                r_abook_get_items                   (RAbook *abook);

get the number of cards into addressbok

abook : a RAbook
Returns : an integer

r_abook_get_deleted ()

gint                r_abook_get_deleted                 (RAbook *abook);

abook :
Returns :

r_abook_is_empty ()

gboolean            r_abook_is_empty                    (RAbook *abook);

is the addressbook empty?

abook : a RAbook
Returns : a boolean. TRUE if addressbook is empty, FALSE otherwise

r_abook_add_card ()

void                r_abook_add_card                    (RAbook *abook,
                                                         RCard *card);

append the given card into the addressbook The "card_added" and "addressbook_changed" signals are emitted

abook : a RAbook
card : an RCard object

r_abook_add_loaded_card ()

void                r_abook_add_loaded_card             (RAbook *abook,
                                                         RCard *card);

append the card read from disk into the addressbook

abook : a RAbook
card : an RCard object

r_abook_paste_card ()

void                r_abook_paste_card                  (RAbook *abook,
                                                         RCard *card);

peste the given card into the addressbook (append the card)

abook : a RAbook
card : an RCard object

r_abook_empty_trash ()

void                r_abook_empty_trash                 (RAbook *abook);

Destroy all cards in the trash. The destroyed cards are unrecoverable the "addressbook_changed" signal is emitted

abook : a RAbook

r_abook_delete_card ()

void                r_abook_delete_card                 (RAbook *abook,
                                                         RCard *card);

mark the given card as delete. The id of the card is appended to the addressbook's trash The "card_removed" and "addressbook_changed" signals are emitted

abook : a RAbook
card : an RCard object

r_abook_destroy_card ()

void                r_abook_destroy_card                (RAbook *abook,
                                                         RCard *card);

Destroy the given card. The destroyed cards are unrecoverable The "card_destroyed" and "addressbook_changed" signals are emitted

abook : a RAbook
card : an RCard object

r_abook_recovery_card ()

gboolean            r_abook_recovery_card               (RAbook *abook,
                                                         RCard *card);

unmark the card previously marked as deleted. The "card_recovered" and "addressbook_changed" signals are emitted

abook : a RAbook
card : an RCard object
Returns : TRUE if card is successfully recovered, FALSE otherwise

r_abook_replace_card ()

void                r_abook_replace_card                (RAbook *abook,
                                                         RCard *old,
                                                         RCard *new);

replace the old card with the new one The "card_replaced" and "addressbook_changed" signals are emitted

abook : a RAbook
old : an RCard object
new : an RCard object

r_abook_get_card ()

gpointer            r_abook_get_card                    (RAbook *abook);

Get the first card in addressbook.

abook : a RAbook
Returns : a pointer to the card or NULL if addressbook is empty

r_abook_get_next_card ()

gpointer            r_abook_get_next_card               (RAbook *abook);

get the next card in addressbook

abook : a RAbook
Returns : a pointer to the card or NULL if the cards's end list is reached.

r_abook_get_prev_card ()

gpointer            r_abook_get_prev_card               (RAbook *abook);

get the previous card in addressbook

abook : a RAbook
Returns : a pointer to the card or NULL if the cards's head list is reached.

r_abook_reset_book ()

void                r_abook_reset_book                  (RAbook *abook);

reset the private addressbook iterator. The iterator will point the head of cards's list.

abook : a RAbook

r_abook_foreach_card ()

void                r_abook_foreach_card                (RAbook *abook,
                                                         RFunc func,
                                                         gpointer data);

Call the function func() for each card in the RAbook.

abook : a RAbook
func : the RFunc that will be called for each card in addressbook
data : user's data to pass to func

r_abook_get_card_by_id ()

gpointer            r_abook_get_card_by_id              (RAbook *abook,
                                                         glong id);

get the card with "id" id

abook : a RAbook
id : the card id
Returns : a pointer to the card or NULL if addressbook doesn't own that card

r_abook_get_selected_card ()

gpointer            r_abook_get_selected_card           (RAbook *abook);

Get the selected card in the addressbook

abook : a RAbook
Returns :

r_abook_unselect_cards ()

void                r_abook_unselect_cards              (RAbook *abook);

unselect card. Clear previpus selections

abook : a RAbook

r_abook_get_groups_box ()

gpointer            r_abook_get_groups_box              (RAbook *abook);

abook :
Returns :

r_abook_find_cards_by_group ()

GList*              r_abook_find_cards_by_group         (RAbook *abook,
                                                         const gchar *group_name);

Find all cards that belongs to the given group. Found cards's ID has inserted in a GList. Caller must free returned GList

abook : a RAbook
group_name : the name of the group
Returns : a GList* or NULL if no cards belong to group

r_abook_find_cards_by_type ()

GList*              r_abook_find_cards_by_type          (RAbook *abook,
                                                         const gchar *type);

abook :
type :
Returns :

r_abook_find_cards_by_genre ()

GList*              r_abook_find_cards_by_genre         (RAbook *abook,
                                                         const gchar *genre);

abook :
genre :
Returns :

r_abook_find_cards_by_rate ()

GList*              r_abook_find_cards_by_rate          (RAbook *abook,
                                                         RRate rate);

abook :
rate :
Returns :

r_abook_search ()

GList*              r_abook_search                      (RAbook *abook,
                                                         const gchar *str);

abook :
str :
Returns :

r_abook_search_date ()

GList*              r_abook_search_date                 (RAbook *abook,
                                                         gint date,
                                                         SearchType type);

abook :
date :
type :
Returns :

r_abook_search_between ()

GList*              r_abook_search_between              (RAbook *abook,
                                                         gint first,
                                                         gint second,
                                                         SearchType type);

abook :
first :
second :
type :
Returns :

Property Details

The "addressbook-name" property

  "addressbook-name"         gchararray            : Read / Write / Construct

the name (filename) of the addressbook.

Default value: NULL


The "addressbook-path" property

  "addressbook-path"         gchararray            : Read / Write / Construct

the path of the addressbook.

Default value: NULL


The "deleted-cards" property

  "deleted-cards"            gint                  : Read

number of cards marked as deleted in the addressbook.

Default value: 0


The "file-filter" property

  "file-filter"              gchararray            : Read / Write / Construct

filter used to identify the file's type.

Default value: NULL


The "selected-id" property

  "selected-id"              glong                 : Read / Write / Construct

load/save the id of the selected card.

Default value: 0

Signal Details

The "addressbook-changed" signal

void                user_function                      (RAbook  *abook,
                                                        gpointer user_data)      : Run Last

The "addressbook_changed" signal

abook : the RAbook object that receives the signal
user_data : user data set when the signal handler was connected.

The "addressbook-closed" signal

void                user_function                      (RAbook  *abook,
                                                        gpointer user_data)      : Run Last

The "addressbook_closed" signal

abook : the RAbook object that receives the signal
user_data : user data set when the signal handler was connected.

The "addressbook-read" signal

void                user_function                      (RAbook  *abook,
                                                        gpointer user_data)      : Run Last

The "addressbook-read" signal is emitted when the addressbook is read

abook : the RAbook object that receives the signal
user_data : user data set when the signal handler was connected.

The "addressbook-saved" signal

void                user_function                      (RAbook  *abook,
                                                        gpointer user_data)      : Run Last

The "addressbook_saved" signal

abook : the RAbook object that receives the signal
user_data : user data set when the signal handler was connected.

The "card-added" signal

void                user_function                      (RAbook  *abook,
                                                        gpointer data,
                                                        gpointer user_data)      : Run Last

The "card-added" signal is emitted after a card is added to addressbook. A pointer to the card is passed to the callback function

abook : the RAbook object that receives the signal
data : a pointer to the readed card
user_data : user data set when the signal handler was connected.

The "card-cutted" signal

void                user_function                      (RAbook  *abook,
                                                        gpointer data,
                                                        gpointer user_data)      : Run Last

The "card-cutted" signal is emitted when a card in the addressbook is cutted. A pointer to the cutted card is passed to the callback function

abook : the RAbook object that receives the signal
data : a pointer to the cutted card
user_data : user data set when the signal handler was connected.

The "card-deleted" signal

void                user_function                      (RAbook  *abook,
                                                        gpointer arg1,
                                                        gpointer user_data)      : Run Last

The "card-removed" signal is emitted when a card is (deleted) removed from addressbook. The removed cards are marked as deleted, to really delete (remove) the card you must destroy it. You can recover (deleted) removed cards. Destroyed cards are unrecoverable

abook : the RAbook object that receives the signal
user_data : user data set when the signal handler was connected.

The "card-destroyed" signal

void                user_function                      (RAbook  *abook,
                                                        gchar   *arg1,
                                                        gpointer user_data)      : Run Last

The "card-destroyed" signal is emitted when a card is deleted from addressbook. Destroyed cards are unrecoverable.

abook : the RAbook object that receives the signal
user_data : user data set when the signal handler was connected.

The "card-read" signal

void                user_function                      (RAbook  *abook,
                                                        gpointer data,
                                                        gpointer user_data)      : Run Last

The "card-read" signal is emitted after the addressbook has been readed

abook : the RAbook object that receives the signal
data : a pointer to the readed card
user_data : user data set when the signal handler was connected.

The "card-recovered" signal

void                user_function                      (RAbook  *abook,
                                                        gpointer arg1,
                                                        gpointer user_data)      : Run Last

The "card-recovered" signal is emitted when a previously deleted marked card is unmarked.

abook : the RAbook object that receives the signal
user_data : user data set when the signal handler was connected.

The "card-replaced" signal

void                user_function                      (RAbook  *abook,
                                                        gpointer data,
                                                        gpointer user_data)      : Run Last

The "card-replaced" signal is emitted on a card replacement. A pointer to the new card is passed to the callback function

abook : the RAbook object that receives the signal
data : a pointer to the readed card
user_data : user data set when the signal handler was connected.

The "need-name" signal

void                user_function                      (RAbook  *abook,
                                                        gpointer user_data)      : Run Last

The "need-name" signal is emitted if user tries to save an addressbook without giving a filename to it

abook : the RAbook object that receives the signal
user_data : user data set when the signal handler was connected.

The "open-fail" signal

void                user_function                      (RAbook  *abook,
                                                        gint     err,
                                                        gpointer user_data)      : Run Last

the "open-fail" signal is emitted if the given file can't be read

abook : the RAbook object that receives the signal
err : an RError
user_data : user data set when the signal handler was connected.

The "save-fail" signal

void                user_function                      (RAbook  *abook,
                                                        gint     err,
                                                        gpointer user_data)      : Run Last

the "save-fail" signal is emitted if the given file can't be read

abook : the RAbook object that receives the signal
err : an RError
user_data : user data set when the signal handler was connected.