c10rpc.xml

<chapter id="c10rpcmi">
	<title>RPC and MI Control Interfaces</title>
	<para>
		Control interfaces are channels to communicate with &kamailio; SIP server for
		administrative purposes. At this moment are two control interfaces:
	</para>
	<itemizedlist>
		<listitem>
			<para>
				MI - management interface - it is no longer the recommended control
				interface and it is planned to be obsoleted in the near future
			</para>
		</listitem>
		<listitem>
			<para>
				RPC - remote procedure call - a more standardized option to
				execute commands. It is the recommended control interface.
			</para>
		</listitem>
	</itemizedlist>
	<section id="c10rpc">
		<title>RPC Control Interface</title>
	<para>
		RPC is designed as scanner-printer communication channel - RPC commands will
		scan the input for parameters as needed and will print back.
	</para>
	<itemizedlist>
		<listitem>
			<para>
				fifo - (<ulink url="http://kamailio.org/docs/modules/3.2.x/modules/ctl.html">ctl module</ulink>)
				- the communication is done via FIFO file using a
				simple text-based, line oriented protocol.
			</para>
		</listitem>
		<listitem>
			<para>
				datagram - (<ulink url="http://kamailio.org/docs/modules/3.2.x/modules/ctl.html">ctl module</ulink>)
				- the communication is done via unix socket files
				or UDP sockets.
			</para>
		</listitem>
		<listitem>
			<para>
				tcp - (<ulink url="http://kamailio.org/docs/modules/3.2.x/modules/ctl.html">ctl module</ulink>)
				- the communication is done via unix socket files
				or TCP sockets.
			</para>
		</listitem>
		<listitem>
			<para>
				xmlrpc - (<ulink url="http://kamailio.org/docs/modules/3.2.x/modules/xmlrpc.html">xmlrpc module</ulink>)
				- the communication is done via XMLRPC
			</para>
		</listitem>
	</itemizedlist>
	<para>
		RPC API is very well documented at: 
		<ulink url="http://www.kamailio.org/docs/docbooks/3.2.x/rpc_api/rpc_api.html">http://www.kamailio.org/docs/docbooks/3.2.x/rpc_api/rpc_api.html</ulink>.
		We will show next just an example of implementing a RPC command:
		<emphasis>pkg.stats</emphasis> - dump usage statistics of PKG (private) memory,
		implemented in modules_k/kex.
	</para>
	<example id="c10rpc_command_code">
		<title>Example of RPC command - pkg.stats</title>

			<programlisting  format="linespecific">
