modules: several small doxygen bug fixes
[sip-router] / modules / db_mysql / km_dbase.c
1 /* 
2  * $Id$ 
3  *
4  * MySQL module core functions
5  *
6  * Copyright (C) 2001-2003 FhG Fokus
7  * Copyright (C) 2007-2008 1&1 Internet AG
8  *
9  * This file is part of Kamailio, a free SIP server.
10  *
11  * Kamailio is free software; you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation; either version 2 of the License, or
14  * (at your option) any later version
15  *
16  * Kamailio is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License 
22  * along with this program; if not, write to the Free Software 
23  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24  */
25
26 /*!
27  * \file
28  * \brief Implementation of core functions for the MySQL driver.
29  *
30  * This file contains the implementation of core functions for the MySQL
31  * database driver, for example to submit a query or fetch a result.
32  * \ingroup db_mysql
33  *  Module: \ref db_mysql
34  */
35
36 #include <stdio.h>
37 #include <string.h>
38 #include <mysql/mysql.h>
39 #include <mysql/errmsg.h>
40 #include <mysql/mysql_version.h>
41 #include "../../mem/mem.h"
42 #include "../../dprint.h"
43 #include "../../lib/srdb1/db_query.h"
44 #include "../../lib/srdb1/db_ut.h"
45 #include "mysql_mod.h"
46 #include "km_val.h"
47 #include "km_my_con.h"
48 #include "km_res.h"
49 #include "km_row.h"
50 #include "km_db_mysql.h"
51 #include "km_dbase.h"
52
53 static char *sql_buf;
54
55
56 /**
57  * \brief Send a SQL query to the server.
58  *
59  * Send a SQL query to the database server. This methods tries to reconnect
60  * to the server if the connection is gone and the auto_reconnect parameter is
61  * enabled. It also issues a mysql_ping before the query to connect again after
62  * a long waiting period because for some older mysql versions the auto reconnect
63  * don't work sufficient. If auto_reconnect is enabled and the server supports it,
64  * then the mysql_ping is probably not necessary, but its safer to do it in this
65  * cases too.
66  *
67  * \param _h handle for the db
68  * \param _s executed query
69  * \return zero on success, negative value on failure
70  */
71 static int db_mysql_submit_query(const db1_con_t* _h, const str* _s)
72 {       
73         time_t t;
74         int i, code;
75
76         if (!_h || !_s || !_s->s) {
77                 LM_ERR("invalid parameter value\n");
78                 return -1;
79         }
80
81         if (my_ping_interval) {
82                 t = time(0);
83                 if ((t - CON_TIMESTAMP(_h)) > my_ping_interval) {
84                         if (mysql_ping(CON_CONNECTION(_h))) {
85                                 LM_WARN("driver error on ping: %s\n", mysql_error(CON_CONNECTION(_h)));
86                                 counter_inc(mysql_cnts_h.driver_err);
87                         }
88                 }
89                 /*
90                  * We're doing later a query anyway that will reset the timout of the server,
91                  * so it makes sense to set the timestamp value to the actual time in order
92                  * to prevent unnecessary pings.
93                  */
94                 CON_TIMESTAMP(_h) = t;
95         }
96
97         /* screws up the terminal when the query contains a BLOB :-( (by bogdan)
98          * LM_DBG("submit_query(): %.*s\n", _s->len, _s->s);
99          */
100
101         /* When a server connection is lost and a query is attempted, most of
102          * the time the query will return a CR_SERVER_LOST, then at the second
103          * attempt to execute it, the mysql lib will reconnect and succeed.
104          * However is a few cases, the first attempt returns CR_SERVER_GONE_ERROR
105          * the second CR_SERVER_LOST and only the third succeeds.
106          * Thus the 3 in the loop count. Increasing the loop count over this
107          * value shouldn't be needed, but it doesn't hurt either, since the loop
108          * will most of the time stop at the second or sometimes at the third
109          * iteration. In the case of CR_SERVER_GONE_ERROR and CR_SERVER_LOST the
110          * driver error counter is increased
111          */
112         for (i=0; i < (db_mysql_auto_reconnect ? 3 : 1); i++) {
113                 if (mysql_real_query(CON_CONNECTION(_h), _s->s, _s->len) == 0) {
114                         return 0;
115                 }
116                 code = mysql_errno(CON_CONNECTION(_h));
117                 if (code != CR_SERVER_GONE_ERROR && code != CR_SERVER_LOST) {
118                         break;
119                 }
120                 counter_inc(mysql_cnts_h.driver_err);
121         }
122         LM_ERR("driver error on query: %s\n", mysql_error(CON_CONNECTION(_h)));
123         return -2;
124 }
125
126
127
128 /**
129  * Initialize the database module.
130  * No function should be called before this
131  * \param _url URL used for initialization
132  * \return zero on success, negative value on failure
133  */
134 db1_con_t* db_mysql_init(const str* _url)
135 {
136         return db_do_init(_url, (void *)db_mysql_new_connection);
137 }
138
139
140 /**
141  * Shut down the database module.
142  * No function should be called after this
143  * \param _h handle to the closed connection
144  * \return zero on success, negative value on failure
145  */
146 void db_mysql_close(db1_con_t* _h)
147 {
148         db_do_close(_h, db_mysql_free_connection);
149 }
150
151
152 /**
153  * Retrieve a result set
154  * \param _h handle to the database
155  * \param _r result set that should be retrieved
156  * \return zero on success, negative value on failure
157  */
158 static int db_mysql_store_result(const db1_con_t* _h, db1_res_t** _r)
159 {
160         int code;
161         if ((!_h) || (!_r)) {
162                 LM_ERR("invalid parameter value\n");
163                 return -1;
164         }
165
166         *_r = db_new_result();
167         if (*_r == 0) {
168                 LM_ERR("no memory left\n");
169                 return -2;
170         }
171
172         CON_RESULT(_h) = mysql_store_result(CON_CONNECTION(_h));
173         if (!CON_RESULT(_h)) {
174                 if (mysql_field_count(CON_CONNECTION(_h)) == 0) {
175                         (*_r)->col.n = 0;
176                         (*_r)->n = 0;
177                         goto done;
178                 } else {
179                         LM_ERR("driver error: %s\n", mysql_error(CON_CONNECTION(_h)));
180                         code = mysql_errno(CON_CONNECTION(_h));
181                         if (code == CR_SERVER_GONE_ERROR || code == CR_SERVER_LOST) {
182                                 counter_inc(mysql_cnts_h.driver_err);
183                         }
184                         db_free_result(*_r);
185                         *_r = 0;
186                         return -3;
187                 }
188         }
189
190         if (db_mysql_convert_result(_h, *_r) < 0) {
191                 LM_ERR("error while converting result\n");
192                 LM_DBG("freeing result set at %p\n", _r);
193                 pkg_free(*_r);
194                 *_r = 0;
195                 /* all mem on openser API side is already freed by
196                  * db_mysql_convert_result in case of error, but we also need
197                  * to free the mem from the mysql lib side */
198                 mysql_free_result(CON_RESULT(_h));
199 #if (MYSQL_VERSION_ID >= 40100)
200                 while( mysql_more_results(CON_CONNECTION(_h)) && mysql_next_result(CON_CONNECTION(_h)) > 0 ) {
201                         MYSQL_RES *res = mysql_store_result( CON_CONNECTION(_h) );
202                         mysql_free_result(res);
203                 }
204 #endif
205                 CON_RESULT(_h) = 0;
206                 return -4;
207         }
208
209 done:
210 #if (MYSQL_VERSION_ID >= 40100)
211         while( mysql_more_results(CON_CONNECTION(_h)) && mysql_next_result(CON_CONNECTION(_h)) > 0 ) {
212                 MYSQL_RES *res = mysql_store_result( CON_CONNECTION(_h) );
213                 mysql_free_result(res);
214         }
215 #endif
216
217         return 0;
218 }
219
220
221 /**
222  * Release a result set from memory.
223  * \param _h handle to the database
224  * \param _r result set that should be freed
225  * \return zero on success, negative value on failure
226  */
227 int db_mysql_free_result(db1_con_t* _h, db1_res_t* _r)
228 {
229      if ((!_h) || (!_r)) {
230              LM_ERR("invalid parameter value\n");
231              return -1;
232      }
233
234      if (db_free_result(_r) < 0) {
235              LM_ERR("unable to free result structure\n");
236              return -1;
237      }
238      mysql_free_result(CON_RESULT(_h));
239      CON_RESULT(_h) = 0;
240      return 0;
241 }
242
243
244 /**
245  * Query a table for specified rows.
246  * \param _h structure representing database connection
247  * \param _k key names
248  * \param _op operators
249  *\param  _v values of the keys that must match
250  * \param _c column names to return
251  * \param _n number of key=values pairs to compare
252  * \param _nc number of columns to return
253  * \param _o order by the specified column
254  * \param _r pointer to a structure representing the result
255  * \return zero on success, negative value on failure
256  */
257 int db_mysql_query(const db1_con_t* _h, const db_key_t* _k, const db_op_t* _op,
258              const db_val_t* _v, const db_key_t* _c, const int _n, const int _nc,
259              const db_key_t _o, db1_res_t** _r)
260 {
261         return db_do_query(_h, _k, _op, _v, _c, _n, _nc, _o, _r,
262         db_mysql_val2str, db_mysql_submit_query, db_mysql_store_result);
263 }
264
265 /**
266  * \brief Gets a partial result set, fetch rows from a result
267  *
268  * Gets a partial result set, fetch a number of rows from a database result.
269  * This function initialize the given result structure on the first run, and
270  * fetches the nrows number of rows. On subsequenting runs, it uses the
271  * existing result and fetches more rows, until it reaches the end of the
272  * result set. Because of this the result needs to be null in the first
273  * invocation of the function. If the number of wanted rows is zero, the
274  * function returns anything with a result of zero.
275  * \param _h structure representing the database connection
276  * \param _r pointer to a structure representing the result
277  * \param nrows number of fetched rows
278  * \return zero on success, negative value on failure
279  */
280 int db_mysql_fetch_result(const db1_con_t* _h, db1_res_t** _r, const int nrows)
281 {
282         int rows, i, code;
283
284         if (!_h || !_r || nrows < 0) {
285                 LM_ERR("Invalid parameter value\n");
286                 return -1;
287         }
288
289         /* exit if the fetch count is zero */
290         if (nrows == 0) {
291                 db_free_result(*_r);
292                 *_r = 0;
293                 return 0;
294         }
295
296         if(*_r==0) {
297                 /* Allocate a new result structure */
298                 *_r = db_new_result();
299                 if (*_r == 0) {
300                         LM_ERR("no memory left\n");
301                         return -2;
302                 }
303
304                 CON_RESULT(_h) = mysql_store_result(CON_CONNECTION(_h));
305                 if (!CON_RESULT(_h)) {
306                         if (mysql_field_count(CON_CONNECTION(_h)) == 0) {
307                                 (*_r)->col.n = 0;
308                                 (*_r)->n = 0;
309                                 return 0;
310                         } else {
311                                 LM_ERR("driver error: %s\n", mysql_error(CON_CONNECTION(_h)));
312                                 code = mysql_errno(CON_CONNECTION(_h));
313                                 if (code == CR_SERVER_GONE_ERROR || code == CR_SERVER_LOST) {
314                                         counter_inc(mysql_cnts_h.driver_err);
315                                 }
316                                 db_free_result(*_r);
317                                 *_r = 0;
318                                 return -3;
319                         }
320                 }
321                 if (db_mysql_get_columns(_h, *_r) < 0) {
322                         LM_ERR("error while getting column names\n");
323                         return -4;
324                 }
325
326                 RES_NUM_ROWS(*_r) = mysql_num_rows(CON_RESULT(_h));
327                 if (!RES_NUM_ROWS(*_r)) {
328                         LM_DBG("no rows returned from the query\n");
329                         RES_ROWS(*_r) = 0;
330                         return 0;
331                 }
332
333         } else {
334                 /* free old rows */
335                 if(RES_ROWS(*_r)!=0)
336                         db_free_rows(*_r);
337                 RES_ROWS(*_r) = 0;
338                 RES_ROW_N(*_r) = 0;
339         }
340
341         /* determine the number of rows remaining to be processed */
342         rows = RES_NUM_ROWS(*_r) - RES_LAST_ROW(*_r);
343
344         /* If there aren't any more rows left to process, exit */
345         if(rows<=0)
346                 return 0;
347
348         /* if the fetch count is less than the remaining rows to process                 */
349         /* set the number of rows to process (during this call) equal to the fetch count */
350         if(nrows < rows)
351                 rows = nrows;
352
353         RES_ROW_N(*_r) = rows;
354
355         LM_DBG("converting row %d of %d count %d\n", RES_LAST_ROW(*_r),
356                         RES_NUM_ROWS(*_r), RES_ROW_N(*_r));
357
358         RES_ROWS(*_r) = (struct db_row*)pkg_malloc(sizeof(db_row_t) * rows);
359         if (!RES_ROWS(*_r)) {
360                 LM_ERR("no memory left\n");
361                 return -5;
362         }
363
364         for(i = 0; i < rows; i++) {
365                 CON_ROW(_h) = mysql_fetch_row(CON_RESULT(_h));
366                 if (!CON_ROW(_h)) {
367                         LM_ERR("driver error: %s\n", mysql_error(CON_CONNECTION(_h)));
368                         RES_ROW_N(*_r) = i;
369                         db_free_rows(*_r);
370                         return -6;
371                 }
372                 if (db_mysql_convert_row(_h, *_r, &(RES_ROWS(*_r)[i])) < 0) {
373                         LM_ERR("error while converting row #%d\n", i);
374                         RES_ROW_N(*_r) = i;
375                         db_free_rows(*_r);
376                         return -7;
377                 }
378         }
379
380         /* update the total number of rows processed */
381         RES_LAST_ROW(*_r) += rows;
382         return 0;
383 }
384
385 /**
386  * Execute a raw SQL query.
387  * \param _h handle for the database
388  * \param _s raw query string
389  * \param _r result set for storage
390  * \return zero on success, negative value on failure
391  */
392 int db_mysql_raw_query(const db1_con_t* _h, const str* _s, db1_res_t** _r)
393 {
394         return db_do_raw_query(_h, _s, _r, db_mysql_submit_query,
395         db_mysql_store_result);
396 }
397
398
399 /**
400  * Insert a row into a specified table.
401  * \param _h structure representing database connection
402  * \param _k key names
403  * \param _v values of the keys
404  * \param _n number of key=value pairs
405  * \return zero on success, negative value on failure
406  */
407 int db_mysql_insert(const db1_con_t* _h, const db_key_t* _k, const db_val_t* _v, const int _n)
408 {
409         return db_do_insert(_h, _k, _v, _n, db_mysql_val2str,
410         db_mysql_submit_query);
411 }
412
413
414 /**
415  * Delete a row from the specified table
416  * \param _h structure representing database connection
417  * \param _k key names
418  * \param _o operators
419  * \param _v values of the keys that must match
420  * \param _n number of key=value pairs
421  * \return zero on success, negative value on failure
422  */
423 int db_mysql_delete(const db1_con_t* _h, const db_key_t* _k, const db_op_t* _o,
424         const db_val_t* _v, const int _n)
425 {
426         return db_do_delete(_h, _k, _o, _v, _n, db_mysql_val2str,
427         db_mysql_submit_query);
428 }
429
430
431 /**
432  * Update some rows in the specified table
433  * \param _h structure representing database connection
434  * \param _k key names
435  * \param _o operators
436  * \param _v values of the keys that must match
437  * \param _uk updated columns
438  * \param _uv updated values of the columns
439  * \param _n number of key=value pairs
440  * \param _un number of columns to update
441  * \return zero on success, negative value on failure
442  */
443 int db_mysql_update(const db1_con_t* _h, const db_key_t* _k, const db_op_t* _o, 
444         const db_val_t* _v, const db_key_t* _uk, const db_val_t* _uv, const int _n, 
445         const int _un)
446 {
447         return db_do_update(_h, _k, _o, _v, _uk, _uv, _n, _un, db_mysql_val2str,
448         db_mysql_submit_query);
449 }
450
451
452 /**
453  * Just like insert, but replace the row if it exists.
454  * \param _h database handle
455  * \param _k key names
456  * \param _v values of the keys that must match
457  * \param _n number of key=value pairs
458  * \return zero on success, negative value on failure
459  */
460 int db_mysql_replace(const db1_con_t* _h, const db_key_t* _k, const db_val_t* _v, const int _n)
461 {
462         return db_do_replace(_h, _k, _v, _n, db_mysql_val2str,
463         db_mysql_submit_query);
464 }
465
466
467 /**
468  * Returns the last inserted ID.
469  * \param _h database handle
470  * \return returns the ID as integer or returns 0 if the previous statement
471  * does not use an AUTO_INCREMENT value.
472  */
473 int db_mysql_last_inserted_id(const db1_con_t* _h)
474 {
475         if (!_h) {
476                 LM_ERR("invalid parameter value\n");
477                 return -1;
478         }
479         return mysql_insert_id(CON_CONNECTION(_h));
480 }
481
482
483 /**
484  * Returns the affected rows of the last query.
485  * \param _h database handle
486  * \return returns the affected rows as integer or -1 on error.
487  */
488 int db_mysql_affected_rows(const db1_con_t* _h)
489 {
490         if (!_h) {
491                 LM_ERR("invalid parameter value\n");
492                 return -1;
493         }
494         return (int)mysql_affected_rows(CON_CONNECTION(_h));
495 }
496
497
498 /**
499   * Insert a row into a specified table, update on duplicate key.
500   * \param _h structure representing database connection
501   * \param _k key names
502   * \param _v values of the keys
503   * \param _n number of key=value pairs
504  */
505  int db_mysql_insert_update(const db1_con_t* _h, const db_key_t* _k, const db_val_t* _v,
506         const int _n)
507  {
508         int off, ret;
509         static str  sql_str;
510  
511         if ((!_h) || (!_k) || (!_v) || (!_n)) {
512                 LM_ERR("invalid parameter value\n");
513                 return -1;
514         }
515  
516         ret = snprintf(sql_buf, sql_buffer_size, "insert into %.*s (", CON_TABLE(_h)->len, CON_TABLE(_h)->s);
517         if (ret < 0 || ret >= sql_buffer_size) goto error;
518         off = ret;
519
520         ret = db_print_columns(sql_buf + off, sql_buffer_size - off, _k, _n);
521         if (ret < 0) return -1;
522         off += ret;
523
524         ret = snprintf(sql_buf + off, sql_buffer_size - off, ") values (");
525         if (ret < 0 || ret >= (sql_buffer_size - off)) goto error;
526         off += ret;
527         ret = db_print_values(_h, sql_buf + off, sql_buffer_size - off, _v, _n, db_mysql_val2str);
528         if (ret < 0) return -1;
529         off += ret;
530
531         *(sql_buf + off++) = ')';
532         
533         ret = snprintf(sql_buf + off, sql_buffer_size - off, " on duplicate key update ");
534         if (ret < 0 || ret >= (sql_buffer_size - off)) goto error;
535         off += ret;
536         
537         ret = db_print_set(_h, sql_buf + off, sql_buffer_size - off, _k, _v, _n, db_mysql_val2str);
538         if (ret < 0) return -1;
539         off += ret;
540         
541         sql_str.s = sql_buf;
542         sql_str.len = off;
543  
544         if (db_mysql_submit_query(_h, &sql_str) < 0) {
545                 LM_ERR("error while submitting query\n");
546                 return -2;
547         }
548         return 0;
549
550 error:
551         LM_ERR("error while preparing insert_update operation\n");
552         return -1;
553 }
554
555
556 /**
557  * Insert delayed a row into a specified table.
558  * \param _h structure representing database connection
559  * \param _k key names
560  * \param _v values of the keys
561  * \param _n number of key=value pairs
562  * \return zero on success, negative value on failure
563  */
564 int db_mysql_insert_delayed(const db1_con_t* _h, const db_key_t* _k, const db_val_t* _v, const int _n)
565 {
566         return db_do_insert_delayed(_h, _k, _v, _n, db_mysql_val2str,
567         db_mysql_submit_query);
568 }
569
570
571 /**
572  * Store the name of table that will be used by subsequent database functions
573  * \param _h database handle
574  * \param _t table name
575  * \return zero on success, negative value on failure
576  */
577 int db_mysql_use_table(db1_con_t* _h, const str* _t)
578 {
579         return db_use_table(_h, _t);
580 }
581
582
583 /**
584  * Allocate a buffer for database module
585  * No function should be called before this
586  * \return zero on success, negative value on failure
587  */
588 int db_mysql_alloc_buffer(void)
589 {
590     if (db_query_init())
591     {
592         LM_ERR("Failed to initialise db_query\n");
593                 return -1;
594     }
595
596     sql_buf = (char*)malloc(sql_buffer_size);
597     if (sql_buf == NULL)
598         return -1;
599     else
600         return 0;
601 }