mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
289 lines
8.0 KiB
289 lines
8.0 KiB
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<section id="db_fifo" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<sectioninfo>
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>$Revision$</revnumber>
|
|
<date>$Date$</date>
|
|
</revision>
|
|
</revhistory>
|
|
</sectioninfo>
|
|
|
|
<title>Database FIFO interface</title>
|
|
|
|
<section id="db_fifo_intro">
|
|
<title>Introduction</title>
|
|
<para>
|
|
<application>SER</application> offers to its module developers a common
|
|
DataBase(DB) interface, disregarding the database implementation (mysql,
|
|
dbtext or postgres) that lays beneath it.
|
|
</para>
|
|
<para>
|
|
This feature is now extended and offered also to the
|
|
<application>SER</application> users/administrators by DataBase
|
|
<acronym>FIFO</acronym> Interface (or DB FIFO interface). So,
|
|
DB FIFO interface is an extension of the internal DB interface through the
|
|
FIFO server. Everybody from outside <application>SER</application> can
|
|
operate SER's database (for adding/removing users, for manipulating
|
|
aliases, access control wrights, etc) using the same FIFO commands
|
|
without caring about the database type that's used by SER.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="advantages">
|
|
<title>Advantages</title>
|
|
<para>
|
|
All external applications that need to work with SER's database (like
|
|
<application>serctl</application> or <application>serweb</application>)
|
|
can do so via DB FIFO interface without depending of a specific database
|
|
driver. No modifications will be required when a new type of database
|
|
will be added to <application>SER</application>.
|
|
</para>
|
|
<para>
|
|
Also, this approach, prevents any kind of confusion between the database
|
|
type used by <application>SER</application> and the one used by these
|
|
external applications. They will use automatically the same database as
|
|
<application>SER</application> is configure to use.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section id="limitations">
|
|
<title>Limitations</title>
|
|
<para>
|
|
DB FIFO interface is restricted to the limitation of the internal DB
|
|
interface.
|
|
</para>
|
|
<para>
|
|
Also the size (can fit on only one line) and the content (\n or \r
|
|
characters must be escaped) of a BLOB value is restricted.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="db_fifo_config">
|
|
<title>Configuration</title>
|
|
<para>
|
|
FIFO server presents is required, so configure in your config file the FIFO
|
|
file to be used by the <application>SER</application> FIFO server:
|
|
<programlisting>
|
|
fifo="/tmp/ser_fifo"
|
|
</programlisting>
|
|
To enable the DB FIFO interface, it's required to load at least one
|
|
database module (available for the moment are mysql, dbtext and postgres).
|
|
</para>
|
|
<para>
|
|
The database module that you want to use and the database configuration are
|
|
configured via parameter <varname>fifo_db_url</varname>:
|
|
<programlisting>
|
|
fifo_db_url="mysql:mysql_url"
|
|
fifo_db_url="dbtext:dbtext_url"
|
|
</programlisting>
|
|
The format of the database URL depends of the used database implementation
|
|
(see the documentation for each DB type).
|
|
</para>
|
|
<para><emphasis>
|
|
NOTE: be sure to load the module the is specified into fifo_db_url!
|
|
</emphasis></para>
|
|
<para>
|
|
If no fifo_db_url is specified or no appropriate DB module found, the
|
|
DB FIFO interface will be disabled.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section id="db_fifo_commands">
|
|
<title>DB FIFO commands</title>
|
|
<para>
|
|
From FIFO point of view, all DB FIFO commands are mapped with the
|
|
same name: <emphasis>DB</emphasis>. The first line of the command must
|
|
contain the name of the DB command. Available are:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>SELECT</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>UPDATE</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>INSERT</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>DELETE</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>RAW_QUERY</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>EAW_QUERY_RES</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
The grammar used in the commands definition can be found in next
|
|
section "DB FIFO grammar". The presence of the
|
|
<varname>reply_fifo_file</varname> in the FIFO command is
|
|
<emphasis>required</emphasis> for all commands.
|
|
</para>
|
|
|
|
<section>
|
|
<title><function>SELECT</function> command</title>
|
|
<para>
|
|
This function implements SELECT DB directive. Its syntax is:
|
|
<programlisting>
|
|
:DB:reply_fifo_file
|
|
select
|
|
[COLUMN]*
|
|
.
|
|
TABLE_NAME
|
|
[CVP]
|
|
.
|
|
</programlisting>
|
|
If no CVP line is present, the whole table.will be returned. If no
|
|
COLUMN line is given, all table columns will be found in the result.
|
|
</para>
|
|
<para>
|
|
The result of the query will be return via reply_fifo_file in one
|
|
raw per line format (only requested columns), the first line being
|
|
the head of the table. The <emphasis>NULL</emphasis> values will be
|
|
printed as "NULL".
|
|
</para>
|
|
</section>
|
|
|
|
<section id="insert">
|
|
<title><function>INSERT</function> command</title>
|
|
<para>
|
|
This function implements INSERT DB directive - inserts one row in
|
|
a table. Its syntax is:
|
|
<programlisting>
|
|
:DB:reply_fifo_file
|
|
insert
|
|
TABLE_NAME
|
|
[EQUAL_CVP]+
|
|
.
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Command returns nothing if success or, other way, an error message.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section id="update">
|
|
<title><function>UPDATE</function> command</title>
|
|
<para>
|
|
The function implements UPDATE DB directive - it is possible to
|
|
modify one or more rows in a table. Its syntax is:
|
|
<programlisting>
|
|
:DB:reply_fifo_file
|
|
update
|
|
[EQUAL_CVP]+
|
|
.
|
|
TABLE_NAME
|
|
[CVP]*
|
|
.
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Command returns nothing if success or, other way, an error message.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section id="delete">
|
|
<title><function>DELETE</function> command</title>
|
|
<para>
|
|
This function implements DELETE DB directive - it is possible to
|
|
delete one or more rows from a table. Its syntax is:
|
|
<programlisting>
|
|
:DB:reply_fifo_file
|
|
delete
|
|
TABLE_NAME
|
|
[CVP]*
|
|
.
|
|
</programlisting>
|
|
If CVP list contain <emphasis>no lines, all rows will be
|
|
deleted</emphasis> (table will be empty).
|
|
</para>
|
|
<para>
|
|
Command returns nothing if success or, other way, an error message.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section id="raw_query">
|
|
<title><function>RAW_QUERY</function> command</title>
|
|
<para>
|
|
This function sends a raw query directly to the database driver
|
|
without trying to understand the command. This command <emphasis>MUST
|
|
NOT</emphasis> generate any response. Otherwise, the database driver
|
|
can block or desynchronize (depending of the driver).
|
|
Its syntax is:
|
|
<programlisting>
|
|
:DB:reply_fifo_file
|
|
raw_query
|
|
(ASCII)+
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Command returns nothing if success or, other way, an error message.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section id="raw_query_res">
|
|
<title>
|
|
<function>RAW_QUERY_RES</function> command
|
|
</title>
|
|
<para>
|
|
This function sends a raw query directly to the database driver without
|
|
trying to understand the command. This command <emphasis>MUST
|
|
</emphasis> generate an response (even if an empty one). Otherwise,
|
|
the database driver can block or desynchronize (depending of the
|
|
driver). Its syntax is:
|
|
<programlisting>
|
|
:DB:reply_fifo_file
|
|
raw_query_res
|
|
(ASCII)+
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Command's output format is identical with the one from
|
|
<function>SELECT</function> command.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
<section id="db_fifo_grammar">
|
|
<title>DB FIFO grammar</title>
|
|
<programlisting>
|
|
<![CDATA[
|
|
COLUMN=(alfa-numeric|'_')+
|
|
|
|
GAP=' '|'\t'
|
|
|
|
DEF_OP='='|'<'|'>'|'>='|'<='
|
|
UNDEF_OP=(ASCII)+
|
|
CAST_OP="int"|"double"|"string"|"date"|"blob"|"bitmap"
|
|
|
|
INT_VAL=integer number
|
|
DOUBLE_VAL=float number
|
|
STRING_VAL='"' ASCII* '"'
|
|
DATE_VAL='<' YEAR '-' MONTH '-' DAY ' ' HOUR ':' MINS ':' SECS '>'
|
|
BLOB_VAL=STRING_VAL
|
|
BITMAP_VAL=INT_VAL
|
|
NULL_VAL="null"
|
|
|
|
VALUE=('['CAST_OP']')?(INT_VAL|DOUBLE_VAL|STRING_VAL|DATE_VAL|
|
|
BLOB_VAL|BITMAP_VAL|NULL_VAL)
|
|
|
|
CVP(column-value-pair)=
|
|
(COLUMN GAP* DEF_OP GAP* VALUE) | (COLUMN GAP+ UNDEF_OP GAP+ VALUE)
|
|
EQUAL-CVP(column-equal-value-pair)=
|
|
(COLUMN GAP* '=' GAP* VALUE)
|
|
]]>
|
|
</programlisting>
|
|
</section>
|
|
</section>
|