src/libstrongswan/database/database.h

   1 /*
   2  * Copyright (C) 2008 Martin Willi
   3  * Hochschule fuer Technik Rapperswil
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * for more details.
  14  */
  15
  16 /**
  17  * @defgroup databasei database
  18  * @{ @ingroup database
  19  */
  20
  21 #ifndef DATABASE_H_
  22 #define DATABASE_H_
  23
  24 typedef enum db_type_t db_type_t;
  25 typedef enum db_driver_t db_driver_t;
  26 typedef struct database_t database_t;
  27
  28 #include <utils/enumerator.h>
  29
  30 /**
  31  * Database column types
  32  */
  33 enum db_type_t {
  34         /** integer type, argument is an "int" */
  35         DB_INT,
  36         /** unsigned integer, argument is an "u_int" */
  37         DB_UINT,
  38         /** string type, argument is a "char*" */
  39         DB_TEXT,
  40         /** binary large object type, argument is a "chunk_t" */
  41         DB_BLOB,
  42         /** floating point, argument is a "double" */
  43         DB_DOUBLE,
  44         /** NULL, takes no argument */
  45         DB_NULL,
  46 };
  47
  48 /**
  49  * Database implementation type.
  50  */
  51 enum db_driver_t {
  52         /** SQLite database */
  53         DB_SQLITE,
  54         /** MySQL database */
  55         DB_MYSQL,
  56 };
  57
  58 /**
  59  * Interface for a database implementation.
  60  *
  61  * @code
  62    int affected, rowid, aint;
  63    char *atext;
  64    database_t *db;
  65    enumerator_t *enumerator;
  66
  67    db = lib->database->create("mysql://user:pass@host/database");
  68    affected = db->execute(db, &rowid, "INSERT INTO table VALUES (?, ?)",
  69                                                   DB_INT, 77, DB_TEXT, "a text");
  70    printf("inserted %d row, new row ID: %d\n", affected, rowid);
  71
  72    enumerator = db->query(db, "SELECT aint, atext FROM table WHERE aint > ?",
  73                                                   DB_INT, 10,           // 1 argument to SQL string
  74                                                   DB_INT, DB_TEXT); // 2 enumerated types in query
  75    if (enumerator)
  76    {
  77        while (enumerator->enumerate(enumerator, &aint, &atext))
  78        {
  79            printf("%d: %s\n", aint, atext);
  80        }
  81        enumerator->destroy(enumerator);
  82    }
  83    @endcode
  84  */
  85 struct database_t {
  86
  87         /**
  88          * Run a query which returns rows, such as a SELECT.
  89          *
  90          * @param sql           sql query string, containing '?' placeholders
  91          * @param ...           list of sql placeholder db_type_t followed by its value,
  92          *                  followed by enumerators arguments as db_type_t's
  93          * @return                      enumerator as defined with arguments, NULL on failure
  94          */
  95         enumerator_t* (*query)(database_t *this, char *sql, ...);
  96
  97         /**
  98          * Execute a query which dows not return rows, such as INSERT.
  99          *
 100          * @param rowid         pointer to write inserted AUTO_INCREMENT row ID, or NULL
 101          * @param sql           sql string, containing '?' placeholders
 102          * @param ...           list of sql placeholder db_type_t followed by its value
 103          * @return                      number of affected rows, < 0 on failure
 104          */
 105         int (*execute)(database_t *this, int *rowid, char *sql, ...);
 106
 107         /**
 108          * Get the database implementation type.
 109          *
 110          * To allow driver specific SQL or performance optimizations each database
 111          * implementations can be queried for its type.
 112          *
 113          * @return                      database implementation type
 114          */
 115         db_driver_t (*get_driver)(database_t *this);
 116
 117         /**
 118      * Destroy a database connection.
 119      */
 120     void (*destroy)(database_t *this);
 121 };
 122
 123 #endif /* DATABASE_H_ @}*/