<![CDATA[
...
/**
 *
 */
static const char* rpc_pkg_stats_doc[2] = {
	"Private memory (pkg) statistics per process",
	0
};

/**
 *
 */
int pkg_proc_get_pid_index(unsigned int pid)
{
	int i;
	for(i=0; i<_pkg_proc_stats_no; i++)
	{
		if(_pkg_proc_stats_list[i].pid == pid)
			return i;
	}
	return -1;
}

/**
 *
 */
static void rpc_pkg_stats(rpc_t* rpc, void* ctx)
{
	int i;
	int limit;
	int cval;
	str cname;
	void* th;
	int mode;

	if(_pkg_proc_stats_list==NULL)
	{
		rpc->fault(ctx, 500, "Not initialized");
		return;
	}
	i = 0;
	mode = 0;
	cval = 0;
	limit = _pkg_proc_stats_no;
	if (rpc->scan(ctx, "*S", &cname) == 1)
	{
		if(cname.len==3 && strncmp(cname.s, "pid", 3)==0)
			mode = 1;
		else if(cname.len==4 && strncmp(cname.s, "rank", 4)==0)
			mode = 2;
		else if(cname.len==5 && strncmp(cname.s, "index", 5)==0)
			mode = 3;
		else {
			rpc->fault(ctx, 500, "Invalid filter type");
			return;
		}

		if (rpc->scan(ctx, "d", &cval) < 1)
		{
			rpc->fault(ctx, 500, "One more parameter expected");
			return;
		}
		if(mode==1)
		{
			i = pkg_proc_get_pid_index((unsigned int)cval);
			if(i<0)
			{
				rpc->fault(ctx, 500, "No such pid");
				return;
			}
			limit = i + 1;
		} else if(mode==3) {
			i=cval;
			limit = i + 1;
		}
	}

	for(; i<limit; i++)
	{
		/* add entry node */
		if(mode!=2 || _pkg_proc_stats_list[i].rank==cval)
		{
			if (rpc->add(ctx, "{", &th) < 0)
			{
				rpc->fault(ctx, 500, "Internal error creating rpc");
				return;
			}
			if(rpc->struct_add(th, "dddddd",
							"entry",     i,
							"pid",       _pkg_proc_stats_list[i].pid,
							"rank",      _pkg_proc_stats_list[i].rank,
							"used",      _pkg_proc_stats_list[i].used,
							"free",      _pkg_proc_stats_list[i].available,
							"real_used", _pkg_proc_stats_list[i].real_used
						)<0)
			{
				rpc->fault(ctx, 500, "Internal error creating rpc");
				return;
			}
		}
	}
}

/**
 *
 */
rpc_export_t kex_pkg_rpc[] = {
	{"pkg.stats", rpc_pkg_stats,  rpc_pkg_stats_doc,       0},
	{0, 0, 0, 0}
};

/**
 *
 */
int pkg_proc_stats_init_rpc(void)
{
	if (rpc_register_array(kex_pkg_rpc)!=0)
	{
		LM_ERR("failed to register RPC commands\n");
		return -1;
	}
	return 0;
}
...
]]>
			</programlisting>
		</example>
		<para>
			To add new RPC commands to control interface, you have to register them. One
			option, which is used here, is to build an array with the new commands and
			the help messages for each one and the use rpc_register_array(...) function.
			You have the register the commands in mod_init() function - in our example
			it is done via pkg_proc_stats_init(), which is a wrapper function called from
			mod_init().
		</para>
		<para>
			pkg.stats commands has optional parameters, which can be used to specify the pid,
			internal rank or position in internal process table (index) of the application
			process for which to dump the private memory statistics. If there is no parameter
			given, the the statistics for all processes will be printed.
		</para>
		<para>
			The command itself is implemented in C function rpc_pkg_stats(...). In the first
			part, it reads the parameters. You can see there the search for optional
			parameter is done by using '*' in the front of the type of parameter (str):
		</para>
<programlisting  format="linespecific">
			rpc->scan(ctx, "*S", &amp;cname)
</programlisting>
		<para>
			If this parameter is found, then there has to be another one, which this time
			is no longer optional.
		</para>
<programlisting  format="linespecific">
			rpc->scan(ctx, "d", &amp;cval)
</programlisting>
		<para>
			Once input is read, follows the printing of the result in RPC structures. When
			kex module is loaded, one can use pkg.stats command via sercmd tool like:
		</para>
<programlisting  format="linespecific">
	sercmd pkg.stats
	sercmd pkg.stats index 2
	sercmd pkg.stats rank 4
	sercmd pkg.stats pid 8492
</programlisting>
	</section>
	<section id="c10mi">
		<title>MI - Management Interface</title>
	<para>
		The <emphasis role="strong">Management Interface</emphasis> is an abstract layer
		introduced to allow interaction between &kamailio; and external applications like
		shell terminal or web applications. It is an old alternative to RPC control interface,
		which is going to be obsoleted in the future.
	</para>
	<para>
		MI is built on a tree architecture - the input is parsed completely and stored as
		a tree in memory. The commands get access to the tree and build another tree with
		the response, which is then printed back to the transport layer.
	</para>
	<para>
		In the past, there were two ways to interact
		with such applications: via <emphasis role="strong">FIFO</emphasis> file
		and via <emphasis role="strong">unix sockets</emphasis>.
	</para>
	<para>
		<emphasis role="strong">MI</emphasis> came and introduced an abstractization between
		the transport and application levels. All MI commands are available for all
		available transports. At this moment the following transports are available:
	</para>
	<itemizedlist>
		<listitem>
			<para>
				fifo - (mi_fifo mofule) - the communication is done via FIFO file using a
				simple text-based, line oriented protocol.
			</para>
		</listitem>
		<listitem>
			<para>
				xmlrpc - (mi_xmlrpc) - the communication is done via XMLRPC
			</para>
		</listitem>
		<listitem>
			<para>
				datagram - (mi_datagram) - the communication is done via unix socket files
				or UDP sockets.
			</para>
		</listitem>
	</itemizedlist>
	<para>
		To implement a new command for <emphasis role="strong">MI</emphasis> you don't need
		to interact with the transports. <emphasis role="strong">MI</emphasis> will pass to
		your function a compiled version of the command, in the form of a tree. The functions
		walks through the tree, finds the input parameters, executes the actions accordingly,
		and returns a new <emphasis role="strong">MI</emphasis> tree with the response to
		the command.
	</para>
	<section id="c10mi_command_function">
		<title>MI Command Function</title>
		<para>
			The function you have to implement for a new <emphasis role="strong">MI</emphasis>
			command has a simple prototype.
		</para>
		<programlisting  format="linespecific">
