cprops: db.h Source File

00001 #ifndef _CP_PERSISTENCE_H
00002 #define _CP_PERSISTENCE_H
00003 
00014 #include "common.h"
00015 
00016 #include <stdarg.h>
00017 #ifdef CP_HAS_SYS_TIME_H
00018 #include <sys/time.h>
00019 #endif /* CP_HAS_SYS_TIME_H */
00020 
00021 #include "collection.h"
00022 #include "hashtable.h"
00023 #include "linked_list.h"
00024 #include "vector.h"
00025 #include "str.h"
00026 
00027 __BEGIN_DECLS
00028 
00029 /* ----------------------------------------------------------------------- */
00030 /*                                                                         */
00031 /*                       general framework declarations                    */
00032 /*                                                                         */
00033 /* ----------------------------------------------------------------------- */
00034 
00035 typedef CPROPS_DLL enum
00036 {
00037     CP_FIELD_TYPE_BOOLEAN,   //  0
00038     CP_FIELD_TYPE_CHAR,      //  1
00039     CP_FIELD_TYPE_SHORT,     //  2
00040     CP_FIELD_TYPE_INT,       //  3
00041     CP_FIELD_TYPE_LONG,      //  4
00042     CP_FIELD_TYPE_LONG_LONG, //  5
00043     CP_FIELD_TYPE_FLOAT,     //  6
00044     CP_FIELD_TYPE_DOUBLE,    //  7
00045     CP_FIELD_TYPE_VARCHAR,   //  8
00046     CP_FIELD_TYPE_BLOB,      //  9
00047     CP_FIELD_TYPE_DATE,      // 10
00048     CP_FIELD_TYPE_TIME,      // 11
00049     CP_FIELD_TYPE_TIMESTAMP  // 12
00050 } cp_field_type;
00051 
00053 CPROPS_DLL
00054 int cp_db_init();
00056 CPROPS_DLL
00057 int cp_db_register_dbms(char *dbms_name, void (*shutdown_call)());
00059 CPROPS_DLL
00060 int cp_db_shutdown();
00061 
00062 
00063 /* ----------------------------------------------------------------------- */
00064 /*                                                                         */
00065 /*                        cp_timestampz declarations                       */
00066 /*                                                                         */
00067 /* ----------------------------------------------------------------------- */
00068 
00069 typedef CPROPS_DLL struct _cp_timestampz
00070 {
00071     struct timeval tm;
00072     int tz_minuteswest;
00073 } cp_timestampz;
00074 
00075 CPROPS_DLL
00076 cp_timestampz *cp_timestampz_create(struct timeval *tm, int minuteswest);
00077 CPROPS_DLL
00078 cp_timestampz *
00079     cp_timestampz_create_prm(int sec_since_epoch, int microsec, int minwest);
00080 CPROPS_DLL
00081 void cp_timestampz_destroy(cp_timestampz *tm);
00082 CPROPS_DLL
00083 struct tm *cp_timestampz_localtime(cp_timestampz *tm, struct tm *res);
00084 
00085 
00086 /* ----------------------------------------------------------------------- */
00087 /*                                                                         */
00088 /*                    connection parameter declarations                    */
00089 /*                                                                         */
00090 /* ----------------------------------------------------------------------- */
00091 
00092 typedef CPROPS_DLL struct _cp_db_connection_parameters 
00093 {
00094     void *impl;
00095     cp_destructor_fn impl_dtr;
00096 } cp_db_connection_parameters; 
00100 CPROPS_DLL
00101 void cp_db_connection_parameters_destroy(cp_db_connection_parameters *prm);
00102 
00103 
00104 /* ----------------------------------------------------------------------- */
00105 /*                                                                         */
00106 /*                          connection declarations                        */
00107 /*                                                                         */
00108 /* ----------------------------------------------------------------------- */
00109 
00110 CPROPS_DLL struct _cp_data_source;
00111 
00112 typedef CPROPS_DLL struct _cp_db_connection
00113 {
00114     struct _cp_data_source *data_source;    
00115     void *connection;                       
00116     void *store;                            
00117     short autofetch_query_metadata;
00118     short read_result_set_at_once;
00119     int fetch_size;
00120     int autocommit;
00121 } cp_db_connection; 
00124 /* ----------------------------------------------------------------------- */
00125 /*                                                                         */
00126 /*                     prepared statement declarations                     */
00127 /*                                                                         */
00128 /* ----------------------------------------------------------------------- */
00129 
00130 typedef CPROPS_DLL struct _cp_db_statement
00131 {
00132     cp_db_connection *connection;
00133     int prm_count;
00134     cp_field_type *types;
00135     void *source;
00136     void *store;
00137     short binary; 
00138 } cp_db_statement;
00139 
00144 CPROPS_DLL
00145 cp_db_statement *cp_db_statement_instantiate(cp_db_connection *connection,
00146                                              int prm_count, 
00147                                              cp_field_type *types, 
00148                                              void *source);
00149 
00151 CPROPS_DLL
00152 void cp_db_statement_set_binary(cp_db_statement *stmt, int binary);
00153 
00158 CPROPS_DLL
00159 void cp_db_statement_destroy(cp_db_statement *statement);
00160 
00161 /* ----------------------------------------------------------------------- */
00162 /*                                                                         */
00163 /*                         result set declarations                         */
00164 /*                                                                         */
00165 /* ----------------------------------------------------------------------- */
00166 
00167 typedef CPROPS_DLL struct _cp_result_set
00168 {
00169     short fetch_complete;
00170     cp_db_connection *connection;
00171     void *source;                   
00172     void *store;                    
00173     cp_vector *field_headers;
00174     cp_vector *field_types;
00175     int position; 
00176     int row_count;
00177     int field_count;
00178     cp_list *results;
00179     short dispose;
00180     cp_list *dispose_list;
00181     short binary;
00182 } cp_result_set; 
00185 CPROPS_DLL
00186 cp_vector *cp_result_set_get_headers(cp_result_set *result_set);
00188 CPROPS_DLL
00189 cp_vector *cp_result_set_get_field_types(cp_result_set *result_set);
00191 CPROPS_DLL
00192 int cp_result_set_field_count(cp_result_set *result_set);
00194 CPROPS_DLL
00195 int cp_result_set_row_count(cp_result_set *result_set);
00197 CPROPS_DLL
00198 char *cp_result_set_get_header(cp_result_set *result_set, int column);
00200 CPROPS_DLL
00201 cp_field_type cp_result_set_get_field_type(cp_result_set *rs, int column);
00203 CPROPS_DLL
00204 void cp_result_set_autodispose(cp_result_set *rs, int mode);
00206 CPROPS_DLL
00207 cp_vector *cp_result_set_next(cp_result_set *result_set);
00209 CPROPS_DLL
00210 void cp_result_set_destroy(cp_result_set *result_set);
00212 CPROPS_DLL
00213 void cp_result_set_release_row(cp_result_set *result_set, cp_vector *row);
00215 CPROPS_DLL
00216 int cp_result_set_is_binary(cp_result_set *result_set);
00217 
00219 CPROPS_DLL
00220 cp_result_set *
00221     cp_db_connection_select(cp_db_connection *connection, char *query);
00223 CPROPS_DLL
00224 int cp_db_connection_update(cp_db_connection *connection, char *query);
00226 CPROPS_DLL
00227 int cp_db_connection_close(cp_db_connection *connection);
00229 CPROPS_DLL
00230 void cp_db_connection_destroy(cp_db_connection *connection);
00231 
00233 CPROPS_DLL
00234 void 
00235     cp_db_connection_set_fetch_metadata(cp_db_connection *connection, int mode);
00237 CPROPS_DLL
00238 void cp_db_connection_set_read_result_set_at_once(cp_db_connection *connection, 
00239                                                   int mode);
00241 CPROPS_DLL
00242 void cp_db_connection_set_fetch_size(cp_db_connection *connection, int fetch_size);
00244 CPROPS_DLL
00245 char *cp_db_connection_escape_string(cp_db_connection *connection, 
00246                                      char *src,
00247                                      int len);
00249 CPROPS_DLL
00250 char *cp_db_connection_escape_binary(cp_db_connection *connection, 
00251                                      char *src, 
00252                                      int src_len, 
00253                                      int *res_len);
00255 CPROPS_DLL
00256 cp_string *cp_db_connection_unescape_binary(cp_db_connection *connection,
00257                                             char *src);
00259 CPROPS_DLL
00260 cp_db_statement *
00261     cp_db_connection_prepare_statement(cp_db_connection *connection,
00262                                        int prm_count,
00263                                        cp_field_type *prm_types, 
00264                                        char *query);
00266 CPROPS_DLL
00267 int cp_db_connection_execute_statement(cp_db_connection *connection,
00268                                        cp_db_statement *statement, 
00269                                        cp_vector *prm,
00270                                        cp_result_set **results);
00272 CPROPS_DLL
00273 int cp_db_connection_execute_statement_args(cp_db_connection *connection,
00274                                             cp_db_statement *statement, 
00275                                             cp_result_set **results, ...);
00277 CPROPS_DLL
00278 void cp_db_connection_close_statement(cp_db_connection *connection, 
00279                                       cp_db_statement *statement);
00281 CPROPS_DLL
00282 void cp_db_connection_set_autocommit(cp_db_connection *conn, int state);
00284 CPROPS_DLL
00285 int cp_db_connection_commit(cp_db_connection *conn);
00287 CPROPS_DLL
00288 int cp_db_connection_rollback(cp_db_connection *conn);
00289 
00290 
00291 /* ----------------------------------------------------------------------- */
00292 /*                                                                         */
00293 /*                          db_actions declarations                        */
00294 /*                                                                         */
00295 /* ----------------------------------------------------------------------- */
00296 
00300 typedef cp_db_connection *(*cp_db_open_fn)(struct _cp_data_source *);
00301 
00302 
00306 typedef cp_result_set *(*cp_db_select_fn)(cp_db_connection *conn, char *query);
00307 
00312 typedef int (*cp_db_fetch_metadata_fn)(cp_result_set *rs);
00313 
00317 typedef int (*cp_db_fetch_next_fn)(cp_result_set *rs);
00318 
00322 typedef int (*cp_db_release_result_set_fn)(cp_result_set *rs);
00323 
00328 typedef int (*cp_db_update_fn)(cp_db_connection *conn, char *query);
00329 
00333 typedef int (*cp_db_close_fn)(cp_db_connection *conn);
00334 
00338 typedef char *(*cp_db_escape_string_fn)(cp_db_connection *conn, char *src, int len);
00339 
00344 typedef char *(*cp_db_escape_binary_fn)(cp_db_connection *conn, char *src, 
00345                                         int src_len, int *res_len);
00350 typedef cp_string *(*cp_db_unescape_binary_fn)(cp_db_connection *conn, 
00351                                                char *src);
00355 typedef cp_db_statement *
00356     (*cp_db_prepare_statement_fn)(cp_db_connection *conn, 
00357                                   int prm_count,
00358                                   cp_field_type *prm_types, 
00359                                   char *query);
00360 
00364 typedef int (*cp_db_execute_statement_fn)(cp_db_connection *conn, 
00365                                           cp_db_statement *stmt, 
00366                                           cp_result_set **results, 
00367                                           int *lengths,
00368                                           void **prm);
00373 typedef void (*cp_db_release_statement_fn)(cp_db_statement *stmt);
00374 
00378 typedef void (*cp_db_set_autocommit_fn)(cp_db_connection *conn, int state);
00379 
00383 typedef int (*cp_db_commit_fn)(cp_db_connection *conn);
00384 
00388 typedef int (*cp_db_rollback_fn)(cp_db_connection *conn);
00389 
00390 typedef CPROPS_DLL struct _cp_db_actions
00391 {
00392     int                           dbms;
00393     char                         *dbms_lit;
00394     cp_db_open_fn                 open;
00395     cp_db_select_fn               select;
00396     cp_db_fetch_next_fn           fetch_next;
00397     cp_db_fetch_metadata_fn       fetch_metadata;
00398     cp_db_release_result_set_fn   release_result_set;
00399     cp_db_update_fn               update;
00400     cp_db_close_fn                close;
00401     cp_db_escape_string_fn        escape_string;
00402     cp_db_escape_binary_fn        escape_binary;
00403     cp_db_unescape_binary_fn      unescape_binary;
00404     cp_db_prepare_statement_fn    prepare_statement;
00405     cp_db_execute_statement_fn    execute_statement;
00406     cp_db_release_statement_fn    release_statement;
00407     cp_db_set_autocommit_fn       set_autocommit;
00408     cp_db_commit_fn               commit;
00409     cp_db_rollback_fn             rollback;
00410 } cp_db_actions; 
00413 CPROPS_DLL
00414 cp_db_actions *
00415     cp_db_actions_create(int dbms,
00416                          char *dbms_lit,
00417                          cp_db_open_fn open,
00418                          cp_db_select_fn select,
00419                          cp_db_fetch_metadata_fn fetch_metadata,
00420                          cp_db_fetch_next_fn fetch_next,
00421                          cp_db_release_result_set_fn release_result_set,
00422                          cp_db_update_fn update,
00423                          cp_db_close_fn close,
00424                          cp_db_escape_string_fn escape_string,
00425                          cp_db_escape_binary_fn escape_binary,
00426                          cp_db_unescape_binary_fn unescape_binary,
00427                          cp_db_prepare_statement_fn prepare_statement,
00428                          cp_db_execute_statement_fn execute_statement,
00429                          cp_db_release_statement_fn release_statement,
00430                          cp_db_set_autocommit_fn set_autocommit,
00431                          cp_db_commit_fn commit,
00432                          cp_db_rollback_fn rollback);
00434 CPROPS_DLL
00435 void cp_db_actions_destroy(cp_db_actions *actions);
00436 
00437 
00438 /* ----------------------------------------------------------------------- */
00439 /*                                                                         */
00440 /*                      driver descriptor declarations                     */
00441 /*                                                                         */
00442 /* ----------------------------------------------------------------------- */
00443 
00444 typedef struct _cp_data_source *
00445     (*cp_db_get_data_source_fn)(char *host, int port, char *user, 
00446                                 char *passwd, char *dbname);
00447 
00448 typedef struct _cp_data_source *
00449     (*cp_db_get_data_source_prm_fn)(char *host, int port, char *user, 
00450                                     char *passwd, char *dbname, 
00451                                     cp_hashtable *prm);
00452 
00453 typedef CPROPS_DLL struct _cp_dbms_driver_descriptor
00454 {
00455     void *lib;
00456     cp_db_get_data_source_fn get_data_source;
00457     cp_db_get_data_source_prm_fn get_data_source_prm;
00458 } cp_dbms_driver_descriptor;
00459 
00460 
00461 /* ----------------------------------------------------------------------- */
00462 /*                                                                         */
00463 /*                         data source declarations                        */
00464 /*                                                                         */
00465 /* ----------------------------------------------------------------------- */
00466 
00467 typedef CPROPS_DLL struct _cp_data_source
00468 {
00469     cp_db_connection_parameters *prm;
00470     cp_db_actions               *act;
00471 } cp_data_source; 
00473 #if defined(CP_HAS_DLFCN_H) || defined(_WINDOWS)
00474 CPROPS_DLL
00475 int cp_dbms_load_driver(char *name);
00476 #endif /* CP_HAS_DLFCN_H */
00477 
00478 CPROPS_DLL
00479 cp_data_source *
00480     cp_dbms_get_data_source(char *driver, char *host, int port, char *user,
00481             char *passwd, char *dbname);
00482 
00483 CPROPS_DLL
00484 cp_data_source *
00485     cp_dbms_get_data_source_prm(char *driver, char *host, int port, 
00486             char *user, char *passwd, char *dbname, cp_hashtable *prm);
00487 
00489 CPROPS_DLL
00490 void cp_data_source_destroy(cp_data_source *data_source);
00492 CPROPS_DLL
00493 cp_db_connection *
00494     cp_data_source_get_connection(cp_data_source *data_source); 
00495 
00496 
00497 /* ----------------------------------------------------------------------- */
00498 /*                                                                         */
00499 /*                       connection pool declarations                      */
00500 /*                                                                         */
00501 /* ----------------------------------------------------------------------- */
00502 
00503 typedef CPROPS_DLL struct _cp_db_connection_pool
00504 {
00505     int running;
00506     int block;
00507 
00508     int min_size;
00509     int max_size;
00510     int size;
00511     cp_data_source *data_source;
00512     cp_list *free_list;
00513 
00514     cp_mutex *lock;
00515     cp_cond  *cond;
00516 } cp_db_connection_pool; 
00519 CPROPS_DLL
00520 cp_db_connection_pool *
00521     cp_db_connection_pool_create(cp_data_source *data_source, 
00522                                  int min_size, 
00523                                  int max_size, 
00524                                  int initial_size);
00525 
00527 CPROPS_DLL
00528 int cp_db_connection_pool_shutdown(cp_db_connection_pool *pool);
00530 CPROPS_DLL
00531 void cp_db_connection_pool_destroy(cp_db_connection_pool *pool);
00532 
00537 CPROPS_DLL
00538 void cp_db_connection_pool_set_blocking(cp_db_connection_pool *pool, int block);
00539 
00541 CPROPS_DLL
00542 cp_db_connection *
00543     cp_db_connection_pool_get_connection(cp_db_connection_pool *pool);
00544 
00546 CPROPS_DLL
00547 void cp_db_connection_pool_release_connection(cp_db_connection_pool *pool, 
00548                                               cp_db_connection *connection);
00549 
00550 __END_DECLS
00551 
00554 #endif