Browse code

topos: docs for inbound event routes and context

Daniel-Constantin Mierla authored on 01/04/2021 07:12:16
Showing 1 changed files
... ...
@@ -199,7 +199,7 @@ modparam("topos", "branch_expire", 300)
199 199
 			after the initial call setup on re-INVITEs or other in-dialog
200 200
 			messages. So set a large enough value (according your longest call
201 201
 			duration) to prevent problems in re-writing messages.
202
-			This key is only relevant for INVITE dialog. 
202
+			This key is only relevant for INVITE dialog.
203 203
                         SUBSCRIBE dialog records lifetime are based on value set in expires
204 204
                         header. Moreover each re-SUBSCRIBEs update the dialog timestamp.
205 205
 		</para>
... ...
@@ -272,7 +272,9 @@ end
272 272
 		<para>
273 273
 			Control what event_route blocks to be executed. It is a bitmask of:
274 274
 			1 - execute event_route[topos:msg-outgoing]; 2 - execute
275
-			event_route[topos:msg-sending].
275
+			event_route[topos:msg-sending]; 4 execute
276
+			event_route[topos:msg-incoming]; 8 execute
277
+			event_route[topos:msg-receiving];.
276 278
 		</para>
277 279
 		<para>
278 280
 		<emphasis>
... ...
@@ -501,7 +503,58 @@ modparam("topos", "xavu_contact_host", "contact_host")
501 503
 </programlisting>
502 504
 		</example>
503 505
 	</section>
506
+	<section id="topos.p.context">
507
+		<title><varname>context</varname> (str)</title>
508
+		<para>
509
+			Set the global context for topos instance.
510
+		</para>
511
+		<para>
512
+			The value has to be maximum 12 characters.
513
+		</para>
514
+		<para>
515
+		<emphasis>
516
+			Default value is <quote>NULL</quote> (disabled).
517
+		</emphasis>
518
+		</para>
519
+		<example>
520
+		<title>Set <varname>context</varname> parameter</title>
521
+		<programlisting format="linespecific">
522
+...
523
+modparam("topos", "context", "srvone")
524
+...
525
+</programlisting>
526
+		</example>
527
+	</section>
528
+	</section>
529
+
530
+	<section>
531
+	<title>Functions</title>
532
+	<section id="topos.f.tps_set_context">
533
+		<title>
534
+		<function moreinfo="none">tps_set_context(ctx)</function>
535
+		</title>
536
+		<para>
537
+			Update the context at runtime. If the value is emtpy string, then
538
+			the runtime context is reset.
539
+		</para>
540
+		<para>
541
+		This function can be used from ANY_ROUTE.
542
+		</para>
543
+		<example>
544
+		<title><function>tps_set_context</function> usage</title>
545
+		<programlisting format="linespecific">
546
+...
547
+request_route {
548
+    ...
549
+    tps_set_context("srvone");
550
+    ...
551
+}
552
+...
553
+</programlisting>
554
+		</example>
504 555
 	</section>
556
+	</section>
557
+
505 558
 	<section>
506 559
 	<title>Event Routes</title>
507 560
 	<section id="topos.e.msg_outgoing">
... ...
@@ -552,6 +605,57 @@ event_route[topos:msg-sending] {
552 605
   }
553 606
 }
554 607
 ...
608
+</programlisting>
609
+		</example>
610
+	</section>
611
+	<section id="topos.e.msg_incoming">
612
+		<title>event_route[topos:msg-incoming]</title>
613
+		<para>
614
+		It is executed before doing topology stripping processing for an incoming
615
+		SIP message. If 'drop' is executed inside the event route, then the
616
+		module skips doing the topology hiding.
617
+		</para>
618
+		<para>
619
+		Inside the event route the variables $si, $sp and
620
+		$proto point to the source address. The SIP message is not the one
621
+		to be sent out, but an internally generated one at startup, to avoid
622
+		reparsing the outgoing SIP message for the cases when topology hiding
623
+		is not wanted.
624
+		</para>
625
+		<example>
626
+		<title>Usage of event_route[topos:msg-incoming]</title>
627
+		<programlisting format="linespecific">
628
+...
629
+event_route[topos:msg-incoming] {
630
+  if($si=="10.1.1.10") {
631
+    drop;
632
+  }
633
+}
634
+...
635
+</programlisting>
636
+		</example>
637
+	</section>
638
+	<section id="topos.e.msg_receiving">
639
+		<title>event_route[topos:msg-receiving]</title>
640
+		<para>
641
+		It is executed before doing topology stripping processing for a SIP
642
+		message that was received, being executed after event_route[topos:msg-incoing].
643
+		</para>
644
+		<para>
645
+		Inside the event route the variables $si, $sp and
646
+		$proto point to the source address. The SIP message is the one
647
+		to be sent out.
648
+		</para>
649
+		<example>
650
+		<title>Usage of event_route[topos:msg-receoving]</title>
651
+		<programlisting format="linespecific">
652
+...
653
+event_route[topos:msg-receiving] {
654
+  if(is_request() and $fU=="alice") {
655
+    drop;
656
+  }
657
+}
658
+...
555 659
 </programlisting>
556 660
 		</example>
557 661
 	</section>