summaryrefslogtreecommitdiff
path: root/development/pim/pim_howto/pim_howto.lyx
blob: 1e43d63d0676d93a4c7d097c6925d745393025fa (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass scrbook
\begin_preamble
\fancyhead{}
\fancyfoot{}
\fancyhead[LE,RO]{\slshape \leftmark}
\fancyhead[LO,RE]{\slshape \leftmark}
\fancyhead[RE,LO]{\thepage}
%\fancyhead[LO,RE]{}
% \usepackage{ae}
\usepackage[bookmarksopen,colorlinks]{hyperref}
% \pdfoutput=1
% \pdfcompresslevel=8
% \pdfinfo{
% /Title   ClearSim-RealtTime und Andere
%  /Creator (Tex)
%  /Author  (Stefan Eilers)
%  /Subject ()
%  /Keywords (Simulation,Real-Time,ClearSim,prototype,efsm)
% }
\renewcommand\familydefault{\sfdefault}

\usepackage{multicol}
\newcommand\NrCol{3}
\renewenvironment{theindex}
               {\columnseprule \z@
                \columnsep 35\p@
                \section*{\indexname}%
                \@mkboth{\MakeUppercase\indexname}%
                        {\MakeUppercase\indexname}%
                \begin{multicols}{\NrCol}\thispagestyle{plain}\parindent\z@
                \parskip\z@ \@plus .3\p@\relax
                \let\item\@idxitem}
               {\clearpage %
                \end{multicols}}

\renewenvironment{theindex}
               {\if@twocolumn
                  \@restonecolfalse
                \else
                  \@restonecoltrue
                \fi
                \columnseprule \z@
                \columnsep 35\p@
                \twocolumn[\refstepcounter{section}%
                  \section{\indexname}]%
                \@mkboth{\MakeUppercase\indexname}%
                        {\MakeUppercase\indexname}%
                \thispagestyle{plain}\parindent\z@
                \parskip\z@ \@plus .3\p@\relax
                \let\item\@idxitem}
               {\if@restonecol\onecolumn\else\clearpage\fi}
\end_preamble
\language american
\inputencoding default
\fontscheme ae
\graphics default
\float_placement htbp
\paperfontsize default
\spacing single 
\papersize a4paper
\paperpackage widemarginsa4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 2
\paperpagestyle fancy

\layout Title

How to use the Opie-Pim API without getting tired!
\newline 
(Aka: Hitchhikers Guide Through the Opie-Pim API)
\newline 
(Pre V 0.1)
\layout Author


\family sans 
Stefan Eilers
\layout Section*


\family sans 
Abstract
\layout Standard

The Opie-Pim API provides a powerfull access interface to the PIM (Personal
 Information Management) data which contains your contact information, the
 dates in your calendar tool (in this paper called datebook events) and
 your todo events.
 Beside providing full featured access to this information, it covers the
 real management of this informantion - the access of the databases - from
 the user.
 
\layout Standard

While starting to read the automatically generated API-documentation, the
 user may be confused by a lot of unnecessary classes and details which
 makes the quick start not as easy as possible.
 Due to the fact that a user will not need most of the details, this paper
 should help to start to become confortable with those details he need to
 solve his problems.
\layout Standard


\begin_inset LatexCommand \tableofcontents{}

\end_inset 


\layout Chapter

Introduction
\layout Standard

Before starting to jump into the work, we should introduce some specialties
 of the PIM API, first.
 To know these facts should help to avoid possible irritations and misunderstand
ings:
\layout Enumerate

The PIM-API heavily uses C++ templates (as known as generic classes), but
 you don't have to understand very deeple what templates are doing and how
 they work! Most of the API works without even seeing the templates.
 In some cases we have to use them (for instance to use the factory classes),
 but this guide will provide examples which should help to find the path
 through.
 But it is a good idea to read some short introduction of templates to avoid
 unnecessary mistakes.
\layout Enumerate

The PIM-API is split into two parts: The 
\emph on 
frontend
\emph default 
 and the 
\emph on 
backend.

\emph default 
 While the frontend provides the API for the user, the backend implements
 how to access the databases and what to do with the data.
 As we just want to access data, this paper just focuses the frontend.
 Thus, you should ignore all classes which contains something like 
\begin_inset Quotes gld
\end_inset 

backend
\begin_inset Quotes grd
\end_inset 

 in its name! Backends are just interesting for people who want to extend
 or implement new possibilities about how to access databases, which will
 be discussed at the end of this paper.
 Currently, you just have to understand that there do exist several backends
 for every type of PIM data (Contact, Todo, Datebook) which controls whether
 you want to access an XML, SQL (SQLite) or VCard style database.
 If you just want to use the default database, you even don't have to think
 about this!
\layout Standard

In the next chapter, we will show how to access the default database as
 easy as possible.
 This will be the solution for most of the problems you may face while accessing
 the PIM data.
\layout Chapter

Quick Guide to access the Database
\layout Standard

In this chapter we will introduce very quickly how to get access to the
 database and how to access data.
 It should help to find the right directions.
 If it is too short for you, you should read the next chapter afterwards
 to find a more complete and detailed view into the system.
\layout Section

Instantiate the access-object
\begin_inset LatexCommand \label{sec:Instantiate-the-Access}

\end_inset 


\layout Standard

To gain access to the database you need something we will call
\emph on 
 access-object
\emph default 
 (an instance of the access-class for the database) which handles the database
 access.
 Requesting such an object is very easy by using the operation 
\emph on 
defaultAccess()
\emph default 
 of the factory class 
\series bold 
OPimAccessFactory
\series default 
 (see 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessFactory.html}

\end_inset 

).
 This operation is defined like this:
