dispatcher: add ds_list full mi command, update documentation

optional parameter 'full' added for ds_list full, which will display
the weight, priority and description of a destination
role of weight and priority briefly explained in documentation, FAQ section

modules/dispatcher/README

@@ -866,7 +866,9 @@ _empty_line_
 
    Name: ds_list
 
-   Parameters: none
+   Parameters:
+     * full (optional) - adds the weight, priority and description
+       fields to the listing
 
    MI FIFO Command Format:
 :ds_list:_reply_fifo_file_
@@ -989,6 +991,26 @@ Chapter 2. Frequently Asked Questions
 
    2.4.
 
+       How is weight and priority used by the dispatcher in selecting
+       a destination?
+
+       The weight of a destination is currently used in the hashing
+       algorithms and it increases the probability of it to be
+       chosen(if we have two destinations with weights 1 respectively
+       4 than the second one is 4 times more likely to be selected
+       than the other). The sum of all weights does not need to add up
+       to a specific number. It is important to understand that the
+       weights are not used in the round-robin algorithm at the
+       moment.
+
+       The priority field is used at ordering the destinations from a
+       set. It does not affect the overall probability of a
+       destination to be chosen. It is reflected when listing the
+       destination, the field can definetly be used in further
+       selecting algorithms.
+
+   2.5.
+
        What happened with the list_file module parameter ?
 
        The support for text file (for provisioning destinations) was
@@ -997,13 +1019,13 @@ Chapter 2. Frequently Asked Questions
        provisioning, use db_text DB driver (DB emulated via text
        files)
 
-   2.5.
+   2.6.
 
        Where can I find more about OpenSIPS?
 
        Take a look at http://www.opensips.org/.
 
-   2.6.
+   2.7.
 
        Where can I post a question about this module?
 
@@ -1022,7 +1044,7 @@ Chapter 2. Frequently Asked Questions
        If you want to keep the mail private, send it to
        <users@lists.opensips.org>.
 
-   2.7.
+   2.8.
 
        How can I report a bug?
 

modules/dispatcher/dispatch.c

