• Skip to content
  • Skip to link menu
KDE 4.1 API Reference
  • KDE API Reference
  • KDE-PIM Libraries
  • Sitemap
  • Contact Us
 

kabc

KABC::AddressBook

KABC::AddressBook Class Reference

Address Book. More...

#include <addressbook.h>

Inheritance diagram for KABC::AddressBook:

Inheritance graph
[legend]

List of all members.


Classes

class  ConstIterator
 Address Book Const Iterator. More...
class  Iterator
 Address Book Iterator. More...

Public Types

typedef ConstIterator const_iterator
typedef Iterator iterator

Signals

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

Public Member Functions

bool addCustomField (const QString &label, int category=Field::All, const QString &key=QString(), const QString &app=QString()) const
bool addResource (Resource *resource)
 AddressBook (const QString &config)
 AddressBook ()
Addressee::List allAddressees () const
QStringList allDistributionListNames () const
QList< DistributionList * > allDistributionLists ()
bool asyncLoad ()
bool asyncSave (Ticket *ticket)
Iterator begin ()
ConstIterator begin () const
void clear ()
DistributionList * createDistributionList (const QString &name, Resource *resource=0)
void dump () const
void emitAddressBookChanged ()
void emitAddressBookLocked ()
void emitAddressBookUnlocked ()
Iterator end ()
ConstIterator end () const
void error (const QString &msg)
Field::List fields (int category=Field::All) const
ConstIterator find (const Addressee &addr) const
Iterator find (const Addressee &addr)
Addressee::List findByCategory (const QString &category) const
Addressee::List findByEmail (const QString &email) const
Addressee::List findByName (const QString &name) const
Addressee findByUid (const QString &uid) const
DistributionList * findDistributionListByIdentifier (const QString &identifier)
DistributionList * findDistributionListByName (const QString &name, Qt::CaseSensitivity caseSensitivity=Qt::CaseSensitive)
virtual QString identifier () const
void insertAddressee (const Addressee &addr)
bool load ()
bool loadingHasFinished () const
void releaseSaveTicket (Ticket *ticket)
void removeAddressee (const Iterator &it)
void removeAddressee (const Addressee &addr)
void removeDistributionList (DistributionList *list)
bool removeResource (Resource *resource)
Ticket * requestSaveTicket (Resource *resource=0)
QList< Resource * > resources () const
bool save (Ticket *ticket)
void setErrorHandler (ErrorHandler *errorHandler)
virtual ~AddressBook ()

Protected Slots

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

Protected Member Functions

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

Friends

QDataStream & operator<< (QDataStream &lhs, const AddressBook &rhs)
QDataStream & operator>> (QDataStream &lhs, AddressBook &rhs)

Detailed Description

Address Book.

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

Definition at line 44 of file addressbook.h.


Member Typedef Documentation

typedef ConstIterator KABC::AddressBook::const_iterator

Typedef for STL style iterator.

Definition at line 274 of file addressbook.h.

typedef Iterator KABC::AddressBook::iterator

Typedef for STL style iterator.

Definition at line 269 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 305 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 315 of file addressbook.cpp.

AddressBook::~AddressBook (  )  [virtual]

Destructor.

Definition at line 330 of file addressbook.cpp.


Member Function Documentation

bool AddressBook::addCustomField ( const QString &  label,
int  category = Field::All,
const QString &  key = QString(),
const QString &  app = QString() 
) const

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 784 of file addressbook.cpp.

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 825 of file addressbook.cpp.

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.

Addressee::List AddressBook::allAddressees (  )  const

Returns a list of all addressees in the address book.

Definition at line 620 of file addressbook.cpp.

QStringList AddressBook::allDistributionListNames (  )  const

Returns a list of names of all distribution lists of all resources of this address book.

Convenience function, equal to iterate over the list returned by allDistributionLists()

Definition at line 725 of file addressbook.cpp.

