modules: readme files regenerated - sdpops ... [skip ci]
[sip-router] / src / modules / sdpops / README
1 SDPOPS Module
2
3 Daniel-Constantin Mierla
4
5    <miconda@gmail.com>
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11    <miconda@gmail.com>
12
13    Copyright © 2011 asipto.com
14      __________________________________________________________________
15
16    Table of Contents
17
18    1. Admin Guide
19
20         1. Overview
21         2. Dependencies
22
23               2.1. Kamailio Modules
24               2.2. External Libraries or Applications
25
26         3. Parameters
27         4. Functions
28
29               4.1. sdp_remove_codecs_by_id(list [, mtype])
30               4.2. sdp_remove_codecs_by_name(list [, mtype])
31               4.3. sdp_remove_line_by_prefix(string [, mtype])
32               4.4. sdp_keep_codecs_by_id(list [, mtype])
33               4.5. sdp_keep_codecs_by_name(list [, mtype])
34               4.6. sdp_with_media(type)
35               4.7. sdp_with_active_media(type)
36               4.8. sdp_remove_media(type)
37               4.9. sdp_with_transport(type)
38               4.10. sdp_with_transport_like(string)
39               4.11. sdp_transport(pv)
40               4.12. sdp_remove_transport(type)
41               4.13. sdp_with_codecs_by_id(list)
42               4.14. sdp_with_codecs_by_name(list)
43               4.15. sdp_print(level)
44               4.16. sdp_get(avpvar)
45               4.17. sdp_content([sloppy])
46               4.18. sdp_with_ice()
47               4.19. sdp_get_line_startswith(avpvar, string)
48
49    List of Examples
50
51    1.1. sdp_remove_codecs_by_id usage
52    1.2. sdp_remove_codecs_by_name usage
53    1.3. sdp_remove_line_by_prefix usage
54    1.4. sdp_keep_codecs_by_id usage
55    1.5. sdp_keep_codecs_by_name usage
56    1.6. sdp_with_media usage
57    1.7. sdp_with_active_media usage
58    1.8. sdp_remove_media usage
59    1.9. sdp_with_transport usage
60    1.10. sdp_with_transport_like usage
61    1.11. sdp_transport usage
62    1.12. sdp_remove_transport usage
63    1.13. sdp_with_codecs_by_id usage
64    1.14. sdp_with_codecs_by_name usage
65    1.15. sdp_print usage
66    1.16. sdp_get usage
67    1.17. sdp_content usage
68    1.18. sdp_with_ice usage
69    1.19. sdp_get_line_startswith usage
70
71 Chapter 1. Admin Guide
72
73    Table of Contents
74
75    1. Overview
76    2. Dependencies
77
78         2.1. Kamailio Modules
79         2.2. External Libraries or Applications
80
81    3. Parameters
82    4. Functions
83
84         4.1. sdp_remove_codecs_by_id(list [, mtype])
85         4.2. sdp_remove_codecs_by_name(list [, mtype])
86         4.3. sdp_remove_line_by_prefix(string [, mtype])
87         4.4. sdp_keep_codecs_by_id(list [, mtype])
88         4.5. sdp_keep_codecs_by_name(list [, mtype])
89         4.6. sdp_with_media(type)
90         4.7. sdp_with_active_media(type)
91         4.8. sdp_remove_media(type)
92         4.9. sdp_with_transport(type)
93         4.10. sdp_with_transport_like(string)
94         4.11. sdp_transport(pv)
95         4.12. sdp_remove_transport(type)
96         4.13. sdp_with_codecs_by_id(list)
97         4.14. sdp_with_codecs_by_name(list)
98         4.15. sdp_print(level)
99         4.16. sdp_get(avpvar)
100         4.17. sdp_content([sloppy])
101         4.18. sdp_with_ice()
102         4.19. sdp_get_line_startswith(avpvar, string)
103
104 1. Overview
105
106    This module provides functions for checking and managing the SDP
107    payloads of SIP messages.
108
109    Examples of functions this module offers: remove codecs from SDP, check
110    the media stream types and return attributes of SDP document. For the
111    full list of the features provided by this module and the
112    implementation state, please read the list of exported functions.
113
114 2. Dependencies
115
116    2.1. Kamailio Modules
117    2.2. External Libraries or Applications
118
119 2.1. Kamailio Modules
120
121    The following modules must be loaded before this module:
122      * none.
123
124 2.2. External Libraries or Applications
125
126    The following libraries or applications must be installed before
127    running Kamailio with this module loaded:
128      * None
129
130 3. Parameters
131
132    The module does not export any config parameters yet.
133
134 4. Functions
135
136    4.1. sdp_remove_codecs_by_id(list [, mtype])
137    4.2. sdp_remove_codecs_by_name(list [, mtype])
138    4.3. sdp_remove_line_by_prefix(string [, mtype])
139    4.4. sdp_keep_codecs_by_id(list [, mtype])
140    4.5. sdp_keep_codecs_by_name(list [, mtype])
141    4.6. sdp_with_media(type)
142    4.7. sdp_with_active_media(type)
143    4.8. sdp_remove_media(type)
144    4.9. sdp_with_transport(type)
145    4.10. sdp_with_transport_like(string)
146    4.11. sdp_transport(pv)
147    4.12. sdp_remove_transport(type)
148    4.13. sdp_with_codecs_by_id(list)
149    4.14. sdp_with_codecs_by_name(list)
150    4.15. sdp_print(level)
151    4.16. sdp_get(avpvar)
152    4.17. sdp_content([sloppy])
153    4.18. sdp_with_ice()
154    4.19. sdp_get_line_startswith(avpvar, string)
155
156 4.1.  sdp_remove_codecs_by_id(list [, mtype])
157
158    Remove the codecs provided in the parameter 'list' from all media
159    streams found in SDP payload. The parameter 'list' must be one item or
160    a comma separated list of numeric codec IDs. The parameter can be a
161    static string or a variable holding the list of numeric codec IDs.
162
163    This function can be used from ANY_ROUTE.
164
165    Example 1.1. sdp_remove_codecs_by_id usage
166 ...
167 # remove PCMU
168 sdp_remove_codecs_by_id("0");
169 # remove PCMU, PCMA and GSM
170 sdp_remove_codecs_by_id("0,8,3");
171 sdp_remove_codecs_by_id("17", "audio");
172 sdp_remove_codecs_by_id("23", "video");
173 ...
174
175 4.2.  sdp_remove_codecs_by_name(list [, mtype])
176
177    Remove the codecs provided in the parameter 'list' from all media
178    streams found in SDP payload. The parameter 'list' must be one item or
179    a comma separated list of codec names. The parameter can be a static
180    string or a variable holding the list of codec names.
181
182    Optional parameter mtype can be provided to apply the operations only
183    to the streams matching m=mtype.
184
185    This function can be used from ANY_ROUTE.
186
187    Example 1.2. sdp_remove_codecs_by_name usage
188 ...
189 # remove PCMU
190 sdp_remove_codecs_by_name("PCMU");
191 # remove PCMU, PCMA and GSM
192 sdp_remove_codecs_by_name("PCMU,PCMA,GSM");
193 ...
194
195 4.3.  sdp_remove_line_by_prefix(string [, mtype])
196
197    Remove all SDP attribute lines beginning with 'string' in all media
198    streams.
199
200    Optional parameter mtype can be provided to apply the operations only
201    to the streams matching m=mtype.
202
203    This function can be used from ANY_ROUTE.
204
205    Example 1.3. sdp_remove_line_by_prefix usage
206 ...
207 if ($si == "2001:DB8::8:800:200C:417A"
208         and ( has_body("application/sdp") or has_body("multipart/mixed")))
209 {
210     xlog("L_INFO", "Cleaning ugly SDP from $si\n");
211     sdp_remove_codecs_by_name("X-NSE");
212     sdp_remove_line_by_prefix("a=X-");
213 }
214
215 ...
216
217 4.4.  sdp_keep_codecs_by_id(list [, mtype])
218
219    Keep only the codecs provided in the parameter 'list' from all media
220    streams found in SDP payload. The parameter 'list' must be one item or
221    a comma separated list of numeric codec IDs. The parameter can be a
222    static string or a variable holding the list of numeric codec IDs.
223
224    Optional parameter mtype can be provided to apply the operations only
225    to the streams matching m=mtype.
226
227    This function can be used from ANY_ROUTE.
228
229    Example 1.4. sdp_keep_codecs_by_id usage
230 ...
231 # keep only PCMU
232 sdp_keep_codecs_by_id("0");
233 # keep PCMU, PCMA and GSM in audio stream
234 sdp_keep_codecs_by_id("0,8,3", "audio");
235 ...
236
237 4.5.  sdp_keep_codecs_by_name(list [, mtype])
238
239    Keep only the codecs provided in the parameter 'list' from all media
240    streams found in SDP payload. The parameter 'list' must be one or a
241    comma separated list of codec names. The parameter can be a static
242    string or a variable holding the list of codec names.
243
244    Note that you have to explicitely keep 'telephone-event' in the list of
245    names if you want to keep DTMF attributes.
246
247    Optional parameter mtype can be provided to apply the operations only
248    to the streams matching m=mtype.
249
250    This function can be used from ANY_ROUTE.
251
252    Example 1.5. sdp_keep_codecs_by_name usage
253 ...
254 # keep only PCMU
255 sdp_keep_codecs_by_name("PCMU");
256 # keep PCMU, PCMA and GSM
257 sdp_keep_codecs_by_name("PCMU,PCMA,GSM");
258 ...
259
260 4.6.  sdp_with_media(type)
261
262    Return true of the SDP has 'media=type ...' line. Useful to check the
263    content of the RTP sessions, such as 'audio' or 'video'. The parameter
264    can be static string or variable holding the media type.
265
266    This function can be used from ANY_ROUTE.
267
268    Example 1.6. sdp_with_media usage
269 ...
270 # check for video stream
271 if(sdp_with_media("video"))
272 {
273     # the session has a video stream
274 }
275 ...
276
277 4.7.  sdp_with_active_media(type)
278
279    Return true of the SDP has 'media=type ...' line and the media is
280    active. Useful to check the content of the RTP sessions, such as
281    'audio' or 'video'. Active media means the port is non-zero and the
282    direction is not "inactive" The parameter can be static string or
283    variable holding the media type.
284
285    This function can be used from ANY_ROUTE.
286
287    Example 1.7. sdp_with_active_media usage
288 ...
289 # check for active video stream
290 if(sdp_with_active_media("video"))
291 {
292     # the session has an active video stream
293 }
294 ...
295
296 4.8.  sdp_remove_media(type)
297
298    Remove the streams that match on 'm=type ...' line. The parameter can
299    be static string or variable holding the media type.
300
301    Note: If this is executed on a request, the callee should reply without
302    the Media too. However, RFC 3264 mandates, that the reply should
303    contain the exact same number of "m=" lines as the request.
304
305
306      6 Generating the Answer
307
308      [...]
309
310      For each "m=" line in the offer, there MUST be a corresponding "m="
311      line in the answer. The answer MUST contain exactly the same number of
312      "m=" lines as the offer. This allows for streams to be matched up based
313      on their order. This implies that if the offer contained zero "m="
314      lines, the answer MUST contain zero "m=" lines.
315
316                                                                   --RFC 3264
317
318    So this may not work with all Endpoints, especially if they follow RFC
319    3264 precisely (e.g. JSSIP).
320
321    This function can be used from ANY_ROUTE.
322
323    Example 1.8. sdp_remove_media usage
324 ...
325 # remove video stream
326 sdp_remove_media("video");
327 ...
328
329 4.9.  sdp_with_transport(type)
330
331    Return true of the SDP has 'media=media port type ...' line. Useful to
332    check the transport of the RTP sessions, such as 'RTP/AVP', 'RTP/SAVP'
333    or 'RTP/SAVPF'. The parameter can be static string or variable holding
334    the transport type.
335
336    This function can be used from ANY_ROUTE.
337
338    Example 1.9. sdp_with_transport usage
339 ...
340 # check for RTP/SAVP stream
341 if(sdp_with_transport("RTP/SAVP"))
342 {
343     # the session has a SRTP/SAVP stream
344 }
345 ...
346
347 4.10.  sdp_with_transport_like(string)
348
349    Returns true if the SDP has 'media=media port type ...' line, where
350    type contains string. The parameter can be static string or variable
351    holding a string.
352
353    This function can be used from ANY_ROUTE.
354
355    Example 1.10. sdp_with_transport_like usage
356 ...
357 # check for SAVPF stream
358 if(sdp_with_transport_like("SAVPF"))
359 {
360     # the session has a SAVPF stream, e.g., RTP/SAVPF or UDP/TLS/RTP/SAVPF
361 }
362 ...
363
364 4.11.  sdp_transport(pv)
365
366    Assigns common media transport (if any) of 'm' lines to pv argument.
367    Returns 1 if common media transport was found, -2 if there was no
368    common media transport, and -1 in case of error.
369
370    This function can be used from ANY_ROUTE.
371
372    Example 1.11. sdp_transport usage
373 ...
374 sdp_transport("$avp(caller_rtp_transport)");
375 ...
376
377 4.12.  sdp_remove_transport(type)
378
379    Remove the streams that match on 'm=media port type ...' line. The
380    parameter can be static string or variable holding the transport type.
381
382    This function can be used from ANY_ROUTE.
383
384    Example 1.12. sdp_remove_transport usage
385 ...
386 # remove stream with transport RTP/AVP
387 sdp_remove_transport("RTP/AVP");
388 ...
389
390 4.13.  sdp_with_codecs_by_id(list)
391
392    Returns true if any of the codecs provided in the parameter 'list' from
393    all media streams is found in SDP payload. The parameter 'list' must be
394    one or a comma separated list of numeric codec IDs. The parameter can
395    be a static string or a variable holding the list of numeric codec IDs.
396
397    This function can be used from ANY_ROUTE.
398
399    Example 1.13. sdp_with_codecs_by_id usage
400 ...
401 # test for PCMU
402 if(sdp_with_codecs_by_id("0")) { ... }
403 # test for PCMU, PCMA or GSM
404 if(sdp_with_codecs_by_id("0,8,3")) { ... }
405 ...
406
407 4.14.  sdp_with_codecs_by_name(list)
408
409    Returns true if any of the codecs provided in the parameter 'list' from
410    all media streams is found in SDP payload. The parameter 'list' must be
411    one item or a comma separated list of codec names. The parameter can be
412    a static string or a variable holding the list of codec names.
413
414    This function can be used from ANY_ROUTE.
415
416    Example 1.14. sdp_with_codecs_by_name usage
417 ...
418 # test for PCMU
419 if(sdp_with_codecs_by_name("PCMU")) { ... }
420 # test for PCMU, PCMA or GSM
421 if(sdp_with_codecs_by_name("PCMU,PCMA,GSM")) { ... }
422 ...
423
424 4.15.  sdp_print(level)
425
426    Print the SDP internal structure to log 'level'. The parameter can be
427    static integer or variable holding the integer value of the log level.
428
429    This function can be used from ANY_ROUTE.
430
431    Example 1.15. sdp_print usage
432 ...
433 # print the SDP
434 sdp_print("1");
435 ...
436
437 4.16.  sdp_get(avpvar)
438
439    Store the SDP part of message body in an AVP. Return 1 if SDP is found,
440    -1 on error and -2 if there is no SDP part in the message body.
441
442    This function can be used from ANY_ROUTE.
443
444    Example 1.16. sdp_get usage
445 ...
446 sdp_get("$avp(sdp)");
447 ...
448
449 4.17.  sdp_content([sloppy])
450
451    Return true if the SIP message has SDP body or a SDP part in body. If
452    an argument is given, the function does not parse message body, but
453    returns true if Content-Type is "application/sdp" or if that string
454    exists in "multipart/mixed" body.
455
456    This function can be used from ANY_ROUTE.
457
458    Example 1.17. sdp_content usage
459 ...
460 if(sdp_content()) {
461     ...
462 }
463 ...
464
465 4.18.  sdp_with_ice()
466
467    Return true if the SIP message has SDP body that contains ICE candidate
468    attribute(s).
469
470    This function can be used from ANY_ROUTE.
471
472    Example 1.18. sdp_with_ice usage
473 ...
474 if(sdp_with_ice()) {
475     ...
476 }
477 ...
478
479 4.19.  sdp_get_line_startswith(avpvar, string)
480
481    Store the search part of SDP body message with line beginning with
482    'string' in an AVP. Return 1 if 'string' is found in SDP, -1 on error
483    and -2 if there is no SDP part in the message body.
484
485    This function can be used from ANY_ROUTE.
486
487    Example 1.19. sdp_get_line_startswith usage
488 ...
489 if(sdp_get_line_startswith("$avp(mline)", "m=")) {
490         xlog("m-line: $avp(mline)\n");
491 }
492 ...