Diffstat (limited to 'development/pim/pim_howto/pim_howto.lyx') (more/less context) (show whitespace changes)
-rw-r--r-- | development/pim/pim_howto/pim_howto.lyx | 112 |
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 | ||
81 | How to use the Opie-Pim API without getting tired! | 81 | How 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 |
90 | Stefan Eilers | 90 | Stefan Eilers |
91 | \layout Section* | 91 | \layout Section* |
92 | 92 | ||
93 | 93 | ||
94 | \family sans | 94 | \family sans |
95 | Abstract | 95 | Abstract |
96 | \layout Standard | 96 | \layout Standard |
97 | 97 | ||
98 | The Opie-Pim API provides a powerfull access interface to the PIM (Personal | 98 | The 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 | ||
108 | While starting to read the automatically generated API-documentation, the | 108 | While 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 | ||
124 | Introduction | 124 | Introduction |
125 | \layout Standard | 125 | \layout Standard |
126 | 126 | ||
127 | Before starting to jump into the work, we should introduce some specialities | 127 | Before 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 |
130 | ings: | 130 | ings: |
131 | \layout Enumerate | 131 | \layout Enumerate |
132 | 132 | ||
133 | The PIM-API heavily uses C++ templates (as known as generic classes), but | 133 | The 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 | ||
143 | The PIM-API is split into two parts: The | 143 | The PIM-API is split into two parts: The |
144 | \emph on | 144 | \emph on |
145 | frontend | 145 | frontend |
146 | \emph default | 146 | \emph default |
147 | and the | 147 | and the |
148 | \emph on | 148 | \emph on |
149 | backend. | 149 | backend. |
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 | ||
159 | backend | 159 | backend |
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 | ||
173 | In the next chapter, we will show how to access the default database as | 173 | In 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 |
209 | OPimAccessFactory | 209 | OPimAccessFactory |
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 | ||
220 | T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName) | 220 | T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName) |
221 | \layout Standard | 221 | \layout Standard |
222 | 222 | ||
223 | You just have to add the following lines to your source code to use it (this | 223 | You 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 | ||
230 | use namespace Opie; | 230 | use namespace Opie; |
231 | \layout Standard | 231 | \layout Standard |
232 | 232 | ||
233 | [...] | 233 | [...] |
234 | \layout LyX-Code | 234 | \layout LyX-Code |
235 | 235 | ||
236 | OPimContactAccess* sourceDB = OPimAccessFactory<OPimContactAccess>::defaultAcces | 236 | OPimContactAccess* sourceDB = OPimAccessFactory<OPimContactAccess>::defaultAcces |
237 | s( OPimGlobal::CONTACTLIST, "my-app" ); | 237 | s( OPimGlobal::CONTACTLIST, "my-app" ); |
238 | \layout Standard | 238 | \layout Standard |
239 | 239 | ||
240 | If everything works as expected, you will receive a pointer to the contact | 240 | If 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 |
244 | collapsed true | 244 | collapsed false |
245 | 245 | ||
246 | \layout Standard | 246 | \layout Standard |
247 | 247 | ||
248 | The API will be changed in the future: ODateBookAccess will be renamed to | 248 | The 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 | ||
255 | ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess( | 255 | ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess( |
256 | OPimGlobal::DATEBOOK, "my-app" ); | 256 | OPimGlobal::DATEBOOK, "my-app" ); |
@@ -266,27 +266,27 @@ OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess( | |||
266 | Using | 266 | Using |
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 | ||
272 | defaultAccess() | 272 | defaultAccess() |
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 |
280 | collapsed true | 280 | collapsed false |
281 | 281 | ||
282 | \layout Standard | 282 | \layout Standard |
283 | 283 | ||
284 | The configuration file | 284 | The configuration file |
285 | \begin_inset Quotes gld | 285 | \begin_inset Quotes gld |
286 | \end_inset | 286 | \end_inset |
287 | 287 | ||
288 | pimaccess.conf | 288 | pimaccess.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 | ||
353 | T | 353 | T |
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 |
359 | data-class | 359 | data-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 |
363 | collapsed true | 363 | collapsed false |
364 | 364 | ||
365 | \layout Standard | 365 | \layout Standard |
366 | 366 | ||
367 | see | 367 | see |
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 |
377 | collapsed true | 377 | collapsed false |
378 | 378 | ||
379 | \layout Standard | 379 | \layout Standard |
380 | 380 | ||
381 | see | 381 | see |
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 |
391 | collapsed true | 391 | collapsed false |
392 | 392 | ||
393 | \layout Standard | 393 | \layout Standard |
394 | 394 | ||
395 | see | 395 | see |
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 | ||
406 | bool load (); | 406 | bool load (); |
407 | \layout LyX-Code | 407 | \layout LyX-Code |
408 | 408 | ||
409 | bool reload (); | 409 | bool reload (); |
410 | \layout LyX-Code | 410 | \layout LyX-Code |
411 | 411 | ||
412 | bool save (); | 412 | bool save (); |
413 | \layout LyX-Code | 413 | \layout LyX-Code |
414 | 414 | ||
415 | \layout LyX-Code | 415 | \layout LyX-Code |
416 | 416 | ||
417 | bool add (const T& t); | 417 | bool add (const T& t); |
418 | \layout LyX-Code | 418 | \layout LyX-Code |
419 | 419 | ||
420 | bool remove (const T& t); | 420 | bool remove (const T& t); |
421 | \layout LyX-Code | 421 | \layout LyX-Code |
422 | 422 | ||
423 | bool replace (const T& t); | 423 | bool replace (const T& t); |
424 | \layout Standard | 424 | \layout Standard |
425 | 425 | ||
426 | After receiving an access-object, we have to load the existing dataset into | 426 | After 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 | ||
431 | load() | 431 | load() |
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 | ||
453 | reload() | 453 | reload() |
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 |
459 | without | 459 | without |
460 | \series default | 460 | \series default |
461 | removing any local changes | 461 | removing any local changes |
462 | \begin_inset Foot | 462 | \begin_inset Foot |
463 | collapsed true | 463 | collapsed false |
464 | 464 | ||
465 | \layout Standard | 465 | \layout Standard |
466 | 466 | ||
467 | We should check whether all dabases behave like this! (se) | 467 | We 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 | ||
476 | If you want to work with the existing dataset, you need to get a list of | 476 | If 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 |
488 | OPimRecordList | 488 | OPimRecordList |
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 | ||
499 | List allRecords (); | 499 | List allRecords(); |
500 | \layout Standard | 500 | \layout Standard |
501 | 501 | ||
502 | In fact, this | 502 | In fact, this |
503 | \emph on | 503 | \emph on |
504 | List | 504 | List |
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 | ||
514 | find() | 514 | find() |
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 | ||
521 | T find (UID uid); | 521 | T find (UID uid); |
522 | \layout Standard | 522 | \layout Standard |
523 | 523 | ||
524 | This is all you need to realize a basic access to the PIM-Databases! The | 524 | This 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 | ||
528 | How to Access PIM-Data: Detailed View | 528 | How to Access PIM-Data: Detailed View |
529 | \layout Standard | 529 | \layout Standard |
530 | 530 | ||
531 | As shown in the previous chapter, all we need to access the PIM-Database | 531 | As 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 | ||
561 | But first we will start with intoducing some features of the | 561 | But first we will start with introducing some features of the |
562 | \series bold | 562 | \series bold |
563 | OPimAccessFactory | 563 | OPimAccessFactory |
564 | \series default | 564 | \series default |
565 | . | 565 | . |
566 | \layout Section | 566 | \layout Section |
567 | 567 | ||
568 | Advanced Factory Features | 568 | Advanced 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 | ||
576 | In the previous chapter we used the operation | 576 | In 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 | ||
580 | defaultAccess() | 580 | defaultAccess() |
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 | ||
590 | pimaccess.conf | 590 | pimaccess.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 | |||
607 | defaultAccess() | 607 | defaultAccess() |
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 | ||
618 | If the developer wants to select a special database type for sure without | 618 | If 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 |
621 | create() | 621 | create() |
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 | ||
626 | T * create (OPimGlobal::PimType type, OPimGlobal::DatabaseStyle dbStyle, | 626 | T* 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 | ||
630 | Some paramters are already known, like type and appName (see section | 630 | Some 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 | ||
640 | dbStyle | 640 | dbStyle |
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 | |||
737 | Special Features: Searching and Sorting | 737 | Special 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 | ||
745 | In most cases it is not sufficient to receive just a list of all information | 745 | In 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 |
752 | collapsed true | 752 | collapsed false |
753 | 753 | ||
754 | \layout Standard | 754 | \layout Standard |
755 | 755 | ||
756 | FIXME: matchRegexp() does take a list of uid's. | 756 | FIXME: 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 | ||
833 | matchRegexp() | 833 | matchRegexp() |
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 | ||
840 | The function is defined like this: | 840 | The function is defined like this: |
841 | \layout LyX-Code | 841 | \layout LyX-Code |
842 | 842 | ||
843 | List matchRegexp (const QRegExp &r); | 843 | List matchRegexp (const QRegExp& r); |
844 | \layout Standard | 844 | \layout Standard |
845 | 845 | ||
846 | The | 846 | The |
847 | \begin_inset Quotes gld | 847 | \begin_inset Quotes gld |
848 | \end_inset | 848 | \end_inset |
849 | 849 | ||
850 | List | 850 | List |
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 | ||
889 | 3 | 889 | 3 |
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 | ||
896 | OPimContact searchQuery; | 896 | OPimContact searchQuery; |
897 | \layout LyX-Code | 897 | \layout LyX-Code |
898 | 898 | ||
899 | searchQuery.setLastName( | 899 | searchQuery.setLastName( |
900 | \begin_inset Quotes gld | 900 | \begin_inset Quotes eld |
901 | \end_inset | 901 | \end_inset |
902 | 902 | ||
903 | Eilers | 903 | Eilers |
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 | ||
910 | searchQuery.setHomeZip( | 910 | searchQuery.setHomeZip( |
911 | \begin_inset Quotes gld | 911 | \begin_inset Quotes eld |
912 | \end_inset | 912 | \end_inset |
913 | 913 | ||
914 | 3* | 914 | 3* |
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 | ||
921 | We use an usual | 921 | We use an usual |
922 | \begin_inset Quotes gld | 922 | \begin_inset Quotes gld |
923 | \end_inset | 923 | \end_inset |
924 | 924 | ||
925 | OPimContact | 925 | OPimContact |
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 | ||
958 | The next step is to put this query into the operation which is defined like | 958 | The 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 | ||
962 | List queryByExample (const T& query, int querySettings, const QDateTime | 962 | List queryByExample (const T& query, int querySettings, const QDateTime& |
963 | &startperiod=QDateTime()) | 963 | startperiod=QDateTime()) |
964 | \layout Standard | 964 | \layout Standard |
965 | 965 | ||
966 | The first parameter | 966 | The first parameter |
967 | \begin_inset Quotes gld | 967 | \begin_inset Quotes gld |
968 | \end_inset | 968 | \end_inset |
969 | 969 | ||
970 | query | 970 | query |
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 | ||
978 | querySettings | 978 | querySettings |
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 | |||
987 | QuerySettings | ||
988 | \begin_inset Quotes grd | ||
989 | \end_inset | ||
990 | |||
991 | in the class | ||
984 | \series bold | 992 | \series bold |
985 | OPimBase | 993 | OPimBase |
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 | ||
1074 | find() | 1082 | find() |
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 | ||
1081 | It should be clear at this stage, that this query is very powerful and - | 1089 | It 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 |
1085 | collapsed true | 1093 | collapsed false |
1086 | 1094 | ||
1087 | \layout Standard | 1095 | \layout Standard |
1088 | 1096 | ||
1089 | At this time, just the contact database for XML and VCard is supporting | 1097 | At 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 | ||
1100 | bool hasQuerySettings( uint querySettings ); | 1108 | bool hasQuerySettings( uint querySettings ); |
1101 | \layout LyX-Code | 1109 | \layout LyX-Code |
1102 | 1110 | ||
1103 | uint querySettings(); | 1111 | uint querySettings(); |
1104 | \layout Standard | 1112 | \layout Standard |
1105 | 1113 | ||
1106 | The first operation | 1114 | The first operation |
1107 | \begin_inset Quotes gld | 1115 | \begin_inset Quotes gld |
1108 | \end_inset | 1116 | \end_inset |
1109 | 1117 | ||
1110 | hasQuerySettings() | 1118 | hasQuerySettings() |
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 | ||
1200 | List | 1208 | List |
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 | ||
1208 | Sorting | 1216 | Sorting |
1209 | \layout Standard | 1217 | \layout Standard |
1210 | 1218 | ||
1211 | To sort a given dataset, you should use the following operation (or one | 1219 | To 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 | ||
1215 | List sorted (const List& list, bool ascending, int sortOrder, int sortFilter, | 1223 | List 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 | ||
1219 | This sort operation takes a list of uid's as returned for instance from | 1227 | This 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 | ||
1225 | ascending | 1233 | ascending |
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 | ||
1396 | Internal Signal Handling: Automatic Propagation of Changes | 1404 | Internal 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 | ||
1404 | Need to be written and is not implemented completly! | 1412 | Need to be written and is not implemented completely! |
1405 | \layout Chapter | 1413 | \layout Chapter |
1406 | 1414 | ||
1407 | Howto Extend and Write New Backends | 1415 | Howto Extend and Write New Backends |
1408 | \layout Standard | 1416 | \layout Standard |
1409 | 1417 | ||
1410 | Need to be written. | 1418 | Need to be written. |
1411 | \the_end | 1419 | \the_end |