kabc Library API Documentation

KABC::AddressBook Class Reference

Address Book. More...

#include <addressbook.h>

Inheritance diagram for KABC::AddressBook:

QObject KABC::StdAddressBook List of all members.

Signals

void addressBookChanged (AddressBook *addressBook)
void addressBookLocked (AddressBook *addressBook)
void addressBookUnlocked (AddressBook *addressBook)
void loadingFinished (Resource *resource)
void savingFinished (Resource *resource)

Public Methods

 AddressBook ()
 AddressBook (const QString &config)
virtual ~AddressBook ()
TicketrequestSaveTicket (Resource *resource=0)
void releaseSaveTicket (Ticket *ticket)
bool load ()
bool asyncLoad ()
bool save (Ticket *ticket)
bool asyncSave (Ticket *ticket)
ConstIterator begin () const
Iterator begin ()
ConstIterator end () const
Iterator end ()
void clear ()
void insertAddressee (const Addressee &addr)
void removeAddressee (const Addressee &addr)
void removeAddressee (const Iterator &it)
Iterator find (const Addressee &addr)
Addressee findByUid (const QString &uid)
Addressee::List allAddressees ()
Addressee::List findByName (const QString &name)
Addressee::List findByEmail (const QString &email)
Addressee::List findByCategory (const QString &category)
virtual QString identifier ()
Field::List fields (int category=Field::All)
bool addCustomField (const QString &label, int category=Field::All, const QString &key=QString::null, const QString &app=QString::null)
bool addResource (Resource *resource)
bool removeResource (Resource *resource)
QPtrList< Resource > resources ()
void setErrorHandler (ErrorHandler *errorHandler)
void error (const QString &msg)
void cleanUp () KDE_DEPRECATED
void dump () const
void emitAddressBookLocked ()
void emitAddressBookUnlocked ()
void emitAddressBookChanged ()

Protected Slots

void resourceLoadingFinished (Resource *)
void resourceSavingFinished (Resource *)
void resourceLoadingError (Resource *, const QString &)
void resourceSavingError (Resource *, const QString &)

Protected Methods

void deleteRemovedAddressees ()
void setStandardResource (Resource *)
Resource * standardResource ()
KRES::Manager< Resource > * resourceManager ()

Friends

class StdAddressBook
Q_OBJECT friend QDataStreamoperator<< (QDataStream &, const AddressBook &)
QDataStreamoperator>> (QDataStream &, AddressBook &)

Detailed Description

Address Book.

This class provides access to a collection of address book entries.

Definition at line 43 of file addressbook.h.


Constructor & Destructor Documentation

AddressBook::AddressBook  
 

Constructs an address book object.

You have to add the resources manually before calling load().

Definition at line 296 of file addressbook.cpp.

AddressBook::AddressBook const QString   config
 

Constructs an address book object.

The resources are loaded automatically.

Parameters:
config  The config file which contains the resource settings.

Definition at line 306 of file addressbook.cpp.

References QString::isEmpty().

AddressBook::~AddressBook   [virtual]
 

Destructor.

Definition at line 320 of file addressbook.cpp.


Member Function Documentation

Ticket * AddressBook::requestSaveTicket Resource *    resource = 0
 

Requests a ticket for saving the addressbook.

Calling this function locks the addressbook for all other processes. You need the returned ticket object for calling the save() function.

Parameters:
resource  A pointer to the resource which shall be locked. If 0, the default resource is locked.
Returns:
0 if the resource is already locked or a valid save ticket otherwise.
See also:
save()

Definition at line 480 of file addressbook.cpp.

void AddressBook::releaseSaveTicket Ticket   ticket
 

Releases the ticket requested previously with requestSaveTicket().

Call this function, if you want to release a ticket without saving.

Definition at line 500 of file addressbook.cpp.

References KABC::Ticket::resource().

bool AddressBook::load  
 

Loads all addressees synchronously.

Returns:
Whether the loading was successfully.

Definition at line 328 of file addressbook.cpp.

References clear(), and error().

bool AddressBook::asyncLoad  
 

Loads all addressees asynchronously.

This function returns immediately and emits the addressBookChanged() signal as soon as the loading has finished.

Returns:
Whether the synchronous part of loading was successfully.

Definition at line 346 of file addressbook.cpp.

References clear(), and error().

