AddressBookSource Class Reference

#include <AddressBookSource.h>

Inheritance diagram for AddressBookSource:

Collaboration diagram for AddressBookSource:

List of all members.

Public Member Functions

AddressBookSource (const EvolutionSyncSourceParams &params, bool asVCard30)

virtual ~AddressBookSource ()

void setVCard30 (bool asVCard30)

bool getVCard30 ()

virtual Databases getDatabases ()

virtual void open ()

virtual void listAllItems (RevisionMap_t &revisions)

virtual void exportData (ostream &out)

virtual InsertItemResult insertItem (const string &uid, const SyncItem &item)

virtual SyncItem * createItem (const string &uid)

virtual SyncItem * createItem (const string &uid, bool asVCard30)

virtual void deleteItem (const string &uid)

virtual void flush ()

virtual void close ()

virtual string fileSuffix () const

virtual const char * getMimeType () const

virtual const char * getMimeVersion () const

virtual const char * getSupportedTypes () const

Protected Member Functions

virtual void logItem (const string &uid, const string &info, bool debug=false)

virtual void logItem (const SyncItem &item, const string &info, bool debug=false)

Detailed Description

The AddressBookSource synchronizes the Mac OS X and iPhone system address book using the "AddressBook" framework. Changes are tracked by comparing the current time stamp of a contact against its time stamp from the previous sync, stored in a separate key/value database. Contacts are converted to/from vCard 2.1 using custom code because a) the mapping can be chosen so that typical SyncML servers understand it and b) the iPhone's AddressBook does not have vcard import/export functions.

On the iPhone the interface is similar, but not the same. These differences are hidden behind "ifdef IPHONE" which depends (for simplicity reasons) on the __arm__ define.

Some of the differences and how they are handled are listed here.

ABC instead of AB prefix, other renames: map Mac OS X name to iPhone name before including AddressBook.h, then use Mac OS X names
CFRelease() and CFCopyDescription on ABMultiValueRef crash (bugs?!): use ref<T, IPHONE_RELEASE> for those instead the normal ref smart pointer, avoid CFCopyDescription()
UID is integer, not CFStringRef: added wrapper function
the address of kABC*Property identifies properties, not the CFStringRef at that address, caused toolchain problems when initializing data with these addresses: added one additional address indirection
UIDs are assigned to added contacts only during saving, but are needed earlier: save after adding each contact (affects performance and aborted sync changes address book - perhaps better guess UID?)
Mac OS X 10.4 still uses the kABHomePageProperty (a single string), the iPhone switched to the more recent kABCURLProperty/kABURLsProperty: conversion code is slightly different
iPhone does not have a title (e.g. "sir") property, only the job title
label constants are not part of the framework: defined in AddressSourceConstants

Definition at line 156 of file AddressBookSource.h.

Constructor & Destructor Documentation

AddressBookSource::AddressBookSource	(	const EvolutionSyncSourceParams &	params,
		bool	asVCard30
	)

Definition at line 1190 of file AddressBookSource.cpp.

virtual AddressBookSource::~AddressBookSource ( ) [inline, virtual]

Definition at line 160 of file AddressBookSource.h.

References close().

Member Function Documentation

void AddressBookSource::close ( ) [virtual]

closes the data source so that it can be reopened

Just as open() it should not affect the state of the database unless some previous action requires it.

Implements TrackingSyncSource.

Definition at line 1225 of file AddressBookSource.cpp.

References EvolutionSyncSource::hasFailed(), and EvolutionSyncSource::throwError().

Referenced by ~AddressBookSource().

SyncItem * AddressBookSource::createItem	(	const string &	uid,
		bool	asVCard30
	)			`[virtual]`

Definition at line 1260 of file AddressBookSource.cpp.

References vCard2ABPerson::fromPerson(), getMimeType(), logItem(), and EvolutionSyncSource::throwError().

virtual SyncItem* AddressBookSource::createItem ( const string & uid ) [inline, virtual]

Extract information for the item identified by UID and store it in a new SyncItem. The caller must free that item. May throw exceptions.

Parameters:

uid

identifies the item

Implements TrackingSyncSource.

Definition at line 170 of file AddressBookSource.h.

References createItem().

Referenced by createItem(), and exportData().

void AddressBookSource::deleteItem ( const string & uid ) [virtual]

removes and item

Implements TrackingSyncSource.

Definition at line 1355 of file AddressBookSource.cpp.

References EvolutionSyncSource::getName(), and EvolutionSyncSource::throwError().

Referenced by insertItem().

void AddressBookSource::exportData ( ostream & out ) [virtual]

exports all items one after the other, separated by blank line; if that format is not suitable, then the derived class must override this call

Reimplemented from TrackingSyncSource.

Definition at line 1245 of file AddressBookSource.cpp.

References createItem().

virtual string AddressBookSource::fileSuffix ( ) const [inline, virtual]

file suffix for database files

Implements TrackingSyncSource.

Definition at line 176 of file AddressBookSource.h.

virtual void AddressBookSource::flush ( ) [inline, virtual]