\layout LyX-Code

T* defaultAccess (typename OPimGlobal::PimType type, const QString &appName)
\layout Standard

You just have to add the following lines to your source code to use it (this
 example is for accessing the contact database):
\layout LyX-Code

#include <opie2/opimaccessfactory.h>
\layout LyX-Code

use namespace Opie;
\layout Standard

[...]
\layout LyX-Code

OPimContactAccess* sourceDB = OPimAccessFactory<OPimContactAccess>::defaultAcces
s( OPimGlobal::CONTACTLIST, "my-app" );
\layout Standard

If everything works as expected, you will receive a pointer to the contact
 access-class which has to be used for accessing the database.
 Accessing the datebook database works equally
\begin_inset Foot
collapsed false

\layout Standard

The API will be changed in the future: ODateBookAccess will be renamed to
 OPimEventAccess.
\end_inset 

:
\layout LyX-Code

ODateBookAccess* sourceDB = OPimAccessFactory<ODatebookAccess>::defaultAccess(
 OPimGlobal::DATEBOOK, "my-app" );
\layout Standard

And the same for todo:
\layout LyX-Code

OPimTodoAccess* sourceDB = OPimAccessFactory<OPimTodoAccess>::defaultAccess(
 OPimGlobal::TODOLIST, "my-app" );
\layout Standard

Using 
\emph on 

\begin_inset Quotes gld
\end_inset 

defaultAccess()
\begin_inset Quotes grd
\end_inset 


\emph default 
, the default database is accessed automatically
\begin_inset Foot
collapsed false

\layout Standard

The configuration file 
\begin_inset Quotes gld
\end_inset 

pimaccess.conf
\begin_inset Quotes grd
\end_inset 

 defines which backend is selected as default!
\end_inset 

.
 If you want to use anything else, you have to read the next chapter to
 get the information how to do this.
 
\layout Standard

The last parameter 
\begin_inset Quotes gld
\end_inset 

my-app
\begin_inset Quotes grd
\end_inset 

 is very importand and should be equal for every instance of an application.
 Some database backends (like the XML backend) uses this string as an unique
 filename to create a journal file.
 If your application should run in several instances independently you will
 need multiple journal files and therefore several name strings!
\layout Standard

If the database access-object is is not needed anymore, you have to remove
 it by calling 
\emph on 
delete
\emph default 
:
\layout LyX-Code

delete sourceDB;
\layout Section

Accessing the Access-Object
\begin_inset LatexCommand \label{sec:Accessing-the-access-object}

