This file is indexed.

/usr/include/synthesis/sync_dbapi.h is in libsynthesis-dev 3.4.0.47.5+syncevolution-1.5.2-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   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
/*
 *  File:    sync_dbapi.h
 *
 *  Author:  Beat Forster (bfo@synthesis.ch)
 *
 *  C/C++    Programming interface between the
 *           Synthesis SyncML engine and
 *           the database layer for plug-ins
 *
 *  Copyright (c) 2005-2011 by Synthesis AG + plan44.ch
 *
 */

/*
 * This is the calling interface between the Synthesis SyncML engine
 * and a customized module "sync_dbapi".
 * The same interface can be used either for Standard C or for C++.
 * And there is a equivalent interface for JNI (Java Native Interface).
 * Normally the customized module will be compiled as DLL and will
 * be called by the SyncML engine. A linkable library is available
 * (for C++) as well.
 *
 * For more detailed information about the DBApi interface
 * please consult the SDK_manual.pdf which contains a tutorial,
 * detailed descriptions and some example code.
 *
 * The flow for accessing the datastores is always the same:
 * The SyncML engine will call these routines step by step
 *
 *  DATASTORE ACCESS FLOW
 *  =====================
 *
 *   1)  CreateContext
 *   2) [ContextSupport]   (optional)
 *   3) [FilterSupport]    (optional)
 *   4) [Read Admin Data]  (optional)
 *
 *   5)  StartDataRead
 *   6)  do ReadNextItem while (aStatus!=ReadNextItem_EOF);
 *   7)  any number of random calls to:
 *         -  ReadItem
 *         -  ReadBlob
 *         - [AdaptItem]   (optional)
 *   8)  EndDataRead
 *
 *   9)  StartDataWrite
 *  10)  any number of random calls to:
 *         -  InsertItem
 *         -  UpdateItem
 *         -  DeleteItem
 *         -  DeleteSyncSet
 *         -  ReadItem
 *         -  WriteBlob
 *         -  ReadBlob
 *         -  DeleteBlob
 *         - [AdaptItem]      (optional)
 *         -  FinalizeLocalID (at the end)
 *  11)  EndDataWrite
 *
 *  12) [Write Admin Data] (optional)
 *  13)  DeleteContext
 *
 *
 *  NOTE: 'DisposeObj' calls can occur anywhere between any statement
 *        of the flow above (but not before 'CreateContext' and not after
 *        'DeleteContext'). The SyncML engine is responsible for
 *        disposing all <aItemData> and <aItemID> objects after use.
 *
 *  NOTE: Returned errors (value > 0) will influence the flow
 *        Error at 1)      will not call any further step.
 *          "   "  2)..3)  these functions do not return errors
 *          "   "  5)..10) will cause an 'EndDataWrite' call with
 *                         <success> = false, then 'DeleteContext'.
 *          "   "  4)
 *                11)..12) 'DeleteContext' will be called afterwards.
 *
 *  The module must be able to handle several contexts in parallel.
 *  All routines will have an <aContext> parameter (assigned by
 *  'CreateContext'), which allows to identify the correct context.
 *  Routines can be called from different threads, but they are
 *  always sequential for each context. If the thread changes,
 *  'ThreadMayChangeNow' will notify the module about this issue.
 *  This routine can left empty and ignored, if not used.
 *
 *  NOTE: As the SyncML engine calls the plug-in multithreaded,
 *        all global structure accesses must be thread save.
 */


#ifndef SYNC_DBAPI_H
#define SYNC_DBAPI_H

/* Global declarations */
#include "synthesis/sync_dbapidef.h"


#if defined __cplusplus
  /* combine the definitions of different namespaces */
  using sysync::sInt32;
  using sysync::uInt32;
  using sysync::CContext;
  using sysync::CVersion;
  using sysync::TSyError;
  using sysync::ItemID;
  using sysync::MapID;
  using sysync::cItemID;
  using sysync::cMapID;
  using sysync::appCharP;
  using sysync::cAppCharP;
  using sysync::appPointer;
  using sysync::memSize;
  using sysync::KeyH;
  using sysync::SDK_Interface_Struct;
  using sysync::DB_Callback;
  using sysync::UI_Call_In;
#endif


/* C/C++ and DLL/library support
 * SYSYNC_ENGINE     : true ( within the engine itself )         / false ( outside )
 * SYSYNC_ENGINE_TEST: true ( within a test engine module )      / false ( outside )
 * DBAPI_LINKED      : true ( at standalone APP, e.g. "helloX" ) / false ( within engine/within DLL )
 * PLUGIN_INFO       : true ( within "plugin_info" program )     / false ( everywhere else )
 */
#if !defined SYSYNC_ENGINE && !defined SYSYNC_ENGINE_TEST && !defined DBAPI_LINKED && !defined PLUGIN_INFO && !defined DLL_EXPORT
  #define DLL_EXPORT 1
#endif

#undef    _ENTRY_ /* could be defined already here */
#ifdef DLL_EXPORT
  #define _ENTRY_ ENGINE_ENTRY
#else
  #define _ENTRY_
#endif


