| -rw-r--r-- | libopie/pim/obackendfactory.h | 26 | ||||
| -rw-r--r-- | libopie/pim/ocontact.h | 7 | ||||
| -rw-r--r-- | libopie/pim/ocontactaccess.h | 14 | ||||
| -rw-r--r-- | libopie/pim/ocontactaccessbackend.h | 30 | ||||
| -rw-r--r-- | libopie/pim/ocontactaccessbackend_vcard.cpp | 7 | ||||
| -rw-r--r-- | libopie/pim/ocontactaccessbackend_vcard.h | 12 | ||||
| -rw-r--r-- | libopie/pim/ocontactaccessbackend_xml.cpp | 7 | ||||
| -rw-r--r-- | libopie/pim/ocontactaccessbackend_xml.h | 12 | ||||
| -rw-r--r-- | libopie/pim/odatebookaccess.cpp | 28 | ||||
| -rw-r--r-- | libopie/pim/odatebookaccess.h | 15 | ||||
| -rw-r--r-- | libopie/pim/odatebookaccessbackend.h | 45 | ||||
| -rw-r--r-- | libopie/pim/odatebookaccessbackend_xml.h | 6 | ||||
| -rw-r--r-- | libopie/pim/oevent.h | 17 |
13 files changed, 209 insertions, 17 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 @@ -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/libopie/pim/ocontact.h b/libopie/pim/ocontact.h index 1fd1c75..25fa0e7 100644 --- a/libopie/pim/ocontact.h +++ b/libopie/pim/ocontact.h @@ -33,12 +33,19 @@ QPC_TEMPLATEEXTERN template class QPC_EXPORT QMap<int, QString>; // MOC_SKIP_END #endif 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/libopie/pim/ocontactaccess.h b/libopie/pim/ocontactaccess.h index 32b2dcb..d7ceaf2 100644 --- a/libopie/pim/ocontactaccess.h +++ b/libopie/pim/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. 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 @@ -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; + /** + * 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/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 @@ -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/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 @@ -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,15 +49,20 @@ #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 (); 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 @@ -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 .. @@ -104,13 +109,13 @@ #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 ); 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 @@ -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,15 +86,20 @@ #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 (); 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 @@ -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/libopie/pim/odatebookaccess.h b/libopie/pim/odatebookaccess.h index 7047039..7c7a63f 100644 --- a/libopie/pim/odatebookaccess.h +++ b/libopie/pim/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/libopie/pim/odatebookaccessbackend.h b/libopie/pim/odatebookaccessbackend.h index eb6e8fb..86ff298 100644 --- a/libopie/pim/odatebookaccessbackend.h +++ b/libopie/pim/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/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 @@ -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/libopie/pim/oevent.h b/libopie/pim/oevent.h index 585515c..57d32d0 100644 --- a/libopie/pim/oevent.h +++ b/libopie/pim/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, |