summaryrefslogtreecommitdiff
authoreilers <eilers>2005-01-04 09:27:04 (UTC)
committer eilers <eilers>2005-01-04 09:27:04 (UTC)
commitff93c49af890b2b03f729a848be36b77a6e2454b (patch) (unidiff)
tree99818ef87f2554da2deaf229941cc69fa54d6ec7
parent12e7c838d741d37c7a526e21ac43562ec5b64c6e (diff)
downloadopie-ff93c49af890b2b03f729a848be36b77a6e2454b.zip
opie-ff93c49af890b2b03f729a848be36b77a6e2454b.tar.gz
opie-ff93c49af890b2b03f729a848be36b77a6e2454b.tar.bz2
First unfinished and undebugged release of the PIM-API Howto paper
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--development/pim/pim_howto/pim_howto.lyx1213
1 files changed, 1213 insertions, 0 deletions
diff --git a/development/pim/pim_howto/pim_howto.lyx b/development/pim/pim_howto/pim_howto.lyx
new file mode 100644
index 0000000..2b08be8
--- a/dev/null
+++ b/development/pim/pim_howto/pim_howto.lyx
@@ -0,0 +1,1213 @@
1#LyX 1.3 created this file. For more info see http://www.lyx.org/
2\lyxformat 221
3\textclass scrbook
4\begin_preamble
5\fancyhead{}
6\fancyfoot{}
7\fancyhead[LE,RO]{\slshape \leftmark}
8\fancyhead[LO,RE]{\slshape \leftmark}
9\fancyhead[RE,LO]{\thepage}
10%\fancyhead[LO,RE]{}
11% \usepackage{ae}
12\usepackage[bookmarksopen,colorlinks]{hyperref}
13% \pdfoutput=1
14% \pdfcompresslevel=8
15% \pdfinfo{
16% /Title ClearSim-RealtTime und Andere
17% /Creator (Tex)
18% /Author (Stefan Eilers)
19% /Subject ()
20% /Keywords (Simulation,Real-Time,ClearSim,prototype,efsm)
21% }
22\renewcommand\familydefault{\sfdefault}
23
24\usepackage{multicol}
25\newcommand\NrCol{3}
26\renewenvironment{theindex}
27 {\columnseprule \z@
28 \columnsep 35\p@
29 \section*{\indexname}%
30 \@mkboth{\MakeUppercase\indexname}%
31 {\MakeUppercase\indexname}%
32 \begin{multicols}{\NrCol}\thispagestyle{plain}\parindent\z@
33 \parskip\z@ \@plus .3\p@\relax
34 \let\item\@idxitem}
35 {\clearpage %
36 \end{multicols}}
37
38\renewenvironment{theindex}
39 {\if@twocolumn
40 \@restonecolfalse
41 \else
42 \@restonecoltrue
43 \fi
44 \columnseprule \z@
45 \columnsep 35\p@
46 \twocolumn[\refstepcounter{section}%
47 \section{\indexname}]%
48 \@mkboth{\MakeUppercase\indexname}%
49 {\MakeUppercase\indexname}%
50 \thispagestyle{plain}\parindent\z@
51 \parskip\z@ \@plus .3\p@\relax
52 \let\item\@idxitem}
53 {\if@restonecol\onecolumn\else\clearpage\fi}
54\end_preamble
55\language german
56\inputencoding auto
57\fontscheme ae
58\graphics default
59\float_placement htbp
60\paperfontsize default
61\spacing single
62\papersize a4paper
63\paperpackage widemarginsa4
64\use_geometry 0
65\use_amsmath 0
66\use_natbib 0
67\use_numerical_citations 0
68\paperorientation portrait
69\secnumdepth 3
70\tocdepth 3
71\paragraph_separation skip
72\defskip medskip
73\quotes_language german
74\quotes_times 2
75\papercolumns 1
76\papersides 2
77\paperpagestyle fancy
78
79\layout Title
80
81How to use the Opie-Pim API without getting tired!
82\newline
83(Aka: Hitchhikers Guide Through the Opie-Pim API)
84\newline
85(Pre V 0.1)
86\layout Author
87
88
89\family sans
90Stefan Eilers
91\layout Section*
92
93
94\family sans
95Abstract
96\layout Standard
97
98The Opie-Pim API provides a powerfull access interface to the PIM (Personal
99 Information Management) data which contains your contact information, the
100 dates in your calender tool (in this paper called datebook events) and
101 your todo events.
102 Beside providing full featured access to this information, it covers the
103 real management of this informantion - the access of the databases - from
104 the user.
105
106\layout Standard
107
108While starting to read the automatically generated API-documentation, the
109 user may be confused by a lot of unneccessary classes and details which
110 makes the quick start not as easy as expected.
111 Due to the fact that a user who just want to access data will not need
112 most of the details, this paper should help to start to be confortable
113 with the details he need to solve his problems.
114\layout Standard
115
116
117\begin_inset LatexCommand \tableofcontents{}
118
119\end_inset
120
121
122\layout Chapter
123
124Introduction
125\layout Standard
126
127Before starting to jump into the work, we should introduce some specialities
128 of the PIM API first.
129 To know these facts should help to avoid possible irritations and misunderstand
130ings:
131\layout Enumerate
132
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
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)
137 but this guide will provide examples which should help to find the path
138 through.
139 But it is a good idea to read some short introduction of templates to avoid
140 unneccessary mistakes.
141\layout Enumerate
142
143The PIM-API is split into two parts: The
144\emph on
145frontend
146\emph default
147 and the
148\emph on
149backend.
150
151\emph default
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.
154 This paper just focusses the frontend as we just want to access data.
155 Thus, you should ignore all classes which contains something like
156\begin_inset Quotes gld
157\end_inset
158
159backend
160\begin_inset Quotes grd
161\end_inset
162
163 in its name! Backends are just interessting for people who want to extend
164 or implement new possiblities about how to access databases, which will
165 be discussed at the end of this paper.
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
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
170 about this!
171\layout Standard
172
173In the next chapter, we will show how to access the default database as
174 easy as possible.
175 This will be the solution for most of the problems you may face while accessing
176 the PIM data.
177\layout Chapter
178
179Quick Guide to access the Database
180\layout Standard
181
182In this chapter we will introduce very quickly how to get access to the
183 database and how to access data.
184 It should help to find the right directions.
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.
187\layout Section
188
189Instantiate the access-object
190\begin_inset LatexCommand \label{sec:Instantiate-the-Access}
191
192\end_inset
193
194
195\layout Standard
196
197To gain access to the database you need something we will call
198\emph on
199 access-object
200\emph default
201 (an instance of the access-class for the database) which handles the database
202 access.
203 Requesting such an object is very easy by using the operation
204\emph on
205defaultAccess()
206\emph default
207 of the factory class
208\series bold
209OPimAccessFactory
210\series default
211 (see
212\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessFactory.html}
213
214\end_inset
215
216).
217 This operation is defined like this:
218\layout LyX-Code
219
220T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName)
221\layout Standard
222
223You just have to add the following lines to your source code to use it (this
224 example is for accessing the contact database):
225\layout LyX-Code
226
227#include <opie2/opimaccessfactory.h>
228\layout LyX-Code
229
230use namespace Opie;
231\layout Standard
232
233[...]
234\layout LyX-Code
235
236OPimContactAccess* sourceDB = OPimAccessFactory<OPimContactAccess>::defaultAcces
237s( OPimGlobal::CONTACTLIST, "my-app" );
238\layout Standard
239
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.
242 Accessing the datebook database works equally
243\begin_inset Foot
244collapsed true
245
246\layout Standard
247
248The API will be changed in the future: ODateBookAccess will be renamed to
249 OPimEventAccess.
250\end_inset
251
252:
253\layout LyX-Code
254
255ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess(
256 OPimGlobal::DATEBOOK, "my-app" );
257\layout Standard
258
259And the same for todo:
260\layout LyX-Code
261
262OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess(
263 OPimGlobal::TODOLIST, "my-app" );
264\layout Standard
265
266Using
267\emph on
268
269\begin_inset Quotes gld
270\end_inset
271
272defaultAccess()
273\begin_inset Quotes grd
274\end_inset
275
276
277\emph default
278, the default dabase is accessed automatically
279\begin_inset Foot
280collapsed true
281
282\layout Standard
283
284The configuration file
285\begin_inset Quotes gld
286\end_inset
287
288pimaccess.conf
289\begin_inset Quotes grd
290\end_inset
291
292 defines which backend is selected as default!
293\end_inset
294
295.
296 If you want to use anything else, you have to read the next chapter to
297 get the information how to do this.
298
299\layout Standard
300
301The last parameter
302\begin_inset Quotes gld
303\end_inset
304
305my-app
306\begin_inset Quotes grd
307\end_inset
308
309 is very importand and should be equal for every instance of an application.
310 Some database backends (like the XML backend) uses this string as an unique
311 filename to create a journal file.
312 If your application should run in several instances independently you will
313 need multiple journal files and therefore several name strings!
314\layout Standard
315
316If the database access-object is is not needed anymore, you have to remove
317 it by calling
318\emph on
319delete
320\emph default
321:
322\layout LyX-Code
323
324delete sourceDB;
325\layout Section
326
327Accessing the access-object
328\begin_inset LatexCommand \label{sec:Accessing-the-access-object}
329
330\end_inset
331
332
333\layout Standard
334
335After receiving the access-object, we just have to use its API which is
336 mainly defined by the common base class
337\series bold
338OPimAccessTemplate
339\series default
340 (see
341\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessTemplate.html}
342
343\end_inset
344
345).
346 This API is inherited by all access-classes and therefore common to all
347 access-objects.
348 We will show the most important operations of it first (please replace
349
350\begin_inset Quotes gld
351\end_inset
352
353T
354\begin_inset Quotes grd
355\end_inset
356
357 below with the corresponding
358\emph on
359data-class
360\emph default
361 for the selected access-class: OPimContact
362\begin_inset Foot
363collapsed true
364
365\layout Standard
366
367see
368\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContact.html}
369
370\end_inset
371
372
373\end_inset
374
375 for OPimContactAccess, OPimEvent
376\begin_inset Foot
377collapsed true
378
379\layout Standard
380
381see
382\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimEvent.html}
383
384\end_inset
385
386
387\end_inset
388
389 for ODateBookAccess and OPimTodo
390\begin_inset Foot
391collapsed true
392
393\layout Standard
394
395see
396\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodo.html}
397
398\end_inset
399
400
401\end_inset
402
403 for OPimTodoAccess):
404\layout LyX-Code
405
406bool load ();
407\layout LyX-Code
408
409bool reload ();
410\layout LyX-Code
411
412bool save ();
413\layout LyX-Code
414
415\layout LyX-Code
416
417bool add (const T& t);
418\layout LyX-Code
419
420bool remove (const T& t);
421\layout LyX-Code
422
423bool replace (const T& t);
424\layout Standard
425
426After receiving an access-object, we have to load the existing dataset,
427 which is done by the
428\begin_inset Quotes gld
429\end_inset
430
431load()
432\begin_inset Quotes grd
433\end_inset
434
435 operation.
436 The
437\begin_inset Quotes gld
438\end_inset
439
440save()
441\begin_inset Quotes grd
442\end_inset
443
444 operation is important to write back (or
445\emph on
446commit
447\emph default
448) local changes into the global database.
449 After doing this, the changes are globally accessable! The
450\begin_inset Quotes gld
451\end_inset
452
453reload()
454\begin_inset Quotes grd
455\end_inset
456
457 operation loads changes of the global database into the local set
458\series bold
459without
460\series default
461 removing any local changes
462\begin_inset Foot
463collapsed true
464
465\layout Standard
466
467We should check whether all dabases behave like this! (se)
468\end_inset
469
470.
471 This may be done after receiving information about any change by an other
472 application which is not in scope of this chapter.
473 The other operations are self explaining and should work as expected.
474\layout Standard
475
476If you want to work with the existing dataset, you need to get a list of
477 all available information.
478 This list is returned by the call
479\begin_inset Quotes gld
480\end_inset
481
482allRecords()
483\begin_inset Quotes grd
484\end_inset
485
486 which returns a list of all available records as an
487\series bold
488OPimRecordList
489\series default
490 (see
491\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html}
492
493\end_inset
494
495).
496
497\layout LyX-Code
498
499List allRecords ();
500\layout Standard
501
502In fact this
503\emph on
504List
505\emph default
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
508 called UID (Unique IDentification), these numbers just exists once in the
509 database which is currently on access! To receive the real record, you
510 have to use the operation
511\begin_inset Quotes gld
512\end_inset
513
514find()
515\begin_inset Quotes grd
516\end_inset
517
518 with a valid UID as paramter:
519\layout LyX-Code
520
521T find (UID uid);
522\layout Standard
523
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.
526\layout Chapter
527
528How to Access PIM-Data: Detailed View
529\layout Standard
530
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.
533 We will now introduce some special features of this factory (see section
534
535\begin_inset LatexCommand \ref{sec:Advanced-Factory-Features}
536
537\end_inset
538
539), followed by some very important features like searching and sorting in
540 section
541\begin_inset LatexCommand \ref{sec:Special-Features:-Searching}
542
543\end_inset
544
545.
546 If you are interested in accessing data without take care about their types,
547 section
548\begin_inset LatexCommand \ref{sec:Generic-Access:-OPimBase}
549
550\end_inset
551
552 will show how to do this, followed by a short introduction about delayed
553 loading in section
554\begin_inset LatexCommand \ref{sec:Internal-Signal-Handling:}
555
556\end_inset
557
558.
559\layout Standard
560
561But first we will start with intoducing some features of the
562\series bold
563OPimAccessFactory
564\series default
565.
566\layout Section
567
568Advanced Factory Features
569\begin_inset LatexCommand \label{sec:Advanced-Factory-Features}
570
571\end_inset
572
573
574\layout Standard
575
576In the previous chapter we used the operation
577\begin_inset Quotes gld
578\end_inset
579
580defaultAccess()
581\begin_inset Quotes grd
582\end_inset
583
584 to request an access-object to the dafault backend.
585 Whether this default backend will access the XML, VCard or SQLite database
586 type, this is defined by the configuration file
587\begin_inset Quotes gld
588\end_inset
589
590pimaccess.conf
591\begin_inset Quotes grd
592\end_inset
593
594 which is stored in the directory
595\begin_inset Quotes gld
596\end_inset
597
598Settings
599\begin_inset Quotes grd
600\end_inset
601
602, stored in the user home directory.
603 Changing this setting will take effect to all applications using
604\begin_inset Quotes gld
605\end_inset
606
607defaultAccess()
608\begin_inset Quotes grd
609\end_inset
610
611.
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
614 database to an other.
615
616\layout Standard
617
618If the developer wants to select a special database type for sure, he has
619 to use the oparation
620\emph on
621create()
622\emph default
623 which has the following parameters:
624\layout LyX-Code
625
626T * create (OPimGlobal::PimType type, OPimGlobal::DatabaseStyle dbStyle,
627 const QString &appName, const QString &fileName=QString::null)
628\layout Standard
629
630Some paramters are already known, like type and appName (see section
631\begin_inset LatexCommand \ref{sec:Instantiate-the-Access}
632
633\end_inset
634
635).
636 The new parameter
637\begin_inset Quotes gld
638\end_inset
639
640dbStyle
641\begin_inset Quotes grd
642\end_inset
643
644 defines which database type should be selected.
645 Possible values could be found in the enumeration
646\emph on
647DataBaseStyle
648\emph default
649 in the class
650\series bold
651OPimGlobal
652\series default
653 (see
654\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1Pim_1_1OPimGlobal.html}
655
656\end_inset
657
658).
659
660\begin_inset Quotes gld
661\end_inset
662
663DEFAULT
664\begin_inset Quotes grd
665\end_inset
666
667 selects the default database and therefore behaves exactly as the operation
668
669\begin_inset Quotes gld
670\end_inset
671
672defaultAccess()
673\begin_inset Quotes grd
674\end_inset
675
676 above.
677
678\begin_inset Quotes gld
679\end_inset
680
681UNKOWN
682\begin_inset Quotes grd
683\end_inset
684
685 is just defined for internal reasons and should not be used be the developer.
686 The remaining values (
687\begin_inset Quotes gld
688\end_inset
689
690XML
691\begin_inset Quotes grd
692\end_inset
693
694,
695\begin_inset Quotes gld
696\end_inset
697
698SQL
699\begin_inset Quotes grd
700\end_inset
701
702,
703\begin_inset Quotes gld
704\end_inset
705
706VCARD
707\begin_inset Quotes grd
708\end_inset
709
710) should be used to select the desired database backend.
711 The last parameter
712\begin_inset Quotes gld
713\end_inset
714
715fileName
716\begin_inset Quotes grd
717\end_inset
718
719 is used to select a special file name and path to the database file.
720 Thus, you can use it to access database files which don't reside on the
721 default path or have other filenames as it is defined by the platform as
722 default (in normal cases
723\begin_inset Quotes gld
724\end_inset
725
726~/Applications/<name of application>/
727\begin_inset Quotes grd
728\end_inset
729
730).
731\layout Standard
732
733In the next section we will discuss how searching and sorting take place
734 with this API.
735\layout Section
736
737Special Features: Searching and Sorting
738\begin_inset LatexCommand \label{sec:Special-Features:-Searching}
739
740\end_inset
741
742
743\layout Standard
744
745In most cases it is not sufficient to receive just a list of all information
746 in a database.
747 It is essential to get a subset of the information available and to be
748 able to sort it.
749 For this kind of excercise we provide some special operations which provide
750 searching and sorting in an incremental manner
751\begin_inset Foot
752collapsed true
753
754\layout Standard
755
756FIXME: matchRegexp() does take a list of uid's.
757 Therefore it is currently not possible to use it in an incremental manner!
758 (se)
759\end_inset
760
761.
762 Therfore it is possible to research a
763\begin_inset Quotes gld
764\end_inset
765
766List
767\begin_inset Quotes grd
768\end_inset
769
770 which was returned by a previous search query and to sort it afterwards.
771 Before we will take a close look into sorting, we will start with searching.
772 There exist two different ways of searching:
773\layout Enumerate
774
775Search a complete database for a special regular expression, using
776\begin_inset Quotes gld
777\end_inset
778
779matchRegexp ()
780\begin_inset Quotes grd
781\end_inset
782
783.
784 This search type returns all records which contains the given regular expressio
785n
786\emph on
787anywhere
788\emph default
789 in the dataset.
790 This search type is used for example by the opie search tool (OSearch)
791 (see
792\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/osearch/}
793
794\end_inset
795
796 and
797\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/osearch/adresssearch.cpp?rev=1.12&content-type=text/x-cvsweb-markup}
798
799\end_inset
800
801).
802\layout Enumerate
803
804Define a so called
805\begin_inset Quotes gld
806\end_inset
807
808Query By Example
809\begin_inset Quotes grd
810\end_inset
811
812 search query which allows to define what should be searched and which internal
813 data fields should be taken into account.
814 This is a very advanced search function which allows to search in a very
815 fine granular manner.
816\layout Standard
817
818We will start with the first and very simple
819\begin_inset Quotes grd
820\end_inset
821
822matchRegexp()
823\begin_inset Quotes grd
824\end_inset
825
826, followed by the query by example search query.
827\layout Subsection
828
829Searching with
830\begin_inset Quotes gld
831\end_inset
832
833matchRegexp()
834\begin_inset Quotes grd
835\end_inset
836
837
838\layout Standard
839
840The function is defined like this:
841\layout LyX-Code
842
843List matchRegexp (const QRegExp &r);
844\layout Standard
845
846The
847\begin_inset Quotes gld
848\end_inset
849
850List
851\begin_inset Quotes grd
852\end_inset
853
854 is still a OPimRecordList which contains 0 or more uid's of matching records.
855 As already discussed in section
856\begin_inset LatexCommand \ref{sec:Accessing-the-access-object}
857
858\end_inset
859
860 you have to use the
861\begin_inset Quotes gld
862\end_inset
863
864find()
865\begin_inset Quotes grd
866\end_inset
867
868 operation to request the real records.
869\layout Subsection
870
871Searching with Query By Example
872\layout Standard
873
874The query by example search style is working is using a data object (for
875 instance an OPimContact) to store the search query.
876 For instance, if you want to request all entries which contains the last
877 name
878\begin_inset Quotes gld
879\end_inset
880
881Eilers
882\begin_inset Quotes grd
883\end_inset
884
885 and the home zip number should start with
886\begin_inset Quotes gld
887\end_inset
888
8893
890\begin_inset Quotes grd
891\end_inset
892
893 you have to do the following:
894\layout LyX-Code
895
896OPimContact searchQuery;
897\layout LyX-Code
898
899searchQuery.setLastName(
900\begin_inset Quotes gld
901\end_inset
902
903Eilers
904\begin_inset Quotes grd
905\end_inset
906
907 );
908\layout LyX-Code
909
910searchQuery.setHomeZip(
911\begin_inset Quotes gld
912\end_inset
913
9143*
915\begin_inset Quotes grd
916\end_inset
917
918 );
919\layout Standard
920
921We use a usual
922\begin_inset Quotes gld
923\end_inset
924
925OPimContact
926\begin_inset Quotes grd
927\end_inset
928
929 and fill into two fields the search information.
930 As we just want to search for entries which zip number starts with a
931\begin_inset Quotes gld
932\end_inset
933
9343
935\begin_inset Quotes grd
936\end_inset
937
938 we use the Wildcard
939\begin_inset Quotes gld
940\end_inset
941
942*
943\begin_inset Quotes grd
944\end_inset
945
946 as we would do for finding files in a filesystem.
947\layout Standard
948
949The next step is to put this query into the operation which is defined like
950 this:
951\layout LyX-Code
952
953List queryByExample (const T& query, int querySettings, const QDateTime
954 &startperiod=QDateTime())
955\layout Standard
956
957The first parameter
958\begin_inset Quotes gld
959\end_inset
960
961query
962\begin_inset Quotes grd
963\end_inset
964
965 should used to set our query, but we have to set the parameter
966\begin_inset Quotes gld
967\end_inset
968
969querySettings
970\begin_inset Quotes grd
971\end_inset
972
973 to configure the search properly.
974 This settings are defined by the enum QuerySettings in the class
975\series bold
976OPimBase
977\series default
978 (see
979\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w19}
980
981\end_inset
982
983).
984 The meaning of all settings will be discussed later.
985 For the first turn we will just concentrate on the things we need in this
986 case.
987 As we use Wildcards in
988\begin_inset Quotes gld
989\end_inset
990
991setHomeZip
992\begin_inset Quotes grd
993\end_inset
994
995 we have to use
996\begin_inset Quotes gld
997\end_inset
998
999WildCards
1000\begin_inset Quotes grd
1001\end_inset
1002
1003.
1004 And we want to be sure to find lower case names, too, which may be mistyped
1005 (like
1006\begin_inset Quotes gld
1007\end_inset
1008
1009eilers
1010\begin_inset Quotes grd
1011\end_inset
1012
1013,
1014\begin_inset Quotes gld
1015\end_inset
1016
1017eIlers
1018\begin_inset Quotes grd
1019\end_inset
1020
1021, ...).
1022 Thus we have to use the
1023\begin_inset Quotes gld
1024\end_inset
1025
1026IgnoreCase
1027\begin_inset Quotes grd
1028\end_inset
1029
1030 setting which is to combine with the other using an
1031\begin_inset Quotes gld
1032\end_inset
1033
1034or
1035\begin_inset Quotes grd
1036\end_inset
1037
1038 operator.
1039 The last parameter
1040\begin_inset Quotes gld
1041\end_inset
1042
1043endperiod
1044\begin_inset Quotes grd
1045\end_inset
1046
1047 will be ignored for this case which will look like this:
1048\layout LyX-Code
1049
1050use namespace Opie;
1051\layout LyX-Code
1052
1053[...]
1054\layout LyX-Code
1055
1056List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase::
1057IgnoreCase );
1058\layout Standard
1059
1060This operation may return a list of entries which can be accesses as usual,
1061 using the
1062\begin_inset Quotes gld
1063\end_inset
1064
1065find()
1066\begin_inset Quotes grd
1067\end_inset
1068
1069 operation.
1070\layout Standard
1071
1072It should be clear at this stage, that this query is very powerful and -
1073 depending to the querySettings - could be very complicated to implement.
1074 Thus, not all backends do support all features defined by querySettings
1075\begin_inset Foot
1076collapsed true
1077
1078\layout Standard
1079
1080At this time, just the contact database for XML and VCard is supporting
1081 all queries and combination of them.
1082 All others just support subsets.
1083\end_inset
1084
1085.
1086 To check which settings are supported and to be able to react dynamically
1087 on missing features (for instance to disable some search features in the
1088 application) we provide the following operations:
1089\layout LyX-Code
1090
1091bool hasQuerySettings( uint querySettings );
1092\layout LyX-Code
1093
1094uint querySettings();
1095\layout Standard
1096
1097The first operation
1098\begin_inset Quotes gld
1099\end_inset
1100
1101hasQuerySettings()
1102\begin_inset Quotes grd
1103\end_inset
1104
1105 may be used to ask whether the database can handle the given query settings.
1106 In this example a call to
1107\layout LyX-Code
1108
1109hasQuerySettings( OPimBase::WildCards | OpimBase::IgnoreCase );
1110\layout Standard
1111
1112should be answered with
1113\begin_inset Quotes gld
1114\end_inset
1115
1116true
1117\begin_inset Quotes grd
1118\end_inset
1119
1120.
1121 If you need to ask which kind of queries are supported, the operation
1122\begin_inset Quotes gld
1123\end_inset
1124
1125querySettings()
1126\begin_inset Quotes grd
1127\end_inset
1128
1129 will be your friend.
1130 It will return an unsigned integer value where a
1131\begin_inset Quotes gld
1132\end_inset
1133
11341
1135\begin_inset Quotes grd
1136\end_inset
1137
1138 is set for every available feature.
1139\layout Standard
1140
1141The last parameter is called
1142\begin_inset Quotes gld
1143\end_inset
1144
1145startperiod
1146\begin_inset Quotes grd
1147\end_inset
1148
1149 which is used to set a time interval:
1150\layout Standard
1151
1152In some cases, a time interval should be set to find for instance all entries
1153 between two dates (used for example by the birthday reminder for today
1154 (see here:
1155\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/today/plugins/addressbook/addresspluginwidget.cpp?rev=1.14&content-type=text/x-cvsweb-markup}
1156
1157\end_inset
1158
1159)) as requested by the setting
1160\begin_inset Quotes gld
1161\end_inset
1162
1163OPimBase::DateDiff
1164\begin_inset Quotes grd
1165\end_inset
1166
1167.
1168 The date and time in the query object is used as the
1169\series bold
1170end
1171\series default
1172 of the interval.
1173 The start will be defined by the last parameter (if nothing is set, the
1174 current date will be taken!).
1175 Therefore, it is possible to set a time frame for all searched entries.
1176\layout Section
1177
1178Generic Access: OPimBase and OPimRecord
1179\begin_inset LatexCommand \label{sec:Generic-Access:-OPimBase}
1180
1181\end_inset
1182
1183
1184\layout Section
1185
1186Caching
1187\layout Standard
1188
1189Need to be written.
1190 Implementation is found at:
1191\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}
1192
1193\end_inset
1194
1195
1196\layout Section
1197
1198Internal Signal Handling: Automatic Propagation of Changes
1199\begin_inset LatexCommand \label{sec:Internal-Signal-Handling:}
1200
1201\end_inset
1202
1203
1204\layout Standard
1205
1206Need to be written and is not implemented completly!
1207\layout Chapter
1208
1209Howto Extend and Write New Backends
1210\layout Standard
1211
1212Need to be written.
1213\the_end