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.
287 lines
9.4 KiB
287 lines
9.4 KiB
Perl Virtual Database Module
|
|
|
|
Bastian Friedrich
|
|
|
|
Collax GmbH
|
|
|
|
Edited by
|
|
|
|
Bastian Friedrich
|
|
|
|
Copyright © 2007 Collax GmbH
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
4. Functions
|
|
|
|
2. Developer Guide
|
|
|
|
1. Introduction
|
|
2. Base class Kamailio::VDB
|
|
3. Data types
|
|
|
|
3.1. Kamailio::VDB::Value
|
|
3.2. Kamailio::VDB::Pair
|
|
3.3. Kamailio::VDB::ReqCond
|
|
3.4. Kamailio::VDB::Column
|
|
3.5. Kamailio::VDB::Result
|
|
|
|
4. Adapters
|
|
|
|
4.1. Function parameters
|
|
|
|
5. VTabs
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
4. Functions
|
|
|
|
1. Overview
|
|
|
|
The Perl Virtual Database (VDB) provides a virtualization framework for
|
|
Kamailio's database access. It does not handle a particular database
|
|
engine itself but lets the user relay database requests to arbitrary
|
|
Perl functions.
|
|
|
|
This module cannot be used "out of the box". The user has to supply
|
|
functionality dedicated to the client module. See below for options.
|
|
|
|
The module can be used in all current Kamailio modules that need
|
|
database access. Relaying of insert, update, query and delete
|
|
operations is supported.
|
|
|
|
Modules can be configured to use the perlvdb module as database backend
|
|
using the db_url_parameter:
|
|
modparam("acc", "db_url", "perlvdb:Kamailio::VDB::Adapter::AccountingSIPtrace")
|
|
|
|
This configuration options tells acc module that it should use the
|
|
perlvdb module which will in turn use the Perl class
|
|
Kamailio::VDB::Adapter::AccountingSIPtrace to relay the database
|
|
requests.
|
|
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
2.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* perl -- Perl module
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* None (Besides the ones mentioned in the perl module documentation).
|
|
|
|
3. Parameters
|
|
|
|
None.
|
|
|
|
4. Functions
|
|
|
|
None.
|
|
|
|
Chapter 2. Developer Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Introduction
|
|
2. Base class Kamailio::VDB
|
|
3. Data types
|
|
|
|
3.1. Kamailio::VDB::Value
|
|
3.2. Kamailio::VDB::Pair
|
|
3.3. Kamailio::VDB::ReqCond
|
|
3.4. Kamailio::VDB::Column
|
|
3.5. Kamailio::VDB::Result
|
|
|
|
4. Adapters
|
|
|
|
4.1. Function parameters
|
|
|
|
5. VTabs
|
|
|
|
1. Introduction
|
|
|
|
Kamailio uses a database API for requests of numerous different types
|
|
of data. Four primary operations are supported:
|
|
* query
|
|
* insert
|
|
* update
|
|
* delete
|
|
|
|
This module relays these database requests to user implemented Perl
|
|
functions.
|
|
|
|
2. Base class Kamailio::VDB
|
|
|
|
A client module has to be configured to use the perlvdb module in
|
|
conjunction with a Perl class to provide the functions. The configured
|
|
class needs to inherit from the base class Kamailio::VDB.
|
|
|
|
Derived classes have to implement the necessary functions "query",
|
|
"insert", "update" and/or "delete". The client module specifies the
|
|
necessary functions. To find out which functions are called from a
|
|
module, its processes may be evaluated with the
|
|
Kamailio::VDB::Adapter::Describe class which will log incoming requests
|
|
(without actually providing any real functionality).
|
|
|
|
While users can directly implement their desired functionality in a
|
|
class derived from Kamailio::VDB, it is advisable to split the
|
|
implementation into an Adapter that transforms the relational
|
|
structured parameters into pure Perl function arguments, and add a
|
|
virtual table (VTab) to provide the relaying to an underlying
|
|
technology.
|
|
|
|
3. Data types
|
|
|
|
3.1. Kamailio::VDB::Value
|
|
3.2. Kamailio::VDB::Pair
|
|
3.3. Kamailio::VDB::ReqCond
|
|
3.4. Kamailio::VDB::Column
|
|
3.5. Kamailio::VDB::Result
|
|
|
|
Before introducing the higher level concepts of this module, the used
|
|
datatypes will briefly be explained. The Kamailio Perl library includes
|
|
some data types that have to be used in this module:
|
|
|
|
3.1. Kamailio::VDB::Value
|
|
|
|
A value includes a data type flag and a value. Valid data types are
|
|
DB_INT, DB_DOUBLE, DB_STRING, DB_STR, DB_DATETIME, DB_BLOB, DB_BITMAP.
|
|
A new variable may be created with
|
|
my $val = new Kamailio::VDB::Value(DB_STRING, "foobar");
|
|
|
|
Value objects contain the type() and data() methods to get or set the
|
|
type and data attributes.
|
|
|
|
3.2. Kamailio::VDB::Pair
|
|
|
|
The Pair class is derived from the Value class and additionally
|
|
contains a column name (key). A new variable may be created with
|
|
my $pair = new Kamailio::VDB::Pair("foo", DB_STRING, "bar");
|
|
|
|
where foo is the key and bar is the value. Additonally to the methods
|
|
of the Value class, it contains a key() method to get or set the key
|
|
attribute.
|
|
|
|
3.3. Kamailio::VDB::ReqCond
|
|
|
|
The ReqCond class is used for select condition and is derived from the
|
|
Pair class. It contains an addtional operator attribute. A new variable
|
|
may be created with
|
|
my $cond = new Kamailio::VDB::ReqCond("foo", ">", DB_INT, 5);
|
|
|
|
where foo is the key, "greater" is the operator and 5 is the value to
|
|
compare. Additonally to the methods of the Pair class, it contains an
|
|
op() method to get or set the operator attribute.
|
|
|
|
3.4. Kamailio::VDB::Column
|
|
|
|
This class represents a column definition or database schema. It
|
|
contains an array for the column names and an array for the column
|
|
types. Both arrays need to have the same length. A new variable may be
|
|
created with
|
|
my @types = { DB_INT, DB_STRING };
|
|
my @names = { "id", "vals" };
|
|
my $cols = new Kamailio::VDB::Column(\@types, \@names);
|
|
|
|
The class contains the methods type() and name() to get or set the type
|
|
and name arrays.
|
|
|
|
3.5. Kamailio::VDB::Result
|
|
|
|
The Result class represents a query result. It contains a schema (class
|
|
Column) and an array of rows, where each row is an array of Values. The
|
|
object methods coldefs() and rows() may be used to get and set the
|
|
object attributes.
|
|
|
|
4. Adapters
|
|
|
|
4.1. Function parameters
|
|
|
|
Adapters should be used to turn the relational structured database
|
|
request into pure Perl function arguments. The alias_db function
|
|
alias_db_lookup for example takes a user/host pair, and turns it into
|
|
another user/host pair. The Alias adapter turns the ReqCond array into
|
|
two separate scalars that are used as parameters for a VTab call.
|
|
|
|
Adapter classes have to inherit from the Kamailio::VDB base class and
|
|
may provide one or more functions with the names insert, update,
|
|
replace, query and/or delete, depending on the module which is to be
|
|
used with the adapter. While modules such as alias_db only require a
|
|
query function, others -- such as siptrace -- depend on inserts only.
|
|
|
|
4.1. Function parameters
|
|
|
|
The implemented functions need to deal with the correct data types. The
|
|
parameter and return types are listed in this section.
|
|
|
|
insert() is passed an array of Kamailio::VDB::Pair objects. It should
|
|
return an integer value.
|
|
|
|
replace() is passed an array of Kamailio::VDB::Pair objects. This
|
|
function is currently not used by any publicly available modules. It
|
|
should return an integer value.
|
|
|
|
delete() is passed an array of Kamailio::VDB::ReqCond objects. It
|
|
should return an integer value.
|
|
|
|
update() is passed an array of Kamailio::VDB::ReqCond objects (which
|
|
rows to update) and an array of Kamailio::VDB::Pair objects (new data).
|
|
It should return an integer value.
|
|
|
|
query() is passed an array of Kamailio::VDB::ReqCond objects (which
|
|
rows to select), an array of strings (which column names to return) and
|
|
a single string by which column to sort. It should return an object of
|
|
type Kamailio::VDB::Result.
|
|
|
|
5. VTabs
|
|
|
|
VTabs (virtual tables) provide a particular implementation for an
|
|
adapter. The Alias adapter e.g. calls a function with two parameters
|
|
(user, host) and expects a hash to be returned with the two elements
|
|
username and domain, or undef (when no result is found). A sample VTab
|
|
implementation for the Alias adapter demonstrates this technique with a
|
|
Perl hash that contains the alias data.
|
|
|
|
The standard Adapter/VTab pattern lets the user choose between three
|
|
options on how to implement VTabs:
|
|
* Single function. When a function is used as a virtual table, it is
|
|
passed the operation name (insert, replace, update, query, delete)
|
|
as its first parameter. The function may be implemented in the main
|
|
namespace.
|
|
|
|
* Package/class. The defined class needs to have an init() function.
|
|
It will be called during the first call of that VTab. Addtionally,
|
|
the package has to define the necessary functions insert, replace,
|
|
update, delete and/or query. These functions will be called in a
|
|
function context (first parameter is the class name).
|
|
|
|
* Object. The defined class needs to have a new() function which will
|
|
return a reference to the newly created object. This object needs
|
|
to define the necessary functions insert, replace, update, delete
|
|
and/or query. These functions will be called in a method context
|
|
(first parameter is a reference to the object).
|