/* -- MODULE -------------------------------------------------------------------- */
/*! Create a module context \<mContext>
 *  This routine will be called as the 2nd call, when the module will be connected.
 *  (The 1st call is a 'Module_Version( 0 )' call outside any context).
 *
 *  It will be called not only once, but once for each session and datastore context,
 *  as defined at the XML config file. This routine can return error 20028 (LOCERR_ALREADY),
 *  if already created. This will be treated not as an error. For this case, it must
 *  return the same \<mContext> as for the former call(s).
 *
 *  NOTE: The module context can exist once and can be shared for all plug-in accesses.
 *        This can either be done with an allocated global variable at the plug-in or
 *        even better using the "GlobContext" structure provided by the SyncML engine.
 *        Please note, that write access to such a common module context structure must
 *        be thread-safe, when accessed from the session or datastore context.
 *        All the 'Module_CreateContext' calls for this module will be called
 *        sequentially by one thread. The plug-in programmer is responsible not to
 *        re-initialize the context for subsequent calls.
 *
 * If the module name at the XML config file is defined as "aaa!bbb!ccc" it will be passed
 * as "aaa" to \<moduleName> and "bbb!ccc" to \<subName>. This mechanism can be used to
 * cascade plug-in modules, where the next module gets "bbb" as \<moduleName> and "ccc" as
 * \<subName>. The JNI plug-in for Java is using this structure to address the JNI plug-in
 * and its assigned Java class. Error 20034 (LOCERR_UNKSUBSYSTEM) should be returned in case
 * the subsystem does not exist, no error if no subsystem has been chosen at all.
 *
 *
 *  @param  <mContext>     Returns a value, which allows to identify this module context.
 *                         Allowed values: Anything except 0, which is reserved for no context.
 *  @param  <moduleName>   Name of this plug-in
 *  @param  <subName>      Name of sub module (if available)
 *  @param  <mContextName> Name of the (datastore) context, e.g. "contacts";
 *                         this string is empty for calll concerning the session.
 *  @param  <mCB>          DB_Callback structure for module logging
 *
 *  @return  error code     if context could not be created       (e.g. not enough memory)
 *           LOCERR_ALREADY if global module context already exists (not treated as error)
 *           0              if context successfully created.
 */
_ENTRY_ TSyError Module_CreateContext( CContext *mContext, cAppCharP   moduleName,
                                                           cAppCharP      subName,
                                                           cAppCharP mContextName,
                                                         DB_Callback mCB );



/*! Get the module's version.
 *
 *  NOTE: The SyncML will take decisions depending on this version number, so
 *  the plug-in developer should not change the values at the delivered sample code.
 *  Plugin_Version( short buildNumber ) of 'SDK_util' should be used.
 *  The \<buildNumber> can be defined by the user.
 *
 *  NOTE: This function can be called by the engine outside any context with
 *  \<mContext> = 0. For this case, any callback is not permitted (as no DB_Callback
 *  is available).
 *
 *  @param  <mContext>      The module context ( 0, if none ).
 *  @return current version as SDK_VERSION_MAJOR | SDK_VERSION_MINOR)
 *                           | SDK_SUBVERSION    | buildNumber
 */
_ENTRY_ CVersion Module_Version( CContext mContext );



/*! Get the module's capabilities
 *  Currently the SyncML engine currently understands and supports:
 *   - "plugin_sessionauth"
 *   - "plugin_deviceadmin"
 *   - "plugin_datastoreadmin"
 *   - "plugin_datastore"
 *
 *  If one of these identifiers will be defined as "no" ( e.g. "plugin_sessionauth:no" ),
 *  the according routines will not be connected and used.
 *
 *  NOTE: The \<mCapabilities> can be allocated with "StrAlloc" (SDK_util.h) for C/C++
 *
 *  @param  <mContext>      The module context.
 *  @param  <mCapabilities> Returns the module's capabilities as multiline
 *                          aa:bb\<CRLF>cc:dd[\<CRLF>]
 *  @return  error code
 */
_ENTRY_ TSyError Module_Capabilities( CContext mContext, appCharP *mCapabilities );



/*! The module's config params will be sent to the plug-in.
 *  It can be used for access path definitions or other things.
 *  The \<plugin_params> can be defined individually for each session and datastore.
 *  The SyncML engine checks the syntax, but not the content.
 *  This routine should return an error 20010 (LOCERR_CFGPARSE), if one of
 *  these parameters is not supported.
 *
 *  EXAMPLE: Definition at XML config file:\n
 *             \<plugin_params>\n
 *               \<datapath>/var/log/sysync\</datapath>\n
 *               \<ultimate_answer>42\</ultimate_answer>\n
 *             \</plugin_params>
 *
 *           will be passed as:\n
 *             "datapath:/var/log/sysync\n
 *              ultimate_answer:42"
 *
 *  NOTE: Module_PluginParams will be called ALWAYS for each module context,
 *        even if no plug-in parameter is defined. This allows to react consistently
 *        on parameters, which are not always available.
 *
 *  @param  <mContext>      The module context.
 *  @param  <mConfigParams> The plugin params as multiline aa:bb\<CRLF>cc:dd[\<CRLF>]
 *  @param  <engineVersion> The SyncML engine's version
 *  @return  error code
 */
_ENTRY_ TSyError Module_PluginParams( CContext mContext, cAppCharP mConfigParams,
                                                          CVersion engineVersion );



/*! Disposes memory, which has been allocated within the module context.
 *  (At the moment this is only the capabilities string).
 *  'Module_DisposeObj' can occur at any time within \<mContext>.
 *
 *  NOTE: - If \<mCapabilities> has been allocated with "StrAlloc", use "Str_Dispose"
 *          (SDK_util.h) to release the memory again.
 *        - If it is defined as const within the plugin module (the module
 *          itself knows about !), this routine can be implemented empty.
 *
 *  @param  <mContext>  The module context.
 *  @param  <memory>    Dispose allocated memory.
 *  @return  -
 */
_ENTRY_ void Module_DisposeObj( CContext mContext, void* memory );



/*! This routine will be called as the last call, before this module is disconnected.
 *  The SyncML engine will call 'Module_DisposeObj' (if required) before this call
 *
 *  NOTE: This routine will be called ONLY, if the server stops in a controlled way.
 *        Its good programming practice not to wait for this 'DeleteContext' call.
 *
 *  @param  <mContext>  The module context.
 *  @return  error code
 */
_ENTRY_ TSyError Module_DeleteContext( CContext mContext );