bool AddressBook::save Ticket   ticket
 

Saves all addressees of one resource synchronously.

If the save is successfull the ticket is deleted.

Parameters:
ticket  The ticket returned by requestSaveTicket().
Returns:
Whether the saving was successfully.

Definition at line 365 of file addressbook.cpp.

References KABC::Ticket::resource().

bool AddressBook::asyncSave Ticket   ticket
 

Saves all addressees of one resource asynchronously.

If the save is successfull the ticket is deleted.

Parameters:
ticket  The ticket returned by requestSaveTicket().
Returns:
Whether the synchronous part of saving was successfully.

Definition at line 379 of file addressbook.cpp.

References KABC::Ticket::resource().

AddressBook::ConstIterator AddressBook::begin   const
 

Returns an iterator pointing to the first addressee of address book.

This iterator equals end() if the address book is empty.

Definition at line 420 of file addressbook.cpp.

References QValueList::append(), QValueList::count(), KABC::AddressBook::Iterator::d, and end().

Referenced by allAddressees(), dump(), and find().

AddressBook::Iterator AddressBook::begin  
 

This is an overloaded member function, provided for convenience.

It behaves essentially like the above function.

Definition at line 393 of file addressbook.cpp.

References QValueList::append(), QValueList::count(), KABC::AddressBook::Iterator::d, and end().

AddressBook::ConstIterator AddressBook::end   const
 

Returns an iterator pointing to the last addressee of address book.

This iterator equals begin() if the address book is empty.

Definition at line 460 of file addressbook.cpp.

Referenced by allAddressees(), begin(), dump(), and find().

AddressBook::Iterator AddressBook::end  
 

This is an overloaded member function, provided for convenience.

It behaves essentially like the above function.

Definition at line 447 of file addressbook.cpp.

void AddressBook::clear  
 

Removes all addressees from the address book.

Definition at line 473 of file addressbook.cpp.

Referenced by asyncLoad(), and load().

void AddressBook::insertAddressee const Addressee   addr
 

Insert an addressee into the address book.

If an addressee with the same unique id already exists, it is replaced by the new one, otherwise it is appended.

Parameters:
addr  The addressee which shall be insert.

Definition at line 510 of file addressbook.cpp.

References QDateTime::currentDateTime(), KABC::Addressee::isEmpty(), KABC::Addressee::resource(), KABC::Addressee::setChanged(), KABC::Addressee::setResource(), and KABC::Addressee::uid().

Referenced by KABC::VCard21Parser::readFromString().

void AddressBook::removeAddressee const Addressee   addr
 

Removes an addressee from the address book.

Parameters:
addr  The addressee which shall be removed.

Definition at line 538 of file addressbook.cpp.

References KABC::Addressee::resource().

void AddressBook::removeAddressee const Iterator   it
 

This is an overloaded member function, provided for convenience.

It behaves essentially like the above function.

Parameters:
it  An iterator pointing to the addressee which shall be removed.

Definition at line 544 of file addressbook.cpp.

AddressBook::Iterator AddressBook::find const Addressee   addr
 

Returns an iterator pointing to the specified addressee.

It will return end() if no addressee matched.

Parameters:
addr  The addresee you are looking for.

Definition at line 550 of file addressbook.cpp.

References begin(), end(), and KABC::Addressee::uid().

Addressee AddressBook::findByUid const QString   uid
 

Searches an addressee with the specified unique identifier.

Parameters:
uid  The unique identifier you are looking for.
Returns:
The addressee with the specified unique identifier or an empty addressee.

Definition at line 561 of file addressbook.cpp.

References KABC::Addressee::isEmpty().

Referenced by KABC::DistributionListManager::load(), and KABC::StdAddressBook::whoAmI().

Addressee::List AddressBook::allAddressees  
 

Returns a list of all addressees in the address book.

Definition at line 573 of file addressbook.cpp.

References begin(), and end().

Addressee::List AddressBook::findByName const QString   name
 

Searches all addressees which match the specified name.

Parameters:
name  The name you are looking for.
Returns:
A list of all matching addressees.

Definition at line 584 of file addressbook.cpp.

Addressee::List AddressBook::findByEmail const QString   email
 

Searches all addressees which match the specified email address.

Parameters:
email  The email address you are looking for.
Returns:
A list of all matching addressees.