\end_inset 


\layout Standard

After receiving the access-object, we just have to use its API which is
 mainly defined by the common base class 
\series bold 
OPimAccessTemplate
\series default 
 (see 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimAccessTemplate.html}

\end_inset 

).
 This API is inherited by all access-classes and therefore common to all
 access-objects.
 We will show the most important operations of it first (please replace
 
\begin_inset Quotes gld
\end_inset 

T
\begin_inset Quotes grd
\end_inset 

 below with the corresponding 
\emph on 
data-class
\emph default 
 for the selected access-class: OPimContact
\begin_inset Foot
collapsed false

\layout Standard

see 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContact.html}

\end_inset 


\end_inset 

 for OPimContactAccess, OPimEvent
\begin_inset Foot
collapsed false

\layout Standard

see 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimEvent.html}

\end_inset 


\end_inset 

 for ODateBookAccess and OPimTodo
\begin_inset Foot
collapsed false

\layout Standard

see 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodo.html}

\end_inset 


\end_inset 

 for OPimTodoAccess):
\layout LyX-Code

bool load ();
\layout LyX-Code

bool reload ();
\layout LyX-Code

bool save ();
\layout LyX-Code

\layout LyX-Code

bool add (const T& t);
\layout LyX-Code

bool remove (const T& t);
\layout LyX-Code

bool replace (const T& t);
\layout Standard

After receiving an access-object, we have to load the existing dataset into
 the backend, which is done by the 
\begin_inset Quotes gld
\end_inset 

load()
\begin_inset Quotes grd
\end_inset 

 operation.
 The 
\begin_inset Quotes gld
\end_inset 

save()
\begin_inset Quotes grd
\end_inset 

 operation is important to write back (or 
\emph on 
commit
\emph default 
) local changes into the global database.
 After doing this, the changes are globally accessable! The 
\begin_inset Quotes gld
\end_inset 

reload()
\begin_inset Quotes grd
\end_inset 

 operation loads changes of the global database into the local set 
\series bold 
without
\series default 
 removing any local changes
\begin_inset Foot
collapsed false

\layout Standard

We should check whether all databases behave like this! (se)
\end_inset 

.
 This may be done after receiving information about any change by an other
 application which is not in scope of this chapter.
 The other operations are self explaining and should work as expected.
\layout Standard

If you want to work with the existing dataset, you need to get a list of
 all available information.
 This list is returned by the call 
\begin_inset Quotes gld
\end_inset 

allRecords()
\begin_inset Quotes grd
\end_inset 

 which returns a list of all available records as an 
\series bold 
OPimRecordList
\series default 
 (see 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html}

\end_inset 

).
 
\layout LyX-Code

List allRecords();
\layout Standard

In fact, this 
\emph on 
List
\emph default 
 just contains a list of uid's to take care of memory space.
 As every record is identified by an unique identification number which
 is called UID (Unique Identification), these numbers just exists once in
 the database which is currently on access! To receive the real record,
 you have to use the operation 
\begin_inset Quotes gld
\end_inset 

find()
\begin_inset Quotes grd
\end_inset 

 with a valid UID as parameter:
\layout LyX-Code

T find (UID uid);
\layout Standard

This is all you need to realize a basic access to the PIM-Databases! The
 next chapter will guide you into more details of the PIM-API.
\layout Chapter

How to Access PIM-Data: Detailed View
\layout Standard

As shown in the previous chapter, all we need to access the PIM-Database
 is to request an access-object from the OPimAccessFactory and to use it.
 We will now introduce some special features of this factory (see section
 
\begin_inset LatexCommand \ref{sec:Advanced-Factory-Features}

\end_inset 

), followed by some very important features like searching and sorting in
 section 
\begin_inset LatexCommand \ref{sec:Special-Features:-Searching}

\end_inset 

.
 If you are interested in accessing data without take care about their types,
 section 
\begin_inset LatexCommand \ref{sec:Generic-Access:-OPimBase}

\end_inset 

 will show how to do this, followed by a short introduction about delayed
 loading in section 
