1 /* 2 * Copyright (C) 2001-2003 FhG Fokus 3 * Copyright (C) 2007-2008 1&1 Internet AG 4 * 5 * This file is part of Kamailio, a free SIP server. 6 * 7 * Kamailio is free software; you can redistribute it and/or modify 8 * it under the terms of the GNU General Public License as published by 9 * the Free Software Foundation; either version 2 of the License, or 10 * (at your option) any later version 11 * 12 * Kamailio is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU General Public License for more details. 16 * 17 * You should have received a copy of the GNU General Public License 18 * along with this program; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 20 */ 21 22 /** 23 * \file lib/srdb1/db_val.h 24 * \brief Data structures that represents values in the database. 25 * 26 * This file defines data structures that represents values in the database. 27 * Several datatypes are recognized and converted by the database API. 28 * Available types: DB1_INT, DB1_DOUBLE, DB1_STRING, DB1_STR, DB1_DATETIME, DB1_BLOB and DB1_BITMAP 29 * It also provides some macros for convenient access to this values, 30 * and a function to convert a str to a value. 31 * \ingroup db1 32 */ 33 34 35 #ifndef DB1_VAL_H 36 #define DB1_VAL_H 37 38 #include "db_con.h" 39 #include <time.h> 40 #include "../../core/str.h" 41 42 43 /** 44 * Each cell in a database table can be of a different type. To distinguish 45 * among these types, the db_type_t enumeration is used. Every value of the 46 * enumeration represents one datatype that is recognized by the database 47 * API. 48 */ 49 typedef enum { 50 DB1_INT, /**< represents an 32 bit integer number */ 51 DB1_BIGINT, /**< represents an 64 bit integer number */ 52 DB1_DOUBLE, /**< represents a floating point number */ 53 DB1_STRING, /**< represents a zero terminated const char* */ 54 DB1_STR, /**< represents a string of 'str' type */ 55 DB1_DATETIME, /**< represents date and time */ 56 DB1_BLOB, /**< represents a large binary object */ 57 DB1_BITMAP, /**< an one-dimensional array of 32 flags */ 58 DB1_UINT, /**< represents an 32 bit unsigned int number */ 59 DB1_UBIGINT, /**< represents an 64 bit unsigned int number */ 60 DB1_UNKNOWN /**< represents an unknown type */ 61 } db_type_t; 62 63 64 /** 65 * This structure represents a value in the database. Several datatypes are 66 * recognized and converted by the database API. These datatypes are automaticaly 67 * recognized, converted from internal database representation and stored in the 68 * variable of corresponding type. 69 * 70 * Module that want to use this values needs to copy them to another memory 71 * location, because after the call to free_result there are not more available. 72 * 73 * If the structure holds a pointer to a string value that needs to be freed 74 * because the module allocated new memory for it then the free flag must 75 * be set to a non-zero value. A free flag of zero means that the string 76 * data must be freed internally by the database driver. 77 */ 78 typedef struct { 79 db_type_t type; /**< Type of the value */ 80 int nul; /**< Means that the column in database has no value */ 81 int free; /**< Means that the value should be freed */ 82 /** Column value structure that holds the actual data in a union. */ 83 union { 84 int int_val; /**< integer value */ 85 long long ll_val; /**< long long value */ 86 double double_val; /**< double value */ 87 time_t time_val; /**< unix time_t value */ 88 const char* string_val; /**< zero terminated string */ 89 str str_val; /**< str type string value */ 90 str blob_val; /**< binary object data */ 91 unsigned int bitmap_val; /**< Bitmap data type */ 92 unsigned int uint_val; /**< unsigned integer value */ 93 unsigned long long ull_val; /**< unsigned long long value */ 94 } val; 95 } db_val_t; 96 97 98 /** 99 * Useful macros for accessing attributes of db_val structure. 100 * All macros expect a reference to a db_val_t variable as parameter. 101 */ 102 103 /** 104 * Use this macro if you need to set/get the type of the value. 105 */ 106 #define VAL_TYPE(dv) ((dv)->type) 107 108 109 /** 110 * Use this macro if you need to set/get the null flag. A non-zero flag means that 111 * the corresponding cell in the database contains no data (a NULL value in MySQL 112 * terminology). 113 */ 114 #define VAL_NULL(dv) ((dv)->nul) 115 116 117 /** 118 * Use this macro if you need to set/ get the free flag. A non-zero flag means that 119 * the corresponding cell in the database contains data that must be freed from the 120 * DB API. 121 */ 122 #define VAL_FREE(dv) ((dv)->free) 123 124 125 /** 126 * Use this macro if you need to access the integer value in the db_val_t structure. 127 */ 128 #define VAL_INT(dv) ((dv)->val.int_val) 129 130 131 /** 132 * Use this macro if you need to access the unsigned integer value in 133 * the db_val_t structure. 134 */ 135 #define VAL_UINT(dv) ((dv)->val.uint_val) 136 137 138 /** 139 * Use this macro if you need to access the long long value in the db_val_t structure. 140 */ 141 #define VAL_BIGINT(dv) ((dv)->val.ll_val) 142 143 /** 144 * Use this macro if you need to access the unsigned long long value in 145 * the db_val_t structure. 146 */ 147 #define VAL_UBIGINT(dv) ((dv)->val.ull_val) 148 149 /** 150 * Use this macro if you need to access the double value in the db_val_t structure. 151 */ 152 #define VAL_DOUBLE(dv) ((dv)->val.double_val) 153 154 155 /** 156 * Use this macro if you need to access the time_t value in the db_val_t structure. 157 */ 158 #define VAL_TIME(dv) ((dv)->val.time_val) 159 160 161 /** 162 * Use this macro if you need to access the string value in the db_val_t structure. 163 */ 164 #define VAL_STRING(dv) ((dv)->val.string_val) 165 166 167 /** 168 * Use this macro if you need to access the str structure in the db_val_t structure. 169 */ 170 #define VAL_STR(dv) ((dv)->val.str_val) 171 172 173 /** 174 * Use this macro if you need to access the blob value in the db_val_t structure. 175 */ 176 #define VAL_BLOB(dv) ((dv)->val.blob_val) 177 178 179 /** 180 * Use this macro if you need to access the bitmap value in the db_val_t structure. 181 */ 182 #define VAL_BITMAP(dv) ((dv)->val.bitmap_val) 183 184 185 /*! 186 * \brief Convert a str to a db value 187 * 188 * Convert a str to a db value, does not copy strings if _cpy is zero 189 * \param _t destination value type 190 * \param _v destination value 191 * \param _s source string 192 * \param _l string length 193 * \param _cpy when set to zero does not copy strings, otherwise copy strings 194 * \return 0 on success, negative on error 195 */ 196 int db_str2val(const db_type_t _t, db_val_t* _v, const char* _s, const int _l, 197 const unsigned int _cpy); 198 199 200 /*! 201 * \brief Convert a numerical value to a string 202 * 203 * Convert a numerical value to a string, used when converting result from a query. 204 * Implement common functionality needed from the databases, does parameter checking. 205 * \param _c database connection 206 * \param _v source value 207 * \param _s target string 208 * \param _len target string length 209 * \return 0 on success, negative on error, 1 if value must be converted by other means 210 */ 211 int db_val2str(const db1_con_t* _c, const db_val_t* _v, char* _s, int* _len); 212 213 #endif /* DB1_VAL_H */ 214