Browse code

modules: readme files regenerated - db_perlvdb ... [skip ci]

Kamailio Dev authored on 08/05/2018 06:32:08
Showing 1 changed files
... ...
@@ -69,12 +69,12 @@ Chapter 1. Admin Guide
69 69
    database access. Relaying of insert, update, query and delete
70 70
    operations is supported.
71 71
 
72
-   Modules can be configured to use the perlvdb module as database backend
73
-   using the db_url_parameter:
72
+   Modules can be configured to use the db_perlvdb module as database
73
+   backend using the db_url_parameter:
74 74
 modparam("acc", "db_url", "perlvdb:Kamailio::VDB::Adapter::AccountingSIPtrace")
75 75
 
76 76
    This configuration options tells acc module that it should use the
77
-   perlvdb module which will in turn use the Perl class
77
+   db_perlvdb module which will in turn use the Perl class
78 78
    Kamailio::VDB::Adapter::AccountingSIPtrace to relay the database
79 79
    requests.
80 80
 
... ...
@@ -86,13 +86,14 @@ modparam("acc", "db_url", "perlvdb:Kamailio::VDB::Adapter::AccountingSIPtrace")
86 86
 2.1. Kamailio Modules
87 87
 
88 88
    The following modules must be loaded before this module:
89
-     * perl -- Perl module
89
+     * app_perl -- Perl Application module
90 90
 
91 91
 2.2. External Libraries or Applications
92 92
 
93 93
    The following libraries or applications must be installed before
94 94
    running Kamailio with this module loaded:
95
-     * None (Besides the ones mentioned in the perl module documentation).
95
+     * None (Besides the ones mentioned in the app_perl module
96
+       documentation).
96 97
 
97 98
 3. Parameters
98 99
 
... ...
@@ -136,7 +137,7 @@ Chapter 2. Developer Guide
136 137
 
137 138
 2. Base class Kamailio::VDB
138 139
 
139
-   A client module has to be configured to use the perlvdb module in
140
+   A client module has to be configured to use the db_perlvdb module in
140 141
    conjunction with a Perl class to provide the functions. The configured
141 142
    class needs to inherit from the base class Kamailio::VDB.
142 143
 
Browse code

modules: readme files regenerated - acc ... [skip ci]

Kamailio Dev authored on 28/02/2018 17:03:37 • The Root committed on 28/02/2018 19:11:36
Showing 1 changed files
... ...
@@ -182,19 +182,19 @@ my $val = new Kamailio::VDB::Value(DB_STRING, "foobar");
182 182
    contains a column name (key). A new variable may be created with
183 183
 my $pair = new Kamailio::VDB::Pair("foo", DB_STRING, "bar");
184 184
 
185
-   where foo is the key and bar is the value. Additonally to the methods
185
+   where foo is the key and bar is the value. Additionally to the methods
186 186
    of the Value class, it contains a key() method to get or set the key
187 187
    attribute.
188 188
 
189 189
 3.3. Kamailio::VDB::ReqCond
190 190
 
191 191
    The ReqCond class is used for select condition and is derived from the
192
-   Pair class. It contains an addtional operator attribute. A new variable
193
-   may be created with
192
+   Pair class. It contains an additional operator attribute. A new
193
+   variable may be created with
194 194
 my $cond = new Kamailio::VDB::ReqCond("foo", ">", DB_INT, 5);
195 195
 
196 196
    where foo is the key, "greater" is the operator and 5 is the value to
197
-   compare. Additonally to the methods of the Pair class, it contains an
197
+   compare. Additionally to the methods of the Pair class, it contains an
198 198
    op() method to get or set the operator attribute.
199 199
 
200 200
 3.4. Kamailio::VDB::Column
... ...
@@ -274,7 +274,7 @@ my $cols = new Kamailio::VDB::Column(\@types, \@names);
274 274
        namespace.
275 275
 
276 276
      * Package/class. The defined class needs to have an init() function.
277
-       It will be called during the first call of that VTab. Addtionally,
277
+       It will be called during the first call of that VTab. Additionally,
278 278
        the package has to define the necessary functions insert, replace,
279 279
        update, delete and/or query. These functions will be called in a
280 280
        function context (first parameter is the class name).
Browse code

core, lib, modules: restructured source code tree

- new folder src/ to hold the source code for main project applications
- main.c is in src/
- all core files are subfolder are in src/core/
- modules are in src/modules/
- libs are in src/lib/
- application Makefiles are in src/
- application binary is built in src/ (src/kamailio)

