osmo-hlr[master]: db api: fix/add API docs

2017-10-26 Thread Max 

Patch Set 2:

(1 comment)

https://gerrit.osmocom.org/#/c/4415/2/src/db_hlr.c
File src/db_hlr.c:

Line 85:  * \returns if the subscriber was found and removed, -EIO on database 
error,
0 is missing?


-- 
To view, visit https://gerrit.osmocom.org/4415
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: comment
Gerrit-Change-Id: I854fafd8e56bd0b8394f8ed79d023c11c2fdbdca
Gerrit-PatchSet: 2
Gerrit-Project: osmo-hlr
Gerrit-Branch: master
Gerrit-Owner: Neels Hofmeyr 
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: Max 
Gerrit-Reviewer: Neels Hofmeyr 
Gerrit-HasComments: Yes

[MERGED] osmo-hlr[master]: db api: fix/add API docs

2017-10-25 Thread Neels Hofmeyr 
Neels Hofmeyr has submitted this change and it was merged.

Change subject: db api: fix/add API docs
..


db api: fix/add API docs

Change-Id: I854fafd8e56bd0b8394f8ed79d023c11c2fdbdca
---
M src/db_hlr.c
1 file changed, 76 insertions(+), 13 deletions(-)

Approvals:
  Neels Hofmeyr: Looks good to me, approved
  Jenkins Builder: Verified



diff --git a/src/db_hlr.c b/src/db_hlr.c
index e8db7d2..ef01428 100644
--- a/src/db_hlr.c
+++ b/src/db_hlr.c
@@ -43,6 +43,11 @@
x[sizeof(x)-1] = '\0';  \
} while (0)
 
+/*! Add new subscriber record to the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] imsi  ASCII string of IMSI digits, is validated.
+ * \returns 0 on success, -EINVAL on invalid IMSI, -EIO on database error.
+ */
 int db_subscr_create(struct db_context *dbc, const char *imsi)
 {
sqlite3_stmt *stmt;
@@ -71,6 +76,15 @@
return 0;
 }
 
+/*! Completely delete a subscriber record from the HLR database.
+ * Also remove authentication data.
+ * Future todo: also drop from all other database tables, which aren't used yet
+ * at the time of writing this.
+ * \param[in,out] dbc  database context.
+ * \param[in] subscr_id  ID of the subscriber in the HLR db.
+ * \returns if the subscriber was found and removed, -EIO on database error,
+ *  -ENOENT if no such subscriber data exists.
+ */
 int db_subscr_delete_by_id(struct db_context *dbc, int64_t subscr_id)
 {
int rc;
@@ -127,6 +141,13 @@
return ret;
 }
 
+/*! Set a subscriber's MSISDN in the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] imsi  ASCII string of IMSI digits.
+ * \param[in] msisdn  ASCII string of MSISDN digits.
+ * \returns 0 on success, -EINVAL in case of invalid MSISDN string, -EIO on
+ *  database failure, -ENOENT if no such subscriber exists.
+ */
 int db_subscr_update_msisdn_by_imsi(struct db_context *dbc, const char *imsi,
const char *msisdn)
 {
@@ -175,14 +196,17 @@
 
 }
 
-/* Insert or update 2G or 3G authentication tokens in the database.
+/*! Insert or update 2G or 3G authentication tokens in the database.
  * If aud->type is OSMO_AUTH_TYPE_GSM, the auc_2g table entry for the
  * subscriber will be added or modified; if aud->algo is OSMO_AUTH_ALG_NONE,
  * however, the auc_2g entry for the subscriber is deleted. If aud->type is
  * OSMO_AUTH_TYPE_UMTS, the auc_3g table is updated; again, if aud->algo is
  * OSMO_AUTH_ALG_NONE, the auc_3g entry is deleted.
- * Returns 0 if successful, -EINVAL for unknown aud->type, -ENOENT for unknown
- * subscr_id, -EIO for SQL errors.
+ * \param[in,out] dbc  database context.
+ * \param[in] subscr_id  DB ID of the subscriber.
+ * \param[in] aud  Pointer to new auth data (in ASCII string form).
+ * \returns 0 on success, -EINVAL for invalid aud, -ENOENT for unknown
+ *  subscr_id, -EIO for database errors.
  */
 int db_subscr_update_aud_by_id(struct db_context *dbc, int64_t subscr_id,
   const struct sub_auth_data_str *aud)
@@ -417,6 +441,13 @@
return ret;
 }
 