/* -- SESSION ------------------------------------------------------------------- */
/*! By default the session context will be handled by the ODBC interface.
 *  The session context of this plug-in module will be used only,
 *  if \<server type="plugin"> and \<plugin_module> is defined
 *  ( \<plugin_module>name_of_the_plugin\</plugin_module> ).
 *  \<plugin_params> can be defined individually.
 *
 *  @param  <sContext>    Returns a value, which allows to identify this session context.
 *  @param  <sessionName> Name of this session
 *  @param  <sCB>         DB_Callback structure for session logging
 *
 *  @result  error code, if context could not be created (e.g. not enough memory)
 *           0           if context successfully created,
 *
 *  Flags (at the XML config file):
 *  - \<plugin_deviceadmin>yes\</plugin_deviceadmin>: "Session_CheckDevice", "Session_GetNonce"
 *                                                    "Session_SaveNonce" and
 *                                                    "Session_SaveDeviceInfo" will be used.
 *
 *  - \<plugin_sessionauth>yes\</plugin_sessionauth>: "Session_PasswordMode",
 *                                                    "Session_Login" and "Session_Logout" will be used.
 */
_ENTRY_ TSyError Session_CreateContext( CContext *sContext, cAppCharP sessionName,
                                                          DB_Callback sCB );



/*! This function adapts itemData
 *
 *  @param  <sContext>    The session context
 *  @param  <sItemData1>  The 1st item's data
 *  @param  <sItemData2>  The 2nd item's data
 *  @param  <sLocalVars>  The local vars
 *  @param  <sIdentifier> To identify, where it is called
 *
 *  @return  error code
 *
 *  NOTE:   The memory for adapted strings must be allocated locally.
 *          The SyncML engine will call 'DisposeObj' later, to release again its memory.
 *          One or more strings can be returned unchanged as well.
 */
_ENTRY_ TSyError Session_AdaptItem( CContext sContext, appCharP *sItemData1,
                                                       appCharP *sItemData2,
                                                       appCharP *sLocalVars,
                                                         uInt32  sIdentifier );


/*! Check the database entry of \<aDeviceID> and return its \<nonce> string.
 *  If \<aDeviceID> is not yet available at the plug-in, return "" for \<nonce>
 *
 *  @param  <sContext>   The session context
 *  @param  <aDeviceID>  The assigned device ID string
 *  @param  <sDevKey>    The device key string (will be used for datastore accesses later)
 *  @param  <nonce>      The nonce string of the last session
 *                       If \<aDeviceID> is not yet available, return "" for \<nonce>
 *                       and error code 0.
 *
 *  @result  error code 403 (Forbidden), if plugin_deviceadmin is not supported;
 *                        0, if successful
 *
 *  USED ONLY WITH \<plugin_deviceadmin>
 */
_ENTRY_ TSyError Session_CheckDevice( CContext sContext, cAppCharP  aDeviceID,
                                                          appCharP *sDevKey,
                                                          appCharP *nonce );


/*! Get a new nonce from the database. If this routine returns an error,
 *  the SyncML engine will create its own nonce.
 *
 *  @param  <sContext>   The session context
 *  @param  <nonce>      A valid new nonce value (for the assigned device ID).
 *
 *  @return  error code 404 (NotFound), if no \<nonce> has been generated;
 *                       0, if a valid \<nonce> has been generated
 *
 *  USED ONLY WITH \<plugin_deviceadmin>
 */
_ENTRY_ TSyError Session_GetNonce( CContext sContext, appCharP *nonce );



/*! Save the new nonce (which will be expected to be returned in the
 *  next session for this device ID.
 *
 *  @param  <sContext>   The session context
 *  @param  <nonce>      New \<nonce> for the next session (of the assigned device ID)
 *
 *  @result  error code 403 (Forbidden), if plugin_deviceadmin is not supported;
 *                        0,             if successful
 *
 *  USED ONLY WITH \<plugin_deviceadmin>
 */
_ENTRY_ TSyError Session_SaveNonce( CContext sContext, cAppCharP nonce );



/*! Save the device info for \<sContext>
 *
 *  @param  <sContext>     The session context
 *  @param  <aDeviceInfo>  More information about the assigned device (for DB and logging)
 *
 *  @result  error code 403 (Forbidden), if plugin_deviceadmin is not supported;
 *                        0,             if successful
 *
 *  USED ONLY WITH \<plugin_deviceadmin>
 */
_ENTRY_ TSyError Session_SaveDeviceInfo( CContext sContext, cAppCharP aDeviceInfo );



/*! Get the current DB time of \<sContext>
 *
 *  @param  <sContext>       The session context
 *  @param  <currentDBTime>  The current time of the plugin's DB (as ISO8601 format).
 *
 *  @result  error code 403 (Forbidden), if plugin_deviceadmin is not supported;
 *                      404 (NotFound),  if not available -> the engine creates its own time
 *                        0,             if successful
 */
_ENTRY_ TSyError Session_GetDBTime( CContext sContext, appCharP *currentDBTime );



/*--------------------------------------------------------------------------------*/
/*! Get the password mode.
 *  There are currently 4 different password modes supported.
 *
 *  @param <sContext>          The session context
 *
 *  @result
 *    - Password_ClrText_IN  : 'SessionLogin' will get    clear text password
 *    - Password_ClrText_OUT :        "       must return clear text password
 *    - Password_MD5_OUT     :        "       must return MD5 coded  password
 *    - Password_MD5_Nonce_IN:        "       will get    MD5B64(MD5B64(user:pwd):nonce)
 *
 *  USED ONLY WITH \<plugin_sessionauth>
 */
_ENTRY_ sInt32 Session_PasswordMode( CContext sContext );


