| -rw-r--r-- | libopie2/opiepim/backend/obackendfactory.h | 26 | ||||
| -rw-r--r-- | libopie2/opiepim/backend/ocontactaccessbackend.h | 32 | ||||
| -rw-r--r-- | libopie2/opiepim/backend/ocontactaccessbackend_vcard.cpp | 7 | ||||
| -rw-r--r-- | libopie2/opiepim/backend/ocontactaccessbackend_vcard.h | 18 | ||||
| -rw-r--r-- | libopie2/opiepim/backend/ocontactaccessbackend_xml.cpp | 171 | ||||
| -rw-r--r-- | libopie2/opiepim/backend/ocontactaccessbackend_xml.h | 46 | ||||
| -rw-r--r-- | libopie2/opiepim/backend/odatebookaccessbackend.h | 45 | ||||
| -rw-r--r-- | libopie2/opiepim/backend/odatebookaccessbackend_xml.h | 6 | ||||
| -rw-r--r-- | libopie2/opiepim/core/ocontactaccess.h | 16 | ||||
| -rw-r--r-- | libopie2/opiepim/core/odatebookaccess.cpp | 28 | ||||
| -rw-r--r-- | libopie2/opiepim/core/odatebookaccess.h | 15 | ||||
| -rw-r--r-- | libopie2/opiepim/ocontact.h | 11 | ||||
| -rw-r--r-- | libopie2/opiepim/oevent.h | 17 |
13 files changed, 315 insertions, 123 deletions
diff --git a/libopie2/opiepim/backend/obackendfactory.h b/libopie2/opiepim/backend/obackendfactory.h index 3a73210..ad6cf5a 100644 --- a/libopie2/opiepim/backend/obackendfactory.h +++ b/libopie2/opiepim/backend/obackendfactory.h @@ -13,12 +13,17 @@ * ToDo: Use plugins * ===================================================================== * Version: $Id$ * ===================================================================== * History: * $Log$ + * Revision 1.6 2003/04/13 18:07:10 zecke + * More API doc + * QString -> const QString& + * QString = 0l -> QString::null + * * Revision 1.5 2003/02/21 23:31:52 zecke * Add XML datebookresource * -clean up todoaccessxml header * -implement some more stuff in the oeven tester * -extend DefaultFactory to not crash and to use datebook * @@ -60,25 +65,44 @@ #include "odatebookaccessbackend_xml.h" #ifdef __USE_SQL #include "otodoaccesssql.h" #endif - +/** + * This class is our factory. It will give us the default implementations + * of at least Todolist, Contacts and Datebook. In the future this class will + * allow users to switch the backend with ( XML->SQLite ) without the need + * to recompile.# + * This class as the whole PIM Api is making use of templates + * + * <pre> + * OTodoAccessBackend* backend = OBackEndFactory<OTodoAccessBackend>::Default("todo", QString::null ); + * backend->load(); + * </pre> + * + * @author Stefan Eilers + * @version 0.1 + */ template<class T> class OBackendFactory { public: OBackendFactory() {}; enum BACKENDS { TODO, CONTACT, DATE }; + /** + * Returns a backend implementation for backendName + * @param backendName the type of the backend + * @param appName will be passed on to the backend + */ static T* Default( const QString backendName, const QString& appName ){ // __asm__("int3"); Config config( "pimaccess" ); config.setGroup ( backendName ); diff --git a/libopie2/opiepim/backend/ocontactaccessbackend.h b/libopie2/opiepim/backend/ocontactaccessbackend.h index 821f5bf..ebeb42d 100644 --- a/libopie2/opiepim/backend/ocontactaccessbackend.h +++ b/libopie2/opiepim/backend/ocontactaccessbackend.h @@ -16,12 +16,17 @@ * ToDo: Define enum for query settings * ===================================================================== * Version: $Id$ * ===================================================================== * History: * $Log$ + * Revision 1.5 2003/04/13 18:07:10 zecke + * More API doc + * QString -> const QString& + * QString = 0l -> QString::null + * * Revision 1.4 2002/11/13 14:14:51 eilers * Added sorted for Contacts.. * * Revision 1.3 2002/11/01 15:10:42 eilers * Added regExp-search in database for all fields in a contact. * @@ -41,21 +46,32 @@ #ifndef _OCONTACTACCESSBACKEND_H_ #define _OCONTACTACCESSBACKEND_H_ #include "ocontact.h" #include "opimaccessbackend.h" -#include "qregexp.h" +#include <qregexp.h> +/** + * This class represents the interface of all Contact Backends. + * Derivates of this class will be used to access the contacts. + * As implementation currently XML and vCard exist. This class needs to be implemented + * if you want to provide your own storage. + * In all queries a list of uids is passed on instead of loading the actual record! + * + * @see OContactAccessBackend_VCard + * @see OContactAccessBackend_XML + */ class OContactAccessBackend: public OPimAccessBackend<OContact> { public: OContactAccessBackend() {} virtual ~OContactAccessBackend() {} - /** Return if database was changed externally. + /** + * Return if database was changed externally. * This may just make sense on file based databases like a XML-File. * It is used to prevent to overwrite the current database content * if the file was already changed by something else ! * If this happens, we have to reload before save our data. * If we use real databases, this should be handled by the database * management system themselve, therefore this function should always return false in @@ -65,21 +81,27 @@ class OContactAccessBackend: public OPimAccessBackend<OContact> { * in this situation. */ virtual bool wasChangedExternally() = 0; virtual QArray<int> matchRegexp( const QRegExp &r ) const = 0; - /** Return all possible settings. + /** + * Return all possible settings. * @return All settings provided by the current backend * (i.e.: query_WildCards & query_IgnoreCase) */ virtual const uint querySettings() = 0; - /** Check whether settings are correct. + /** + * Check whether settings are correct. * @return <i>true</i> if the given settings are correct and possible. */ virtual bool hasQuerySettings (uint querySettings) const = 0; - virtual QArray<int> sorted( bool ascending, int sortOrder, int sortFilter, int cat ) = 0; + /** + * FIXME!!! + * Returns a sorted list of records either ascendinf or descending for a giving criteria and category + */ + virtual QArray<int> sorted( bool ascending, int sortOrder, int sortFilter, int cat ) = 0; }; #endif diff --git a/libopie2/opiepim/backend/ocontactaccessbackend_vcard.cpp b/libopie2/opiepim/backend/ocontactaccessbackend_vcard.cpp index f24523f..270bef3 100644 --- a/libopie2/opiepim/backend/ocontactaccessbackend_vcard.cpp +++ b/libopie2/opiepim/backend/ocontactaccessbackend_vcard.cpp @@ -14,12 +14,17 @@ * * ===================================================================== * Version: $Id$ * ===================================================================== * History: * $Log$ + * Revision 1.10 2003/04/13 18:07:10 zecke + * More API doc + * QString -> const QString& + * QString = 0l -> QString::null + * * Revision 1.9 2003/03/21 10:33:09 eilers * Merged speed optimized xml backend for contacts to main. * Added QDateTime to querybyexample. For instance, it is now possible to get * all Birthdays/Anniversaries between two dates. This should be used * to show all birthdays in the datebook.. * This change is sourcecode backward compatible but you have to upgrade @@ -73,13 +78,13 @@ #include "../../library/backend/qfiledirect_p.h" #include <qpe/timeconversion.h> #include <qfile.h> -OContactAccessBackend_VCard::OContactAccessBackend_VCard ( QString , QString filename ): +OContactAccessBackend_VCard::OContactAccessBackend_VCard ( const QString& , const QString& filename ): m_dirty( false ), m_file( filename ) { load(); } diff --git a/libopie2/opiepim/backend/ocontactaccessbackend_vcard.h b/libopie2/opiepim/backend/ocontactaccessbackend_vcard.h index 93e2da3..712d769 100644 --- a/libopie2/opiepim/backend/ocontactaccessbackend_vcard.h +++ b/libopie2/opiepim/backend/ocontactaccessbackend_vcard.h @@ -14,12 +14,17 @@ * * ===================================================================== * Version: $Id$ * ===================================================================== * History: * $Log$ + * Revision 1.6 2003/04/13 18:07:10 zecke + * More API doc + * QString -> const QString& + * QString = 0l -> QString::null + * * Revision 1.5 2003/03/21 10:33:09 eilers * Merged speed optimized xml backend for contacts to main. * Added QDateTime to querybyexample. For instance, it is now possible to get * all Birthdays/Anniversaries between two dates. This should be used * to show all birthdays in the datebook.. * This change is sourcecode backward compatible but you have to upgrade @@ -44,43 +49,48 @@ #include <opie/ocontact.h> #include "ocontactaccessbackend.h" class VObject; +/** + * This is the vCard 2.1 implementation of the Contact Storage + * @see OContactAccessBackend_XML + * @see OPimAccessBackend + */ class OContactAccessBackend_VCard : public OContactAccessBackend { public: - OContactAccessBackend_VCard ( QString appname, QString filename = 0l ); + OContactAccessBackend_VCard ( const QString& appname, const QString& filename = QString::null ); bool load (); bool reload(); bool save(); void clear (); bool add ( const OContact& newcontact ); bool remove ( int uid ); bool replace ( const OContact& contact ); - + OContact find ( int uid ) const; QArray<int> allRecords() const; QArray<int> queryByExample ( const OContact &query, int settings, const QDateTime& d = QDateTime() ); QArray<int> matchRegexp( const QRegExp &r ) const; const uint querySettings(); bool hasQuerySettings (uint querySettings) const; QArray<int> sorted( bool ascending, int sortOrder, int sortFilter, int cat ); bool wasChangedExternally(); - + private: OContact parseVObject( VObject* obj ); VObject* createVObject( const OContact& c ); QString convDateToVCardDate( const QDate& c ) const; QDate convVCardDateToDate( const QString& datestr ); VObject *safeAddPropValue( VObject *o, const char* prop, const QString& value ); VObject *safeAddProp( VObject* o, const char* prop); - + bool m_dirty : 1; QString m_file; QMap<int, OContact> m_map; }; #endif diff --git a/libopie2/opiepim/backend/ocontactaccessbackend_xml.cpp b/libopie2/opiepim/backend/ocontactaccessbackend_xml.cpp index c5a7820..661cd51 100644 --- a/libopie2/opiepim/backend/ocontactaccessbackend_xml.cpp +++ b/libopie2/opiepim/backend/ocontactaccessbackend_xml.cpp @@ -14,12 +14,17 @@ * * ===================================================================== * Version: $Id$ * ===================================================================== * History: * $Log$ + * Revision 1.5 2003/04/13 18:07:10 zecke + * More API doc + * QString -> const QString& + * QString = 0l -> QString::null + * * Revision 1.4 2003/03/21 14:32:54 mickeyl * g++ compliance fix: default arguments belong into the declaration, but not the definition * * Revision 1.3 2003/03/21 12:26:28 eilers * Fixing small bug: If we search a birthday from today to today, it returned * every contact .. @@ -90,13 +95,13 @@ #include <qdatetime.h> #include <qfile.h> #include <qfileinfo.h> #include <qregexp.h> #include <qarray.h> #include <qmap.h> -#include <qdatetime.h> +#include <qdatetime.h> #include <qpe/global.h> #include <opie/xmltree.h> #include "ocontactaccessbackend.h" #include "ocontactaccess.h" @@ -104,47 +109,47 @@ #include <stdlib.h> #include <errno.h> using namespace Opie; -OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString filename ): +OContactAccessBackend_XML::OContactAccessBackend_XML ( const QString& appname, const QString& filename ): m_changed( false ) { // Just m_contactlist should call delete if an entry // is removed. m_contactList.setAutoDelete( true ); m_uidToContact.setAutoDelete( false ); m_appName = appname; - + /* Set journalfile name ... */ m_journalName = getenv("HOME"); m_journalName +="/.abjournal" + appname; - + /* Expecting to access the default filename if nothing else is set */ if ( filename.isEmpty() ){ m_fileName = Global::applicationFileName( "addressbook","addressbook.xml" ); } else m_fileName = filename; - + /* Load Database now */ load (); } -bool OContactAccessBackend_XML::save() +bool OContactAccessBackend_XML::save() { - + if ( !m_changed ) return true; - + QString strNewFile = m_fileName + ".new"; QFile f( strNewFile ); if ( !f.open( IO_WriteOnly|IO_Raw ) ) return false; - + int total_written; int idx_offset = 0; QString out; // Write Header out = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><!DOCTYPE Addressbook ><AddressBook>\n" @@ -171,109 +176,109 @@ bool OContactAccessBackend_XML::save() QFile::remove( strNewFile ); return false; } out = ""; } out += " </Contacts>\n</AddressBook>\n"; - + // Write Footer cstr = out.utf8(); total_written = f.writeBlock( cstr.data(), cstr.length() ); if ( total_written != int( cstr.length() ) ) { f.close(); QFile::remove( strNewFile ); return false; } f.close(); - + // move the file over, I'm just going to use the system call // because, I don't feel like using QDir. if ( ::rename( strNewFile.latin1(), m_fileName.latin1() ) < 0 ) { qWarning( "problem renaming file %s to %s, errno: %d", strNewFile.latin1(), m_journalName.latin1(), errno ); // remove the tmp file... QFile::remove( strNewFile ); } - + /* The journalfile should be removed now... */ removeJournal(); - + m_changed = false; return true; } -bool OContactAccessBackend_XML::load () +bool OContactAccessBackend_XML::load () { m_contactList.clear(); m_uidToContact.clear(); - + /* Load XML-File and journal if it exists */ if ( !load ( m_fileName, false ) ) return false; /* The returncode of the journalfile is ignored due to the * fact that it does not exist when this class is instantiated ! * But there may such a file exist, if the application crashed. * Therefore we try to load it to get the changes before the # * crash happened... */ load (m_journalName, true); - + return true; } -void OContactAccessBackend_XML::clear () +void OContactAccessBackend_XML::clear () { m_contactList.clear(); m_uidToContact.clear(); m_changed = false; } bool OContactAccessBackend_XML::wasChangedExternally() { QFileInfo fi( m_fileName ); - + QDateTime lastmod = fi.lastModified (); - + return (lastmod != m_readtime); } -QArray<int> OContactAccessBackend_XML::allRecords() const +QArray<int> OContactAccessBackend_XML::allRecords() const { QArray<int> uid_list( m_contactList.count() ); - - uint counter = 0; + + uint counter = 0; QListIterator<OContact> it( m_contactList ); for( ; it.current(); ++it ){ uid_list[counter++] = (*it)->uid(); } - + return ( uid_list ); } OContact OContactAccessBackend_XML::find ( int uid ) const { OContact foundContact; //Create empty contact - + OContact* found = m_uidToContact.find( QString().setNum( uid ) ); if ( found ){ foundContact = *found; } - + return ( foundContact ); } -QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, int settings, +QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, int settings, const QDateTime& d ) { - + QArray<int> m_currentQuery( m_contactList.count() ); QListIterator<OContact> it( m_contactList ); uint arraycounter = 0; - + for( ; it.current(); ++it ){ /* Search all fields and compare them with query object. Store them into list * if all fields matches. */ QDate* queryDate = 0l; QDate* checkDate = 0l; @@ -287,68 +292,68 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i checkDate = new QDate( (*it)->birthday() ); case Qtopia::Anniversary: if ( queryDate == 0l ){ queryDate = new QDate( query.anniversary() ); checkDate = new QDate( (*it)->anniversary() ); } - + if ( queryDate->isValid() ){ if( checkDate->isValid() ){ if ( settings & OContactAccess::DateYear ){ if ( queryDate->year() != checkDate->year() ) allcorrect = false; - } + } if ( settings & OContactAccess::DateMonth ){ if ( queryDate->month() != checkDate->month() ) allcorrect = false; - } + } if ( settings & OContactAccess::DateDay ){ if ( queryDate->day() != checkDate->day() ) allcorrect = false; - } + } if ( settings & OContactAccess::DateDiff ) { QDate current; // If we get an additional date, we // will take this date instead of - // the current one.. + // the current one.. if ( !d.date().isValid() ) current = QDate::currentDate(); else current = d.date(); // We have to equalize the year, otherwise // the search will fail.. - checkDate->setYMD( current.year(), - checkDate->month(), + checkDate->setYMD( current.year(), + checkDate->month(), checkDate->day() ); if ( *checkDate < current ) - checkDate->setYMD( current.year()+1, - checkDate->month(), + checkDate->setYMD( current.year()+1, + checkDate->month(), checkDate->day() ); // Check whether the birthday/anniversary date is between // the current/given date and the maximum date // ( maximum time range ) ! - qWarning("Checking if %s is between %s and %s ! ", + qWarning("Checking if %s is between %s and %s ! ", checkDate->toString().latin1(), - current.toString().latin1(), + current.toString().latin1(), queryDate->toString().latin1() ); if ( current.daysTo( *queryDate ) >= 0 ){ - if ( !( ( *checkDate >= current ) && + if ( !( ( *checkDate >= current ) && ( *checkDate <= *queryDate ) ) ){ allcorrect = false; qWarning (" Nope!.."); } } } } else{ // checkDate is invalid. Therefore this entry is always rejected allcorrect = false; } } - + delete queryDate; queryDate = 0l; delete checkDate; checkDate = 0l; break; default: @@ -356,15 +361,15 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i if ( !query.field(i).isEmpty() ){ switch ( settings & ~( OContactAccess::IgnoreCase | OContactAccess::DateDiff | OContactAccess::DateYear | OContactAccess::DateMonth | OContactAccess::DateDay - | OContactAccess::MatchOne + | OContactAccess::MatchOne ) ){ - + case OContactAccess::RegExp:{ QRegExp expr ( query.field(i), !(settings & OContactAccess::IgnoreCase), false ); if ( expr.find ( (*it)->field(i), 0 ) == -1 ) allcorrect = false; @@ -394,122 +399,122 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i } } if ( allcorrect ){ m_currentQuery[arraycounter++] = (*it)->uid(); } } - + // Shrink to fit.. m_currentQuery.resize(arraycounter); - + return m_currentQuery; } QArray<int> OContactAccessBackend_XML::matchRegexp( const QRegExp &r ) const { QArray<int> m_currentQuery( m_contactList.count() ); QListIterator<OContact> it( m_contactList ); uint arraycounter = 0; - + for( ; it.current(); ++it ){ if ( (*it)->match( r ) ){ m_currentQuery[arraycounter++] = (*it)->uid(); } - + } // Shrink to fit.. m_currentQuery.resize(arraycounter); - + return m_currentQuery; } const uint OContactAccessBackend_XML::querySettings() { return ( OContactAccess::WildCards | OContactAccess::IgnoreCase | OContactAccess::RegExp - | OContactAccess::ExactMatch + | OContactAccess::ExactMatch | OContactAccess::DateDiff | OContactAccess::DateYear | OContactAccess::DateMonth | OContactAccess::DateDay ); } bool OContactAccessBackend_XML::hasQuerySettings (uint querySettings) const { - /* OContactAccess::IgnoreCase, DateDiff, DateYear, DateMonth, DateDay + /* OContactAccess::IgnoreCase, DateDiff, DateYear, DateMonth, DateDay * may be added with any of the other settings. IgnoreCase should never used alone. * Wildcards, RegExp, ExactMatch should never used at the same time... */ - - if ( querySettings == OContactAccess::IgnoreCase ) + + if ( querySettings == OContactAccess::IgnoreCase ) return false; - + switch ( querySettings & ~( OContactAccess::IgnoreCase | OContactAccess::DateDiff | OContactAccess::DateYear | OContactAccess::DateMonth | OContactAccess::DateDay - ) + ) ){ case OContactAccess::RegExp: return ( true ); case OContactAccess::WildCards: return ( true ); case OContactAccess::ExactMatch: return ( true ); default: return ( false ); } } -// Currently only asc implemented.. -QArray<int> OContactAccessBackend_XML::sorted( bool asc, int , int , int ) +// Currently only asc implemented.. +QArray<int> OContactAccessBackend_XML::sorted( bool asc, int , int , int ) { QMap<QString, int> nameToUid; QStringList names; QArray<int> m_currentQuery( m_contactList.count() ); - - // First fill map and StringList with all Names + + // First fill map and StringList with all Names // Afterwards sort namelist and use map to fill array to return.. QListIterator<OContact> it( m_contactList ); for( ; it.current(); ++it ){ names.append( (*it)->fileAs() + QString::number( (*it)->uid() ) ); nameToUid.insert( (*it)->fileAs() + QString::number( (*it)->uid() ), (*it)->uid() ); } names.sort(); - + int i = 0; if ( asc ){ for ( QStringList::Iterator it = names.begin(); it != names.end(); ++it ) m_currentQuery[i++] = nameToUid[ (*it) ]; }else{ for ( QStringList::Iterator it = names.end(); it != names.begin(); --it ) m_currentQuery[i++] = nameToUid[ (*it) ]; } - + return m_currentQuery; - + } bool OContactAccessBackend_XML::add ( const OContact &newcontact ) { //qWarning("odefaultbackend: ACTION::ADD"); updateJournal (newcontact, ACTION_ADD); addContact_p( newcontact ); - + m_changed = true; - + return true; } bool OContactAccessBackend_XML::replace ( const OContact &contact ) { m_changed = true; - + OContact* found = m_uidToContact.find ( QString().setNum( contact.uid() ) ); if ( found ) { OContact* newCont = new OContact( contact ); updateJournal ( *newCont, ACTION_REPLACE); @@ -525,13 +530,13 @@ bool OContactAccessBackend_XML::replace ( const OContact &contact ) return false; } bool OContactAccessBackend_XML::remove ( int uid ) { m_changed = true; - + OContact* found = m_uidToContact.find ( QString().setNum( uid ) ); if ( found ) { updateJournal ( *found, ACTION_REMOVE); m_contactList.removeRef ( found ); m_uidToContact.remove( QString().setNum( uid ) ); @@ -552,34 +557,34 @@ void OContactAccessBackend_XML::addContact_p( const OContact &newcontact ) m_contactList.append ( contRef ); m_uidToContact.insert( QString().setNum( newcontact.uid() ), contRef ); } /* This function loads the xml-database and the journalfile */ -bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) +bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) { - + /* We use the time of the last read to check if the file was * changed externally. */ if ( !isJournal ){ QFileInfo fi( filename ); m_readtime = fi.lastModified (); } - + const int JOURNALACTION = Qtopia::Notes + 1; const int JOURNALROW = JOURNALACTION + 1; - + bool foundAction = false; journal_action action = ACTION_ADD; int journalKey = 0; QMap<int, QString> contactMap; QMap<QString, QString> customMap; QMap<QString, QString>::Iterator customIt; QAsciiDict<int> dict( 47 ); - + dict.setAutoDelete( TRUE ); dict.insert( "Uid", new int(Qtopia::AddressUid) ); dict.insert( "Title", new int(Qtopia::Title) ); dict.insert( "FirstName", new int(Qtopia::FirstName) ); dict.insert( "MiddleName", new int(Qtopia::MiddleName) ); dict.insert( "LastName", new int(Qtopia::LastName) ); @@ -620,24 +625,24 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) dict.insert( "Birthday", new int(Qtopia::Birthday) ); dict.insert( "Anniversary", new int(Qtopia::Anniversary) ); dict.insert( "Nickname", new int(Qtopia::Nickname) ); dict.insert( "Notes", new int(Qtopia::Notes) ); dict.insert( "action", new int(JOURNALACTION) ); dict.insert( "actionrow", new int(JOURNALROW) ); - + //qWarning( "OContactDefaultBackEnd::loading %s", filename.latin1() ); - + XMLElement *root = XMLElement::load( filename ); if(root != 0l ){ // start parsing /* Parse all XML-Elements and put the data into the * Contact-Class */ XMLElement *element = root->firstChild(); //qWarning("OContactAccess::load tagName(): %s", root->tagName().latin1() ); element = element->firstChild(); - + /* Search Tag "Contacts" which is the parent of all Contacts */ while( element && !isJournal ){ if( element->tagName() != QString::fromLatin1("Contacts") ){ //qWarning ("OContactDefBack::Searching for Tag \"Contacts\"! Found: %s", // element->tagName().latin1()); element = element->nextChild(); @@ -658,29 +663,29 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) * attributes contained */ //qWarning("OContactDefBack::load element tagName() : %s", // element->tagName().latin1() ); QString dummy; foundAction = false; - + XMLElement::AttributeMap aMap = element->attributes(); XMLElement::AttributeMap::Iterator it; contactMap.clear(); customMap.clear(); for( it = aMap.begin(); it != aMap.end(); ++it ){ // qWarning ("Read Attribute: %s=%s", it.key().latin1(),it.data().latin1()); - + int *find = dict[ it.key() ]; /* Unknown attributes will be stored as "Custom" elements */ if ( !find ) { qWarning("Attribute %s not known.", it.key().latin1()); //contact.setCustomField(it.key(), it.data()); customMap.insert( it.key(), it.data() ); continue; } - + /* Check if special conversion is needed and add attribute * into Contact class */ switch( *find ) { /* case Qtopia::AddressUid: @@ -702,17 +707,17 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) contactMap.insert( *find, it.data() ); break; } } /* now generate the Contact contact */ OContact contact( contactMap ); - + for (customIt = customMap.begin(); customIt != customMap.end(); ++customIt ) { contact.setCustomField( customIt.key(), customIt.data() ); } - + if (foundAction){ foundAction = false; switch ( action ) { case ACTION_ADD: addContact_p (contact); break; @@ -731,13 +736,13 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) break; } }else{ /* Add contact to list */ addContact_p (contact); } - + /* Move to next element */ element = element->nextChild(); } }else { qWarning("ODefBack::could not load"); } @@ -745,31 +750,31 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) qWarning("returning from loading" ); return true; } void OContactAccessBackend_XML::updateJournal( const OContact& cnt, - journal_action action ) + journal_action action ) { QFile f( m_journalName ); bool created = !f.exists(); if ( !f.open(IO_WriteOnly|IO_Append) ) return; - + QString buf; QCString str; - + // if the file was created, we have to set the Tag "<CONTACTS>" to // get a XML-File which is readable by our parser. // This is just a cheat, but better than rewrite the parser. if ( created ){ buf = "<Contacts>"; QCString cstr = buf.utf8(); f.writeBlock( cstr.data(), cstr.length() ); } - + buf = "<Contact "; cnt.save( buf ); buf += " action=\"" + QString::number( (int)action ) + "\" "; buf += "/>\n"; QCString cstr = buf.utf8(); f.writeBlock( cstr.data(), cstr.length() ); diff --git a/libopie2/opiepim/backend/ocontactaccessbackend_xml.h b/libopie2/opiepim/backend/ocontactaccessbackend_xml.h index 4d6a7ef..7b5365b 100644 --- a/libopie2/opiepim/backend/ocontactaccessbackend_xml.h +++ b/libopie2/opiepim/backend/ocontactaccessbackend_xml.h @@ -14,12 +14,17 @@ * * ===================================================================== * Version: $Id$ * ===================================================================== * History: * $Log$ + * Revision 1.14 2003/04/13 18:07:10 zecke + * More API doc + * QString -> const QString& + * QString = 0l -> QString::null + * * Revision 1.13 2003/03/21 10:33:09 eilers * Merged speed optimized xml backend for contacts to main. * Added QDateTime to querybyexample. For instance, it is now possible to get * all Birthdays/Anniversaries between two dates. This should be used * to show all birthdays in the datebook.. * This change is sourcecode backward compatible but you have to upgrade @@ -81,58 +86,63 @@ #include "ocontactaccess.h" #include <qlist.h> #include <qdict.h> /* the default xml implementation */ +/** + * This class is the XML implementation of a Contact backend + * it does implement everything available for OContact. + * @see OPimAccessBackend for more information of available methods + */ class OContactAccessBackend_XML : public OContactAccessBackend { public: - OContactAccessBackend_XML ( QString appname, QString filename = 0l ); - + OContactAccessBackend_XML ( const QString& appname, const QString& filename = QString::null ); + bool save(); - + bool load (); void clear (); - + bool wasChangedExternally(); - + QArray<int> allRecords() const; - + OContact find ( int uid ) const; - + QArray<int> queryByExample ( const OContact &query, int settings, const QDateTime& d = QDateTime() ); QArray<int> matchRegexp( const QRegExp &r ) const; - + const uint querySettings(); - + bool hasQuerySettings (uint querySettings) const; - - // Currently only asc implemented.. + + // Currently only asc implemented.. QArray<int> sorted( bool asc, int , int , int ); bool add ( const OContact &newcontact ); - + bool replace ( const OContact &contact ); - + bool remove ( int uid ); bool reload(); - + private: enum journal_action { ACTION_ADD, ACTION_REMOVE, ACTION_REPLACE }; void addContact_p( const OContact &newcontact ); - + /* This function loads the xml-database and the journalfile */ bool load( const QString filename, bool isJournal ); - - + + void updateJournal( const OContact& cnt, journal_action action ); void removeJournal(); - + protected: bool m_changed; QString m_journalName; QString m_fileName; QString m_appName; QList<OContact> m_contactList; diff --git a/libopie2/opiepim/backend/odatebookaccessbackend.h b/libopie2/opiepim/backend/odatebookaccessbackend.h index eb6e8fb..86ff298 100644 --- a/libopie2/opiepim/backend/odatebookaccessbackend.h +++ b/libopie2/opiepim/backend/odatebookaccessbackend.h @@ -3,30 +3,71 @@ #include <qarray.h> #include "opimaccessbackend.h" #include "oevent.h" +/** + * This class is the interface to the storage of Events. + * @see OPimAccessBackend + * + */ class ODateBookAccessBackend : public OPimAccessBackend<OEvent> { public: typedef int UID; + + /** + * c'tor without parameter + */ ODateBookAccessBackend(); ~ODateBookAccessBackend(); + /** + * This method should return a list of UIDs containing + * all events. No filter should be applied + * @return list of events + */ virtual QArray<UID> rawEvents()const = 0; + + /** + * This method should return a list of UIDs containing + * all repeating events. No filter should be applied + * @return list of repeating events + */ virtual QArray<UID> rawRepeats()const = 0; + + /** + * This mthod should return a list of UIDs containing all non + * repeating events. No filter should be applied + * @return list of nonrepeating events + */ virtual QArray<UID> nonRepeats() const = 0; /** - * these two methods are used if you do not implement - * effectiveEvents... + * If you do not want to implement the effectiveEvents methods below + * you need to supply it with directNonRepeats. + * This method can return empty lists if effectiveEvents is implememted */ virtual OEvent::ValueList directNonRepeats() = 0; + + /** + * Same as above but return raw repeats! + */ virtual OEvent::ValueList directRawRepeats() = 0; /* is implemented by default but you can reimplement it*/ + /** + * Effective Events are special event occuring during a time frame. This method does calcualte + * EffectiveEvents bases on the directNonRepeats and directRawRepeats. You may implement this method + * yourself + */ virtual OEffectiveEvent::ValueList effecticeEvents( const QDate& from, const QDate& to ); + + /** + * this is an overloaded member function + * @see effecticeEvents + */ virtual OEffectiveEvent::ValueList effecticeEvents( const QDateTime& start ); }; #endif diff --git a/libopie2/opiepim/backend/odatebookaccessbackend_xml.h b/libopie2/opiepim/backend/odatebookaccessbackend_xml.h index 563c31f..7848f7c 100644 --- a/libopie2/opiepim/backend/odatebookaccessbackend_xml.h +++ b/libopie2/opiepim/backend/odatebookaccessbackend_xml.h @@ -2,12 +2,18 @@ #define OPIE_DATE_BOOK_ACCESS_BACKEND_XML__H #include <qmap.h> #include "odatebookaccessbackend.h" +/** + * This is the default XML implementation for DateBoook XML storage + * It fully implements the interface + * @see ODateBookAccessBackend + * @see OPimAccessBackend + */ class ODateBookAccessBackend_XML : public ODateBookAccessBackend { public: ODateBookAccessBackend_XML( const QString& appName, const QString& fileName = QString::null); ~ODateBookAccessBackend_XML(); diff --git a/libopie2/opiepim/core/ocontactaccess.h b/libopie2/opiepim/core/ocontactaccess.h index 32b2dcb..d7ceaf2 100644 --- a/libopie2/opiepim/core/ocontactaccess.h +++ b/libopie2/opiepim/core/ocontactaccess.h @@ -14,12 +14,17 @@ * ToDo: Define enum for query settings * ===================================================================== * Version: $Id$ * ===================================================================== * History: * $Log$ + * Revision 1.7 2003/04/13 18:07:10 zecke + * More API doc + * QString -> const QString& + * QString = 0l -> QString::null + * * Revision 1.6 2003/01/02 14:27:12 eilers * Improved query by example: Search by date is possible.. First step * for a today plugin for birthdays.. * * Revision 1.5 2002/11/13 14:14:51 eilers * Added sorted for Contacts.. @@ -52,23 +57,28 @@ #include <qfileinfo.h> #include "ocontact.h" #include "ocontactaccessbackend.h" #include "opimaccesstemplate.h" -/** Class to access the contacts database. +/** + * Class to access the contacts database. * This is just a frontend for the real database handling which is * done by the backend. + * This class is used to access the Contacts on a system. This class as any OPIE PIM + * class is backend independent. + * @see OPimAccessTemplate */ class OContactAccess: public QObject, public OPimAccessTemplate<OContact> { Q_OBJECT public: - /** Create Database with contacts (addressbook). + /** + * Create Database with contacts (addressbook). * @param appname Name of application which wants access to the database * (i.e. "todolist") * @param filename The name of the database file. If not set, the default one * is used. * @param backend Pointer to an alternative Backend. If not set, we will use * the default backend. @@ -96,13 +106,13 @@ class OContactAccess: public QObject, public OPimAccessTemplate<OContact> DateDiff = 0x0020, // Find all entries from today until given date DateYear = 0x0040, // The year matches DateMonth = 0x0080, // The month matches DateDay = 0x0100, // The day matches }; - + ORecordList<OContact> matchRegexp( const QRegExp &r )const; /** Return all Contacts in a sorted manner. * @param ascending true: Sorted in acending order. * @param sortOrder Currently not implemented. Just defined to stay compatible to otodoaccess * @param sortFilter Currently not implemented. Just defined to stay compatible to otodoaccess diff --git a/libopie2/opiepim/core/odatebookaccess.cpp b/libopie2/opiepim/core/odatebookaccess.cpp index 08e61ff..a3661a3 100644 --- a/libopie2/opiepim/core/odatebookaccess.cpp +++ b/libopie2/opiepim/core/odatebookaccess.cpp @@ -1,38 +1,66 @@ #include "obackendfactory.h" #include "odatebookaccess.h" +/** + * Simple constructor + * It takes a ODateBookAccessBackend as parent. If it is 0 the default implementation + * will be used! + * @param back The backend to be used or 0 for the default backend + * @param ac What kind of access is intended + */ ODateBookAccess::ODateBookAccess( ODateBookAccessBackend* back, enum Access ac ) : OPimAccessTemplate<OEvent>( back ) { if (!back ) back = OBackendFactory<ODateBookAccessBackend>::Default("datebook", QString::null ); m_backEnd = back; setBackEnd( m_backEnd ); } ODateBookAccess::~ODateBookAccess() { } + +/** + * @return all events available + */ ODateBookAccess::List ODateBookAccess::rawEvents()const { QArray<int> ints = m_backEnd->rawEvents(); List lis( ints, this ); return lis; } + +/** + * @return all repeating events + */ ODateBookAccess::List ODateBookAccess::rawRepeats()const { QArray<int> ints = m_backEnd->rawRepeats(); List lis( ints, this ); return lis; } + +/** + * @return all non repeating events + */ ODateBookAccess::List ODateBookAccess::nonRepeats()const { QArray<int> ints = m_backEnd->nonRepeats(); List lis( ints, this ); return lis; } + +/** + * @return dates in the time span between from and to + * @param from Include all events from... + * @param to Include all events to... + */ OEffectiveEvent::ValueList ODateBookAccess::effectiveEvents( const QDate& from, const QDate& to ) { return m_backEnd->effecticeEvents( from, to ); } +/** + * @return all events at a given datetime + */ OEffectiveEvent::ValueList ODateBookAccess::effectiveEvents( const QDateTime& start ) { return m_backEnd->effecticeEvents( start ); } diff --git a/libopie2/opiepim/core/odatebookaccess.h b/libopie2/opiepim/core/odatebookaccess.h index 7047039..7c7a63f 100644 --- a/libopie2/opiepim/core/odatebookaccess.h +++ b/libopie2/opiepim/core/odatebookaccess.h @@ -3,24 +3,33 @@ #include "odatebookaccessbackend.h" #include "opimaccesstemplate.h" #include "oevent.h" +/** + * This is the object orientated datebook database. It'll use OBackendFactory + * to query for a backend. + * All access to the datebook should be done via this class. + * Make sure to load and save the datebook this is not part of + * destructing and creating the object + * + * @author Holger Freyther + */ class ODateBookAccess : public OPimAccessTemplate<OEvent> { public: ODateBookAccess( ODateBookAccessBackend* = 0l, enum Access acc = Random ); ~ODateBookAccess(); - /** return all events */ + /* return all events */ List rawEvents()const; - /** return repeating events */ + /* return repeating events */ List rawRepeats()const; - /** return non repeating events */ + /* return non repeating events */ List nonRepeats()const; OEffectiveEvent::ValueList effectiveEvents( const QDate& from, const QDate& to ); OEffectiveEvent::ValueList effectiveEvents( const QDateTime& start ); private: diff --git a/libopie2/opiepim/ocontact.h b/libopie2/opiepim/ocontact.h index 1fd1c75..25fa0e7 100644 --- a/libopie2/opiepim/ocontact.h +++ b/libopie2/opiepim/ocontact.h @@ -31,14 +31,21 @@ #if defined(QPC_TEMPLATEDLL) // MOC_SKIP_BEGIN QPC_TEMPLATEEXTERN template class QPC_EXPORT QMap<int, QString>; // MOC_SKIP_END #endif -class ContactPrivate; - +class ContactPrivate; + +/** + * OContact class represents a specialised PIM Record for contacts. + * It does store all kind of persopn related information. + * + * @short Contact Container + * @author TT, Stefan Eiler, Holger Freyther + */ class QPC_EXPORT OContact : public OPimRecord { friend class DataSet; public: OContact(); OContact( const QMap<int, QString> &fromMap ); diff --git a/libopie2/opiepim/oevent.h b/libopie2/opiepim/oevent.h index 585515c..57d32d0 100644 --- a/libopie2/opiepim/oevent.h +++ b/libopie2/opiepim/oevent.h @@ -27,15 +27,24 @@ struct OCalendarHelper { static int monthDiff( const QDate& first, const QDate& second ); }; class OPimNotifyManager; class ORecur; + +/** + * This is the container for all Events. It encapsules all + * available information for a single Event + * @short container for events. + */ class OEvent : public OPimRecord { public: typedef QValueList<OEvent> ValueList; + /** + * RecordFields contain possible attributes + */ enum RecordFields { Uid = Qtopia::UID_ID, Category = Qtopia::CATEGORY_ID, Description, Location, Alarm, @@ -46,13 +55,20 @@ public: StartDate, EndDate, AllDay, TimeZone }; + /** + * Start with an Empty OEvent. UID == 0 means that it is empty + */ OEvent(int uid = 0); + + /** + * copy c'tor + */ OEvent( const OEvent& ); ~OEvent(); OEvent &operator=( const OEvent& ); QString description()const; void setDescription( const QString& description ); @@ -141,13 +157,12 @@ private: }; /** * AN Event can span through multiple days. We split up a multiday eve */ - class OEffectiveEvent { public: typedef QValueList<OEffectiveEvent> ValueList; enum Position { MidWay, Start, End, StartEnd }; // If we calculate the effective event of a multi-day event // we have to figure out whether we are at the first day, |