usrloc: Fully document the module API

(cherry picked from commit 107b6fa)

modules/usrloc/dlist.c

@@ -798,29 +798,8 @@ get_domain_mem_ucontacts(udomain_t *d,void *buf, int *len, unsigned int flags,
 
 /*! \brief
  * Return list of all contacts for all currently registered
- * users in all domains. Caller must provide a buffer of
- * sufficient length to fit all those contacts. If the buffer
- * is exhausted, the function returns the estimated amount
- * of additional space needed. In this case the caller is
- * expected to repeat the call using this value as the hint.
- *
- * Information is packed into the buffer as follows:
- *
- * +------------+----------+---------+-------+------------+--------+--------+---------------+
- * |int         |char[]    |int      |char[] |socket_info*|unsigned|proxy_l |uint64         |
- * +============+==========+=========+=======+============+========+========+===============+
- * |contact1.len|contact1.s|path1.len|path1.s|sock1       |dbflags |next_hop|contact_coords1|
- * +------------+----------+---------+-------+------------+--------+--------+---------------+
- * |contact2.len|contact2.s|path2.len|path2.s|sock2       |dbflags |next_hop|contact_coords2|
- * +------------+----------+---------+-------+------------+--------+--------+---------------+
- * |........................................................................................|
- * +------------+----------+---------+-------+------------+--------+--------+---------------+
- * |contactN.len|contactN.s|pathN.len|pathN.s|sockN       |dbflags |next_hop|contact_coordsN|
- * +------------+----------+---------+-------+------------+--------+--------+---------------+
- * |000000000000|
- * +------------+
- *
- * if @pack_coords is false, all "contact_coordsX" parts will be omitted
+ * users in all currently defined domains.  The packed data format is identical
+ * to @get_domain_ucontacts.
  */
 int get_all_ucontacts(void *buf, int len, unsigned int flags,
                  unsigned int part_idx, unsigned int part_max, int pack_coords)
@@ -1192,7 +1171,7 @@ int cdb_delete_ucontact_coords(ucontact_sip_coords *sip_key)
 }
 
 int delete_ucontact_from_coords(udomain_t *d, ucontact_coords ct_coords,
-                                char is_replicated)
+                                char skip_replication)
 {
 	ucontact_t *c, virt_c;
 	urecord_t *r;
@@ -1225,7 +1204,7 @@ int delete_ucontact_from_coords(udomain_t *d, ucontact_coords ct_coords,
 		return 0;
 	}
 
-	if (!is_replicated && location_cluster)
+	if (!skip_replication && location_cluster)
 		replicate_ucontact_delete(r, c);
 
 	if (exists_ulcb_type(UL_CONTACT_DELETE)) {

modules/usrloc/dlist.h

@@ -59,7 +59,6 @@ extern dlist_t* root;
  * will be returned, otherwise a new domain will be
  * created
  */
-typedef int (*register_udomain_t)(const char* _n, udomain_t** _d);
 int register_udomain(const char* _n, udomain_t** _d);
 
 
@@ -78,17 +77,12 @@ int _synchronize_all_udomains(void);
 /*! \brief
  * Get contacts to all registered users
  */
-typedef int  (*get_all_ucontacts_t) (void* buf, int len, unsigned int flags,
-		unsigned int part_idx, unsigned int part_max, int pack_cid);
 int get_all_ucontacts(void *, int, unsigned int,
 		unsigned int part_idx, unsigned int part_max, int pack_cid);
 
 /*! \brief
  * Get contacts structures to all registered users
  */
-typedef int  (*get_domain_ucontacts_t) (udomain_t *d, void* buf, int len,
-		unsigned int flags, unsigned int part_idx, unsigned int part_max,
-		int pack_cid);
 int get_domain_ucontacts(udomain_t *d,void *buf, int len, unsigned int flags,
 					unsigned int part_idx, unsigned int part_max, int pack_cid);
 
@@ -107,7 +101,6 @@ int find_domain(str* _d, udomain_t** _p);
 /*! \brief
  * Returnes the next udomain, following the given one (as param)
  */
-typedef udomain_t* (*get_next_udomain_t) (udomain_t* _d);
 udomain_t* get_next_udomain(udomain_t *_d);
 
 /* when using various DBs (SQL/NoSQL) in order to store AoR hashes, it's best
@@ -146,16 +139,12 @@ unpack_indexes(uint64_t v,
 	*aorhash = (v >> 46);
 }
 
-typedef int (*delete_ucontact_from_coords_t)(udomain_t *d,
-                   ucontact_coords ct_coords, char is_replicated);
 int delete_ucontact_from_coords(udomain_t *d,
-		ucontact_coords ct_coords, char is_replicated);
+		ucontact_coords ct_coords, char skip_replication);
 
 /*
- * update sipping latancy
+ * update sipping latency
  */
-typedef int (*update_sipping_latency_t)(udomain_t *d,
-                    ucontact_coords ct_coords, int sipping_latency);
 int update_sipping_latency(udomain_t *d, ucontact_coords ct_coords,
                            int sipping_latency);
 

modules/usrloc/ucontact.c

@@ -966,7 +966,7 @@ static inline void update_contact_pos(struct urecord* _r, ucontact_t* _c)
  * Update ucontact with new values
  */
 int update_ucontact(struct urecord* _r, ucontact_t* _c, ucontact_info_t* _ci,
-															char is_replicated)
+															char skip_replication)
 {
 	int ret, persist_kv_store = 1;
 
@@ -977,10 +977,10 @@ int update_ucontact(struct urecord* _r, ucontact_t* _c, ucontact_info_t* _ci,
 		return -1;
 	}
 
-	if (is_replicated && _c->kv_storage)
+	if (skip_replication && _c->kv_storage)
 		restore_urecord_kv_store(_r, _c);
 
-	if (!is_replicated && have_data_replication()) {
+	if (!skip_replication && have_data_replication()) {
 		if (persist_urecord_kv_store(_r) != 0)
 			LM_ERR("failed to persist latest urecord K/V storage\n");
 		else

modules/usrloc/ucontact.h

@@ -299,20 +299,15 @@ struct urecord;
 /*! \brief
  * Update ucontact with new values
  */
-typedef int (*update_ucontact_t)(struct urecord* _r, ucontact_t* _c,
-		ucontact_info_t* _ci, char is_replicated);
-
 int update_ucontact(struct urecord* _r, ucontact_t* _c, ucontact_info_t* _ci,
-                    char is_replicated);
+                    char skip_replication);
 
 /*! \brief
  * Fetch a key from the contact-level storage
  * NOTE: assumes the corresponding udomain lock is properly acquired
  *
  * Returns: NULL on error/key not found, value pointer otherwise
  */
-typedef int_str_t *(*get_ucontact_key_t)(ucontact_t* _ct, const str* _key);
-
 int_str_t *get_ucontact_key(ucontact_t* _ct, const str* _key);
 
 /*! \brief
@@ -323,9 +318,6 @@ int_str_t *get_ucontact_key(ucontact_t* _ct, const str* _key);
  *
  * Returns: NULL on error, new value pointer otherwise
  */
-typedef int_str_t *(*put_ucontact_key_t)(ucontact_t* _ct,
-                                    const str* _key, const int_str_t* _val);
-
 int_str_t *put_ucontact_key(ucontact_t* _ct, const str* _key,
                             const int_str_t* _val);
 

modules/usrloc/udomain.c

@@ -1352,19 +1352,17 @@ int cdb_update_urecord_metadata(const str *_aor, int unpublish)
 
 /*! \brief
  * Create and insert a new record
- * after inserting and urecord one must populate the
- * label field outside this function
  */
 int insert_urecord(udomain_t* _d, str* _aor, struct urecord** _r,
-                   char is_replicated)
+                   char skip_replication)
 {
 	if (have_mem_storage()) {
 		if (mem_insert_urecord(_d, _aor, _r) < 0) {
 			LM_ERR("inserting record failed\n");
 			return -1;
 		}
 
-		if (!is_replicated) {
+		if (!skip_replication) {
 			init_urecord_labels(*_r, _d);
 
 			if (cluster_mode == CM_FEDERATION_CACHEDB
@@ -1481,7 +1479,7 @@ int get_global_urecord(udomain_t* _d, str* _aor, struct urecord** _r)
  * Delete a urecord from domain
  */
 int delete_urecord(udomain_t* _d, str* _aor, struct urecord* _r,
-                   char is_replicated)
+                   char skip_replication)
 {
 	struct ucontact* c, *t;
 
@@ -1507,7 +1505,7 @@ int delete_urecord(udomain_t* _d, str* _aor, struct urecord* _r,
 		return 0;
 
 	case CM_FEDERATION_CACHEDB:
-		if (!is_replicated && cdb_update_urecord_metadata(_aor, 1) != 0)
+		if (!skip_replication && cdb_update_urecord_metadata(_aor, 1) != 0)
 			LM_ERR("failed to delete metadata, aor: %.*s\n",
 			       _aor->len, _aor->s);
 		break;
@@ -1526,7 +1524,7 @@ int delete_urecord(udomain_t* _d, str* _aor, struct urecord* _r,
 	while(c) {
 		t = c;
 		c = c->next;
-		if (delete_ucontact(_r, t, is_replicated) < 0) {
+		if (delete_ucontact(_r, t, skip_replication) < 0) {
 			LM_ERR("deleting contact failed\n");
 			return -1;
 		}
@@ -1535,10 +1533,10 @@ int delete_urecord(udomain_t* _d, str* _aor, struct urecord* _r,
 	if (_r->no_clear_ref > 0)
 		return 0;
 
-	if (!is_replicated && location_cluster)
+	if (!skip_replication && location_cluster)
 		replicate_urecord_delete(_r);
 
-	release_urecord(_r, is_replicated);
+	release_urecord(_r, skip_replication);
 	return 0;
 }
 

modules/usrloc/udomain.h

@@ -120,29 +120,25 @@ void mem_delete_urecord(udomain_t* _d, struct urecord* _r);
 /*! \brief
  * Locks the domain hash entrie corresponding to AOR
  */
-typedef void (*lock_udomain_t)(udomain_t* _d, str *_aor);
 void lock_udomain(udomain_t* _d, str *_aor);
 
 
 /*! \brief
  *  Unlocks the domain hash entrie corresponding to AOR
  */
-typedef void (*unlock_udomain_t)(udomain_t* _d, str *_aor);
 void unlock_udomain(udomain_t* _d, str *_aor);
 
 struct ucontact* get_ucontact_from_id(udomain_t *d, uint64_t contact_id, struct urecord **_r);
 
 /*! \brief
  * Locks the specific domain hash entrie
  */
-typedef void (*lock_ulslot_t)(udomain_t* _d, int slot);
 void lock_ulslot(udomain_t* _d, int slot);
 
 
 /*! \brief
  * Unlocks the specific domain hash entrie
  */
-typedef void (*unlock_ulslot_t)(udomain_t* _d, int slot);
 void unlock_ulslot(udomain_t* _d, int slot);
 #define _unlock_ulslot(domain, contact_id) \
 	do { \
@@ -158,23 +154,18 @@ void unlock_ulslot(udomain_t* _d, int slot);
 /*! \brief
  * Create and insert a new record
  */
-typedef int (*insert_urecord_t)(udomain_t* _d, str* _aor, struct urecord** _r,
-                                char is_replicated);
 int insert_urecord(udomain_t* _d, str* _aor, struct urecord** _r,
-                   char is_replicated);
+                   char skip_replication);
 
 /*! \brief
  * Obtain a urecord pointer if the urecord exists in domain
  */
-typedef int  (*get_urecord_t)(udomain_t* _d, str* _a, struct urecord** _r);
 int get_urecord(udomain_t* _d, str* _aor, struct urecord** _r);
 
 /*! \brief
  * Only relevant in a federation @cluster_mode.
  * Obtain urecord pointer if AoR exists in at least one location.
  */
-typedef int
-(*get_global_urecord_t)(udomain_t* _d, str* _a, struct urecord** _r);
 int get_global_urecord(udomain_t* _d, str* _aor, struct urecord** _r);
 
 int cdb_update_urecord_metadata(const str *_aor, int unpublish);
@@ -183,9 +174,7 @@ int cdb_update_urecord_metadata(const str *_aor, int unpublish);
 /*! \brief
  * Delete a urecord from domain
  */
-typedef int  (*delete_urecord_t)(udomain_t* _d, str* _a, struct urecord* _r,
-                                 char is_replicated);
 int delete_urecord(udomain_t* _d, str* _aor, struct urecord* _r,
-                   char is_replicated);
+                   char skip_replication);
 
 #endif /* UDOMAIN_H */

modules/usrloc/ul_callback.c

@@ -113,5 +113,5 @@ int register_ulcb(ul_cb_type types, ul_cb f)
 
 	cbp->types = types;
 
-	return 1;
+	return 0;
 }

modules/usrloc/ul_callback.h

@@ -61,8 +61,6 @@ typedef enum ul_cb_types {
  * @type:    type of the callback
  */
 typedef void (ul_cb) (void *binding, ul_cb_type type);
-/*! \brief register callback function prototype */
-typedef int (*register_ulcb_t)(ul_cb_type types, ul_cb f);
 
 
 struct ul_callback {

modules/usrloc/urecord.c

@@ -808,7 +808,7 @@ static int cdb_build_ucontact_key(str* _ct, ucontact_info_t* _ci)
  * Release urecord previously obtained
  * through get_urecord
  */
-void release_urecord(urecord_t* _r, char is_replicated)
+void release_urecord(urecord_t* _r, char skip_replication)
 {
 	switch (cluster_mode) {
 	case CM_SQL_ONLY:
@@ -830,7 +830,7 @@ void release_urecord(urecord_t* _r, char is_replicated)
 		if (exists_ulcb_type(UL_AOR_DELETE))
 			run_ul_callbacks(UL_AOR_DELETE, _r);
 
-		if (!is_replicated && location_cluster) {
+		if (!skip_replication && location_cluster) {
 			if (cluster_mode == CM_FEDERATION_CACHEDB &&
 			    cdb_update_urecord_metadata(&_r->aor, 1) != 0)
 				LM_ERR("failed to delete metadata, aor: %.*s\n",
@@ -849,7 +849,7 @@ void release_urecord(urecord_t* _r, char is_replicated)
  * into urecord
  */
 int insert_ucontact(urecord_t* _r, str* _contact, ucontact_info_t* _ci,
-										ucontact_t** _c, char is_replicated)
+										ucontact_t** _c, char skip_replication)
 {
 	int first_contact = !_r->contacts;
 
@@ -874,7 +874,7 @@ int insert_ucontact(urecord_t* _r, str* _contact, ucontact_info_t* _ci,
 		return -1;
 	}
 
-	if (!is_replicated && have_data_replication())
+	if (!skip_replication && have_data_replication())
 		replicate_ucontact_insert(_r, _contact, *_c);
 
 	if (exists_ulcb_type(UL_CONTACT_INSERT))
@@ -901,9 +901,9 @@ int insert_ucontact(urecord_t* _r, str* _contact, ucontact_info_t* _ci,
 /*! \brief
  * Delete ucontact from urecord
  */
-int delete_ucontact(urecord_t* _r, struct ucontact* _c, char is_replicated)
+int delete_ucontact(urecord_t* _r, struct ucontact* _c, char skip_replication)
 {
-	if (!is_replicated && have_data_replication())
+	if (!skip_replication && have_data_replication())
 		replicate_ucontact_delete(_r, _c);
 
 	if (exists_ulcb_type(UL_CONTACT_DELETE))