+/*! Retrieve subscriber data from the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] imsi  ASCII string of IMSI digits.
+ * \param[out] subscr  place retrieved data in this struct.
+ * \returns 0 on success, -ENOENT if no such subscriber was found, -EIO on
+ *  database error.
+ */
 int db_subscr_get_by_imsi(struct db_context *dbc, const char *imsi,
  struct hlr_subscriber *subscr)
 {
@@ -434,6 +465,13 @@
return rc;
 }
 
+/*! Retrieve subscriber data from the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] msisdn  ASCII string of MSISDN digits.
+ * \param[out] subscr  place retrieved data in this struct.
+ * \returns 0 on success, -ENOENT if no such subscriber was found, -EIO on
+ *  database error.
+ */
 int db_subscr_get_by_msisdn(struct db_context *dbc, const char *msisdn,
struct hlr_subscriber *subscr)
 {
@@ -451,6 +489,13 @@
return rc;
 }
 
+/*! Retrieve subscriber data from the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] id  ID of the subscriber in the HLR db.
+ * \param[out] subscr  place retrieved data in this struct.
+ * \returns 0 on success, -ENOENT if no such subscriber was found, -EIO on
+ *  database error.
+ */
 int db_subscr_get_by_id(struct db_context *dbc, int64_t id,
struct hlr_subscriber *subscr)
 {
@@ -468,12 +513,14 @@
return rc;
 }
 
-/* Enable or disable PS or CS for a subscriber.
- * For the subscriber with the given imsi, set nam_ps (when is_ps == true) or
- * nam_cs (when is_ps == false) to nam_val in the database.
- * Returns 0 on success, -ENOENT when the given IMSI does not exist, -EINVAL if
- * the SQL statement could not be composed,

osmo-hlr[master]: db api: fix/add API docs

2017-10-25 Thread Neels Hofmeyr 

Patch Set 2: Code-Review+2

let me just apply this without causing review cycles.

-- 
To view, visit https://gerrit.osmocom.org/4415
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: comment
Gerrit-Change-Id: I854fafd8e56bd0b8394f8ed79d023c11c2fdbdca
Gerrit-PatchSet: 2
Gerrit-Project: osmo-hlr
Gerrit-Branch: master
Gerrit-Owner: Neels Hofmeyr 
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: Neels Hofmeyr 
Gerrit-HasComments: No

[PATCH] osmo-hlr[master]: db api: fix/add API docs

2017-10-25 Thread Neels Hofmeyr 
Hello Jenkins Builder,

I'd like you to reexamine a change.  Please visit

https://gerrit.osmocom.org/4415

to look at the new patch set (#2).

db api: fix/add API docs

Change-Id: I854fafd8e56bd0b8394f8ed79d023c11c2fdbdca
---
M src/db_hlr.c
1 file changed, 76 insertions(+), 13 deletions(-)


  git pull ssh://gerrit.osmocom.org:29418/osmo-hlr refs/changes/15/4415/2

diff --git a/src/db_hlr.c b/src/db_hlr.c
index e8db7d2..ef01428 100644
--- a/src/db_hlr.c
+++ b/src/db_hlr.c
@@ -43,6 +43,11 @@
x[sizeof(x)-1] = '\0';  \
} while (0)
 
+/*! Add new subscriber record to the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] imsi  ASCII string of IMSI digits, is validated.
+ * \returns 0 on success, -EINVAL on invalid IMSI, -EIO on database error.
+ */
 int db_subscr_create(struct db_context *dbc, const char *imsi)
 {
sqlite3_stmt *stmt;
@@ -71,6 +76,15 @@
return 0;
 }
 
+/*! Completely delete a subscriber record from the HLR database.
+ * Also remove authentication data.
+ * Future todo: also drop from all other database tables, which aren't used yet
+ * at the time of writing this.
+ * \param[in,out] dbc  database context.
+ * \param[in] subscr_id  ID of the subscriber in the HLR db.
+ * \returns if the subscriber was found and removed, -EIO on database error,
+ *  -ENOENT if no such subscriber data exists.
+ */
 int db_subscr_delete_by_id(struct db_context *dbc, int64_t subscr_id)
 {
int rc;
@@ -127,6 +141,13 @@
return ret;
 }
 
