1 /*************************************************************************** 2 begin : Mon Mar 01 2004 3 copyright : (C) 2018 by Martin Preuss 4 email : martin@libchipcard.de 5 6 *************************************************************************** 7 * This file is part of the project "AqBanking". * 8 * Please see toplevel file COPYING of that project for license details. * 9 ***************************************************************************/ 10 11 /** @file provider_be.h 12 * @short This file is used by provider backends. 13 */ 14 15 16 #ifndef AQBANKING_PROVIDER_BE_H 17 #define AQBANKING_PROVIDER_BE_H 18 19 #include <aqbanking/backendsupport/provider.h> 20 #include <aqbanking/backendsupport/providerqueue.h> 21 #include <aqbanking/backendsupport/userqueue.h> 22 #include <aqbanking/backendsupport/user.h> 23 24 #include <gwenhywfar/plugin.h> 25 #include <gwenhywfar/db.h> 26 #include <gwenhywfar/dialog.h> 27 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 34 /** @addtogroup G_AB_PROVIDER 35 * 36 */ 37 /*@{*/ 38 39 40 #define AB_PROVIDER_FLAGS_HAS_NEWUSER_DIALOG 0x00000001 41 #define AB_PROVIDER_FLAGS_HAS_EDITUSER_DIALOG 0x00000002 42 #define AB_PROVIDER_FLAGS_HAS_NEWACCOUNT_DIALOG 0x00000004 43 #define AB_PROVIDER_FLAGS_HAS_EDITACCOUNT_DIALOG 0x00000008 44 #define AB_PROVIDER_FLAGS_HAS_USERTYPE_DIALOG 0x00000010 45 46 47 48 /** See @ref AB_Provider_Init. */ 49 typedef int (*AB_PROVIDER_INIT_FN)(AB_PROVIDER *pro, GWEN_DB_NODE *dbData); 50 51 /** See @ref AB_Provider_Fini. */ 52 typedef int (*AB_PROVIDER_FINI_FN)(AB_PROVIDER *pro, GWEN_DB_NODE *dbData); 53 54 55 typedef GWEN_DIALOG *(*AB_PROVIDER_GET_NEWUSER_DIALOG_FN)(AB_PROVIDER *pro, int i); 56 57 typedef GWEN_DIALOG *(*AB_PROVIDER_GET_EDITUSER_DIALOG_FN)(AB_PROVIDER *pro, AB_USER *u); 58 59 typedef GWEN_DIALOG *(*AB_PROVIDER_GET_NEWACCOUNT_DIALOG_FN)(AB_PROVIDER *pro); 60 61 typedef GWEN_DIALOG *(*AB_PROVIDER_GET_EDITACCOUNT_DIALOG_FN)(AB_PROVIDER *pro, AB_ACCOUNT *a); 62 63 typedef GWEN_DIALOG *(*AB_PROVIDER_GET_USERTYPE_DIALOG_FN)(AB_PROVIDER *pro); 64 65 66 67 typedef int (*AB_PROVIDER_SENDCOMMANDS_FN)(AB_PROVIDER *pro, AB_PROVIDERQUEUE *pq, AB_IMEXPORTER_CONTEXT *ctx); 68 69 70 typedef AB_ACCOUNT *(*AB_PROVIDER_CREATEACCOUNTOBJECT_FN)(AB_PROVIDER *pro); 71 72 typedef AB_USER *(*AB_PROVIDER_CREATEUSEROBJECT_FN)(AB_PROVIDER *pro); 73 74 typedef int (*AB_PROVIDER_UPDATEACCOUNTSPEC_FN)(AB_PROVIDER *pro, AB_ACCOUNT_SPEC *as, int doLock); 75 76 typedef int (*AB_PROVIDER_CONTROL_FN)(AB_PROVIDER *pro, int argc, char **argv); 77 78 /*@}*/ 79 80 81 82 83 84 AB_PROVIDER *AB_Provider_new(AB_BANKING *ab, const char *name); 85 86 87 88 /** 89 * @return 0 if the backend is not initialized, !=0 if it is 90 */ 91 int AB_Provider_IsInit(const AB_PROVIDER *pro); 92 93 94 95 void AB_Provider_AddFlags(AB_PROVIDER *pro, uint32_t fl); 96 97 98 /** @name Virtual Functions - Minimally Required Functions 99 * 100 */ 101 /*@{*/ 102 103 104 /** 105 * Allow the backend to initialize itself. 106 * @param pro backend object 107 * @param db db of the config group for this backend 108 */ 109 int AB_Provider_Init(AB_PROVIDER *pro, GWEN_DB_NODE *db); 110 111 112 113 /** 114 * Allow the backend to deinitialize itself. 115 * @param pro backend object 116 * @param db db of the config group for this backend 117 */ 118 int AB_Provider_Fini(AB_PROVIDER *pro, GWEN_DB_NODE *db); 119 120 121 122 /** 123 * Send commands to backends. 124 * The given queue can be modified by the provider in this function as it will be deleted upon return from this function. 125 * @return 0 if okay, error code otherwise 126 * @param pro pointer to the provider 127 * @param pq provider queue which contains the commands to send, sorted by account (may be modified by provider) 128 * @param ctx context to receive results 129 */ 130 int AB_Provider_SendCommands(AB_PROVIDER *pro, AB_PROVIDERQUEUE *pq, AB_IMEXPORTER_CONTEXT *ctx); 131 132 /*@}*/ 133 134 135 136 /** @name Virtual Functions - Functions Required When Working with AB_ACCOUNT/AB_USER 137 * 138 */ 139 /*@{*/ 140 141 /** 142 * Create an empty AB_ACCOUNT object. 143 * This function only needs to be implemented by backends which use AB_ACCOUNT objects internally and which 144 * want to use AqBankings convenience functions for loading and saving AB_ACCOUNT objects. 145 * 146 * @return AB_ACCOUNT object created, NULL on error 147 * @param pro provider which is to create the object 148 */ 149 AB_ACCOUNT *AB_Provider_CreateAccountObject(AB_PROVIDER *pro); 150 151 152 /** 153 * Create an empty AB_USER object. 154 * This function only needs to be implemented by backends which use AB_USER objects internally and which 155 * want to use AqBankings convenience functions for loading and saving AB_USER objects. 156 * 157 * @return AB_USER object created, NULL on error 158 * @param pro provider which is to create the object 159 */ 160 AB_USER *AB_Provider_CreateUserObject(AB_PROVIDER *pro); 161 162 163 /** 164 * Update the given account spec. 165 * 166 * This callback gives a provider the opportunity to set the transaction limits and other stuff. 167 * This function only needs to be implemented in the backend if it has some specials things to 168 * setup (like transaction limits). 169 * 170 * @return 0 if okay, error code otherwise 171 * @param pro pointer to provider object 172 * @param as account spec object to update 173 */ 174 int AB_Provider_UpdateAccountSpec(AB_PROVIDER *pro, AB_ACCOUNT_SPEC *as, int doLock); 175 176 /*@}*/ 177 178 179 180 /** @name Virtual Functions - Special Functions 181 * 182 */ 183 /*@{*/ 184 185 /** 186 * Allow the backend to perform some tasks specific to the given provider. 187 * 188 * Most backends use this function to provide command line functions to retrieve account list, 189 * create accounts and user etc. 190 * 191 * @return depending on the task performed, generally negative on error 192 * @param pro pointer to provider object 193 * @param argc number of arguments in the argument list 194 * @param argv pointer to the argument list 195 */ 196 int AB_Provider_Control(AB_PROVIDER *pro, int argc, char **argv); 197 198 199 /*@}*/ 200 201 202 203 204 /** @name Virtual Functions - Functions Providing Graphical Dialogs 205 * 206 */ 207 /*@{*/ 208 209 /** 210 * Create a dialog which allows to create a new user. 211 * The dialog returned (if any) must be derived via @ref AB_NewUserDialog_new(). 212 * @param pro pointer to the backend for which a new user is to be created 213 * @param i additional parameter depending on the backend. it can be used 214 * to specify the user type to be created (e.g. for HBCI those values 215 * specify whether PIN/TAN, keyfile or chipcard users are to be created). 216 * Use value 0 for the generic dialog. 217 */ 218 GWEN_DIALOG *AB_Provider_GetNewUserDialog(AB_PROVIDER *pro, int i); 219 220 221 222 GWEN_DIALOG *AB_Provider_GetEditUserDialog(AB_PROVIDER *pro, AB_USER *u); 223 224 225 226 /** 227 * Create a dialog which allows to create a new account. 228 * The dialog returned (if any) must be derived via @ref AB_NewAccountDialog_new(). 229 */ 230 GWEN_DIALOG *AB_Provider_GetNewAccountDialog(AB_PROVIDER *pro); 231 232 233 234 GWEN_DIALOG *AB_Provider_GetEditAccountDialog(AB_PROVIDER *pro, AB_ACCOUNT *a); 235 236 237 238 GWEN_DIALOG *AB_Provider_GetUserTypeDialog(AB_PROVIDER *pro); 239 240 241 242 /*@}*/ 243 244 245 246 /** @name Setters For Virtual Functions 247 * 248 */ 249 /*@{*/ 250 void AB_Provider_SetInitFn(AB_PROVIDER *pro, AB_PROVIDER_INIT_FN f); 251 252 void AB_Provider_SetFiniFn(AB_PROVIDER *pro, AB_PROVIDER_FINI_FN f); 253 254 void AB_Provider_SetSendCommandsFn(AB_PROVIDER *pro, AB_PROVIDER_SENDCOMMANDS_FN f); 255 256 void AB_Provider_SetCreateAccountObjectsFn(AB_PROVIDER *pro, AB_PROVIDER_CREATEACCOUNTOBJECT_FN f); 257 258 void AB_Provider_SetCreateUserObjectsFn(AB_PROVIDER *pro, AB_PROVIDER_CREATEUSEROBJECT_FN f); 259 260 void AB_Provider_SetUpdateAccountSpecFn(AB_PROVIDER *pro, AB_PROVIDER_UPDATEACCOUNTSPEC_FN f); 261 262 void AB_Provider_SetControlFn(AB_PROVIDER *pro, AB_PROVIDER_CONTROL_FN f); 263 264 265 void AB_Provider_SetGetNewUserDialogFn(AB_PROVIDER *pro, AB_PROVIDER_GET_NEWUSER_DIALOG_FN f); 266 267 void AB_Provider_SetGetEditUserDialogFn(AB_PROVIDER *pro, AB_PROVIDER_GET_EDITUSER_DIALOG_FN f); 268 269 void AB_Provider_SetGetNewAccountDialogFn(AB_PROVIDER *pro, AB_PROVIDER_GET_NEWACCOUNT_DIALOG_FN f); 270 271 void AB_Provider_SetGetEditAccountDialogFn(AB_PROVIDER *pro, AB_PROVIDER_GET_EDITACCOUNT_DIALOG_FN f); 272 273 void AB_Provider_SetGetUserTypeDialogFn(AB_PROVIDER *pro, AB_PROVIDER_GET_USERTYPE_DIALOG_FN f); 274 275 /*@}*/ 276 277 278 279 280 281 /** @name Account Management Functions 282 * 283 */ 284 /*@{*/ 285 286 /** 287 * Read account given by its unique id. 288 * 289 * When reading the object it will be locked and/or unlocked as requestd. 290 * If both the parameters doLock and doUnlock are !=0 you can later call @ref AB_Provider_EndExclUseAccount on the 291 * account object returned (if any). 292 * 293 * @return 0 if okay, <0 on error 294 * @param pro provider (THIS in C++ speak) 295 * @param uid unique id of the object to read 296 * @param doLock do lock the objects configuration before reading 297 * @param doUnlock do unlock the objects configuration after reading 298 * @param account pointer to the object to read the configuration into 299 */ 300 int AB_Provider_ReadAccount(AB_PROVIDER *pro, uint32_t uid, int doLock, int doUnlock, AB_ACCOUNT *account); 301 302 303 /** 304 * Get account given by its unique id. 305 * 306 * When reading the object it will be locked and/or unlocked as requestd. 307 * If both the parameters doLock and doUnlock are !=0 you can later call @ref AB_Provider_EndExclUseAccount on the 308 * object returned (if any). 309 * 310 * @return 0 if okay, <0 on error 311 * @param pro provider (THIS in C++ speak) 312 * @param uid unique id of the object to read 313 * @param doLock do lock the objects configuration before reading 314 * @param doUnlock do unlock the objects configuration after reading 315 * @param pAccount pointer to a pointer to receive the object created and read 316 */ 317 int AB_Provider_GetAccount(AB_PROVIDER *pro, uint32_t uid, int doLock, int doUnlock, AB_ACCOUNT **pAccount); 318 319 320 /** 321 * Read all account objects belonging to this provider. 322 * @return 0 if okay, <0 on error 323 * @param pro provider (THIS in C++ speak) 324 * @param accountList list to receive all objects read 325 */ 326 int AB_Provider_ReadAccounts(AB_PROVIDER *pro, AB_ACCOUNT_LIST *accountList); 327 328 329 /** 330 * Check whether an account with the given id exists. 331 * @return 0 if a user with the given id exists, error code otherwise 332 * @param pro pointer to provider object 333 * @param uid unique id of the object in question 334 */ 335 int AB_Provider_HasAccount(AB_PROVIDER *pro, uint32_t uid); 336 337 338 /** 339 * Write account given by its unique id. 340 * 341 * When writing the object it will be locked and/or unlocked as requested. 342 * If both the parameters doLock and doUnlock are !=0 you can later call @ref AH_Provider_EndExclUseAccount on the 343 * object returned (if any). 344 * 345 * @return 0 if okay, <0 on error 346 * @param pro provider (THIS in C++ speak) 347 * @param uid unique id of the object to read 348 * @param doLock do lock the objects configuration before reading 349 * @param doUnlock do unlock the objects configuration after reading 350 * @param account pointer to the object to be written to the configuration 351 */ 352 int AB_Provider_WriteAccount(AB_PROVIDER *pro, uint32_t uid, int doLock, int doUnlock, const AB_ACCOUNT *account); 353 354 355 /** 356 * Add an account to the configuration. Assigns a unique id to the new account. 357 * 358 * Also creates and adds a AB_ACCOUNT_SPEC object for applications. 359 * Internally calls the callback function @ref AB_Provider_UpdateAccountSpec(). 360 * 361 * @return 0 on success, error code otherwise 362 * @param pro provider (THIS in C++ speak) 363 * @param a account to add 364 * @param lockCorrespondingUser lock user which this account belongs to while using user data. 365 * Some backends (e.g. AqHBCI) access the corresponding AB_USER object when creating AB_ACCOUNT_SPEC 366 * objects for the given account. If the user is already locked for any reason, the function 367 * should not try to lock the AB_USER object because that must fail. 368 * 369 */ 370 int AB_Provider_AddAccount(AB_PROVIDER *pro, AB_ACCOUNT *a, int lockCorrespondingUser); 371 372 373 /** 374 * Remove an account from the configuration. 375 * 376 * Also removes the corresponding AB_ACCOUNT_SPEC object for applications. 377 * 378 * @return 0 on success, error code otherwise 379 * @param pro provider (THIS in C++ speak) 380 * @param uid unique id of the account to remove 381 */ 382 int AB_Provider_DeleteAccount(AB_PROVIDER *pro, uint32_t uid); 383 384 385 /** 386 * Begin exclusively using the given account. 387 * This function locks the configuration for the given account, reads the configuration and 388 * leaves the configuration locked upon return. 389 * Therefore you MUST call @ref AH_Provider_EndExclUseAccount() to unlock it later. 390 */ 391 int AB_Provider_BeginExclUseAccount(AB_PROVIDER *pro, AB_ACCOUNT *a); 392 393 394 /** 395 * End exclusive use of the given account. 396 * This function writes the still locked configuration of the account and unlocks it afterwards. 397 * 398 * @param pro pointer to provider object 399 * @param a pointer to account 400 * @param abandon if !=0 the configuration is just unlocked, not written 401 */ 402 int AB_Provider_EndExclUseAccount(AB_PROVIDER *pro, AB_ACCOUNT *a, int abandon); 403 404 405 /** 406 * Find an account spec from a list which matches the given account. 407 * Only checks against account specs from the same provider as the called one (i.e. if this is the AqHBCI 408 * provider only AqHBCI account specs are checked against). 409 * 410 * @return pointer to matching account spec from the given list, NULL if none found 411 * @param acc account to look for 412 * @param asl account spec list to check against 413 */ 414 AB_ACCOUNT_SPEC *AB_Provider_FindMatchingAccountSpec(AB_PROVIDER *pro, const AB_ACCOUNT *acc, 415 AB_ACCOUNT_SPEC_LIST *asl); 416 417 418 /*@}*/ 419 420 421 422 /** @name User Management Functions 423 * 424 */ 425 /*@{*/ 426 427 428 /** 429 * This functions reads a user from the configuration database. 430 * When reading the user object it will be locked and/or unlocked as requestd. 431 * If both the parameters doLock and doUnlock are !=0 you can later call @ref AB_Provider_EndExclUseUser on the 432 * user object returned (if any). 433 * 434 * @param pro pointer to provider object 435 * @param uid unique id of the user to read 436 * @param doLock if !0 0 the config group for the given object will be locked before reading 437 * @param doUnlock if !0 0 the config group for the given object will be unlocked after reading 438 * @param pUser pointer to a variable to receive the user read 439 */ 440 int AB_Provider_GetUser(AB_PROVIDER *pro, uint32_t uid, int doLock, int doUnlock, AB_USER **pUser); 441 442 443 /** 444 * Read all users of this backend. 445 * 446 * The caller is responsible for releasing the list and the contained users (if any), 447 * e.g. by calling @ref AB_User_List_free(). 448 * 449 * @return 0 on success, error code otherwise 450 * @param pro pointer to provider object 451 * @param userList pointer to a list to receive the users. 452 */ 453 int AB_Provider_ReadUsers(AB_PROVIDER *pro, AB_USER_LIST *userList); 454 455 456 /** 457 * Check whether a user with the given id exists. 458 * @return 0 if a user with the given id exists, error code otherwise 459 * @param pro pointer to provider object 460 * @param uid unique id of the object in question 461 */ 462 int AB_Provider_HasUser(AB_PROVIDER *pro, uint32_t uid); 463 464 465 /** 466 * Write user given by its unique id. 467 * 468 * When writing the object it will be locked and/or unlocked as requested. 469 * If both the parameters doLock and doUnlock are !=0 you can later call @ref AB_Provider_EndExclUseUser on the 470 * object returned (if any). 471 * 472 * @return 0 if okay, <0 on error 473 * @param pro provider (THIS in C++ speak) 474 * @param uid unique id of the object to write 475 * @param doLock do lock the objects configuration before reading 476 * @param doUnlock do unlock the objects configuration after reading 477 * @param user pointer to the object to be written to the configuration 478 */ 479 int AB_Provider_WriteUser(AB_PROVIDER *pro, uint32_t uid, int doLock, int doUnlock, const AB_USER *user); 480 481 482 /** 483 * Add a user to the configuration. Assigns a unique id to the new user. 484 * 485 * @return 0 on success, error code otherwise 486 * @param pro provider (THIS in C++ speak) 487 * @param u user to add 488 * 489 */ 490 int AB_Provider_AddUser(AB_PROVIDER *pro, AB_USER *u); 491 492 493 /** 494 * Remove a user from the configuration. 495 * 496 * @return 0 on success, error code otherwise 497 * @param pro provider (THIS in C++ speak) 498 * @param uid unique id of the account to remove 499 */ 500 int AB_Provider_DeleteUser(AB_PROVIDER *pro, uint32_t uid); 501 502 503 504 /** 505 * Begin exclusively using the given user. 506 * This function locks the configuration for the given user, reads the configuration and 507 * leaves the configuration locked upon return. 508 * Therefore you MUST call @ref AH_Provider_EndExclUseUser() to unlock it later. 509 */ 510 int AB_Provider_BeginExclUseUser(AB_PROVIDER *pro, AB_USER *u); 511 512 513 /** 514 * End exclusive use of the given user. 515 * This function writes the still locked configuration of the user and unlocks it afterwards. 516 * 517 * @param pro pointer to provider object 518 * @param u pointer to user 519 * @param abandon if !=0 the configuration is just unlocked, not written 520 */ 521 int AB_Provider_EndExclUseUser(AB_PROVIDER *pro, AB_USER *u, int abandon); 522 523 524 /*@}*/ 525 526 527 528 /** @name Account Spec Management Functions 529 * 530 */ 531 /*@{*/ 532 533 534 int AB_Provider_AccountToAccountSpec(AB_PROVIDER *pro, const AB_ACCOUNT *acc, AB_ACCOUNT_SPEC *as, int doLock); 535 int AB_Provider_WriteAccountSpecForAccount(AB_PROVIDER *pro, const AB_ACCOUNT *acc, int doLock); 536 int AB_Provider_CreateInitialAccountSpecs(AB_PROVIDER *pro); 537 538 539 /*@}*/ 540 541 542 543 544 545 546 /** @name Queue Management Functions 547 * 548 */ 549 /*@{*/ 550 551 552 /** 553 * Sort jobs in provider queues (AB_PROVIDERQUEUE) into a list of AB_USERQUEUEs. 554 * This function makes use of the field @ref AB_ACCOUNT_userId. 555 */ 556 int AB_Provider_SortProviderQueueIntoUserQueueList(AB_PROVIDER *pro, AB_PROVIDERQUEUE *pq, AB_USERQUEUE_LIST *uql); 557 558 559 /** 560 * Frees all users and accounts mentioned in the given AB_USERQUEUE list. 561 */ 562 void AB_Provider_FreeUsersAndAccountsFromUserQueueList(AB_PROVIDER *pro, AB_USERQUEUE_LIST *uql); 563 564 565 566 /*@}*/ 567 568 569 570 571 572 typedef AB_PROVIDER *(*AB_PLUGIN_PROVIDER_FACTORY_FN)(GWEN_PLUGIN *pl, AB_BANKING *ab); 573 574 575 GWEN_PLUGIN *AB_Plugin_Provider_new(GWEN_PLUGIN_MANAGER *pm, 576 const char *name, 577 const char *fileName); 578 579 580 AB_PROVIDER *AB_Plugin_Provider_Factory(GWEN_PLUGIN *pl, AB_BANKING *ab); 581 582 void AB_Plugin_Provider_SetFactoryFn(GWEN_PLUGIN *pl, AB_PLUGIN_PROVIDER_FACTORY_FN fn); 583 584 585 586 587 /*@}*/ /* defgroup */ 588 589 590 #ifdef __cplusplus 591 } 592 #endif 593 594 595 596 597 #endif /* AQBANKING_PROVIDER_BE_H */ 598 599 600 601 602 603 604 605 606 607