aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_pq_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_pq_lib.h')
-rw-r--r--src/include/gnunet_pq_lib.h142
1 files changed, 99 insertions, 43 deletions
diff --git a/src/include/gnunet_pq_lib.h b/src/include/gnunet_pq_lib.h
index 6c576c8ab..2aea77b7f 100644
--- a/src/include/gnunet_pq_lib.h
+++ b/src/include/gnunet_pq_lib.h
@@ -46,15 +46,16 @@
46 * @param scratch_length number of entries left in @a scratch 46 * @param scratch_length number of entries left in @a scratch
47 * @return -1 on error, number of offsets used in @a scratch otherwise 47 * @return -1 on error, number of offsets used in @a scratch otherwise
48 */ 48 */
49typedef int (*GNUNET_PQ_QueryConverter) (void *cls, 49typedef int
50 const void *data, 50(*GNUNET_PQ_QueryConverter) (void *cls,
51 size_t data_len, 51 const void *data,
52 void *param_values[], 52 size_t data_len,
53 int param_lengths[], 53 void *param_values[],
54 int param_formats[], 54 int param_lengths[],
55 unsigned int param_length, 55 int param_formats[],
56 void *scratch[], 56 unsigned int param_length,
57 unsigned int scratch_length); 57 void *scratch[],
58 unsigned int scratch_length);
58 59
59 60
60/** 61/**
@@ -214,12 +215,13 @@ GNUNET_PQ_query_param_uint64 (const uint64_t *x);
214 * #GNUNET_YES if all results could be extracted 215 * #GNUNET_YES if all results could be extracted
215 * #GNUNET_SYSERR if a result was invalid (non-existing field or NULL) 216 * #GNUNET_SYSERR if a result was invalid (non-existing field or NULL)
216 */ 217 */
217typedef int (*GNUNET_PQ_ResultConverter) (void *cls, 218typedef int
218 PGresult *result, 219(*GNUNET_PQ_ResultConverter) (void *cls,
219 int row, 220 PGresult *result,
220 const char *fname, 221 int row,
221 size_t *dst_size, 222 const char *fname,
222 void *dst); 223 size_t *dst_size,
224 void *dst);
223 225
224 226
225/** 227/**
@@ -229,7 +231,9 @@ typedef int (*GNUNET_PQ_ResultConverter) (void *cls,
229 * @param cls closure 231 * @param cls closure
230 * @param rd result data to clean up 232 * @param rd result data to clean up
231 */ 233 */
232typedef void (*GNUNET_PQ_ResultCleanup) (void *cls, void *rd); 234typedef void
235(*GNUNET_PQ_ResultCleanup) (void *cls,
236 void *rd);
233 237
234 238
235/** 239/**
@@ -420,16 +424,22 @@ GNUNET_PQ_result_spec_uint64 (const char *name, uint64_t *u64);
420/* ************************* pq.c functions ************************ */ 424/* ************************* pq.c functions ************************ */
421 425
422/** 426/**
427 * Postgres context.
428 */
429struct GNUNET_PQ_Context;
430
431
432/**
423 * Execute a prepared statement. 433 * Execute a prepared statement.
424 * 434 *
425 * @param db_conn database connection 435 * @param db database context
426 * @param name name of the prepared statement 436 * @param name name of the prepared statement
427 * @param params parameters to the statement 437 * @param params parameters to the statement
428 * @return postgres result 438 * @return postgres result
429 * @deprecated (should become an internal API) 439 * @deprecated (should become an internal API)
430 */ 440 */
431PGresult * 441PGresult *
432GNUNET_PQ_exec_prepared (PGconn *db_conn, 442GNUNET_PQ_exec_prepared (struct GNUNET_PQ_Context *db,
433 const char *name, 443 const char *name,
434 const struct GNUNET_PQ_QueryParam *params); 444 const struct GNUNET_PQ_QueryParam *params);
435 445
@@ -468,7 +478,7 @@ GNUNET_PQ_cleanup_result (struct GNUNET_PQ_ResultSpec *rs);
468 * Check the @a result's error code to see what happened. 478 * Check the @a result's error code to see what happened.
469 * Also logs errors. 479 * Also logs errors.
470 * 480 *
471 * @param connection connection to execute the statement in 481 * @param db database to execute the statement in
472 * @param statement_name name of the statement that created @a result 482 * @param statement_name name of the statement that created @a result
473 * @param result result to check 483 * @param result result to check
474 * @return status code from the result, mapping PQ status 484 * @return status code from the result, mapping PQ status
@@ -478,7 +488,7 @@ GNUNET_PQ_cleanup_result (struct GNUNET_PQ_ResultSpec *rs);
478 * @deprecated (low level, let's see if we can do with just the high-level functions) 488 * @deprecated (low level, let's see if we can do with just the high-level functions)
479 */ 489 */
480enum GNUNET_DB_QueryStatus 490enum GNUNET_DB_QueryStatus
481GNUNET_PQ_eval_result (PGconn *connection, 491GNUNET_PQ_eval_result (struct GNUNET_PQ_Context *db,
482 const char *statement_name, 492 const char *statement_name,
483 PGresult *result); 493 PGresult *result);
484 494
@@ -488,7 +498,7 @@ GNUNET_PQ_eval_result (PGconn *connection,
488 * statement in @a connnection using the given @a params. Returns the 498 * statement in @a connnection using the given @a params. Returns the
489 * resulting session state. 499 * resulting session state.
490 * 500 *
491 * @param connection connection to execute the statement in 501 * @param db database to execute the statement with
492 * @param statement_name name of the statement 502 * @param statement_name name of the statement
493 * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated) 503 * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated)
494 * @return status code from the result, mapping PQ status 504 * @return status code from the result, mapping PQ status
@@ -500,7 +510,7 @@ GNUNET_PQ_eval_result (PGconn *connection,
500 * zero; if INSERT was successful, we return one. 510 * zero; if INSERT was successful, we return one.
501 */ 511 */
502enum GNUNET_DB_QueryStatus 512enum GNUNET_DB_QueryStatus
503GNUNET_PQ_eval_prepared_non_select (PGconn *connection, 513GNUNET_PQ_eval_prepared_non_select (struct GNUNET_PQ_Context *db,
504 const char *statement_name, 514 const char *statement_name,
505 const struct GNUNET_PQ_QueryParam *params); 515 const struct GNUNET_PQ_QueryParam *params);
506 516
@@ -513,9 +523,10 @@ GNUNET_PQ_eval_prepared_non_select (PGconn *connection,
513 * @param result the postgres result 523 * @param result the postgres result
514 * @param num_result the number of results in @a result 524 * @param num_result the number of results in @a result
515 */ 525 */
516typedef void (*GNUNET_PQ_PostgresResultHandler) (void *cls, 526typedef void
517 PGresult *result, 527(*GNUNET_PQ_PostgresResultHandler) (void *cls,
518 unsigned int num_results); 528 PGresult *result,
529 unsigned int num_results);
519 530
520 531
521/** 532/**
@@ -525,7 +536,7 @@ typedef void (*GNUNET_PQ_PostgresResultHandler) (void *cls,
525 * status including the number of results given to @a rh (possibly zero). 536 * status including the number of results given to @a rh (possibly zero).
526 * @a rh will not have been called if the return value is negative. 537 * @a rh will not have been called if the return value is negative.
527 * 538 *
528 * @param connection connection to execute the statement in 539 * @param db database to execute the statement with
529 * @param statement_name name of the statement 540 * @param statement_name name of the statement
530 * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated) 541 * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated)
531 * @param rh function to call with the result set, NULL to ignore 542 * @param rh function to call with the result set, NULL to ignore
@@ -534,7 +545,7 @@ typedef void (*GNUNET_PQ_PostgresResultHandler) (void *cls,
534 * codes to `enum GNUNET_DB_QueryStatus`. 545 * codes to `enum GNUNET_DB_QueryStatus`.
535 */ 546 */
536enum GNUNET_DB_QueryStatus 547enum GNUNET_DB_QueryStatus
537GNUNET_PQ_eval_prepared_multi_select (PGconn *connection, 548GNUNET_PQ_eval_prepared_multi_select (struct GNUNET_PQ_Context *db,
538 const char *statement_name, 549 const char *statement_name,
539 const struct GNUNET_PQ_QueryParam *params, 550 const struct GNUNET_PQ_QueryParam *params,
540 GNUNET_PQ_PostgresResultHandler rh, 551 GNUNET_PQ_PostgresResultHandler rh,
@@ -549,7 +560,7 @@ GNUNET_PQ_eval_prepared_multi_select (PGconn *connection,
549 * value was #GNUNET_DB_STATUS_SUCCESS_ONE_RESULT. Returns the 560 * value was #GNUNET_DB_STATUS_SUCCESS_ONE_RESULT. Returns the
550 * resulting session status. 561 * resulting session status.
551 * 562 *
552 * @param connection connection to execute the statement in 563 * @param db database to execute the statement with
553 * @param statement_name name of the statement 564 * @param statement_name name of the statement
554 * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated) 565 * @param params parameters to give to the statement (#GNUNET_PQ_query_param_end-terminated)
555 * @param[in,out] rs result specification to use for storing the result of the query 566 * @param[in,out] rs result specification to use for storing the result of the query
@@ -557,11 +568,11 @@ GNUNET_PQ_eval_prepared_multi_select (PGconn *connection,
557 * codes to `enum GNUNET_DB_QueryStatus`. 568 * codes to `enum GNUNET_DB_QueryStatus`.
558 */ 569 */
559enum GNUNET_DB_QueryStatus 570enum GNUNET_DB_QueryStatus
560GNUNET_PQ_eval_prepared_singleton_select ( 571GNUNET_PQ_eval_prepared_singleton_select (struct GNUNET_PQ_Context *db,
561 PGconn *connection, 572 const char *statement_name,
562 const char *statement_name, 573 const struct
563 const struct GNUNET_PQ_QueryParam *params, 574 GNUNET_PQ_QueryParam *params,
564 struct GNUNET_PQ_ResultSpec *rs); 575 struct GNUNET_PQ_ResultSpec *rs);
565 576
566 577
567/* ******************** pq_prepare.c functions ************** */ 578/* ******************** pq_prepare.c functions ************** */
@@ -587,6 +598,7 @@ struct GNUNET_PQ_PreparedStatement
587 * Number of arguments included in @e sql. 598 * Number of arguments included in @e sql.
588 */ 599 */
589 unsigned int num_arguments; 600 unsigned int num_arguments;
601
590}; 602};
591 603
592 604
@@ -616,14 +628,14 @@ GNUNET_PQ_make_prepare (const char *name,
616/** 628/**
617 * Request creation of prepared statements @a ps from Postgres. 629 * Request creation of prepared statements @a ps from Postgres.
618 * 630 *
619 * @param connection connection to prepare the statements for 631 * @param db database to prepare the statements for
620 * @param ps #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared 632 * @param ps #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared
621 * statements. 633 * statements.
622 * @return #GNUNET_OK on success, 634 * @return #GNUNET_OK on success,
623 * #GNUNET_SYSERR on error 635 * #GNUNET_SYSERR on error
624 */ 636 */
625int 637int
626GNUNET_PQ_prepare_statements (PGconn *connection, 638GNUNET_PQ_prepare_statements (struct GNUNET_PQ_Context *db,
627 const struct GNUNET_PQ_PreparedStatement *ps); 639 const struct GNUNET_PQ_PreparedStatement *ps);
628 640
629 641
@@ -681,14 +693,14 @@ GNUNET_PQ_make_try_execute (const char *sql);
681/** 693/**
682 * Request execution of an array of statements @a es from Postgres. 694 * Request execution of an array of statements @a es from Postgres.
683 * 695 *
684 * @param connection connection to execute the statements over 696 * @param pq database to execute the statements in
685 * @param es #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared 697 * @param es #GNUNET_PQ_PREPARED_STATEMENT_END-terminated array of prepared
686 * statements. 698 * statements.
687 * @return #GNUNET_OK on success (modulo statements where errors can be ignored) 699 * @return #GNUNET_OK on success (modulo statements where errors can be ignored)
688 * #GNUNET_SYSERR on error 700 * #GNUNET_SYSERR on error
689 */ 701 */
690int 702int
691GNUNET_PQ_exec_statements (PGconn *connection, 703GNUNET_PQ_exec_statements (struct GNUNET_PQ_Context *db,
692 const struct GNUNET_PQ_ExecuteStatement *es); 704 const struct GNUNET_PQ_ExecuteStatement *es);
693 705
694 706
@@ -698,26 +710,70 @@ GNUNET_PQ_exec_statements (PGconn *connection,
698/** 710/**
699 * Create a connection to the Postgres database using @a config_str 711 * Create a connection to the Postgres database using @a config_str
700 * for the configuration. Initialize logging via GNUnet's log 712 * for the configuration. Initialize logging via GNUnet's log
701 * routines and disable Postgres's logger. 713 * routines and disable Postgres's logger. Also ensures that the
714 * statements in @a es are executed whenever we (re)connect to the
715 * database, and that the prepared statements in @a ps are "ready".
716 * If statements in @es fail that were created with
717 * #GNUNET_PQ_make_execute(), then the entire operation fails.
702 * 718 *
703 * @param config_str configuration to use 719 * @param config_str configuration to use
720 * @param es #GNUNET_PQ_PREPARED_STATEMENT_END-terminated
721 * array of statements to execute upon EACH connection, can be NULL
722 * @param ps array of prepared statements to prepare, can be NULL
704 * @return NULL on error 723 * @return NULL on error
705 */ 724 */
706PGconn * 725struct GNUNET_PQ_Context *
707GNUNET_PQ_connect (const char *config_str); 726GNUNET_PQ_connect (const char *config_str,
727 const struct GNUNET_PQ_ExecuteStatement *es,
728 const struct GNUNET_PQ_PreparedStatement *ps);
708 729
709 730
710/** 731/**
711 * Connect to a postgres database using the configuration 732 * Connect to a postgres database using the configuration
712 * option "CONFIG" in @a section. 733 * option "CONFIG" in @a section. Also ensures that the
734 * statements in @a es are executed whenever we (re)connect to the
735 * database, and that the prepared statements in @a ps are "ready".
713 * 736 *
714 * @param cfg configuration 737 * @param cfg configuration
715 * @param section configuration section to use to get Postgres configuration options 738 * @param section configuration section to use to get Postgres configuration options
739 * @param es #GNUNET_PQ_PREPARED_STATEMENT_END-terminated
740 * array of statements to execute upon EACH connection, can be NULL
741 * @param ps array of prepared statements to prepare, can be NULL
716 * @return the postgres handle, NULL on error 742 * @return the postgres handle, NULL on error
717 */ 743 */
718PGconn * 744struct GNUNET_PQ_Context *
719GNUNET_PQ_connect_with_cfg (const struct GNUNET_CONFIGURATION_Handle *cfg, 745GNUNET_PQ_connect_with_cfg (const struct GNUNET_CONFIGURATION_Handle *cfg,
720 const char *section); 746 const char *section,
747 const struct GNUNET_PQ_ExecuteStatement *es,
748 const struct GNUNET_PQ_PreparedStatement *ps);
749
750
751/**
752 * Reinitialize the database @a db if the connection is down.
753 *
754 * @param db database connection to reinitialize
755 */
756void
757GNUNET_PQ_reconnect_if_down (struct GNUNET_PQ_Context *db);
758
759
760/**
761 * Reinitialize the database @a db.
762 *
763 * @param db database connection to reinitialize
764 */
765void
766GNUNET_PQ_reconnect (struct GNUNET_PQ_Context *db);
767
768
769/**
770 * Disconnect from the database, destroying the prepared statements
771 * and releasing other associated resources.
772 *
773 * @param db database handle to disconnect (will be free'd)
774 */
775void
776GNUNET_PQ_disconnect (struct GNUNET_PQ_Context *db);
721 777
722 778
723#endif /* GNUNET_PQ_LIB_H_ */ 779#endif /* GNUNET_PQ_LIB_H_ */