/*! Get \<sUsrKey> of \<sUsername>,\<sPassword> in the session context.
 *
 *  @param  <sContext>   The session context
 *  @param  <sUsername>  The user name ...
 *  @param  <sPassword>  ... and the password. \<sPassword> is an input parameter
                         for 'Password_ClrTxt_IN' mode and an output parameter for
 *                       'Password_ClrText_OUT' and 'Password_MD5_OUT' modes.
 *  @param  <sUsrKey>    Returns the internal reference key, which will be passed to
 *                       to the datastore contexts later.
 *
 *  @result  error code 403 (Forbidden), if plugin_sessionauth is not supported;
 *                        0, if successful
 *
 *  USED ONLY WITH \<plugin_sessionauth>
 */
_ENTRY_ TSyError Session_Login( CContext sContext, cAppCharP  sUsername,
                                                    appCharP *sPassword,
                                                    appCharP *sUsrKey );


/*! Logout for this session context
 *
 *  @param  <sContext>  The session context
 *
 *  @result  error code 403 (Forbidden), if plugin_sessionauth is not supported;
 *                        0, if successful
 *
 *  USED ONLY WITH \<plugin_sessionauth>
 */
_ENTRY_ TSyError Session_Logout( CContext sContext );



/*! Disposes memory, which has been allocated within the session context.
 *  'Session_DisposeObj' can occur at any time within \<sContext>.
 *
 *  @param  <sContext>  The session context.
 *  @param  <memory>    Dispose allocated memory.
 *
 *  @return  -
 */
_ENTRY_ void Session_DisposeObj( CContext sContext, void* memory );



/*! Due to the architecture of the SyncML engine, the system may run in a multithread
 *  environment. The consequence is that each routine of this plugin module can be
 *  called by a different thread. Normally this is not a problem, nevertheless
 *  this routine notifies about thread changes in \<sContext>.
 *  It can be ignored ( =implemented empty), if not really needed.
 *
 *  @param  <sContext>      The session context
 *  @return  -
 */
_ENTRY_ void Session_ThreadMayChangeNow( CContext sContext );



/*! Writes the context of all items to dbg output path
 *  This routine is implemented for debug purposes only and will NOT BE CALLED by the
 *  SyncML engine. Can be implemented empty
 *
 *  @param  <sContext>      The session context
 *  @param  <allFields>     true : all fields, also empty ones, will be displayed;
 *                          false: only fields <> "" will be shown
 *  @param  <specificItem>  ""   : all items will be shown;
 *                          else   shows the \<specificItem>
 *
 *  @return  -
 */
_ENTRY_ void Session_DispItems( CContext sContext, bool allFields, cAppCharP specificItem );



/*! Delete a session context.
 *  No access to \<sContext> will be done after this call
 *
 *  @param  <sContext>  The session context
 *  @return  error code, if context could not be deleted.
 */
_ENTRY_ TSyError Session_DeleteContext( CContext sContext );




/* -- OPEN ---------------------------------------------------------------------- */
/*! This routine is called to create a new context for a datastore access.
 *  It must allocate all resources for this context and initialize the \<aContext>
 *  parameter with a value that allows re-identifying the context.
 *  \<aContext> can either be a pointer to the local context structure or any key
 *  value which allows to re-identify the context later.
 *  Subsequent calls related to this context will pass the \<aContext> value as returned
 *  from CreateContext. The context must be valid until 'DeleteContext' is called.
 *  \<plugin_params> can be defined individually.
 *
 *  NOTE:   The SyncML engine treats \<aContext> simply as a key. The only condition
 *          is uniqueness for all datastore contexts. Even \<aContext> = 0 can be used.
 *
 *  @param  <aContext>     Returns a value, which allows to identify this datastore context.
 *  @param  <aContextName> Allows to identify the context, if more than one must be
 *                         handled. \<contextName> is defined at the XML configuration.
 *  @param  <aCB>          DB_Callback structure for datatstore logging.
 *  @param  <sDevKey>      The result of 'Session_CheckDevice' comes in here.
 *  @param  <sUsrKey>      The result of 'Session_Login'       comes in here.
 *
 *  @return  error code, if context could not be created (e.g. not enough memory),
 *           0           if context successfully created.
 */
_ENTRY_ TSyError CreateContext( CContext *aContext, cAppCharP aContextName, DB_Callback aCB,
                                                    cAppCharP sDevKey,
                                                    cAppCharP sUsrKey );


/*! This function asks for specific context configurations
 *
 *  @param  <aContext>      The datastore context
 *  @param  <aSupportRules> The SyncML sends a list of support rules.
 *                          This function has to reply, up to which rule,
 *                          contexts are supported (and switched on now).
 *                          Data is formatted as multiline aa:bb\<CRLF>cc:dd[\<CRLF>]
 *
 *  @return  Up to \<n> fields are supported (and switched on) for this context.
 *           If 0 will be returned, no field of \<aSupportRules> is supported.
 *
 */
_ENTRY_ uInt32 ContextSupport( CContext aContext, cAppCharP aSupportRules );



/*! This function asks for filter support.
 *
 *  @param  <aContext>      The datastore context
 *  @param  <aFilterRules>  The SyncML sends a list of filter rules.
 *                          This function has to reply, up to which rule,
 *                          filters are supported (and switched on now).
 *                          Data is formatted as multiline aa:bb\<CRLF>cc:dd[\<CRLF>]
 *
 *  @return  Up to \<n> filters are supported (and switched on) for this context
 *           If 0 will be returned, no field of \<aFilterRules> are supported.
 */
_ENTRY_ uInt32 FilterSupport( CContext aContext, cAppCharP aFilterRules );



/* -- GENERAL ------------------------------------------------------------------- */
/*! Due to the architecture of the SyncML engine, the system may run in a multithread
 *  environment. The consequence is that each routine of this API module can be
 *  called by a different thread. Normally this is not a problem, nevertheless
 *  this routine notifies about thread changes in \<aContext>.
 *  It can be ignored ( =implemented empty), if not really needed.
 *
 *  @param  <aContext>  The datastore context.
 *
 *  @result  -
 */
_ENTRY_ void ThreadMayChangeNow( CContext aContext );



