GNUstep Readme#
Addresses.framework#
(c) 2003 Björn Giesler
This is a framework containing an implementation of Apple’s
AddressBook API. It’s not called AddressBook.framework to avoid
confusion and possible trademark issues and to be able to install it
on Apple systems alongside Apple’s implementation. The classes and
header files are called AD* instead of AB* to be able to use both
Addresses and Apple’s AddressBook frameworks in the same application
(e.g. to migrate between the two); there is, however, a compatibility
header file named AddressBook.h containing define statements that will
allow you to use the frameworks interchangeably. Additionally, the
installation process on GNUstep will create a link called
“AddressBook” to the Addresses header directory, so that you don’t have
to change any sourcecode that has the line
#include <AddressBook/AddressBook.h>
in it.
It is expandable to allow for different address storage locations (SQL databases, MS Exchange servers, etc.). The intent is to provide a framework which will handle anything from small personal address books to large corporate databases.
No Apple code has been used, copied or even looked at in connection with developing this framework; this includes any of the original AddressBook Framework headers or libraries. The API has been entirely reverse-engineered from Apple’s AddressBook Framework documentation.
License#
This framework is distributed under the LGPL; read the file COPYING.LIB for details.
Implementation Notes#
This section contains some notes (instead of a full documentation,
which I’m too lazy to write right now) about some implementation
details and extensions Addresses.framework has over Apple’s
AddressBook.framework. Few people using the framework in their
applications will probably need to read this section; but if you’re
extending the framework (for example, with converters or address book
classes), you’ll find this interesting.
Different Address Books Look As One#
This framework comes with two subclasses of the AddressBook class. The
first one, ADLocalAddressBook, accesses a user’s personal database
(located at ~/GNUstep/Library/Addresses). This database contains
contacts as property list files and groups as directories. It is clear
that this naive approach has its disadvantages, but it is easily
maintained with standard tools, even if the framework fails. For large
databases, storage in RDBMS can easily be implemented.
The second subclass, ADEnvelopeAddressBook, acts as an envelope for
other address books. [ADAddressBook sharedAddressBook] will return an
instance of this class. You can add other address books to this
instance; by default, it contains an instance of
ADLocalAddressBook. Addresses added to ADEnvelopeAddressBook will be
added to its primaryAddressBook (the local one, by default).
The idea behind this system is to be able to transparently connect to arbitrary address sources (LDAP, Apple’s address book, whatever). To add a new address book, just write a class, instantiate it and add it using
[[ADEnvelopeAddressBook sharedAddressBook] addAddressBook: myBook]
Handling Notifications#
Addresses uses three notifications that an application can observe to be notified of database changes:
ADRecordChangedNotification#
This is posted to the default notification center every time a
record is changed. Its userInfo member is a dictionary containing
the following:
Key |
Description |
|---|---|
|
the changed property |
|
the new value of the changed property |
ADDatabaseChangedNotification#
This is posted to the default notification center every time a record is changed. Its userInfo member is a dictionary containing the following:
Key |
Description |
|---|---|
|
the record’s address book |
|
the ID of the changed record |
|
the changed property |
|
the new value of the changed property |
ADDatabaseChangedExternallyNotification#
This is posted to the default distributed notification center
by a process saving a changed database. From there, it is caught
by all other processes’ shared ADAddressBook instances and
re-thrown to their default notification centers. Its object
member is a string specifying the ADAddressBook subclass that
changed the database, its userInfo a dictionary specifying that
class’s specifics (e.g. a filesystem path to the database).
Further Documentation#
Please see Apple’s AddressBook documentation for a complete reference on the original AddressBook.framework. It is located at http://developer.apple.com/ue/addressbook/