class AddressBookInterface
{
  K_DCOP

  public:
    AddressBookInterface();
    ~AddressBookInterface();

    enum LockType {
      NoLock,
      ReadLock,
      WriteLock,
      ReadWriteLock
    };

  k_dcop:
    /**
      Address Book Management

      The following functions allow you to manage address books ( create, edit, delete ).
     */

    /**
      Returns the identifiers of all available address book types.
     */
    QStringList addressBookTypes() const;

    /**
      Returns the i18n'ed name for a given address book type.
     */
    QString addressBookTypeName( const QString &type ) const;

    /**
      Returns the i18n'ed description for a given address book type.
     */
    QString addressBookTypeDescription( const QString &type ) const;

    /**
      Returns the icon assocciated with the given address book type.
     */
    QPixmap addressBookTypeIcon( const QString &type ) const;

    /**
      Returns the unique identifiers of all available address books.
     */
    QStringList addressBooks() const;

    /**
      Returns the name for a given address book identifier.
     */
    QString addressBookName( const QString &identifier ) const;

    /**
      Returns the type for a given address book identifier.
     */
    QString addressBookType( const QString &identifier ) const;

    /**
      Creates a new address book with the given @param type and the given @param name.

      The @param configuration is an address book type specific xml string which is
      used as default configuration by the new address book.
      If @showConfigDialog is true, a configuration dialog is shown where the user
      can configure the address book manually.

      @returns The unique identifier for the new address book or an empty string
              if the creation was canceled.
     */
    QString createAddressBook( const QString &name, const QString &type, const QString &configuration,
                               bool showConfigDialog = true );

    /**
      Changes the address book with the given unique @param identifier.
      @param configuration The new configuration of this address book.
      @param showConfigDialog If true a configuration dialog is shown where the user
             can configure the address book manually.
     */
    void changeAddressBook( const QString &identifier, const QString &configuration,
                            bool showConfigDialog = true );

    /**
      Deletes the address book with the given unique @param identifier.
     */
    void deleteAddressBook( const QString &identifier );

    /**
      Returns the current lock status of the address book with the given address book @param identifier.
     */
    LockType addressBookLock( const QString &identifier ) const;

    /**
      Sets a lock status for the address book with the given address book @param identifier.
     */
    void addressBookSetLock( const QString &identifier, LockType lockType );

    /**
      Returns whether the address book with the given unique @param identifier
      is active.
     */
    bool addressBookActive( const QString &identifier ) const;

    /**
      Sets the address book with the given identifier active or passive.
     */
    void addressBookSetActive( const QString &identifier, bool active );

    /**
      Contact Management

      The following functions allow you to manage contacts ( create, change, delete ).
     */

    /**
      Adds a new contact to the given address book.
      @param identifier The address book identifier of the address book where the contact shall be added.
      @param vCard contains the contact in vCard 3.0 format.
     */
    void createContact( const QString &identifier, const QString &vCard );

    /**
      Adds a list of new contacts to the given address book.
      @param identifier The address book identifier of the address book where the contacts shall be added.
      @param vCards contains the contacts in vCard 3.0 format.
     */
    void createContacts( const QString &identifier, const QStringList &vCards );

    /**
      Changes the contact with given unique @param identifier.
      @param vCard contains the contact in vCard 3.0 format.
     */
    void changeContact( const QString &identifier, const QString &vCard );

    /**
      Removes the contact with the given unique @param identifier from the address book.
     */
    void deleteContact( const QString &identifier );

    /**
      Removes the contacts with the given unique @param identifiers from the address book.
     */
    void deleteContacts( const QStringList &identifiers );

    /**
      Returns the contact in vCard 3.0 format for the given unique @param identifier.
     */
    QString contact( const QString &identifier );

    /**
      Returns the contacts in vCard 3.0 format for the given unique @param identifiers.
     */
    QStringList contacts( const QStringList &identifiers );

    /**
      Category Management

      The following functions allow you to manage the address book categories.
     */

    /**
      Returns all categories provided by the address book with the given @param identifier.
     */
    QStringList categories( const QString &identifier );

    /**
      Creates a new category for the address book with the given @param identifier.
     */
    void createCategory( const QString &identifier, const QString &category );

    /**
      Deletes the @param category from the address book with the given @param identifier.
     */
    void deleteCategory( const QString &identifier, const QString &category );

    /**
      Custom Fields Management

      The following functions allow you to manage the custom fields.
     */

    /**
      Creates a new custom field.

      @param key The key of this custom field.
      @param label The i18n'ed label for this custom field.
     */
    void createCustomField( const QString &key, const QString &label );

    /**
      Deletes the custom field with the given @param key.
     */
    void deleteCustomField( const QString &key );

    /**
      Returns the list of keys from all custom fields.
     */
    QStringList customFields() const;

    /**
      Returns the label of the custom field with the given @param key.
     */
    QString customFieldLabel( const QString &key ) const;

  k_dcop_signals:
    void addressBookCreated( const QString &identifier );
    void addressBookChanged( const QString &identifier );
    void addressBookDeleted( const QString &identifier );
    void addressBookLocked( const QString &identifier, bool locked );
    void addressBookActivated( const QString &identifier, bool activated );

    void contactCreated( const QString &addressBookIdentifier, const QString &identifier );
    void contactChanged( const QString &addressBookIdentifier, const QString &identifier );
    void contactDeleted( const QString &addressBookIdentifier, const QString &identifier );

    void categoryCreated( const QString &addressBookIdentifier, const QString &category );
    void categoryDeleted( const QString &addressBookIdentifier, const QString &category );

    void customFieldCreated( const QString &key );
    void customFieldDeleted( const QString &key );
};