-rw-r--r-- | libopie2/opiepim/ChangeLog | 3 | ||||
-rw-r--r-- | libopie2/opiepim/core/ocontactaccess.h | 2 | ||||
-rw-r--r-- | libopie2/opiepim/core/opimaccesstemplate.h | 76 | ||||
-rw-r--r-- | libopie2/opiepim/core/opimtemplatebase.h | 0 |
4 files changed, 73 insertions, 8 deletions
diff --git a/libopie2/opiepim/ChangeLog b/libopie2/opiepim/ChangeLog index dd57259..564e92a 100644 --- a/libopie2/opiepim/ChangeLog +++ b/libopie2/opiepim/ChangeLog @@ -1,18 +1,21 @@ +2004-12-28 Stefan Eilers <stefan@eilers-online.net> + * Make improved query by example accessable via frontend + * Some API improvement 2004-11-23 Stefan Eilers <stefan@eilers-online.net> * Implement fast and full featured version of sorted() for addressbook * Implement generic queryByExample for all Addressboook backends. It allows incremental search. * Update of API Documentation 2004-11-18 Holger Freyther <freyther@handhelds.org> * Every Access can give a set of Occurrences for a period or a datetime * QueryByExample, Find, Sort can be generically accessed by OPimBase pointer interface * OPimBackendOccurrence gets split up to OPimOccurrences by OPimTemplateBase * Add safeCast to various OPimRecords * Kill memleak in OPimTodo * Add SortVector implementations for OPimTodo and OPimContact 2004-??-?? The Opie Team <opie@handhelds.org> * Implemented some important modifications to allow to use OPimRecords as it is, without have to cast them. This makes it possible to write applications which handling pim data in a generic manner (see opimconvertion tool) (eilers)
\ No newline at end of file diff --git a/libopie2/opiepim/core/ocontactaccess.h b/libopie2/opiepim/core/ocontactaccess.h index bd85b4e..5051321 100644 --- a/libopie2/opiepim/core/ocontactaccess.h +++ b/libopie2/opiepim/core/ocontactaccess.h @@ -1,177 +1,177 @@ /* This file is part of the Opie Project Copyright (C) The Main Author <main-author@whereever.org> =. Copyright (C) The Opie Team <opie-devel@handhelds.org> .=l. .>+-= _;:, .> :=|. This program is free software; you can .> <`_, > . <= redistribute it and/or modify it under :`=1 )Y*s>-.-- : the terms of the GNU Library General Public .="- .-=="i, .._ License as published by the Free Software - . .-<_> .<> Foundation; either version 2 of the License, ._= =} : or (at your option) any later version. .%`+i> _;_. .i_,=:_. -<s. This program is distributed in the hope that + . -:. = it will be useful, but WITHOUT ANY WARRANTY; : .. .:, . . . without even the implied warranty of =_ + =;=|` MERCHANTABILITY or FITNESS FOR A _.=:. : :=>`: PARTICULAR PURPOSE. See the GNU ..}^=.= = ; Library General Public License for more ++= -. .` .: details. : = ...= . :.=- -. .:....=;==+<; You should have received a copy of the GNU -_. . . )=. = Library General Public License along with -- :-=` this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ /* * ===================================================================== * ToDo: Define enum for query settings * ===================================================================== */ #ifndef _OCONTACTACCESS_H #define _OCONTACTACCESS_H #include <qobject.h> #include <qpe/qcopenvelope_qws.h> #include <qvaluelist.h> #include <qfileinfo.h> #include <opie2/opimcontact.h> #include <opie2/ocontactaccessbackend.h> #include <opie2/opimaccesstemplate.h> namespace Opie { /** * 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. * @author Stefan Eilers, Holger Freyther * @see OPimAccessTemplate */ class OPimContactAccess: public QObject, public OPimAccessTemplate<OPimContact> { Q_OBJECT public: /** * Filter for sorted() * @see SortFilterBase in OPimBase */ enum SortFilter { /** Don't return entries who don't have children */ DoNotShowWithoutChildren = FilterCustom<<1, /** Don't return entries who don't have an anniversary */ DoNotShowWithoutAnniversary = FilterCustom<<2, /** Don't return entries who don't have a birthday */ DoNotShowWithoutBirthday = FilterCustom<<3, /** Don't return entries who don't have a home address */ DoNotShowWithoutHomeAddress = FilterCustom<<4, /** Don't return entries who don't have a business address */ DoNotShowWithoutBusinessAddress = FilterCustom<<5, /** Don't return entries which hava any category */ DoNotShowWithCategory = FilterCustom << 6 }; /** * Sort order for sorted() * @see SortOrderBase in OPimBase */ enum SortOrder { SortTitle = SortCustom, SortFirstName, SortMiddleName, SortLastName, SortSuffix, SortEmail, SortNickname, SortFileAsName, SortAnniversary, SortBirthday, SortGender }; /** * 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. * @param handlesync If <b>true</b> the database stores the current state * automatically if it receives the signals <i>flush()</i> and <i>reload()</i> * which are used before and after synchronisation. If the application wants * to react itself, it should be disabled by setting it to <b>false</b> * @see OPimContactAccessBackend */ OPimContactAccess (const QString appname, const QString filename = 0l, OPimContactAccessBackend* backend = 0l, bool handlesync = true); ~OPimContactAccess (); /** * Return all possible settings for queryByExample(). * @return All settings provided by the current backend * (i.e.: WildCards & IgnoreCase) - * @see QuerySettings in OPimBase for details of the parameter + * @see QuerySettings in OPimBase for details of the parameter, queryByExample() */ const uint querySettings(); /** * Check whether settings are correct for queryByExample(). * @return <i>true</i> if the given settings are correct and possible. * @see QuerySettings in OPimBase for details of the parameter */ bool hasQuerySettings ( int querySettings ) const; /** * if the resource was changed externally. * You should use the signal instead of polling possible changes ! */ bool wasChangedExternally()const; /** Save contacts database. * Save is more a "commit". After calling this function, all changes are public available. * @return true if successful */ bool save(); /** * Return identification of used records */ int rtti() const; signals: /* Signal is emitted if the database was changed. Therefore * we may need to reload to stay consistent. * @param which Pointer to the database who created this event. This pointer * is useful if an application has to handle multiple databases at the same time. * @see reload() */ void signalChanged ( const OPimContactAccess *which ); private: OPimContactAccessBackend *m_backEnd; bool m_loading:1; private slots: void copMessage( const QCString &msg, const QByteArray &data ); private: class Private; Private *d; }; } #endif diff --git a/libopie2/opiepim/core/opimaccesstemplate.h b/libopie2/opiepim/core/opimaccesstemplate.h index 073d5f9..3875f09 100644 --- a/libopie2/opiepim/core/opimaccesstemplate.h +++ b/libopie2/opiepim/core/opimaccesstemplate.h @@ -1,477 +1,539 @@ /* This file is part of the Opie Project Copyright (C) Holger Freyther <zecke@handhelds.org> Copyright (C) Stefan Eilers <eilers.stefan@epost.de> =. Copyright (C) The Opie Team <opie-devel@handhelds.org> .=l. .>+-= _;:, .> :=|. This program is free software; you can .> <`_, > . <= redistribute it and/or modify it under :`=1 )Y*s>-.-- : the terms of the GNU Library General Public .="- .-=="i, .._ License as published by the Free Software - . .-<_> .<> Foundation; either version 2 of the License, ._= =} : or (at your option) any later version. .%`+i> _;_. .i_,=:_. -<s. This program is distributed in the hope that + . -:. = it will be useful, but WITHOUT ANY WARRANTY; : .. .:, . . . without even the implied warranty of =_ + =;=|` MERCHANTABILITY or FITNESS FOR A _.=:. : :=>`: PARTICULAR PURPOSE. See the GNU ..}^=.= = ; Library General Public License for more ++= -. .` .: details. : = ...= . :.=- -. .:....=;==+<; You should have received a copy of the GNU -_. . . )=. = Library General Public License along with -- :-=` this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ #ifndef OPIE_PIM_ACCESS_TEMPLATE_H #define OPIE_PIM_ACCESS_TEMPLATE_H /* OPIE */ #include <opie2/opimrecord.h> #include <opie2/opimaccessbackend.h> #include <opie2/opimrecordlist.h> #include <opie2/opimtemplatebase.h> #include <opie2/odebug.h> /* QT */ #include <qarray.h> #include <qdatetime.h> namespace Opie { class OPimAccessTemplatePrivate; /** * Thats the frontend to our OPIE PIM * Library. Either you want to use it's * interface or you want to implement * your own Access lib * Just create a OPimRecord and inherit from * the templates */ template <class T = OPimRecord > class OPimAccessTemplate : public OTemplateBase<T> { public: /** * */ enum Access { Random = 0, SortedAccess }; typedef OPimRecordList<T> List; typedef OPimAccessBackend<T> BackEnd; typedef OPimCache<T> Cache; //@{ OPimAccessTemplate( BackEnd* end); virtual ~OPimAccessTemplate(); //@} //@{ bool load(); virtual bool reload(); bool save(); void clear() ; //@} bool wasChangedExternally()const; //@{ virtual List allRecords()const; virtual List matchRegexp( const QRegExp &r ) const; - virtual List queryByExample( const T& t, int querySettings, const QDateTime& d = QDateTime() ); + + /** + * Query by example search interface. + * "Query by Example" provides a very powerful search engine. Use the query object + * (this may be a contact, a todo or databook event) + * as a search mask which is converted into a query regarding the querySettings. If a time period is needed + * (as for OpimBase::DateDiff), you have to use the date/time in the query object and the endperiod (the last parameter). + * @see QuerySettings in class OPimBase + * @param query The object which contains the query set + * @param querySettings This parameter defines what should be searched and how the query should be interpreted + * @param endperiod Defines the end of a period for some special queries. + */ + virtual List queryByExample( const T& query, int querySettings, const QDateTime& endperiod = QDateTime() ); + + /** + * Generic query by example search interface. This is a special version which handles generic OPimRecord types. They are converted + * automatically into the right datatype. + * "Query by Example" provides a very powerful search engine. Use the query object (this may be a contact, a todo or databook event) + * as a search mask which is converted into a query regarding the querySettings. If a time period is needed + * (as for OpimBase::DateDiff), you have to use the date/time in the query object and the endperiod (the last parameter). + * @see QuerySettings in class OPimBase + * @param query The object which contains the query set + * @param querySettings This parameter defines what should be searched and how the query should be interpreted + * @param endperiod Defines the end of a period for some special queries. + */ + virtual List queryByExample( const OPimRecord* query, int querySettings, const QDateTime& endperiod = QDateTime() ); + /** + * Incremental query by example search interface. Providing incremental search, this one provides the feature + * to search in a list of records which may be returned by an other search. + * "Query by Example" provides a very powerful search engine. Use the query object (this may be a contact, a todo or databook event) + * as a search mask which is converted into a query regarding the querySettings. If a time period is needed + * (as for OpimBase::DateDiff), you have to use the date/time in the query object and the endperiod (the last parameter). + * @see QuerySettings in class OPimBase + * @param uidlist List of uid's which should be incorporated into the next search + * @param query The object which contains the query set + * @param querySettings This parameter defines what should be searched and how the query should be interpreted + * @param endperiod Defines the end of a period for some special queries. + */ + virtual List queryByExample( const OPimAccessTemplate::List& uidlist, const T& query, int querySettings, + const QDateTime& endperiod = QDateTime() ); + virtual T find( UID uid )const; virtual T find( UID uid, const QArray<int>&, uint current, typename OTemplateBase<T>::CacheDirection dir = OTemplateBase<T>::Forward )const; //@} /** * Get sorted lists.. * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params: * @param list of UID's received by allRecords() or others... * @param sortOrder Setting the sort order defined by enum SortOrder * @param ascending Sort in ascending order if true, otherwise descending * @param sortFilter Setting the sort filter defined by enum SortFilter * @param cat number of category. */ virtual List sorted( const List& list, bool ascending, int sortOrder, int sortFilter, int cat )const; /** * Get sorted lists.. * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params: * @param list of UID's received by allRecords() or others... * @param sortOrder Setting the sort order defined by enum SortOrder * @param ascending Sort in ascending order if true, otherwise descending * @param sortFilter Setting the sort filter defined by enum SortFilter * @param cats List of categories. */ virtual List sorted( const List& list, bool ascending, int sortOrder, int sortFilter, const QArray<UID>& cats )const; /** * Get sorted lists.. * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params: * @param ascending Sort in ascending order if true, otherwise descending * @param sortOrder Setting the sort order defined by enum SortOrder * @param sortFilter Setting the sort filter defined by enum SortFilter * @param cat number of category. */ virtual List sorted( bool ascending, int sortOrder, int sortFilter, int cat )const; /** * Get sorted lists.. * @see OPimContactAccess, OPimTodoAccess and ODateBookAccess regarding more info for the following params: * @param ascending Sort in ascending order if true, otherwise descending * @param sortOrder Setting the sort order defined by enum SortOrder * @param sortFilter Setting the sort filter defined by enum SortFilter * @param cats List of categories. */ virtual List sorted( bool ascending, int sortOrder, int sortFilter, const QArray<UID>& cats )const; /** * (Re)Implementation */ //@{ UIDArray matchRegexpSimple( const QRegExp& r )const; UIDArray queryByExampleSimple( const OPimRecord*, int, const QDateTime& )const; UIDArray sortedSimple( const UIDArray&, bool asc, int sortOrder, int sortFilter, int cat )const; UIDArray sortedSimple( const UIDArray&, bool asc, int sortOrder, int sortFilter, const QArray<int>& )const; UIDArray sortedSimple( bool ascending, int sortOrder, int sortFilter, int cat )const; UIDArray sortedSimple( bool ascending, int sortOrder, int sortFilter, const QArray<int>& )const; OPimOccurrence::List occurrences( const QDate& start, const QDate& end )const; OPimOccurrence::List occurrences( const QDateTime& dt )const; //@} //@{ virtual bool add( const T& t ) ; bool add( const OPimRecord& ); bool add( const OPimRecord* ); virtual bool remove( const T& t ); bool remove( UID uid ); bool remove( const OPimRecord& ); virtual bool replace( const T& t) ; //@} void setReadAhead( uint count ); void cache( const T& )const; void setSaneCacheSize( int ); QArray<UID> records()const; protected: /** * invalidate the cache */ void invalidateCache(); void setBackEnd( BackEnd* end ); /** * returns the backend */ BackEnd* backEnd(); BackEnd* m_backEnd; Cache m_cache; private: OPimAccessTemplatePrivate *d; }; /** * c'tor BackEnd * enum Access a small hint on how to handle the backend */ template <class T> OPimAccessTemplate<T>::OPimAccessTemplate( BackEnd* end ) : OTemplateBase<T>(), m_backEnd( end ) { if (end ) end->setFrontend( this ); } template <class T> OPimAccessTemplate<T>::~OPimAccessTemplate() { delete m_backEnd; } /** * load from the backend */ template <class T> bool OPimAccessTemplate<T>::load() { invalidateCache(); return m_backEnd->load(); } /** Reload database. * You should execute this function if the external database * was changed. * This function will load the external database and afterwards * rejoin the local changes. Therefore the local database will be set consistent. */ template <class T> bool OPimAccessTemplate<T>::reload() { invalidateCache(); return m_backEnd->reload(); } /** * Save contacts database. * Save is more a "commit". After calling this function, all changes are public available. * @return true if successful */ template <class T> bool OPimAccessTemplate<T>::save() { return m_backEnd->save(); } /** * return a List of records * you can iterate over them */ template <class T> typename OPimAccessTemplate<T>::List OPimAccessTemplate<T>::allRecords()const { QArray<int> ints = m_backEnd->allRecords(); List lis(ints, this ); return lis; } /** * return a List of records * that match the regex */ template <class T> typename OPimAccessTemplate<T>::List OPimAccessTemplate<T>::matchRegexp( const QRegExp &r )const { QArray<int> ints = m_backEnd->matchRegexp( r ); List lis(ints, this ); return lis; } /** * find the OPimRecord uid */ template <class T> QArray<int> OPimAccessTemplate<T>::records()const { return m_backEnd->allRecords(); } -/** - * queryByExample. - * @see otodoaccess, ocontactaccess - */ template <class T> typename OPimAccessTemplate<T>::List OPimAccessTemplate<T>::queryByExample( const T& t, int settings, const QDateTime& d ) { QArray<int> ints = m_backEnd->queryByExample( t, settings, d ); - List lis(ints, this ); - return lis; + List list(ints, this ); + return list; } template <class T> +typename OPimAccessTemplate<T>::List +OPimAccessTemplate<T>::queryByExample( const OPimRecord* t, int settings, const QDateTime& d ) { + T tempInstance; + + if ( t->rtti() == tempInstance.rtti() ) { + QArray<int> ints = m_backEnd->queryByExample( t, settings, d ); + List list( ints, this ); + return list; + } else { + owarn << "Query not possible: Objecttype mismatch" << oendl; + } + + return List(); +} + +template <class T> +typename OPimAccessTemplate<T>::List +OPimAccessTemplate<T>::queryByExample( const OPimAccessTemplate::List& uidlist, const T& t, int settings, const QDateTime& d ) { + QArray<int> ints = m_backEnd->queryByExample( uidlist.uids(), t, settings, d ); + + List list( ints, this ); + return list; +} + + +template <class T> T OPimAccessTemplate<T>::find( UID uid ) const{ // First search in cache.. if ( m_cache.contains( uid ) ) return m_cache.find( uid ); T t = m_backEnd->find( uid ); cache( t ); return t; } /** * read ahead cache find method ;) */ template <class T> T OPimAccessTemplate<T>::find( UID uid, const QArray<int>& ar, uint current, typename OTemplateBase<T>::CacheDirection dir )const { /* * better do T.isEmpty() * after a find this way we would * avoid two finds in QCache... */ if (m_cache.contains( uid ) ) return m_cache.find( uid ); T t = m_backEnd->find( uid, ar, current, dir ); cache( t ); return t; } /** * clears the backend and invalidates the backend */ template <class T> void OPimAccessTemplate<T>::clear() { invalidateCache(); m_backEnd->clear(); } /** * add T to the backend * @param t The item to add. * @return <i>true</i> if added successfully. */ template <class T> bool OPimAccessTemplate<T>::add( const T& t ) { cache( t ); return m_backEnd->add( t ); } template <class T> bool OPimAccessTemplate<T>::add( const OPimRecord& rec ) { /* same type */ T tempInstance; if ( rec.rtti() == tempInstance.rtti() ) { const T& t = static_cast<const T&>(rec); return add(t); } else { owarn << "Adding not possible: Objecttype mismatch" << oendl; } return false; } /** * Add an Opie PimRecord. * Info: Take this if you are working with OPimRecords and you need to add it into any database. * But take care that the accessing database is compatible to the real type of OPimRecord !! * Otherwise this access will be rejected ! */ template <class T> bool OPimAccessTemplate<T>::add( const OPimRecord* rec) { /* same type, but pointer */ T tempInstance; if ( rec -> rtti() == tempInstance.rtti() ) { const T* t = static_cast<const T*>(rec); return add( *t ); } else { owarn << "Adding not possible: Objecttype mismatch" << oendl; } return false; } /** * remove T from the backend * @param t The item to remove * @return <i>true</i> if successful. */ template <class T> bool OPimAccessTemplate<T>::remove( const T& t ) { return remove( t.uid() ); } /** * remove the OPimRecord with uid * @param uid The ID of the item to remove * @return <i>true</i> if successful. */ template <class T> bool OPimAccessTemplate<T>::remove( UID uid ) { m_cache.remove( uid ); return m_backEnd->remove( uid ); } template <class T> bool OPimAccessTemplate<T>::remove( const OPimRecord& rec) { return remove( rec.uid() ); } /** * replace T from backend * @param t The item to replace * @return <i>true</i> if successful. */ template <class T> bool OPimAccessTemplate<T>::replace( const T& t ) { m_cache.replace( t ); return m_backEnd->replace( t ); } /** * @internal */ template <class T> void OPimAccessTemplate<T>::invalidateCache() { m_cache.invalidate(); } template <class T> typename OPimAccessTemplate<T>::BackEnd* OPimAccessTemplate<T>::backEnd() { return m_backEnd; } /** * if the resource was changed externally * You should use the signal handling instead of polling possible changes ! * zecke: Do you implement a signal for otodoaccess ? */ template <class T> bool OPimAccessTemplate<T>::wasChangedExternally()const { return false; } template <class T> void OPimAccessTemplate<T>::setBackEnd( BackEnd* end ) { m_backEnd = end; if (m_backEnd ) m_backEnd->setFrontend( this ); } template <class T> void OPimAccessTemplate<T>::cache( const T& t ) const{ /* hacky we need to work around the const*/ ((OPimAccessTemplate<T>*)this)->m_cache.add( t ); } template <class T> void OPimAccessTemplate<T>::setSaneCacheSize( int size ) { m_cache.setSize( size ); } template <class T> void OPimAccessTemplate<T>::setReadAhead( uint count ) { m_backEnd->setReadAhead( count ); } template <class T> typename OPimAccessTemplate<T>::List OPimAccessTemplate<T>::sorted( const OPimAccessTemplate::List& lst, bool ascending, int sortOrder, int sortFilter, int cat )const { QArray<int> cats( 1 ); cats[0] = cat; UIDArray ints = m_backEnd->sorted( lst.uids(), ascending, sortOrder, sortFilter, cats ); return List(ints, this); } template<class T> typename OPimAccessTemplate<T>::List OPimAccessTemplate<T>::sorted( const OPimAccessTemplate::List& lst, bool ascending, int sortOrder, int sortFilter, const QArray<UID>& cats )const { UIDArray ints = m_backEnd->sorted( lst.uids(), ascending, sortOrder, sortFilter, cats ); return List(ints, this); } template<class T> typename OPimAccessTemplate<T>::List OPimAccessTemplate<T>::sorted( bool ascending, int sortOrder, int sortFilter, int cat )const { QArray<int> cats( 1 ); cats[0] = cat; UIDArray ints = m_backEnd->sorted( ascending, sortOrder, sortFilter, cats ); return List(ints, this); } diff --git a/libopie2/opiepim/core/opimtemplatebase.h b/libopie2/opiepim/core/opimtemplatebase.h index c8abab4..075e573 100644 --- a/libopie2/opiepim/core/opimtemplatebase.h +++ b/libopie2/opiepim/core/opimtemplatebase.h |