/*! This functions writes \<logData> for this context
 *  Can be implemented empty, if not needed.
 *
 *  @param  <aContext>  The datastore context.
 *  @param  <logData>   Logging information, formatted as multiline aa:bb\<CRLF>cc:dd[\<CRLF>]
 *
 *  @result  -
 */
_ENTRY_ void WriteLogData( CContext aContext, cAppCharP logData );



/*! Writes the context of all items to dbg output path
 *  This routine is implemented for debug purposes only and will NOT BE CALLED by the
 *  SyncML engine. Can be implemented empty, if not needed.
 *
 *  @param  <aContext>      The datastore context.
 *  @param  <allFields>
 *                          - true : all fields, also empty ones, will be displayed;
 *                          - false: only fields <> "" will be shown
 *  @param  <specificItem>
 *                          - ""   : all items will be shown;
 *                          - else : shows the \<specificItem>
 *
 *  @return  -
 */
_ENTRY_ void DispItems( CContext aContext, bool allFields, cAppCharP specificItem );



/* -- ADMINISTRATION ------------------------------------------------------------ */
/* This section contains the 'admin read' and 'admin write' routines. */

/*! This function gets the stored information about the record with the four paramters:
 *  \<sDevKey>, \<sUsrKey>, \<aLocDB>, \<aRemDB>.
 *
 *  - \<plugin_deviceadmin>yes\</plugin_deviceadmin>: Admin/Map routines will be used.
 *
 *  @param  <aContext>   The datastore context
 *  @param  <aLocDB>     Name of the local  DB
 *  @param  <aRemDB>     Name of the remote DB
 *  @param  <adminData>  The data, saved with the last 'SaveAdminData' call
 *
 *  @return  error code 404 (NotFound), if record is not (yet) available,
 *                        0 (no error)  if admin data found
 *
 *  NOTE: \<sDevKey> and \<sUsrKey> have been passed with 'CreateContext' already.
 *        The plug-in module must have stored them within the datastore context.
 *
 *  USED ONLY WITH \<plugin_datastoredadmin>
 */
_ENTRY_ TSyError LoadAdminData     ( CContext aContext, cAppCharP aLocDB,
                                                        cAppCharP aRemDB, appCharP *adminData );

/*! This is the equivalent to 'LoadAdminData', but using a key instead of a data string */
_ENTRY_ TSyError LoadAdminDataAsKey( CContext aContext, cAppCharP aLocDB,
                                                        cAppCharP aRemDB,     KeyH  aItemKey );


/*! This functions stores the new \<adminData> for this context
 *
 *  @param  <aContext>   The datastore context
 *  @param  <adminData>  The new set of admin data to be stored, will be loaded again
 *                       with the next 'LoadAdminData' call.
 *
 *  @result  error code, if data could not be saved (e.g. not enough memory);
 *                       0 if successfully created.
 *
 *  USED ONLY WITH \<plugin_datastoredadmin>
 */
_ENTRY_ TSyError SaveAdminData     ( CContext aContext, cAppCharP adminData );

/*! This is the equivalent to 'SaveAdminData', but using a key instead of a data string */
_ENTRY_ TSyError SaveAdminDataAsKey( CContext aContext,      KeyH aItemKey );



/*! Map table handling: Get the next map item of this context.
 *  If \<aFirst> is true, the routine must start to return the first element
 *
 *  @param  <aContext>   The datastore context
 *  @param  <mID>        MapID ( with \<localID>,\<remoteID>, <flags> and \<ident> ).
 *  @param  <aFirst>     Starting with the first MapID. When creating a context,
 *                       the first call will get the first MapID, even if \<aFirst>
 *                       is false.
 *
 *  @return
 *          - true:  as long as there is a MapID available, which must be assigned to <mID>
 *          - false: if there is no more MapID. Nothing must be assigned to <mID>
 *
 *  USED ONLY WITH \<plugin_datastoredadmin>
 */
_ENTRY_ bool ReadNextMapItem( CContext aContext, MapID mID, bool aFirst );


/*! Map table handling: Insert a map item of this context
 *
 *  @param  <aContext>   The datastore context
 *  @param  <mID>        MapID ( with \<localID>,\<remoteID>, \<flags> and \<ident> ).
 *
 *  @return  error code, if this MapID can't be inserted, or if already existing
 *
 *  USED ONLY WITH \<plugin_datastoredadmin>
 */
_ENTRY_ TSyError InsertMapItem( CContext aContext, cMapID mID );


/*! Map table handling: Update a map item of this context
 *
 *  @param  <aContext>   The datastore context
 *  @param  <mID>        MapID ( with \<localID>,\<remoteID>, \<flags> and \<ident> ).
 *                       If there is already a MapID element with \<localID> and \<ident>,
 *                       it will be updated, else created.
 *
 *  @return  error code, if this MapID can't be updated (e.g. not yet existing).
 *
 *  USED ONLY WITH \<plugin_datastoredadmin>
 */
_ENTRY_ TSyError UpdateMapItem( CContext aContext, cMapID mID );


/*! Map table handling: Delete a map item of this context
 *
 *  @param  <aContext>   The datastore context
 *  @param  <mID>        MapID ( with \<localID>,\<remoteID>, \<flags> and \<ident> ).
 *
 *  @return  error code, if this MapID can't deleted,
 *                    or if this MapID does not exist.
 *
 *  USED ONLY WITH \<plugin_datastoredadmin>
 */
_ENTRY_ TSyError DeleteMapItem( CContext aContext, cMapID mID );




/* -- READ ---------------------------------------------------------------------- */
/*! This routine initializes reading from the database
 *  StartDataRead must prepare the database to return the objects of this context.
 *
 *  @param  <aContext>     The datastore context.
 *  @param  <lastToken>    The value which has been returned by this module
 *                         at the last "EndDataWrite" call will be given.
 *                         It will be "", when called the first time.
 *                         Normally this token is an ISO8601 formatted string
 *                         which represents the module's current time (at the
 *                         beginning of a session). It will be used to decide at
 *                         'ReadNextItem' whether a record has been changed.
 *  @param   <resumeToken> Token for Suspend/Resume mode.
 *
 *  @return  error code
 */