QList< DistributionList * > AddressBook::allDistributionLists (  ) 

Returns a list of all distribution lists of all resources of this address book.

Definition at line 713 of file addressbook.cpp.

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 359 of file addressbook.cpp.

bool AddressBook::asyncSave ( Ticket *  ticket  ) 

Saves all addressees of one resource asynchronously.

If the save is successful the ticket is deleted.

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

Definition at line 393 of file addressbook.cpp.

AddressBook::Iterator AddressBook::begin (  ) 

This is an overloaded member function, provided for convenience.

It behaves essentially like the above function.

Definition at line 409 of file addressbook.cpp.

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 440 of file addressbook.cpp.

void AddressBook::clear (  ) 

Removes all addressees from the address book.

Definition at line 499 of file addressbook.cpp.

DistributionList * AddressBook::createDistributionList ( const QString &  name,
Resource *  resource = 0 
)

Creates a distribution list with a given name storing it in a given resource.

Note:
The newly created list will be added to the addressbook automatically on creation.
Parameters:
name The localized name of the new distribution list.
resource The resource which should save the list. If 0 (default) the addressbook's standard resource will be used.
See also:
standardResource()

Definition at line 668 of file addressbook.cpp.

void AddressBook::dump (  )  const

Used for debug output.

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

Definition at line 737 of file addressbook.cpp.

void KABC::AddressBook::emitAddressBookChanged (  )  [inline]

Emits the signal addressBookChanged() using this as the parameter.

Definition at line 590 of file addressbook.h.

void KABC::AddressBook::emitAddressBookLocked (  )  [inline]

Emits the signal addressBookLocked() using this as the parameter.

Definition at line 582 of file addressbook.h.

void KABC::AddressBook::emitAddressBookUnlocked (  )  [inline]

Emits the signal addressBookUnlocked() using this as the parameter.

Definition at line 586 of file addressbook.h.

AddressBook::Iterator AddressBook::end (  ) 

This is an overloaded member function, provided for convenience.

It behaves essentially like the above function.

Definition at line 471 of file addressbook.cpp.

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 485 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 895 of file addressbook.cpp.

Field::List AddressBook::fields ( int  category = Field::All  )  const

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

Definition at line 763 of file addressbook.cpp.

AddressBook::ConstIterator AddressBook::find ( const Addressee &  addr  )  const

Returns an iterator pointing to the specified addressee.

It will return end() if no addressee matched.

Parameters:
addr The addressee you are looking for.

Definition at line 595 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 addressee you are looking for.

Definition at line 583 of file addressbook.cpp.

Addressee::List AddressBook::findByCategory ( const QString &  category  )  const

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 656 of file addressbook.cpp.

Addressee::List AddressBook::findByEmail ( const QString &  email  )  const

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 644 of file addressbook.cpp.

Addressee::List AddressBook::findByName ( const QString &  name  )  const

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 632 of file addressbook.cpp.

Addressee AddressBook::findByUid ( const QString &  uid  )  const

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 607 of file addressbook.cpp.

DistributionList * AddressBook::findDistributionListByIdentifier ( const QString &  identifier  ) 

Returns a distribution list for the given identifier or 0.

Parameters:
identifier The ID of the list for look for.

Definition at line 686 of file addressbook.cpp.

DistributionList * AddressBook::findDistributionListByName ( const QString &  name,
Qt::CaseSensitivity  caseSensitivity = Qt::CaseSensitive 
)

Returns a distribution list with the given name or 0.

Parameters:
name The localized name of the list for look for.
caseSensitivity Whether to do string matching case sensitive or case insensitive. Default is Qt::CaseSensitive

Definition at line 699 of file addressbook.cpp.

QString AddressBook::identifier (  )  const [virtual]

Returns a string identifying this addressbook.

The identifier is created by concatenation of the resource identifiers.

Definition at line 749 of file addressbook.cpp.

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 540 of file addressbook.cpp.