...
struct mi_root my_my_function(struct mi_root *tree, void *param);
...
		</programlisting>
		<para>
			Parameters:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					tree - the tree with the input parameters sent via the transport layer.
					The <emphasis role="strong">struct mi_root</emphasis> is defined in
					<emphasis role="strong">mi/three.h</emphasis>.
				</para>
<programlisting  format="linespecific">
...
struct mi_node {
	str value;                   /* value of node (parameter) */
	str name;                    /* name of node (parameter) */
	struct mi_node *kids;        /* children nodes */
	struct mi_node *next;        /* sibling nodes */
	struct mi_node *last;        /* last node */
	struct mi_attr *attributes;  /* the attributes of the node */
};

struct mi_root {
	unsigned int       code;       /* return code of the command */
	str                reason;     /* reason code */
	struct mi_handler  *async_hdl; /* handler function for asynchronous replying */
	struct mi_node     node;       /* head of the tree with parameters (nodes) */
};
...
				</programlisting>
			</listitem>
			<listitem>
				<para>
					param - parameter given when registering the command to
					<emphasis role="strong">MI</emphasis>.
				</para>
			</listitem>
		</itemizedlist>
		<para>
			Returns a tree containing the response to be send back for that command or NULL in
			case of error.
		</para>
	</section>
	<section id="c10register_command">
		<title>Register MI Command</title>
		<para>
			It is recommended to register new <emphasis role="strong">MI</emphasis> commands via
			&kamailio; module interface - described later, in the chapted about
			<emphasis role="strong">module development</emphasis>.
		</para>
		<para>
			The alternative is to use <emphasis role="strong">register_mi_cmd(...)</emphasis>,
			defined in file <emphasis role="strong">mi/mi.h</emphasis>.
		</para>
<programlisting  format="linespecific">
...
typedef struct mi_root* (mi_cmd_f)(struct mi_root*, void *param);
typedef int (mi_child_init_f)(void);

int register_mi_cmd(mi_cmd_f f, char *name, void *param,
		mi_child_init_f in, unsigned int flags);
...
		</programlisting>
		<para>
			Parameters:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					f - function to be called when the command is received from the transport layer
				</para>
			</listitem>
			<listitem>
				<para>
					name - the name of the command
				</para>
			</listitem>
			<listitem>
				<para>
					param - parameter to be given when function is executed
				</para>
			</listitem>
			<listitem>
				<para>
					in - function to be executed at &kamailio; initialization time
				</para>
			</listitem>
			<listitem>
				<para>
					flags - set of flags describing properties of the command
				</para>
				<programlisting  format="linespecific">
...
#define MI_ASYNC_RPL_FLAG   (1&lt;&lt;0) // - the reply to command is asynchronous
#define MI_NO_INPUT_FLAG    (1&lt;&lt;1) // - the command does not get any input parameters
...
				</programlisting>
			</listitem>
		</itemizedlist>
		<para>
			Returns 0 if the MI command was successfully registered, &lt;0 in case of error.
		</para>
	</section>
	<section id="c10example">
		<title>Example of MI Command Function</title>
		<para>
			We look at a MI command exported by <emphasis role="strong">dispatcher</emphasis>
			module. The command allow to set the state (active/inactive) for a destination
			address in the dispatching list (read documentation for
			<emphasis role="strong">dispatcher</emphasis> module).
		</para>
		<para>
			The command expects 3 parameters:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					state - the state to set to the destination address
				</para>
			</listitem>
			<listitem>
				<para>
					group - the id of the group (destination set) the destination belongs to
				</para>
			</listitem>
			<listitem>
				<para>
					address - the address of the destination to change the state for it
				</para>
			</listitem>
		</itemizedlist>
		<para>
			The function expects to find in the input tree, one flag (state), one number (group)
			and a string (the address). If not, an reply containing error message is sent back.
			If the parameters are ok and the destination is found, the state is changed accordingly
			and successful code and message is sent back, in not, an appropriate error code and
			message is sent back.
		</para>
		<para>
			Code is shown below (in the sources look in file
			<emphasis role="strong">modules/dispatcher/dispatcher.c</emphasis>).
		</para>
		<programlisting  format="linespecific">
