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
@@ -31,158 +31,158 @@
31 {\MakeUppercase\indexname}% 31 {\MakeUppercase\indexname}%
32 \begin{multicols}{\NrCol}\thispagestyle{plain}\parindent\z@ 32 \begin{multicols}{\NrCol}\thispagestyle{plain}\parindent\z@
33 \parskip\z@ \@plus .3\p@\relax 33 \parskip\z@ \@plus .3\p@\relax
34 \let\item\@idxitem} 34 \let\item\@idxitem}
35 {\clearpage % 35 {\clearpage %
36 \end{multicols}} 36 \end{multicols}}
37 37
38\renewenvironment{theindex} 38\renewenvironment{theindex}
39 {\if@twocolumn 39 {\if@twocolumn
40 \@restonecolfalse 40 \@restonecolfalse
41 \else 41 \else
42 \@restonecoltrue 42 \@restonecoltrue
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)
86\layout Author 86\layout Author
87 87
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.
177\layout Chapter 177\layout Chapter
178 178
179Quick Guide to access the Database 179Quick Guide to access the Database
180\layout Standard 180\layout Standard
181 181
182In this chapter we will introduce very quickly how to get access to the 182In this chapter we will introduce very quickly how to get access to the
183 database and how to access data. 183 database and how to access data.
184 It should help to find the right directions. 184 It should help to find the right directions.
185 If it is too short for you, you should read the next chapter afterwards 185 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. 186 to find a more complete and detailed view into the system.
187\layout Section 187\layout Section
188 188
@@ -196,109 +196,109 @@ Instantiate the access-object
196 196
197To gain access to the database you need something we will call 197To gain access to the database you need something we will call
198\emph on 198\emph on
199 access-object 199 access-object
200\emph default 200\emph default
201 (an instance of the access-class for the database) which handles the database 201 (an instance of the access-class for the database) which handles the database
202 access. 202 access.
203 Requesting such an object is very easy by using the operation 203 Requesting such an object is very easy by using the operation
204\emph on 204\emph on
205defaultAccess() 205defaultAccess()
206\emph default 206\emph default
207 of the factory class 207 of the factory class
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" );
257\layout Standard 257\layout Standard
258 258
259And the same for todo: 259And the same for todo:
260\layout LyX-Code 260\layout LyX-Code
261 261
262OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess( 262OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess(
263 OPimGlobal::TODOLIST, "my-app" ); 263 OPimGlobal::TODOLIST, "my-app" );
264\layout Standard 264\layout Standard
265 265
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!
293\end_inset 293\end_inset
294 294
295. 295.
296 If you want to use anything else, you have to read the next chapter to 296 If you want to use anything else, you have to read the next chapter to
297 get the information how to do this. 297 get the information how to do this.
298 298
299\layout Standard 299\layout Standard
300 300
301The last parameter 301The last parameter
302\begin_inset Quotes gld 302\begin_inset Quotes gld
303\end_inset 303\end_inset
304 304
@@ -339,316 +339,316 @@ OPimAccessTemplate
339\series default 339\series default
340 (see 340 (see
341\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessTemplate.html} 341\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessTemplate.html}
342 342
343\end_inset 343\end_inset
344 344
345). 345).
346 This API is inherited by all access-classes and therefore common to all 346 This API is inherited by all access-classes and therefore common to all
347 access-objects. 347 access-objects.
348 We will show the most important operations of it first (please replace 348 We will show the most important operations of it first (please replace
349 349
350\begin_inset Quotes gld 350\begin_inset Quotes gld
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.
436 The 436 The
437\begin_inset Quotes gld 437\begin_inset Quotes gld
438\end_inset 438\end_inset
439 439
440save() 440save()
441\begin_inset Quotes grd 441\begin_inset Quotes grd
442\end_inset 442\end_inset
443 443
444 operation is important to write back (or 444 operation is important to write back (or
445\emph on 445\emph on
446commit 446commit
447\emph default 447\emph default
448) local changes into the global database. 448) local changes into the global database.
449 After doing this, the changes are globally accessable! The 449 After doing this, the changes are globally accessable! The
450\begin_inset Quotes gld 450\begin_inset Quotes gld
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
480\end_inset 480\end_inset
481 481
482allRecords() 482allRecords()
483\begin_inset Quotes grd 483\begin_inset Quotes grd
484\end_inset 484\end_inset
485 485
486 which returns a list of all available records as an 486 which returns a list of all available records as an
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
534 534
535\begin_inset LatexCommand \ref{sec:Advanced-Factory-Features} 535\begin_inset LatexCommand \ref{sec:Advanced-Factory-Features}
536 536
537\end_inset 537\end_inset
538 538
539), followed by some very important features like searching and sorting in 539), followed by some very important features like searching and sorting in
540 section 540 section
541\begin_inset LatexCommand \ref{sec:Special-Features:-Searching} 541\begin_inset LatexCommand \ref{sec:Special-Features:-Searching}
542 542
543\end_inset 543\end_inset
544 544
545. 545.
546 If you are interested in accessing data without take care about their types, 546 If you are interested in accessing data without take care about their types,
547 section 547 section
548\begin_inset LatexCommand \ref{sec:Generic-Access:-OPimBase} 548\begin_inset LatexCommand \ref{sec:Generic-Access:-OPimBase}
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
597 597
598Settings 598Settings
599\begin_inset Quotes grd 599\begin_inset Quotes grd
600\end_inset 600\end_inset
601 601
602, stored in the user home directory. 602, stored in the user home directory.
603 Changing this setting will take effect to all applications using 603 Changing this setting will take effect to all applications using
604\begin_inset Quotes gld 604\begin_inset Quotes gld
605\end_inset 605\end_inset
606 606
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
643 643
644 defines which database type should be selected. 644 defines which database type should be selected.
645 Possible values could be found in the enumeration 645 Possible values could be found in the enumeration
646\emph on 646\emph on
647DataBaseStyle 647DataBaseStyle
648\emph default 648\emph default
649 in the class 649 in the class
650\series bold 650\series bold
651OPimGlobal 651OPimGlobal
652\series default 652\series default
653 (see 653 (see
654\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1Pim_1_1OPimGlobal.html} 654\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1Pim_1_1OPimGlobal.html}
@@ -725,52 +725,52 @@ fileName
725 725
726~/Applications/<name of application>/ 726~/Applications/<name of application>/
727\begin_inset Quotes grd 727\begin_inset Quotes grd
728\end_inset 728\end_inset
729 729
730). 730).
731\layout Standard 731\layout Standard
732 732
733In the next section we will discuss how searching and sorting take place 733In the next section we will discuss how searching and sorting take place
734 with this API. 734 with this API.
735\layout Section 735\layout Section
736 736
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
765 765
766List 766List
767\begin_inset Quotes grd 767\begin_inset Quotes grd
768\end_inset 768\end_inset
769 769
770 which was returned by a previous search query and to sort it afterwards. 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. 771 Before we will take a close look into sorting, we will start with searching.
772 There exist two different ways of searching: 772 There exist two different ways of searching:
773\layout Enumerate 773\layout Enumerate
774 774
775Search a complete database for a special regular expression, using 775Search a complete database for a special regular expression, using
776\begin_inset Quotes gld 776\begin_inset Quotes gld
@@ -819,49 +819,49 @@ We will start with the first and very simple
819\begin_inset Quotes grd 819\begin_inset Quotes grd
820\end_inset 820\end_inset
821 821
822matchRegexp() 822matchRegexp()
823\begin_inset Quotes grd 823\begin_inset Quotes grd
824\end_inset 824\end_inset
825 825
826, followed by the query by example search query. 826, followed by the query by example search query.
827\layout Subsection 827\layout Subsection
828 828
829Searching with 829Searching with
830\begin_inset Quotes gld 830\begin_inset Quotes gld
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
856\begin_inset LatexCommand \ref{sec:Accessing-the-access-object} 856\begin_inset LatexCommand \ref{sec:Accessing-the-access-object}
857 857
858\end_inset 858\end_inset
859 859
860 you have to use the 860 you have to use the
861\begin_inset Quotes gld 861\begin_inset Quotes gld
862\end_inset 862\end_inset
863 863
864find() 864find()
865\begin_inset Quotes grd 865\begin_inset Quotes grd
866\end_inset 866\end_inset
867 867
@@ -876,132 +876,140 @@ The query by example search style is working is using a data object (for
876 For instance, if you want to request all entries which contains the last 876 For instance, if you want to request all entries which contains the last
877 name 877 name
878\begin_inset Quotes gld 878\begin_inset Quotes gld
879\end_inset 879\end_inset
880 880
881Eilers 881Eilers
882\begin_inset Quotes grd 882\begin_inset Quotes grd
883\end_inset 883\end_inset
884 884
885 and the home zip number should start with 885 and the home zip number should start with
886\begin_inset Quotes gld 886\begin_inset Quotes gld
887\end_inset 887\end_inset
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
928 928
929 and fill into two fields the query information. 929 and fill into two fields the query information.
930 All filled fields are taken for the search operation (using an 930 All filled fields are taken for the search operation (using an
931\begin_inset Quotes gld 931\begin_inset Quotes gld
932\end_inset 932\end_inset
933 933
934AND 934AND
935\begin_inset Quotes grd 935\begin_inset Quotes grd
936\end_inset 936\end_inset
937 937
938 operation), the unused ones are simply ignored. 938 operation), the unused ones are simply ignored.
939 As we just want to search for entries which zip number starts with a 939 As we just want to search for entries which zip number starts with a
940\begin_inset Quotes gld 940\begin_inset Quotes gld
941\end_inset 941\end_inset
942 942
9433 9433
944\begin_inset Quotes grd 944\begin_inset Quotes grd
945\end_inset 945\end_inset
946 946
947 we use the Wildcard 947 we use the Wildcard
948\begin_inset Quotes gld 948\begin_inset Quotes gld
949\end_inset 949\end_inset
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.
996 As we use Wildcards in 1004 As we use Wildcards in
997\begin_inset Quotes gld 1005\begin_inset Quotes gld
998\end_inset 1006\end_inset
999 1007
1000setHomeZip 1008setHomeZip
1001\begin_inset Quotes grd 1009\begin_inset Quotes grd
1002\end_inset 1010\end_inset
1003 1011
1004 we have to use 1012 we have to use
1005\begin_inset Quotes gld 1013\begin_inset Quotes gld
1006\end_inset 1014\end_inset
1007 1015
@@ -1061,67 +1069,67 @@ use namespace Opie;
1061 1069
1062[...] 1070[...]
1063\layout LyX-Code 1071\layout LyX-Code
1064 1072
1065List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase:: 1073List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase::
1066IgnoreCase ); 1074IgnoreCase );
1067\layout Standard 1075\layout Standard
1068 1076
1069This operation may return a list of entries which can be accessed as above, 1077This operation may return a list of entries which can be accessed as above,
1070 using the 1078 using the
1071\begin_inset Quotes gld 1079\begin_inset Quotes gld
1072\end_inset 1080\end_inset
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
1116\layout LyX-Code 1124\layout LyX-Code
1117 1125
1118hasQuerySettings( OPimBase::WildCards | OpimBase::IgnoreCase ); 1126hasQuerySettings( OPimBase::WildCards | OpimBase::IgnoreCase );
1119\layout Standard 1127\layout Standard
1120 1128
1121should be answered with 1129should be answered with
1122\begin_inset Quotes gld 1130\begin_inset Quotes gld
1123\end_inset 1131\end_inset
1124 1132
1125true 1133true
1126\begin_inset Quotes grd 1134\begin_inset Quotes grd
1127\end_inset 1135\end_inset
@@ -1181,59 +1189,59 @@ end
1181 of the interval. 1189 of the interval.
1182 The start will be defined by the last parameter (if nothing is set, the 1190 The start will be defined by the last parameter (if nothing is set, the
1183 current date will be taken!). 1191 current date will be taken!).
1184 Therefore, it is possible to set a time frame for all searched entries. 1192 Therefore, it is possible to set a time frame for all searched entries.
1185\layout Standard 1193\layout Standard
1186 1194
1187If you want to do incremental search operations, you may use the special 1195If you want to do incremental search operations, you may use the special
1188 1196
1189\begin_inset Quotes gld 1197\begin_inset Quotes gld
1190\end_inset 1198\end_inset
1191 1199
1192queryByExample() 1200queryByExample()
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
1228 1236
1229 defines whether the sort should be in an ascending order or not. 1237 defines whether the sort should be in an ascending order or not.
1230 1238
1231\begin_inset Quotes gld 1239\begin_inset Quotes gld
1232\end_inset 1240\end_inset
1233 1241
1234sortOrder 1242sortOrder
1235\begin_inset Quotes grd 1243\begin_inset Quotes grd
1236\end_inset 1244\end_inset
1237 1245
1238 is defined by the enumerations 1246 is defined by the enumerations
1239\begin_inset Quotes gld 1247\begin_inset Quotes gld
@@ -1380,32 +1388,32 @@ Generic Access: OPimBase and OPimRecord
1380 1388
1381 1389
1382\layout Section 1390\layout Section
1383 1391
1384Caching 1392Caching
1385\layout Standard 1393\layout Standard
1386 1394
1387Need to be written. 1395Need to be written.
1388 Implementation is found at: 1396 Implementation is found at:
1389\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/noncore/tools/pimconverter/converter.cpp?rev=1.9&content-type=text/x-cvsweb-markup} 1397\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/noncore/tools/pimconverter/converter.cpp?rev=1.9&content-type=text/x-cvsweb-markup}
1390 1398
1391\end_inset 1399\end_inset
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