bool AddressBook::load (  ) 

Loads all addressees synchronously.

Returns:
Whether the loading was successfully.

Definition at line 341 of file addressbook.cpp.

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.

bool AddressBook::loadingHasFinished (  )  const

Returns true when the loading of the addressbook has finished, otherwise false.

Definition at line 924 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.

Parameters:
ticket the save ticket acquired with requestSaveTicket()

Definition at line 529 of file addressbook.cpp.

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 576 of file addressbook.cpp.

void AddressBook::removeAddressee ( const Addressee &  addr  ) 

Removes an addressee from the address book.

Parameters:
addr The addressee which shall be removed.

Definition at line 569 of file addressbook.cpp.

void AddressBook::removeDistributionList ( DistributionList *  list  ) 

Removes a distribution list from its associated resource.

Parameters:
list The list to remove.

Definition at line 677 of file addressbook.cpp.

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 848 of file addressbook.cpp.

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 507 of file addressbook.cpp.

void AddressBook::resourceLoadingError ( Resource *  resource,
const QString &  errMsg 
) [protected, slot]

Handles loading errors.

Resource will be removed from the list of those pending for loading. If this has been the last one in this list, signal addressBookChanged() is emitted.

Parameters:
resource The resource which could not be loaded.
errMsg The message describing the error. See error()

Definition at line 946 of file addressbook.cpp.

void AddressBook::resourceLoadingFinished ( Resource *  resource  )  [protected, slot]

Handles loading success.

Resource will be removed from the list of those pending for loading and signal loadingFinished() will be emitted. It this has been the last one in this list, signal addressBookChanged() is emitted as well.

Parameters:
resource The resource which has been saved successfully.

Definition at line 929 of file addressbook.cpp.

KRES::Manager< Resource > * AddressBook::resourceManager (  )  [protected]

Returns the addressbook's resource manager.

Definition at line 919 of file addressbook.cpp.

QList< Resource * > AddressBook::resources (  )  const

Returns a list of all resources.

Definition at line 873 of file addressbook.cpp.

void AddressBook::resourceSavingError ( Resource *  resource,
const QString &  errMsg 
) [protected, slot]

Handles saving errors.

Resource will be removed from the list of those pending for saving.

Parameters:
resource The resource which could not be saved.
errMsg The message describing the error. See error()

Definition at line 957 of file addressbook.cpp.

void AddressBook::resourceSavingFinished ( Resource *  resource  )  [protected, slot]

Handles saving success.

Resource will be removed from the list of those pending for saving.

Parameters:
resource The resource which has been saved successfully.

Definition at line 939 of file addressbook.cpp.

bool AddressBook::save ( Ticket *  ticket  ) 

Saves all addressees of one resource synchronously.

If the save is successful the ticket is deleted.

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

Definition at line 378 of file addressbook.cpp.

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.

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 889 of file addressbook.cpp.

void AddressBook::setStandardResource ( Resource *  resource  )  [protected]

Sets the resource manager's standard resource.

Convenience method for resourceManager()->setStandardResource()

Parameters:
resource The resource to use as the standard
See also:
standardResource()

Definition at line 909 of file addressbook.cpp.

Resource * AddressBook::standardResource (  )  [protected]

Returns the addressbook resource manager's standard resource.

Convenience method for resourceManager()->standardResource()

See also:
setStandardResource()

Definition at line 914 of file addressbook.cpp.


The documentation for this class was generated from the following files:
  • addressbook.h
  • addressbook.cpp

kabc

Skip menu "kabc"
  • Main Page
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

KDE-PIM Libraries

Skip menu "KDE-PIM Libraries"
  • akonadi
  • kabc
  • kblog
  • kcal
  • kimap
  • kioslave
  •   imap4
  •   mbox
  • kldap
  • kmime
  • kpimidentities
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Generated for KDE-PIM Libraries by doxygen 1.5.7.1
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal