Browse code

xhttp: extended example for event_route[xhttp:request]

Daniel-Constantin Mierla authored on 21/06/2021 07:42:28
Showing 1 changed files
... ...
@@ -222,6 +222,11 @@ event_route[xhttp:request] {
222 222
         </para>
223 223
         <programlisting  format="linespecific">
224 224
 ...
225
+tcp_accept_no_cl=yes
226
+...
227
+loadmodule "sl.so"
228
+loadmodule "xhttp.so
229
+...
225 230
 event_route[xhttp:request] {
226 231
     xhttp_reply("200", "OK", "text/html",
227 232
         "&lt;html&gt;&lt;body&gt;OK - [$si:$sp]&lt;/body&gt;&lt;/html&gt;");
Browse code

xhttp: fixed the docbook format

Daniel-Constantin Mierla authored on 23/06/2017 11:11:25
Showing 1 changed files
... ...
@@ -183,6 +183,9 @@ function ksr_xhttp_event(evname)
183 183
 	return 1;
184 184
 end
185 185
 ...
186
+</programlisting>
187
+	    </example>
188
+	</section>
186 189
 	</section>
187 190
 
188 191
 	<section>
Browse code

xhttp: added section for event route in the docs

Daniel-Constantin Mierla authored on 19/04/2017 07:30:46
Showing 1 changed files
... ...
@@ -207,5 +207,25 @@ event_route[xhttp:request] {
207 207
 	    </example>
208 208
 	</section>
209 209
 	</section>
210
+
211
+    <section>
212
+    <title>Event Routes</title>
213
+    <section id="xhttp.evr.request">
214
+        <title>
215
+        <function moreinfo="none">xhttp:request</function>
216
+        </title>
217
+        <para>
218
+			The event route is executed when a new HTTP request is received.
219
+        </para>
220
+        <programlisting  format="linespecific">
221
+...
222
+event_route[xhttp:request] {
223
+    xhttp_reply("200", "OK", "text/html",
224
+        "&lt;html&gt;&lt;body&gt;OK - [$si:$sp]&lt;/body&gt;&lt;/html&gt;");
225
+}
226
+...
227
+        </programlisting>
228
+	</section>
229
+	</section>
210 230
 </chapter>
211 231
 
Browse code

xhttp: documented event_callback parameter

Daniel-Constantin Mierla authored on 17/04/2017 06:15:36
Showing 1 changed files
... ...
@@ -156,6 +156,33 @@ modparam("xhttp", "url_match", "^/sip/")
156 156
 </programlisting>
157 157
 		</example>
158 158
 	</section>
159
+	<section id="xhttp.p.event_callback">
160
+		<title><varname>event_callback</varname> (str)</title>
161
+		<para>
162
+			The name of the function in the kemi configuration file (embedded
163
+			scripting language such as Lua, Python, ...) to be executed instead
164
+			of event_route[xhttp:request] block.
165
+		</para>
166
+		<para>
167
+			The function has one string parameter with the value "xhttp:request".
168
+		</para>
169
+		<para>
170
+		<emphasis>
171
+			Default value is 'empty' (no function is executed for events).
172
+		</emphasis>
173
+		</para>
174
+		<example>
175
+		<title>Set <varname>event_callback</varname> parameter</title>
176
+		<programlisting format="linespecific">
177
+...
178
+modparam("xhttp", "event_callback", "ksr_xhttp_event")
179
+...
180
+-- event callback function implemented in Lua
181
+function ksr_xhttp_event(evname)
182
+	KSR.info("===== xhttp module triggered event: " .. evname .. "\n");
183
+	return 1;
184
+end
185
+...
159 186
 	</section>
160 187
 
161 188
 	<section>
Browse code

xhttp: added section ids

Daniel-Constantin Mierla authored on 16/04/2017 07:48:40
Showing 1 changed files
... ...
@@ -10,13 +10,13 @@
10 10
 <!-- Module User's Guide -->
11 11
 
12 12
 <chapter>
13
-	
13
+
14 14
 	<title>&adminguide;</title>
15
-	
15
+
16 16
 	<section>
17 17
 	<title>Overview</title>
18 18
 	<para>
19
-		This module provides basic HTTP/1.0 server functionality inside 
19
+		This module provides basic HTTP/1.0 server functionality inside
20 20
 		&kamailio;. SIP and HTTP are very similar protocols, so, practically, the
21 21
 		SIP parser can easily handle HTTP requests just by adding a fake
22 22
 		Via header.
... ...
@@ -36,32 +36,32 @@
36 36
 	<title>Note on Latency</title>
37 37
 	<para>
38 38
 		Because HTTP requests in <emphasis>xhttp</emphasis> are handled
39
-		by the same, finite number of SIP worker processes that operate on 
40
-		SIP messages, the same general principles regarding script execution 
41
-		speed and throughput should be observed by the writer in 
39
+		by the same, finite number of SIP worker processes that operate on
40
+		SIP messages, the same general principles regarding script execution
41
+		speed and throughput should be observed by the writer in
42 42
 		<emphasis>event_route[xhttp:request]</emphasis> as in any other
43
-		part of the route script.  
43
+		part of the route script.
44 44
 	</para>
45 45
 	<para>
46 46
 		For example, if you initiate a database query in the HTTP request route
47 47
 		that takes a long time to return rows, the SIP worker process in which
48
-		the request is handled will be blocked for that time and unable to 
48
+		the request is handled will be blocked for that time and unable to
49 49
 		process other SIP messages.  In most typical installations, there are
50
-		only a few of these worker processes running.  
50
+		only a few of these worker processes running.
51 51
 	</para>
52 52
 	<para>
53 53
 		Therefore, it is highly inadvisable to execute particularly slow things in the
54
-		<emphasis>event_route[xhttp:request]</emphasis>, because the request is not 
55
-		handled in an asynchronous manner or otherwise peripherally to general 
56
-		SIP processing.  SIP worker threads will block, pending the outcome of the 
57
-		event route just like any other config script route.  
54
+		<emphasis>event_route[xhttp:request]</emphasis>, because the request is not
55
+		handled in an asynchronous manner or otherwise peripherally to general
56
+		SIP processing.  SIP worker threads will block, pending the outcome of the
57
+		event route just like any other config script route.
58 58
 	</para>
59 59
 	<para>
60
-		This is no more or less true for <emphasis>xhttp</emphasis> than it is for 
61
-		any other block of script in any other scenario, and does not warrant any 
62
-		extraordinary concern.  It nevertheless bears mention here because some 
63
-		processes with embedded HTTP servers have the request processing take place 
64
-		"outside" of the main synchronous event sequence, whether by creating 
60
+		This is no more or less true for <emphasis>xhttp</emphasis> than it is for
61
+		any other block of script in any other scenario, and does not warrant any
62
+		extraordinary concern.  It nevertheless bears mention here because some
63
+		processes with embedded HTTP servers have the request processing take place
64
+		"outside" of the main synchronous event sequence, whether by creating
65 65
 		separate threads or by some other asynchronous handling.  That is not the
66 66
 		case with <emphasis>xhttp</emphasis>.
67 67
 	</para>
... ...
@@ -114,7 +114,7 @@
114 114
 	</section>
115 115
 	<section>
116 116
 	<title>Parameters</title>
117
-	<section>
117
+	<section id="xhttp.p.url_skip">
118 118
 		<title><varname>url_skip</varname> (str)</title>
119 119
 		<para>
120 120
 			Regular expression to match the HTTP URL. If there is a match,
... ...
@@ -134,7 +134,7 @@ modparam("xhttp", "url_skip", "^/RPC2")
134 134
 </programlisting>
135 135
 		</example>
136 136
 	</section>
137
-	<section>
137
+	<section id="xhttp.p.url_match">
138 138
 		<title><varname>url_match</varname> (str)</title>
139 139
 		<para>
140 140
 			Regular expression to match the HTTP URL. If there is no match,
... ...
@@ -160,7 +160,7 @@ modparam("xhttp", "url_match", "^/sip/")
160 160
 
161 161
 	<section>
162 162
 	<title>Functions</title>
163
- 	<section>
163
+	<section id="xhttp.f.xhttp_reply">
164 164
 	    <title>
165 165
 		<function moreinfo="none">xhttp_reply(code, reason, ctype, body)</function>
166 166
 	    </title>
Browse code

doc, modules: updated the path to docbook entities and spec files

Daniel-Constantin Mierla authored on 07/12/2016 14:24:32
Showing 1 changed files
... ...
@@ -3,7 +3,7 @@
3 3
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4 4
 
5 5
 <!-- Include general documentation entities -->
6
-<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
6
+<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 7
 %docentities;
8 8
 
9 9
 ]>
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,184 @@
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 "../../../docbook/entities.xml">
7
+%docentities;
8
+
9
+]>
10
+<!-- Module User's Guide -->
11
+
12
+<chapter>
13
+	
14
+	<title>&adminguide;</title>
15
+	
16
+	<section>
17
+	<title>Overview</title>
18
+	<para>
19
+		This module provides basic HTTP/1.0 server functionality inside 
20
+		&kamailio;. SIP and HTTP are very similar protocols, so, practically, the
21
+		SIP parser can easily handle HTTP requests just by adding a fake
22
+		Via header.
23
+	</para>
24
+	<para>
25
+		The <module>xmlrpc</module> module uses the same concept.
26
+		The xHTTP module offers a generic way of handling the <acronym>HTTP</acronym>
27
+		protocol, by calling <emphasis>event_route[xhttp:request]</emphasis>
28
+		in your config. You can check the HTTP URL via the config variable
29
+		<acronym>$hu</acronym>. Note that use of <acronym>$ru</acronym> will
30
+		raise errors since the structure of an HTTP URL is not compatible with
31
+		that of a SIP URI.
32
+	</para>
33
+	</section>
34
+
35
+	<section>
36
+	<title>Note on Latency</title>
37
+	<para>
38
+		Because HTTP requests in <emphasis>xhttp</emphasis> are handled
39
+		by the same, finite number of SIP worker processes that operate on 
40
+		SIP messages, the same general principles regarding script execution 
41
+		speed and throughput should be observed by the writer in 
42
+		<emphasis>event_route[xhttp:request]</emphasis> as in any other
43
+		part of the route script.  
44
+	</para>
45
+	<para>
46
+		For example, if you initiate a database query in the HTTP request route
47
+		that takes a long time to return rows, the SIP worker process in which
48
+		the request is handled will be blocked for that time and unable to 
49
+		process other SIP messages.  In most typical installations, there are
50
+		only a few of these worker processes running.  
51
+	</para>
52
+	<para>
53
+		Therefore, it is highly inadvisable to execute particularly slow things in the
54
+		<emphasis>event_route[xhttp:request]</emphasis>, because the request is not 
55
+		handled in an asynchronous manner or otherwise peripherally to general 
56
+		SIP processing.  SIP worker threads will block, pending the outcome of the 
57
+		event route just like any other config script route.  
58
+	</para>
59
+	<para>
60
+		This is no more or less true for <emphasis>xhttp</emphasis> than it is for 
61
+		any other block of script in any other scenario, and does not warrant any 
62
+		extraordinary concern.  It nevertheless bears mention here because some 
63
+		processes with embedded HTTP servers have the request processing take place 
64
+		"outside" of the main synchronous event sequence, whether by creating 
65
+		separate threads or by some other asynchronous handling.  That is not the
66
+		case with <emphasis>xhttp</emphasis>.
67
+	</para>
68
+	</section>
69
+
70
+	<section>
71
+	<title>Dependencies</title>
72
+	<section>
73
+		<title>&kamailio; Modules</title>
74
+		<para>
75
+		The following modules must be loaded before this module:
76
+			<itemizedlist>
77
+			<listitem>
78
+			<para>
79
+				<emphasis>sl</emphasis> - stateless reply.
80
+			</para>
81
+			</listitem>
82
+			</itemizedlist>
83
+		</para>
84
+	</section>
85
+	<section>
86
+		<title>&kamailio; Core Settings</title>
87
+		<para>
88
+		SIP requires a Content-Length header for TCP transport. But most HTTP clients do not
89
+		set the content length for normal GET requests. Therefore, the core must be configured
90
+		to allow incoming requests without content length header:
91
+			<itemizedlist>
92
+			<listitem>
93
+			<para>
94
+				<emphasis>tcp_accept_no_cl=yes</emphasis>
95
+			</para>
96
+			</listitem>
97
+			</itemizedlist>
98
+		</para>
99
+	</section>
100
+	<section>
101
+		<title>External Libraries or Applications</title>
102
+		<para>
103
+		The following libraries or applications must be installed before running
104
+		&kamailio; with this module loaded:
105
+			<itemizedlist>
106
+			<listitem>
107
+			<para>
108
+				<emphasis>None</emphasis>
109
+			</para>
110
+			</listitem>
111
+			</itemizedlist>
112
+		</para>
113
+	</section>
114
+	</section>
115
+	<section>
116
+	<title>Parameters</title>
117
+	<section>
118
+		<title><varname>url_skip</varname> (str)</title>
119
+		<para>
120
+			Regular expression to match the HTTP URL. If there is a match,
121
+			the event route is not executed.
122
+		</para>
123
+		<para>
124
+		<emphasis>
125
+			Default value is null (don't skip).
126
+		</emphasis>
127
+		</para>
128
+		<example>
129
+		<title>Set <varname>url_skip</varname> parameter</title>
130
+		<programlisting format="linespecific">
131
+...
132
+modparam("xhttp", "url_skip", "^/RPC2")
133
+...
134
+</programlisting>
135
+		</example>
136
+	</section>
137
+	<section>
138
+		<title><varname>url_match</varname> (str)</title>
139
+		<para>
140
+			Regular expression to match the HTTP URL. If there is no match,
141
+			the event route is not executed. This check is done after
142
+			url_skip, so if both url_skip and url_match would match then
143
+			the event route is not executed (url_skip has higher priority).
144
+		</para>
145
+		<para>
146
+		<emphasis>
147
+			Default value is null (match everything).
148
+		</emphasis>
149
+		</para>
150
+		<example>
151
+		<title>Set <varname>url_match</varname> parameter</title>
152
+		<programlisting format="linespecific">
153
+...
154
+modparam("xhttp", "url_match", "^/sip/")
155
+...
156
+</programlisting>
157
+		</example>
158
+	</section>
159
+	</section>
160
+
161
+	<section>
162
+	<title>Functions</title>
163
+ 	<section>
164
+	    <title>
165
+		<function moreinfo="none">xhttp_reply(code, reason, ctype, body)</function>
166
+	    </title>
167
+	    <para>
168
+		Send back a reply with content-type and body.
169
+	    </para>
170
+		<example>
171
+		<title><function>xhttp_reply</function> usage</title>
172
+		<programlisting format="linespecific">
173
+...
174
+event_route[xhttp:request] {
175
+    xhttp_reply("200", "OK", "text/html",
176
+        "&lt;html&gt;&lt;body&gt;OK - [$si:$sp]&lt;/body&gt;&lt;/html&gt;");
177
+}
178
+...
179
+</programlisting>
180
+	    </example>
181
+	</section>
182
+	</section>
183
+</chapter>
184
+