_ENTRY_ TSyError StartDataRead( CContext aContext, cAppCharP   lastToken,
                                                   cAppCharP resumeToken );



/*! This routine reads the next ItemID from the database.
 *  \<allfields>    of 'ContextSupport' ( "ReadNextItem:allfields" ) and
 *  \<aFilterRules> of 'FilterSupport' must be considered.
 *  If \<aFirst> is true, the routine must return the first element (again).
 *
 *  @param  <aContext>  The datastore context.
 *  @param  <aID>       The assigned ItemID in the database;
 *                      will be ignored by the SyncML engine, if \<aStatus> = 0
 *  @param  <aItemData> The data, formatted as multiline aa:bb\<CRLF>cc:dd[\<CRLF>];
 *                      will be ignored by the SyncML engine, if \<aStatus> = 0
 *  @param  <aStatus>
 *                      - ReadItem_EOF       ( =0 ) for none ( =eof ),
 *                      - ReadItem_Changed   ( =1 ) for a changed item,
 *                      - ReadItem_Unchanged ( =2 ) for unchanged item.
 *                      - ReadItem_Resumed   ( =3 ) for a changed item (since resumed)
 *  @param  <aFirst>
 *                      - true:  the routine must return the first element
 *                      - false: the routine must return the next  element
 *
 *  @return  error code, if not ok. No datasets found is a success as well !
 *
 *
 *  NOTE:   The memory for \<aID> and \<aItemData> must be allocated locally.
 *          The SyncML engine will call 'DisposeObj' later for these objects to
 *          release the memory again. It needn't to be allocated, if \<aStatus>
 *          is ReadItem_EOF.
 *
 *  NOTE:   By default, the SyncML engine asks for \<aID> only.
 *          \<aItemData> can be returned, if anyway available or
 *          \<aItemData> must be returned, if the engine asks for it
 *          (when calling "ReadNextItem:allfields" at 'ContextSupport' with \<allfields>).
 */
_ENTRY_ TSyError ReadNextItem     ( CContext aContext, ItemID aID, appCharP *aItemData,
                                     sInt32 *aStatus,    bool aFirst );

/*! This is the equivalent to 'ReadNextItem', but using a key instead of a data string */
_ENTRY_ TSyError ReadNextItemAsKey( CContext aContext, ItemID aID,     KeyH aItemKey,
                                     sInt32 *aStatus,    bool aFirst );



/*! This routine reads the contents of a specific ItemID \<aID> from the database.
 *
 *  @param  <aContext>  The datastore context.
 *  @param  <aID>       The assigned ItemID in the database
 *  @param  <aItemData> Returns the data, formatted as multiline aa:bb\<CRLF>cc:dd[\<CRLF>]
 *
 *  @return  error code, if not ok ( e.g. invalid \<aItemID> )
 *
 *
 *  NOTE:   The memory for \<aItemData> must be allocated locally.
 *          The SyncML engine will call 'DisposeObj' later for \<aItemData>,
 *          to release again its memory.
 */
_ENTRY_ TSyError ReadItem     ( CContext aContext, cItemID aID, appCharP *aItemData );

/*! This is the equivalent to 'ReadItem', but using a key instead of a data string */
_ENTRY_ TSyError ReadItemAsKey( CContext aContext, cItemID aID,     KeyH aItemKey );



/*! This routine reads the specific binary logic block \<aID>,\<aBlobID>
 *  from the database.
 *
 *  @param  <aContext>  The datastore context.
 *  @param  <aID>       ItemID ( with \<item>,\<parent> ).
 *  @param  <aBlobID>   The assigned ID of the blob.
 *
 *  @param  <aBlkPtr>   Position and size (in bytes) of the blob block.
 *  @param  <aBlkSize>
 *                      - Input:  Maximum size (in bytes) of the blob block to be read.
 *                                If \<blkSize> is 0, the result size is not limited.
 *                      - Output: Size (in bytes) of the blob block.
 *                                \<blkSize> must not be larger than its input value.
 *  @param  <aTotSize>  Total size of the blob (in bytes), can be also 0,
 *                      if not available, e.g. for a stream.
 *
 *  @param  <aFirst>    (Input)
 *                      - true : Engine asks for the first block of this blob.
 *                      - false: Engine asks for the next  block of this blob.
 *
 *  @param  <aLast>     (Output)
 *                      - true : This is the last part (or the whole) blob.
 *                      - false: More blocks will follow.
 *
 *  @return  error code, if not ok ( e.g. invalid \<aItemID>,\<aBlobID> )
 *
 *
 *  NOTE 1) The memory at \<blkPtr>,\<blkSize> must be allocated locally.
 *          The SyncML engine will call 'DisposeObj' later for \<blkPtr>,
 *          to release the memory.
 *
 *  NOTE 2) Empty blobs are allowed, \<blkSize> and \<totSize> must be set to 0,
 *          \<blkPtr> can be undefined, \<aLast> must be true.
 *          No 'DisposeObj' call is required for this case.
 *
 *  NOTE 3) The SyncML engine can change to read another blob before
 *          having read the whole blob. It will never resume reading of this
 *          incomplete blob, but start reading again with \<aFirst> = true.
 */
_ENTRY_ TSyError ReadBlob( CContext aContext, cItemID  aID,   cAppCharP  aBlobID,
                                           appPointer *aBlkPtr, memSize *aBlkSize,
                                                                memSize *aTotSize,
                                                 bool  aFirst,     bool *aLast );



/*! This routine terminates the read from database phase
 *  It can be used e.g. for termination of a transaction.
 *  In standard case it can be implemented empty, returning simply a value LOCERR_OK = 0.
 *
 *  @param  <aContext>   The datastore context.
 *  @return  error code
 */
