26 files changed, 630 insertions, 246 deletions
diff --git a/libopie/pim/obackendfactory.h b/libopie/pim/obackendfactory.h index 3a73210..ad6cf5a 100644 --- a/libopie/pim/obackendfactory.h +++ b/libopie/pim/obackendfactory.h @@ -18,2 +18,7 @@ * $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 @@ -65,3 +70,17 @@ - +/** + * 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> @@ -78,2 +97,7 @@ class OBackendFactory + /** + * 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 ){ diff --git a/libopie/pim/ocontact.h b/libopie/pim/ocontact.h index 1fd1c75..25fa0e7 100644 --- a/libopie/pim/ocontact.h +++ b/libopie/pim/ocontact.h @@ -36,4 +36,11 @@ QPC_TEMPLATEEXTERN template class QPC_EXPORT QMap<int, QString>; -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 diff --git a/libopie/pim/ocontactaccess.h b/libopie/pim/ocontactaccess.h index 32b2dcb..d7ceaf2 100644 --- a/libopie/pim/ocontactaccess.h +++ b/libopie/pim/ocontactaccess.h @@ -19,2 +19,7 @@ * $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 @@ -57,5 +62,9 @@ -/** 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 @@ -67,3 +76,4 @@ class OContactAccess: public QObject, public OPimAccessTemplate<OContact> public: - /** Create Database with contacts (addressbook). + /** + * Create Database with contacts (addressbook). * @param appname Name of application which wants access to the database @@ -101,3 +111,3 @@ class OContactAccess: public QObject, public OPimAccessTemplate<OContact> - + ORecordList<OContact> matchRegexp( const QRegExp &r )const; diff --git a/libopie/pim/ocontactaccessbackend.h b/libopie/pim/ocontactaccessbackend.h index 821f5bf..ebeb42d 100644 --- a/libopie/pim/ocontactaccessbackend.h +++ b/libopie/pim/ocontactaccessbackend.h @@ -21,2 +21,7 @@ * $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 @@ -46,4 +51,14 @@ -#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> { @@ -54,3 +69,4 @@ class OContactAccessBackend: public OPimAccessBackend<OContact> { - /** 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. @@ -70,3 +86,4 @@ class OContactAccessBackend: public OPimAccessBackend<OContact> { - /** Return all possible settings. + /** + * Return all possible settings. * @return All settings provided by the current backend @@ -76,3 +93,4 @@ class OContactAccessBackend: public OPimAccessBackend<OContact> { - /** Check whether settings are correct. + /** + * Check whether settings are correct. * @return <i>true</i> if the given settings are correct and possible. @@ -81,3 +99,7 @@ class OContactAccessBackend: public OPimAccessBackend<OContact> { - 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; diff --git a/libopie/pim/ocontactaccessbackend_vcard.cpp b/libopie/pim/ocontactaccessbackend_vcard.cpp index f24523f..270bef3 100644 --- a/libopie/pim/ocontactaccessbackend_vcard.cpp +++ b/libopie/pim/ocontactaccessbackend_vcard.cpp @@ -19,2 +19,7 @@ * $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 @@ -78,3 +83,3 @@ -OContactAccessBackend_VCard::OContactAccessBackend_VCard ( QString , QString filename ): +OContactAccessBackend_VCard::OContactAccessBackend_VCard ( const QString& , const QString& filename ): m_dirty( false ), diff --git a/libopie/pim/ocontactaccessbackend_vcard.h b/libopie/pim/ocontactaccessbackend_vcard.h index 93e2da3..712d769 100644 --- a/libopie/pim/ocontactaccessbackend_vcard.h +++ b/libopie/pim/ocontactaccessbackend_vcard.h @@ -19,2 +19,7 @@ * $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 @@ -49,5 +54,10 @@ 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 ); @@ -61,3 +71,3 @@ class OContactAccessBackend_VCard : public OContactAccessBackend { bool replace ( const OContact& contact ); - + OContact find ( int uid ) const; @@ -71,3 +81,3 @@ class OContactAccessBackend_VCard : public OContactAccessBackend { bool wasChangedExternally(); - + private: @@ -79,3 +89,3 @@ private: VObject *safeAddProp( VObject* o, const char* prop); - + bool m_dirty : 1; diff --git a/libopie/pim/ocontactaccessbackend_xml.cpp b/libopie/pim/ocontactaccessbackend_xml.cpp index c5a7820..661cd51 100644 --- a/libopie/pim/ocontactaccessbackend_xml.cpp +++ b/libopie/pim/ocontactaccessbackend_xml.cpp @@ -19,2 +19,7 @@ * $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 @@ -95,3 +100,3 @@ #include <qmap.h> -#include <qdatetime.h> +#include <qdatetime.h> @@ -109,3 +114,3 @@ using namespace Opie; -OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString filename ): +OContactAccessBackend_XML::OContactAccessBackend_XML ( const QString& appname, const QString& filename ): m_changed( false ) @@ -118,3 +123,3 @@ OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString m_appName = appname; - + /* Set journalfile name ... */ @@ -122,3 +127,3 @@ OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString m_journalName +="/.abjournal" + appname; - + /* Expecting to access the default filename if nothing else is set */ @@ -128,3 +133,3 @@ OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString m_fileName = filename; - + /* Load Database now */ @@ -133,8 +138,8 @@ OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString -bool OContactAccessBackend_XML::save() +bool OContactAccessBackend_XML::save() { - + if ( !m_changed ) return true; - + QString strNewFile = m_fileName + ".new"; @@ -143,3 +148,3 @@ bool OContactAccessBackend_XML::save() return false; - + int total_written; @@ -176,3 +181,3 @@ bool OContactAccessBackend_XML::save() out += " </Contacts>\n</AddressBook>\n"; - + // Write Footer @@ -186,3 +191,3 @@ bool OContactAccessBackend_XML::save() f.close(); - + // move the file over, I'm just going to use the system call @@ -195,6 +200,6 @@ bool OContactAccessBackend_XML::save() } - + /* The journalfile should be removed now... */ removeJournal(); - + m_changed = false; @@ -203,3 +208,3 @@ bool OContactAccessBackend_XML::save() -bool OContactAccessBackend_XML::load () +bool OContactAccessBackend_XML::load () { @@ -207,3 +212,3 @@ bool OContactAccessBackend_XML::load () m_uidToContact.clear(); - + /* Load XML-File and journal if it exists */ @@ -218,3 +223,3 @@ bool OContactAccessBackend_XML::load () load (m_journalName, true); - + return true; @@ -222,3 +227,3 @@ bool OContactAccessBackend_XML::load () -void OContactAccessBackend_XML::clear () +void OContactAccessBackend_XML::clear () { @@ -233,5 +238,5 @@ bool OContactAccessBackend_XML::wasChangedExternally() QFileInfo fi( m_fileName ); - + QDateTime lastmod = fi.lastModified (); - + return (lastmod != m_readtime); @@ -239,7 +244,7 @@ bool OContactAccessBackend_XML::wasChangedExternally() -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 ); @@ -248,3 +253,3 @@ QArray<int> OContactAccessBackend_XML::allRecords() const } - + return ( uid_list ); @@ -255,3 +260,3 @@ OContact OContactAccessBackend_XML::find ( int uid ) const OContact foundContact; //Create empty contact - + OContact* found = m_uidToContact.find( QString().setNum( uid ) ); @@ -261,3 +266,3 @@ OContact OContactAccessBackend_XML::find ( int uid ) const } - + return ( foundContact ); @@ -265,6 +270,6 @@ OContact OContactAccessBackend_XML::find ( int uid ) const -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() ); @@ -272,3 +277,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i uint arraycounter = 0; - + for( ; it.current(); ++it ){ @@ -292,3 +297,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i } - + if ( queryDate->isValid() ){ @@ -298,3 +303,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i allcorrect = false; - } + } if ( settings & OContactAccess::DateMonth ){ @@ -302,3 +307,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i allcorrect = false; - } + } if ( settings & OContactAccess::DateDay ){ @@ -306,3 +311,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i allcorrect = false; - } + } if ( settings & OContactAccess::DateDiff ) { @@ -311,3 +316,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i // will take this date instead of - // the current one.. + // the current one.. if ( !d.date().isValid() ) @@ -319,8 +324,8 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i // 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() ); @@ -330,8 +335,8 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i // ( 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 ) ) ){ @@ -347,3 +352,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i } - + delete queryDate; @@ -361,5 +366,5 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i | OContactAccess::DateDay - | OContactAccess::MatchOne + | OContactAccess::MatchOne ) ){ - + case OContactAccess::RegExp:{ @@ -399,6 +404,6 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i } - + // Shrink to fit.. m_currentQuery.resize(arraycounter); - + return m_currentQuery; @@ -411,3 +416,3 @@ QArray<int> OContactAccessBackend_XML::matchRegexp( const QRegExp &r ) const uint arraycounter = 0; - + for( ; it.current(); ++it ){ @@ -416,3 +421,3 @@ QArray<int> OContactAccessBackend_XML::matchRegexp( const QRegExp &r ) const } - + } @@ -420,3 +425,3 @@ QArray<int> OContactAccessBackend_XML::matchRegexp( const QRegExp &r ) const m_currentQuery.resize(arraycounter); - + return m_currentQuery; @@ -429,3 +434,3 @@ const uint OContactAccessBackend_XML::querySettings() | OContactAccess::RegExp - | OContactAccess::ExactMatch + | OContactAccess::ExactMatch | OContactAccess::DateDiff @@ -439,3 +444,3 @@ 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. @@ -443,6 +448,6 @@ bool OContactAccessBackend_XML::hasQuerySettings (uint querySettings) const */ - - if ( querySettings == OContactAccess::IgnoreCase ) + + if ( querySettings == OContactAccess::IgnoreCase ) return false; - + switch ( querySettings & ~( OContactAccess::IgnoreCase @@ -452,3 +457,3 @@ bool OContactAccessBackend_XML::hasQuerySettings (uint querySettings) const | OContactAccess::DateDay - ) + ) ){ @@ -465,4 +470,4 @@ bool OContactAccessBackend_XML::hasQuerySettings (uint querySettings) const -// 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 ) { @@ -471,4 +476,4 @@ QArray<int> OContactAccessBackend_XML::sorted( bool asc, int , int , int ) 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.. @@ -480,3 +485,3 @@ QArray<int> OContactAccessBackend_XML::sorted( bool asc, int , int , int ) names.sort(); - + int i = 0; @@ -489,5 +494,5 @@ QArray<int> OContactAccessBackend_XML::sorted( bool asc, int , int , int ) } - + return m_currentQuery; - + } @@ -499,5 +504,5 @@ bool OContactAccessBackend_XML::add ( const OContact &newcontact ) addContact_p( newcontact ); - + m_changed = true; - + return true; @@ -508,3 +513,3 @@ bool OContactAccessBackend_XML::replace ( const OContact &contact ) m_changed = true; - + OContact* found = m_uidToContact.find ( QString().setNum( contact.uid() ) ); @@ -530,3 +535,3 @@ bool OContactAccessBackend_XML::remove ( int uid ) m_changed = true; - + OContact* found = m_uidToContact.find ( QString().setNum( uid ) ); @@ -557,5 +562,5 @@ void OContactAccessBackend_XML::addContact_p( const OContact &newcontact ) /* 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 @@ -567,6 +572,6 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) } - + const int JOURNALACTION = Qtopia::Notes + 1; const int JOURNALROW = JOURNALACTION + 1; - + bool foundAction = false; @@ -578,3 +583,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) QAsciiDict<int> dict( 47 ); - + dict.setAutoDelete( TRUE ); @@ -625,5 +630,5 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) dict.insert( "actionrow", new int(JOURNALROW) ); - + //qWarning( "OContactDefaultBackEnd::loading %s", filename.latin1() ); - + XMLElement *root = XMLElement::load( filename ); @@ -636,3 +641,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) element = element->firstChild(); - + /* Search Tag "Contacts" which is the parent of all Contacts */ @@ -663,3 +668,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) foundAction = false; - + XMLElement::AttributeMap aMap = element->attributes(); @@ -670,3 +675,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) // qWarning ("Read Attribute: %s=%s", it.key().latin1(),it.data().latin1()); - + int *find = dict[ it.key() ]; @@ -679,3 +684,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) } - + /* Check if special conversion is needed and add attribute @@ -707,3 +712,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) OContact contact( contactMap ); - + for (customIt = customMap.begin(); customIt != customMap.end(); ++customIt ) { @@ -711,3 +716,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) } - + if (foundAction){ @@ -736,3 +741,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) } - + /* Move to next element */ @@ -750,3 +755,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) void OContactAccessBackend_XML::updateJournal( const OContact& cnt, - journal_action action ) + journal_action action ) { @@ -756,6 +761,6 @@ void OContactAccessBackend_XML::updateJournal( const OContact& cnt, return; - + QString buf; QCString str; - + // if the file was created, we have to set the Tag "<CONTACTS>" to @@ -768,3 +773,3 @@ void OContactAccessBackend_XML::updateJournal( const OContact& cnt, } - + buf = "<Contact "; diff --git a/libopie/pim/ocontactaccessbackend_xml.h b/libopie/pim/ocontactaccessbackend_xml.h index 4d6a7ef..7b5365b 100644 --- a/libopie/pim/ocontactaccessbackend_xml.h +++ b/libopie/pim/ocontactaccessbackend_xml.h @@ -19,2 +19,7 @@ * $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 @@ -86,8 +91,13 @@ /* 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 (); @@ -95,9 +105,9 @@ class OContactAccessBackend_XML : public OContactAccessBackend { 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() ); @@ -105,16 +115,16 @@ class OContactAccessBackend_XML : public OContactAccessBackend { 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: @@ -124,10 +134,10 @@ class OContactAccessBackend_XML : public OContactAccessBackend { 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: diff --git a/libopie/pim/odatebookaccess.cpp b/libopie/pim/odatebookaccess.cpp index 08e61ff..a3661a3 100644 --- a/libopie/pim/odatebookaccess.cpp +++ b/libopie/pim/odatebookaccess.cpp @@ -3,2 +3,9 @@ +/** + * 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 ) @@ -14,2 +21,6 @@ ODateBookAccess::~ODateBookAccess() { } + +/** + * @return all events available + */ ODateBookAccess::List ODateBookAccess::rawEvents()const { @@ -20,2 +31,6 @@ ODateBookAccess::List ODateBookAccess::rawEvents()const { } + +/** + * @return all repeating events + */ ODateBookAccess::List ODateBookAccess::rawRepeats()const { @@ -26,2 +41,6 @@ ODateBookAccess::List ODateBookAccess::rawRepeats()const { } + +/** + * @return all non repeating events + */ ODateBookAccess::List ODateBookAccess::nonRepeats()const { @@ -32,2 +51,8 @@ ODateBookAccess::List ODateBookAccess::nonRepeats()const { } + +/** + * @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 ) { @@ -35,2 +60,5 @@ OEffectiveEvent::ValueList ODateBookAccess::effectiveEvents( const QDate& from, } +/** + * @return all events at a given datetime + */ OEffectiveEvent::ValueList ODateBookAccess::effectiveEvents( const QDateTime& start ) { diff --git a/libopie/pim/odatebookaccess.h b/libopie/pim/odatebookaccess.h index 7047039..7c7a63f 100644 --- a/libopie/pim/odatebookaccess.h +++ b/libopie/pim/odatebookaccess.h @@ -8,2 +8,11 @@ +/** + * 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> { @@ -13,9 +22,9 @@ public: - /** 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; diff --git a/libopie/pim/odatebookaccessbackend.h b/libopie/pim/odatebookaccessbackend.h index eb6e8fb..86ff298 100644 --- a/libopie/pim/odatebookaccessbackend.h +++ b/libopie/pim/odatebookaccessbackend.h @@ -8,2 +8,7 @@ +/** + * This class is the interface to the storage of Events. + * @see OPimAccessBackend + * + */ class ODateBookAccessBackend : public OPimAccessBackend<OEvent> { @@ -11,2 +16,6 @@ public: typedef int UID; + + /** + * c'tor without parameter + */ ODateBookAccessBackend(); @@ -14,4 +23,21 @@ public: + /** + * 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; @@ -19,6 +45,11 @@ public: /** - * 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; @@ -26,3 +57,13 @@ public: /* 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 ); diff --git a/libopie/pim/odatebookaccessbackend_xml.h b/libopie/pim/odatebookaccessbackend_xml.h index 563c31f..7848f7c 100644 --- a/libopie/pim/odatebookaccessbackend_xml.h +++ b/libopie/pim/odatebookaccessbackend_xml.h @@ -7,2 +7,8 @@ +/** + * This is the default XML implementation for DateBoook XML storage + * It fully implements the interface + * @see ODateBookAccessBackend + * @see OPimAccessBackend + */ class ODateBookAccessBackend_XML : public ODateBookAccessBackend { diff --git a/libopie/pim/oevent.h b/libopie/pim/oevent.h index 585515c..57d32d0 100644 --- a/libopie/pim/oevent.h +++ b/libopie/pim/oevent.h @@ -32,2 +32,8 @@ 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 { @@ -35,2 +41,5 @@ public: typedef QValueList<OEvent> ValueList; + /** + * RecordFields contain possible attributes + */ enum RecordFields { @@ -51,3 +60,10 @@ public: + /** + * Start with an Empty OEvent. UID == 0 means that it is empty + */ OEvent(int uid = 0); + + /** + * copy c'tor + */ OEvent( const OEvent& ); @@ -146,3 +162,2 @@ private: */ - class OEffectiveEvent { 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 @@ -18,2 +18,7 @@ * $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 @@ -65,3 +70,17 @@ - +/** + * 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> @@ -78,2 +97,7 @@ class OBackendFactory + /** + * 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 ){ 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 @@ -21,2 +21,7 @@ * $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 @@ -46,4 +51,14 @@ -#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> { @@ -54,3 +69,4 @@ class OContactAccessBackend: public OPimAccessBackend<OContact> { - /** 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. @@ -70,3 +86,4 @@ class OContactAccessBackend: public OPimAccessBackend<OContact> { - /** Return all possible settings. + /** + * Return all possible settings. * @return All settings provided by the current backend @@ -76,3 +93,4 @@ class OContactAccessBackend: public OPimAccessBackend<OContact> { - /** Check whether settings are correct. + /** + * Check whether settings are correct. * @return <i>true</i> if the given settings are correct and possible. @@ -81,3 +99,7 @@ class OContactAccessBackend: public OPimAccessBackend<OContact> { - 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; 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 @@ -19,2 +19,7 @@ * $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 @@ -78,3 +83,3 @@ -OContactAccessBackend_VCard::OContactAccessBackend_VCard ( QString , QString filename ): +OContactAccessBackend_VCard::OContactAccessBackend_VCard ( const QString& , const QString& filename ): m_dirty( false ), 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 @@ -19,2 +19,7 @@ * $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 @@ -49,5 +54,10 @@ 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 ); @@ -61,3 +71,3 @@ class OContactAccessBackend_VCard : public OContactAccessBackend { bool replace ( const OContact& contact ); - + OContact find ( int uid ) const; @@ -71,3 +81,3 @@ class OContactAccessBackend_VCard : public OContactAccessBackend { bool wasChangedExternally(); - + private: @@ -79,3 +89,3 @@ private: VObject *safeAddProp( VObject* o, const char* prop); - + bool m_dirty : 1; 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 @@ -19,2 +19,7 @@ * $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 @@ -95,3 +100,3 @@ #include <qmap.h> -#include <qdatetime.h> +#include <qdatetime.h> @@ -109,3 +114,3 @@ using namespace Opie; -OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString filename ): +OContactAccessBackend_XML::OContactAccessBackend_XML ( const QString& appname, const QString& filename ): m_changed( false ) @@ -118,3 +123,3 @@ OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString m_appName = appname; - + /* Set journalfile name ... */ @@ -122,3 +127,3 @@ OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString m_journalName +="/.abjournal" + appname; - + /* Expecting to access the default filename if nothing else is set */ @@ -128,3 +133,3 @@ OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString m_fileName = filename; - + /* Load Database now */ @@ -133,8 +138,8 @@ OContactAccessBackend_XML::OContactAccessBackend_XML ( QString appname, QString -bool OContactAccessBackend_XML::save() +bool OContactAccessBackend_XML::save() { - + if ( !m_changed ) return true; - + QString strNewFile = m_fileName + ".new"; @@ -143,3 +148,3 @@ bool OContactAccessBackend_XML::save() return false; - + int total_written; @@ -176,3 +181,3 @@ bool OContactAccessBackend_XML::save() out += " </Contacts>\n</AddressBook>\n"; - + // Write Footer @@ -186,3 +191,3 @@ bool OContactAccessBackend_XML::save() f.close(); - + // move the file over, I'm just going to use the system call @@ -195,6 +200,6 @@ bool OContactAccessBackend_XML::save() } - + /* The journalfile should be removed now... */ removeJournal(); - + m_changed = false; @@ -203,3 +208,3 @@ bool OContactAccessBackend_XML::save() -bool OContactAccessBackend_XML::load () +bool OContactAccessBackend_XML::load () { @@ -207,3 +212,3 @@ bool OContactAccessBackend_XML::load () m_uidToContact.clear(); - + /* Load XML-File and journal if it exists */ @@ -218,3 +223,3 @@ bool OContactAccessBackend_XML::load () load (m_journalName, true); - + return true; @@ -222,3 +227,3 @@ bool OContactAccessBackend_XML::load () -void OContactAccessBackend_XML::clear () +void OContactAccessBackend_XML::clear () { @@ -233,5 +238,5 @@ bool OContactAccessBackend_XML::wasChangedExternally() QFileInfo fi( m_fileName ); - + QDateTime lastmod = fi.lastModified (); - + return (lastmod != m_readtime); @@ -239,7 +244,7 @@ bool OContactAccessBackend_XML::wasChangedExternally() -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 ); @@ -248,3 +253,3 @@ QArray<int> OContactAccessBackend_XML::allRecords() const } - + return ( uid_list ); @@ -255,3 +260,3 @@ OContact OContactAccessBackend_XML::find ( int uid ) const OContact foundContact; //Create empty contact - + OContact* found = m_uidToContact.find( QString().setNum( uid ) ); @@ -261,3 +266,3 @@ OContact OContactAccessBackend_XML::find ( int uid ) const } - + return ( foundContact ); @@ -265,6 +270,6 @@ OContact OContactAccessBackend_XML::find ( int uid ) const -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() ); @@ -272,3 +277,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i uint arraycounter = 0; - + for( ; it.current(); ++it ){ @@ -292,3 +297,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i } - + if ( queryDate->isValid() ){ @@ -298,3 +303,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i allcorrect = false; - } + } if ( settings & OContactAccess::DateMonth ){ @@ -302,3 +307,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i allcorrect = false; - } + } if ( settings & OContactAccess::DateDay ){ @@ -306,3 +311,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i allcorrect = false; - } + } if ( settings & OContactAccess::DateDiff ) { @@ -311,3 +316,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i // will take this date instead of - // the current one.. + // the current one.. if ( !d.date().isValid() ) @@ -319,8 +324,8 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i // 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() ); @@ -330,8 +335,8 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i // ( 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 ) ) ){ @@ -347,3 +352,3 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i } - + delete queryDate; @@ -361,5 +366,5 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i | OContactAccess::DateDay - | OContactAccess::MatchOne + | OContactAccess::MatchOne ) ){ - + case OContactAccess::RegExp:{ @@ -399,6 +404,6 @@ QArray<int> OContactAccessBackend_XML::queryByExample ( const OContact &query, i } - + // Shrink to fit.. m_currentQuery.resize(arraycounter); - + return m_currentQuery; @@ -411,3 +416,3 @@ QArray<int> OContactAccessBackend_XML::matchRegexp( const QRegExp &r ) const uint arraycounter = 0; - + for( ; it.current(); ++it ){ @@ -416,3 +421,3 @@ QArray<int> OContactAccessBackend_XML::matchRegexp( const QRegExp &r ) const } - + } @@ -420,3 +425,3 @@ QArray<int> OContactAccessBackend_XML::matchRegexp( const QRegExp &r ) const m_currentQuery.resize(arraycounter); - + return m_currentQuery; @@ -429,3 +434,3 @@ const uint OContactAccessBackend_XML::querySettings() | OContactAccess::RegExp - | OContactAccess::ExactMatch + | OContactAccess::ExactMatch | OContactAccess::DateDiff @@ -439,3 +444,3 @@ 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. @@ -443,6 +448,6 @@ bool OContactAccessBackend_XML::hasQuerySettings (uint querySettings) const */ - - if ( querySettings == OContactAccess::IgnoreCase ) + + if ( querySettings == OContactAccess::IgnoreCase ) return false; - + switch ( querySettings & ~( OContactAccess::IgnoreCase @@ -452,3 +457,3 @@ bool OContactAccessBackend_XML::hasQuerySettings (uint querySettings) const | OContactAccess::DateDay - ) + ) ){ @@ -465,4 +470,4 @@ bool OContactAccessBackend_XML::hasQuerySettings (uint querySettings) const -// 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 ) { @@ -471,4 +476,4 @@ QArray<int> OContactAccessBackend_XML::sorted( bool asc, int , int , int ) 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.. @@ -480,3 +485,3 @@ QArray<int> OContactAccessBackend_XML::sorted( bool asc, int , int , int ) names.sort(); - + int i = 0; @@ -489,5 +494,5 @@ QArray<int> OContactAccessBackend_XML::sorted( bool asc, int , int , int ) } - + return m_currentQuery; - + } @@ -499,5 +504,5 @@ bool OContactAccessBackend_XML::add ( const OContact &newcontact ) addContact_p( newcontact ); - + m_changed = true; - + return true; @@ -508,3 +513,3 @@ bool OContactAccessBackend_XML::replace ( const OContact &contact ) m_changed = true; - + OContact* found = m_uidToContact.find ( QString().setNum( contact.uid() ) ); @@ -530,3 +535,3 @@ bool OContactAccessBackend_XML::remove ( int uid ) m_changed = true; - + OContact* found = m_uidToContact.find ( QString().setNum( uid ) ); @@ -557,5 +562,5 @@ void OContactAccessBackend_XML::addContact_p( const OContact &newcontact ) /* 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 @@ -567,6 +572,6 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) } - + const int JOURNALACTION = Qtopia::Notes + 1; const int JOURNALROW = JOURNALACTION + 1; - + bool foundAction = false; @@ -578,3 +583,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) QAsciiDict<int> dict( 47 ); - + dict.setAutoDelete( TRUE ); @@ -625,5 +630,5 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) dict.insert( "actionrow", new int(JOURNALROW) ); - + //qWarning( "OContactDefaultBackEnd::loading %s", filename.latin1() ); - + XMLElement *root = XMLElement::load( filename ); @@ -636,3 +641,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) element = element->firstChild(); - + /* Search Tag "Contacts" which is the parent of all Contacts */ @@ -663,3 +668,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) foundAction = false; - + XMLElement::AttributeMap aMap = element->attributes(); @@ -670,3 +675,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) // qWarning ("Read Attribute: %s=%s", it.key().latin1(),it.data().latin1()); - + int *find = dict[ it.key() ]; @@ -679,3 +684,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) } - + /* Check if special conversion is needed and add attribute @@ -707,3 +712,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) OContact contact( contactMap ); - + for (customIt = customMap.begin(); customIt != customMap.end(); ++customIt ) { @@ -711,3 +716,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) } - + if (foundAction){ @@ -736,3 +741,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) } - + /* Move to next element */ @@ -750,3 +755,3 @@ bool OContactAccessBackend_XML::load( const QString filename, bool isJournal ) void OContactAccessBackend_XML::updateJournal( const OContact& cnt, - journal_action action ) + journal_action action ) { @@ -756,6 +761,6 @@ void OContactAccessBackend_XML::updateJournal( const OContact& cnt, return; - + QString buf; QCString str; - + // if the file was created, we have to set the Tag "<CONTACTS>" to @@ -768,3 +773,3 @@ void OContactAccessBackend_XML::updateJournal( const OContact& cnt, } - + buf = "<Contact "; 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 @@ -19,2 +19,7 @@ * $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 @@ -86,8 +91,13 @@ /* 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 (); @@ -95,9 +105,9 @@ class OContactAccessBackend_XML : public OContactAccessBackend { 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() ); @@ -105,16 +115,16 @@ class OContactAccessBackend_XML : public OContactAccessBackend { 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: @@ -124,10 +134,10 @@ class OContactAccessBackend_XML : public OContactAccessBackend { 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: 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 @@ -8,2 +8,7 @@ +/** + * This class is the interface to the storage of Events. + * @see OPimAccessBackend + * + */ class ODateBookAccessBackend : public OPimAccessBackend<OEvent> { @@ -11,2 +16,6 @@ public: typedef int UID; + + /** + * c'tor without parameter + */ ODateBookAccessBackend(); @@ -14,4 +23,21 @@ public: + /** + * 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; @@ -19,6 +45,11 @@ public: /** - * 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; @@ -26,3 +57,13 @@ public: /* 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 ); 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 @@ -7,2 +7,8 @@ +/** + * This is the default XML implementation for DateBoook XML storage + * It fully implements the interface + * @see ODateBookAccessBackend + * @see OPimAccessBackend + */ class ODateBookAccessBackend_XML : public ODateBookAccessBackend { 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 @@ -19,2 +19,7 @@ * $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 @@ -57,5 +62,9 @@ -/** 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 @@ -67,3 +76,4 @@ class OContactAccess: public QObject, public OPimAccessTemplate<OContact> public: - /** Create Database with contacts (addressbook). + /** + * Create Database with contacts (addressbook). * @param appname Name of application which wants access to the database @@ -101,3 +111,3 @@ class OContactAccess: public QObject, public OPimAccessTemplate<OContact> - + ORecordList<OContact> matchRegexp( const QRegExp &r )const; 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 @@ -3,2 +3,9 @@ +/** + * 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 ) @@ -14,2 +21,6 @@ ODateBookAccess::~ODateBookAccess() { } + +/** + * @return all events available + */ ODateBookAccess::List ODateBookAccess::rawEvents()const { @@ -20,2 +31,6 @@ ODateBookAccess::List ODateBookAccess::rawEvents()const { } + +/** + * @return all repeating events + */ ODateBookAccess::List ODateBookAccess::rawRepeats()const { @@ -26,2 +41,6 @@ ODateBookAccess::List ODateBookAccess::rawRepeats()const { } + +/** + * @return all non repeating events + */ ODateBookAccess::List ODateBookAccess::nonRepeats()const { @@ -32,2 +51,8 @@ ODateBookAccess::List ODateBookAccess::nonRepeats()const { } + +/** + * @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 ) { @@ -35,2 +60,5 @@ OEffectiveEvent::ValueList ODateBookAccess::effectiveEvents( const QDate& from, } +/** + * @return all events at a given datetime + */ OEffectiveEvent::ValueList ODateBookAccess::effectiveEvents( const QDateTime& 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 @@ -8,2 +8,11 @@ +/** + * 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> { @@ -13,9 +22,9 @@ public: - /** 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; 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 @@ -36,4 +36,11 @@ QPC_TEMPLATEEXTERN template class QPC_EXPORT QMap<int, QString>; -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 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 @@ -32,2 +32,8 @@ 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 { @@ -35,2 +41,5 @@ public: typedef QValueList<OEvent> ValueList; + /** + * RecordFields contain possible attributes + */ enum RecordFields { @@ -51,3 +60,10 @@ public: + /** + * Start with an Empty OEvent. UID == 0 means that it is empty + */ OEvent(int uid = 0); + + /** + * copy c'tor + */ OEvent( const OEvent& ); @@ -146,3 +162,2 @@ private: */ - class OEffectiveEvent { |