Browse code

- convert existing documentation to doxygen format - add some comments, some smaller cleanups - small adjustment of the fetch_result function to the postgres one, add one DBG message, renames a parameter

git-svn-id: https://openser.svn.sourceforge.net/svnroot/openser/trunk@4124 689a6050-402a-0410-94f2-e92a70836424

Henning Westerholt authored on 07/05/2008 16:36:48
Showing 6 changed files
... ...
@@ -117,9 +117,11 @@ static int db_mysql_submit_query(const db_con_t* _h, const str* _s)
117 117
 
118 118
 
119 119
 
120
-/*
121
- * Initialize database module
120
+/**
121
+ * Initialize the database module.
122 122
  * No function should be called before this
123
+ * \param _url URL used for initialization
124
+ * \return zero on success, negative value on failure
123 125
  */
124 126
 db_con_t* db_mysql_init(const str* _url)
125 127
 {
... ...
@@ -127,9 +129,11 @@ db_con_t* db_mysql_init(const str* _url)
127 129
 }
128 130
 
129 131
 
130
-/*
131
- * Shut down database module
132
+/**
133
+ * Shut down the database module.
132 134
  * No function should be called after this
135
+ * \param _h handle to the closed connection
136
+ * \return zero on success, negative value on failure
133 137
  */
134 138
 void db_mysql_close(db_con_t* _h)
135 139
 {
... ...
@@ -137,8 +141,11 @@ void db_mysql_close(db_con_t* _h)
137 141
 }
138 142
 
139 143
 
140
-/*
141
- * Retrieve result set
144
+/**
145
+ * Retrieve a result set
146
+ * \param _h handle to the database
147
+ * \param _r result set that should be retrieved
148
+ * \return zero on success, negative value on failure
142 149
  */
143 150
 static int db_mysql_store_result(const db_con_t* _h, db_res_t** _r)
144 151
 {
... ...
@@ -197,8 +204,11 @@ done:
197 204
 }
198 205
 
199 206
 
200
-/*
201
- * Release a result set from memory
207
+/**
208
+ * Release a result set from memory.
209
+ * \param _h handle to the database
210
+ * \param _r result set that should be freed
211
+ * \return zero on success, negative value on failure
202 212
  */
203 213
 int db_mysql_free_result(db_con_t* _h, db_res_t* _r)
204 214
 {
... ...
@@ -217,16 +227,17 @@ int db_mysql_free_result(db_con_t* _h, db_res_t* _r)
217 227
 }
218 228
 
219 229
 
220
-/*
221
- * Query table for specified rows
222
- * _h: structure representing database connection
223
- * _k: key names
224
- * _op: operators
225
- * _v: values of the keys that must match
226
- * _c: column names to return
227
- * _n: number of key=values pairs to compare
228
- * _nc: number of columns to return
229
- * _o: order by the specified column
230
+/**
231
+ * Query a table for specified rows.
232
+ * \param _h structure representing database connection
233
+ * \param _k key names
234
+ * \param _op operators
235
+ *\param  _v values of the keys that must match
236
+ * \param _c column names to return
237
+ * \param _n number of key=values pairs to compare
238
+ * \param _nc number of columns to return
239
+ * \param _o order by the specified column
240
+ * \return zero on success, negative value on failure
230 241
  */
231 242
 int db_mysql_query(const db_con_t* _h, const db_key_t* _k, const db_op_t* _op,
232 243
 	     const db_val_t* _v, const db_key_t* _c, const int _n, const int _nc,
... ...
@@ -236,16 +247,16 @@ int db_mysql_query(const db_con_t* _h, const db_key_t* _k, const db_op_t* _op,
236 247
 	db_mysql_val2str, db_mysql_submit_query, db_mysql_store_result);
237 248
 }
238 249
 
239
-/*
240
- * gets a partial result set
241
- * _h: structure representing the database connection
242
- * _r: pointer to a structure representing the result
243
- * nrows: number of fetched rows
250
+/**
251
+ * Gets a partial result set.
252
+ * \param _h structure representing the database connection
253
+ * \param _r pointer to a structure representing the result
254
+ * \param nrows number of fetched rows
255
+ * \return zero on success, negative value on failure
244 256
  */