_ENTRY_ TSyError EndDataRead( CContext aContext );




/* -- WRITE --------------------------------------------------------------------- */
/*! This routine initializes writing to the database
 *
 *  @param  <aContext>   The datastore context.
 *  @return  error code, if not ok (e.g. invalid select options)
 */
_ENTRY_ TSyError StartDataWrite( CContext aContext );



/*! This routine inserts a new dataset to the database. The assigned
 *  new ItemID \<aId> will be returned.
 *
 *  @param  <aContext>   The datastore context.
 *  @param  <aItemData>  The data, formatted as multiline aa:bb\<CRLF>cc:dd[\<CRLF>]
 *  @param  <aID>        Database key of the new dataset.
 *
 *  @return  error code
 *             - LOCERR_OK       (   =0 ), if successful
 *             - DB_DataMerged   ( =207 ), if successful, but item actually stored
 *                                                        was updated with data from
 *                                                        external source or another
 *                                                        sync set item. Engine will
 *                                                        request updated version
 *                                                        using ReadItem.
 *                                                        (server add case only)
 *             - DB_DataReplaced ( =208 ), if successful, but item added replaces
 *                                                        another item that already
 *                                                        existed in the sync set.
 *                                                        (server add case only)
 *             - DB_Conflict     ( =409 ), if database requests engine to merge
 *                                                        existing data with the
 *                                                        to-be stored data first.
 *             - DB_Forbidden    ( =403 ), if \<aItemData> can't be resolved
 *             - DB_Full         ( =420 ), if not enough space in the DB
 *             - ... or any other SyncML error code, see Reference Manual
 *
 *  NOTE:   The memory for \<aItemID> must be allocated locally.
 *          The SyncML engine will call 'DisposeObj' later for \<aItemID>,
 *          to release the memory
 *
 */
_ENTRY_ TSyError InsertItem     ( CContext aContext, cAppCharP aItemData, ItemID aID );

/*! This is the equivalent to 'InsertItem', but using a key instead of a data string */
_ENTRY_ TSyError InsertItemAsKey( CContext aContext,      KeyH aItemKey,  ItemID aID );



/*! This routine updates an existing dataset of the database
 *
 *  @param  <aContext>   The datastore context.
 *  @param  <aItemData>  The data, formatted as multiline aa:bb\<CRLF>cc:dd[\<CRLF>]
 *  @param  <aID>        Database key of dataset to be updated
 *  @param  <updID>
 *                       - Input:  NULL is assigned as default value to
 *                                 \<updID.item> and \<updID.parent>.
 *                       - Output: The updated database key for \<aID>.
 *                                 Can be NULL,  if the same as \<aID>
 *
 *  @return  error code
 *             - LOCERR_OK    (   =0 ), if successful
 *             - DB_Forbidden ( =403 ), if \<aItemData> can't be resolved
 *             - DB_NotFound  ( =404 ), if unknown  \<aID>
 *             - DB_Full      ( =420 ), if not enough space in the DB
 *             - ... or any other SyncML error code, see Reference Manual
 *
 *
 *  NOTE:   \<updID> must either contain NULL references ( if the same as \<aID> ),
 *          or the memory for \<updID.item>,\<updID.parent> must be allocated locally.
 *          The SyncML engine will call 'DisposeObj' later for \<updID.item> and
 *          \<updID.parent> to release the memory.
 *          \<updID.parent> can be NULL, if the hierarchical model is not supported.
 */
_ENTRY_ TSyError UpdateItem     ( CContext aContext, cAppCharP aItemData, cItemID   aID,
                                                                           ItemID updID );

/*! This is the equivalent to 'UpdateItem', but using a key instead of a data string */
_ENTRY_ TSyError UpdateItemAsKey( CContext aContext,      KeyH aItemKey,  cItemID   aID,
                                                                           ItemID updID );



/*! This routine moves \<aID.item> from \<aID.parent> to \<newParID>
 *
 *  @param  <aContext>  The datastore context.
 *  @param  <aID>       ItemID ( with \<item>,\<parent> ) to be moved.
 *  @param  <newParID>  New parent ID for \<aID>
 *
 *  @return  error code
 *             - LOCERR_OK    (   =0 ), if successful
 *             - DB_NotFound  ( =404 ), if unknown  \<newParID>
 *             - DB_Full      ( =420 ), if not enough space in the DB
 *             - ... or any other SyncML error code, see Reference Manual
 */
_ENTRY_ TSyError MoveItem( CContext aContext, cItemID aID, cAppCharP newParID );



/*! This routine deletes a dataset from the database
 *
 *  @param  <aContext>  The datastore context.
 *  @param  <aID>       ItemID ( with \<item>,\<parent> ) to be deleted.
 *
 *  @return  error code
 *             - LOCERR_OK    (   =0 ), if successful
 *             - DB_NotFound  ( =404 ), if unknown \<aItemID>
 *             - ... or any other SyncML error code, see Reference Manual
 */
_ENTRY_ TSyError DeleteItem( CContext aContext, cItemID aID );




/*! This routine updates a temporary <aID> to an <updID> at the end
 *  For cached systems which assign IDs at the end of a run.
 *
 *  @param  <aContext>   The datastore context.
 *  @param  <aID>        Database key of dataset to be updated
 *  @param  <updID>
 *                       - Input:  NULL is assigned as default value to
 *                                 \<updID.item> and \<updID.parent>.
 *                       - Output: The updated database key for \<aID>.
 *                                 Can be NULL,  if the same as \<aID>
 *
 *  @return  error code
 *             - LOCERR_OK     (     =0 ), if successful
 *             - DB_Forbidden  (   =403 ), if \<aItemData> can't be resolved
 *             - DB_NotFound   (   =404 ), if unknown \<aID>
 *             - LOCERR_NOTIMP ( =20030 ), if no finalizing is needed at all
 *             - ... or any other SyncML error code, see Reference Manual
 *
 *  NOTE:   \<updID> must either contain NULL references ( if the same as \<aID> ),
 *          or the memory for \<updID.item> must be allocated locally.
 *          The SyncML engine will call 'DisposeObj' later for \<updID.item>
 *          to release the memory. \<updID.parent>should be always NULL.
 */