\begin_inset LatexCommand \ref{sec:Internal-Signal-Handling:}

\end_inset 

.
\layout Standard

But first we will start with introducing some features of the 
\series bold 
OPimAccessFactory
\series default 
.
\layout Section

Advanced Factory Features
\begin_inset LatexCommand \label{sec:Advanced-Factory-Features}

\end_inset 


\layout Standard

In the previous chapter we used the operation 
\begin_inset Quotes gld
\end_inset 

defaultAccess()
\begin_inset Quotes grd
\end_inset 

 to request an access-object to the default backend.
 Whether this default backend will access the XML, VCard or SQLite database
 type, is defined by the configuration file 
\begin_inset Quotes gld
\end_inset 

pimaccess.conf
\begin_inset Quotes grd
\end_inset 

 which is stored in the directory 
\begin_inset Quotes gld
\end_inset 

Settings
\begin_inset Quotes grd
\end_inset 

, stored in the user home directory.
 Changing this setting will take effect to all applications using 
\begin_inset Quotes gld
\end_inset 

defaultAccess()
\begin_inset Quotes grd
\end_inset 

.
 Therefore it is not a good idea to modify a global setting, if an application
 should access a special database type, for instance to move data from one
 database to an other.
 
\layout Standard

If the developer wants to select a special database type for sure without
 unnecessary side effects, he has to use the operation 
\emph on 
create()
\emph default 
 which has the following parameters:
\layout LyX-Code

T* create (OPimGlobal::PimType type, OPimGlobal::DatabaseStyle dbStyle,
 const QString &appName, const QString &fileName=QString::null)
\layout Standard

Some parameters are already known, like type and appName (see section 
\begin_inset LatexCommand \ref{sec:Instantiate-the-Access}

\end_inset 

).
 The new parameter 
\begin_inset Quotes gld
\end_inset 

dbStyle
\begin_inset Quotes grd
\end_inset 

 defines which database type should be selected.
 Possible values could be found in the enumeration 
\emph on 
DataBaseStyle
\emph default 
 in the class 
\series bold 
OPimGlobal
\series default 
 (see 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1Pim_1_1OPimGlobal.html}

\end_inset 

).
 
\begin_inset Quotes gld
\end_inset 

DEFAULT
\begin_inset Quotes grd
\end_inset 

 selects the default database and therefore behaves exactly as the operation
 
\begin_inset Quotes gld
\end_inset 

defaultAccess()
\begin_inset Quotes grd
\end_inset 

 above.
 
\begin_inset Quotes gld
\end_inset 

UNKOWN
\begin_inset Quotes grd
\end_inset 

 is just defined for internal reasons and should not be used be the developer.
 The remaining values (
\begin_inset Quotes gld
\end_inset 

XML
\begin_inset Quotes grd
\end_inset 

, 
\begin_inset Quotes gld
\end_inset 

SQL
\begin_inset Quotes grd
\end_inset 

, 
\begin_inset Quotes gld
\end_inset 

VCARD
\begin_inset Quotes grd
\end_inset 

) should be used to select the desired database backend.
 The last parameter 
\begin_inset Quotes gld
\end_inset 

fileName
\begin_inset Quotes grd
\end_inset 

 is used to select a special file name and path to the database file.
 Thus, you can use it to access database files which don't reside on the
 default path or have other filenames as it is defined by the platform as
 default (in normal cases 
\begin_inset Quotes gld
\end_inset 

~/Applications/<name of application>/
\begin_inset Quotes grd
\end_inset 

).
\layout Standard

In the next section we will discuss how searching and sorting take place
 with this API.
\layout Section

Special Features: Searching and Sorting
\begin_inset LatexCommand \label{sec:Special-Features:-Searching}

\end_inset 


\layout Standard

In most cases it is not sufficient to receive just a list of all information
 in a database.
 It is essential to get a subset of the information available and to be
 able to sort it.
 For this kind of exercise we provide some special operations which provide
 searching and sorting in an incremental manner
\begin_inset Foot
collapsed false

\layout Standard

FIXME: matchRegexp() does take a list of uid's.
 Therefore it is currently not possible to use it in an incremental manner!
 (se)
