summaryrefslogtreecommitdiff
Unidiff
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,164 +1,143 @@
1#LyX 1.3 created this file. For more info see http://www.lyx.org/ 1#LyX 1.3 created this file. For more info see http://www.lyx.org/
2\lyxformat 221 2\lyxformat 221
3\textclass scrbook 3\textclass scrbook
4\begin_preamble 4\begin_preamble
5\fancyhead{} 5\fancyhead{}
6\fancyfoot{} 6\fancyfoot{}
7\fancyhead[LE,RO]{\slshape \leftmark} 7\fancyhead[LE,RO]{\slshape \leftmark}
8\fancyhead[LO,RE]{\slshape \leftmark} 8\fancyhead[LO,RE]{\slshape \leftmark}
9\fancyhead[RE,LO]{\thepage} 9\fancyhead[RE,LO]{\thepage}
10%\fancyhead[LO,RE]{} 10%\fancyhead[LO,RE]{}
11% \usepackage{ae} 11% \usepackage{ae}
12\usepackage[T1]{fontenc}
12\usepackage[bookmarksopen,colorlinks]{hyperref} 13\usepackage[bookmarksopen,colorlinks]{hyperref}
13% \pdfoutput=1 14% \pdfoutput=1
14% \pdfcompresslevel=8 15% \pdfcompresslevel=8
15% \pdfinfo{ 16% \pdfinfo{
16% /Title ClearSim-RealtTime und Andere 17% /Title ClearSim-RealtTime und Andere
17% /Creator (Tex) 18% /Creator (Tex)
18% /Author (Stefan Eilers) 19% /Author (Stefan Eilers)
19% /Subject () 20% /Subject ()
20% /Keywords (Simulation,Real-Time,ClearSim,prototype,efsm) 21% /Keywords (Simulation,Real-Time,ClearSim,prototype,efsm)
21% } 22% }
22\renewcommand\familydefault{\sfdefault}
23
24\usepackage{multicol}
25\newcommand\NrCol{3}
26\renewenvironment{theindex}
27 {\columnseprule \z@
28 \columnsep 35\p@
29 \section*{\indexname}%
30 \@mkboth{\MakeUppercase\indexname}%
31 {\MakeUppercase\indexname}%
32 \begin{multicols}{\NrCol}\thispagestyle{plain}\parindent\z@
33 \parskip\z@ \@plus .3\p@\relax
34 \let\item\@idxitem}
35 {\clearpage %
36 \end{multicols}}
37
38\renewenvironment{theindex}
39 {\if@twocolumn
40 \@restonecolfalse
41 \else
42 \@restonecoltrue
43 \fi
44 \columnseprule \z@
45 \columnsep 35\p@
46 \twocolumn[\refstepcounter{section}%
47 \section{\indexname}]%
48 \@mkboth{\MakeUppercase\indexname}%
49 {\MakeUppercase\indexname}%
50 \thispagestyle{plain}\parindent\z@
51 \parskip\z@ \@plus .3\p@\relax
52 \let\item\@idxitem}
53 {\if@restonecol\onecolumn\else\clearpage\fi}
54\end_preamble 23\end_preamble
55\language american 24\language american
56\inputencoding default 25\inputencoding default
57\fontscheme ae 26\fontscheme ae
58\graphics default 27\graphics default
59\float_placement htbp 28\float_placement htbp
60\paperfontsize default 29\paperfontsize default
61\spacing single 30\spacing single
62\papersize a4paper 31\papersize a4paper
63\paperpackage widemarginsa4 32\paperpackage widemarginsa4
64\use_geometry 0 33\use_geometry 0
65\use_amsmath 0 34\use_amsmath 0
66\use_natbib 0 35\use_natbib 0
67\use_numerical_citations 0 36\use_numerical_citations 0
68\paperorientation portrait 37\paperorientation portrait
69\secnumdepth 3 38\secnumdepth 3
70\tocdepth 3 39\tocdepth 3
71\paragraph_separation skip 40\paragraph_separation skip
72\defskip medskip 41\defskip medskip
73\quotes_language english 42\quotes_language english
74\quotes_times 2 43\quotes_times 2
75\papercolumns 1 44\papercolumns 1
76\papersides 2 45\papersides 2
77\paperpagestyle fancy 46\paperpagestyle fancy
78 47
79\layout Title 48\layout Title
80 49
81How to use the Opie-Pim API without getting tired! 50How to use the Opie-Pim API without getting tired!
82\newline 51\newline
83(Aka: Hitchhikers Guide Through the Opie-Pim API) 52(Aka: Hitchhikers Guide Through the Opie-Pim API)
84\newline 53\newline
85(Pre V 0.1) 54(V 0.2)
86\layout Author 55\layout Author
87 56
88 57
89\family sans 58\family sans
90Stefan Eilers 59Stefan Eilers (stefan@eilers-online.net)
91\layout Section* 60\layout Section*
92 61
93 62
94\family sans 63\family sans
95Abstract 64Abstract
96\layout Standard 65\layout Standard
97 66
98The Opie-Pim API provides a powerfull access interface to the PIM (Personal 67The Opie-Pim API provides a powerfull access interface to the PIM (Personal
99 Information Management) data which contains your contact information, the 68 Information Management) data which contains your contact information, the
100 dates in your calendar tool (in this paper called datebook events) and 69 dates in your calendar tool (in this paper called datebook events) and
101 your todo events. 70 your todo events.
102 Beside providing full featured access to this information, it covers the 71 Beside providing full featured access to this information, it covers the
103 real management of this informantion - the access of the databases - from 72 real management of this informantion - the access of the databases - from
104 the user. 73 the user.
105 74
106\layout Standard 75\layout Standard
107 76
108While starting to read the automatically generated API-documentation, the 77While starting to read the automatically generated API-documentation, the
109 user may be confused by a lot of unnecessary classes and details which 78 user may be confused by a lot of unnecessary classes and details which
110 makes the quick start not as easy as possible. 79 makes the quick start not as easy as possible.
111 Due to the fact that a user will not need most of the details, this paper 80 Due to the fact that a user will not need most of the details, this paper
112 should help to start to become confortable with those details he need to 81 should help to start to become confortable with those details he need to
113 solve his problems. 82 solve his problems.
114\layout Standard 83\layout Standard
115 84
116 85
86\series bold
87You will find a more recent version at:
88\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apihowto/pim_howto.pdf}
89
90\end_inset
91
92
93\layout Standard
94
95
117\begin_inset LatexCommand \tableofcontents{} 96\begin_inset LatexCommand \tableofcontents{}
118 97
119\end_inset 98\end_inset
120 99
121 100
122\layout Chapter 101\layout Chapter
123 102
124Introduction 103Introduction
125\layout Standard 104\layout Standard
126 105
127Before starting to jump into the work, we should introduce some specialties 106Before starting to jump into the work, we should introduce some specialties
128 of the PIM API, first. 107 of the PIM API, first.
129 To know these facts should help to avoid possible irritations and misunderstand 108 To know these facts should help to avoid possible irritations and misunderstand
130ings: 109ings:
131\layout Enumerate 110\layout Enumerate
132 111
133The PIM-API heavily uses C++ templates (as known as generic classes), but 112The PIM-API heavily uses C++ templates (as known as generic classes), but
134 you don't have to understand very deeple what templates are doing and how 113 you don't have to understand very deeple what templates are doing and how
135 they work! Most of the API works without even seeing the templates. 114 they work! Most of the API works without even seeing the templates.
136 In some cases we have to use them (for instance to use the factory classes), 115 In some cases we have to use them (for instance to use the factory classes),
137 but this guide will provide examples which should help to find the path 116 but this guide will provide examples which should help to find the path
138 through. 117 through.
139 But it is a good idea to read some short introduction of templates to avoid 118 But it is a good idea to read some short introduction of templates to avoid
140 unnecessary mistakes. 119 unnecessary mistakes.
141\layout Enumerate 120\layout Enumerate
142 121
143The PIM-API is split into two parts: The 122The PIM-API is split into two parts: The
144\emph on 123\emph on
145frontend 124frontend
146\emph default 125\emph default
147 and the 126 and the
148\emph on 127\emph on
149backend. 128backend.
150 129
151\emph default 130\emph default
152 While the frontend provides the API for the user, the backend implements 131 While the frontend provides the API for the user, the backend implements
153 how to access the databases and what to do with the data. 132 how to access the databases and what to do with the data.
154 As we just want to access data, this paper just focuses the frontend. 133 As we just want to access data, this paper just focuses the frontend.
155 Thus, you should ignore all classes which contains something like 134 Thus, you should ignore all classes which contains something like
156\begin_inset Quotes gld 135\begin_inset Quotes gld
157\end_inset 136\end_inset
158 137
159backend 138backend
160\begin_inset Quotes grd 139\begin_inset Quotes grd
161\end_inset 140\end_inset
162 141
163 in its name! Backends are just interesting for people who want to extend 142 in its name! Backends are just interesting for people who want to extend
164 or implement new possibilities about how to access databases, which will 143 or implement new possibilities about how to access databases, which will
@@ -172,140 +151,163 @@ backend
172 151
173In the next chapter, we will show how to access the default database as 152In the next chapter, we will show how to access the default database as
174 easy as possible. 153 easy as possible.
175 This will be the solution for most of the problems you may face while accessing 154 This will be the solution for most of the problems you may face while accessing
176 the PIM data. 155 the PIM data.
177\layout Chapter 156\layout Chapter
178 157
179Quick Guide to access the Database 158Quick Guide to access the Database
180\layout Standard 159\layout Standard
181 160
182In this chapter we will introduce very quickly how to get access to the 161In this chapter we will introduce very quickly how to get access to the
183 database and how to access data. 162 database and how to access data.
184 It should help to find the right directions. 163 It should help to find the right directions.
185 If it is too short for you, you should read the next chapter afterwards 164 If it is too short for you, you should read the next chapter afterwards
186 to find a more complete and detailed view into the system. 165 to find a more complete and detailed view into the system.
187\layout Section 166\layout Section
188 167
189Instantiate the access-object 168Instantiate the access-object
190\begin_inset LatexCommand \label{sec:Instantiate-the-Access} 169\begin_inset LatexCommand \label{sec:Instantiate-the-Access}
191 170
192\end_inset 171\end_inset
193 172
194 173
195\layout Standard 174\layout Standard
196 175
197To gain access to the database you need something we will call 176To gain access to the database you need something we will call
198\emph on 177\emph on
199 access-object 178 access-object
200\emph default 179\emph default
201 (an instance of the access-class for the database) which handles the database 180 (an instance of the access-class for the database) which handles the database
202 access. 181 access.
203 Requesting such an object is very easy by using the operation 182 Requesting such an object is very easy by using the operation
204\emph on 183\emph on
205defaultAccess() 184defaultAccess()
206\emph default 185\emph default
207 of the factory class 186 of the factory class
208\series bold 187\series bold
209OPimAccessFactory 188OPimAccessFactory
210\series default 189\series default
211 (see 190 (see
212\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessFactory.html} 191\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessFactory.html}
213 192
214\end_inset 193\end_inset
215 194
216). 195).
217 This operation is defined like this: 196 This operation is defined like this:
218\layout LyX-Code 197\layout LyX-Code
219 198
220T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName) 199T* defaultAccess (
200\newline
201typename OPimGlobal::PimType type,
202\newline
203const QString &appName)
221\layout Standard 204\layout Standard
222 205
223You just have to add the following lines to your source code to use it (this 206You just have to add the following lines to your source code to use it (this
224 example is for accessing the contact database): 207 example is for accessing the contact database):
225\layout LyX-Code 208\layout LyX-Code
226 209
210\layout LyX-Code
211
227#include <opie2/opimaccessfactory.h> 212#include <opie2/opimaccessfactory.h>
228\layout LyX-Code 213\layout LyX-Code
229 214
230use namespace Opie; 215use namespace Opie;
231\layout Standard 216\layout Standard
232 217
233[...] 218[...]
234\layout LyX-Code 219\layout LyX-Code
235 220
236OPimContactAccess* sourceDB = OPimAccessFactory<OPimContactAccess>::defaultAcces 221OPimContactAccess* sourceDB =
237s( OPimGlobal::CONTACTLIST, "my-app" ); 222\newline
223OPimAccessFactory<OPimContactAccess>::defaultAccess(
224\newline
225OPimGlobal::CONTACTLIST,
226\newline
227"my-app" );
228\layout LyX-Code
229
238\layout Standard 230\layout Standard
239 231
240If everything works as expected, you will receive a pointer to the contact 232If everything works as expected, you will receive a pointer to the contact
241 access-class which has to be used for accessing the database. 233 access-class which has to be used for accessing the database.
242 Accessing the datebook database works equally 234 Accessing the datebook database works equally
243\begin_inset Foot 235\begin_inset Foot
244collapsed false 236collapsed false
245 237
246\layout Standard 238\layout Standard
247 239
248The API will be changed in the future: ODateBookAccess will be renamed to 240The API will be changed in the future: ODateBookAccess will be renamed to
249 OPimEventAccess. 241 OPimEventAccess.
250\end_inset 242\end_inset
251 243
252: 244:
253\layout LyX-Code 245\layout LyX-Code
254 246
255ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess( 247ODateBookAccess* sourceDB =
256 OPimGlobal::DATEBOOK, "my-app" ); 248\newline
249OPimAccessFactory<ODatebookAccess>::defaultAccess(
250\newline
251OPimGlobal::DATEBOOK,
252\newline
253"my-app" );
257\layout Standard 254\layout Standard
258 255
259And the same for todo: 256And the same for todo:
260\layout LyX-Code 257\layout LyX-Code
261 258
262OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess( 259OPimTodoAccess* sourceDB =
263 OPimGlobal::TODOLIST, "my-app" ); 260\newline
261OPimAccessFactory<OPimTodoAccess>::defaultAccess(
262\newline
263OPimGlobal::TODOLIST,
264\newline
265"my-app" );
264\layout Standard 266\layout Standard
265 267
266Using 268Using
267\emph on 269\emph on
268 270
269\begin_inset Quotes gld 271\begin_inset Quotes gld
270\end_inset 272\end_inset
271 273
272defaultAccess() 274defaultAccess()
273\begin_inset Quotes grd 275\begin_inset Quotes grd
274\end_inset 276\end_inset
275 277
276 278
277\emph default 279\emph default
278, the default database is accessed automatically 280, the default database is accessed automatically
279\begin_inset Foot 281\begin_inset Foot
280collapsed false 282collapsed false
281 283
282\layout Standard 284\layout Standard
283 285
284The configuration file 286The configuration file
285\begin_inset Quotes gld 287\begin_inset Quotes gld
286\end_inset 288\end_inset
287 289
288pimaccess.conf 290pimaccess.conf
289\begin_inset Quotes grd 291\begin_inset Quotes grd
290\end_inset 292\end_inset
291 293
292 defines which backend is selected as default! 294 defines which backend is selected as default!
293\end_inset 295\end_inset
294 296
295. 297.
296 If you want to use anything else, you have to read the next chapter to 298 If you want to use anything else, you have to read the next chapter to
297 get the information how to do this. 299 get the information how to do this.
298 300
299\layout Standard 301\layout Standard
300 302
301The last parameter 303The last parameter
302\begin_inset Quotes gld 304\begin_inset Quotes gld
303\end_inset 305\end_inset
304 306
305my-app 307my-app
306\begin_inset Quotes grd 308\begin_inset Quotes grd
307\end_inset 309\end_inset
308 310
309 is very importand and should be equal for every instance of an application. 311 is very importand and should be equal for every instance of an application.
310 Some database backends (like the XML backend) uses this string as an unique 312 Some database backends (like the XML backend) uses this string as an unique
311 filename to create a journal file. 313 filename to create a journal file.
@@ -440,132 +442,215 @@ load()
440save() 442save()
441\begin_inset Quotes grd 443\begin_inset Quotes grd
442\end_inset 444\end_inset
443 445
444 operation is important to write back (or 446 operation is important to write back (or
445\emph on 447\emph on
446commit 448commit
447\emph default 449\emph default
448) local changes into the global database. 450) local changes into the global database.
449 After doing this, the changes are globally accessable! The 451 After doing this, the changes are globally accessable! The
450\begin_inset Quotes gld 452\begin_inset Quotes gld
451\end_inset 453\end_inset
452 454
453reload() 455reload()
454\begin_inset Quotes grd 456\begin_inset Quotes grd
455\end_inset 457\end_inset
456 458
457 operation loads changes of the global database into the local set 459 operation loads changes of the global database into the local set
458\series bold 460\series bold
459without 461without
460\series default 462\series default
461 removing any local changes 463 removing any local changes
462\begin_inset Foot 464\begin_inset Foot
463collapsed false 465collapsed false
464 466
465\layout Standard 467\layout Standard
466 468
467We should check whether all databases behave like this! (se) 469We should check whether all databases behave like this! (se)
468\end_inset 470\end_inset
469 471
470. 472.
471 This may be done after receiving information about any change by an other 473 This may be done after receiving information about any change by an other
472 application which is not in scope of this chapter. 474 application which is not in scope of this chapter.
473 The other operations are self explaining and should work as expected. 475 The other operations are self explaining and should work as expected.
474\layout Standard 476\layout Standard
475 477
476If you want to work with the existing dataset, you need to get a list of 478If you want to work with the existing dataset, you need to get a list of
477 all available information. 479 all available information.
478 This list is returned by the call 480 This list is returned by the call
479\begin_inset Quotes gld 481\begin_inset Quotes gld
480\end_inset 482\end_inset
481 483
482allRecords() 484allRecords()
483\begin_inset Quotes grd 485\begin_inset Quotes grd
484\end_inset 486\end_inset
485 487
486 which returns a list of all available records as an 488 which returns a list of all available records as an
487\series bold 489\series bold
488OPimRecordList 490OPimRecordList<T>
489\series default 491\series default
490 (see 492 (see
491\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html} 493\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html}
492 494
493\end_inset 495\end_inset
494 496
495). 497).
496 498 This OPimRecordList is a template and should be used with the right class
499 parameter
500\begin_inset Quotes eld
501\end_inset
502
503T
504\begin_inset Quotes erd
505\end_inset
506
507 which is currently one of the following: OPimContact, OPimTodo and OPimEvent.
497\layout LyX-Code 508\layout LyX-Code
498 509
499List allRecords(); 510OPimRecordList<T> allRecords();
500\layout Standard 511\layout Standard
501 512
502In fact, this 513In fact, this
503\emph on 514\begin_inset Quotes eld
504List 515\end_inset
505\emph default 516
517OPimRecordList<T>
518\begin_inset Quotes erd
519\end_inset
520
506 just contains a list of uid's to take care of memory space. 521 just contains a list of uid's to take care of memory space.
507 As every record is identified by an unique identification number which 522 Every record is identified by an unique identification number which is
508 is called UID (Unique Identification), these numbers just exists once in 523 called UID (Unique Identification).
509 the database which is currently on access! To receive the real record, 524 These numbers just exists once in the database which is currently on access!
510 you have to use the operation 525 To receive the real record, you have to use the operation
511\begin_inset Quotes gld 526\begin_inset Quotes gld
512\end_inset 527\end_inset
513 528
514find() 529find()
515\begin_inset Quotes grd 530\begin_inset Quotes grd
516\end_inset 531\end_inset
517 532
518 with a valid UID as parameter: 533 with a valid UID as parameter:
519\layout LyX-Code 534\layout LyX-Code
520 535
521T find (UID uid); 536T find (UID uid);
522\layout Standard 537\layout Standard
523 538
539The remaining question is, how to get a valid UID out of a list to use the
540
541\begin_inset Quotes eld
542\end_inset
543
544find()
545\begin_inset Quotes erd
546\end_inset
547
548 in a correct manner.
549 This could be done by requesting a special element of the list, using the
550 operator[] or by using iterators.
551 The first one would be like this
552\begin_inset Foot
553collapsed true
554
555\layout Standard
556
557Please do not forget to use
558\begin_inset Quotes eld
559\end_inset
560
561use namespace Opie;
562\begin_inset Quotes erd
563\end_inset
564
565 to enable the namespace
566\begin_inset Quotes eld
567\end_inset
568
569Opie
570\begin_inset Quotes erd
571\end_inset
572
573!!
574\end_inset
575
576:
577\layout LyX-Code
578
579OPimRecordList<OPimContact> list = allRecords();
580\layout LyX-Code
581
582for ( int i = 0; i < list.count(); i++ ){
583\layout LyX-Code
584
585 cout << "The UID is: " << list[i] << endl;
586\layout LyX-Code
587
588}
589\layout Standard
590
591Using the iterator is as easy as the previous one:
592\layout LyX-Code
593
594OPimRecordList<OPimContact> list = allRecords();
595\layout LyX-Code
596
597OPimRecordList<OPimContact>::iterator it;
598\layout LyX-Code
599
600for ( it = list.begin(); it != list.end(); ++it ){
601\layout LyX-Code
602
603 count << "The UID is: " << (*it) << endl;
604\layout LyX-Code
605
606}
607\layout Standard
608
524This is all you need to realize a basic access to the PIM-Databases! The 609This is all you need to realize a basic access to the PIM-Databases! The
525 next chapter will guide you into more details of the PIM-API. 610 next chapter will guide you into more details of the PIM-API.
526\layout Chapter 611\layout Chapter
527 612
528How to Access PIM-Data: Detailed View 613How to Access PIM-Data: Detailed View
529\layout Standard 614\layout Standard
530 615
531As shown in the previous chapter, all we need to access the PIM-Database 616As shown in the previous chapter, all we need to access the PIM-Database
532 is to request an access-object from the OPimAccessFactory and to use it. 617 is to request an access-object from the OPimAccessFactory and to use it.
533 We will now introduce some special features of this factory (see section 618 We will now introduce some special features of this factory (see section
534 619
535\begin_inset LatexCommand \ref{sec:Advanced-Factory-Features} 620\begin_inset LatexCommand \ref{sec:Advanced-Factory-Features}
536 621
537\end_inset 622\end_inset
538 623
539), followed by some very important features like searching and sorting in 624), followed by some very important features like searching and sorting in
540 section 625 section
541\begin_inset LatexCommand \ref{sec:Special-Features:-Searching} 626\begin_inset LatexCommand \ref{sec:Special-Features:-Searching}
542 627
543\end_inset 628\end_inset
544 629
545. 630.
546 If you are interested in accessing data without take care about their types, 631 If you are interested in accessing data without take care about their types,
547 section 632 section
548\begin_inset LatexCommand \ref{sec:Generic-Access:-OPimBase} 633\begin_inset LatexCommand \ref{sec:Generic-Access:-OPimBase}
549 634
550\end_inset 635\end_inset
551 636
552 will show how to do this, followed by a short introduction about delayed 637 will show how to do this, followed by a short introduction about delayed
553 loading in section 638 loading in section
554\begin_inset LatexCommand \ref{sec:Internal-Signal-Handling:} 639\begin_inset LatexCommand \ref{sec:Internal-Signal-Handling:}
555 640
556\end_inset 641\end_inset
557 642
558. 643.
559\layout Standard 644\layout Standard
560 645
561But first we will start with introducing some features of the 646But first we will start with introducing some features of the
562\series bold 647\series bold
563OPimAccessFactory 648OPimAccessFactory
564\series default 649\series default
565. 650.
566\layout Section 651\layout Section
567 652
568Advanced Factory Features 653Advanced Factory Features
569\begin_inset LatexCommand \label{sec:Advanced-Factory-Features} 654\begin_inset LatexCommand \label{sec:Advanced-Factory-Features}
570 655
571\end_inset 656\end_inset
@@ -708,304 +793,282 @@ VCARD
708\end_inset 793\end_inset
709 794
710) should be used to select the desired database backend. 795) should be used to select the desired database backend.
711 The last parameter 796 The last parameter
712\begin_inset Quotes gld 797\begin_inset Quotes gld
713\end_inset 798\end_inset
714 799
715fileName 800fileName
716\begin_inset Quotes grd 801\begin_inset Quotes grd
717\end_inset 802\end_inset
718 803
719 is used to select a special file name and path to the database file. 804 is used to select a special file name and path to the database file.
720 Thus, you can use it to access database files which don't reside on the 805 Thus, you can use it to access database files which don't reside on the
721 default path or have other filenames as it is defined by the platform as 806 default path or have other filenames as it is defined by the platform as
722 default (in normal cases 807 default (in normal cases
723\begin_inset Quotes gld 808\begin_inset Quotes gld
724\end_inset 809\end_inset
725 810
726~/Applications/<name of application>/ 811~/Applications/<name of application>/
727\begin_inset Quotes grd 812\begin_inset Quotes grd
728\end_inset 813\end_inset
729 814
730). 815).
731\layout Standard 816\layout Standard
732 817
733In the next section we will discuss how searching and sorting take place 818In the next section we will discuss how searching and sorting take place
734 with this API. 819 with this API.
735\layout Section 820\layout Section
736 821
737Special Features: Searching and Sorting 822Special Features: Searching and Sorting
738\begin_inset LatexCommand \label{sec:Special-Features:-Searching} 823\begin_inset LatexCommand \label{sec:Special-Features:-Searching}
739 824
740\end_inset 825\end_inset
741 826
742 827
743\layout Standard 828\layout Standard
744 829
745In most cases it is not sufficient to receive just a list of all information 830In most cases it is not sufficient to receive just a list of all information
746 in a database. 831 in a database.
747 It is essential to get a subset of the information available and to be 832 It is essential to get a subset of the information available and to be
748 able to sort it. 833 able to sort it.
749 For this kind of exercise we provide some special operations which provide 834 For this kind of exercise we provide some special operations which provide
750 searching and sorting in an incremental manner 835 searching and sorting in an incremental manner
751\begin_inset Foot 836\begin_inset Foot
752collapsed false 837collapsed false
753 838
754\layout Standard 839\layout Standard
755 840
756FIXME: matchRegexp() does take a list of uid's. 841FIXME: matchRegexp() does not take a list of uid's.
757 Therefore it is currently not possible to use it in an incremental manner! 842 Therefore it is currently not possible to use it in an incremental manner!
758 (se) 843 (se)
759\end_inset 844\end_inset
760 845
761. 846.
762 Therefore it is possible to research a 847 Therefore it is possible to use a list which was returned by a previous
763\begin_inset Quotes gld 848 search query and to sort it afterwards.
764\end_inset
765
766List
767\begin_inset Quotes grd
768\end_inset
769
770 which was returned by a previous search query and to sort it afterwards.
771 Before we will take a close look into sorting, we will start with searching. 849 Before we will take a close look into sorting, we will start with searching.
772 There exist two different ways of searching: 850 There exist two different ways of searching:
773\layout Enumerate 851\layout Enumerate
774 852
775Search a complete database for a special regular expression, using 853Search a complete database for a special regular expression, using
776\begin_inset Quotes gld 854\begin_inset Quotes gld
777\end_inset 855\end_inset
778 856
779matchRegexp () 857matchRegexp ()
780\begin_inset Quotes grd 858\begin_inset Quotes grd
781\end_inset 859\end_inset
782 860
783. 861.
784 This search type returns all records which contains the given regular expressio 862 This search type returns all records which contains the given regular expressio
785n 863n
786\emph on 864\emph on
787anywhere 865anywhere
788\emph default 866\emph default
789 in the dataset. 867 in the dataset.
790 This search type is used for example by the opie search tool (OSearch) 868 This search type is used for example by the opie search tool (OSearch)
791 (see 869 (see
792\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/osearch/} 870\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/osearch/}
793 871
794\end_inset 872\end_inset
795 873
796 and 874 and
797\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/osearch/adresssearch.cpp?rev=1.12&content-type=text/x-cvsweb-markup} 875\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/osearch/adresssearch.cpp?rev=1.12&content-type=text/x-cvsweb-markup}
798 876
799\end_inset 877\end_inset
800 878
801). 879).
802\layout Enumerate 880\layout Enumerate
803 881
804Define a so called 882Define a so called
805\begin_inset Quotes gld 883\begin_inset Quotes gld
806\end_inset 884\end_inset
807 885
808Query By Example 886Query By Example
809\begin_inset Quotes grd 887\begin_inset Quotes grd
810\end_inset 888\end_inset
811 889
812 search query which allows to define what should be searched and which internal 890 search query which allows to define what should be searched and which internal
813 data fields should be taken into account. 891 data fields should be taken into account.
814 This is a very advanced search function which allows to search in a very 892 This is a very advanced search function which allows to search in a very
815 fine granular manner. 893 fine granular manner.
816\layout Standard 894\layout Standard
817 895
818We will start with the first and very simple 896We will start with the first and very simple
819\begin_inset Quotes grd 897\begin_inset Quotes grd
820\end_inset 898\end_inset
821 899
822matchRegexp() 900matchRegexp()
823\begin_inset Quotes grd 901\begin_inset Quotes grd
824\end_inset 902\end_inset
825 903
826, followed by the query by example search query. 904, followed by the query by example search query.
827\layout Subsection 905\layout Subsection
828 906
829Searching with 907Searching with
830\begin_inset Quotes gld 908\begin_inset Quotes gld
831\end_inset 909\end_inset
832 910
833matchRegexp() 911matchRegexp()
834\begin_inset Quotes grd 912\begin_inset Quotes grd
835\end_inset 913\end_inset
836 914
837 915
838\layout Standard 916\layout Standard
839 917
840The function is defined like this: 918The function is defined like this:
841\layout LyX-Code 919\layout LyX-Code
842 920
843List matchRegexp (const QRegExp& r); 921OPimRecordList<T> matchRegexp (const QRegExp& r);
844\layout Standard 922\layout Standard
845 923
846The 924The
847\begin_inset Quotes gld 925\begin_inset Quotes gld
848\end_inset 926\end_inset
849 927
850List 928OPimRecordList<T>
851\begin_inset Quotes grd 929\begin_inset Quotes grd
852\end_inset 930\end_inset
853 931
854 is still a OPimRecordList which contains 0 or more uid's of matching records. 932 is still a list which contains 0 or more uid's of matching records.
855 As already discussed in section 933 As already discussed in section
856\begin_inset LatexCommand \ref{sec:Accessing-the-access-object} 934\begin_inset LatexCommand \ref{sec:Accessing-the-access-object}
857 935
858\end_inset 936\end_inset
859 937
860 you have to use the 938 you have to use the
861\begin_inset Quotes gld 939\begin_inset Quotes gld
862\end_inset 940\end_inset
863 941
864find() 942find()
865\begin_inset Quotes grd 943\begin_inset Quotes grd
866\end_inset 944\end_inset
867 945
868 operation to request the real records. 946 operation to request the real records.
869\layout Subsection 947\layout Subsection
870 948
871Searching with Query By Example 949Searching with Query By Example
872\layout Standard 950\layout Standard
873 951
874The query by example search style is working is using a data object (for 952The query by example search style is working is using a data object (for
875 instance an OPimContact) to store the search query. 953 instance an OPimContact) to store the search query.
876 For instance, if you want to request all entries which contains the last 954 For instance, if you want to request all entries which contains the last
877 name 955 name
878\begin_inset Quotes gld 956\begin_inset Quotes gld
879\end_inset 957\end_inset
880 958
881Eilers 959Eilers
882\begin_inset Quotes grd 960\begin_inset Quotes grd
883\end_inset 961\end_inset
884 962
885 and the home zip number should start with 963 and the home zip number should start with
886\begin_inset Quotes gld 964\begin_inset Quotes gld
887\end_inset 965\end_inset
888 966
8893 9673
890\begin_inset Quotes grd 968\begin_inset Quotes grd
891\end_inset 969\end_inset
892 970
893 you have to do the following: 971 you have to do the following:
894\layout LyX-Code 972\layout LyX-Code
895 973
896OPimContact searchQuery; 974OPimContact searchQuery;
897\layout LyX-Code 975\layout LyX-Code
898 976
899searchQuery.setLastName( 977searchQuery.setLastName( "Eilers" );
900\begin_inset Quotes eld
901\end_inset
902
903Eilers
904\begin_inset Quotes erd
905\end_inset
906
907 );
908\layout LyX-Code 978\layout LyX-Code
909 979
910searchQuery.setHomeZip( 980searchQuery.setHomeZip( "3*" );
911\begin_inset Quotes eld
912\end_inset
913
9143*
915\begin_inset Quotes srd
916\end_inset
917
918 );
919\layout Standard 981\layout Standard
920 982
921We use an usual 983We use an usual
922\begin_inset Quotes gld 984\begin_inset Quotes gld
923\end_inset 985\end_inset
924 986
925OPimContact 987OPimContact
926\begin_inset Quotes grd 988\begin_inset Quotes grd
927\end_inset 989\end_inset
928 990
929 and fill into two fields the query information. 991 and fill into two fields the query information.
930 All filled fields are taken for the search operation (using an 992 All filled fields are taken for the search operation (using an
931\begin_inset Quotes gld 993\begin_inset Quotes gld
932\end_inset 994\end_inset
933 995
934AND 996AND
935\begin_inset Quotes grd 997\begin_inset Quotes grd
936\end_inset 998\end_inset
937 999
938 operation), the unused ones are simply ignored. 1000 operation), the unused ones are simply ignored.
939 As we just want to search for entries which zip number starts with a 1001 As we just want to search for entries which zip number starts with a
940\begin_inset Quotes gld 1002\begin_inset Quotes gld
941\end_inset 1003\end_inset
942 1004
9433 10053
944\begin_inset Quotes grd 1006\begin_inset Quotes grd
945\end_inset 1007\end_inset
946 1008
947 we use the Wildcard 1009 we use the Wildcard
948\begin_inset Quotes gld 1010\begin_inset Quotes gld
949\end_inset 1011\end_inset
950 1012
951* 1013*
952\begin_inset Quotes grd 1014\begin_inset Quotes grd
953\end_inset 1015\end_inset
954 1016
955 as we would do to find files in a filesystem. 1017 as we would do to find files in a filesystem.
956\layout Standard 1018\layout Standard
957 1019
958The next step is to put this query into the operation which is defined like 1020The next step is to put this query into the operation which is defined like
959 this: 1021 this:
960\layout LyX-Code 1022\layout LyX-Code
961 1023
962List queryByExample (const T& query, int querySettings, const QDateTime& 1024OPimRecordList<T> queryByExample (const T& query,
963 startperiod=QDateTime()) 1025\newline
1026int querySettings, const QDateTime& startperiod=QDateTime())
964\layout Standard 1027\layout Standard
965 1028
966The first parameter 1029The first parameter
967\begin_inset Quotes gld 1030\begin_inset Quotes gld
968\end_inset 1031\end_inset
969 1032
970query 1033query
971\begin_inset Quotes grd 1034\begin_inset Quotes grd
972\end_inset 1035\end_inset
973 1036
974 should used to set our query, but we have to set the parameter 1037 should used to set our query, but we have to set the parameter
975\begin_inset Quotes gld 1038\begin_inset Quotes gld
976\end_inset 1039\end_inset
977 1040
978querySettings 1041querySettings
979\begin_inset Quotes grd 1042\begin_inset Quotes grd
980\end_inset 1043\end_inset
981 1044
982 to configure the search properly. 1045 to configure the search properly.
983 This settings are defined by the enumeration 1046 This settings are defined by the enumeration
984\begin_inset Quotes gld 1047\begin_inset Quotes gld
985\end_inset 1048\end_inset
986 1049
987QuerySettings 1050QuerySettings
988\begin_inset Quotes grd 1051\begin_inset Quotes grd
989\end_inset 1052\end_inset
990 1053
991 in the class 1054 in the class
992\series bold 1055\series bold
993OPimBase 1056OPimBase
994\series default 1057\series default
995 (see 1058 (see
996\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w19} 1059\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w19}
997 1060
998\end_inset 1061\end_inset
999 1062
1000). 1063).
1001 The meaning of all settings will be discussed later. 1064 The meaning of all settings will be discussed later.
1002 For the first turn we will just concentrate on the things we need in this 1065 For the first turn we will just concentrate on the things we need in this
1003 case. 1066 case.
1004 As we use Wildcards in 1067 As we use Wildcards in
1005\begin_inset Quotes gld 1068\begin_inset Quotes gld
1006\end_inset 1069\end_inset
1007 1070
1008setHomeZip 1071setHomeZip
1009\begin_inset Quotes grd 1072\begin_inset Quotes grd
1010\end_inset 1073\end_inset
1011 1074
@@ -1025,98 +1088,101 @@ WildCards
1025 1088
1026eilers 1089eilers
1027\begin_inset Quotes grd 1090\begin_inset Quotes grd
1028\end_inset 1091\end_inset
1029 1092
1030, 1093,
1031\begin_inset Quotes gld 1094\begin_inset Quotes gld
1032\end_inset 1095\end_inset
1033 1096
1034eIlers 1097eIlers
1035\begin_inset Quotes grd 1098\begin_inset Quotes grd
1036\end_inset 1099\end_inset
1037 1100
1038, ...). 1101, ...).
1039 Thus, we have to use the 1102 Thus, we have to use the
1040\begin_inset Quotes gld 1103\begin_inset Quotes gld
1041\end_inset 1104\end_inset
1042 1105
1043IgnoreCase 1106IgnoreCase
1044\begin_inset Quotes grd 1107\begin_inset Quotes grd
1045\end_inset 1108\end_inset
1046 1109
1047 setting which is to combine with the other using an 1110 setting which is to combine with the other using an
1048\begin_inset Quotes gld 1111\begin_inset Quotes gld
1049\end_inset 1112\end_inset
1050 1113
1051or 1114or
1052\begin_inset Quotes grd 1115\begin_inset Quotes grd
1053\end_inset 1116\end_inset
1054 1117
1055 operator. 1118 operator.
1056 The last parameter 1119 The last parameter
1057\begin_inset Quotes gld 1120\begin_inset Quotes gld
1058\end_inset 1121\end_inset
1059 1122
1060endperiod 1123endperiod
1061\begin_inset Quotes grd 1124\begin_inset Quotes grd
1062\end_inset 1125\end_inset
1063 1126
1064 will be ignored for this case which will look like this: 1127 will be ignored for this case which will look like this:
1065\layout LyX-Code 1128\layout LyX-Code
1066 1129
1067use namespace Opie; 1130use namespace Opie;
1068\layout LyX-Code 1131\layout LyX-Code
1069 1132
1070[...] 1133[...]
1071\layout LyX-Code 1134\layout LyX-Code
1072 1135
1073List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase:: 1136OPimRecordList<OPimContact> found_items =
1074IgnoreCase ); 1137\newline
1138sourceDB->queryByExample( searchQuery,
1139\newline
1140OPimBase::WildCards | OpimBase::IgnoreCase );
1075\layout Standard 1141\layout Standard
1076 1142
1077This operation may return a list of entries which can be accessed as above, 1143This operation may return a list of entries which can be accessed as above,
1078 using the 1144 using the
1079\begin_inset Quotes gld 1145\begin_inset Quotes gld
1080\end_inset 1146\end_inset
1081 1147
1082find() 1148find()
1083\begin_inset Quotes grd 1149\begin_inset Quotes grd
1084\end_inset 1150\end_inset
1085 1151
1086 operation. 1152 operation.
1087\layout Standard 1153\layout Standard
1088 1154
1089It should be clear at this stage, that this query is very powerful and - 1155It should be clear at this stage, that this query is very powerful and -
1090 depending to the querySettings - could be very complicated to implement. 1156 depending to the querySettings - could be very complicated to implement.
1091 Thus, not all backends do support all features defined by querySettings 1157 Thus, not all backends do support all features defined by querySettings
1092\begin_inset Foot 1158\begin_inset Foot
1093collapsed false 1159collapsed false
1094 1160
1095\layout Standard 1161\layout Standard
1096 1162
1097At this time, just the contact database for XML and VCard is supporting 1163At this time, just the contact database for XML and VCard is supporting
1098 all queries and combination of them. 1164 all queries and combination of them.
1099 All others just support subsets. 1165 All others just support subsets.
1100\end_inset 1166\end_inset
1101 1167
1102. 1168.
1103 To check which settings are supported and to be able to react dynamically 1169 To check which settings are supported and to be able to react dynamically
1104 on missing features (for instance to disable some search features in the 1170 on missing features (for instance to disable some search features in the
1105 application) we provide the following operations: 1171 application) we provide the following operations:
1106\layout LyX-Code 1172\layout LyX-Code
1107 1173
1108bool hasQuerySettings( uint querySettings ); 1174bool hasQuerySettings( uint querySettings );
1109\layout LyX-Code 1175\layout LyX-Code
1110 1176
1111uint querySettings(); 1177uint querySettings();
1112\layout Standard 1178\layout Standard
1113 1179
1114The first operation 1180The first operation
1115\begin_inset Quotes gld 1181\begin_inset Quotes gld
1116\end_inset 1182\end_inset
1117 1183
1118hasQuerySettings() 1184hasQuerySettings()
1119\begin_inset Quotes grd 1185\begin_inset Quotes grd
1120\end_inset 1186\end_inset
1121 1187
1122 may be used to ask whether the database can handle the given query settings. 1188 may be used to ask whether the database can handle the given query settings.
@@ -1172,101 +1238,109 @@ In some cases, a time interval should be set to find for instance all entries
1172\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} 1238\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}
1173 1239
1174\end_inset 1240\end_inset
1175 1241
1176)) as requested by the setting 1242)) as requested by the setting
1177\begin_inset Quotes gld 1243\begin_inset Quotes gld
1178\end_inset 1244\end_inset
1179 1245
1180OPimBase::DateDiff 1246OPimBase::DateDiff
1181\begin_inset Quotes grd 1247\begin_inset Quotes grd
1182\end_inset 1248\end_inset
1183 1249
1184. 1250.
1185 The date and time in the query object is used as the 1251 The date and time in the query object is used as the
1186\series bold 1252\series bold
1187end 1253end
1188\series default 1254\series default
1189 of the interval. 1255 of the interval.
1190 The start will be defined by the last parameter (if nothing is set, the 1256 The start will be defined by the last parameter (if nothing is set, the
1191 current date will be taken!). 1257 current date will be taken!).
1192 Therefore, it is possible to set a time frame for all searched entries. 1258 Therefore, it is possible to set a time frame for all searched entries.
1193\layout Standard 1259\layout Standard
1194 1260
1195If you want to do incremental search operations, you may use the special 1261If you want to do incremental search operations, you may use the special
1196 1262
1197\begin_inset Quotes gld 1263\begin_inset Quotes gld
1198\end_inset 1264\end_inset
1199 1265
1200queryByExample() 1266queryByExample()
1201\begin_inset Quotes grd 1267\begin_inset Quotes grd
1202\end_inset 1268\end_inset
1203 1269
1204 which takes a 1270 which takes a
1205\begin_inset Quotes gld 1271\begin_inset Quotes gld
1206\end_inset 1272\end_inset
1207 1273
1208List 1274List
1209\begin_inset Quotes grd 1275\begin_inset Quotes grd
1210\end_inset 1276\end_inset
1211 1277
1212 as the first parameter. 1278 as the first parameter.
1213 The search operation will just occur on this set of uid's! 1279 The search operation will just occur on this set of uid's!
1214\layout Subsection 1280\layout Subsection
1215 1281
1216Sorting 1282Sorting
1217\layout Standard 1283\layout Standard
1218 1284
1219To sort a given dataset, you should use the following operation (or one 1285To sort a given dataset, you should use the following operation (or one
1220 of the others which behave slightly differently): 1286 of the others which behave slightly differently, see
1287\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessTemplate.html}
1288
1289\end_inset
1290
1291):
1221\layout LyX-Code 1292\layout LyX-Code
1222 1293
1223List sorted (const List& list, bool ascending, int sortOrder, int sortFilter, 1294OPimRecordList<T> sorted (const List& list,
1224 const QArray< UID >& cats); 1295\newline
1296bool ascending, int sortOrder, int sortFilter,
1297\newline
1298const QArray< UID >& cats);
1225\layout Standard 1299\layout Standard
1226 1300
1227This sort operation takes a list of uid's as returned for instance from 1301This sort operation takes a list of uid's as returned for instance from
1228 a search query. 1302 a search query.
1229 The parameter 1303 The parameter
1230\begin_inset Quotes gld 1304\begin_inset Quotes gld
1231\end_inset 1305\end_inset
1232 1306
1233ascending 1307ascending
1234\begin_inset Quotes grd 1308\begin_inset Quotes grd
1235\end_inset 1309\end_inset
1236 1310
1237 defines whether the sort should be in an ascending order or not. 1311 defines whether the sort should be in an ascending order or not.
1238 1312
1239\begin_inset Quotes gld 1313\begin_inset Quotes gld
1240\end_inset 1314\end_inset
1241 1315
1242sortOrder 1316sortOrder
1243\begin_inset Quotes grd 1317\begin_inset Quotes grd
1244\end_inset 1318\end_inset
1245 1319
1246 is defined by the enumerations 1320 is defined by the enumerations
1247\begin_inset Quotes gld 1321\begin_inset Quotes gld
1248\end_inset 1322\end_inset
1249 1323
1250SortOrder 1324SortOrder
1251\begin_inset Quotes grd 1325\begin_inset Quotes grd
1252\end_inset 1326\end_inset
1253 1327
1254 and 1328 and
1255\begin_inset Quotes gld 1329\begin_inset Quotes gld
1256\end_inset 1330\end_inset
1257 1331
1258SortOrderBase 1332SortOrderBase
1259\begin_inset Quotes grd 1333\begin_inset Quotes grd
1260\end_inset 1334\end_inset
1261 1335
1262 and defines which field should be used to sort (see for 1336 and defines which field should be used to sort (see for
1263\series bold 1337\series bold
1264OPimContactAccess 1338OPimContactAccess
1265\series default 1339\series default
1266: 1340:
1267\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContactAccess.html} 1341\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContactAccess.html}
1268 1342
1269\end_inset 1343\end_inset
1270 1344
1271, for 1345, for
1272\series bold 1346\series bold