@@ -148,7 +148,7 @@ void ds_destroy_data(ds_partition_t *partition)
 
 
 int add_dest2list(int id, str uri, struct socket_info *sock, int state,
-							int weight, int prio, str attrs, ds_data_t *d_data)
+							int weight, int prio, str attrs, str description, ds_data_t *d_data)
 {
 	ds_dest_p dp = NULL;
 	ds_set_p  sp = NULL;
@@ -202,23 +202,26 @@ int add_dest2list(int id, str uri, struct socket_info *sock, int state,
 			&& puri.headers.len == 0) {
 
 		/* The uri from db is good for ds_select_dst */
-		dp->uri.s = shm_malloc(uri.len + 1 + attrs.len + 1);
+		dp->uri.s = shm_malloc(uri.len + 1 + attrs.len + 1 + description.len + 1);
 		if(dp->uri.s==NULL){
 			LM_ERR("no more shm memory!\n");
 			goto err;
 		}
 		dp->dst_uri = dp->uri;
 		dp->attrs.s = dp->uri.s + dp->uri.len + 1;
+		dp->description.s = dp->uri.s + dp->uri.len + 1 + attrs.len + 1;
 	}
 	else {
 		dp->dst_uri.len = uri_typestrlen(puri.type) + 1 + puri.host.len
 						+ (puri.port.len ? puri.port.len + 1 : 0);
-		dp->uri.s = shm_malloc(uri.len+1 + dp->dst_uri.len + 1 + attrs.len+1);
+		dp->uri.s = shm_malloc(uri.len+1 + dp->dst_uri.len + 1 + attrs.len+1
+								+ description.len + 1);
 		if(dp->uri.s==NULL){
 			LM_ERR("no more shm memory!\n");
 			goto err;
 		}
 
+		dp->description.s = dp->uri.s + dp->uri.len + 1 + dp->dst_uri.len + 1 + attrs.len + 1;
 		dp->attrs.s = dp->uri.s + dp->uri.len + 1 + dp->dst_uri.len + 1;
 		dp->dst_uri.s = dp->uri.s + dp->uri.len + 1;
 		char *p = uri_type2str(puri.type, dp->dst_uri.s);
@@ -243,6 +246,12 @@ int add_dest2list(int id, str uri, struct socket_info *sock, int state,
 	}
 	else dp->attrs.s = NULL;
 
+	if(description.len){
+		memcpy(dp->description.s, description.s, description.len);
+		dp->description.s[description.len]='\0';
+		dp->description.len = description.len;
+	}
+
 	/* copy state, weight & socket */
 	dp->sock = sock;
 	dp->weight = weight;
@@ -730,22 +739,23 @@ void ds_flusher_routine(unsigned int ticks, void* param)
 static ds_data_t* ds_load_data(ds_partition_t *partition, int use_state_col)
 {
 	ds_data_t *d_data;
-	int i, id, nr_rows, cnt, nr_cols = 7;
+	int i, id, nr_rows, cnt, nr_cols = 8;
 	int state;
 	int weight;
 	int prio;
 	struct socket_info *sock;
 	str uri;
 	str attrs;
 	str host;
+	str description;
 	int port, proto;
 	db_res_t * res = NULL;
 	db_val_t * values;
 	db_row_t * rows;
 
-	db_key_t query_cols[7] = {&ds_set_id_col, &ds_dest_uri_col,
+	db_key_t query_cols[8] = {&ds_set_id_col, &ds_dest_uri_col,
 			&ds_dest_sock_col, &ds_dest_weight_col, &ds_dest_attrs_col,
-			&ds_dest_prio_col, &ds_dest_state_col};
+			&ds_dest_prio_col, &ds_dest_description_col, &ds_dest_state_col};
 
 	if (!use_state_col)
 		nr_cols--;
@@ -836,13 +846,16 @@ static ds_data_t* ds_load_data(ds_partition_t *partition, int use_state_col)
 			prio = VAL_INT(values+5);
 
 		/* state */
-		if (!use_state_col || VAL_NULL(values+6))
+		if (!use_state_col || VAL_NULL(values+7))
 			/* active state */
 			state = 0;
 		else
-			state = VAL_INT(values+6);
+			state = VAL_INT(values+7);
 
-		if (add_dest2list(id, uri, sock, state, weight, prio, attrs, d_data)
+		get_str_from_dbval( "DESCIPTION", values+6,
+			0/*not_null*/, 0/*not_empty*/, description, error2);
+
+		if (add_dest2list(id, uri, sock, state, weight, prio, attrs, description, d_data)
 		!= 0) {
 			LM_WARN("failed to add destination <%.*s> in group %d\n",
 				uri.len,uri.s,id);
@@ -2043,7 +2056,7 @@ int ds_is_in_list(struct sip_msg *_m, gparam_t *gp_ip, gparam_t *gp_port,
 }
 
 
-int ds_print_mi_list(struct mi_node* rpl, ds_partition_t *partition)
+int ds_print_mi_list(struct mi_node* rpl, ds_partition_t *partition, int flags)
 {
 	int len, j;
 	char* p;
@@ -2110,6 +2123,27 @@ int ds_print_mi_list(struct mi_node* rpl, ds_partition_t *partition)
 				if(node1 == NULL)
 					goto error;
 			}
+
+			if (flags & 1) {
+				p = int2str(list->dlist[j].weight, &len);
+				node1= add_mi_node_child(node, MI_DUP_VALUE, "weight", 6,
+					p, len);
+				if(node1 == NULL)
+					goto error;
+
+				p = int2str(list->dlist[j].priority, &len);
+				node1 = add_mi_node_child(node, MI_DUP_VALUE, "priority", 8,
+					p, len);
+				if(node1 == NULL)
+					goto error;
+
+				if (list->dlist[j].description.len) {
+					node1= add_mi_node_child(node, MI_DUP_VALUE, "description", 11,
+						list->dlist[j].description.s, list->dlist[j].description.len);
+					if(node1 == NULL)
+						goto error;
+				}
+			}
 		}
 	}
 

modules/dispatcher/dispatch.h

@@ -76,6 +76,7 @@ typedef struct _ds_dest
 	str uri;
 	str dst_uri;    /* Actual uri used in ds_select_dst ds_select_domain */
 	str attrs;
+	str description;
 	int flags;
 	unsigned short weight;
 	unsigned short running_weight;
@@ -175,6 +176,7 @@ extern str ds_dest_state_col;
 extern str ds_dest_weight_col;
 extern str ds_dest_prio_col;
 extern str ds_dest_attrs_col;
+extern str ds_dest_description_col;
 
 extern pv_elem_t * hash_param_model;
 
@@ -204,7 +206,7 @@ int ds_next_dst(struct sip_msg *msg, int mode, ds_partition_t *partition);
 int ds_set_state(int group, str *address, int state, int type,
 		ds_partition_t *partition);
 int ds_mark_dst(struct sip_msg *msg, int mode, ds_partition_t *partition);
-int ds_print_mi_list(struct mi_node* rpl, ds_partition_t *partition);
+int ds_print_mi_list(struct mi_node* rpl, ds_partition_t *partition, int flags);
 int ds_count(struct sip_msg *msg, int set_id, const char *cmp, pv_spec_p ret,
 				ds_partition_t *partition);
 

modules/dispatcher/dispatcher.c

@@ -65,6 +65,7 @@
 #define DS_DEST_WEIGHT_COL	"weight"
 #define DS_DEST_PRIO_COL	"priority"
 #define DS_DEST_ATTRS_COL	"attrs"
+#define DS_DEST_DESCRIPTION_COL	"description"
 #define DS_TABLE_NAME 		"dispatcher"
 #define DS_PARTITION_DELIM  ':'
 
@@ -138,6 +139,7 @@ str ds_dest_state_col = str_init(DS_DEST_STATE_COL);
 str ds_dest_weight_col= str_init(DS_DEST_WEIGHT_COL);
 str ds_dest_prio_col = str_init(DS_DEST_PRIO_COL);
 str ds_dest_attrs_col = str_init(DS_DEST_ATTRS_COL);
+str ds_dest_description_col = str_init(DS_DEST_DESCRIPTION_COL);
 
 str ds_setid_pvname   = {NULL, 0};
 pv_spec_t ds_setid_pv;
@@ -243,6 +245,7 @@ static param_export_t params[]={
 	{"weight_col",      STR_PARAM, &ds_dest_weight_col.s},
 	{"priority_col",    STR_PARAM, &ds_dest_prio_col.s},
 	{"attrs_col",       STR_PARAM, &ds_dest_attrs_col.s},
+	{"description_col",       STR_PARAM, &ds_dest_description_col.s},
 	{"dst_avp",         STR_PARAM, &default_db_head.dst_avp.s},
 	{"grp_avp",         STR_PARAM, &default_db_head.grp_avp.s},
 	{"cnt_avp",         STR_PARAM, &default_db_head.cnt_avp.s},
@@ -273,7 +276,7 @@ static module_dependency_t *get_deps_ds_ping_interval(param_export_t *param)
 
 static mi_export_t mi_cmds[] = {
 	{ "ds_set_state",   0, ds_mi_set,     0,                0,  0            },
-	{ "ds_list",        0, ds_mi_list,    MI_NO_INPUT_FLAG, 0,  0            },
+	{ "ds_list",        0, ds_mi_list,    0,                0,  0            },
 	{ "ds_reload",      0, ds_mi_reload,  0,                0,  mi_child_init},
 	{ 0, 0, 0, 0, 0, 0}
 };
@@ -1353,6 +1356,15 @@ static struct mi_root* ds_mi_list(struct mi_root* cmd_tree, void* param)
 {
 	struct mi_root* rpl_tree;
 	struct mi_node* part_node;
+	int explicit = 0;
+
+	if (cmd_tree->node.kids){
+		if(cmd_tree->node.kids->value.len == 4 && memcmp(cmd_tree->node.kids->value.s,"full",4)==0)
+			explicit = 1;
+		else
+			return init_mi_tree(400, MI_SSTR(MI_BAD_PARM_S));
+
+	}
 
 	rpl_tree = init_mi_tree(200, MI_OK_S, MI_OK_LEN);
 	if (rpl_tree==NULL)
@@ -1365,7 +1377,7 @@ static struct mi_root* ds_mi_list(struct mi_root* cmd_tree, void* param)
 				9, part_it->name.s, part_it->name.len);
 
 		if (part_node == NULL
-			|| ds_print_mi_list(part_node, part_it) < 0) {
+			|| ds_print_mi_list(part_node, part_it, explicit) < 0) {
 		LM_ERR("failed to add node\n");
 		free_mi_tree(rpl_tree);
 		return 0;

modules/dispatcher/doc/dispatcher_admin.xml

@@ -1157,7 +1157,13 @@ _empty_line_
 		<para>
 		Name: <emphasis>ds_list</emphasis>
 		</para>
-		<para>Parameters: <emphasis>none</emphasis></para>
+		<para>Parameters:</para>
+		 <itemizedlist>
+			<listitem><para>
+				<emphasis>full</emphasis> (optional) - adds the weight,
+				priority and description fields to the listing
+			</para></listitem>
+		</itemizedlist>
 		<para>
 		MI FIFO Command Format:
 		</para>

modules/dispatcher/doc/dispatcher_faq.xml

@@ -50,6 +50,30 @@
 		</answer>
 	</qandaentry>
 
+	<qandaentry>
+		<question>
+			<para>How is weight and priority used by the dispatcher in selecting
+			a destination?</para>
+		</question>
+		<answer>
+			<para>
+			The <emphasis>weight</emphasis> of a destination is currently used in
+			the hashing algorithms and it increases the probability of it to be
+			chosen(if we have two destinations with weights 1 respectively
+			4 than the second one is 4 times more likely to be selected than the
+			other). The sum of all weights does not need to add up to a specific
+			number. It is important to understand that the weights are not used
+			in the round-robin algorithm at the moment.
+			</para>
+			<para>
+			The  <emphasis>priority</emphasis> field is used at ordering the
+			destinations from a set. It does not affect the overall probability
+			of a destination to be chosen.  It is reflected when listing the
+			destination, the field can definetly be used in further selecting algorithms.
+			</para>
+		</answer>
+	</qandaentry>
+
 	<qandaentry>
 		<question>
 			<para>What happened with the <emphasis>list_file</emphasis>