Definition at line 595 of file addressbook.cpp.

Addressee::List AddressBook::findByCategory const QString   category
 

Searches all addressees which belongs to the specified category.

Parameters:
category  The category you are looking for.
Returns:
A list of all matching addressees.

Definition at line 606 of file addressbook.cpp.

QString AddressBook::identifier   [virtual]
 

Returns a string identifying this addressbook.

The identifier is created by concatenation of the resource identifiers.

Definition at line 629 of file addressbook.cpp.

References identifier(), and QStringList::join().

Referenced by identifier(), KABC::DistributionListManager::load(), and KABC::DistributionListManager::save().

Field::List AddressBook::fields int    category = Field::All
 

Returns a list of all Fields known to the address book which are associated with the given field category.

Definition at line 643 of file addressbook.cpp.

bool AddressBook::addCustomField const QString   label,
int    category = Field::All,
const QString   key = QString::null,
const QString   app = QString::null
 

Add custom field to address book.

Parameters:
label  User visible label of the field.
category  Ored list of field categories.
key  Identifier used as key for reading and writing the field.
app  String used as application key for reading and writing the field.

Definition at line 660 of file addressbook.cpp.

References KGlobal::instance(), KInstance::instanceName(), QString::isNull(), KStdAccel::key(), and KStdAccel::label().

bool AddressBook::addResource Resource *    resource
 

Adds a resource to the address book.

Parameters:
resource  The resource you want to add.
Returns:
Whether opening the resource was successfully.

Definition at line 695 of file addressbook.cpp.

References QObject::connect(), loadingFinished(), and savingFinished().

bool AddressBook::removeResource Resource *    resource
 

Removes a resource from the address book.

Parameters:
resource  The resource you want to remove.
Returns:
Whether closing the resource was successfully.

Definition at line 718 of file addressbook.cpp.

References QObject::disconnect(), loadingFinished(), and savingFinished().

QPtrList< Resource > AddressBook::resources  
 

Returns a list of all resources.

Definition at line 742 of file addressbook.cpp.

References QPtrList::append().

void AddressBook::setErrorHandler ErrorHandler   errorHandler
 

Sets the ErrorHandler, that is used by error() to provide GUI independent error messages.

Parameters:
errorHandler  The error handler you want to use.

Definition at line 753 of file addressbook.cpp.

void AddressBook::error const QString   msg
 

Shows GUI independent error messages.

Parameters:
msg  The error message that shall be displayed.

Definition at line 759 of file addressbook.cpp.

Referenced by asyncLoad(), and load().

void AddressBook::cleanUp  
 

Deprecated:
There is no need to call this function anymore.

Definition at line 790 of file addressbook.cpp.

void AddressBook::dump   const
 

Used for debug output.

This function prints out the list of all addressees to kdDebug(5700).

Definition at line 617 of file addressbook.cpp.

References begin(), and end().

void KABC::AddressBook::addressBookChanged AddressBook *    addressBook [signal]
 

Emitted when one of the resources discovered a change in its backend or the asynchronous loading of all resources has finished.

You should connect to this signal to update the presentation of the contact data in your application.

Parameters:
addressBook  The address book which emitted this signal.

void KABC::AddressBook::addressBookLocked AddressBook *    addressBook [signal]
 

Emitted when one of the resources has been locked for writing.

Parameters:
addressBook  The address book which emitted this signal.

void KABC::AddressBook::addressBookUnlocked AddressBook *    addressBook [signal]
 

Emitted when one of the resources has been unlocked.

You should connect to this signal if you want to save your changes to a resource which is currently locked, and want to get notified when saving is possible again.

Parameters:
addressBook  The address book which emitted this signal.

void KABC::AddressBook::loadingFinished Resource *    resource [signal]
 

Emitted when the asynchronous loading of one resource has finished after calling asyncLoad().

Parameters:
resource  The resource which emitted this signal.

Referenced by addResource(), and removeResource().

void KABC::AddressBook::savingFinished Resource *    resource [signal]
 

Emitted when the asynchronous saving of one resource has finished after calling asyncSave().

Parameters:
resource  The resource which emitted this signal.

Referenced by addResource(), and removeResource().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kabc Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sun May 16 22:05:39 2004 by doxygen 1.2.15 written by Dimitri van Heesch, © 1997-2003