optional: write all changes, throw error if that fails

This is called while the sync is still active whereas close() is called afterwards. Reporting problems as early as possible may be useful at some point, but currently doesn't make a relevant difference.

Reimplemented from TrackingSyncSource.

Definition at line 173 of file AddressBookSource.h.

EvolutionSyncSource::Databases AddressBookSource::getDatabases ( ) [virtual]

returns a list of all know sources for the kind of items supported by this sync source

Implements TrackingSyncSource.

Definition at line 1197 of file AddressBookSource.cpp.

virtual const char* AddressBookSource::getMimeType ( ) const [inline, virtual]

Returns the preferred mime type of the items handled by the sync source. Example: "text/x-vcard"

Implements TrackingSyncSource.

Definition at line 177 of file AddressBookSource.h.

Referenced by createItem().

virtual const char* AddressBookSource::getMimeVersion ( ) const [inline, virtual]

Returns the version of the mime type used by client. Example: "2.1"

Implements TrackingSyncSource.

Definition at line 178 of file AddressBookSource.h.

virtual const char* AddressBookSource::getSupportedTypes ( ) const [inline, virtual]

A string representing the source types (with versions) supported by the SyncSource. The string must be formatted as a sequence of "type:version" separated by commas ','. For example: "text/x-vcard:2.1,text/vcard:3.0". The version can be left empty, for example: "text/x-s4j-sifc:". Supported types will be sent as part of the DevInf.

Implements TrackingSyncSource.

Definition at line 179 of file AddressBookSource.h.

bool AddressBookSource::getVCard30 ( ) [inline]

Definition at line 163 of file AddressBookSource.h.

AddressBookSource::InsertItemResult AddressBookSource::insertItem	(	const string &	uid,
		const SyncItem &	item
	)			`[virtual]`

Create or modify an item.

The sync source should be flexible: if the UID is non-empty, it shall modify the item referenced by the UID. If the UID is empty, the normal operation is to add it. But if the item already exists (e.g., a calendar event which was imported by the user manually), then the existing item should be updated also in the second case.

Passing a UID of an item which does not exist is an error. This error should be reported instead of covering it up by (re)creating the item.

Errors are signalled by throwing an exception. Returning empty strings in the result is an error which triggers an "item could not be stored" error.

Parameters:

	uid	identifies the item to be modified, empty for creating
	item	contains the new content of the item and its MIME type

Returns:: the result of inserting the item

Implements TrackingSyncSource.

Definition at line 1289 of file AddressBookSource.cpp.

References deleteItem(), PersonCreateWrapper, ref< T, doRelease >::set(), EvolutionSyncSource::throwError(), and vCard2ABPerson::toPerson().

void AddressBookSource::listAllItems ( RevisionMap_t & revisions ) [virtual]

Definition at line 1213 of file AddressBookSource.cpp.

void AddressBookSource::logItem	(	const SyncItem &	item,
		const string &	info,
		bool	debug = `false`
	)			`[protected, virtual]`

Implements TrackingSyncSource.

Definition at line 1407 of file AddressBookSource.cpp.

References EvolutionSyncSource::getName().

void AddressBookSource::logItem	(	const string &	uid,
		const string &	info,
		bool	debug = `false`
	)			`[protected, virtual]`

log a one-line info about an item

Implements TrackingSyncSource.

Definition at line 1370 of file AddressBookSource.cpp.

References EvolutionSyncSource::getName().

Referenced by createItem().

void AddressBookSource::open ( ) [virtual]

Actually opens the data source specified in the constructor, will throw the normal exceptions if that fails. Should not modify the state of the sync source: that can be deferred until the server is also ready and beginSync() is called.

Implements TrackingSyncSource.

Definition at line 1205 of file AddressBookSource.cpp.

References EvolutionSyncSource::throwError().

void AddressBookSource::setVCard30 ( bool asVCard30 ) [inline]

Definition at line 162 of file AddressBookSource.h.

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

src/backends/addressbook/AddressBookSource.h
src/backends/addressbook/AddressBookSource.cpp


Public Member Functions
	AddressBookSource (const EvolutionSyncSourceParams &params, bool asVCard30)
virtual	~AddressBookSource ()
void	setVCard30 (bool asVCard30)
bool	getVCard30 ()
virtual Databases	getDatabases ()
virtual void	open ()
virtual void	listAllItems (RevisionMap_t &revisions)
virtual void	exportData (ostream &out)
virtual InsertItemResult	insertItem (const string &uid, const SyncItem &item)
virtual SyncItem *	createItem (const string &uid)
virtual SyncItem *	createItem (const string &uid, bool asVCard30)
virtual void	deleteItem (const string &uid)
virtual void	flush ()
virtual void	close ()
virtual string	fileSuffix () const
virtual const char *	getMimeType () const
virtual const char *	getMimeVersion () const
virtual const char *	getSupportedTypes () const
Protected Member Functions
virtual void	logItem (const string &uid, const string &info, bool debug=false)
virtual void	logItem (const SyncItem &item, const string &info, bool debug=false)