summaryrefslogtreecommitdiff
Unidiff
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
@@ -43,43 +43,43 @@
43 \fi 43 \fi
44 \columnseprule \z@ 44 \columnseprule \z@
45 \columnsep 35\p@ 45 \columnsep 35\p@
46 \twocolumn[\refstepcounter{section}% 46 \twocolumn[\refstepcounter{section}%
47 \section{\indexname}]% 47 \section{\indexname}]%
48 \@mkboth{\MakeUppercase\indexname}% 48 \@mkboth{\MakeUppercase\indexname}%
49 {\MakeUppercase\indexname}% 49 {\MakeUppercase\indexname}%
50 \thispagestyle{plain}\parindent\z@ 50 \thispagestyle{plain}\parindent\z@
51 \parskip\z@ \@plus .3\p@\relax 51 \parskip\z@ \@plus .3\p@\relax
52 \let\item\@idxitem} 52 \let\item\@idxitem}
53 {\if@restonecol\onecolumn\else\clearpage\fi} 53 {\if@restonecol\onecolumn\else\clearpage\fi}
54\end_preamble 54\end_preamble
55\language german 55\language american
56\inputencoding auto 56\inputencoding default
57\fontscheme ae 57\fontscheme ae
58\graphics default 58\graphics default
59\float_placement htbp 59\float_placement htbp
60\paperfontsize default 60\paperfontsize default
61\spacing single 61\spacing single
62\papersize a4paper 62\papersize a4paper
63\paperpackage widemarginsa4 63\paperpackage widemarginsa4
64\use_geometry 0 64\use_geometry 0
65\use_amsmath 0 65\use_amsmath 0
66\use_natbib 0 66\use_natbib 0
67\use_numerical_citations 0 67\use_numerical_citations 0
68\paperorientation portrait 68\paperorientation portrait
69\secnumdepth 3 69\secnumdepth 3
70\tocdepth 3 70\tocdepth 3
71\paragraph_separation skip 71\paragraph_separation skip
72\defskip medskip 72\defskip medskip
73\quotes_language german 73\quotes_language english
74\quotes_times 2 74\quotes_times 2
75\papercolumns 1 75\papercolumns 1
76\papersides 2 76\papersides 2
77\paperpagestyle fancy 77\paperpagestyle fancy
78 78
79\layout Title 79\layout Title
80 80
81How to use the Opie-Pim API without getting tired! 81How to use the Opie-Pim API without getting tired!
82\newline 82\newline
83(Aka: Hitchhikers Guide Through the Opie-Pim API) 83(Aka: Hitchhikers Guide Through the Opie-Pim API)
84\newline 84\newline
85(Pre V 0.1) 85(Pre V 0.1)
@@ -88,89 +88,89 @@ How to use the Opie-Pim API without getting tired!
88 88
89\family sans 89\family sans
90Stefan Eilers 90Stefan Eilers
91\layout Section* 91\layout Section*
92 92
93 93
94\family sans 94\family sans
95Abstract 95Abstract
96\layout Standard 96\layout Standard
97 97
98The Opie-Pim API provides a powerfull access interface to the PIM (Personal 98The Opie-Pim API provides a powerfull access interface to the PIM (Personal
99 Information Management) data which contains your contact information, the 99 Information Management) data which contains your contact information, the
100 dates in your calender tool (in this paper called datebook events) and 100 dates in your calendar tool (in this paper called datebook events) and
101 your todo events. 101 your todo events.
102 Beside providing full featured access to this information, it covers the 102 Beside providing full featured access to this information, it covers the
103 real management of this informantion - the access of the databases - from 103 real management of this informantion - the access of the databases - from
104 the user. 104 the user.
105 105
106\layout Standard 106\layout Standard
107 107
108While starting to read the automatically generated API-documentation, the 108While starting to read the automatically generated API-documentation, the
109 user may be confused by a lot of unneccessary classes and details which 109 user may be confused by a lot of unnecessary classes and details which
110 makes the quick start not as easy as possible. 110 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 111 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 112 should help to start to become confortable with those details he need to
113 solve his problems. 113 solve his problems.
114\layout Standard 114\layout Standard
115 115
116 116
117\begin_inset LatexCommand \tableofcontents{} 117\begin_inset LatexCommand \tableofcontents{}
118 118
119\end_inset 119\end_inset
120 120
121 121
122\layout Chapter 122\layout Chapter
123 123
124Introduction 124Introduction
125\layout Standard 125\layout Standard
126 126
127Before starting to jump into the work, we should introduce some specialities 127Before starting to jump into the work, we should introduce some specialties
128 of the PIM API, first. 128 of the PIM API, first.
129 To know these facts should help to avoid possible irritations and misunderstand 129 To know these facts should help to avoid possible irritations and misunderstand
130ings: 130ings:
131\layout Enumerate 131\layout Enumerate
132 132
133The PIM-API heavily uses C++ templates (as known as generic classes), but 133The 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 134 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. 135 they work! Most of the API works without even seeing the templates.
136 In some cases whe have to use them (for instance to use the factory classes), 136 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 137 but this guide will provide examples which should help to find the path
138 through. 138 through.
139 But it is a good idea to read some short introduction of templates to avoid 139 But it is a good idea to read some short introduction of templates to avoid
140 unneccessary mistakes. 140 unnecessary mistakes.
141\layout Enumerate 141\layout Enumerate
142 142
143The PIM-API is split into two parts: The 143The PIM-API is split into two parts: The
144\emph on 144\emph on
145frontend 145frontend
146\emph default 146\emph default
147 and the 147 and the
148\emph on 148\emph on
149backend. 149backend.
150 150
151\emph default 151\emph default
152 While the frontend provides the API for the user, the backend implements 152 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. 153 how to access the databases and what to do with the data.
154 As we just want to access data, this paper just focusses the frontend. 154 As we just want to access data, this paper just focuses the frontend.
155 Thus, you should ignore all classes which contains something like 155 Thus, you should ignore all classes which contains something like
156\begin_inset Quotes gld 156\begin_inset Quotes gld
157\end_inset 157\end_inset
158 158
159backend 159backend
160\begin_inset Quotes grd 160\begin_inset Quotes grd
161\end_inset 161\end_inset
162 162
163 in its name! Backends are just interessting for people who want to extend 163 in its name! Backends are just interesting for people who want to extend
164 or implement new possiblities about how to access databases, which will 164 or implement new possibilities about how to access databases, which will
165 be discussed at the end of this paper. 165 be discussed at the end of this paper.
166 Currently, you just have to understand that there do exist several backends 166 Currently, you just have to understand that there do exist several backends
167 for every type of PIM data (Contact, Todo, Datebook) which controls whether 167 for every type of PIM data (Contact, Todo, Datebook) which controls whether
168 you want to access an XML, SQL (SQLite) or VCard style database. 168 you want to access an XML, SQL (SQLite) or VCard style database.
169 If you just want to use the default database, you even don't have to think 169 If you just want to use the default database, you even don't have to think
170 about this! 170 about this!
171\layout Standard 171\layout Standard
172 172
173In the next chapter, we will show how to access the default database as 173In the next chapter, we will show how to access the default database as
174 easy as possible. 174 easy as possible.
175 This will be the solution for most of the problems you may face while accessing 175 This will be the solution for most of the problems you may face while accessing
176 the PIM data. 176 the PIM data.
@@ -208,49 +208,49 @@ defaultAccess()
208\series bold 208\series bold
209OPimAccessFactory 209OPimAccessFactory
210\series default 210\series default
211 (see 211 (see
212\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessFactory.html} 212\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessFactory.html}
213 213
214\end_inset 214\end_inset
215 215
216). 216).
217 This operation is defined like this: 217 This operation is defined like this:
218\layout LyX-Code 218\layout LyX-Code
219 219
220T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName) 220T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName)
221\layout Standard 221\layout Standard
222 222
223You just have to add the following lines to your source code to use it (this 223You just have to add the following lines to your source code to use it (this
224 example is for accessing the contact database): 224 example is for accessing the contact database):
225\layout LyX-Code 225\layout LyX-Code
226 226
227#include <opie2/opimaccessfactory.h> 227#include <opie2/opimaccessfactory.h>
228\layout LyX-Code 228\layout LyX-Code
229 229
230use namespace Opie; 230use namespace Opie;
231\layout Standard 231\layout Standard
232 232
233[...] 233[...]
234\layout LyX-Code 234\layout LyX-Code
235 235
236OPimContactAccess* sourceDB = OPimAccessFactory<OPimContactAccess>::defaultAcces 236OPimContactAccess* sourceDB = OPimAccessFactory<OPimContactAccess>::defaultAcces
237s( OPimGlobal::CONTACTLIST, "my-app" ); 237s( OPimGlobal::CONTACTLIST, "my-app" );
238\layout Standard 238\layout Standard
239 239
240If everything works as expected, you will receive a pointer to the contact 240If everything works as expected, you will receive a pointer to the contact
241 access-class which has to be used for accessing the database. 241 access-class which has to be used for accessing the database.
242 Accessing the datebook database works equally 242 Accessing the datebook database works equally
243\begin_inset Foot 243\begin_inset Foot
244collapsed true 244collapsed false
245 245
246\layout Standard 246\layout Standard
247 247
248The API will be changed in the future: ODateBookAccess will be renamed to 248The API will be changed in the future: ODateBookAccess will be renamed to
249 OPimEventAccess. 249 OPimEventAccess.
250\end_inset 250\end_inset
251 251
252: 252:
253\layout LyX-Code 253\layout LyX-Code
254 254
255ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess( 255ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess(
256 OPimGlobal::DATEBOOK, "my-app" ); 256 OPimGlobal::DATEBOOK, "my-app" );
@@ -266,27 +266,27 @@ OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess(
266Using 266Using
267\emph on 267\emph on
268 268
269\begin_inset Quotes gld 269\begin_inset Quotes gld
270\end_inset 270\end_inset
271 271
272defaultAccess() 272defaultAccess()
273\begin_inset Quotes grd 273\begin_inset Quotes grd
274\end_inset 274\end_inset
275 275
276 276
277\emph default 277\emph default
278, the default dabase is accessed automatically 278, the default database is accessed automatically
279\begin_inset Foot 279\begin_inset Foot
280collapsed true 280collapsed false
281 281
282\layout Standard 282\layout Standard
283 283
284The configuration file 284The configuration file
285\begin_inset Quotes gld 285\begin_inset Quotes gld
286\end_inset 286\end_inset
287 287
288pimaccess.conf 288pimaccess.conf
289\begin_inset Quotes grd 289\begin_inset Quotes grd
290\end_inset 290\end_inset
291 291
292 defines which backend is selected as default! 292 defines which backend is selected as default!
@@ -351,85 +351,85 @@ OPimAccessTemplate
351\end_inset 351\end_inset
352 352
353T 353T
354\begin_inset Quotes grd 354\begin_inset Quotes grd
355\end_inset 355\end_inset
356 356
357 below with the corresponding 357 below with the corresponding
358\emph on 358\emph on
359data-class 359data-class
360\emph default 360\emph default
361 for the selected access-class: OPimContact 361 for the selected access-class: OPimContact
362\begin_inset Foot 362\begin_inset Foot
363collapsed true 363collapsed false
364 364
365\layout Standard 365\layout Standard
366 366
367see 367see
368\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContact.html} 368\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContact.html}
369 369
370\end_inset 370\end_inset
371 371
372 372
373\end_inset 373\end_inset
374 374
375 for OPimContactAccess, OPimEvent 375 for OPimContactAccess, OPimEvent
376\begin_inset Foot 376\begin_inset Foot
377collapsed true 377collapsed false
378 378
379\layout Standard 379\layout Standard
380 380
381see 381see
382\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimEvent.html} 382\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimEvent.html}
383 383
384\end_inset 384\end_inset
385 385
386 386
387\end_inset 387\end_inset
388 388
389 for ODateBookAccess and OPimTodo 389 for ODateBookAccess and OPimTodo
390\begin_inset Foot 390\begin_inset Foot
391collapsed true 391collapsed false
392 392
393\layout Standard 393\layout Standard
394 394
395see 395see
396\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodo.html} 396\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodo.html}
397 397
398\end_inset 398\end_inset
399 399
400 400
401\end_inset 401\end_inset
402 402
403 for OPimTodoAccess): 403 for OPimTodoAccess):
404\layout LyX-Code 404\layout LyX-Code
405 405
406bool load (); 406bool load ();
407\layout LyX-Code 407\layout LyX-Code
408 408
409bool reload (); 409bool reload ();
410\layout LyX-Code 410\layout LyX-Code
411 411
412bool save (); 412bool save ();
413\layout LyX-Code 413\layout LyX-Code
414 414
415\layout LyX-Code 415\layout LyX-Code
416 416
417bool add (const T& t); 417bool add (const T& t);
418\layout LyX-Code 418\layout LyX-Code
419 419
420bool remove (const T& t); 420bool remove (const T& t);
421\layout LyX-Code 421\layout LyX-Code
422 422
423bool replace (const T& t); 423bool replace (const T& t);
424\layout Standard 424\layout Standard
425 425
426After receiving an access-object, we have to load the existing dataset into 426After receiving an access-object, we have to load the existing dataset into
427 the backend, which is done by the 427 the backend, which is done by the
428\begin_inset Quotes gld 428\begin_inset Quotes gld
429\end_inset 429\end_inset
430 430
431load() 431load()
432\begin_inset Quotes grd 432\begin_inset Quotes grd
433\end_inset 433\end_inset
434 434
435 operation. 435 operation.
@@ -451,29 +451,29 @@ commit
451\end_inset 451\end_inset
452 452
453reload() 453reload()
454\begin_inset Quotes grd 454\begin_inset Quotes grd
455\end_inset 455\end_inset
456 456
457 operation loads changes of the global database into the local set 457 operation loads changes of the global database into the local set
458\series bold 458\series bold
459without 459without
460\series default 460\series default
461 removing any local changes 461 removing any local changes
462\begin_inset Foot 462\begin_inset Foot
463collapsed true 463collapsed false
464 464
465\layout Standard 465\layout Standard
466 466
467We should check whether all dabases behave like this! (se) 467We should check whether all databases behave like this! (se)
468\end_inset 468\end_inset
469 469
470. 470.
471 This may be done after receiving information about any change by an other 471 This may be done after receiving information about any change by an other
472 application which is not in scope of this chapter. 472 application which is not in scope of this chapter.
473 The other operations are self explaining and should work as expected. 473 The other operations are self explaining and should work as expected.
474\layout Standard 474\layout Standard
475 475
476If you want to work with the existing dataset, you need to get a list of 476If you want to work with the existing dataset, you need to get a list of
477 all available information. 477 all available information.
478 This list is returned by the call 478 This list is returned by the call
479\begin_inset Quotes gld 479\begin_inset Quotes gld
@@ -487,47 +487,47 @@ allRecords()
487\series bold 487\series bold
488OPimRecordList 488OPimRecordList
489\series default 489\series default
490 (see 490 (see
491\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html} 491\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html}
492 492
493\end_inset 493\end_inset
494 494
495). 495).
496 496
497\layout LyX-Code 497\layout LyX-Code
498 498
499List allRecords (); 499List allRecords();
500\layout Standard 500\layout Standard
501 501
502In fact, this 502In fact, this
503\emph on 503\emph on
504List 504List
505\emph default 505\emph default
506 just contains a list of uid's to take care of memory space. 506 just contains a list of uid's to take care of memory space.
507 As every record is identified by an unique identifaction number which is 507 As every record is identified by an unique identification number which
508 called UID (Unique IDentification), these numbers just exists once in the 508 is called UID (Unique Identification), these numbers just exists once in
509 database which is currently on access! To receive the real record, you 509 the database which is currently on access! To receive the real record,
510 have to use the operation 510 you have to use the operation
511\begin_inset Quotes gld 511\begin_inset Quotes gld
512\end_inset 512\end_inset
513 513
514find() 514find()
515\begin_inset Quotes grd 515\begin_inset Quotes grd
516\end_inset 516\end_inset
517 517
518 with a valid UID as paramter: 518 with a valid UID as parameter:
519\layout LyX-Code 519\layout LyX-Code
520 520
521T find (UID uid); 521T find (UID uid);
522\layout Standard 522\layout Standard
523 523
524This is all you need to realize a basic access to the PIM-Databases! The 524This 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. 525 next chapter will guide you into more details of the PIM-API.
526\layout Chapter 526\layout Chapter
527 527
528How to Access PIM-Data: Detailed View 528How to Access PIM-Data: Detailed View
529\layout Standard 529\layout Standard
530 530
531As shown in the previous chapter, all we need to access the PIM-Database 531As 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. 532 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 533 We will now introduce some special features of this factory (see section
@@ -549,48 +549,48 @@ As shown in the previous chapter, all we need to access the PIM-Database
549 549
550\end_inset 550\end_inset
551 551
552 will show how to do this, followed by a short introduction about delayed 552 will show how to do this, followed by a short introduction about delayed
553 loading in section 553 loading in section
554\begin_inset LatexCommand \ref{sec:Internal-Signal-Handling:} 554\begin_inset LatexCommand \ref{sec:Internal-Signal-Handling:}
555 555
556\end_inset 556\end_inset
557 557
558. 558.
559\layout Standard 559\layout Standard
560 560
561But first we will start with intoducing some features of the 561But first we will start with introducing some features of the
562\series bold 562\series bold
563OPimAccessFactory 563OPimAccessFactory
564\series default 564\series default
565. 565.
566\layout Section 566\layout Section
567 567
568Advanced Factory Features 568Advanced Factory Features
569\begin_inset LatexCommand \label{sec:Advanced-Factory-Features} 569\begin_inset LatexCommand \label{sec:Advanced-Factory-Features}
570 570
571\end_inset 571\end_inset
572 572
573 573
574\layout Standard 574\layout Standard
575 575
576In the previous chapter we used the operation 576In the previous chapter we used the operation
577\begin_inset Quotes gld 577\begin_inset Quotes gld
578\end_inset 578\end_inset
579 579
580defaultAccess() 580defaultAccess()
581\begin_inset Quotes grd 581\begin_inset Quotes grd
582\end_inset 582\end_inset
583 583
584 to request an access-object to the dafault backend. 584 to request an access-object to the default backend.
585 Whether this default backend will access the XML, VCard or SQLite database 585 Whether this default backend will access the XML, VCard or SQLite database
586 type, is defined by the configuration file 586 type, is defined by the configuration file
587\begin_inset Quotes gld 587\begin_inset Quotes gld
588\end_inset 588\end_inset
589 589
590pimaccess.conf 590pimaccess.conf
591\begin_inset Quotes grd 591\begin_inset Quotes grd
592\end_inset 592\end_inset
593 593
594 which is stored in the directory 594 which is stored in the directory
595\begin_inset Quotes gld 595\begin_inset Quotes gld
596\end_inset 596\end_inset
@@ -607,36 +607,36 @@ Settings
607defaultAccess() 607defaultAccess()
608\begin_inset Quotes grd 608\begin_inset Quotes grd
609\end_inset 609\end_inset
610 610
611. 611.
612 Therefore it is not a good idea to modify a global setting, if an application 612 Therefore it is not a good idea to modify a global setting, if an application
613 should access a special database type, for instance to move data from one 613 should access a special database type, for instance to move data from one
614 database to an other. 614 database to an other.
615 615
616\layout Standard 616\layout Standard
617 617
618If the developer wants to select a special database type for sure without 618If the developer wants to select a special database type for sure without
619 unnecessary side effects, he has to use the oparation 619 unnecessary side effects, he has to use the operation
620\emph on 620\emph on
621create() 621create()
622\emph default 622\emph default
623 which has the following parameters: 623 which has the following parameters:
624\layout LyX-Code 624\layout LyX-Code
625 625
626T * create (OPimGlobal::PimType type, OPimGlobal::DatabaseStyle dbStyle, 626T* create (OPimGlobal::PimType type, OPimGlobal::DatabaseStyle dbStyle,
627 const QString &appName, const QString &fileName=QString::null) 627 const QString &appName, const QString &fileName=QString::null)
628\layout Standard 628\layout Standard
629 629
630Some paramters are already known, like type and appName (see section 630Some parameters are already known, like type and appName (see section
631\begin_inset LatexCommand \ref{sec:Instantiate-the-Access} 631\begin_inset LatexCommand \ref{sec:Instantiate-the-Access}
632 632
633\end_inset 633\end_inset
634 634
635). 635).
636 The new parameter 636 The new parameter
637\begin_inset Quotes gld 637\begin_inset Quotes gld
638\end_inset 638\end_inset
639 639
640dbStyle 640dbStyle
641\begin_inset Quotes grd 641\begin_inset Quotes grd
642\end_inset 642\end_inset
@@ -737,28 +737,28 @@ In the next section we will discuss how searching and sorting take place
737Special Features: Searching and Sorting 737Special Features: Searching and Sorting
738\begin_inset LatexCommand \label{sec:Special-Features:-Searching} 738\begin_inset LatexCommand \label{sec:Special-Features:-Searching}
739 739
740\end_inset 740\end_inset
741 741
742 742
743\layout Standard 743\layout Standard
744 744
745In most cases it is not sufficient to receive just a list of all information 745In most cases it is not sufficient to receive just a list of all information
746 in a database. 746 in a database.
747 It is essential to get a subset of the information available and to be 747 It is essential to get a subset of the information available and to be
748 able to sort it. 748 able to sort it.
749 For this kind of excercise we provide some special operations which provide 749 For this kind of exercise we provide some special operations which provide
750 searching and sorting in an incremental manner 750 searching and sorting in an incremental manner
751\begin_inset Foot 751\begin_inset Foot
752collapsed true 752collapsed false
753 753
754\layout Standard 754\layout Standard
755 755
756FIXME: matchRegexp() does take a list of uid's. 756FIXME: matchRegexp() does take a list of uid's.
757 Therefore it is currently not possible to use it in an incremental manner! 757 Therefore it is currently not possible to use it in an incremental manner!
758 (se) 758 (se)
759\end_inset 759\end_inset
760 760
761. 761.
762 Therefore it is possible to research a 762 Therefore it is possible to research a
763\begin_inset Quotes gld 763\begin_inset Quotes gld
764\end_inset 764\end_inset
@@ -831,25 +831,25 @@ Searching with
831\end_inset 831\end_inset
832 832
833matchRegexp() 833matchRegexp()
834\begin_inset Quotes grd 834\begin_inset Quotes grd
835\end_inset 835\end_inset
836 836
837 837
838\layout Standard 838\layout Standard
839 839
840The function is defined like this: 840The function is defined like this:
841\layout LyX-Code 841\layout LyX-Code
842 842
843List matchRegexp (const QRegExp &r); 843List matchRegexp (const QRegExp& r);
844\layout Standard 844\layout Standard
845 845
846The 846The
847\begin_inset Quotes gld 847\begin_inset Quotes gld
848\end_inset 848\end_inset
849 849
850List 850List
851\begin_inset Quotes grd 851\begin_inset Quotes grd
852\end_inset 852\end_inset
853 853
854 is still a OPimRecordList which contains 0 or more uid's of matching records. 854 is still a OPimRecordList which contains 0 or more uid's of matching records.
855 As already discussed in section 855 As already discussed in section
@@ -888,40 +888,40 @@ Eilers
888 888
8893 8893
890\begin_inset Quotes grd 890\begin_inset Quotes grd
891\end_inset 891\end_inset
892 892
893 you have to do the following: 893 you have to do the following:
894\layout LyX-Code 894\layout LyX-Code
895 895
896OPimContact searchQuery; 896OPimContact searchQuery;
897\layout LyX-Code 897\layout LyX-Code
898 898
899searchQuery.setLastName( 899searchQuery.setLastName(
900\begin_inset Quotes gld 900\begin_inset Quotes eld
901\end_inset 901\end_inset
902 902
903Eilers 903Eilers
904\begin_inset Quotes grd 904\begin_inset Quotes erd
905\end_inset 905\end_inset
906 906
907 ); 907 );
908\layout LyX-Code 908\layout LyX-Code
909 909
910searchQuery.setHomeZip( 910searchQuery.setHomeZip(
911\begin_inset Quotes gld 911\begin_inset Quotes eld
912\end_inset 912\end_inset
913 913
9143* 9143*
915\begin_inset Quotes grd 915\begin_inset Quotes srd
916\end_inset 916\end_inset
917 917
918 ); 918 );
919\layout Standard 919\layout Standard
920 920
921We use an usual 921We use an usual
922\begin_inset Quotes gld 922\begin_inset Quotes gld
923\end_inset 923\end_inset
924 924
925OPimContact 925OPimContact
926\begin_inset Quotes grd 926\begin_inset Quotes grd
927\end_inset 927\end_inset
@@ -950,46 +950,54 @@ AND
950 950
951* 951*
952\begin_inset Quotes grd 952\begin_inset Quotes grd
953\end_inset 953\end_inset
954 954
955 as we would do to find files in a filesystem. 955 as we would do to find files in a filesystem.
956\layout Standard 956\layout Standard
957 957
958The next step is to put this query into the operation which is defined like 958The next step is to put this query into the operation which is defined like
959 this: 959 this:
960\layout LyX-Code 960\layout LyX-Code
961 961
962List queryByExample (const T& query, int querySettings, const QDateTime 962List queryByExample (const T& query, int querySettings, const QDateTime&
963 &startperiod=QDateTime()) 963 startperiod=QDateTime())
964\layout Standard 964\layout Standard
965 965
966The first parameter 966The first parameter
967\begin_inset Quotes gld 967\begin_inset Quotes gld
968\end_inset 968\end_inset
969 969
970query 970query
971\begin_inset Quotes grd 971\begin_inset Quotes grd
972\end_inset 972\end_inset
973 973
974 should used to set our query, but we have to set the parameter 974 should used to set our query, but we have to set the parameter
975\begin_inset Quotes gld 975\begin_inset Quotes gld
976\end_inset 976\end_inset
977 977
978querySettings 978querySettings
979\begin_inset Quotes grd 979\begin_inset Quotes grd
980\end_inset 980\end_inset
981 981
982 to configure the search properly. 982 to configure the search properly.
983 This settings are defined by the enum QuerySettings in the class 983 This settings are defined by the enumeration
984\begin_inset Quotes gld
985\end_inset
986
987QuerySettings
988\begin_inset Quotes grd
989\end_inset
990
991 in the class
984\series bold 992\series bold
985OPimBase 993OPimBase
986\series default 994\series default
987 (see 995 (see
988\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w19} 996\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w19}
989 997
990\end_inset 998\end_inset
991 999
992). 1000).
993 The meaning of all settings will be discussed later. 1001 The meaning of all settings will be discussed later.
994 For the first turn we will just concentrate on the things we need in this 1002 For the first turn we will just concentrate on the things we need in this
995 case. 1003 case.
@@ -1073,43 +1081,43 @@ This operation may return a list of entries which can be accessed as above,
1073 1081
1074find() 1082find()
1075\begin_inset Quotes grd 1083\begin_inset Quotes grd
1076\end_inset 1084\end_inset
1077 1085
1078 operation. 1086 operation.
1079\layout Standard 1087\layout Standard
1080 1088
1081It should be clear at this stage, that this query is very powerful and - 1089It should be clear at this stage, that this query is very powerful and -
1082 depending to the querySettings - could be very complicated to implement. 1090 depending to the querySettings - could be very complicated to implement.
1083 Thus, not all backends do support all features defined by querySettings 1091 Thus, not all backends do support all features defined by querySettings
1084\begin_inset Foot 1092\begin_inset Foot
1085collapsed true 1093collapsed false
1086 1094
1087\layout Standard 1095\layout Standard
1088 1096
1089At this time, just the contact database for XML and VCard is supporting 1097At this time, just the contact database for XML and VCard is supporting
1090 all queries and combination of them. 1098 all queries and combination of them.
1091 All others just support subsets. 1099 All others just support subsets.
1092\end_inset 1100\end_inset
1093 1101
1094. 1102.
1095 To check which settings are supported and to be able to react dynamically 1103 To check which settings are supported and to be able to react dynamically
1096 on missing features (for instance to disable some search features in the 1104 on missing features (for instance to disable some search features in the
1097 application) we provide the following operations: 1105 application) we provide the following operations:
1098\layout LyX-Code 1106\layout LyX-Code
1099 1107
1100bool hasQuerySettings( uint querySettings ); 1108bool hasQuerySettings( uint querySettings );
1101\layout LyX-Code 1109\layout LyX-Code
1102 1110
1103uint querySettings(); 1111uint querySettings();
1104\layout Standard 1112\layout Standard
1105 1113
1106The first operation 1114The first operation
1107\begin_inset Quotes gld 1115\begin_inset Quotes gld
1108\end_inset 1116\end_inset
1109 1117
1110hasQuerySettings() 1118hasQuerySettings()
1111\begin_inset Quotes grd 1119\begin_inset Quotes grd
1112\end_inset 1120\end_inset
1113 1121
1114 may be used to ask whether the database can handle the given query settings. 1122 may be used to ask whether the database can handle the given query settings.
1115 In this example a call to 1123 In this example a call to
@@ -1193,35 +1201,35 @@ queryByExample()
1193\begin_inset Quotes grd 1201\begin_inset Quotes grd
1194\end_inset 1202\end_inset
1195 1203
1196 which takes a 1204 which takes a
1197\begin_inset Quotes gld 1205\begin_inset Quotes gld
1198\end_inset 1206\end_inset
1199 1207
1200List 1208List
1201\begin_inset Quotes grd 1209\begin_inset Quotes grd
1202\end_inset 1210\end_inset
1203 1211
1204 as the first parameter. 1212 as the first parameter.
1205 The search operation will just occure on this set of uid's! 1213 The search operation will just occur on this set of uid's!
1206\layout Subsection 1214\layout Subsection
1207 1215
1208Sorting 1216Sorting
1209\layout Standard 1217\layout Standard
1210 1218
1211To sort a given dataset, you should use the following operation (or one 1219To sort a given dataset, you should use the following operation (or one
1212 of the others which behave slightly differently): 1220 of the others which behave slightly differently):
1213\layout LyX-Code 1221\layout LyX-Code
1214 1222
1215List sorted (const List& list, bool ascending, int sortOrder, int sortFilter, 1223List sorted (const List& list, bool ascending, int sortOrder, int sortFilter,
1216 const QArray< UID >& cats); 1224 const QArray< UID >& cats);
1217\layout Standard 1225\layout Standard
1218 1226
1219This sort operation takes a list of uid's as returned for instance from 1227This sort operation takes a list of uid's as returned for instance from
1220 a search query. 1228 a search query.
1221 The parameter 1229 The parameter
1222\begin_inset Quotes gld 1230\begin_inset Quotes gld
1223\end_inset 1231\end_inset
1224 1232
1225ascending 1233ascending
1226\begin_inset Quotes grd 1234\begin_inset Quotes grd
1227\end_inset 1235\end_inset
@@ -1392,20 +1400,20 @@ Need to be written.
1392 1400
1393 1401
1394\layout Section 1402\layout Section
1395 1403
1396Internal Signal Handling: Automatic Propagation of Changes 1404Internal Signal Handling: Automatic Propagation of Changes
1397\begin_inset LatexCommand \label{sec:Internal-Signal-Handling:} 1405\begin_inset LatexCommand \label{sec:Internal-Signal-Handling:}
1398 1406
1399\end_inset 1407\end_inset
1400 1408
1401 1409
1402\layout Standard 1410\layout Standard
1403 1411
1404Need to be written and is not implemented completly! 1412Need to be written and is not implemented completely!
1405\layout Chapter 1413\layout Chapter
1406 1414
1407Howto Extend and Write New Backends 1415Howto Extend and Write New Backends
1408\layout Standard 1416\layout Standard
1409 1417
1410Need to be written. 1418Need to be written.
1411\the_end 1419\the_end