modules: use Docbook tag for Kamailio wiki URL
[sip-router] / src / modules / avpops / doc / avpops_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10
11 <!-- Module User's Guide -->
12
13 <chapter>
14         
15         <title>&adminguide;</title>
16
17
18         <section>
19                 <title>Overview</title>
20                 <para>
21                 The AVPops (AVP-operations) module implements a set of script
22                 functions which allow access and manipulation of user attribute-value pairs (AVPs,
23                 preferences) and pseudo-variables. AVPs are a powerful tool
24                 for implementing services/preferences per user/domain. With this module, they
25                 are usable directly from configuration script. </para>
26                 <para>The module implement functions for
27                 interfacing DB resources (loading/storing/removing), functions
28                 for swapping information between AVPs and SIP messages and a function for 
29                 testing/checking the value of an AVP.
30                 </para>
31                 <para>
32                 If you just need a way to execute SQL statements in a
33                 &kamailio; configuration script, please consider use the
34                 <emphasis>sqlops</emphasis> module instead.
35                 </para>
36                 <para>
37                 AVPs are persistent per SIP transaction, being available in "route", 
38                 "branch_route" and "failure_route". A tutorial providing more information (detailed
39                 explanations and commented examples) can be found on the SIP-router web site.
40                 </para>
41         </section>
42         <section>
43                 <title>Dependencies</title>
44                 <section>
45                         <title>&kamailio; Modules</title>
46                         <para>
47                         The following modules must be loaded before this module:
48                         <itemizedlist>
49                         <listitem>
50                         <para>
51                                 <emphasis>Optionally a database module</emphasis>
52                         </para>
53                         </listitem>
54                         </itemizedlist>
55                         </para>
56                 </section>
57                 <section>
58                         <title>External Libraries or Applications</title>
59                         <para>
60                                 The following libraries or applications must be installed 
61                                 before running &kamailio; with this module loaded:
62                                 <itemizedlist>
63                                 <listitem>
64                                 <para>
65                                         <emphasis>None</emphasis>
66                                 </para>
67                                 </listitem>
68                                 </itemizedlist>
69                         </para>
70                 </section>
71         </section>
72
73         <section>
74                 <title>AVP naming format</title>
75                 <para>
76                 The format of the parameters specifying an AVP in functions exported
77                 by this module is:
78                         <emphasis role="bold">$avp(avp_flags:avp_name)</emphasis> or
79                         <emphasis role="bold">$avp(avp_alias)</emphasis>.
80                 </para>
81                 <itemizedlist>
82                 <listitem>
83                 <para>
84                         <emphasis>avp_flags</emphasis> = type_flags [script_flags]; type_flags = 'I' | 'i' | 'S' | 's'; script_flags = 0..255
85                 </para>
86                 <para>
87                 'I' or 'i' means that the type of avp name is an integer (ID)
88                 </para>
89                 <para>
90                 'S' or 's' means that the type of avp name is string
91                 </para>
92                 <para>
93                 The type flag is mandatory.
94                 Please note that the type flag only indicates type of name, not type of variable. An avp with name type "i" may very well contain text strings.
95                 </para>
96                 <para>
97                 script_flags must be an 8 bit unsigned number, therefore can be set
98                 up to 8 flags. If no script flag is provided, the name will
99                 match all AVPs, regardless they have or not a script flag set (preserves
100                 the compatibility with the old naming schema).
101                 </para>
102                 </listitem>
103                 <listitem>
104                 <para>
105                         <emphasis>avp_name</emphasis> = string | integer
106                 </para>
107                 <para>
108                 string - might be any alphanumeric string, wich contain following
109                 characters: [a-z] [A-Z] [0-9] '_'
110                 </para>
111                 <para>
112                 integer - might be an unsigned integer, greater than zero, up to 2^16-1
113                 </para>
114                 </listitem>
115                 <listitem>
116                 <para>
117                         <emphasis>avp_alias</emphasis> = string
118                 </para>
119                 <para>
120                 string - might be any alphanumeric string, wich contain following
121                 characters: [a-z] [A-Z] [0-9] '_'
122                 </para>
123                 </listitem>
124                 </itemizedlist>
125                         <example>
126                                 <title>AVP naming examples</title>
127                                 <programlisting format="linespecific">
128 ...
129 $avp(i:11) - the AVP identified by integer 11
130 $avp(s:foo) - the AVP identified by the string 'foo'
131 $avp(bar) - the AVP identified by the AVP alias 'bar'
132 $avp(i3:123) - the AVP identified by the integer 123 which has script flags 1
133     and 2 set
134 ...
135                                 </programlisting>
136                         </example>
137         </section>
138         <section>
139                 <title>Parameters</title>
140                 <section id="avpops.p.db_url">
141                         <title><varname>db_url</varname> (string)</title>
142                         <para>
143                         DB URL for database connection.
144                         </para>
145                         <para>
146                                 <emphasis>
147                                         This parameter is optional, it's default value being NULL.
148                                 </emphasis>
149                         </para>
150                         <example>
151                                 <title>Set <varname>db_url</varname> parameter</title>
152                                 <programlisting format="linespecific">
153 ...
154 modparam("avpops","db_url","mysql://user:passwd@host/database")
155 ...
156                                 </programlisting>
157                         </example>
158                 </section>
159                 <section id="avpops.p.avp_table">
160                         <title><varname>avp_table</varname> (string)</title>
161                         <para>
162                         DB table to be used.
163                         </para>
164                         <para>
165                                 <emphasis>
166                                         This parameter is optional, it's default value being NULL. But if
167                                         you specify a db_url, you need also setup this parameter.
168                                 </emphasis>
169                         </para>
170                         <example>
171                                 <title>Set <varname>avp_table</varname> parameter</title>
172                                 <programlisting format="linespecific">
173 ...
174 modparam("avpops","avp_table","avptable")
175 ...
176                                 </programlisting>
177                         </example>
178                 </section>
179                 <section id="avpops.p.use_domain">
180                         <title><varname>use_domain</varname> (integer)</title>
181                         <para>
182                                 If the domain part of the URI should be used for 
183                                 identifying an AVP in DB operations.
184                         </para>
185                         <para>
186                                 <emphasis>Default value is 0 (no).
187                                 </emphasis>
188                         </para>
189                         <example>
190                                 <title>Set <varname>use_domain</varname> parameter
191                                 </title>
192                                 <programlisting format="linespecific">
193 ...
194 modparam("avpops","use_domain",1)
195 ...
196                                 </programlisting>
197                         </example>
198                 </section>
199                 <section id="avpops.p.uuid_column">
200                         <title><varname>uuid_column</varname> (string)</title>
201                         <para>
202                                 Name of column containing the uuid (unique user id).
203                         </para>
204                         <para>
205                                 <emphasis>Default value is <quote>uuid</quote>.
206                                 </emphasis>
207                         </para>
208                         <example>
209                                 <title>Set <varname>uuid_column</varname> parameter</title>
210                                 <programlisting format="linespecific">
211 ...
212 modparam("avpops","uuid_column","uuid")
213 ...
214                                 </programlisting>
215                         </example>
216                 </section>
217                 <section id="avpops.p.username_column">
218                         <title><varname>username_column</varname> (string)</title>
219                         <para>
220                                 Name of column containing the username.
221                         </para>
222                         <para>
223                                 <emphasis>Default value is <quote>username</quote>.
224                                 </emphasis>
225                         </para>
226                         <example>
227                                 <title>Set <varname>username_column</varname> parameter</title>
228                                 <programlisting format="linespecific">
229 ...
230 modparam("avpops","username_column","username")
231 ...
232                                 </programlisting>
233                         </example>
234                 </section>
235                 <section id="avpops.p.domain_column">
236                         <title><varname>domain_column</varname> (string)</title>
237                         <para>
238                                 Name of column containing the domain name.
239                         </para>
240                         <para>
241                                 <emphasis>Default value is <quote>domain</quote>.
242                                 </emphasis>
243                         </para>
244                         <example>
245                                 <title>Set <varname>domain_column</varname> parameter</title>
246                                 <programlisting format="linespecific">
247 ...
248 modparam("avpops","domain_column","domain")
249 ...
250                                 </programlisting>
251                         </example>
252                 </section>
253                 <section id="avpops.p.attribute_column">
254                         <title><varname>attribute_column</varname> (string)</title>
255                         <para>
256                                 Name of column containing the attribute name (AVP name).
257                         </para>
258                         <para>
259                                 <emphasis>Default value is <quote>attribute</quote>.
260                                 </emphasis>
261                         </para>
262                         <example>
263                                 <title>Set <varname>attribute_column</varname> parameter
264                                 </title>
265                                 <programlisting format="linespecific">
266 ...
267 modparam("avpops","attribute_column","attribute")
268 ...
269                                 </programlisting>
270                         </example>
271                 </section>
272                 <section id="avpops.p.value_column">
273                         <title><varname>value_column</varname> (string)</title>
274                         <para>
275                                 Name of column containing the AVP value.
276                         </para>
277                         <para>
278                                 <emphasis>Default value is <quote>value</quote>.
279                                 </emphasis>
280                         </para>
281                         <example>
282                                 <title>Set <varname>value_column</varname> parameter
283                                 </title>
284                                 <programlisting format="linespecific">
285 ...
286 modparam("avpops","value_column","value")
287 ...
288                                 </programlisting>
289                         </example>
290                 </section>
291                 <section id="avpops.p.type_column">
292                         <title><varname>type_column</varname> (string)</title>
293                         <para>
294                                 Name of integer column containing the AVP type.
295                         </para>
296                         <para>
297                                 <emphasis>Default value is <quote>type</quote>.
298                                 </emphasis>
299                         </para>
300                         <para>
301                         Possible column values are 
302                         <itemizedlist>
303                         <listitem><para><emphasis>
304                                 0 - AVP with string name and string value
305                         </emphasis></para></listitem>
306                         <listitem><para><emphasis>
307                                 1 - AVP with string name and integer value
308                         </emphasis></para></listitem>
309                         <listitem><para><emphasis>
310                                 2 - AVP with integer name and string value
311                         </emphasis></para></listitem>
312                         <listitem><para><emphasis>
313                                 3 - AVP with integer name and integer value
314                         </emphasis></para></listitem>
315                         </itemizedlist>
316                         </para>
317
318                         <example>
319                                 <title>Set <varname>type_column</varname> parameter
320                                 </title>
321                                 <programlisting format="linespecific">
322 ...
323 modparam("avpops","type_column","type")
324 ...
325                                 </programlisting>
326                         </example>
327                 </section>
328                 <section id="avpops.p.db_scheme">
329                         <title><varname>db_scheme</varname> (string)</title>
330                         <para>
331                                 Definition of a DB scheme to be used for non-standard
332                                 access to Database information.
333                         </para>
334                         <para>
335                         Definition of a DB scheme. Scheme syntax is:
336                         <itemizedlist>
337                                 <listitem><para><emphasis>
338                                 db_scheme = name':'element[';'element]*
339                                 </emphasis></para></listitem>
340                                 <listitem><para><emphasis>element</emphasis> =
341                                         <itemizedlist>
342                                                 <listitem><para>'uuid_col='string
343                                                 </para></listitem>
344                                                 <listitem><para>'username_col='string
345                                                 </para></listitem>
346                                                 <listitem><para>'domain_col='string
347                                                 </para></listitem>
348                                                 <listitem><para>'value_col='string
349                                                 </para></listitem>
350                                                 <listitem><para>'value_type='('integer'|'string')
351                                                 </para></listitem>
352                                                 <listitem><para>'table='string
353                                                 </para></listitem>
354                                         </itemizedlist>
355                                 </para></listitem>
356                         </itemizedlist>
357                         </para>
358                         <para>
359                                 <emphasis>Default value is <quote>NULL</quote>.
360                                 </emphasis>
361                         </para>
362                         <example>
363                                 <title>Set <varname>db_scheme</varname> parameter
364                                 </title>
365                                 <programlisting format="linespecific">
366 ...
367 modparam("avpops","db_scheme",
368 "scheme1:table=subscriber;uuid_col=uuid;value_col=first_name")
369 ...
370                                 </programlisting>
371                         </example>
372                 </section>
373         </section>
374
375
376         <section>
377                 <title>Functions</title>
378                 <section id="avpops.f.avp_db_load">
379                         <title>
380                                 <function moreinfo="none">avp_db_load(source,name)
381                                 </function>
382                         </title>
383                         <para>
384                         Loads from DB into memory the AVPs corresponding to the given
385                         <emphasis>source</emphasis>. If given, it sets the script flags
386                         for loaded AVPs. It returns true if it loaded some values 
387                         in AVPs, false otherwise (db error, no avp loaded ...).
388                         </para>
389                         <para>Meaning of the parameters is as follows:</para>
390                         <itemizedlist>
391                         <listitem>
392                                 <para><emphasis>source</emphasis> - what info is used for 
393                                 identifying the AVPs. Parameter syntax:
394                                 <itemizedlist>
395                                         <listitem><para><emphasis>
396                                         source = (pvar|str_value)
397                                         ['/'('username'|'domain'|'uri'|'uuid')])
398                                         </emphasis></para></listitem>
399                                         <listitem><para><emphasis>
400                                         pvar = any pseudo variable defined in &kamailio;. If
401                                         the pvar is $ru (request uri), $fu (from uri), $tu (to uri)
402                                         or $ou (original uri), then the implicit flag is 'uri'.
403                                         Otherwise, the implicit flag is 'uuid'.
404                                         </emphasis></para></listitem>
405                                 </itemizedlist>
406                                 </para>
407                         </listitem>
408                         <listitem>
409                                 <para><emphasis>name</emphasis> - which AVPs will be loaded
410                                 from DB into memory. Parameter syntax is:
411                                 <itemizedlist>
412                                         <listitem><para><emphasis>
413                                         name = avp_spec['/'(table_name|'$'db_scheme)]
414                                         </emphasis></para></listitem>
415                                         <listitem><para><emphasis>
416                                         avp_spec = matching_flags|$avp(avp_name)|$avp(avp_alias)
417                                         </emphasis></para></listitem>
418                                         <listitem><para><emphasis>
419                                         matching_flags = 'a' | 'A' | 'i' | 'I' | 's' | 'S'
420                                         [script_flags]
421                                         </emphasis></para><para>'a' or 'A' means matching any of
422                                         AVP name types ('i' and 's') (NOTE: matching_flags cannot
423                                         be used with $db_scheme because the name of AVP to save in 
424                                         cannot be specified), the rest have the
425                                         meaning descriped in 'AVP naming format' chapter.</para>
426                                         </listitem>
427                                 </itemizedlist>
428                                 </para>
429                         </listitem>
430                         </itemizedlist>
431                         <para>
432                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
433                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
434                         </para>
435                         
436                         <example>
437                                 <title><function>avp_db_load</function> usage</title>
438                                 <programlisting format="linespecific">
439 ...
440 avp_db_load("$fu","$(i:678)");
441 avp_db_load("$ru/domain","i:/domain_preferences");
442 avp_db_load("$uuid","$avp(s:404fwd)/fwd_table");
443 avp_db_load("$ru","$avp(i1:123)/$some_scheme");
444 ...
445                                 </programlisting>
446                         </example>
447                 </section>
448                 <section id="avpops.f.avp_db_store">
449                         <title>
450                                 <function moreinfo="none">avp_db_store(source,name)</function>
451                         </title>
452                         <para>
453                         Stores to DB the AVPs corresponding to the given
454                         <emphasis>source</emphasis>.
455                         </para>
456                         <para>The meaning and usage of the parameters are identical as for
457                         <emphasis>avp_db_load(source,name)</emphasis>
458                         function. Please refer to its description.
459                         </para>
460                         <para>
461                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
462                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
463                         </para>
464                         
465                         <example>
466                                 <title><function>avp_db_store</function> usage</title>
467                                 <programlisting format="linespecific">
468 ...
469 avp_db_store("$tu","$avp(i:678)");
470 avp_db_store("$ru/username","$avp(email)");
471 ...
472                                 </programlisting>
473                         </example>
474                 </section>
475                 <section id="avpops.f.avp_db_delete">
476                         <title>
477                                 <function moreinfo="none">avp_db_delete(source,name)</function>
478                         </title>
479                         <para>
480                         Deletes from DB the AVPs corresponding to the given
481                         <emphasis>source</emphasis>.
482                         </para>
483                         <para>The meaning and usage of the parameters are identical as for
484                         <emphasis>avp_db_load(source,name)</emphasis>
485                         function. Please refer to its description.
486                         </para>
487                         <para>
488                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
489                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
490                         </para>
491                         <example>
492                                 <title><function>avp_db_delete</function> usage</title>
493                                 <programlisting format="linespecific">
494 ...
495 avp_db_delete("$tu","$avp(i:678)");
496 avp_db_delete("$ru/username","$avp(email)");
497 avp_db_delete("$uuid","$avp(s:404fwd)/fwd_table");
498 ...
499                                 </programlisting>
500                         </example>
501                 </section>
502                 <section id="avpops.f.avp_db_query">
503                         <title>
504                                 <function moreinfo="none">avp_db_query(query[,dest])</function>
505                         </title>
506                         <para>
507                         Make a database query and store the result in AVPs.
508                         This command is deprecated, please use the more
509                         flexible and advanced <emphasis>sqlops</emphasis> module instead.
510                         </para>
511                         <para>
512                         The meaning and usage of the parameters:
513                         </para>
514                         <itemizedlist>
515                         <listitem>
516                                 <para><emphasis>query</emphasis> - must be a valid SQL
517                                 query. The parameter can contain pseudo-variables.</para>
518                                 <para>You must escape any pseudo-variables manually to prevent
519                                 SQL injection attacks. You can use the existing transformations
520                                 <emphasis>escape.common</emphasis> and 
521                                 <emphasis>unescape.common</emphasis>
522                                 to escape and unescape the content of any pseudo-variable.
523                                 Failing to escape the variables used in the query makes you 
524                                 vulnerable to SQL injection, e.g. make it possible for an 
525                                 outside attacker to alter your database content.
526                                 </para>
527                         </listitem>
528                         <listitem>
529                                 <para><emphasis>dest</emphasis> - a list with AVP names where
530                                 to store the result. The format is
531                                 <quote>$avp(name1);$avp(name2);...</quote>. If this parameter
532                                 is ommited, the result is stored in 
533                                 <quote>$avp(i:1);$avp(i:2);...</quote>. If the result gives
534                                 many rows, then multiple AVPs with corresponding name will
535                                 be added. The value type of the AVP (string or integer) will
536                                 be derived from the type of the columns. Please note that only
537                                 this two datatypes are supported, so its not possible for
538                                 example to return floating point or big integer values this way.
539                                 </para>
540                         </listitem>
541                         </itemizedlist>
542                         <para>The function delivers the following return-codes:</para>
543                         <itemizedlist>
544                         <listitem><para>
545                         <emphasis>-1</emphasis> - An error occurred while querying the database
546                         (e.g. wrong SQL or database error)
547                         </para></listitem>
548                         <listitem><para>
549                         <emphasis>1</emphasis> - Query was successful
550                         </para></listitem>
551                         <listitem><para>
552                         <emphasis>-2</emphasis> - Query was successful, but no rows where returned.
553                         </para></listitem>
554                         </itemizedlist>
555                         <para>
556                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
557                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
558                         </para>
559                         <example>
560                                 <title><function>avp_db_query</function> usage</title>
561                                 <programlisting format="linespecific">
562 ...
563 avp_db_query("select password, ha1 from subscriber where username='$tu'",
564         "$avp(i:678);$avp(i:679)");
565 avp_db_query("delete from subscriber");
566 ...
567                                 </programlisting>
568                         </example>
569                 </section>
570                 <section id="avpops.f.avp_delete">
571                         <title>
572                                 <function moreinfo="none">avp_delete(name)
573                                 </function>
574                         </title>
575                         <para>
576                         Deletes from memory the AVPs with <emphasis>name</emphasis> or,
577                         if empty, all AVPs.
578                         </para>
579                         <para>Meaning of the parameters is as follows:</para>
580                         <itemizedlist>
581                         <listitem>
582                                 <para><emphasis>name</emphasis> - which AVPs will be deleted
583                                 from memory.
584                                 Parameter syntax is:
585                                 <itemizedlist>
586                                         <listitem><para><emphasis>
587                                         name = (matching_flags|avp_name|avp_alias)['/'flag]
588                                         </emphasis></para></listitem>
589                                         <listitem><para><emphasis>
590                                         matching_flags = please refer to avp_db_load() function
591                                         </emphasis></para></listitem>
592                                         <listitem><para><emphasis>
593                                         flag = 'g'|'G' = deletes not only the last value but the complete AVP.
594                                         </emphasis></para></listitem>
595                                 </itemizedlist>
596                                 </para>
597                         </listitem>
598                         </itemizedlist>
599                         <para>
600                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
601                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
602                         </para>
603                         <example>
604                                 <title><function>avp_delete</function> usage</title>
605                                 <programlisting format="linespecific">
606 ...
607 avp_delete("$avp(i:678)/g");
608 avp_delete("$avp(email)");
609 avp_delete("i");
610 avp_delete("a3");
611 ...
612                                 </programlisting>
613                         </example>
614                 </section>
615                 <section id="avpops.f.avp_pushto">
616                         <title>
617                                 <function moreinfo="none">avp_pushto(destination,name)
618                                 </function>
619                         </title>
620                         <para>
621                         Pushes the value of AVP(s) into the SIP message.
622                         </para>
623                         <para>Meaning of the parameters is as follows:</para>
624                         <itemizedlist>
625                         <listitem>
626                                 <para><emphasis>destination</emphasis> - as what will be the
627                                 AVP value pushed into SIP message.
628                                 Parameter syntax:
629                                 <itemizedlist>
630                                         <listitem><para><emphasis>
631                                         destination = '$ru' ['/'('username'|'domain')] | '$du' |
632                                         '$br'
633                                         </emphasis></para></listitem>
634                                         <listitem><para><emphasis>
635                                         $ru '['/'('username'|'domain')] - write the AVP in the
636                                         request URI or in username/domain part of it
637                                         </emphasis></para></listitem>
638                                         <listitem><para><emphasis>
639                                         $du - write the AVP in 'dst_uri' field
640                                         </emphasis></para></listitem>
641                                         <listitem><para><emphasis>
642                                         $br - write the AVP directly as a new branch (does not 
643                                         affect RURI)
644                                         </emphasis></para></listitem>
645                                 </itemizedlist>
646                                 </para>
647                         </listitem>
648                         <listitem>
649                                 <para><emphasis>name</emphasis> - which AVP(s)/pseudo-variable
650                                 should be pushed
651                                 into the SIP message.
652                                 Parameter syntax is:
653                                 <itemizedlist>
654                                         <listitem><para><emphasis>
655                                         name = ( avp_name | avp_alias | pvar_name )['/'flags]
656                                         </emphasis></para></listitem>
657                                         <listitem><para><emphasis>
658                                         flags = 'g' - effective only with AVPs
659                                         </emphasis></para></listitem>
660                                 </itemizedlist>
661                                 </para>
662                         </listitem>
663                         </itemizedlist>
664                         <para>
665                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
666                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
667                         </para>
668                         <example>
669                                 <title><function>avp_pushto</function> usage</title>
670                                 <programlisting format="linespecific">
671 ...
672 avp_pushto("$ru/domain","$fd");
673 avp_pushto("$ru","$avp(i:678)");
674 avp_pushto("$ru/domain","$avp(s:backup_domains)/g");
675 avp_pushto("$du","$avp(i:679)");
676 avp_pushto("$br","$avp(i:680)");
677 ...
678                                 </programlisting>
679                         </example>
680                 </section>
681                 <section id="avpops.f.avp_check">
682                         <title>
683                                 <function moreinfo="none">avp_check(name,op_value)
684                                 </function>
685                         </title>
686                         <para>
687                         Checks the value of the AVP(s) against an operator and value.
688                         </para>
689                         <para>Meaning of the parameters is as follows:</para>
690                         <itemizedlist>
691                         <listitem>
692                                 <para><emphasis>name</emphasis> - which AVP(s) should be 
693                                 checked.
694                                 Parameter syntax is:
695                                 <itemizedlist>
696                                         <listitem><para><emphasis>
697                                         name = ( pseudo-variable )
698                                         </emphasis></para></listitem>
699                                 </itemizedlist>
700                                 </para>
701                         </listitem>
702                         <listitem>
703                                 <para><emphasis>op_value</emphasis> - define the operator, 
704                                 the value and flags for checking.
705                                 Parameter syntax is:
706                                 </para>
707                                 <itemizedlist>
708                                         <listitem><para><emphasis>
709                                         op_value = operator '/' value ['/'flags]
710                                         </emphasis></para></listitem>
711                                         <listitem><para><emphasis>
712                                         operator = 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge'
713                                         | 're' | 'fm' | 'and' | 'or' | 'xor'
714                                         </emphasis></para></listitem>
715                                         <listitem><para><emphasis>
716                                         value = pseudo-variable | fix_value
717                                         </emphasis></para></listitem>
718                                         <listitem><para><emphasis>
719                                         fix_value = 'i:'integer | 's:'string | string
720                                         </emphasis></para></listitem>
721                                         <listitem><para><emphasis>
722                                         flags = 'g' | 'G' | 'i' | 'I'
723                                         </emphasis></para></listitem>
724                                 </itemizedlist>
725                                 <para>
726                                 Operator meaning:
727                                 </para>
728                                 <itemizedlist>
729                                         <listitem><para><emphasis>eq
730                                         </emphasis> - equal</para></listitem>
731                                         <listitem><para><emphasis>ne
732                                         </emphasis> - not equal</para></listitem>
733                                         <listitem><para><emphasis>lt
734                                         </emphasis> - less than</para></listitem>
735                                         <listitem><para><emphasis>le
736                                         </emphasis> - less or equal</para></listitem>
737                                         <listitem><para><emphasis>gt
738                                         </emphasis> - greater than</para></listitem>
739                                         <listitem><para><emphasis>ge
740                                         </emphasis> - greater or equal</para></listitem>
741                                         <listitem><para><emphasis>re
742                                         </emphasis> - regexp (regular exression match)</para>
743                                         </listitem>
744                                         <listitem><para><emphasis>fm
745                                         </emphasis> - fast match (see: man fnmatch)</para>
746                                         </listitem>
747                                         <listitem><para><emphasis>and
748                                         </emphasis> - bitwise 'and'</para></listitem>
749                                         <listitem><para><emphasis>or
750                                         </emphasis> - bitwise 'or'</para></listitem>
751                                         <listitem><para><emphasis>xor
752                                         </emphasis> - bitwise 'xor'</para></listitem>
753                                 </itemizedlist>
754                                 <para>
755                                 Integer values can be given in hexadecimal using notation:
756                                 'i:0xhex_number' (e.g.,: 'i:0xabcd');
757                                 </para>
758                         </listitem>
759                         </itemizedlist>
760                         <para>
761                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
762                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
763                         </para>
764                         <example>
765                                 <title><function>avp_check</function> usage</title>
766                                 <programlisting format="linespecific">
767 ...
768 avp_check("$avp(i:678)", "lt/i:345/g");
769 avp_check("$fd","eq/$td/I");
770 avp_check("$avp(s:foo)","gt/$avp($var(bar))/g");
771 avp_check("$avp(s:foo)","re/sip:.*@bar.net/g");
772 avp_check("$avp(s:foo)","fm/$avp(fm_avp)/g");
773 ...
774                                 </programlisting>
775                                 <para>NOTE: you can use a xavp variable ($xavp(key1[indx1]=>key2[indx2]))
776                                 as first or second parameter.
777                                 If you want to check all the values of the key2 you should
778                                 use [*] at indx2. The [*] index is not allowed at indx1.
779                                 </para>
780                                 <programlisting format="linespecific">
781 ...
782 avp_check("$xavp(op[0]=>lt[0])", "lt/i:345/g");
783 avp_check("$xavp(op=>fd","eq/$td/I");
784 avp_check("$xavp(op[1]=>foo[*])","gt/$avp($var(bar))/g");
785 avp_check("$avp(s:foo)","re/$xavp(op[0]=>re[*]/g");
786 $var(id)=2;
787 avp_check("$xavp(op=>foo[*])","fm/$xavp(op=>fm[$var(id)])/g");
788 ...
789                                 </programlisting>
790                         </example>
791                 </section>
792                 <section id="avpops.f.avp_copy">
793                         <title>
794                                 <function moreinfo="none">avp_copy(old_name,new_name)
795                                 </function>
796                         </title>
797                         <para>
798                         Copy / move an avp under a new name.
799                         </para>
800                         <para>Meaning of the parameters is as follows:</para>
801                         <itemizedlist>
802                         <listitem>
803                                 <para><emphasis>name1</emphasis> - which AVP(s) should be 
804                                 copied/moved.
805                                 Parameter syntax is:
806                                 <itemizedlist>
807                                         <listitem><para><emphasis>
808                                         name = ( avp_name | avp_alias )
809                                         </emphasis></para></listitem>
810                                 </itemizedlist>
811                                 </para>
812                         </listitem>
813                         <listitem>
814                                 <para><emphasis>name2</emphasis> - the new name of the 
815                                 copied/moved AVP(s).
816                                 Parameter syntax is:
817                                 <itemizedlist>
818                                         <listitem><para><emphasis>
819                                         name = ( avp_name | avp_alias ) ['/'flags]
820                                         </emphasis></para></listitem>
821                                         <listitem><para><emphasis>
822                                         flags = 'g' | 'G' | 'd' | 'D' | 'n' | 'N' | 's' | 'S'
823                                         </emphasis></para></listitem>
824                                 </itemizedlist>
825                                 </para>
826                         </listitem>
827                         </itemizedlist>
828                         <para>
829                                 NOTE: if a list of AVPs is copied/moved (flag g|G), then the order
830                                 of the values is reversed. Copy/move twice in order to get the same
831                                 order as in original list.
832                         </para>
833                         <para>
834                         This function can be used from ANY_ROUTE.
835                         </para>
836                         <example>
837                                 <title><function>avp_copy</function> usage</title>
838                                 <programlisting format="linespecific">
839 ...
840 avp_copy("$avp(i:678)", "$avp(s:345)/g");
841 avp_copy("$avp(old)","$avp(new)/gd");
842 ...
843                                 </programlisting>
844                         </example>
845                 </section>
846                 <section id="avpops.f.avp_printf">
847                         <title>
848                                 <function moreinfo="none">avp_printf(dest, format)
849                                 </function>
850                         </title>
851                         <para>
852                         NOTE: since &kamailio; 1.3.0 the function has been moved to core
853                         and it is an alias to pv_printf().
854                         </para>
855                         <para>
856                         Prints the formatted string 'format' in the AVP 'dest'. The
857                         'format' parameter can include any pseudo-variable defined in
858                         &kamailio;. The list with all pseudo-variables in &kamailio; can
859                         be found at: &kamwikilink;
860                         </para>
861                         <para>Meaning of the parameters is as follows:</para>
862                         <itemizedlist>
863                         <listitem>
864                                 <para><emphasis>dest</emphasis> - in which AVP should be 
865                                 stored the result.
866                                 Parameter syntax is:
867                                 </para>
868                                 <itemizedlist>
869                                         <listitem><para><emphasis>
870                                         name = ( avp_name | avp_alias )
871                                         </emphasis></para></listitem>
872                                 </itemizedlist>
873                         </listitem>
874                         <listitem>
875                                 <para><emphasis>format</emphasis> - the formatted string
876                                 to be printed in 'dest' AVP.
877                                 </para>
878                         </listitem>
879                         </itemizedlist>
880                         <para>
881                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
882                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
883                         </para>
884                         <example>
885                                 <title><function>avp_printf</function> usage</title>
886                                 <programlisting format="linespecific">
887 ...
888 avp_printf("$avp(i:20)", "This is a $rm request with call-id $hdr(call-id)");
889 ...
890                                 </programlisting>
891                         </example>
892                 </section>
893                 <section id="avpops.f.avp_subst">
894                         <title>
895                                 <function moreinfo="none">avp_subst(avps, subst)</function>
896                         </title>
897                         <para>
898                         Perl/sed-like subst applied to AVPs having string value.
899                         </para>
900                         <para>Meaning of the parameters is as follows:</para>
901                         <itemizedlist>
902                         <listitem>
903                                 <para><emphasis>avps</emphasis> - source AVP, destination AVP
904                                 and flags. Parameter syntax is:
905                                 <itemizedlist>
906                                         <listitem><para><emphasis>
907                                         avps = src_avp [ '/' dst_avp [ '/' flags ] ]
908                                         </emphasis></para></listitem>
909                                         <listitem><para><emphasis>
910                                         src_avp = ( avp_name | avp_alias )
911                                         </emphasis></para></listitem>
912                                         <listitem><para><emphasis>
913                                         dst_avp = ( avp_name | avp_alias ) - if dst_avp is missing
914                                         then the value of src_avp will be replaced
915                                         </emphasis></para></listitem>
916                                         <listitem><para><emphasis>
917                                         flags = ( d | D | g | G ) -- (d, D - delete source avp;
918                                         g, G - apply to all avps matching src_avp name)
919                                         </emphasis></para></listitem>
920                                 </itemizedlist>
921                                 </para>
922                         </listitem>
923                         <listitem>
924                                 <para><emphasis>subst</emphasis> - perl/sed-like reqular expression.
925                                 Parameter syntax is:
926                                 <itemizedlist>
927                                         <listitem><para><emphasis>
928                                         subst = "/regexp/replacement/flags"
929                                         </emphasis></para></listitem>
930                                         <listitem><para><emphasis>
931                                         regexp - regular expression
932                                         </emphasis></para></listitem>
933                                         <listitem><para><emphasis>
934                                         replacement - replacement string, can include 
935                                         pseudo-variables and \1, ..., \9 for matching tokens, 
936                                         \0 for whole matching text
937                                         </emphasis></para></listitem>
938                                         <listitem><para><emphasis>
939                                         flags = 'g' | 'G' | 'i' | 'i' (g, G - replace all 
940                                         matching tokens; i, I - match ignore case)
941                                         </emphasis></para></listitem>
942                                 </itemizedlist>
943                                 </para>
944                         </listitem>
945                         </itemizedlist>
946                         <para>
947                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
948                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
949                         </para>
950                         <example>
951                                 <title><function>avp_subst</function> usage</title>
952                                 <programlisting format="linespecific">
953 ...
954 # if avp i:678 has a string value in e-mail format, replace the
955 # domain part with the value of domain part from R-URI
956 avp_subst("$avp(i:678)", "/(.*)@(.*)/\1@$rd/");
957
958 # if any avp i:678 has a string value in e-mail format, replace the
959 # domain part with the value of domain part from R-URI
960 # and place the result in avp i:679
961 avp_subst("$avp(i:678)/$avp(i:679)/g", "/(.*)@(.*)/\1@$rd/");
962 ...
963                                 </programlisting>
964                         </example>
965                         <para>
966                         IMPORTANT NOTE: if the replacement string includes src_avp
967                         or dst_avp you will get something that you may not expect.
968                         In case you have many src_avp and you make the substitution
969                         to be applied to all of them, after the first src_avp is
970                         processed, it will be added in avp list and next
971                         processing will use it.
972                         </para>
973                 </section>
974                 <section id="avpops.f.avp_op">
975                         <title>
976                                 <function moreinfo="none">avp_op(name,op_value)
977                                 </function>
978                         </title>
979                         <para>
980                         Different integer operations with avps.
981                         </para>
982                         <para>Meaning of the parameters is as follows:</para>
983                         <itemizedlist>
984                         <listitem>
985                                 <para><emphasis>name</emphasis>
986                                 - 'source_avp/destination_avp' - which AVP(s) should be 
987                                 processed and where to store the result. If 'destination_avp'
988                                 is missing, same name as 'source_avp' is used to store the
989                                 result.
990                                 </para>
991                                 <para>
992                                 Parameter syntax is:
993                                 </para>
994                                 <itemizedlist>
995                                         <listitem>
996                                         <para><emphasis>
997                                         name = ( source_avp[/destination_avp] )
998                                         </emphasis></para>
999                                         <para><emphasis>
1000                                         source_avp = ( avp_name | avp_alias )
1001                                         </emphasis></para>
1002                                         <para><emphasis>
1003                                         destination_avp = ( avp_name | avp_alias )
1004                                         </emphasis></para>
1005                                         </listitem>
1006                                 </itemizedlist>
1007                         </listitem>
1008                         <listitem>
1009                                 <para><emphasis>op_value</emphasis> - define the operation, 
1010                                 the value and flags.
1011                                 Parameter syntax is:
1012                                 <itemizedlist>
1013                                         <listitem><para><emphasis>
1014                                         op_value = operator '/' value ['/'flags]
1015                                         </emphasis></para></listitem>
1016                                         <listitem><para><emphasis>
1017                                         operator = 'add' | 'sub' | 'mul' | 'div' | 'mod'
1018                                         | 'and' | 'or' | 'xor' | 'not'
1019                                         </emphasis></para></listitem>
1020                                         <listitem><para><emphasis>
1021                                         value = pseudo-variable | fix_value
1022                                         </emphasis></para></listitem>
1023                                         <listitem><para><emphasis>
1024                                         fix_value = 'i:'integer
1025                                         </emphasis></para></listitem>
1026                                         <listitem><para><emphasis>
1027                                         flags = 'g' | 'G' | 'd' | 'D'
1028                                         </emphasis></para></listitem>
1029                                 </itemizedlist>
1030                                 </para>
1031                                 <para>
1032                                 Integer values can be given in hexadecimal using notation
1033                                 'i:0xhex_number' (e.g.,: 'i:0xabcd');
1034                                 </para>
1035                         </listitem>
1036                         </itemizedlist>
1037                         <para>
1038                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
1039                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
1040                         </para>
1041                         <example>
1042                                 <title><function>avp_op</function> usage</title>
1043                                 <programlisting format="linespecific">
1044 ...
1045 avp_op("$avp(i:678)", "add/i:345/g");
1046 avp_op("$avp(number)","sub/$avp(number2)/d");
1047 ...
1048                                 </programlisting>
1049                         </example>
1050                 </section>
1051                 <section id="avpops.f.is_avp_set">
1052                         <title>
1053                                 <function moreinfo="none">is_avp_set(name)
1054                                 </function>
1055                         </title>
1056                         <para>
1057                         Check if any AVP with <emphasis>name</emphasis> is set.
1058                         </para>
1059                         <para>Meaning of the parameters is as follows:</para>
1060                         <itemizedlist>
1061                         <listitem>
1062                                 <para><emphasis>name</emphasis> - name of AVP to look for.
1063                                 Parameter syntax is:
1064                                 <itemizedlist>
1065                                         <listitem><para><emphasis>
1066                                         name = avp_name|avp_alias [ '/' flags ])
1067                                         </emphasis></para>
1068                                         <para><emphasis>
1069                                         flags = ('e'|'s'|'n') - e = empty value; s = value string;
1070                                         n = value number (int)
1071                                         </emphasis></para></listitem>
1072                                 </itemizedlist>
1073                                 </para>
1074                         </listitem>
1075                         </itemizedlist>
1076                         <para>
1077                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
1078                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
1079                         </para>
1080                         <example>
1081                                 <title><function>is_avp_set</function> usage</title>
1082                                 <programlisting format="linespecific">
1083 ...
1084 if(is_avp_set("$avp(i:678)"))
1085     log("AVP with integer id 678 exists\n");
1086 ...
1087                                 </programlisting>
1088                         </example>
1089                 </section>
1090                 <section id="avpops.f.avp_print">
1091                         <title>
1092                                 <function moreinfo="none">avp_print()
1093                                 </function>
1094                         </title>
1095                         <para>
1096                         Prints the list with all the AVPs from memory. This is only a
1097                         helper/debug function.
1098                         </para>
1099                         <para>
1100                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
1101                         BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
1102                         </para>
1103                         <example>
1104                                 <title><function>avp_print</function> usage</title>
1105                                 <programlisting format="linespecific">
1106 ...
1107 avp_print();
1108 ...
1109                                 </programlisting>
1110                         </example>
1111                 </section>
1112         </section>
1113
1114 </chapter>
1115