summaryrefslogtreecommitdiff
Side-by-side diff
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--development/pim/pim_howto/pim_howto.lyx252
1 files changed, 163 insertions, 89 deletions
diff --git a/development/pim/pim_howto/pim_howto.lyx b/development/pim/pim_howto/pim_howto.lyx
index 1e43d63..a99b0df 100644
--- a/development/pim/pim_howto/pim_howto.lyx
+++ b/development/pim/pim_howto/pim_howto.lyx
@@ -1,65 +1,34 @@
#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass scrbook
\begin_preamble
\fancyhead{}
\fancyfoot{}
\fancyhead[LE,RO]{\slshape \leftmark}
\fancyhead[LO,RE]{\slshape \leftmark}
\fancyhead[RE,LO]{\thepage}
%\fancyhead[LO,RE]{}
% \usepackage{ae}
+\usepackage[T1]{fontenc}
\usepackage[bookmarksopen,colorlinks]{hyperref}
% \pdfoutput=1
% \pdfcompresslevel=8
% \pdfinfo{
% /Title ClearSim-RealtTime und Andere
% /Creator (Tex)
% /Author (Stefan Eilers)
% /Subject ()
% /Keywords (Simulation,Real-Time,ClearSim,prototype,efsm)
% }
-\renewcommand\familydefault{\sfdefault}
-
-\usepackage{multicol}
-\newcommand\NrCol{3}
-\renewenvironment{theindex}
- {\columnseprule \z@
- \columnsep 35\p@
- \section*{\indexname}%
- \@mkboth{\MakeUppercase\indexname}%
- {\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 american
\inputencoding default
\fontscheme ae
\graphics default
\float_placement htbp
\paperfontsize default
\spacing single
\papersize a4paper
\paperpackage widemarginsa4
\use_geometry 0
\use_amsmath 0
@@ -73,30 +42,30 @@
\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)
+(V 0.2)
\layout Author
\family sans
-Stefan Eilers
+Stefan Eilers (stefan@eilers-online.net)
\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 calendar tool (in this paper called datebook events) and
your todo events.
Beside providing full featured access to this information, it covers the
@@ -105,24 +74,34 @@ The Opie-Pim API provides a powerfull access interface to the PIM (Personal
\layout Standard
While starting to read the automatically generated API-documentation, the
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
+\series bold
+You will find a more recent version at:
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apihowto/pim_howto.pdf}
+
+\end_inset
+
+
+\layout Standard
+
+
\begin_inset LatexCommand \tableofcontents{}
\end_inset
\layout Chapter
Introduction
\layout Standard
Before starting to jump into the work, we should introduce some specialties
of the PIM API, first.
@@ -208,68 +187,91 @@ defaultAccess()
\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 (
+\newline
+typename OPimGlobal::PimType type,
+\newline
+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
+\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" );
+OPimContactAccess* sourceDB =
+\newline
+OPimAccessFactory<OPimContactAccess>::defaultAccess(
+\newline
+OPimGlobal::CONTACTLIST,
+\newline
+"my-app" );
+\layout LyX-Code
+
\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 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" );
+ODateBookAccess* sourceDB =
+\newline
+OPimAccessFactory<ODatebookAccess>::defaultAccess(
+\newline
+OPimGlobal::DATEBOOK,
+\newline
+"my-app" );
\layout Standard
And the same for todo:
\layout LyX-Code
-OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess(
- OPimGlobal::TODOLIST, "my-app" );
+OPimTodoAccess* sourceDB =
+\newline
+OPimAccessFactory<OPimTodoAccess>::defaultAccess(
+\newline
+OPimGlobal::TODOLIST,
+\newline
+"my-app" );
\layout Standard
Using
\emph on
\begin_inset Quotes gld
\end_inset
defaultAccess()
\begin_inset Quotes grd
\end_inset
@@ -476,60 +478,143 @@ We should check whether all databases behave like this! (se)
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
+OPimRecordList<T>
\series default
(see
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html}
\end_inset
).
-
+ This OPimRecordList is a template and should be used with the right class
+ parameter
+\begin_inset Quotes eld
+\end_inset
+
+T
+\begin_inset Quotes erd
+\end_inset
+
+ which is currently one of the following: OPimContact, OPimTodo and OPimEvent.
\layout LyX-Code
-List allRecords();
+OPimRecordList<T> allRecords();
\layout Standard
In fact, this
-\emph on
-List
-\emph default
+\begin_inset Quotes eld
+\end_inset
+
+OPimRecordList<T>
+\begin_inset Quotes erd
+\end_inset
+
just contains a list of uid's to take care of memory space.
- 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
+ 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 parameter:
\layout LyX-Code
T find (UID uid);
\layout Standard
+The remaining question is, how to get a valid UID out of a list to use the
+
+\begin_inset Quotes eld
+\end_inset
+
+find()
+\begin_inset Quotes erd
+\end_inset
+
+ in a correct manner.
+ This could be done by requesting a special element of the list, using the
+ operator[] or by using iterators.
+ The first one would be like this
+\begin_inset Foot
+collapsed true
+
+\layout Standard
+
+Please do not forget to use
+\begin_inset Quotes eld
+\end_inset
+
+use namespace Opie;
+\begin_inset Quotes erd
+\end_inset
+
+ to enable the namespace
+\begin_inset Quotes eld
+\end_inset
+
+Opie
+\begin_inset Quotes erd
+\end_inset
+
+!!
+\end_inset
+
+:
+\layout LyX-Code
+
+OPimRecordList<OPimContact> list = allRecords();
+\layout LyX-Code
+
+for ( int i = 0; i < list.count(); i++ ){
+\layout LyX-Code
+
+ cout << "The UID is: " << list[i] << endl;
+\layout LyX-Code
+
+}
+\layout Standard
+
+Using the iterator is as easy as the previous one:
+\layout LyX-Code
+
+OPimRecordList<OPimContact> list = allRecords();
+\layout LyX-Code
+
+OPimRecordList<OPimContact>::iterator it;
+\layout LyX-Code
+
+for ( it = list.begin(); it != list.end(); ++it ){
+\layout LyX-Code
+
+ count << "The UID is: " << (*it) << endl;
+\layout LyX-Code
+
+}
+\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}
@@ -744,39 +829,32 @@ Special Features: Searching and Sorting
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 exercise we provide some special operations which provide
searching and sorting in an incremental manner
\begin_inset Foot
collapsed false
\layout Standard
-FIXME: matchRegexp() does take a list of uid's.
+FIXME: matchRegexp() does not 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.
+ Therefore it is possible to use a list 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
@@ -831,36 +909,36 @@ Searching with
\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);
+OPimRecordList<T> matchRegexp (const QRegExp& r);
\layout Standard
The
\begin_inset Quotes gld
\end_inset
-List
+OPimRecordList<T>
\begin_inset Quotes grd
\end_inset
- is still a OPimRecordList which contains 0 or more uid's of matching records.
+ is still a list 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
@@ -887,44 +965,28 @@ Eilers
\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 eld
-\end_inset
-
-Eilers
-\begin_inset Quotes erd
-\end_inset
-
- );
+searchQuery.setLastName( "Eilers" );
\layout LyX-Code
-searchQuery.setHomeZip(
-\begin_inset Quotes eld
-\end_inset
-
-3*
-\begin_inset Quotes srd
-\end_inset
-
- );
+searchQuery.setHomeZip( "3*" );
\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
@@ -950,26 +1012,27 @@ AND
*
\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())
+OPimRecordList<T> queryByExample (const T& query,
+\newline
+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
@@ -1061,26 +1124,29 @@ 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 );
+OPimRecordList<OPimContact> found_items =
+\newline
+sourceDB->queryByExample( searchQuery,
+\newline
+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.
@@ -1208,29 +1274,37 @@ queryByExample()
List
\begin_inset Quotes grd
\end_inset
as the first parameter.
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):
+ of the others which behave slightly differently, see
+\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessTemplate.html}
+
+\end_inset
+
+):
\layout LyX-Code
-List sorted (const List& list, bool ascending, int sortOrder, int sortFilter,
- const QArray< UID >& cats);
+OPimRecordList<T> sorted (const List& list,
+\newline
+bool ascending, int sortOrder, int sortFilter,
+\newline
+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