_ENTRY_ TSyError FinalizeLocalID( CContext aContext, cItemID aID, ItemID updID );




/*! This routine deletes all datasets from the database
 *
 *  @param  <aContext>  The datastore context.
 *
 *  @return  error code
 *             - LOCERR_OK     (     =0 ), if successful
 *             - LOCERR_NOTIMP ( =20030 ). For this case, the engine removes all items directly
 *             - ... or any other SyncML error code, see Reference Manual
 */
_ENTRY_ TSyError DeleteSyncSet( CContext aContext );




/*! This routine writes the specific binary logic block \<blobID> to the database.
 *
 *  @param  <aContext>  The datastore context.
 *  @param  <aID>       ItemID ( with \<item>,\<parent> ).
 *  @param  <aBlobID>   The assigned ID of the blob.
 *
 *  @param  <aBlkPtr>
 *  @param  <aBlkSize>  Position and size (in bytes) of the blob block.
 *  @param  <aTotSize>  Total size of the blob (in bytes),
 *                      Can be also 0, if not available, e.g. for a stream.
 *
 *  @param  <aFirst>
 *                      - true : this is the first block of the blob.
 *                      - false: this is the next  block.
 *  @param  <aLast>
 *                      - true : this is the last  block.
 *                      - false: more blocks will follow.
 *
 *  @return  error code, if not ok ( e.g. invalid \<aID>,\<aBlobID> )
 *
 *  NOTE:   Empty blobs are possible, \<blkSize> and \<totSize> will be set to 0,
 *          \<blkPtr> will be NULL, \<aFirst> and \<aLast> will be true.
 */
_ENTRY_ TSyError WriteBlob( CContext aContext, cItemID aID,   cAppCharP aBlobID,
                                            appPointer aBlkPtr, memSize aBlkSize,
                                                                memSize aTotSize,
                                                  bool aFirst,     bool aLast );


/*! This routine deletes the specific binary logic block \<blobID> at the database.
 *
 *  @param  <aContext>  The datastore context.
 *  @param  <aID>       ItemID ( with \<item>,\<parent> ).
 *  @param  <aBlobID>   The assigned ID of the blob.
 *
 *  @return  error code, if not ok ( e.g. invalid \<aID>,\<aBlobID> )
 */
_ENTRY_ TSyError DeleteBlob( CContext aContext, cItemID aID, cAppCharP aBlobID );


/*! Advises the database to finsish the running transaction
 *
 *  @param  <aContext>   The datastore context.
 *  @param  <success>
 *                       - true:  All former actions were successful,
 *                                so the database can commit
 *                       - false: The transaction was not successful,
 *                                so the database may rollback or ignore the transaction.
 *
 *  @param  <newToken>   An internally generated string value, which
 *                       will be used to identify changed database records.
 *                       It is normally an ISO8601 formatted string, which
 *                       represents the module's current time (at the
 *                       time the 'StartDataRead' of this context has been
 *                       called). All changed records of the currrent context
 *                       must get this token as timestamp as as well.
 *                       The SyncML engine will return this value with the
 *                       'StartDataRead' call within the next session.
 *                       It must return NULL in case of no \<success>.
 *
 *  @return  error code, if operation can't be performed. No \<success> is not an error.
 *
 *
 *  NOTE: By default, the SyncML engine expects an ISO8601 string for \<newToken>.
 *        But the SyncML engine can be configured to treat this value completely
 *        opaque, if implemented in a different way.
 *
 *        The \<newToken> must be allocated locally and will be
 *        disposed with a 'DisposeObj' call later by the SyncML engine.
 */
_ENTRY_ TSyError EndDataWrite( CContext aContext, bool success, appCharP *newToken );



/* ---- ADAPT ITEM -------------------------------------------------------------- */
/*! This function adapts aItemData
 *
 *  @param  <aContext>      The datastore context
 *  @param  <aItemData1>    The 1st item's data
 *  @param  <aItemData2>    The 2nd item's data
 *  @param  <aLocalVars>    The local vars
 *  @param  <aIdentifier>   To identify, where it is called
 *
 *  @return  error code
 *
 *  NOTE:   The memory for adapted strings must be allocated locally.
 *          The SyncML engine will call 'DisposeObj' later, to release again its memory.
 *          One or more strings can be returned unchanged as well.
 */
_ENTRY_ TSyError AdaptItem( CContext aContext, appCharP *aItemData1,
                                               appCharP *aItemData2,
                                               appCharP *aLocalVars,
                                                 uInt32  aIdentifier );


/* -- DISPOSE / CLOSE ----------------------------------------------------------- */
/*! Disposes memory, which has been allocated within the datastore context.
 *  'DisposeObj' can occur at any time within \<aContext>.
 *
 *  @param  <aContext>  The datastore context.
 *  @param  <memory>    Dispose allocated memory.
 *
 *  @return  -
 *
 */
_ENTRY_ void DisposeObj( CContext aContext, void* memory );



/*! This routine is called to delete a context, that was previously created with
 *  'CreateContext'. The DB Module must free all resources related to this context.
 *  No calls with \<aContext> will be done after calling this routine, so the
 *  assigned structure, allocated at 'CreateContext' can be released here.
 *
 *  @param  <aContext>   The datastore context.
 *
 *  @result  error code, if context could not be deleted ( e.g. not existing \<aContext> ).
 */
_ENTRY_ TSyError DeleteContext( CContext aContext );


#endif
/* eof */