summaryrefslogtreecommitdiff
Side-by-side diff
Diffstat (more/less context) (show whitespace changes)
-rw-r--r--libopie2/opiepim/ChangeLog3
-rw-r--r--libopie2/opiepim/core/ocontactaccess.h2
-rw-r--r--libopie2/opiepim/core/opimaccesstemplate.h76
-rw-r--r--libopie2/opiepim/core/opimtemplatebase.h0
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