summaryrefslogtreecommitdiff
Side-by-side diff
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--development/pim/pim_howto/pim_howto.lyx238
1 files changed, 218 insertions, 20 deletions
diff --git a/development/pim/pim_howto/pim_howto.lyx b/development/pim/pim_howto/pim_howto.lyx
index 2b08be8..4571996 100644
--- a/development/pim/pim_howto/pim_howto.lyx
+++ b/development/pim/pim_howto/pim_howto.lyx
@@ -86,93 +86,93 @@ How to use the Opie-Pim API without getting tired!
\layout Author
\family sans
Stefan Eilers
\layout Section*
\family sans
Abstract
\layout Standard
The Opie-Pim API provides a powerfull access interface to the PIM (Personal
Information Management) data which contains your contact information, the
dates in your calender tool (in this paper called datebook events) and
your todo events.
Beside providing full featured access to this information, it covers the
real management of this informantion - the access of the databases - from
the user.
\layout Standard
While starting to read the automatically generated API-documentation, the
user may be confused by a lot of unneccessary classes and details which
- makes the quick start not as easy as expected.
- Due to the fact that a user who just want to access data will not need
- most of the details, this paper should help to start to be confortable
- with the details he need to solve his problems.
+ makes the quick start not as easy as possible.
+ Due to the fact that a user will not need most of the details, this paper
+ should help to start to become confortable with those details he need to
+ solve his problems.
\layout Standard
\begin_inset LatexCommand \tableofcontents{}
\end_inset
\layout Chapter
Introduction
\layout Standard
Before starting to jump into the work, we should introduce some specialities
- of the PIM API first.
+ of the PIM API, first.
To know these facts should help to avoid possible irritations and misunderstand
ings:
\layout Enumerate
The PIM-API heavily uses C++ templates (as known as generic classes), but
you don't have to understand very deeple what templates are doing and how
they work! Most of the API works without even seeing the templates.
- In some cases whe have to use them (for instance to use the factory classes)
+ In some cases whe have to use them (for instance to use the factory classes),
but this guide will provide examples which should help to find the path
through.
But it is a good idea to read some short introduction of templates to avoid
unneccessary mistakes.
\layout Enumerate
The PIM-API is split into two parts: The
\emph on
frontend
\emph default
and the
\emph on
backend.
\emph default
While the frontend provides the API for the user, the backend implements
how to access the databases and what to do with the data.
- This paper just focusses the frontend as we just want to access data.
+ As we just want to access data, this paper just focusses the frontend.
Thus, you should ignore all classes which contains something like
\begin_inset Quotes gld
\end_inset
backend
\begin_inset Quotes grd
\end_inset
in its name! Backends are just interessting for people who want to extend
or implement new possiblities about how to access databases, which will
be discussed at the end of this paper.
Currently, you just have to understand that there do exist several backends
for every type of PIM data (Contact, Todo, Datebook) which controls whether
you want to access an XML, SQL (SQLite) or VCard style database.
If you just want to use the default database, you even don't have to think
about this!
\layout Standard
In the next chapter, we will show how to access the default database as
easy as possible.
This will be the solution for most of the problems you may face while accessing
the PIM data.
\layout Chapter
@@ -303,49 +303,49 @@ The last parameter
\end_inset
my-app
\begin_inset Quotes grd
\end_inset
is very importand and should be equal for every instance of an application.
Some database backends (like the XML backend) uses this string as an unique
filename to create a journal file.
If your application should run in several instances independently you will
need multiple journal files and therefore several name strings!
\layout Standard
If the database access-object is is not needed anymore, you have to remove
it by calling
\emph on
delete
\emph default
:
\layout LyX-Code
delete sourceDB;
\layout Section
-Accessing the access-object
+Accessing the Access-Object
\begin_inset LatexCommand \label{sec:Accessing-the-access-object}
\end_inset
\layout Standard
After receiving the access-object, we just have to use its API which is
mainly defined by the common base class
\series bold
OPimAccessTemplate
\series default
(see
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessTemplate.html}
\end_inset
).
This API is inherited by all access-classes and therefore common to all
access-objects.
We will show the most important operations of it first (please replace
\begin_inset Quotes gld
\end_inset
@@ -402,50 +402,50 @@ see
for OPimTodoAccess):
\layout LyX-Code
bool load ();
\layout LyX-Code
bool reload ();
\layout LyX-Code
bool save ();
\layout LyX-Code
\layout LyX-Code
bool add (const T& t);
\layout LyX-Code
bool remove (const T& t);
\layout LyX-Code
bool replace (const T& t);
\layout Standard
-After receiving an access-object, we have to load the existing dataset,
- which is done by the
+After receiving an access-object, we have to load the existing dataset into
+ the backend, which is done by the
\begin_inset Quotes gld
\end_inset
load()
\begin_inset Quotes grd
\end_inset
operation.
The
\begin_inset Quotes gld
\end_inset
save()
\begin_inset Quotes grd
\end_inset
operation is important to write back (or
\emph on
commit
\emph default
) local changes into the global database.
After doing this, the changes are globally accessable! The
\begin_inset Quotes gld
\end_inset
@@ -478,49 +478,49 @@ If you want to work with the existing dataset, you need to get a list of
This list is returned by the call
\begin_inset Quotes gld
\end_inset
allRecords()
\begin_inset Quotes grd
\end_inset
which returns a list of all available records as an
\series bold
OPimRecordList
\series default
(see
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html}
\end_inset
).
\layout LyX-Code
List allRecords ();
\layout Standard
-In fact this
+In fact, this
\emph on
List
\emph default
just contains a list of uid's to take care of memory space.
As every record is identified by an unique identifaction number which is
called UID (Unique IDentification), these numbers just exists once in the
database which is currently on access! To receive the real record, you
have to use the operation
\begin_inset Quotes gld
\end_inset
find()
\begin_inset Quotes grd
\end_inset
with a valid UID as paramter:
\layout LyX-Code
T find (UID uid);
\layout Standard
This is all you need to realize a basic access to the PIM-Databases! The
next chapter will guide you into more details of the PIM-API.
\layout Chapter
@@ -562,82 +562,82 @@ But first we will start with intoducing some features of the
\series bold
OPimAccessFactory
\series default
.
\layout Section
Advanced Factory Features
\begin_inset LatexCommand \label{sec:Advanced-Factory-Features}
\end_inset
\layout Standard
In the previous chapter we used the operation
\begin_inset Quotes gld
\end_inset
defaultAccess()
\begin_inset Quotes grd
\end_inset
to request an access-object to the dafault backend.
Whether this default backend will access the XML, VCard or SQLite database
- type, this is defined by the configuration file
+ type, is defined by the configuration file
\begin_inset Quotes gld
\end_inset
pimaccess.conf
\begin_inset Quotes grd
\end_inset
which is stored in the directory
\begin_inset Quotes gld
\end_inset
Settings
\begin_inset Quotes grd
\end_inset
, stored in the user home directory.
Changing this setting will take effect to all applications using
\begin_inset Quotes gld
\end_inset
defaultAccess()
\begin_inset Quotes grd
\end_inset
.
Therefore it is not a good idea to modify a global setting, if an application
should access a special database type, for instance to move data from one
database to an other.
\layout Standard
-If the developer wants to select a special database type for sure, he has
- to use the oparation
+If the developer wants to select a special database type for sure without
+ unnecessary side effects, he has to use the oparation
\emph on
create()
\emph default
which has the following parameters:
\layout LyX-Code
T * create (OPimGlobal::PimType type, OPimGlobal::DatabaseStyle dbStyle,
const QString &appName, const QString &fileName=QString::null)
\layout Standard
Some paramters are already known, like type and appName (see section
\begin_inset LatexCommand \ref{sec:Instantiate-the-Access}
\end_inset
).
The new parameter
\begin_inset Quotes gld
\end_inset
dbStyle
\begin_inset Quotes grd
\end_inset
@@ -738,49 +738,49 @@ Special Features: Searching and Sorting
\begin_inset LatexCommand \label{sec:Special-Features:-Searching}
\end_inset
\layout Standard
In most cases it is not sufficient to receive just a list of all information
in a database.
It is essential to get a subset of the information available and to be
able to sort it.
For this kind of excercise we provide some special operations which provide
searching and sorting in an incremental manner
\begin_inset Foot
collapsed true
\layout Standard
FIXME: matchRegexp() does take a list of uid's.
Therefore it is currently not possible to use it in an incremental manner!
(se)
\end_inset
.
- Therfore it is possible to research a
+ Therefore it is possible to research a
\begin_inset Quotes gld
\end_inset
List
\begin_inset Quotes grd
\end_inset
which was returned by a previous search query and to sort it afterwards.
Before we will take a close look into sorting, we will start with searching.
There exist two different ways of searching:
\layout Enumerate
Search a complete database for a special regular expression, using
\begin_inset Quotes gld
\end_inset
matchRegexp ()
\begin_inset Quotes grd
\end_inset
.
This search type returns all records which contains the given regular expressio
n
\emph on
@@ -897,74 +897,83 @@ OPimContact searchQuery;
\layout LyX-Code
searchQuery.setLastName(
\begin_inset Quotes gld
\end_inset
Eilers
\begin_inset Quotes grd
\end_inset
);
\layout LyX-Code
searchQuery.setHomeZip(
\begin_inset Quotes gld
\end_inset
3*
\begin_inset Quotes grd
\end_inset
);
\layout Standard
-We use a usual
+We use an usual
\begin_inset Quotes gld
\end_inset
OPimContact
\begin_inset Quotes grd
\end_inset
- and fill into two fields the search information.
+ and fill into two fields the query information.
+ All filled fields are taken for the search operation (using an
+\begin_inset Quotes gld
+\end_inset
+
+AND
+\begin_inset Quotes grd
+\end_inset
+
+ operation), the unused ones are simply ignored.
As we just want to search for entries which zip number starts with a
\begin_inset Quotes gld
\end_inset
3
\begin_inset Quotes grd
\end_inset
we use the Wildcard
\begin_inset Quotes gld
\end_inset
*
\begin_inset Quotes grd
\end_inset
- as we would do for finding files in a filesystem.
+ as we would do to find files in a filesystem.
\layout Standard
The next step is to put this query into the operation which is defined like
this:
\layout LyX-Code
List queryByExample (const T& query, int querySettings, const QDateTime
&startperiod=QDateTime())
\layout Standard
The first parameter
\begin_inset Quotes gld
\end_inset
query
\begin_inset Quotes grd
\end_inset
should used to set our query, but we have to set the parameter
\begin_inset Quotes gld
\end_inset
querySettings
\begin_inset Quotes grd
@@ -998,87 +1007,87 @@ setHomeZip
WildCards
\begin_inset Quotes grd
\end_inset
.
And we want to be sure to find lower case names, too, which may be mistyped
(like
\begin_inset Quotes gld
\end_inset
eilers
\begin_inset Quotes grd
\end_inset
,
\begin_inset Quotes gld
\end_inset
eIlers
\begin_inset Quotes grd
\end_inset
, ...).
- Thus we have to use the
+ Thus, we have to use the
\begin_inset Quotes gld
\end_inset
IgnoreCase
\begin_inset Quotes grd
\end_inset
setting which is to combine with the other using an
\begin_inset Quotes gld
\end_inset
or
\begin_inset Quotes grd
\end_inset
operator.
The last parameter
\begin_inset Quotes gld
\end_inset
endperiod
\begin_inset Quotes grd
\end_inset
will be ignored for this case which will look like this:
\layout LyX-Code
use namespace Opie;
\layout LyX-Code
[...]
\layout LyX-Code
List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase::
IgnoreCase );
\layout Standard
-This operation may return a list of entries which can be accesses as usual,
+This operation may return a list of entries which can be accessed as above,
using the
\begin_inset Quotes gld
\end_inset
find()
\begin_inset Quotes grd
\end_inset
operation.
\layout Standard
It should be clear at this stage, that this query is very powerful and -
depending to the querySettings - could be very complicated to implement.
Thus, not all backends do support all features defined by querySettings
\begin_inset Foot
collapsed true
\layout Standard
At this time, just the contact database for XML and VCard is supporting
all queries and combination of them.
All others just support subsets.
\end_inset
@@ -1152,48 +1161,237 @@ startperiod
In some cases, a time interval should be set to find for instance all entries
between two dates (used for example by the birthday reminder for today
(see here:
\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/today/plugins/addressbook/addresspluginwidget.cpp?rev=1.14&content-type=text/x-cvsweb-markup}
\end_inset
)) as requested by the setting
\begin_inset Quotes gld
\end_inset
OPimBase::DateDiff
\begin_inset Quotes grd
\end_inset
.
The date and time in the query object is used as the
\series bold
end
\series default
of the interval.
The start will be defined by the last parameter (if nothing is set, the
current date will be taken!).
Therefore, it is possible to set a time frame for all searched entries.
+\layout Standard
+
+If you want to do incremental search operations, you may use the special
+
+\begin_inset Quotes gld
+\end_inset
+
+queryByExample()
+\begin_inset Quotes grd
+\end_inset
+
+ which takes a
+\begin_inset Quotes gld
+\end_inset
+
+List
+\begin_inset Quotes grd
+\end_inset
+
+ as the first parameter.
+ The search operation will just occure on this set of uid's!
+\layout Subsection
+
+Sorting
+\layout Standard
+
+To sort a given dataset, you should use the following operation (or one
+ of the others which behave slightly differently):
+\layout LyX-Code
+
+List sorted (const List& list, bool ascending, int sortOrder, int sortFilter,
+ const QArray< UID >& cats);
+\layout Standard
+
+This sort operation takes a list of uid's as returned for instance from
+ a search query.
+ The parameter
+\begin_inset Quotes gld
+\end_inset
+
+ascending
+\begin_inset Quotes grd
+\end_inset
+
+ defines whether the sort should be in an ascending order or not.
+
+\begin_inset Quotes gld
+\end_inset
+
+sortOrder
+\begin_inset Quotes grd
+\end_inset
+
+ is defined by the enumerations
+\begin_inset Quotes gld
+\end_inset
+
+SortOrder
+\begin_inset Quotes grd
+\end_inset
+
+ and
+\begin_inset Quotes gld
+\end_inset
+
+SortOrderBase
+\begin_inset Quotes grd
+\end_inset
+
+ and defines which field should be used to sort (see for
+\series bold
+OPimContactAccess
+\series default
+:
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContactAccess.html}
+
+\end_inset
+
+, for
+\series bold
+ODateBookAccess
+\series default
+:
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1ODateBookAccess.html}
+
+\end_inset
+
+ and for
+\series bold
+OPimTodoAccess
+\series default
+:
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodoAccess.html}
+
+\end_inset
+
+ and for common settings
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w21}
+
+\end_inset
+
+).
+\layout Standard
+
+The
+\begin_inset Quotes gld
+\end_inset
+
+sortFilter
+\begin_inset Quotes grd
+\end_inset
+
+ parameter allows to remove some entries which are not interesting for the
+ result and is defined in the same classes as
+\begin_inset Quotes gld
+\end_inset
+
+sortOrder
+\begin_inset Quotes grd
+\end_inset
+
+ by the enumeration
+\begin_inset Quotes gld
+\end_inset
+
+SortFilter
+\begin_inset Quotes grd
+\end_inset
+
+ and
+\begin_inset Quotes gld
+\end_inset
+
+SortFilterBase
+\begin_inset Quotes grd
+\end_inset
+
+.
+ The list of id's in
+\begin_inset Quotes gld
+\end_inset
+
+cats
+\begin_inset Quotes grd
+\end_inset
+
+ allows to remain just these entries which are included in the list of categorie
+s.
+\layout Standard
+
+The returned list contains the same uid's as given via
+\begin_inset Quotes gld
+\end_inset
+
+list
+\begin_inset Quotes grd
+\end_inset
+
+ (or a subset of it, as the sortFilter and category list removes some entries)
+ with a modified order as
+\begin_inset Quotes gld
+\end_inset
+
+sortOrder
+\begin_inset Quotes grd
+\end_inset
+
+ and
+\begin_inset Quotes gld
+\end_inset
+
+ascending
+\begin_inset Quotes grd
+\end_inset
+
+ dictates.
+\layout Standard
+
+Therefore
+\begin_inset Quotes gld
+\end_inset
+
+sorted()
+\begin_inset Quotes grd
+\end_inset
+
+ is more a combination of search and sort, as just a sort command.
+ But this combination is exactly what the developer needs in most situations.
+
\layout Section
Generic Access: OPimBase and OPimRecord
\begin_inset LatexCommand \label{sec:Generic-Access:-OPimBase}
\end_inset
\layout Section
Caching
\layout Standard
Need to be written.
Implementation is found at:
\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/noncore/tools/pimconverter/converter.cpp?rev=1.9&content-type=text/x-cvsweb-markup}
\end_inset
\layout Section
Internal Signal Handling: Automatic Propagation of Changes
\begin_inset LatexCommand \label{sec:Internal-Signal-Handling:}