summaryrefslogtreecommitdiff
Unidiff
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--development/pim/pim_howto/pim_howto.lyx238
1 files changed, 218 insertions, 20 deletions
diff --git a/development/pim/pim_howto/pim_howto.lyx b/development/pim/pim_howto/pim_howto.lyx
index 2b08be8..4571996 100644
--- a/development/pim/pim_howto/pim_howto.lyx
+++ b/development/pim/pim_howto/pim_howto.lyx
@@ -98,69 +98,69 @@ Abstract
98The Opie-Pim API provides a powerfull access interface to the PIM (Personal 98The Opie-Pim API provides a powerfull access interface to the PIM (Personal
99 Information Management) data which contains your contact information, the 99 Information Management) data which contains your contact information, the
100 dates in your calender tool (in this paper called datebook events) and 100 dates in your calender tool (in this paper called datebook events) and
101 your todo events. 101 your todo events.
102 Beside providing full featured access to this information, it covers the 102 Beside providing full featured access to this information, it covers the
103 real management of this informantion - the access of the databases - from 103 real management of this informantion - the access of the databases - from
104 the user. 104 the user.
105 105
106\layout Standard 106\layout Standard
107 107
108While starting to read the automatically generated API-documentation, the 108While starting to read the automatically generated API-documentation, the
109 user may be confused by a lot of unneccessary classes and details which 109 user may be confused by a lot of unneccessary classes and details which
110 makes the quick start not as easy as expected. 110 makes the quick start not as easy as possible.
111 Due to the fact that a user who just want to access data will not need 111 Due to the fact that a user will not need most of the details, this paper
112 most of the details, this paper should help to start to be confortable 112 should help to start to become confortable with those details he need to
113 with the details he need to solve his problems. 113 solve his problems.
114\layout Standard 114\layout Standard
115 115
116 116
117\begin_inset LatexCommand \tableofcontents{} 117\begin_inset LatexCommand \tableofcontents{}
118 118
119\end_inset 119\end_inset
120 120
121 121
122\layout Chapter 122\layout Chapter
123 123
124Introduction 124Introduction
125\layout Standard 125\layout Standard
126 126
127Before starting to jump into the work, we should introduce some specialities 127Before starting to jump into the work, we should introduce some specialities
128 of the PIM API first. 128 of the PIM API, first.
129 To know these facts should help to avoid possible irritations and misunderstand 129 To know these facts should help to avoid possible irritations and misunderstand
130ings: 130ings:
131\layout Enumerate 131\layout Enumerate
132 132
133The PIM-API heavily uses C++ templates (as known as generic classes), but 133The PIM-API heavily uses C++ templates (as known as generic classes), but
134 you don't have to understand very deeple what templates are doing and how 134 you don't have to understand very deeple what templates are doing and how
135 they work! Most of the API works without even seeing the templates. 135 they work! Most of the API works without even seeing the templates.
136 In some cases whe have to use them (for instance to use the factory classes) 136 In some cases 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 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 unneccessary mistakes.
141\layout Enumerate 141\layout Enumerate
142 142
143The PIM-API is split into two parts: The 143The PIM-API is split into two parts: The
144\emph on 144\emph on
145frontend 145frontend
146\emph default 146\emph default
147 and the 147 and the
148\emph on 148\emph on
149backend. 149backend.
150 150
151\emph default 151\emph default
152 While the frontend provides the API for the user, the backend implements 152 While the frontend provides the API for the user, the backend implements
153 how to access the databases and what to do with the data. 153 how to access the databases and what to do with the data.
154 This paper just focusses the frontend as we just want to access data. 154 As we just want to access data, this paper just focusses the frontend.
155 Thus, you should ignore all classes which contains something like 155 Thus, you should ignore all classes which contains something like
156\begin_inset Quotes gld 156\begin_inset Quotes gld
157\end_inset 157\end_inset
158 158
159backend 159backend
160\begin_inset Quotes grd 160\begin_inset Quotes grd
161\end_inset 161\end_inset
162 162
163 in its name! Backends are just interessting for people who want to extend 163 in its name! Backends are just interessting for people who want to extend
164 or implement new possiblities about how to access databases, which will 164 or implement new possiblities 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
@@ -315,25 +315,25 @@ my-app
315 315
316If the database access-object is is not needed anymore, you have to remove 316If the database access-object is is not needed anymore, you have to remove
317 it by calling 317 it by calling
318\emph on 318\emph on
319delete 319delete
320\emph default 320\emph default
321: 321:
322\layout LyX-Code 322\layout LyX-Code
323 323
324delete sourceDB; 324delete sourceDB;
325\layout Section 325\layout Section
326 326
327Accessing the access-object 327Accessing the Access-Object
328\begin_inset LatexCommand \label{sec:Accessing-the-access-object} 328\begin_inset LatexCommand \label{sec:Accessing-the-access-object}
329 329
330\end_inset 330\end_inset
331 331
332 332
333\layout Standard 333\layout Standard
334 334
335After receiving the access-object, we just have to use its API which is 335After receiving the access-object, we just have to use its API which is
336 mainly defined by the common base class 336 mainly defined by the common base class
337\series bold 337\series bold
338OPimAccessTemplate 338OPimAccessTemplate
339\series default 339\series default
@@ -414,26 +414,26 @@ bool save ();
414 414
415\layout LyX-Code 415\layout LyX-Code
416 416
417bool add (const T& t); 417bool add (const T& t);
418\layout LyX-Code 418\layout LyX-Code
419 419
420bool remove (const T& t); 420bool remove (const T& t);
421\layout LyX-Code 421\layout LyX-Code
422 422
423bool replace (const T& t); 423bool replace (const T& t);
424\layout Standard 424\layout Standard
425 425
426After receiving an access-object, we have to load the existing dataset, 426After receiving an access-object, we have to load the existing dataset into
427 which is done by the 427 the backend, which is done by the
428\begin_inset Quotes gld 428\begin_inset Quotes gld
429\end_inset 429\end_inset
430 430
431load() 431load()
432\begin_inset Quotes grd 432\begin_inset Quotes grd
433\end_inset 433\end_inset
434 434
435 operation. 435 operation.
436 The 436 The
437\begin_inset Quotes gld 437\begin_inset Quotes gld
438\end_inset 438\end_inset
439 439
@@ -490,25 +490,25 @@ OPimRecordList
490 (see 490 (see
491\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html} 491\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimRecordList.html}
492 492
493\end_inset 493\end_inset
494 494
495). 495).
496 496
497\layout LyX-Code 497\layout LyX-Code
498 498
499List allRecords (); 499List allRecords ();
500\layout Standard 500\layout Standard
501 501
502In fact this 502In fact, this
503\emph on 503\emph on
504List 504List
505\emph default 505\emph default
506 just contains a list of uid's to take care of memory space. 506 just contains a list of uid's to take care of memory space.
507 As every record is identified by an unique identifaction number which is 507 As every record is identified by an unique identifaction number which is
508 called UID (Unique IDentification), these numbers just exists once in the 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 509 database which is currently on access! To receive the real record, you
510 have to use the operation 510 have to use the operation
511\begin_inset Quotes gld 511\begin_inset Quotes gld
512\end_inset 512\end_inset
513 513
514find() 514find()
@@ -574,25 +574,25 @@ Advanced Factory Features
574\layout Standard 574\layout Standard
575 575
576In the previous chapter we used the operation 576In the previous chapter we used the operation
577\begin_inset Quotes gld 577\begin_inset Quotes gld
578\end_inset 578\end_inset
579 579
580defaultAccess() 580defaultAccess()
581\begin_inset Quotes grd 581\begin_inset Quotes grd
582\end_inset 582\end_inset
583 583
584 to request an access-object to the dafault backend. 584 to request an access-object to the dafault 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, this is defined by the configuration file 586 type, is defined by the configuration file
587\begin_inset Quotes gld 587\begin_inset Quotes gld
588\end_inset 588\end_inset
589 589
590pimaccess.conf 590pimaccess.conf
591\begin_inset Quotes grd 591\begin_inset Quotes grd
592\end_inset 592\end_inset
593 593
594 which is stored in the directory 594 which is stored in the directory
595\begin_inset Quotes gld 595\begin_inset Quotes gld
596\end_inset 596\end_inset
597 597
598Settings 598Settings
@@ -606,26 +606,26 @@ Settings
606 606
607defaultAccess() 607defaultAccess()
608\begin_inset Quotes grd 608\begin_inset Quotes grd
609\end_inset 609\end_inset
610 610
611. 611.
612 Therefore it is not a good idea to modify a global setting, if an application 612 Therefore it is not a good idea to modify a global setting, if an application
613 should access a special database type, for instance to move data from one 613 should access a special database type, for instance to move data from one
614 database to an other. 614 database to an other.
615 615
616\layout Standard 616\layout Standard
617 617
618If the developer wants to select a special database type for sure, he has 618If the developer wants to select a special database type for sure without
619 to use the oparation 619 unnecessary side effects, he has to use the oparation
620\emph on 620\emph on
621create() 621create()
622\emph default 622\emph default
623 which has the following parameters: 623 which has the following parameters:
624\layout LyX-Code 624\layout LyX-Code
625 625
626T * create (OPimGlobal::PimType type, OPimGlobal::DatabaseStyle dbStyle, 626T * create (OPimGlobal::PimType type, OPimGlobal::DatabaseStyle dbStyle,
627 const QString &appName, const QString &fileName=QString::null) 627 const QString &appName, const QString &fileName=QString::null)
628\layout Standard 628\layout Standard
629 629
630Some paramters are already known, like type and appName (see section 630Some paramters 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}
@@ -750,25 +750,25 @@ In most cases it is not sufficient to receive just a list of all information
750 searching and sorting in an incremental manner 750 searching and sorting in an incremental manner
751\begin_inset Foot 751\begin_inset Foot
752collapsed true 752collapsed true
753 753
754\layout Standard 754\layout Standard
755 755
756FIXME: matchRegexp() does take a list of uid's. 756FIXME: matchRegexp() does take a list of uid's.
757 Therefore it is currently not possible to use it in an incremental manner! 757 Therefore it is currently not possible to use it in an incremental manner!
758 (se) 758 (se)
759\end_inset 759\end_inset
760 760
761. 761.
762 Therfore it is possible to research a 762 Therefore it is possible to research a
763\begin_inset Quotes gld 763\begin_inset Quotes gld
764\end_inset 764\end_inset
765 765
766List 766List
767\begin_inset Quotes grd 767\begin_inset Quotes grd
768\end_inset 768\end_inset
769 769
770 which was returned by a previous search query and to sort it afterwards. 770 which was returned by a previous search query and to sort it afterwards.
771 Before we will take a close look into sorting, we will start with searching. 771 Before we will take a close look into sorting, we will start with searching.
772 There exist two different ways of searching: 772 There exist two different ways of searching:
773\layout Enumerate 773\layout Enumerate
774 774
@@ -909,50 +909,59 @@ Eilers
909 909
910searchQuery.setHomeZip( 910searchQuery.setHomeZip(
911\begin_inset Quotes gld 911\begin_inset Quotes gld
912\end_inset 912\end_inset
913 913
9143* 9143*
915\begin_inset Quotes grd 915\begin_inset Quotes grd
916\end_inset 916\end_inset
917 917
918 ); 918 );
919\layout Standard 919\layout Standard
920 920
921We use a usual 921We use an usual
922\begin_inset Quotes gld 922\begin_inset Quotes gld
923\end_inset 923\end_inset
924 924
925OPimContact 925OPimContact
926\begin_inset Quotes grd 926\begin_inset Quotes grd
927\end_inset 927\end_inset
928 928
929 and fill into two fields the search information. 929 and fill into two fields the query information.
930 All filled fields are taken for the search operation (using an
931\begin_inset Quotes gld
932\end_inset
933
934AND
935\begin_inset Quotes grd
936\end_inset
937
938 operation), the unused ones are simply ignored.
930 As we just want to search for entries which zip number starts with a 939 As we just want to search for entries which zip number starts with a
931\begin_inset Quotes gld 940\begin_inset Quotes gld
932\end_inset 941\end_inset
933 942
9343 9433
935\begin_inset Quotes grd 944\begin_inset Quotes grd
936\end_inset 945\end_inset
937 946
938 we use the Wildcard 947 we use the Wildcard
939\begin_inset Quotes gld 948\begin_inset Quotes gld
940\end_inset 949\end_inset
941 950
942* 951*
943\begin_inset Quotes grd 952\begin_inset Quotes grd
944\end_inset 953\end_inset
945 954
946 as we would do for finding files in a filesystem. 955 as we would do to find files in a filesystem.
947\layout Standard 956\layout Standard
948 957
949The next step is to put this query into the operation which is defined like 958The next step is to put this query into the operation which is defined like
950 this: 959 this:
951\layout LyX-Code 960\layout LyX-Code
952 961
953List queryByExample (const T& query, int querySettings, const QDateTime 962List queryByExample (const T& query, int querySettings, const QDateTime
954 &startperiod=QDateTime()) 963 &startperiod=QDateTime())
955\layout Standard 964\layout Standard
956 965
957The first parameter 966The first parameter
958\begin_inset Quotes gld 967\begin_inset Quotes gld
@@ -1010,25 +1019,25 @@ eilers
1010\begin_inset Quotes grd 1019\begin_inset Quotes grd
1011\end_inset 1020\end_inset
1012 1021
1013, 1022,
1014\begin_inset Quotes gld 1023\begin_inset Quotes gld
1015\end_inset 1024\end_inset
1016 1025
1017eIlers 1026eIlers
1018\begin_inset Quotes grd 1027\begin_inset Quotes grd
1019\end_inset 1028\end_inset
1020 1029
1021, ...). 1030, ...).
1022 Thus we have to use the 1031 Thus, we have to use the
1023\begin_inset Quotes gld 1032\begin_inset Quotes gld
1024\end_inset 1033\end_inset
1025 1034
1026IgnoreCase 1035IgnoreCase
1027\begin_inset Quotes grd 1036\begin_inset Quotes grd
1028\end_inset 1037\end_inset
1029 1038
1030 setting which is to combine with the other using an 1039 setting which is to combine with the other using an
1031\begin_inset Quotes gld 1040\begin_inset Quotes gld
1032\end_inset 1041\end_inset
1033 1042
1034or 1043or
@@ -1048,25 +1057,25 @@ endperiod
1048\layout LyX-Code 1057\layout LyX-Code
1049 1058
1050use namespace Opie; 1059use namespace Opie;
1051\layout LyX-Code 1060\layout LyX-Code
1052 1061
1053[...] 1062[...]
1054\layout LyX-Code 1063\layout LyX-Code
1055 1064
1056List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase:: 1065List found_items = queryByExample( searchQuery, OPimBase::WildCards | OpimBase::
1057IgnoreCase ); 1066IgnoreCase );
1058\layout Standard 1067\layout Standard
1059 1068
1060This operation may return a list of entries which can be accesses as usual, 1069This operation may return a list of entries which can be accessed as above,
1061 using the 1070 using the
1062\begin_inset Quotes gld 1071\begin_inset Quotes gld
1063\end_inset 1072\end_inset
1064 1073
1065find() 1074find()
1066\begin_inset Quotes grd 1075\begin_inset Quotes grd
1067\end_inset 1076\end_inset
1068 1077
1069 operation. 1078 operation.
1070\layout Standard 1079\layout Standard
1071 1080
1072It should be clear at this stage, that this query is very powerful and - 1081It should be clear at this stage, that this query is very powerful and -
@@ -1164,24 +1173,213 @@ OPimBase::DateDiff
1164\begin_inset Quotes grd 1173\begin_inset Quotes grd
1165\end_inset 1174\end_inset
1166 1175
1167. 1176.
1168 The date and time in the query object is used as the 1177 The date and time in the query object is used as the
1169\series bold 1178\series bold
1170end 1179end
1171\series default 1180\series default
1172 of the interval. 1181 of the interval.
1173 The start will be defined by the last parameter (if nothing is set, the 1182 The start will be defined by the last parameter (if nothing is set, the
1174 current date will be taken!). 1183 current date will be taken!).
1175 Therefore, it is possible to set a time frame for all searched entries. 1184 Therefore, it is possible to set a time frame for all searched entries.
1185\layout Standard
1186
1187If you want to do incremental search operations, you may use the special
1188
1189\begin_inset Quotes gld
1190\end_inset
1191
1192queryByExample()
1193\begin_inset Quotes grd
1194\end_inset
1195
1196 which takes a
1197\begin_inset Quotes gld
1198\end_inset
1199
1200List
1201\begin_inset Quotes grd
1202\end_inset
1203
1204 as the first parameter.
1205 The search operation will just occure on this set of uid's!
1206\layout Subsection
1207
1208Sorting
1209\layout Standard
1210
1211To sort a given dataset, you should use the following operation (or one
1212 of the others which behave slightly differently):
1213\layout LyX-Code
1214
1215List sorted (const List& list, bool ascending, int sortOrder, int sortFilter,
1216 const QArray< UID >& cats);
1217\layout Standard
1218
1219This sort operation takes a list of uid's as returned for instance from
1220 a search query.
1221 The parameter
1222\begin_inset Quotes gld
1223\end_inset
1224
1225ascending
1226\begin_inset Quotes grd
1227\end_inset
1228
1229 defines whether the sort should be in an ascending order or not.
1230
1231\begin_inset Quotes gld
1232\end_inset
1233
1234sortOrder
1235\begin_inset Quotes grd
1236\end_inset
1237
1238 is defined by the enumerations
1239\begin_inset Quotes gld
1240\end_inset
1241
1242SortOrder
1243\begin_inset Quotes grd
1244\end_inset
1245
1246 and
1247\begin_inset Quotes gld
1248\end_inset
1249
1250SortOrderBase
1251\begin_inset Quotes grd
1252\end_inset
1253
1254 and defines which field should be used to sort (see for
1255\series bold
1256OPimContactAccess
1257\series default
1258:
1259\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimContactAccess.html}
1260
1261\end_inset
1262
1263, for
1264\series bold
1265ODateBookAccess
1266\series default
1267:
1268\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1ODateBookAccess.html}
1269
1270\end_inset
1271
1272 and for
1273\series bold
1274OPimTodoAccess
1275\series default
1276:
1277\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/classOpie_1_1OPimTodoAccess.html}
1278
1279\end_inset
1280
1281 and for common settings
1282\begin_inset LatexCommand \url{http://www.sra.uni-hannover.de/~eilers/apidocs/pim2/html/structOpie_1_1OPimBase.html#w21}
1283
1284\end_inset
1285
1286).
1287\layout Standard
1288
1289The
1290\begin_inset Quotes gld
1291\end_inset
1292
1293sortFilter
1294\begin_inset Quotes grd
1295\end_inset
1296
1297 parameter allows to remove some entries which are not interesting for the
1298 result and is defined in the same classes as
1299\begin_inset Quotes gld
1300\end_inset
1301
1302sortOrder
1303\begin_inset Quotes grd
1304\end_inset
1305
1306 by the enumeration
1307\begin_inset Quotes gld
1308\end_inset
1309
1310SortFilter
1311\begin_inset Quotes grd
1312\end_inset
1313
1314 and
1315\begin_inset Quotes gld
1316\end_inset
1317
1318SortFilterBase
1319\begin_inset Quotes grd
1320\end_inset
1321
1322.
1323 The list of id's in
1324\begin_inset Quotes gld
1325\end_inset
1326
1327cats
1328\begin_inset Quotes grd
1329\end_inset
1330
1331 allows to remain just these entries which are included in the list of categorie
1332s.
1333\layout Standard
1334
1335The returned list contains the same uid's as given via
1336\begin_inset Quotes gld
1337\end_inset
1338
1339list
1340\begin_inset Quotes grd
1341\end_inset
1342
1343 (or a subset of it, as the sortFilter and category list removes some entries)
1344 with a modified order as
1345\begin_inset Quotes gld
1346\end_inset
1347
1348sortOrder
1349\begin_inset Quotes grd
1350\end_inset
1351
1352 and
1353\begin_inset Quotes gld
1354\end_inset
1355
1356ascending
1357\begin_inset Quotes grd
1358\end_inset
1359
1360 dictates.
1361\layout Standard
1362
1363Therefore
1364\begin_inset Quotes gld
1365\end_inset
1366
1367sorted()
1368\begin_inset Quotes grd
1369\end_inset
1370
1371 is more a combination of search and sort, as just a sort command.
1372 But this combination is exactly what the developer needs in most situations.
1373
1176\layout Section 1374\layout Section
1177 1375
1178Generic Access: OPimBase and OPimRecord 1376Generic Access: OPimBase and OPimRecord
1179\begin_inset LatexCommand \label{sec:Generic-Access:-OPimBase} 1377\begin_inset LatexCommand \label{sec:Generic-Access:-OPimBase}
1180 1378
1181\end_inset 1379\end_inset
1182 1380
1183 1381
1184\layout Section 1382\layout Section
1185 1383
1186Caching 1384Caching
1187\layout Standard 1385\layout Standard