Compound list   Compound Members  

AddressBook::Entry Class Reference

Each entry in a loaded database has its own Entry object. More...

List of all members.

Public Members

Protected Members


Detailed Description

Each entry in a loaded database has its own Entry object.

The structure of the address database
As you might have read, kab uses the QConfigDB class to manage its data files. This class is intended to handle hierarchical structures. Thus, kab is able to create human readable but still deep and complex data files. This paragraph describes the overall structure of the files, the next two deal with special parts of it.
First of all, kab II data files (that usually end with .kab, while in kab 1 the fixed file name was addressbook.database) have two main sections (see the documentation of the QConfigDB and Section classes), one is called config, it contains different file specific configuration settings like the last displayed entry, and one section called entries that in turn contains a subsection for each entry in the database file. The keys of this subsections are the literal strings that are used in the KabKey class in the member KabKey::key. Each entry subsection has some key-value-pairs described below and another subsection "addresses" with one or more addresses in it. See the following example for a kab II data file (without any key-value-pairs):
  [config]
  [END]
  [entries]
     [1] (the first entry with literal key "1")
       [addresses]
         [1] (the first address, addresses are enumerated)
         [END]
         [2] (the second address)
         [END]
         ... (more addresses may follow)
       [END]
     [END]
     [2] (the second entry)
       [addresses]
         [1]
         [END]
       [END]
     [END]
     ... (more entries may follow)
  [END] 

The fields an entry contains
An entry contains all settings that are expected to be unique for all addresses directly as key-value-pairs. Everything that is part of a specific address of this person is part of an object of the member list addresses referenced in the next paragraph.
The keys defined directly in the entry sections are:
"title" The title of that person.
"rank" A possible military rank of that person.
"fn" The formatted name. If it is not empty, it replaces the standard combination of the other name fields in the address display.
"nameprefix" A possible name prefix.
"firstname" The first name.
"middlename" The middle name.
"lastname" The last name.
"birthday" The birthday (a QDate).
"comment" A free form comment.
"talk" The talk addresses (a string list).
"emails" The email addresses (a string list).
"keywords" A list of free-form keywords.
"telephone" A list of telephone numbers in a special format.
"URLs" A list of internet addresses.
"user_1" The first user-declared data field.
"user_2" The second user-declared data field.
"user_3" The third user-declared data field.
"user_4" The fourth user-declared data field.
See the next section for a description of the addresses subsections.

The fields of the addresses subsections
The section for each entry contains a subsection addresses with in turn a subsection for each address. The addresses are enumerated in the order they are inserted, their keys are the numbers of inserting converted to a string.
The keys defined in an address subsection are:
"headline" A headline shown for the address.
"position" The position of the person.
"org" The organisation.
"orgunit" The organisational unit.
"orgsubunit" The organisational subunit.
"role" The role of the person.
"deliverylabel" A label for delivering to this address.
"address" The street, house no., flat etc line.
"zip" A zip or postal code.
"town" The town the person lives in in this address.
"country" The country for federal states.
"state" The state for federal states.

The local configuration section
For each kab II database file there are some settings that apply only to the file itselfes, not to all kab databases the user works with. These settings are called the local configuration. The settings are stored in the config section of the local file. The following keys are declared in this section:
"user_1" The name of the first user-declared field.
"user_2" The name of the second user-declared field.
"user_3" The name of the third user-declared field.
"user_4" The name of the fourth user-declared field.
More fields will surely follow.


Member Function Documentation

ErrorCode AddressBook::Entry::getAddress(int index, Address& address)

Use this method to retrieve the address at the given index.

The method is provided for convenience. The address data is returned in address.

const QConfigDB* AddressBook::Entry::getFile()

Returns a pointer to the database.


Member Data Documentation

list<AddressBook::Entry::Address> AddressBook::Entry::addresses

Contains one or more Address objects.

QString AddressBook::Entry::title

The title of the person.

QString AddressBook::Entry::rank

The rank of the person.

QString AddressBook::Entry::fn

The formatted name of the person.

QString AddressBook::Entry::nameprefix

A possibly name prefix for that person.

QString AddressBook::Entry::firstname

The first name of the person.

QString AddressBook::Entry::middlename

The middle name of the person.

QString AddressBook::Entry::lastname

The last name of the person.

QDate AddressBook::Entry::birthday

The birthday of this person.

QString AddressBook::Entry::comment

The comment.

list<QString> AddressBook::Entry::talk

The talk addresses.

list<QString> AddressBook::Entry::emails

The email addresses.

list<QString> AddressBook::Entry::keywords

The user defined keywords for searching.

list<QString> AddressBook::Entry::telephone

Telephon numbers and types.

This list contains combinations of telephone numbers and the types of the phones, in this order. Types are (in literal strings) "mobil", "fix", "beeper", "answer machine", "fax", "dial in". Send your comments for more types, please!

list<QString> AddressBook::Entry::URLs

The home or related web pages of this person.

QString AddressBook::Entry::user1

The first user-declared field.

QString AddressBook::Entry::user2

The second user-declared field.

QString AddressBook::Entry::user3

The third user-declared field.

QString AddressBook::Entry::user4

The fourth user-declared field.

const QConfigDB* AddressBook::Entry::file [protected]

For internal use only.


The documentation for this class was generated from the following file:

The KDE Addressbook Developers Reference 
Mirko Sucker, 1999