diff options
author | Christian Grothoff <christian@grothoff.org> | 2017-06-01 21:48:19 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2017-06-01 21:48:19 +0200 |
commit | 1defd30dfeb1867c2756b3fe6a437f695951d0c9 (patch) | |
tree | b48c0fe6bb32469cfcb4284bfac3142e22417ae8 /src/include/gnunet_pq_lib.h | |
parent | bbbe0b2404d131cc0d9eda26725b65b47a7e073a (diff) | |
download | gnunet-1defd30dfeb1867c2756b3fe6a437f695951d0c9.tar.gz gnunet-1defd30dfeb1867c2756b3fe6a437f695951d0c9.zip |
adding more good helpers to libgnunetpq
Diffstat (limited to 'src/include/gnunet_pq_lib.h')
-rw-r--r-- | src/include/gnunet_pq_lib.h | 293 |
1 files changed, 293 insertions, 0 deletions
diff --git a/src/include/gnunet_pq_lib.h b/src/include/gnunet_pq_lib.h index 756370b74..5e54813e3 100644 --- a/src/include/gnunet_pq_lib.h +++ b/src/include/gnunet_pq_lib.h | |||
@@ -25,6 +25,9 @@ | |||
25 | #include "gnunet_util_lib.h" | 25 | #include "gnunet_util_lib.h" |
26 | 26 | ||
27 | 27 | ||
28 | /* ************************* pq_query_helper.c functions ************************ */ | ||
29 | |||
30 | |||
28 | /** | 31 | /** |
29 | * Function called to convert input argument into SQL parameters. | 32 | * Function called to convert input argument into SQL parameters. |
30 | * | 33 | * |
@@ -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,289 @@ 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 | * Status code returned from functions running PQ commands. | ||
470 | * Can be combined with a function that returns the number | ||
471 | * of results, so non-negative values indicate success. | ||
472 | */ | ||
473 | enum GNUNET_PQ_QueryStatus | ||
474 | { | ||
475 | /** | ||
476 | * A hard error occurred, retrying will not help. | ||
477 | */ | ||
478 | GNUNET_PQ_STATUS_HARD_ERROR = -2, | ||
479 | |||
480 | /** | ||
481 | * A soft error occurred, retrying the transaction may succeed. | ||
482 | */ | ||
483 | GNUNET_PQ_STATUS_SOFT_ERROR = -1, | ||
484 | |||
485 | /** | ||
486 | * The transaction succeeded, but yielded zero results. | ||
487 | */ | ||
488 | GNUNET_PQ_STATUS_SUCCESS_NO_RESULTS = 0, | ||
489 | |||
490 | /** | ||
491 | * The transaction succeeded, and yielded one result. | ||
492 | */ | ||
493 | GNUNET_PQ_STATUS_SUCCESS_ONE_RESULT = 1 | ||
494 | |||
495 | }; | ||
496 | |||
497 | |||
498 | /** | ||
499 | * Check the @a result's error code to see what happened. | ||
500 | * Also logs errors. | ||
501 | * | ||
502 | * @param connection connection to execute the statement in | ||
503 | * @param statement_name name of the statement that created @a result | ||
504 | * @param result result to check | ||
505 | * @return status code from the result, mapping PQ status | ||
506 | * codes to `enum GNUNET_PQ_QueryStatus`. Never | ||
507 | * returns positive values as this function does | ||
508 | * not look at the result set. | ||
509 | * @deprecated (low level, let's see if we can do with just the high-level functions) | ||
510 | */ | ||
511 | enum GNUNET_PQ_QueryStatus | ||
512 | GNUNET_PQ_eval_result (PGconn *connection, | ||
513 | const char *statement_name, | ||
514 | PGresult *result); | ||
515 | |||
516 | |||
517 | /** | ||
518 | * Execute a named prepared @a statement that is NOT a SELECT | ||
519 | * statement in @a connnection using the given @a params. Returns the | ||
520 | * resulting session state. | ||
521 | * | ||
522 | * @param connection connection to execute the statement in | ||
523 | * @param statement_name name of the statement | ||
524 | * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated) | ||
525 | * @return status code from the result, mapping PQ status | ||
526 | * codes to `enum GNUNET_PQ_QueryStatus`. Never | ||
527 | * returns positive values as this function does | ||
528 | * not look at the result set. | ||
529 | */ | ||
530 | enum GNUNET_PQ_QueryStatus | ||
531 | GNUNET_PQ_eval_prepared_non_select (PGconn *connection, | ||
532 | const char *statement_name, | ||
533 | const struct GNUNET_PQ_QueryParam *params); | ||
534 | |||
535 | |||
536 | /** | ||
537 | * Function to be called with the results of a SELECT statement | ||
538 | * that has returned @a num_results results. | ||
539 | * | ||
540 | * @param cls closure | ||
541 | * @param result the postgres result | ||
542 | * @param num_result the number of results in @a result | ||
543 | */ | ||
544 | typedef void | ||
545 | (*GNUNET_PQ_PostgresResultHandler)(void *cls, | ||
546 | PGresult *result, | ||
547 | unsigned int num_results); | ||
548 | |||
549 | |||
550 | /** | ||
551 | * Execute a named prepared @a statement that is a SELECT statement | ||
552 | * which may return multiple results in @a connection using the given | ||
553 | * @a params. Call @a rh with the results. Returns the query | ||
554 | * status including the number of results given to @a rh (possibly zero). | ||
555 | * @a rh will not have been called if the return value is negative. | ||
556 | * | ||
557 | * @param connection connection to execute the statement in | ||
558 | * @param statement_name name of the statement | ||
559 | * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated) | ||
560 | * @param rh function to call with the result set, NULL to ignore | ||
561 | * @param rh_cls closure to pass to @a rh | ||
562 | * @return status code from the result, mapping PQ status | ||
563 | * codes to `enum GNUNET_PQ_QueryStatus`. | ||
564 | */ | ||
565 | enum GNUNET_PQ_QueryStatus | ||
566 | GNUNET_PQ_eval_prepared_multi_select (PGconn *connection, | ||
567 | const char *statement_name, | ||
568 | const struct GNUNET_PQ_QueryParam *params, | ||
569 | GNUNET_PQ_PostgresResultHandler rh, | ||
570 | void *rh_cls); | ||
571 | |||
572 | |||
573 | /** | ||
574 | * Execute a named prepared @a statement that is a SELECT statement | ||
575 | * which must return a single result in @a connection using the given | ||
576 | * @a params. Stores the result (if any) in @a rs, which the caller | ||
577 | * must then clean up using #GNUNET_PQ_cleanup_result() if the return | ||
578 | * value was #GNUNET_PQ_STATUS_SUCCESS_ONE_RESULT. Returns the | ||
579 | * resulting session status. | ||
580 | * | ||
581 | * @param connection connection to execute the statement in | ||
582 | * @param statement_name name of the statement | ||
583 | * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated) | ||
584 | * @param[in,out] rs result specification to use for storing the result of the query | ||
585 | * @return status code from the result, mapping PQ status | ||
586 | * codes to `enum GNUNET_PQ_QueryStatus`. | ||
587 | */ | ||
588 | enum GNUNET_PQ_QueryStatus | ||
589 | GNUNET_PQ_eval_prepared_singleton_select (PGconn *connection, | ||
590 | const char *statement_name, | ||
591 | const struct GNUNET_PQ_QueryParam *params, | ||
592 | struct GNUNET_PQ_ResultSpec *rs); | ||
593 | |||
594 | |||
595 | /* ******************** pq_prepare.c functions ************** */ | ||
596 | |||
597 | |||
598 | /** | ||
599 | * Information needed to prepare a list of SQL statements using | ||
600 | * #GNUNET_PQ_prepare_statements(). | ||
601 | */ | ||
602 | struct GNUNET_PQ_PreparedStatement { | ||
603 | |||
604 | /** | ||
605 | * Name of the statement. | ||
606 | */ | ||
607 | const char *name; | ||
608 | |||
609 | /** | ||
610 | * Actual SQL statement. | ||
611 | */ | ||
612 | const char *sql; | ||
613 | |||
614 | /** | ||
615 | * Number of arguments included in @e sql. | ||
616 | */ | ||
617 | unsigned int num_arguments; | ||
618 | |||
619 | }; | ||
620 | |||
621 | |||
622 | /** | ||
623 | * Terminator for prepared statement list. | ||
624 | */ | ||
625 | #define GNUNET_PQ_PREPARED_STATEMENT_END { NULL, NULL, 0 } | ||
626 | |||
627 | |||
628 | /** | ||
629 | * Create a `struct GNUNET_PQ_PreparedStatement`. | ||
630 | * | ||
631 | * @param name name of the statement | ||
632 | * @param sql actual SQL statement | ||
633 | * @param num_args number of arguments in the statement | ||
634 | * @return initialized struct | ||
635 | */ | ||
636 | struct GNUNET_PQ_PreparedStatement | ||
637 | GNUNET_PQ_make_prepare (const char *name, | ||
638 | const char *sql, | ||
639 | unsigned int num_args); | ||
640 | |||
641 | |||
642 | /** | ||
643 | * Request creation of prepared statements @a ps from Postgres. | ||
644 | * | ||
645 | * @param connection connection to prepare the statements for | ||
646 | * @param ps #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared | ||
647 | * statements. | ||
648 | * @return #GNUNET_OK on success, | ||
649 | * #GNUNET_SYSERR on error | ||
650 | */ | ||
651 | int | ||
652 | GNUNET_PQ_prepare_statements (PGconn *connection, | ||
653 | const struct GNUNET_PQ_PreparedStatement *ps); | ||
654 | |||
655 | |||
656 | /* ******************** pq_exec.c functions ************** */ | ||
657 | |||
658 | |||
659 | /** | ||
660 | * Information needed to run a list of SQL statements using | ||
661 | * #GNUNET_PQ_exec_statements(). | ||
662 | */ | ||
663 | struct GNUNET_PQ_ExecuteStatement { | ||
664 | |||
665 | /** | ||
666 | * Actual SQL statement. | ||
667 | */ | ||
668 | const char *sql; | ||
669 | |||
670 | /** | ||
671 | * Should we ignore errors? | ||
672 | */ | ||
673 | int ignore_errors; | ||
674 | |||
675 | }; | ||
676 | |||
677 | |||
678 | /** | ||
679 | * Terminator for executable statement list. | ||
680 | */ | ||
681 | #define GNUNET_PQ_EXECUTE_STATEMENT_END { NULL, GNUNET_SYSERR } | ||
682 | |||
683 | |||
684 | /** | ||
685 | * Create a `struct GNUNET_PQ_ExecuteStatement` where errors are fatal. | ||
686 | * | ||
687 | * @param sql actual SQL statement | ||
688 | * @return initialized struct | ||
689 | */ | ||
690 | struct GNUNET_PQ_ExecuteStatement | ||
691 | GNUNET_PQ_make_execute (const char *sql); | ||
692 | |||
693 | |||
694 | /** | ||
695 | * Create a `struct GNUNET_PQ_ExecuteStatement` where errors should | ||
696 | * be tolerated. | ||
697 | * | ||
698 | * @param sql actual SQL statement | ||
699 | * @return initialized struct | ||
700 | */ | ||
701 | struct GNUNET_PQ_ExecuteStatement | ||
702 | GNUNET_PQ_make_try_execute (const char *sql); | ||
703 | |||
704 | |||
705 | /** | ||
706 | * Request execution of an array of statements @a es from Postgres. | ||
707 | * | ||
708 | * @param connection connection to execute the statements over | ||
709 | * @param es #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared | ||
710 | * statements. | ||
711 | * @return #GNUNET_OK on success (modulo statements where errors can be ignored) | ||
712 | * #GNUNET_SYSERR on error | ||
713 | */ | ||
714 | int | ||
715 | GNUNET_PQ_exec_statements (PGconn *connection, | ||
716 | const struct GNUNET_PQ_ExecuteStatement *es); | ||
717 | |||
718 | |||
719 | /* ******************** pq_connect.c functions ************** */ | ||
720 | |||
721 | |||
722 | /** | ||
723 | * Create a connection to the Postgres database using @a config_str | ||
724 | * for the configuration. Initialize logging via GNUnet's log | ||
725 | * routines and disable Postgres's logger. | ||
726 | * | ||
727 | * @param config_str configuration to use | ||
728 | * @return NULL on error | ||
729 | */ | ||
730 | PGconn * | ||
731 | GNUNET_PQ_connect (const char *config_str); | ||
732 | |||
733 | |||
734 | /** | ||
735 | * Connect to a postgres database using the configuration | ||
736 | * option "CONFIG" in @a section. | ||
737 | * | ||
738 | * @param cfg configuration | ||
739 | * @param section configuration section to use to get Postgres configuration options | ||
740 | * @return the postgres handle, NULL on error | ||
741 | */ | ||
742 | PGconn * | ||
743 | GNUNET_PQ_connect_with_cfg (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
744 | const char *section); | ||
745 | |||
746 | |||
747 | |||
455 | #endif /* GNUNET_PQ_LIB_H_ */ | 748 | #endif /* GNUNET_PQ_LIB_H_ */ |
456 | 749 | ||
457 | /* end of include/gnunet_pq_lib.h */ | 750 | /* end of include/gnunet_pq_lib.h */ |