\end_inset 

.
 Therefore it is possible to research a 
\begin_inset Quotes gld
\end_inset 

List
\begin_inset Quotes grd
\end_inset 

 which was returned by a previous search query and to sort it afterwards.
 Before we will take a close look into sorting, we will start with searching.
 There exist two different ways of searching:
\layout Enumerate

Search a complete database for a special regular expression, using 
\begin_inset Quotes gld
\end_inset 

matchRegexp ()
\begin_inset Quotes grd
\end_inset 

.
 This search type returns all records which contains the given regular expressio
n 
\emph on 
anywhere
\emph default 
 in the dataset.
 This search type is used for example by the opie search tool (OSearch)
 (see 
\begin_inset LatexCommand \url{http://handhelds.org/cgi-bin/cvsweb.cgi/opie/core/pim/osearch/}

\end_inset 

 and 
\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}

\end_inset 

).
\layout Enumerate

Define a so called 
\begin_inset Quotes gld
\end_inset 

Query By Example
\begin_inset Quotes grd
\end_inset 

 search query which allows to define what should be searched and which internal
 data fields should be taken into account.
 This is a very advanced search function which allows to search in a very
 fine granular manner.
\layout Standard

We will start with the first and very simple 
\begin_inset Quotes grd
\end_inset 

matchRegexp()
\begin_inset Quotes grd
\end_inset 

, followed by the query by example search query.
\layout Subsection

Searching with 
\begin_inset Quotes gld
\end_inset 

matchRegexp()
\begin_inset Quotes grd
\end_inset 


\layout Standard

The function is defined like this:
\layout LyX-Code

List matchRegexp (const QRegExp& r);
\layout Standard

The 
\begin_inset Quotes gld
\end_inset 

List
\begin_inset Quotes grd
\end_inset 

 is still a OPimRecordList which contains 0 or more uid's of matching records.
 As already discussed in section 
\begin_inset LatexCommand \ref{sec:Accessing-the-access-object}

\end_inset 

 you have to use the 
\begin_inset Quotes gld
\end_inset 

find()
\begin_inset Quotes grd
\end_inset 

 operation to request the real records.
\layout Subsection

Searching with Query By Example
\layout Standard

The query by example search style is working is using a data object (for
 instance an OPimContact) to store the search query.
 For instance, if you want to request all entries which contains the last
 name 
\begin_inset Quotes gld
\end_inset 

Eilers
\begin_inset Quotes grd
\end_inset 

 and the home zip number should start with 
\begin_inset Quotes gld
\end_inset 

3
\begin_inset Quotes grd
\end_inset 

 you have to do the following:
\layout LyX-Code

OPimContact searchQuery;
\layout LyX-Code

searchQuery.setLastName( 
\begin_inset Quotes eld
\end_inset 

Eilers
\begin_inset Quotes erd
\end_inset 

 );
\layout LyX-Code

searchQuery.setHomeZip( 
\begin_inset Quotes eld
\end_inset 

3*
\begin_inset Quotes srd
\end_inset 

 );
\layout Standard

We use an usual 
\begin_inset Quotes gld
\end_inset 

OPimContact
\begin_inset Quotes grd
\end_inset 

 and fill into two fields the query information.
 All filled fields are taken for the search operation (using an 
\begin_inset Quotes gld
\end_inset 

AND
\begin_inset Quotes grd
\end_inset 

 operation), the unused ones are simply ignored.
 As we just want to search for entries which zip number starts with a 
\begin_inset Quotes gld
\end_inset 

3
\begin_inset Quotes grd
\end_inset 

 we use the Wildcard 
\begin_inset Quotes gld
\end_inset 

*
\begin_inset Quotes grd
\end_inset 

 as we would do to find files in a filesystem.
\layout Standard

The next step is to put this query into the operation which is defined like
 this:
\layout LyX-Code

List queryByExample (const T& query, int querySettings, const QDateTime&
 startperiod=QDateTime())
\layout Standard

The first parameter 
\begin_inset Quotes gld
\end_inset 