Daniel-Constantin Mierla authored on 07/12/2016 11:03:51
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,286 @@
1
+Perl Virtual Database Module
2
+
3
+Bastian Friedrich
4
+
5
+   Collax GmbH
6
+
7
+Edited by
8
+
9
+Bastian Friedrich
10
+
11
+   Copyright © 2007 Collax GmbH
12
+     __________________________________________________________________
13
+
14
+   Table of Contents
15
+
16
+   1. Admin Guide
17
+
18
+        1. Overview
19
+        2. Dependencies
20
+
21
+              2.1. Kamailio Modules
22
+              2.2. External Libraries or Applications
23
+
24
+        3. Parameters
25
+        4. Functions
26
+
27
+   2. Developer Guide
28
+
29
+        1. Introduction
30
+        2. Base class Kamailio::VDB
31
+        3. Data types
32
+
33
+              3.1. Kamailio::VDB::Value
34
+              3.2. Kamailio::VDB::Pair
35
+              3.3. Kamailio::VDB::ReqCond
36
+              3.4. Kamailio::VDB::Column
37
+              3.5. Kamailio::VDB::Result
38
+
39
+        4. Adapters
40
+
41
+              4.1. Function parameters
42
+
43
+        5. VTabs
44
+
45
+Chapter 1. Admin Guide
46
+
47
+   Table of Contents
48
+
49
+   1. Overview
50
+   2. Dependencies
51
+
52
+        2.1. Kamailio Modules
53
+        2.2. External Libraries or Applications
54
+
55
+   3. Parameters
56
+   4. Functions
57
+
58
+1. Overview
59
+
60
+   The Perl Virtual Database (VDB) provides a virtualization framework for
61
+   Kamailio's database access. It does not handle a particular database
62
+   engine itself but lets the user relay database requests to arbitrary
63
+   Perl functions.
64
+
65
+   This module cannot be used "out of the box". The user has to supply
66
+   functionality dedicated to the client module. See below for options.
67
+
68
+   The module can be used in all current Kamailio modules that need
69
+   database access. Relaying of insert, update, query and delete
70
+   operations is supported.
71
+
72
+   Modules can be configured to use the perlvdb module as database backend
73
+   using the db_url_parameter:
74
+modparam("acc", "db_url", "perlvdb:Kamailio::VDB::Adapter::AccountingSIPtrace")
75
+
76
+   This configuration options tells acc module that it should use the
77
+   perlvdb module which will in turn use the Perl class
78
+   Kamailio::VDB::Adapter::AccountingSIPtrace to relay the database
79
+   requests.
80
+
81
+2. Dependencies
82
+
83
+   2.1. Kamailio Modules
84
+   2.2. External Libraries or Applications
85
+
86
+2.1. Kamailio Modules
87
+
88
+   The following modules must be loaded before this module:
89
+     * perl -- Perl module
90
+
91
+2.2. External Libraries or Applications
92
+
93
+   The following libraries or applications must be installed before
94
+   running Kamailio with this module loaded:
95
+     * None (Besides the ones mentioned in the perl module documentation).
96
+
97
+3. Parameters
98
+
99
+   None.
100
+
101
+4. Functions
102
+
103
+   None.
104
+
105
+Chapter 2. Developer Guide
106
+
107
+   Table of Contents
108
+
109
+   1. Introduction
110
+   2. Base class Kamailio::VDB
111
+   3. Data types
112
+
113
+        3.1. Kamailio::VDB::Value
114
+        3.2. Kamailio::VDB::Pair
115
+        3.3. Kamailio::VDB::ReqCond
116
+        3.4. Kamailio::VDB::Column
117
+        3.5. Kamailio::VDB::Result
118
+
119
+   4. Adapters
120
+
121
+        4.1. Function parameters
122
+
123
+   5. VTabs
124
+
125
+1. Introduction
126
+
127
+   Kamailio uses a database API for requests of numerous different types
128
+   of data. Four primary operations are supported:
129
+     * query
130
+     * insert
131
+     * update
132
+     * delete
133
+
134
+   This module relays these database requests to user implemented Perl
135
+   functions.
136
+
137
+2. Base class Kamailio::VDB
138
+
139
+   A client module has to be configured to use the perlvdb module in
140
+   conjunction with a Perl class to provide the functions. The configured
141
+   class needs to inherit from the base class Kamailio::VDB.
142
+
143
+   Derived classes have to implement the necessary functions "query",
144
+   "insert", "update" and/or "delete". The client module specifies the
145
+   necessary functions. To find out which functions are called from a
146
+   module, its processes may be evaluated with the
147
+   Kamailio::VDB::Adapter::Describe class which will log incoming requests
148
+   (without actually providing any real functionality).
149
+
150
+   While users can directly implement their desired functionality in a
151
+   class derived from Kamailio::VDB, it is advisable to split the
152
+   implementation into an Adapter that transforms the relational
153
+   structured parameters into pure Perl function arguments, and add a
154
+   virtual table (VTab) to provide the relaying to an underlying
155
+   technology.
156
+
157
+3. Data types
158
+
159
+   3.1. Kamailio::VDB::Value
160
+   3.2. Kamailio::VDB::Pair
161
+   3.3. Kamailio::VDB::ReqCond
162
+   3.4. Kamailio::VDB::Column
163
+   3.5. Kamailio::VDB::Result
164
+
165
+   Before introducing the higher level concepts of this module, the used
166
+   datatypes will briefly be explained. The Kamailio Perl library includes
167
+   some data types that have to be used in this module:
168
+
169
+3.1. Kamailio::VDB::Value
170
+
171
+   A value includes a data type flag and a value. Valid data types are
172
+   DB_INT, DB_DOUBLE, DB_STRING, DB_STR, DB_DATETIME, DB_BLOB, DB_BITMAP.
173
+   A new variable may be created with
174
+my $val = new Kamailio::VDB::Value(DB_STRING, "foobar");
175
+
176
+   Value objects contain the type() and data() methods to get or set the
177
+   type and data attributes.
178
+
179
+3.2. Kamailio::VDB::Pair
180
+
181
+   The Pair class is derived from the Value class and additionally
182
+   contains a column name (key). A new variable may be created with
183
+my $pair = new Kamailio::VDB::Pair("foo", DB_STRING, "bar");
184
+
185
+   where foo is the key and bar is the value. Additonally to the methods
186
+   of the Value class, it contains a key() method to get or set the key
187
+   attribute.
188
+
189
+3.3. Kamailio::VDB::ReqCond
190
+
191
+   The ReqCond class is used for select condition and is derived from the
192
+   Pair class. It contains an addtional operator attribute. A new variable
193
+   may be created with
194
+my $cond = new Kamailio::VDB::ReqCond("foo", ">", DB_INT, 5);
195
+
196
+   where foo is the key, "greater" is the operator and 5 is the value to
197
+   compare. Additonally to the methods of the Pair class, it contains an
198
+   op() method to get or set the operator attribute.
199
+
200
+3.4. Kamailio::VDB::Column
201
+
202
+   This class represents a column definition or database schema. It
203
+   contains an array for the column names and an array for the column
204
+   types. Both arrays need to have the same length. A new variable may be
205
+   created with
206
+my @types = { DB_INT, DB_STRING };
207
+my @names = { "id", "vals" };
208
+my $cols = new Kamailio::VDB::Column(\@types, \@names);
209
+
210
+   The class contains the methods type() and name() to get or set the type
211
+   and name arrays.
212
+
213
+3.5. Kamailio::VDB::Result
214
+
215
+   The Result class represents a query result. It contains a schema (class
216
+   Column) and an array of rows, where each row is an array of Values. The
217
+   object methods coldefs() and rows() may be used to get and set the
218
+   object attributes.
219
+
220
+4. Adapters
221
+
222
+   4.1. Function parameters
223
+
224
+   Adapters should be used to turn the relational structured database
225
+   request into pure Perl function arguments. The alias_db function
226
+   alias_db_lookup for example takes a user/host pair, and turns it into
227
+   another user/host pair. The Alias adapter turns the ReqCond array into
228
+   two separate scalars that are used as parameters for a VTab call.
229
+
230
+   Adapter classes have to inherit from the Kamailio::VDB base class and
231
+   may provide one or more functions with the names insert, update,
232
+   replace, query and/or delete, depending on the module which is to be
233
+   used with the adapter. While modules such as alias_db only require a
234
+   query function, others -- such as siptrace -- depend on inserts only.
235
+
236
+4.1. Function parameters
237
+
238
+   The implemented functions need to deal with the correct data types. The
239
+   parameter and return types are listed in this section.
240
+
241
+   insert() is passed an array of Kamailio::VDB::Pair objects. It should
242
+   return an integer value.
243
+
244
+   replace() is passed an array of Kamailio::VDB::Pair objects. This
245
+   function is currently not used by any publicly available modules. It
246
+   should return an integer value.
247
+
248
+   delete() is passed an array of Kamailio::VDB::ReqCond objects. It
249
+   should return an integer value.
250
+
251
+   update() is passed an array of Kamailio::VDB::ReqCond objects (which
252
+   rows to update) and an array of Kamailio::VDB::Pair objects (new data).
253
+   It should return an integer value.
254
+
255
+   query() is passed an array of Kamailio::VDB::ReqCond objects (which
256
+   rows to select), an array of strings (which column names to return) and
257
+   a single string by which column to sort. It should return an object of
258
+   type Kamailio::VDB::Result.
259
+
260
+5. VTabs
261
+
262
+   VTabs (virtual tables) provide a particular implementation for an
263
+   adapter. The Alias adapter e.g. calls a function with two parameters
264
+   (user, host) and expects a hash to be returned with the two elements
265
+   username and domain, or undef (when no result is found). A sample VTab
266
+   implementation for the Alias adapter demonstrates this technique with a
267
+   Perl hash that contains the alias data.
268
+
269
+   The standard Adapter/VTab pattern lets the user choose between three
270
+   options on how to implement VTabs:
271
+     * Single function. When a function is used as a virtual table, it is
272
+       passed the operation name (insert, replace, update, query, delete)
273
+       as its first parameter. The function may be implemented in the main
274
+       namespace.
275
+
276
+     * Package/class. The defined class needs to have an init() function.
277
+       It will be called during the first call of that VTab. Addtionally,
278
+       the package has to define the necessary functions insert, replace,
279
+       update, delete and/or query. These functions will be called in a
280
+       function context (first parameter is the class name).
281
+
282
+     * Object. The defined class needs to have a new() function which will
283
+       return a reference to the newly created object. This object needs
284
+       to define the necessary functions insert, replace, update, delete
285
+       and/or query. These functions will be called in a method context
286
+       (first parameter is a reference to the object).