diff options
Diffstat (limited to 'src/include/gnunet_pq_lib.h')
-rw-r--r-- | src/include/gnunet_pq_lib.h | 268 |
1 files changed, 267 insertions, 1 deletions
diff --git a/src/include/gnunet_pq_lib.h b/src/include/gnunet_pq_lib.h index 756370b74..ed295b500 100644 --- a/src/include/gnunet_pq_lib.h +++ b/src/include/gnunet_pq_lib.h | |||
@@ -1,6 +1,6 @@ | |||
1 | /* | 1 | /* |
2 | This file is part of GNUnet | 2 | This file is part of GNUnet |
3 | Copyright (C) 2016 GNUnet e.V. | 3 | Copyright (C) 2016, 2017 GNUnet e.V. |
4 | 4 | ||
5 | GNUnet is free software; you can redistribute it and/or modify it under the | 5 | GNUnet is free software; you can redistribute it and/or modify it under the |
6 | terms of the GNU General Public License as published by the Free Software | 6 | terms of the GNU General Public License as published by the Free Software |
@@ -23,6 +23,9 @@ | |||
23 | 23 | ||
24 | #include <libpq-fe.h> | 24 | #include <libpq-fe.h> |
25 | #include "gnunet_util_lib.h" | 25 | #include "gnunet_util_lib.h" |
26 | #include "gnunet_db_lib.h" | ||
27 | |||
28 | /* ************************* pq_query_helper.c functions ************************ */ | ||
26 | 29 | ||
27 | 30 | ||
28 | /** | 31 | /** |
@@ -188,6 +191,9 @@ struct GNUNET_PQ_QueryParam | |||
188 | GNUNET_PQ_query_param_uint64 (const uint64_t *x); | 191 | GNUNET_PQ_query_param_uint64 (const uint64_t *x); |
189 | 192 | ||
190 | 193 | ||
194 | /* ************************* pq_result_helper.c functions ************************ */ | ||
195 | |||
196 | |||
191 | /** | 197 | /** |
192 | * Extract data from a Postgres database @a result at row @a row. | 198 | * Extract data from a Postgres database @a result at row @a row. |
193 | * | 199 | * |
@@ -412,6 +418,8 @@ GNUNET_PQ_result_spec_uint64 (const char *name, | |||
412 | uint64_t *u64); | 418 | uint64_t *u64); |
413 | 419 | ||
414 | 420 | ||
421 | /* ************************* pq.c functions ************************ */ | ||
422 | |||
415 | /** | 423 | /** |
416 | * Execute a prepared statement. | 424 | * Execute a prepared statement. |
417 | * | 425 | * |
@@ -419,6 +427,7 @@ GNUNET_PQ_result_spec_uint64 (const char *name, | |||
419 | * @param name name of the prepared statement | 427 | * @param name name of the prepared statement |
420 | * @param params parameters to the statement | 428 | * @param params parameters to the statement |
421 | * @return postgres result | 429 | * @return postgres result |
430 | * @deprecated (should become an internal API) | ||
422 | */ | 431 | */ |
423 | PGresult * | 432 | PGresult * |
424 | GNUNET_PQ_exec_prepared (PGconn *db_conn, | 433 | GNUNET_PQ_exec_prepared (PGconn *db_conn, |
@@ -435,6 +444,7 @@ GNUNET_PQ_exec_prepared (PGconn *db_conn, | |||
435 | * @return | 444 | * @return |
436 | * #GNUNET_YES if all results could be extracted | 445 | * #GNUNET_YES if all results could be extracted |
437 | * #GNUNET_SYSERR if a result was invalid (non-existing field) | 446 | * #GNUNET_SYSERR if a result was invalid (non-existing field) |
447 | * @deprecated (should become an internal API) | ||
438 | */ | 448 | */ |
439 | int | 449 | int |
440 | GNUNET_PQ_extract_result (PGresult *result, | 450 | GNUNET_PQ_extract_result (PGresult *result, |
@@ -452,6 +462,262 @@ void | |||
452 | GNUNET_PQ_cleanup_result (struct GNUNET_PQ_ResultSpec *rs); | 462 | GNUNET_PQ_cleanup_result (struct GNUNET_PQ_ResultSpec *rs); |
453 | 463 | ||
454 | 464 | ||
465 | /* ******************** pq_eval.c functions ************** */ | ||
466 | |||
467 | |||
468 | /** | ||
469 | * Check the @a result's error code to see what happened. | ||
470 | * Also logs errors. | ||
471 | * | ||
472 | * @param connection connection to execute the statement in | ||
473 | * @param statement_name name of the statement that created @a result | ||
474 | * @param result result to check | ||
475 | * @return status code from the result, mapping PQ status | ||
476 | * codes to `enum GNUNET_DB_QueryStatus`. Never | ||
477 | * returns positive values as this function does | ||
478 | * not look at the result set. | ||
479 | * @deprecated (low level, let's see if we can do with just the high-level functions) | ||
480 | */ | ||
481 | enum GNUNET_DB_QueryStatus | ||
482 | GNUNET_PQ_eval_result (PGconn *connection, | ||
483 | const char *statement_name, | ||
484 | PGresult *result); | ||
485 | |||
486 | |||
487 | /** | ||
488 | * Execute a named prepared @a statement that is NOT a SELECT | ||
489 | * statement in @a connnection using the given @a params. Returns the | ||
490 | * resulting session state. | ||
491 | * | ||
492 | * @param connection connection to execute the statement in | ||
493 | * @param statement_name name of the statement | ||
494 | * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated) | ||
495 | * @return status code from the result, mapping PQ status | ||
496 | * codes to `enum GNUNET_DB_QueryStatus`. If the | ||
497 | * statement was a DELETE or UPDATE statement, the | ||
498 | * number of affected rows is returned; if the | ||
499 | * statment was an INSERT statement, and no row | ||
500 | * was added due to a UNIQUE violation, we return | ||
501 | * zero; if INSERT was successful, we return one. | ||
502 | */ | ||
503 | enum GNUNET_DB_QueryStatus | ||
504 | GNUNET_PQ_eval_prepared_non_select (PGconn *connection, | ||
505 | const char *statement_name, | ||
506 | const struct GNUNET_PQ_QueryParam *params); | ||
507 | |||
508 | |||
509 | /** | ||
510 | * Function to be called with the results of a SELECT statement | ||
511 | * that has returned @a num_results results. | ||
512 | * | ||
513 | * @param cls closure | ||
514 | * @param result the postgres result | ||
515 | * @param num_result the number of results in @a result | ||
516 | */ | ||
517 | typedef void | ||
518 | (*GNUNET_PQ_PostgresResultHandler)(void *cls, | ||
519 | PGresult *result, | ||
520 | unsigned int num_results); | ||
521 | |||
522 | |||
523 | /** | ||
524 | * Execute a named prepared @a statement that is a SELECT statement | ||
525 | * which may return multiple results in @a connection using the given | ||
526 | * @a params. Call @a rh with the results. Returns the query | ||
527 | * status including the number of results given to @a rh (possibly zero). | ||
528 | * @a rh will not have been called if the return value is negative. | ||
529 | * | ||
530 | * @param connection connection to execute the statement in | ||
531 | * @param statement_name name of the statement | ||
532 | * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated) | ||
533 | * @param rh function to call with the result set, NULL to ignore | ||
534 | * @param rh_cls closure to pass to @a rh | ||
535 | * @return status code from the result, mapping PQ status | ||
536 | * codes to `enum GNUNET_DB_QueryStatus`. | ||
537 | */ | ||
538 | enum GNUNET_DB_QueryStatus | ||
539 | GNUNET_PQ_eval_prepared_multi_select (PGconn *connection, | ||
540 | const char *statement_name, | ||
541 | const struct GNUNET_PQ_QueryParam *params, | ||
542 | GNUNET_PQ_PostgresResultHandler rh, | ||
543 | void *rh_cls); | ||
544 | |||
545 | |||
546 | /** | ||
547 | * Execute a named prepared @a statement that is a SELECT statement | ||
548 | * which must return a single result in @a connection using the given | ||
549 | * @a params. Stores the result (if any) in @a rs, which the caller | ||
550 | * must then clean up using #GNUNET_PQ_cleanup_result() if the return | ||
551 | * value was #GNUNET_DB_STATUS_SUCCESS_ONE_RESULT. Returns the | ||
552 | * resulting session status. | ||
553 | * | ||
554 | * @param connection connection to execute the statement in | ||
555 | * @param statement_name name of the statement | ||
556 | * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated) | ||
557 | * @param[in,out] rs result specification to use for storing the result of the query | ||
558 | * @return status code from the result, mapping PQ status | ||
559 | * codes to `enum GNUNET_DB_QueryStatus`. | ||
560 | */ | ||
561 | enum GNUNET_DB_QueryStatus | ||
562 | GNUNET_PQ_eval_prepared_singleton_select (PGconn *connection, | ||
563 | const char *statement_name, | ||
564 | const struct GNUNET_PQ_QueryParam *params, | ||
565 | struct GNUNET_PQ_ResultSpec *rs); | ||
566 | |||
567 | |||
568 | /* ******************** pq_prepare.c functions ************** */ | ||
569 | |||
570 | |||
571 | /** | ||
572 | * Information needed to prepare a list of SQL statements using | ||
573 | * #GNUNET_PQ_prepare_statements(). | ||
574 | */ | ||
575 | struct GNUNET_PQ_PreparedStatement { | ||
576 | |||
577 | /** | ||
578 | * Name of the statement. | ||
579 | */ | ||
580 | const char *name; | ||
581 | |||
582 | /** | ||
583 | * Actual SQL statement. | ||
584 | */ | ||
585 | const char *sql; | ||
586 | |||
587 | /** | ||
588 | * Number of arguments included in @e sql. | ||
589 | */ | ||
590 | unsigned int num_arguments; | ||
591 | |||
592 | }; | ||
593 | |||
594 | |||
595 | /** | ||
596 | * Terminator for prepared statement list. | ||
597 | */ | ||
598 | #define GNUNET_PQ_PREPARED_STATEMENT_END { NULL, NULL, 0 } | ||
599 | |||
600 | |||
601 | /** | ||
602 | * Create a `struct GNUNET_PQ_PreparedStatement`. | ||
603 | * | ||
604 | * @param name name of the statement | ||
605 | * @param sql actual SQL statement | ||
606 | * @param num_args number of arguments in the statement | ||
607 | * @return initialized struct | ||
608 | */ | ||
609 | struct GNUNET_PQ_PreparedStatement | ||
610 | GNUNET_PQ_make_prepare (const char *name, | ||
611 | const char *sql, | ||
612 | unsigned int num_args); | ||
613 | |||
614 | |||
615 | /** | ||
616 | * Request creation of prepared statements @a ps from Postgres. | ||
617 | * | ||
618 | * @param connection connection to prepare the statements for | ||
619 | * @param ps #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared | ||
620 | * statements. | ||
621 | * @return #GNUNET_OK on success, | ||
622 | * #GNUNET_SYSERR on error | ||
623 | */ | ||
624 | int | ||
625 | GNUNET_PQ_prepare_statements (PGconn *connection, | ||
626 | const struct GNUNET_PQ_PreparedStatement *ps); | ||
627 | |||
628 | |||
629 | /* ******************** pq_exec.c functions ************** */ | ||
630 | |||
631 | |||
632 | /** | ||
633 | * Information needed to run a list of SQL statements using | ||
634 | * #GNUNET_PQ_exec_statements(). | ||
635 | */ | ||
636 | struct GNUNET_PQ_ExecuteStatement { | ||
637 | |||
638 | /** | ||
639 | * Actual SQL statement. | ||
640 | */ | ||
641 | const char *sql; | ||
642 | |||
643 | /** | ||
644 | * Should we ignore errors? | ||
645 | */ | ||
646 | int ignore_errors; | ||
647 | |||
648 | }; | ||
649 | |||
650 | |||
651 | /** | ||
652 | * Terminator for executable statement list. | ||
653 | */ | ||
654 | #define GNUNET_PQ_EXECUTE_STATEMENT_END { NULL, GNUNET_SYSERR } | ||
655 | |||
656 | |||
657 | /** | ||
658 | * Create a `struct GNUNET_PQ_ExecuteStatement` where errors are fatal. | ||
659 | * | ||
660 | * @param sql actual SQL statement | ||
661 | * @return initialized struct | ||
662 | */ | ||
663 | struct GNUNET_PQ_ExecuteStatement | ||
664 | GNUNET_PQ_make_execute (const char *sql); | ||
665 | |||
666 | |||
667 | /** | ||
668 | * Create a `struct GNUNET_PQ_ExecuteStatement` where errors should | ||
669 | * be tolerated. | ||
670 | * | ||
671 | * @param sql actual SQL statement | ||
672 | * @return initialized struct | ||
673 | */ | ||
674 | struct GNUNET_PQ_ExecuteStatement | ||
675 | GNUNET_PQ_make_try_execute (const char *sql); | ||
676 | |||
677 | |||
678 | /** | ||
679 | * Request execution of an array of statements @a es from Postgres. | ||
680 | * | ||
681 | * @param connection connection to execute the statements over | ||
682 | * @param es #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared | ||
683 | * statements. | ||
684 | * @return #GNUNET_OK on success (modulo statements where errors can be ignored) | ||
685 | * #GNUNET_SYSERR on error | ||
686 | */ | ||
687 | int | ||
688 | GNUNET_PQ_exec_statements (PGconn *connection, | ||
689 | const struct GNUNET_PQ_ExecuteStatement *es); | ||
690 | |||
691 | |||
692 | /* ******************** pq_connect.c functions ************** */ | ||
693 | |||
694 | |||
695 | /** | ||
696 | * Create a connection to the Postgres database using @a config_str | ||
697 | * for the configuration. Initialize logging via GNUnet's log | ||
698 | * routines and disable Postgres's logger. | ||
699 | * | ||
700 | * @param config_str configuration to use | ||
701 | * @return NULL on error | ||
702 | */ | ||
703 | PGconn * | ||
704 | GNUNET_PQ_connect (const char *config_str); | ||
705 | |||
706 | |||
707 | /** | ||
708 | * Connect to a postgres database using the configuration | ||
709 | * option "CONFIG" in @a section. | ||
710 | * | ||
711 | * @param cfg configuration | ||
712 | * @param section configuration section to use to get Postgres configuration options | ||
713 | * @return the postgres handle, NULL on error | ||
714 | */ | ||
715 | PGconn * | ||
716 | GNUNET_PQ_connect_with_cfg (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
717 | const char *section); | ||
718 | |||
719 | |||
720 | |||
455 | #endif /* GNUNET_PQ_LIB_H_ */ | 721 | #endif /* GNUNET_PQ_LIB_H_ */ |
456 | 722 | ||
457 | /* end of include/gnunet_pq_lib.h */ | 723 | /* end of include/gnunet_pq_lib.h */ |