245 257
 int db_mysql_fetch_result(const db_con_t* _h, db_res_t** _r, const int nrows)
246 258
 {
247
-	int n;
248
-	int i;
259
+	int rows, i;
249 260
 
250 261
 	if (!_h || !_r || nrows < 0) {
251 262
 		LM_ERR("Invalid parameter value\n");
... ...
@@ -287,9 +298,11 @@ int db_mysql_fetch_result(const db_con_t* _h, db_res_t** _r, const int nrows)
287 298
 
288 299
 		RES_NUM_ROWS(*_r) = mysql_num_rows(CON_RESULT(_h));
289 300
 		if (!RES_NUM_ROWS(*_r)) {
301
+			LM_DBG("no rows returned from the query\n");
290 302
 			RES_ROWS(*_r) = 0;
291 303
 			return 0;
292 304
 		}
305
+
293 306
 	} else {
294 307
 		/* free old rows */
295 308
 		if(RES_ROWS(*_r)!=0)
... ...
@@ -299,27 +312,27 @@ int db_mysql_fetch_result(const db_con_t* _h, db_res_t** _r, const int nrows)
299 312
 	}
300 313
 
301 314
 	/* determine the number of rows remaining to be processed */
302
-	n = RES_NUM_ROWS(*_r) - RES_LAST_ROW(*_r);
315
+	rows = RES_NUM_ROWS(*_r) - RES_LAST_ROW(*_r);
303 316
 
304 317
 	/* If there aren't any more rows left to process, exit */
305
-	if(n<=0)
318
+	if(rows<=0)
306 319
 		return 0;
307 320
 
308 321
 	/* if the fetch count is less than the remaining rows to process                 */
309 322
 	/* set the number of rows to process (during this call) equal to the fetch count */
310
-	if(nrows < n)
311
-		n = nrows;
323
+	if(nrows < rows)
324
+		rows = nrows;
312 325
 
313
-	RES_LAST_ROW(*_r) += n;
314
-	RES_ROW_N(*_r) = n;
326
+	RES_LAST_ROW(*_r) += rows;
327
+	RES_ROW_N(*_r) = rows;
315 328
 
316
-	RES_ROWS(*_r) = (struct db_row*)pkg_malloc(sizeof(db_row_t) * n);
329
+	RES_ROWS(*_r) = (struct db_row*)pkg_malloc(sizeof(db_row_t) * rows);
317 330
 	if (!RES_ROWS(*_r)) {
318 331
 		LM_ERR("no memory left\n");
319 332
 		return -5;
320 333
 	}
321 334
 
322
-	for(i = 0; i < n; i++) {
335
+	for(i = 0; i < rows; i++) {
323 336
 		CON_ROW(_h) = mysql_fetch_row(CON_RESULT(_h));
324 337
 		if (!CON_ROW(_h)) {
325 338
 			LM_ERR("driver error: %s\n", mysql_error(CON_CONNECTION(_h)));
... ...
@@ -337,8 +350,12 @@ int db_mysql_fetch_result(const db_con_t* _h, db_res_t** _r, const int nrows)
337 350
 	return 0;
338 351
 }
339 352
 
340
-/*
341
- * Execute a raw SQL query
353
+/**
354
+ * Execute a raw SQL query.
355
+ * \param _h handle for the database
356
+ * \param _s raw query string
357
+ * \param _r result set for storage
358
+ * \return zero on success, negative value on failure
342 359
  */
343 360
 int db_mysql_raw_query(const db_con_t* _h, const str* _s, db_res_t** _r)
344 361
 {
... ...
@@ -347,12 +364,13 @@ int db_mysql_raw_query(const db_con_t* _h, const str* _s, db_res_t** _r)
347 364
 }
348 365
 
349 366
 
350
-/*
351
- * Insert a row into specified table
352
- * _h: structure representing database connection
353
- * _k: key names
354
- * _v: values of the keys
355
- * _n: number of key=value pairs
367
+/**
368
+ * Insert a row into a specified table.
369
+ * \param _h structure representing database connection
370
+ * \param _k key names
371
+ * \param _v values of the keys
372
+ * \param _n number of key=value pairs
373
+ * \return zero on success, negative value on failure
356 374
  */
357 375
 int db_mysql_insert(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v, const int _n)
358 376
 {
... ...
@@ -361,13 +379,14 @@ int db_mysql_insert(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v,
361 379
 }
362 380
 
363 381
 
364
-/*
382
+/**
365 383
  * Delete a row from the specified table
366
- * _h: structure representing database connection
367
- * _k: key names
368
- * _o: operators
369
- * _v: values of the keys that must match
370
- * _n: number of key=value pairs
384
+ * \param _h structure representing database connection
385
+ * \param _k key names
386
+ * \param _o operators
387
+ * \param _v values of the keys that must match
388
+ * \param _n number of key=value pairs
389
+ * \return zero on success, negative value on failure
371 390
  */
372 391
 int db_mysql_delete(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o,
373 392
 	const db_val_t* _v, const int _n)
... ...
@@ -377,16 +396,17 @@ int db_mysql_delete(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o,
377 396
 }
378 397
 
379 398
 
380
-/*
399
+/**
381 400
  * Update some rows in the specified table
382
- * _h: structure representing database connection
383
- * _k: key names
384
- * _o: operators
385
- * _v: values of the keys that must match
386
- * _uk: updated columns
387
- * _uv: updated values of the columns
388
- * _n: number of key=value pairs
389
- * _un: number of columns to update
401
+ * \param _h structure representing database connection
402
+ * \param _k key names
403
+ * \param _o operators
404
+ * \param _v values of the keys that must match
405
+ * \param _uk updated columns
406
+ * \param _uv updated values of the columns
407
+ * \param _n number of key=value pairs
408
+ * \param _un number of columns to update
409
+ * \return zero on success, negative value on failure
390 410
  */
391 411
 int db_mysql_update(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o, 
392 412
 	const db_val_t* _v, const db_key_t* _uk, const db_val_t* _uv, const int _n, 
... ...
@@ -397,8 +417,13 @@ int db_mysql_update(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o,
397 417
 }
398 418
 
399 419
 
400
-/*
401
- * Just like insert, but replace the row if it exists
420
+/**
421
+ * Just like insert, but replace the row if it exists.
422
+ * \param _h database handle
423
+ * \param _k key names
424
+ * \param _v values of the keys that must match
425
+ * \param _n number of key=value pairs
426
+ * \return zero on success, negative value on failure
402 427
  */
403 428
 int db_mysql_replace(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v, const int _n)
404 429
 {
... ...
@@ -407,8 +432,11 @@ int db_mysql_replace(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v,
407 432
 }
408 433
 
409 434
 
410
-/*
411
- * Returns the last inserted ID
435
+/**
436
+ * Returns the last inserted ID.
437
+ * \param _h database handle
438
+ * \return returns the ID as integer or returns 0 if the previous statement
439
+ * does not use an AUTO_INCREMENT value.
412 440
  */
413 441
 int db_last_inserted_id(const db_con_t* _h)
414 442
 {
... ...
@@ -419,13 +447,13 @@ int db_last_inserted_id(const db_con_t* _h)
419 447
 	return mysql_insert_id(CON_CONNECTION(_h));
420 448
 }
421 449
 
422
- 
423
- /*
424
-  * Insert a row into specified table, update on duplicate key
425
-  * _h: structure representing database connection
426
-  * _k: key names
427
-  * _v: values of the keys
428
-  * _n: number of key=value pairs
450
+
451
+ /**
452
+  * Insert a row into a specified table, update on duplicate key.
453
+  * \param _h structure representing database connection
454
+  * \param _k key names
455
+  * \param _v values of the keys
456
+  * \param _n number of key=value pairs
429 457
  */
430 458
  int db_insert_update(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v,
431 459
 	const int _n)
... ...
@@ -479,9 +507,11 @@ error:
479 507
 }
480 508
 
481 509
 
482
-/*
483
- * Store name of table that will be used by
484
- * subsequent database functions
510
+/**
511
+ * Store the name of table that will be used by subsequent database functions
512
+ * \param _h database handle
513
+ * \param _t table name
514
+ * \return zero on success, negative value on failure
485 515
  */
486 516
 int db_mysql_use_table(db_con_t* _h, const str* _t)
487 517
 {
... ...
@@ -29,7 +29,7 @@
29 29
 #include "../../ut.h"
30 30
 
31 31
 
32
-/*
32
+/**
33 33
  * Create a new connection structure,
34 34
  * open the MySQL connection and set reference count to 1
35 35
  */
... ...
@@ -104,7 +104,7 @@ struct my_con* db_mysql_new_connection(const struct db_id* id)
104 104
 }
105 105
 
106 106
 
107
-/*
107
+/**
108 108
  * Close the connection and release memory
109 109
  */
110 110
 void db_mysql_free_connection(struct pool_con* con)
... ...
@@ -34,7 +34,7 @@
34 34
 #include "res.h"
35 35
 
36 36
 
37
-/*
37
+/**
38 38
  * Get and convert columns from a result
39 39
  */
40 40
 int db_mysql_get_columns(const db_con_t* _h, db_res_t* _r)
... ...
@@ -130,7 +130,7 @@ int db_mysql_get_columns(const db_con_t* _h, db_res_t* _r)
130 130
 }
131 131
 
132 132
 
133
-/*
133
+/**
134 134
  * Convert rows from mysql to db API representation
135 135
  */
136 136
 static inline int db_mysql_convert_rows(const db_con_t* _h, db_res_t* _r)
... ...
@@ -154,8 +154,7 @@ static inline int db_mysql_convert_rows(const db_con_t* _h, db_res_t* _r)
154 154
 		LM_ERR("no private memory left\n");
155 155
 		return -2;
156 156
 	}
157
-	LM_DBG("allocate %d bytes for rows at %p", len,
158
-			RES_ROWS(_r));
157
+	LM_DBG("allocate %d bytes for rows at %p", len, RES_ROWS(_r));
159 158
 	memset(RES_ROWS(_r), 0, len);
160 159
 
161 160
 	for(row = 0; row < RES_ROW_N(_r); row++) {
... ...
@@ -177,7 +176,7 @@ static inline int db_mysql_convert_rows(const db_con_t* _h, db_res_t* _r)
177 176
 }
178 177
 
179 178
 
180
-/*
179
+/**
181 180
  * Fill the structure with data from database
182 181
  */
183 182
 int db_mysql_convert_result(const db_con_t* _h, db_res_t* _r)
... ...
@@ -33,7 +33,7 @@
33 33
 #include "row.h"
34 34
 
35 35
 
36
-/*
36
+/**
37 37
  * Convert a row from result into db API representation
38 38
  */
39 39
 int db_mysql_convert_row(const db_con_t* _h, db_res_t* _res, db_row_t* _r)
... ...
@@ -31,7 +31,7 @@
31 31
 #include "../../db/db_row.h"
32 32
 
33 33
 
34
-/*
34
+/**
35 35
  * Convert a row from result into db API representation
36 36
  */
37 37
 int db_mysql_convert_row(const db_con_t* _h, db_res_t* _res, db_row_t* _r);
... ...
@@ -29,13 +29,13 @@
29 29
 #include "../../db/db.h"
30 30
 
31 31
 
32
-/*
32
+/**
33 33
  * Does not copy strings
34 34
  */
35 35
 int db_mysql_str2val(const db_type_t _t, db_val_t* _v, const char* _s, const int _l);
36 36
 
37 37
 
38
-/*
38
+/**
39 39
  * Used when converting result from a query
40 40
  */
41 41
 int db_mysql_val2str(const db_con_t* _con, const db_val_t* _v, char* _s, int* _len);