query
\begin_inset Quotes grd
\end_inset 

 should used to set our query, but we have to set the parameter 
\begin_inset Quotes gld
\end_inset 

querySettings
\begin_inset Quotes grd
\end_inset 

 to configure the search properly.
 This settings are defined by the enumeration 
\begin_inset Quotes gld
\end_inset 

QuerySettings
\begin_inset Quotes grd
\end_inset 

 in the class 
\series bold 
OPimBase
\series default 
 (see 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w19}

\end_inset 

).
 The meaning of all settings will be discussed later.
 For the first turn we will just concentrate on the things we need in this
 case.
 As we use Wildcards in 
\begin_inset Quotes gld
\end_inset 

setHomeZip
\begin_inset Quotes grd
\end_inset 

 we have to use 
\begin_inset Quotes gld
\end_inset 

WildCards
\begin_inset Quotes grd
\end_inset 

.
 And we want to be sure to find lower case names, too, which may be mistyped
 (like 
\begin_inset Quotes gld
\end_inset 

eilers
\begin_inset Quotes grd
\end_inset 

, 
\begin_inset Quotes gld
\end_inset 

eIlers
\begin_inset Quotes grd
\end_inset 

, ...).
 Thus, we have to use the 
\begin_inset Quotes gld
\end_inset 

IgnoreCase
\begin_inset Quotes grd
\end_inset 

 setting which is to combine with the other using an 
\begin_inset Quotes gld
\end_inset 

or
\begin_inset Quotes grd
\end_inset 

 operator.
 The last parameter 
\begin_inset Quotes gld
\end_inset 

endperiod
\begin_inset Quotes grd
\end_inset 

 will be ignored for this case which will look like this:
\layout LyX-Code

use namespace Opie;
\layout LyX-Code

[...]
\layout LyX-Code

List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase::
IgnoreCase );
\layout Standard

This operation may return a list of entries which can be accessed as above,
 using the 
\begin_inset Quotes gld
\end_inset 

find()
\begin_inset Quotes grd
\end_inset 

 operation.
\layout Standard

It should be clear at this stage, that this query is very powerful and -
 depending to the querySettings - could be very complicated to implement.
 Thus, not all backends do support all features defined by querySettings
\begin_inset Foot
collapsed false

\layout Standard

At this time, just the contact database for XML and VCard is supporting
 all queries and combination of them.
 All others just support subsets.
\end_inset 

.
 To check which settings are supported and to be able to react dynamically
 on missing features (for instance to disable some search features in the
 application) we provide the following operations:
\layout LyX-Code

bool hasQuerySettings( uint querySettings );
\layout LyX-Code

uint querySettings();
\layout Standard

The first operation 
\begin_inset Quotes gld
\end_inset 

hasQuerySettings()
\begin_inset Quotes grd
\end_inset 

 may be used to ask whether the database can handle the given query settings.
 In this example a call to 
\layout LyX-Code

hasQuerySettings( OPimBase::WildCards | OpimBase::IgnoreCase );
\layout Standard

should be answered with 
\begin_inset Quotes gld
\end_inset 

true
\begin_inset Quotes grd
\end_inset 

.
 If you need to ask which kind of queries are supported, the operation 
\begin_inset Quotes gld
\end_inset 

querySettings()
\begin_inset Quotes grd
\end_inset 

 will be your friend.
 It will return an unsigned integer value where a 
\begin_inset Quotes gld
\end_inset 

1
\begin_inset Quotes grd
\end_inset 

 is set for every available feature.
\layout Standard

The last parameter is called 
\begin_inset Quotes gld
\end_inset 

startperiod
\begin_inset Quotes grd
\end_inset 

 which is used to set a time interval: 
\layout Standard

In some cases, a time interval should be set to find for instance all entries
 between two dates (used for example by the birthday reminder for today
 (see here: 
\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}

\end_inset 

)) as requested by the setting 
\begin_inset Quotes gld
\end_inset 

OPimBase::DateDiff
\begin_inset Quotes grd
\end_inset 

.
 The date and time in the query object is used as the 
