# class KabAPI | The class KabAPI defines the API to access user address databases. More...
Definition | `#include <kabapi.h>`
Inherits | KDialogBase (kdeui) [public ]
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Methods

- KabAPI (QWidget* parent=0, const char* name=0)
- AddressBook::ErrorCode init ()
- AddressBook* addressbook ()
- AddressBook::ErrorCode save (bool force=false)
- AddressBook::ErrorCode getEntry (AddressBook::Entry& entry, KabKey& key)
- AddressBook::ErrorCode getEntries (std::list<AddressBook::Entry>& entries)
- AddressBook::ErrorCode add (const AddressBook::Entry& entry, KabKey& key, bool update=true)
- AddressBook::ErrorCode remove (const KabKey& key)
- AddressBook::ErrorCode getEntryByName (const QString& name, std::list<AddressBook::Entry>& entries, const int max=5)
- AddressBook::ErrorCode getEntryByName (const AddressBook::Entry& pattern, std::list<AddressBook::Entry>& entries, const int max=5)
- int exec ()

#### Signals

- void setStatus (const QString&)

#### Protected Slots

- void entrySelected (int)
- void setStatusSlot (const QString&)

#### Protected Members

- AddressBook* book
- KListBox* listbox
- int selection

## Detailed Description

The class KabAPI provides a public interface to access the users address database created using kab. The complete functionality regarding database operations provided by kab is available using an object of this class.

The class is derived from the class KDialogBase, thus objects can be used as a KDE dialog where the user may select a person out of the entries in his personal database. The following code may be used to let the user select an address:

     KabAPI kabapi(this);
     if(dialog.init()!=KabAPI::NoError)
       {
         ... error handling
       }
     AddressBook::Entry entry;
     if(kabapi.exec())
       {
         if(!kabapi.getEntry(entry))
           {
             // ... the database is empty
           } else {
             // ... use the entry
           }
       }
     ...

Some methods declared here return keys of entries. The keys are of the datatype KabKey. Every key is (of course) unique and identifying. If you store it, you can access the entry it represents with it. Be careful that the entry may have been deleted by another program instance meanwhile! <tt>Please be careful to test for the return code NotImplemented as long the kab API is not completely finished.</tt>

See also: KDialogBase, KDialogBase

KabAPI (QWidget* parent=0, const char* name=0) | ### KabAPI

The constructor creates a KabAPI object, but it does not load the database itselfes, as you could not query if this could be done without failures. Thus you have to call init before you can use the database.

Parameters:

parent | The QWidget pointer to the parent widget.

AddressBook::ErrorCode init () | ### init

You must call init before accessing the database. init opens the database file (usually $HOME/.kde/share/apps/kab/addressbook.database) and loads its contents.

Returns: NoError if all succeeded or a valid ErrorCode.

See also: AddressBook::ErrorCode

AddressBook* addressbook () | ### addressbook

Get the addressbook object of this API. This is probably the most powerful method in the KabAPI since it allows you to access the database backend itselfes. If the API has not been initialized (using #init) before, zero is returned.

See also: init

AddressBook::ErrorCode save (bool force=false) | ### save

Save the database to the file. This method is used to force the database to save its contents. If force is true, the method will try to get writing permissions to the file if the database is opened readonly. After finishing saving, the r/o state is reset. This allows easier file sharing, since by default, all files are opened readonly aand closed after all read accesses.

AddressBook::ErrorCode getEntry (AddressBook::Entry& entry, KabKey& key) | ### getEntry

The method getEntry returns the selected entry.

Parameters:

entry | Reference to an AddressBook::Entry -object.
key | Reference to a KabKey where the key of the entry is stored.

Returns: NoError if all succeeded or a valid ErrorCode.

See also: AddressBook::ErrorCode

AddressBook::ErrorCode getEntries (std::list<AddressBook::Entry>& entries) | ### getEntries

Using the method getEntries, the caller will get a copy of all entries in the database. This might seem unneeded, but the address database can be used by multiple instances of the kab API at the same time, so that, if the programmer wants, for example, print a letter header for all persons, the database might change during the operation. That is why she can retrieve the whole database in one operation. It is required that the referenced list is empty. Note that the function returns NoEntry if the database is empty.

Parameters:

entries | Reference to a list of entries.

Returns: NoError or a valid error code.

See also: AddressBook::ErrorCode

AddressBook::ErrorCode add (const AddressBook::Entry& entry, KabKey& key, bool update=true) | ### add

The method requires that the database is not opened readonly.

Parameters:

entry | Reference to the entry to be added.
key | Reference to a KabKey where the key of the new entry is stored.
update | Whether to update the mirror map or not. Note: The functionality to edit an entry herein has been removed.

Returns: NoError if all succeeded or a valid ErrorCode, especially PermDenied.

AddressBook::ErrorCode remove (const KabKey& key) | ### remove

If the preferences of kab say to query before deleting, the user has to click "yes" on a message box that appeares. If called for a read only database, the method will return PermDenied.

Parameters:

key | The key of the entry to delete.

Returns: NoEntry if there is no entry with this key or another ErrorCode.

AddressBook::ErrorCode getEntryByName (const QString& name, std::list<AddressBook::Entry>& entries, const int max=5) | ### getEntryByName

Use getEntryByName to find entries that look like the name given. The name might be incomplete or diffuse.

Parameters:

name | The name, containing "." for abbreviations.
entries | Reference to a list of entries where matches are stored.
max | Maximum number of returned entries.

Returns: NoError if an entry is found or NoEntry.

AddressBook::ErrorCode getEntryByName (const AddressBook::Entry& pattern, std::list<AddressBook::Entry>& entries, const int max=5) | ### getEntryByName

This method also searches for close matches to the pattern, but it compares the whole entry given. This way you can search for, for example, nearly similar email addresses. Empty parts of the entry are not considered as criteria.

Parameters:

name | The name, containing "." for abbreviations.
entries | Reference to a list of entries where matches are stored.
max | Maximum number of returned entries.

Returns: NoError if an entry is found or NoEntry.

int exec () | ### exec

Execute this dialog. This overloads QDialog::exec to fill the list box before showing.

AddressBook* book | ### book

[protected]

KListBox* listbox | ### listbox

[protected]

int selection | ### selection

[protected]

void entrySelected (int) | ### entrySelected

[protected slots slot]

The index of the selected entry. This value is only valid after the KabAPI dialog has been executed and accepted by the user.

void setStatusSlot (const QString&) | ### setStatusSlot

[protected slots slot]

void setStatus (const QString&) | ### setStatus

[signal]

- Version: $Id: kabapi.h,v 1.13 2000/10/06 19:14:53 mirko Exp $
- Author: Mirko Sucker <mirko@kde.org>
- Generated: root@i386.ports.openbsd.org on Wed Apr 25 13:59:05 2001, using kdoc 2.0a53.