<![CDATA[
...
static struct mi_root* ds_mi_set(struct mi_root* cmd_tree, void* param)
{
	str sp;
	int ret;
	unsigned int group, state;
	struct mi_node* node;

	node = cmd_tree->node.kids;
	if(node == NULL)
		return init_mi_tree(400, MI_MISSING_PARM_S, MI_MISSING_PARM_LEN);
	sp = node->value;
	if(sp.len<=0 || !sp.s)
	{
		LM_ERR("bad state value\n");
		return init_mi_tree(500, "bad state value", 15);
	}

	state = 0;
	if(sp.s[0]=='0' || sp.s[0]=='I' || sp.s[0]=='i') {
		/* set inactive */
		state |= DS_INACTIVE_DST;
		if((sp.len>1) && (sp.s[1]=='P' || sp.s[1]=='p'))
			state |= DS_PROBING_DST;
	} else if(sp.s[0]=='1' || sp.s[0]=='A' || sp.s[0]=='a') {
		/* set active */
		if((sp.len>1) && (sp.s[1]=='P' || sp.s[1]=='p'))
			state |= DS_PROBING_DST;
	} else if(sp.s[0]=='2' || sp.s[0]=='D' || sp.s[0]=='d') {
		/* set disabled */
		state |= DS_DISABLED_DST;
	} else if(sp.s[0]=='3' || sp.s[0]=='T' || sp.s[0]=='t') {
		/* set trying */
		state |= DS_TRYING_DST;
		if((sp.len>1) && (sp.s[1]=='P' || sp.s[1]=='p'))
			state |= DS_PROBING_DST;
	} else {
		LM_ERR("unknow state value\n");
		return init_mi_tree(500, "unknown state value", 19);
	}
	node = node->next;
	if(node == NULL)
		return init_mi_tree(400, MI_MISSING_PARM_S, MI_MISSING_PARM_LEN);
	sp = node->value;
	if(sp.s == NULL)
	{
		return init_mi_tree(500, "group not found", 15);
	}

	if(str2int(&sp, &group))
	{
		LM_ERR("bad group value\n");
		return init_mi_tree( 500, "bad group value", 16);
	}

	node= node->next;
	if(node == NULL)
		return init_mi_tree( 400, MI_MISSING_PARM_S, MI_MISSING_PARM_LEN);

	sp = node->value;
	if(sp.s == NULL)
	{
		return init_mi_tree(500,"address not found", 18 );
	}

	ret = ds_reinit_state(group, &sp, state);

	if(ret!=0)
	{
		return init_mi_tree(404, "destination not found", 21);
	}

	return init_mi_tree( 200, MI_OK_S, MI_OK_LEN);
}
...
]]>
		</programlisting>
	</section>
	<section id="c10mi_fifo_command">
		<title>MI FIFO Command</title>
		<para>
			The structure of the command that has to be sent to transport layer depends
			on the implementation. Check the documentation of the modules implementing the
			MI transports.
		</para>
		<para>
			For FIFO, the structure is line oriented, command being plain text.
		</para>
		<programlisting  format="linespecific">
...
:_command_name_:_reply_fifo_file_
_parameters_
_empty_line_
...
		</programlisting>
		<para>
			MI FIFO command structure:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					_command_name_ - the name of the command
				</para>
			</listitem>
			<listitem>
				<para>
					_reply_fifo_file_ - the FIFO file where to write the reply message
				</para>
			</listitem>
			<listitem>
				<para>
					_parameters_ - values for parameters, one per line
				</para>
			</listitem>
			<listitem>
				<para>
					_empty_line_ - an empty line to mark the end of the command
				</para>
			</listitem>
		</itemizedlist>
		<para>
			For the command described in the previous section, it can look like:
		</para>
		<programlisting  format="linespecific">
...
:ds_set_state:kamailio_fifo_reply
i
2
sip:10.10.10.10:5080
\n
...
		</programlisting>
	</section>
	</section>
</chapter>