git.sip-router.org Git - sip-router/blob - 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 ...