• Main Page
  • Related Pages
  • Modules
  • Data Structures
  • Files
  • File List
  • Globals

sst/elements/genericProc/programs/libcprops/db.h

Go to the documentation of this file.
00001 #ifndef _CP_PERSISTENCE_H
00002 #define _CP_PERSISTENCE_H
00003 
00004 /**
00005  * @addtogroup cp_dbms
00006  */
00007 /** @{ */
00008 /**
00009  * @file
00010  * definitions for dbms abstraction api
00011  */
00012 
00013 
00014 #include "common.h"
00015 
00016 #include <stdarg.h>
00017 #ifdef TIME_WITH_SYS_TIME
00018 # include <sys/time.h>
00019 # include <time.h>
00020 #else
00021 # ifdef HAVE_SYS_TIME_H
00022 #  include <sys/time.h>
00023 # else
00024 #  include <time.h>
00025 # endif
00026 #endif
00027 
00028 #include "collection.h"
00029 #include "hashtable.h"
00030 #include "linked_list.h"
00031 #include "vector.h"
00032 #include "str.h"
00033 
00034 __BEGIN_DECLS
00035 
00036 /* ----------------------------------------------------------------------- */
00037 /*                                                                         */
00038 /*                       general framework declarations                    */
00039 /*                                                                         */
00040 /* ----------------------------------------------------------------------- */
00041 
00042 typedef CPROPS_DLL enum
00043 {
00044         CP_FIELD_TYPE_BOOLEAN,   //  0
00045         CP_FIELD_TYPE_CHAR,      //  1
00046         CP_FIELD_TYPE_SHORT,     //  2
00047         CP_FIELD_TYPE_INT,       //  3
00048         CP_FIELD_TYPE_LONG,      //  4
00049         CP_FIELD_TYPE_LONG_LONG, //  5
00050         CP_FIELD_TYPE_FLOAT,     //  6
00051         CP_FIELD_TYPE_DOUBLE,    //  7
00052         CP_FIELD_TYPE_VARCHAR,   //  8
00053         CP_FIELD_TYPE_BLOB,      //  9
00054         CP_FIELD_TYPE_DATE,      // 10
00055         CP_FIELD_TYPE_TIME,      // 11
00056         CP_FIELD_TYPE_TIMESTAMP  // 12
00057 } cp_field_type;
00058 
00059 /** initialize persistence framework */
00060 CPROPS_DLL
00061 int cp_db_init();
00062 /** register a dbms driver with the persistence framework */
00063 CPROPS_DLL
00064 int cp_db_register_dbms(char *dbms_name, void (*shutdown_call)());
00065 /** shutdown dbms framework */
00066 CPROPS_DLL
00067 int cp_db_shutdown();
00068 
00069 
00070 /* ----------------------------------------------------------------------- */
00071 /*                                                                         */
00072 /*                        cp_timestampz declarations                       */
00073 /*                                                                         */
00074 /* ----------------------------------------------------------------------- */
00075 
00076 typedef CPROPS_DLL struct _cp_timestampz
00077 {
00078         struct timeval tm;
00079         int tz_minuteswest;
00080 } cp_timestampz;
00081 
00082 CPROPS_DLL
00083 cp_timestampz *cp_timestampz_create(struct timeval *tm, int minuteswest);
00084 CPROPS_DLL
00085 cp_timestampz *
00086         cp_timestampz_create_prm(int sec_since_epoch, int microsec, int minwest);
00087 CPROPS_DLL
00088 void cp_timestampz_destroy(cp_timestampz *tm);
00089 CPROPS_DLL
00090 struct tm *cp_timestampz_localtime(cp_timestampz *tm, struct tm *res);
00091 
00092 
00093 /* ----------------------------------------------------------------------- */
00094 /*                                                                         */
00095 /*                    connection parameter declarations                    */
00096 /*                                                                         */
00097 /* ----------------------------------------------------------------------- */
00098 
00099 typedef CPROPS_DLL struct _cp_db_connection_parameters 
00100 {
00101         void *impl;
00102         cp_destructor_fn impl_dtr;
00103 } cp_db_connection_parameters; /**< wrapper for dbms specific connection parameter 
00104                                     descriptor */
00105 
00106 /** destroy connection parameter descriptor */
00107 CPROPS_DLL
00108 void cp_db_connection_parameters_destroy(cp_db_connection_parameters *prm);
00109 
00110 
00111 /* ----------------------------------------------------------------------- */
00112 /*                                                                         */
00113 /*                          connection declarations                        */
00114 /*                                                                         */
00115 /* ----------------------------------------------------------------------- */
00116 
00117 CPROPS_DLL struct _cp_data_source;
00118 
00119 typedef CPROPS_DLL struct _cp_db_connection
00120 {
00121         struct _cp_data_source *data_source;    /**< data source                     */
00122         void *connection;                                               /**< impl. connection type  */
00123         void *store;                                                    /**< impl. specific storage */
00124         short autofetch_query_metadata;
00125         short read_result_set_at_once;
00126         int fetch_size;
00127         int autocommit;
00128 } cp_db_connection; /**< wrapper for dbms specific connection structure */
00129 
00130 
00131 /* ----------------------------------------------------------------------- */
00132 /*                                                                         */
00133 /*                     prepared statement declarations                     */
00134 /*                                                                         */
00135 /* ----------------------------------------------------------------------- */
00136 
00137 typedef CPROPS_DLL struct _cp_db_statement
00138 {
00139         cp_db_connection *connection;
00140         int prm_count;
00141         cp_field_type *types;
00142         void *source;
00143         void *store;
00144         short binary; /**< set to 1 to request results in binary format */
00145 } cp_db_statement;
00146 
00147 /** 
00148  * convenience function for driver implementations - do not call directly. to
00149  * create a prepared statement use cp_db_connection_prepare_statement.
00150  */
00151 CPROPS_DLL
00152 cp_db_statement *cp_db_statement_instantiate(cp_db_connection *connection,
00153                                                                                      int prm_count, 
00154                                                      cp_field_type *types, 
00155                                                                                      void *source);
00156 
00157 /** set binary = 1 to request results in binary format */
00158 CPROPS_DLL
00159 void cp_db_statement_set_binary(cp_db_statement *stmt, int binary);
00160 
00161 /** 
00162  * internal function - do not call directly. to release a prepared statement 
00163  * use cp_db_connection_close_statement.
00164  */
00165 CPROPS_DLL
00166 void cp_db_statement_destroy(cp_db_statement *statement);
00167 
00168 /* ----------------------------------------------------------------------- */
00169 /*                                                                         */
00170 /*                         result set declarations                         */
00171 /*                                                                         */
00172 /* ----------------------------------------------------------------------- */
00173 
00174 typedef CPROPS_DLL struct _cp_result_set
00175 {
00176         short fetch_complete;
00177         cp_db_connection *connection;
00178         void *source;                                   /**< implementation result type      */
00179         void *store;                                    /**< implementation specific storage */
00180         cp_vector *field_headers;
00181         cp_vector *field_types;
00182         int position; 
00183         int row_count;
00184         int field_count;
00185         cp_list *results;
00186         short dispose;
00187         cp_list *dispose_list;
00188         short binary;
00189 } cp_result_set; /**< holder for SELECT query results */
00190 
00191 /** get a vector with field headers */
00192 CPROPS_DLL
00193 cp_vector *cp_result_set_get_headers(cp_result_set *result_set);
00194 /** get a vector with field type codes - see cp_field_type */
00195 CPROPS_DLL
00196 cp_vector *cp_result_set_get_field_types(cp_result_set *result_set);
00197 /** get field count */
00198 CPROPS_DLL
00199 int cp_result_set_field_count(cp_result_set *result_set);
00200 /** get number of rows */
00201 CPROPS_DLL
00202 int cp_result_set_row_count(cp_result_set *result_set);
00203 /** get a vector with field headers */
00204 CPROPS_DLL
00205 char *cp_result_set_get_header(cp_result_set *result_set, int column);
00206 /** get the type of a column */
00207 CPROPS_DLL
00208 cp_field_type cp_result_set_get_field_type(cp_result_set *rs, int column);
00209 /** set auto disposal */
00210 CPROPS_DLL
00211 void cp_result_set_autodispose(cp_result_set *rs, int mode);
00212 /** get next row */
00213 CPROPS_DLL
00214 cp_vector *cp_result_set_next(cp_result_set *result_set);
00215 /** close result set */
00216 CPROPS_DLL
00217 void cp_result_set_destroy(cp_result_set *result_set);
00218 /** free a row from a result set */
00219 CPROPS_DLL
00220 void cp_result_set_release_row(cp_result_set *result_set, cp_vector *row);
00221 /** check whether rows are in binary format */
00222 CPROPS_DLL
00223 int cp_result_set_is_binary(cp_result_set *result_set);
00224 
00225 /** perform a SELECT query */
00226 CPROPS_DLL
00227 cp_result_set *
00228         cp_db_connection_select(cp_db_connection *connection, char *query);
00229 /** perform an INSERT, UPDATE or DELETE query */
00230 CPROPS_DLL
00231 int cp_db_connection_update(cp_db_connection *connection, char *query);
00232 /** close connection */
00233 CPROPS_DLL
00234 int cp_db_connection_close(cp_db_connection *connection);
00235 /** deallocate connection wrapper */
00236 CPROPS_DLL
00237 void cp_db_connection_destroy(cp_db_connection *connection);
00238 
00239 /** auto fetch metadata */
00240 CPROPS_DLL
00241 void 
00242         cp_db_connection_set_fetch_metadata(cp_db_connection *connection, int mode);
00243 /** fetch complete result set immediately */
00244 CPROPS_DLL
00245 void cp_db_connection_set_read_result_set_at_once(cp_db_connection *connection, 
00246                                                                                                   int mode);
00247 /** number of rows to fetch at a time */
00248 CPROPS_DLL
00249 void cp_db_connection_set_fetch_size(cp_db_connection *connection, int fetch_size);
00250 /** escape a string for use in an SQL query on this connection */
00251 CPROPS_DLL
00252 char *cp_db_connection_escape_string(cp_db_connection *connection, 
00253                                              char *src,
00254                                                                      int len);
00255 /** escape binary data for use in an SQL query on this connection */
00256 CPROPS_DLL
00257 char *cp_db_connection_escape_binary(cp_db_connection *connection, 
00258                                              char *src, 
00259                                                                      int src_len, 
00260                                                                      int *res_len);
00261 /** unescape binary data returned by an SQL query on this connection */
00262 CPROPS_DLL
00263 cp_string *cp_db_connection_unescape_binary(cp_db_connection *connection,
00264                                                                                         char *src);
00265 /** create a prepared statement for use with a connection */
00266 CPROPS_DLL
00267 cp_db_statement *
00268         cp_db_connection_prepare_statement(cp_db_connection *connection,
00269                                                                            int prm_count,
00270                                                                            cp_field_type *prm_types, 
00271                                                                            char *query);
00272 /** execute a prepared statement */
00273 CPROPS_DLL
00274 int cp_db_connection_execute_statement(cp_db_connection *connection,
00275                                                cp_db_statement *statement, 
00276                                                                            cp_vector *prm,
00277                                                                            cp_result_set **results);
00278 /** execute a prepared statement */
00279 CPROPS_DLL
00280 int cp_db_connection_execute_statement_args(cp_db_connection *connection,
00281                                                     cp_db_statement *statement, 
00282                                                                                 cp_result_set **results, ...);
00283 /** release a statement */
00284 CPROPS_DLL
00285 void cp_db_connection_close_statement(cp_db_connection *connection, 
00286                                                                           cp_db_statement *statement);
00287 /** set autocommit state */
00288 CPROPS_DLL
00289 void cp_db_connection_set_autocommit(cp_db_connection *conn, int state);
00290 /** perform a commit */
00291 CPROPS_DLL
00292 int cp_db_connection_commit(cp_db_connection *conn);
00293 /** perform a rollback */
00294 CPROPS_DLL
00295 int cp_db_connection_rollback(cp_db_connection *conn);
00296 
00297 
00298 /* ----------------------------------------------------------------------- */
00299 /*                                                                         */
00300 /*                          db_actions declarations                        */
00301 /*                                                                         */
00302 /* ----------------------------------------------------------------------- */
00303 
00304 /** 
00305  * implementations must define a function to open connections 
00306  */
00307 typedef cp_db_connection *(*cp_db_open_fn)(struct _cp_data_source *);
00308 
00309 
00310 /** 
00311  * implementations must define a function to perform SELECT queries 
00312  */
00313 typedef cp_result_set *(*cp_db_select_fn)(cp_db_connection *conn, char *query);
00314 
00315 /** 
00316  * implementations may define a function to retrieve metadata for a query 
00317  * result 
00318  */
00319 typedef int (*cp_db_fetch_metadata_fn)(cp_result_set *rs);
00320 
00321 /** 
00322  * implementations may define a function to retrieve result rows by chunk 
00323  */
00324 typedef int (*cp_db_fetch_next_fn)(cp_result_set *rs);
00325 
00326 /** 
00327  * implementations may define a function to close an open result set 
00328  */
00329 typedef int (*cp_db_release_result_set_fn)(cp_result_set *rs);
00330 
00331 /** 
00332  * implemetations must define a function to perform INSERT, UPDATE or DELETE 
00333  * queries 
00334  */
00335 typedef int (*cp_db_update_fn)(cp_db_connection *conn, char *query);
00336 
00337 /** 
00338  * implemetations must define a function to close database connections 
00339  */
00340 typedef int (*cp_db_close_fn)(cp_db_connection *conn);
00341 
00342 /** 
00343  * implementations may define a function to escape strings for use in SQL queries 
00344  */
00345 typedef char *(*cp_db_escape_string_fn)(cp_db_connection *conn, char *src, int len);
00346 
00347 /** 
00348  * implementations may define a function to escape binary data for use in SQL 
00349  * queries 
00350  */
00351 typedef char *(*cp_db_escape_binary_fn)(cp_db_connection *conn, char *src, 
00352                                                 int src_len, int *res_len);
00353 /** 
00354  * implementation may define a function to unescape binary data returned by
00355  * an SQL query
00356  */
00357 typedef cp_string *(*cp_db_unescape_binary_fn)(cp_db_connection *conn, 
00358                                                                                            char *src);
00359 /** 
00360  * implementations may define a function to create a prepared statement 
00361  */
00362 typedef cp_db_statement *
00363         (*cp_db_prepare_statement_fn)(cp_db_connection *conn, 
00364                                                                   int prm_count,
00365                                                                   cp_field_type *prm_types, 
00366                                                                   char *query);
00367 
00368 /** 
00369  * implementations may define a function to execute a prepared statement 
00370  */
00371 typedef int (*cp_db_execute_statement_fn)(cp_db_connection *conn, 
00372                                                                                   cp_db_statement *stmt, 
00373                                                                                   cp_result_set **results, 
00374                                                                                   int *lengths,
00375                                                                                   void **prm);
00376 /**
00377  * implementations may define a function to release implementation specific
00378  * allocations made to instantiate a prepared statement
00379  */
00380 typedef void (*cp_db_release_statement_fn)(cp_db_statement *stmt);
00381 
00382 /** 
00383  * implementations may define a function to set autocommit mode 
00384  */
00385 typedef void (*cp_db_set_autocommit_fn)(cp_db_connection *conn, int state);
00386 
00387 /** 
00388  * implementations may define a function to perform a commit 
00389  */
00390 typedef int (*cp_db_commit_fn)(cp_db_connection *conn);
00391 
00392 /** 
00393  * implementations may define a function to perform a rollback 
00394  */
00395 typedef int (*cp_db_rollback_fn)(cp_db_connection *conn);
00396 
00397 typedef CPROPS_DLL struct _cp_db_actions
00398 {
00399         int                                   dbms;
00400         char                                 *dbms_lit;
00401         cp_db_open_fn                         open;
00402         cp_db_select_fn                       select;
00403         cp_db_fetch_next_fn                   fetch_next;
00404         cp_db_fetch_metadata_fn       fetch_metadata;
00405         cp_db_release_result_set_fn   release_result_set;
00406         cp_db_update_fn                       update;
00407         cp_db_close_fn                        close;
00408         cp_db_escape_string_fn        escape_string;
00409         cp_db_escape_binary_fn        escape_binary;
00410         cp_db_unescape_binary_fn      unescape_binary;
00411         cp_db_prepare_statement_fn    prepare_statement;
00412         cp_db_execute_statement_fn    execute_statement;
00413         cp_db_release_statement_fn    release_statement;
00414         cp_db_set_autocommit_fn       set_autocommit;
00415         cp_db_commit_fn               commit;
00416         cp_db_rollback_fn             rollback;
00417 } cp_db_actions; /**< holder for implementation specific dbms access functions */
00418 
00419 /** convenience method to create a new implementation method holder */
00420 CPROPS_DLL
00421 cp_db_actions *
00422         cp_db_actions_create(int dbms,
00423                                      char *dbms_lit,
00424                                          cp_db_open_fn open,
00425                                                  cp_db_select_fn select,
00426                                                  cp_db_fetch_metadata_fn fetch_metadata,
00427                                                  cp_db_fetch_next_fn fetch_next,
00428                                                  cp_db_release_result_set_fn release_result_set,
00429                                                  cp_db_update_fn update,
00430                                                  cp_db_close_fn close,
00431                                                  cp_db_escape_string_fn escape_string,
00432                                                  cp_db_escape_binary_fn escape_binary,
00433                                                  cp_db_unescape_binary_fn unescape_binary,
00434                                                  cp_db_prepare_statement_fn prepare_statement,
00435                                                  cp_db_execute_statement_fn execute_statement,
00436                                                  cp_db_release_statement_fn release_statement,
00437                                                  cp_db_set_autocommit_fn set_autocommit,
00438                                                  cp_db_commit_fn commit,
00439                                                  cp_db_rollback_fn rollback);
00440 /** deallocate an implementation method holder */
00441 CPROPS_DLL
00442 void cp_db_actions_destroy(cp_db_actions *actions);
00443 
00444 
00445 /* ----------------------------------------------------------------------- */
00446 /*                                                                         */
00447 /*                      driver descriptor declarations                     */
00448 /*                                                                         */
00449 /* ----------------------------------------------------------------------- */
00450 
00451 typedef struct _cp_data_source *
00452         (*cp_db_get_data_source_fn)(char *host, int port, char *user, 
00453                                                                 char *passwd, char *dbname);
00454 
00455 typedef struct _cp_data_source *
00456         (*cp_db_get_data_source_prm_fn)(char *host, int port, char *user, 
00457                                                                         char *passwd, char *dbname, 
00458                                                                         cp_hashtable *prm);
00459 
00460 typedef CPROPS_DLL struct _cp_dbms_driver_descriptor
00461 {
00462         void *lib;
00463         cp_db_get_data_source_fn get_data_source;
00464         cp_db_get_data_source_prm_fn get_data_source_prm;
00465 } cp_dbms_driver_descriptor;
00466 
00467 
00468 /* ----------------------------------------------------------------------- */
00469 /*                                                                         */
00470 /*                         data source declarations                        */
00471 /*                                                                         */
00472 /* ----------------------------------------------------------------------- */
00473 
00474 typedef CPROPS_DLL struct _cp_data_source
00475 {
00476         cp_db_connection_parameters *prm;
00477         cp_db_actions               *act;
00478 } cp_data_source; /**< dbms driver abstraction */
00479 
00480 #if defined(HAVE_DLFCN_H) || defined(_WINDOWS)
00481 CPROPS_DLL
00482 int cp_dbms_load_driver(char *name);
00483 #endif /* HAVE_DLFCN_H */
00484 
00485 CPROPS_DLL
00486 cp_data_source *
00487         cp_dbms_get_data_source(char *driver, char *host, int port, char *user,
00488                         char *passwd, char *dbname);
00489 
00490 CPROPS_DLL
00491 cp_data_source *
00492         cp_dbms_get_data_source_prm(char *driver, char *host, int port, 
00493                         char *user, char *passwd, char *dbname, cp_hashtable *prm);
00494 
00495 /** deallocate a cp_data_source structure */
00496 CPROPS_DLL
00497 void cp_data_source_destroy(cp_data_source *data_source);
00498 /** open a connection with the set connection parameters */
00499 CPROPS_DLL
00500 cp_db_connection *
00501         cp_data_source_get_connection(cp_data_source *data_source); 
00502 
00503 
00504 /* ----------------------------------------------------------------------- */
00505 /*                                                                         */
00506 /*                       connection pool declarations                      */
00507 /*                                                                         */
00508 /* ----------------------------------------------------------------------- */
00509 
00510 typedef CPROPS_DLL struct _cp_db_connection_pool
00511 {
00512         int running;
00513         int block;
00514 
00515         int min_size;
00516         int max_size;
00517         int size;
00518         cp_data_source *data_source;
00519         cp_list *free_list;
00520 
00521         cp_mutex *lock;
00522         cp_cond  *cond;
00523 } cp_db_connection_pool; /**< connection pool structure */
00524 
00525 /** create a new connection pool */
00526 CPROPS_DLL
00527 cp_db_connection_pool *
00528         cp_db_connection_pool_create(cp_data_source *data_source, 
00529                                                                  int min_size, 
00530                                                                  int max_size, 
00531                                                                  int initial_size);
00532 
00533 /** shut down a connection pool */
00534 CPROPS_DLL
00535 int cp_db_connection_pool_shutdown(cp_db_connection_pool *pool);
00536 /** deallocate a connection pool object */
00537 CPROPS_DLL
00538 void cp_db_connection_pool_destroy(cp_db_connection_pool *pool);
00539 
00540 /** 
00541  * set connection pool to block until a connection is available when 
00542  * retrieving connections if no connection is available
00543  */
00544 CPROPS_DLL
00545 void cp_db_connection_pool_set_blocking(cp_db_connection_pool *pool, int block);
00546 
00547 /** retrieve a connection from a connection pool */
00548 CPROPS_DLL
00549 cp_db_connection *
00550         cp_db_connection_pool_get_connection(cp_db_connection_pool *pool);
00551 
00552 /** return a connection to the pool */
00553 CPROPS_DLL
00554 void cp_db_connection_pool_release_connection(cp_db_connection_pool *pool, 
00555                                                                                           cp_db_connection *connection);
00556 
00557 __END_DECLS
00558 
00559 /** @} */
00560 
00561 #endif

Generated on Fri Oct 22 2010 11:02:22 for SST by  doxygen 1.7.1