summaryrefslogtreecommitdiff
authoreilers <eilers>2005-01-05 10:03:30 (UTC)
committer eilers <eilers>2005-01-05 10:03:30 (UTC)
commit80823d4cbd234a54a15d6b439bd37a8ea42e7904 (patch) (side-by-side diff)
treefe2a72ec3d6e6fce6075cb9be34e456e2aa9b1e2
parentbf65cf9aeb5dddcc4b0c0d702afd748d97e95d5e (diff)
downloadopie-80823d4cbd234a54a15d6b439bd37a8ea42e7904.zip
opie-80823d4cbd234a54a15d6b439bd37a8ea42e7904.tar.gz
opie-80823d4cbd234a54a15d6b439bd37a8ea42e7904.tar.bz2
Fixes by iSpell and other minor stuff
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--development/pim/pim_howto/pim_howto.lyx112
1 files changed, 60 insertions, 52 deletions
diff --git a/development/pim/pim_howto/pim_howto.lyx b/development/pim/pim_howto/pim_howto.lyx
index 4571996..1e43d63 100644
--- a/development/pim/pim_howto/pim_howto.lyx
+++ b/development/pim/pim_howto/pim_howto.lyx
@@ -31,158 +31,158 @@
{\MakeUppercase\indexname}%
\begin{multicols}{\NrCol}\thispagestyle{plain}\parindent\z@
\parskip\z@ \@plus .3\p@\relax
\let\item\@idxitem}
{\clearpage %
\end{multicols}}
\renewenvironment{theindex}
{\if@twocolumn
\@restonecolfalse
\else
\@restonecoltrue
\fi
\columnseprule \z@
\columnsep 35\p@
\twocolumn[\refstepcounter{section}%
\section{\indexname}]%
\@mkboth{\MakeUppercase\indexname}%
{\MakeUppercase\indexname}%
\thispagestyle{plain}\parindent\z@
\parskip\z@ \@plus .3\p@\relax
\let\item\@idxitem}
{\if@restonecol\onecolumn\else\clearpage\fi}
\end_preamble
-\language german
-\inputencoding auto
+\language american
+\inputencoding default
\fontscheme ae
\graphics default
\float_placement htbp
\paperfontsize default
\spacing single
\papersize a4paper
\paperpackage widemarginsa4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
-\quotes_language german
+\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 2
\paperpagestyle fancy
\layout Title
How to use the Opie-Pim API without getting tired!
\newline
(Aka: Hitchhikers Guide Through the Opie-Pim API)
\newline
(Pre V 0.1)
\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
+ dates in your calendar 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
+ user may be confused by a lot of unnecessary classes and details which
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
+Before starting to jump into the work, we should introduce some specialties
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 we 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.
+ unnecessary 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.
- As we just want to access data, this paper just focusses the frontend.
+ As we just want to access data, this paper just focuses 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
+ in its name! Backends are just interesting for people who want to extend
+ or implement new possibilities 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
Quick Guide to access the Database
\layout Standard
In this chapter we will introduce very quickly how to get access to the
database and how to access data.
It should help to find the right directions.
If it is too short for you, you should read the next chapter afterwards
to find a more complete and detailed view into the system.
\layout Section
@@ -196,109 +196,109 @@ Instantiate the access-object
To gain access to the database you need something we will call
\emph on
access-object
\emph default
(an instance of the access-class for the database) which handles the database
access.
Requesting such an object is very easy by using the operation
\emph on
defaultAccess()
\emph default
of the factory class
\series bold
OPimAccessFactory
\series default
(see
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessFactory.html}
\end_inset
).
This operation is defined like this:
\layout LyX-Code
-T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName)
+T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName)
\layout Standard
You just have to add the following lines to your source code to use it (this
example is for accessing the contact database):
\layout LyX-Code
#include <opie2/opimaccessfactory.h>
\layout LyX-Code
use namespace Opie;
\layout Standard
[...]
\layout LyX-Code
OPimContactAccess* sourceDB = OPimAccessFactory<OPimContactAccess>::defaultAcces
s( OPimGlobal::CONTACTLIST, "my-app" );
\layout Standard
If everything works as expected, you will receive a pointer to the contact
access-class which has to be used for accessing the database.
Accessing the datebook database works equally
\begin_inset Foot
-collapsed true
+collapsed false
\layout Standard
The API will be changed in the future: ODateBookAccess will be renamed to
OPimEventAccess.
\end_inset
:
\layout LyX-Code
ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess(
OPimGlobal::DATEBOOK, "my-app" );
\layout Standard
And the same for todo:
\layout LyX-Code
OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess(
OPimGlobal::TODOLIST, "my-app" );
\layout Standard
Using
\emph on
\begin_inset Quotes gld
\end_inset
defaultAccess()
\begin_inset Quotes grd
\end_inset
\emph default
-, the default dabase is accessed automatically
+, the default database is accessed automatically
\begin_inset Foot
-collapsed true
+collapsed false
\layout Standard
The configuration file
\begin_inset Quotes gld
\end_inset
pimaccess.conf
\begin_inset Quotes grd
\end_inset
defines which backend is selected as default!
\end_inset
.
If you want to use anything else, you have to read the next chapter to
get the information how to do this.
\layout Standard
The last parameter
\begin_inset Quotes gld
\end_inset
@@ -339,316 +339,316 @@ 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
T
\begin_inset Quotes grd
\end_inset
below with the corresponding
\emph on
data-class
\emph default
for the selected access-class: OPimContact
\begin_inset Foot
-collapsed true
+collapsed false
\layout Standard
see
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContact.html}
\end_inset
\end_inset
for OPimContactAccess, OPimEvent
\begin_inset Foot
-collapsed true
+collapsed false
\layout Standard
see
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimEvent.html}
\end_inset
\end_inset
for ODateBookAccess and OPimTodo
\begin_inset Foot
-collapsed true
+collapsed false
\layout Standard
see
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodo.html}
\end_inset
\end_inset
for OPimTodoAccess):
\layout LyX-Code
bool load ();
\layout LyX-Code
-bool reload ();
+bool reload ();
\layout LyX-Code
bool save ();
\layout LyX-Code
\layout LyX-Code
-bool add (const T& t);
+bool add (const T& t);
\layout LyX-Code
-bool remove (const T& t);
+bool remove (const T& t);
\layout LyX-Code
-bool replace (const T& t);
+bool replace (const T& t);
\layout Standard
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
reload()
\begin_inset Quotes grd
\end_inset
operation loads changes of the global database into the local set
\series bold
without
\series default
removing any local changes
\begin_inset Foot
-collapsed true
+collapsed false
\layout Standard
-We should check whether all dabases behave like this! (se)
+We should check whether all databases behave like this! (se)
\end_inset
.
This may be done after receiving information about any change by an other
application which is not in scope of this chapter.
The other operations are self explaining and should work as expected.
\layout Standard
If you want to work with the existing dataset, you need to get a list of
all available information.
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 ();
+List allRecords();
\layout Standard
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
+ As every record is identified by an unique identification 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:
+ with a valid UID as parameter:
\layout LyX-Code
-T find (UID uid);
+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
How to Access PIM-Data: Detailed View
\layout Standard
As shown in the previous chapter, all we need to access the PIM-Database
is to request an access-object from the OPimAccessFactory and to use it.
We will now introduce some special features of this factory (see section
\begin_inset LatexCommand \ref{sec:Advanced-Factory-Features}
\end_inset
), followed by some very important features like searching and sorting in
section
\begin_inset LatexCommand \ref{sec:Special-Features:-Searching}
\end_inset
.
If you are interested in accessing data without take care about their types,
section
\begin_inset LatexCommand \ref{sec:Generic-Access:-OPimBase}
\end_inset
will show how to do this, followed by a short introduction about delayed
loading in section
\begin_inset LatexCommand \ref{sec:Internal-Signal-Handling:}
\end_inset
.
\layout Standard
-But first we will start with intoducing some features of the
+But first we will start with introducing 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.
+ to request an access-object to the default backend.
Whether this default backend will access the XML, VCard or SQLite database
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 without
- unnecessary side effects, he has to use the oparation
+ unnecessary side effects, he has to use the operation
\emph on
create()
\emph default
which has the following parameters:
\layout LyX-Code
-T * create (OPimGlobal::PimType type, OPimGlobal::DatabaseStyle dbStyle,
+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
+Some parameters 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
defines which database type should be selected.
Possible values could be found in the enumeration
\emph on
DataBaseStyle
\emph default
in the class
\series bold
OPimGlobal
\series default
(see
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1Pim_1_1OPimGlobal.html}
@@ -725,52 +725,52 @@ fileName
~/Applications/<name of application>/
\begin_inset Quotes grd
\end_inset
).
\layout Standard
In the next section we will discuss how searching and sorting take place
with this API.
\layout Section
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
+ For this kind of exercise we provide some special operations which provide
searching and sorting in an incremental manner
\begin_inset Foot
-collapsed true
+collapsed false
\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
.
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
@@ -819,49 +819,49 @@ We will start with the first and very simple
\begin_inset Quotes grd
\end_inset
matchRegexp()
\begin_inset Quotes grd
\end_inset
, followed by the query by example search query.
\layout Subsection
Searching with
\begin_inset Quotes gld
\end_inset
matchRegexp()
\begin_inset Quotes grd
\end_inset
\layout Standard
The function is defined like this:
\layout LyX-Code
-List matchRegexp (const QRegExp &r);
+List matchRegexp (const QRegExp& r);
\layout Standard
The
\begin_inset Quotes gld
\end_inset
List
\begin_inset Quotes grd
\end_inset
is still a OPimRecordList which contains 0 or more uid's of matching records.
As already discussed in section
\begin_inset LatexCommand \ref{sec:Accessing-the-access-object}
\end_inset
you have to use the
\begin_inset Quotes gld
\end_inset
find()
\begin_inset Quotes grd
\end_inset
@@ -876,132 +876,140 @@ The query by example search style is working is using a data object (for
For instance, if you want to request all entries which contains the last
name
\begin_inset Quotes gld
\end_inset
Eilers
\begin_inset Quotes grd
\end_inset
and the home zip number should start with
\begin_inset Quotes gld
\end_inset
3
\begin_inset Quotes grd
\end_inset
you have to do the following:
\layout LyX-Code
OPimContact searchQuery;
\layout LyX-Code
searchQuery.setLastName(
-\begin_inset Quotes gld
+\begin_inset Quotes eld
\end_inset
Eilers
-\begin_inset Quotes grd
+\begin_inset Quotes erd
\end_inset
);
\layout LyX-Code
searchQuery.setHomeZip(
-\begin_inset Quotes gld
+\begin_inset Quotes eld
\end_inset
3*
-\begin_inset Quotes grd
+\begin_inset Quotes srd
\end_inset
);
\layout Standard
We use an usual
\begin_inset Quotes gld
\end_inset
OPimContact
\begin_inset Quotes grd
\end_inset
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 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())
+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
\end_inset
to configure the search properly.
- This settings are defined by the enum QuerySettings in the class
+ This settings are defined by the enumeration
+\begin_inset Quotes gld
+\end_inset
+
+QuerySettings
+\begin_inset Quotes grd
+\end_inset
+
+ in the class
\series bold
OPimBase
\series default
(see
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w19}
\end_inset
).
The meaning of all settings will be discussed later.
For the first turn we will just concentrate on the things we need in this
case.
As we use Wildcards in
\begin_inset Quotes gld
\end_inset
setHomeZip
\begin_inset Quotes grd
\end_inset
we have to use
\begin_inset Quotes gld
\end_inset
@@ -1061,67 +1069,67 @@ use namespace Opie;
[...]
\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 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
+collapsed false
\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
.
To check which settings are supported and to be able to react dynamically
on missing features (for instance to disable some search features in the
application) we provide the following operations:
\layout LyX-Code
-bool hasQuerySettings( uint querySettings );
+bool hasQuerySettings( uint querySettings );
\layout LyX-Code
-uint querySettings();
+uint querySettings();
\layout Standard
The first operation
\begin_inset Quotes gld
\end_inset
hasQuerySettings()
\begin_inset Quotes grd
\end_inset
may be used to ask whether the database can handle the given query settings.
In this example a call to
\layout LyX-Code
hasQuerySettings( OPimBase::WildCards | OpimBase::IgnoreCase );
\layout Standard
should be answered with
\begin_inset Quotes gld
\end_inset
true
\begin_inset Quotes grd
\end_inset
@@ -1181,59 +1189,59 @@ end
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!
+ The search operation will just occur 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,
+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
@@ -1380,32 +1388,32 @@ Generic Access: OPimBase and OPimRecord
\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:}
\end_inset
\layout Standard
-Need to be written and is not implemented completly!
+Need to be written and is not implemented completely!
\layout Chapter
Howto Extend and Write New Backends
\layout Standard
Need to be written.
\the_end