KabAPI Class Reference

[kab Index] [kab Hierarchy] [Headers]


The class KabAPI defines the API to access user address databases. More...

#include <kabapi.h>

Inherits: QDialog (qt)

Public Members

Public Slots

Protected Members


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 QDialog, thus objects can be used as a dialog where the user may select an address similar to the interface of kab. 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. This keys are of the datatype string declared in the (by now) standard C++ library. 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! Please note that the kab code assumes that a QImage-IO-handler for jpeg pictures has been installed. You will get a message that the background image could not been loaded if you forget it. See kab/main.cc and kab/kabapi_test.cc for examples.
Please be careful to test for the return code NotImplemented as long the kab API is not completely finished (it is not).

See Also: KabAPI::AddressBook


enum ErrorCode ( NoError, NotImplemented, PermDenied, NoSuchFile, NoEntry, Rejected, InternError ) [public]

ErrorCode is used in all methods that may return more status codes than true or false.
NoError The operations has been finished successful.
NotImplemented The feature you requested is not implemented by KabAPI.
PermDenied Not all permissions needed for the operation were available. Also returned if a database is locked.
NoSuchFile No database file exists for this user.
NoEntry You tried to retrieve an entry but there is none.
InternError There was a program error.

KabAPI(QWidget* parent=0) [public]

The constructor creates a KabAPI object, but it does not load thedatabase 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.

ErrorCode init(bool readonly=true) [public]

You must call init before accessing the dialog. init opens thedatabase file (usually $HOME/.kde/share/apps/kab/addressbook.database) and loads its contents. If the database is already opened by another instance of kab and readonly is NOT true, init returns PermDenied. You may try to open a database for reading and writing first, and if it fails with PermDenied try again to open it readonly. The dialog will not provide the capabilities to store the database or to edit an entry then.

Returns:
NoError if all succeeded or a valid ErrorCode.
See Also:
ErrorCode

ErrorCode getEntry(AddressBook::Entry& entry, string& key) [public]

The method getEntry returns the selected entry.

Parameters:
key Reference to a string where the key of the entry is stored.
entry Reference to an AddressBook::Entry -object.
Returns:
NoError if all succeeded or a valid ErrorCode.
See Also:
ErrorCode

ErrorCode getEntries(list<AddressBook::Entry>& entries) [public]

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:
ErrorCode

ErrorCode add(const AddressBook::Entry& entry, string& key, bool edit=true) [public]

The method requires that the database is not opened readonly.A dialog will show up that allows the users to edit the entry before it is inserted into the database. If you do not want to open the dialog set edit to false.

Parameters:
key Reference to a string where the key of the new entry is stored.
entry Reference to the entry to be added.
edit If true, the edit dialog is shown.
Returns:
NoError if all succeeded or a valid ErrorCode, especially PermDenied.

ErrorCode edit(AddressBook::Entry& entry) [public]

This method can be used to edit an Entry object used by your program.The "entry" does not need to be in the database and is NOT added to it. Shortly, the database is not changed. Thus, you may call this method even if your database object is read only.

Parameters:
entry The entry to be edited.
Returns:
NoError if the user accepted the dialog or Rejected if she rejected it.

ErrorCode edit(const string& key) [public]

In difference to the other edit method, this one will edit an entry in the database. A dialog will pop up where the user can edit it, if the dialog is finished with "OK", the entry will be changed. If called for a read only database, the method will return PermDenied.

Parameters:
key The key of the entry to be edited.
Returns:
Rejected if the user cancelled the dialog, NoError if the entry has been changed or another ErrorCode.

ErrorCode remove(const string& key) [public]

If the preferences of kab say to query before deleting, the user hasto 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.

ErrorCode getEntryByName(const string& name, list<AddressBook::Entry>& entries, const int max=5) [public]

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.

ErrorCode getEntryByName(const AddressBook.html">AddressBook::Entry& pattern, list<AddressBook.html">AddressBook::Entry>& entries, const int max=5) [public]

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.

ErrorCode sendEmail(const string& address, const string& subject="") [public]

This method uses kab's configuration to call the (KDE ?) mailer orwhatever is configured to send an email in kab.


  • Author: Mirko Sucker <mirko.sucker@unibw-hamburg.de>
  • Version: $Id: kabapi.h,v 1.4 1999/01/21 19:39:12 pbrown Exp $
  • Documentation generated by root@darkstar.lst.de on Wed Sep 8 17:39:05 CEST 1999
Kdoc