+/*! Set a subscriber's MSISDN in the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] imsi  ASCII string of IMSI digits.
+ * \param[in] msisdn  ASCII string of MSISDN digits.
+ * \returns 0 on success, -EINVAL in case of invalid MSISDN string, -EIO on
+ *  database failure, -ENOENT if no such subscriber exists.
+ */
 int db_subscr_update_msisdn_by_imsi(struct db_context *dbc, const char *imsi,
const char *msisdn)
 {
@@ -175,14 +196,17 @@
 
 }
 
-/* Insert or update 2G or 3G authentication tokens in the database.
+/*! Insert or update 2G or 3G authentication tokens in the database.
  * If aud->type is OSMO_AUTH_TYPE_GSM, the auc_2g table entry for the
  * subscriber will be added or modified; if aud->algo is OSMO_AUTH_ALG_NONE,
  * however, the auc_2g entry for the subscriber is deleted. If aud->type is
  * OSMO_AUTH_TYPE_UMTS, the auc_3g table is updated; again, if aud->algo is
  * OSMO_AUTH_ALG_NONE, the auc_3g entry is deleted.
- * Returns 0 if successful, -EINVAL for unknown aud->type, -ENOENT for unknown
- * subscr_id, -EIO for SQL errors.
+ * \param[in,out] dbc  database context.
+ * \param[in] subscr_id  DB ID of the subscriber.
+ * \param[in] aud  Pointer to new auth data (in ASCII string form).
+ * \returns 0 on success, -EINVAL for invalid aud, -ENOENT for unknown
+ *  subscr_id, -EIO for database errors.
  */
 int db_subscr_update_aud_by_id(struct db_context *dbc, int64_t subscr_id,
   const struct sub_auth_data_str *aud)
@@ -417,6 +441,13 @@
return ret;
 }
 
+/*! Retrieve subscriber data from the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] imsi  ASCII string of IMSI digits.
+ * \param[out] subscr  place retrieved data in this struct.
+ * \returns 0 on success, -ENOENT if no such subscriber was found, -EIO on
+ *  database error.
+ */
 int db_subscr_get_by_imsi(struct db_context *dbc, const char *imsi,
  struct hlr_subscriber *subscr)
 {
@@ -434,6 +465,13 @@
return rc;
 }
 
+/*! Retrieve subscriber data from the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] msisdn  ASCII string of MSISDN digits.
+ * \param[out] subscr  place retrieved data in this struct.
+ * \returns 0 on success, -ENOENT if no such subscriber was found, -EIO on
+ *  database error.
+ */
 int db_subscr_get_by_msisdn(struct db_context *dbc, const char *msisdn,
struct hlr_subscriber *subscr)
 {
@@ -451,6 +489,13 @@
return rc;
 }
 
+/*! Retrieve subscriber data from the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] id  ID of the subscriber in the HLR db.
+ * \param[out] subscr  place retrieved data in this struct.
+ * \returns 0 on success, -ENOENT if no such subscriber was found, -EIO on
+ *  database error.
+ */
 int db_subscr_get_by_id(struct db_context *dbc, int64_t id,
struct hlr_subscriber *subscr)
 {
@@ -468,12 +513,14 @@
return rc;
 }
 
-/* Enable or disable PS or CS for a subscriber.
- * For the subscriber with the given imsi, set nam_ps (when is_ps == true) or
- * nam_cs (when is_ps == false) to nam_val in the database.
- * Returns 0 on success, -ENOENT when the given IMSI does not exist, -EINVAL if
- * the SQL statement could not be composed, -ENOEXEC if running the SQL
- * statement

[PATCH] osmo-hlr[master]: db api: fix/add API docs

2017-10-25 Thread Neels Hofmeyr 

Review at  https://gerrit.osmocom.org/4415

db api: fix/add API docs

Change-Id: I854fafd8e56bd0b8394f8ed79d023c11c2fdbdca
---
M src/db_hlr.c
1 file changed, 76 insertions(+), 13 deletions(-)


  git pull ssh://gerrit.osmocom.org:29418/osmo-hlr refs/changes/15/4415/1

diff --git a/src/db_hlr.c b/src/db_hlr.c
index e8db7d2..73ff1f8 100644
--- a/src/db_hlr.c
+++ b/src/db_hlr.c
@@ -43,6 +43,11 @@
x[sizeof(x)-1] = '\0';  \
} while (0)
 
+/*! Add new subscriber record to the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] imsi  ASCII string of IMSI digits, is validated.
+ * \returns 0 on success, -EINVAL on invalid IMSI, -EIO on database error.
+ */
 int db_subscr_create(struct db_context *dbc, const char *imsi)
 {
sqlite3_stmt *stmt;
@@ -71,6 +76,15 @@
return 0;
 }
 
