Browse code

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

Kamailio Dev authored on 23/06/2017 11:16:24
Showing 1 changed files
... ...
@@ -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
+...