db_val.h 6.7 KB

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