GitList
Browse code

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

Kamailio Dev authored on 23/06/2017 11:16:24
Showing 1 changed files
src/modules/xhttp/README
History View file @ fec6764a6f
... ... 
@@ -1,2 +1,229 @@
1 
+xHTTP Module
1 2
3 
+Daniel-Constantin Mierla
2 4
5 
+   <miconda@gmail.com>
6 
+
7 
+Edited by
8 
+
9 
+Daniel-Constantin Mierla
10 
+
11 
+   <miconda@gmail.com>
12 
+
13 
+Edited by
14 
+
15 
+Alex Balashov
16 
+
17 
+   <abalashov@evaristesys.com>
18 
+
19 
+   Copyright © 2010 asipto.com
20 
+     __________________________________________________________________
21 
+
22 
+   Table of Contents
23 
+
24 
+   1. Admin Guide
25 
+
26 
+        1. Overview
27 
+        2. Note on Latency
28 
+        3. Dependencies
29 
+
30 
+              3.1. Kamailio Modules
31 
+              3.2. Kamailio Core Settings
32 
+              3.3. External Libraries or Applications
33 
+
34 
+        4. Parameters
35 
+
36 
+              4.1. url_skip (str)
37 
+              4.2. url_match (str)
38 
+              4.3. event_callback (str)
39 
+
40 
+        5. Functions
41 
+
42 
+              5.1. xhttp_reply(code, reason, ctype, body)
43 
+
44 
+        6. Event Routes
45 
+
46 
+              6.1. xhttp:request
47 
+
48 
+   List of Examples
49 
+
50 
+   1.1. Set url_skip parameter
51 
+   1.2. Set url_match parameter
52 
+   1.3. Set event_callback parameter
53 
+   1.4. xhttp_reply usage
54 
+
55 
+Chapter 1. Admin Guide
56 
+
57 
+   Table of Contents
58 
+
59 
+   1. Overview
60 
+   2. Note on Latency
61 
+   3. Dependencies
62 
+
63 
+        3.1. Kamailio Modules
64 
+        3.2. Kamailio Core Settings
65 
+        3.3. External Libraries or Applications
66 
+
67 
+   4. Parameters
68 
+
69 
+        4.1. url_skip (str)
70 
+        4.2. url_match (str)
71 
+        4.3. event_callback (str)
72 
+
73 
+   5. Functions
74 
+
75 
+        5.1. xhttp_reply(code, reason, ctype, body)
76 
+
77 
+   6. Event Routes
78 
+
79 
+        6.1. xhttp:request
80 
+
81 
+1. Overview
82 
+
83 
+   This module provides basic HTTP/1.0 server functionality inside
84 
+   Kamailio. SIP and HTTP are very similar protocols, so, practically, the
85 
+   SIP parser can easily handle HTTP requests just by adding a fake Via
86 
+   header.
87 
+
88 
+   The <module>xmlrpc</module> module uses the same concept. The xHTTP
89 
+   module offers a generic way of handling the HTTP protocol, by calling
90 
+   event_route[xhttp:request] in your config. You can check the HTTP URL
91 
+   via the config variable $hu. Note that use of $ru will raise errors
92 
+   since the structure of an HTTP URL is not compatible with that of a SIP
93 
+   URI.
94 
+
95 
+2. Note on Latency
96 
+
97 
+   Because HTTP requests in xhttp are handled by the same, finite number
98 
+   of SIP worker processes that operate on SIP messages, the same general
99 
+   principles regarding script execution speed and throughput should be
100 
+   observed by the writer in event_route[xhttp:request] as in any other
101 
+   part of the route script.
102 
+
103 
+   For example, if you initiate a database query in the HTTP request route
104 
+   that takes a long time to return rows, the SIP worker process in which
105 
+   the request is handled will be blocked for that time and unable to
106 
+   process other SIP messages. In most typical installations, there are
107 
+   only a few of these worker processes running.
108 
+
109 
+   Therefore, it is highly inadvisable to execute particularly slow things
110 
+   in the event_route[xhttp:request], because the request is not handled
111 
+   in an asynchronous manner or otherwise peripherally to general SIP
112 
+   processing. SIP worker threads will block, pending the outcome of the
113 
+   event route just like any other config script route.
114 
+
115 
+   This is no more or less true for xhttp than it is for any other block
116 
+   of script in any other scenario, and does not warrant any extraordinary
117 
+   concern. It nevertheless bears mention here because some processes with
118 
+   embedded HTTP servers have the request processing take place "outside"
119 
+   of the main synchronous event sequence, whether by creating separate
120 
+   threads or by some other asynchronous handling. That is not the case
121 
+   with xhttp.
122 
+
123 
+3. Dependencies
124 
+
125 
+   3.1. Kamailio Modules
126 
+   3.2. Kamailio Core Settings
127 
+   3.3. External Libraries or Applications
128 
+
129 
+3.1. Kamailio Modules
130 
+
131 
+   The following modules must be loaded before this module:
132 
+     * sl - stateless reply.
133 
+
134 
+3.2. Kamailio Core Settings
135 
+
136 
+   SIP requires a Content-Length header for TCP transport. But most HTTP
137 
+   clients do not set the content length for normal GET requests.
138 
+   Therefore, the core must be configured to allow incoming requests
139 
+   without content length header:
140 
+     * tcp_accept_no_cl=yes
141 
+
142 
+3.3. External Libraries or Applications
143 
+
144 
+   The following libraries or applications must be installed before
145 
+   running Kamailio with this module loaded:
146 
+     * None
147 
+
148 
+4. Parameters
149 
+
150 
+   4.1. url_skip (str)
151 
+   4.2. url_match (str)
152 
+   4.3. event_callback (str)
153 
+
154 
+4.1. url_skip (str)
155 
+
156 
+   Regular expression to match the HTTP URL. If there is a match, the
157 
+   event route is not executed.
158 
+
159 
+   Default value is null (don't skip).
160 
+
161 
+   Example 1.1. Set url_skip parameter
162 
+...
163 
+modparam("xhttp", "url_skip", "^/RPC2")
164 
+...
165 
+
166 
+4.2. url_match (str)
167 
+
168 
+   Regular expression to match the HTTP URL. If there is no match, the
169 
+   event route is not executed. This check is done after url_skip, so if
170 
+   both url_skip and url_match would match then the event route is not
171 
+   executed (url_skip has higher priority).
172 
+
173 
+   Default value is null (match everything).
174 
+
175 
+   Example 1.2. Set url_match parameter
176 
+...
177 
+modparam("xhttp", "url_match", "^/sip/")
178 
+...
179 
+
180 
+4.3. event_callback (str)
181 
+
182 
+   The name of the function in the kemi configuration file (embedded
183 
+   scripting language such as Lua, Python, ...) to be executed instead of
184 
+   event_route[xhttp:request] block.
185 
+
186 
+   The function has one string parameter with the value "xhttp:request".
187 
+
188 
+   Default value is 'empty' (no function is executed for events).
189 
+
190 
+   Example 1.3. Set event_callback parameter
191 
+...
192 
+modparam("xhttp", "event_callback", "ksr_xhttp_event")
193 
+...
194 
+-- event callback function implemented in Lua
195 
+function ksr_xhttp_event(evname)
196 
+        KSR.info("===== xhttp module triggered event: " .. evname .. "\n");
197 
+        return 1;
198 
+end
199 
+...
200 
+
201 
+5. Functions
202 
+
203 
+   5.1. xhttp_reply(code, reason, ctype, body)
204 
+
205 
+5.1.  xhttp_reply(code, reason, ctype, body)
206 
+
207 
+   Send back a reply with content-type and body.
208 
+
209 
+   Example 1.4. xhttp_reply usage
210 
+...
211 
+event_route[xhttp:request] {
212 
+    xhttp_reply("200", "OK", "text/html",
213 
+        "<html><body>OK - [$si:$sp]</body></html>");
214 
+}
215 
+...
216 
+
217 
+6. Event Routes
218 
+
219 
+   6.1. xhttp:request
220 
+
221 
+6.1.  xhttp:request
222 
+
223 
+   The event route is executed when a new HTTP request is received.
224 
+...
225 
+event_route[xhttp:request] {
226 
+    xhttp_reply("200", "OK", "text/html",
227 
+        "<html><body>OK - [$si:$sp]</body></html>");
228 
+}
229 
+...