+/*! Completely delete a subscriber record from the HLR database.
+ * Also removes authentication data.
+ * Future todo: also drop from all other database tables, which aren't used yet
+ * at the time of writing this.
+ * \param[in,out] dbc  database context.
+ * \param[in] subscr_id  ID of the subscriber in the HLR db.
+ * \returns if the subscriber was found and removed, -EIO on database error,
+ *  -ENOENT if no such subscriber data exists.
+ */
 int db_subscr_delete_by_id(struct db_context *dbc, int64_t subscr_id)
 {
int rc;
@@ -127,6 +141,13 @@
return ret;
 }
 
+/*! Set a subscriber's MSISDN in the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] imsi  ASCII string of IMSI digits.
+ * \param[in] msisdn  ASCII string of MSISDN digits.
+ * \returns 0 on success, -EINVAL in case of invalid MSISDN string, -EIO on
+ *  database failure, -ENOENT if no such subscriber exists.
+ */
 int db_subscr_update_msisdn_by_imsi(struct db_context *dbc, const char *imsi,
const char *msisdn)
 {
@@ -175,14 +196,17 @@
 
 }
 
-/* Insert or update 2G or 3G authentication tokens in the database.
+/** Insert or update 2G or 3G authentication tokens in the database.
  * If aud->type is OSMO_AUTH_TYPE_GSM, the auc_2g table entry for the
  * subscriber will be added or modified; if aud->algo is OSMO_AUTH_ALG_NONE,
  * however, the auc_2g entry for the subscriber is deleted. If aud->type is
  * OSMO_AUTH_TYPE_UMTS, the auc_3g table is updated; again, if aud->algo is
  * OSMO_AUTH_ALG_NONE, the auc_3g entry is deleted.
- * Returns 0 if successful, -EINVAL for unknown aud->type, -ENOENT for unknown
- * subscr_id, -EIO for SQL errors.
+ * \param[in,out] dbc  database context.
+ * \param[in] subscr_id  DB ID of the subscriber.
+ * \param[in] aud  Pointer to new auth data (in ASCII string form).
+ * \returns 0 on success, -EINVAL for invalid aud, -ENOENT for unknown
+ *  subscr_id, -EIO for database errors.
  */
 int db_subscr_update_aud_by_id(struct db_context *dbc, int64_t subscr_id,
   const struct sub_auth_data_str *aud)
@@ -417,6 +441,13 @@
return ret;
 }
 
+/*! Retrieve subscriber data from the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] imsi  ASCII string of IMSI digits.
+ * \param[out] subscr  place retrieved data in this struct.
+ * \returns 0 on success, -ENOENT if no such subscriber was found, -EIO on
+ *  database error.
+ */
 int db_subscr_get_by_imsi(struct db_context *dbc, const char *imsi,
  struct hlr_subscriber *subscr)
 {
@@ -434,6 +465,13 @@
return rc;
 }
 
+/*! Retrieve subscriber data from the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] msisdn  ASCII string of MSISDN digits.
+ * \param[out] subscr  place retrieved data in this struct.
+ * \returns 0 on success, -ENOENT if no such subscriber was found, -EIO on
+ *  database error.
+ */
 int db_subscr_get_by_msisdn(struct db_context *dbc, const char *msisdn,
struct hlr_subscriber *subscr)
 {
@@ -451,6 +489,13 @@
return rc;
 }
 
+/*! Retrieve subscriber data from the HLR database.
+ * \param[in,out] dbc  database context.
+ * \param[in] id  ID of the subscriber in the HLR db.
+ * \param[out] subscr  place retrieved data in this struct.
+ * \returns 0 on success, -ENOENT if no such subscriber was found, -EIO on
+ *  database error.
+ */
 int db_subscr_get_by_id(struct db_context *dbc, int64_t id,
struct hlr_subscriber *subscr)
 {
@@ -468,12 +513,14 @@
return rc;
 }
 
-/* Enable or disable PS or CS for a subscriber.
- * For the subscriber with the given imsi, set nam_ps (when is_ps == true) or
- * nam_cs (when is_ps == false) to nam_val in the database.
- * Returns 0 on success, -ENOENT when the given IMSI does not exist, -EINVAL if
- * the SQL statement could not be composed, -ENOEXEC if running the SQL
- * statement failed, -EIO if the amount of rows modified is unexpected.
+/*! You should use hlr_subscr_nam()