[SR-Dev] git:janakj/mysql: - add a comment about the NULL value behaviour of libmysql

[Jan Janak]

Module: sip-router
Branch: janakj/mysql
Commit: c56b4491a617caa82be13a8ed95949f04b7980f0
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=c56b4491a617caa82be13a8ed95949f04b7980f0

Author: Henning Westerholt <henning.westerholt at 1und1.de>
Committer: Henning Westerholt <henning.westerholt at 1und1.de>
Date:   Thu Nov 13 16:14:34 2008 +0000

- add a comment about the NULL value behaviour of libmysql
- add some doxygen documentation


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

---

 modules/db_mysql/km_val.c |   26 ++++++++++++++++++++------
 modules/db_mysql/km_val.h |   26 ++++++++++++++++++++------
 2 files changed, 40 insertions(+), 12 deletions(-)

diff --git a/modules/db_mysql/km_val.c b/modules/db_mysql/km_val.c
index 8cb485f..3af1e65 100644
--- a/modules/db_mysql/km_val.c
+++ b/modules/db_mysql/km_val.c
@@ -22,7 +22,7 @@
  */
 
 /*! \file
- *  \brief DB_MYSQL :: Data conversion
+ *  \brief DB_MYSQL :: Data conversions
  *  \ingroup db_mysql
  *  Module: \ref db_mysql
  */
@@ -36,8 +36,15 @@
 #include <stdio.h>
 
 
-/*! \brief
- * Convert str to db value, does not copy strings
+/*!
+ * \brief Convert a str to a db value, does not copy strings
+ *
+ * Convert a str to a db value, does not copy strings.
+ * \param _t destination value type
+ * \param _v destination value
+ * \param _s source string
+ * \param _l string length
+ * \return 0 on success, negative on error
  */
 int db_mysql_str2val(const db_type_t _t, db_val_t* _v, const char* _s, const int _l)
 {
@@ -47,7 +54,7 @@ int db_mysql_str2val(const db_type_t _t, db_val_t* _v, const char* _s, const int
 		LM_ERR("invalid parameter value\n");
 		return -1;
 	}
-
+	/* A NULL string is a NULL value in mysql, otherwise its an empty value */
 	if (!_s) {
 		memset(_v, 0, sizeof(db_val_t));
 			/* Initialize the string pointers to a dummy empty
@@ -143,8 +150,15 @@ int db_mysql_str2val(const db_type_t _t, db_val_t* _v, const char* _s, const int
 }
 
 
-/*! \brief
- * Used when converting result from a query
+/*!
+ * \brief Converting a value to a string
+ *
+ * Converting a value to a string, used when converting result from a query
+ * \param _c database connection
+ * \param _v source value
+ * \param _s target string
+ * \param _len target string length
+ * \return 0 on success, negative on error
  */
 int db_mysql_val2str(const db_con_t* _c, const db_val_t* _v, char* _s, int* _len)
 {
diff --git a/modules/db_mysql/km_val.h b/modules/db_mysql/km_val.h
index 4f034cc..f9cb609 100644
--- a/modules/db_mysql/km_val.h
+++ b/modules/db_mysql/km_val.h
@@ -22,7 +22,7 @@
  */
 
 /*! \file
- *  \brief DB_MYSQL :: Conversions
+ *  \brief DB_MYSQL :: Data conversions
  *  \ref val.c
  *  \ingroup db_mysql
  *  Module: \ref db_mysql
@@ -37,15 +37,29 @@
 #include "../../db/db.h"
 
 
-/**
- * Does not copy strings
+/*!
+ * \brief Convert a str to a db value, does not copy strings
+ *
+ * Convert a str to a db value, does not copy strings.
+ * \param _t destination value type
+ * \param _v destination value
+ * \param _s source string
+ * \param _l string length
+ * \return 0 on success, negative on error
  */
 int db_mysql_str2val(const db_type_t _t, db_val_t* _v, const char* _s, const int _l);
 
 
-/**
- * Used when converting result from a query
+/*!
+ * \brief Converting a value to a string
+ *
+ * Converting a value to a string, used when converting result from a query
+ * \param _c database connection
+ * \param _v source value
+ * \param _s target string
+ * \param _len target string length
+ * \return 0 on success, negative on error
  */
 int db_mysql_val2str(const db_con_t* _con, const db_val_t* _v, char* _s, int* _len);
 
-#endif /* VAL_H */
+#endif