\series bold 
end
\series default 
 of the interval.
 The start will be defined by the last parameter (if nothing is set, the
 current date will be taken!).
 Therefore, it is possible to set a time frame for all searched entries.
\layout Standard

If you want to do incremental search operations, you may use the special
 
\begin_inset Quotes gld
\end_inset 

queryByExample()
\begin_inset Quotes grd
\end_inset 

 which takes a 
\begin_inset Quotes gld
\end_inset 

List
\begin_inset Quotes grd
\end_inset 

 as the first parameter.
 The search operation will just occur on this set of uid's!
\layout Subsection

Sorting
\layout Standard

To sort a given dataset, you should use the following operation (or one
 of the others which behave slightly differently):
\layout LyX-Code

List sorted (const List& list, bool ascending, int sortOrder, int sortFilter,
 const QArray< UID >& cats);
\layout Standard

This sort operation takes a list of uid's as returned for instance from
 a search query.
 The parameter 
\begin_inset Quotes gld
\end_inset 

ascending
\begin_inset Quotes grd
\end_inset 

 defines whether the sort should be in an ascending order or not.
 
\begin_inset Quotes gld
\end_inset 

sortOrder
\begin_inset Quotes grd
\end_inset 

 is defined by the enumerations 
\begin_inset Quotes gld
\end_inset 

SortOrder
\begin_inset Quotes grd
\end_inset 

 and 
\begin_inset Quotes gld
\end_inset 

SortOrderBase
\begin_inset Quotes grd
\end_inset 

 and defines which field should be used to sort (see for 
\series bold 
OPimContactAccess
\series default 
: 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContactAccess.html}

\end_inset 

, for 
\series bold 
ODateBookAccess
\series default 
: 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1ODateBookAccess.html}

\end_inset 

 and for 
\series bold 
OPimTodoAccess
\series default 
: 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodoAccess.html}

\end_inset 

 and for common settings 
\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w21}

\end_inset 

).
\layout Standard

The 
\begin_inset Quotes gld
\end_inset 

sortFilter
\begin_inset Quotes grd
\end_inset 

 parameter allows to remove some entries which are not interesting for the
 result and is defined in the same classes as 
\begin_inset Quotes gld
\end_inset 

sortOrder
\begin_inset Quotes grd
\end_inset 

 by the enumeration 
\begin_inset Quotes gld
\end_inset 

SortFilter
\begin_inset Quotes grd
\end_inset 

 and 
\begin_inset Quotes gld
\end_inset 

SortFilterBase
\begin_inset Quotes grd
\end_inset 

.
 The list of id's in 
\begin_inset Quotes gld
\end_inset 

cats
\begin_inset Quotes grd
\end_inset 

 allows to remain just these entries which are included in the list of categorie
s.
\layout Standard

The returned list contains the same uid's as given via 
\begin_inset Quotes gld
\end_inset 

list
\begin_inset Quotes grd
\end_inset 

 (or a subset of it, as the sortFilter and category list removes some entries)
 with a modified order as 
\begin_inset Quotes gld
\end_inset 

sortOrder
\begin_inset Quotes grd
\end_inset 

 and 
\begin_inset Quotes gld
\end_inset 

ascending
\begin_inset Quotes grd
\end_inset 

 dictates.
\layout Standard

Therefore 
\begin_inset Quotes gld
\end_inset 

sorted()
\begin_inset Quotes grd
\end_inset 

 is more a combination of search and sort, as just a sort command.
 But this combination is exactly what the developer needs in most situations.
 
\layout Section

Generic Access: OPimBase and OPimRecord
\begin_inset LatexCommand \label{sec:Generic-Access:-OPimBase}

\end_inset 


\layout Section

Caching
\layout Standard

Need to be written.
 Implementation is found at: 
\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}

\end_inset 


\layout Section

Internal Signal Handling: Automatic Propagation of Changes
\begin_inset LatexCommand \label{sec:Internal-Signal-Handling:}

\end_inset 


\layout Standard

Need to be written and is not implemented completely!
\layout Chapter

Howto Extend and Write New Backends
\layout Standard

Need to be written.
\the_end