Table of Contents
append_to_reply(txt)
append_hf(txt)
append_hf(txt, hdr)
insert_hf(txt)
insert_hf(txt, hdr)
append_urihf(prefix, suffix)
is_present_hf(hf_name)
append_time()
is_method(name)
remove_hf(hname [,flags])
has_body_part([mime]),
is_audio_on_hold()
is_privacy(privacy_type)
remove_body_part([mime[,revert]]),
add_body_part(body,mime)
sipmsg_validate([flags[,result_pvar]])
codec_exists (name [,clock] )
codec_delete (name [,clock] )
codec_move_up (name [,clock] )
codec_move_down (name [,clock] )
codec_exists_re ( regexp )
codec_delete_re ( regexp )
codec_delete_except_re ( regexp )
codec_move_up_re ( regexp )
codec_move_down_re ( regexp )
change_reply_status(code, reason)
stream_exists(regexp)
stream_delete(regexp)
List of Tables
List of Examples
append_to_reply usageappend_hf usageappend_hf usageinsert_hf usageinsert_hf usageappend_urihf usageis_present_hf usageappend_time usageis_method usageremove_hf usagehas_body_part usageis_audio_on_hold usageis_privacy usageremove_body_part() usageadd_body_part usagesipmsg_validate usagecodec_exists usagecodec_delete usagecodec_move_up usagecodec_move_down usagecodec_move_down usagecodec_exists_re usagecodec_delete_re usagecodec_delete_except_re usagecodec_move_up_re usagecodec_move_down_re usagecodec_move_down usagechange_reply_status usagestream_exists usagestream_delete usageThe module implements SIP based operations over the messages processed by OpenSIPS. SIP is a text based protocol and the module provides a large set of very useful functions to manipulate the message at SIP level, e.g., inserting new headers or deleting them, check for method type, etc.
The following modules must be loaded before this module:
No dependencies on other OpenSIPS modules.
Append txt as header to all replies that will be generated by OpenSIPS for this request.
Meaning of the parameters is as follows:
txt - String which may contains pseudo-variables.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, ERROR_ROUTE.
Example 1.1. append_to_reply usage
...
append_to_reply("Foo: bar\r\n");
append_to_reply("Foo: $rm at $Ts\r\n");
...
Appends 'txt' as header after the last header field.
Meaning of the parameters is as follows:
txt - Header field to be appended. The value can contain pseudo-variables which will be replaced at run time.
Note: Headers which are added in main route cannot be removed in further routes (e.g. failure routes). So, the idea is not to add there any headers that you might want to remove later. To add headers temporarely use the branch route because the changes you do there are per-branch.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
Example 1.2. append_hf usage
...
append_hf("P-hint: VOICEMAIL\r\n");
append_hf("From-username: $fU\r\n");
...
Appends 'txt' as header after first 'hdr' header field.
Meaning of the parameters is as follows:
txt - Header field to be appended. The value can contain pseudo-variables which will be replaced at run time.
hdr - Header name after which the 'txt' is appended.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
Example 1.3. append_hf usage
...
append_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
append_hf("From-username: $fU\r\n", "Call-ID");
...
Inserts 'txt' as header before the first header field.
Meaning of the parameters is as follows:
txt - Header field to be inserted. The value can contain pseudo-variables which will be replaced at run time.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
Example 1.4. insert_hf usage
...
insert_hf("P-hint: VOICEMAIL\r\n");
insert_hf("To-username: $tU\r\n");
...
Inserts 'txt' as header before first 'hdr' header field.
Meaning of the parameters is as follows:
txt - Header field to be inserted. The value can contain pseudo-variables which will be replaced at run time.
hdr - Header name before which the 'txt' is inserted.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
Example 1.5. insert_hf usage
...
insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
insert_hf("To-username: $tU\r\n", "Call-ID");
...
Append header field name with original Request-URI in middle.
Meaning of the parameters is as follows:
prefix - string (usually at least header field name).
suffix - string (usually at least line terminator).
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
Return true if a header field is present in message.
The function is also able to distinguish the compact names. For exmaple “From” will match with “f”
Meaning of the parameters is as follows:
hf_name - Header field name.(long or compact form). The hf_name parameter can have the following types:
string - Static header field name
pvar - Header field name is given as a pseudo-variable (as string value)
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
Adds a time header to the reply of the request. You must use it before functions that are likely to send a reply, e.g., save() from 'registrar' module. Header format is: “Date: %a, %d %b %Y %H:%M:%S GMT”, with the legend:
%a abbreviated week of day name (locale)
%d day of month as decimal number
%b abbreviated month name (locale)
%Y year with century
%H hour
%M minutes
%S seconds
Return true if a header was successfully appended.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
Check if the method of the message matches the name. If name is a known method (invite, cancel, ack, bye, options, info, update, register, message, subscribe, notify, refer, prack), the function performs method ID testing (integer comparison) instead of ignore case string comparison.
The 'name' can be a list of methods in the form of 'method1|method2|...'. In this case, the function returns true if the SIP message's method is one from the list. IMPORTANT NOTE: in the list must be only methods defined in OpenSIPS with ID (invite, cancel, ack, bye, options, info, update, register, message, subscribe, notify, refer, prack, publish; for more see: http://www.iana.org/assignments/sip-parameters).
If used for replies, the function tests the value of method field from CSeq header.
Meaning of the parameters is as follows:
name - SIP method name
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
Example 1.9. is_method usage
...
if(is_method("INVITE"))
{
# process INVITEs here
}
if(is_method("OPTION|UPDATE"))
{
# process OPTIONs and UPDATEs here
}
...
Remove from message all headers with name “hname”
Returns true if at least one header is found and removed.
Meaning of the parameters is as follows:
hname - header name to be removed. The hname parameter can have the following types:
string - Header name to be removed
pvar - Header name to be removed is the value of an existing pseudo-variable (as string value)
pattern - pattern to match the names of the headers to be removed; can be a simple wildcard or a regexp (see the second param too)
flags - how to interpret the pattern from the first parameted.
r - pattern is a regexp
g - pattern is glob (shell wildcard pattern)
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE.
Example 1.10. remove_hf usage
...
if(remove_hf("User-Agent"))
{
# User Agent header removed
}
...
# removes X-Billing-Account, X-Billing-Price, X-Billing-rateplan, etc
remove_hf("X-Billing*", "g");
...
#removes headers by regex
remove_hf("^X-g.+[0-9]", "r");
...
The function returns true if the SIP message has any body part with the given MIME. If there is no MIME given, it will return true if at least one body part is found (with any MIME).
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE.
Example 1.11. has_body_part usage
...
if(has_body_part("application/sdp"))
{
# do interesting stuff here
}
...
The function returns true if the SIP message has an SDP body attached and at least one audio stream in on hold.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE.
The function returns true if the SIP message has a Privacy header field that includes the given privacy_type among its privacy values. See http://www.iana.org/assignments/sip-priv-values for possible privacy type values.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE.
Removes from the message body all the body parts with the given mime. The necessary corrections over the Content-Type and Content-Length headers are automatically done.
If a MIME type is given, it will delete only the body parts with that mime. If no MIME given, all the parts (entire body) will be removed.
Meaning of the parameters is as follows:
mime - mime to be checked against the body parts; If not present, all parts are to remvoed;
revert - usefull only if a MIME was specified. If "revert" string is given here, the function will delete all body parts but the ones with the given MIME.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
Example 1.14. remove_body_part() usage
...
#delete entire body message (all parts)
remove_body_part();
# delete all body parts with mime "application/isup"
remove_body_part("application/isup");
# delete all body parts but keep the the ones with "application/sdp"
remove_body_part("application/sdp","revert")
...
This function can be used to add a new body part to the message body. If another part already exist, body of the message will be converted to a multi-part body automatically.
Meaning of the parameters is as follows:
body - the content of the body part to be added - it may contain variables;
mime - the mime string for the body part to be added.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
The function returns true if the SIP message is properly built according to SIP RFC3261. It verifies if the mandatory headers for each request/reply and can also check the format of the headers body.
The flags parameter received is optional and can be composed with the following values:
's' - checks the integrity of the SDP body, if it exists
'h' - checks the format and integrity of each header body.
'm' - don't check the Max-Forwards header.
'r' - checks the R-URI and whether the domain contains valid characters.
'f' - checks the URI of the 'From' field and whether the domain contains valid characters.
't' - checks the URI of the 'To' field and whether the domain contains valid characters.
'c' - checks the URI of the 'Contact' field.
The result_pvar parameter sets resulting pvar with text error reason in case of negative result ( easy for logging or propagating the rejection reason back to the bogus UA )
This function can return the following codes:
1 - the message is RFC3261 compliant and has been successfully validated.
-1 - No SIP message
-2 - Header Parsing error
-3 - No Call-ID header
-4 - No Content-Length header for transports that require it ( eg. TCP )
-5 - Invalid Content-Length, other from the size of the actual body
-6 - SDP body parsing error.
-7 - No Cseq header.
-8 - No From header.
-9 - No To header.
-10 - No Via header.
-11 - Request URI parse error.
-12 - Bad hostname in R-URI.
-13 - No Max-Forward header.
-14 - No Contact header.
-15 - Path user for non-Register request.
-16 - No allow header in 405 reply.
-17 - No Min-Expire header in 423 reply.
-18 - No Proxy-Authorize header in 407 reply.
-19 - No Unsupported header in 420 reply.
-20 - No WWW-Authorize header in 401 reply.
-21 - No Content-Type header
-22 - To header parse error
-23 - From header parse error
-24 - Bad hostname in To header
-25 - Bad hostname in From header
-26 - Contact header parse error
-255 - undefined errors.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE.
Example 1.16. sipmsg_validate usage
...
if(!sipmsg_validate())
{
send_reply("400", "Bad Request");
exit;
}
...
...
# checks also the SDP and headers body
if(!sipmsg_validate("sh"))
{
send_reply("400", "Bad Request/Body");
exit;
}
...
This function can be used to verify if a codec exists inside an sdp payload. It will search for the codec inside all streams from all sdp sessions. If it is found anywhere it will return TRUE otherwise it will return FALSE. The second parameter is optional, if it is not supplied any clockrate will match. Parameters are CASE INSENSITIVE.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
This function can be used to delete a codec from inside an sdp payload. It will search for the codec inside all streams from all sdp sessions. If it is found anywhere it will be deleted from the mapping ("a=...") and from the list of indexes ("m=..."). Returns TRUE if any deletion occurred otherwise it will return FALSE. The second parameter is optional, if it is not supplied any clockrate will match and all will be deleted. Parameters are CASE INSENSITIVE.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
This function can be used to move a codec up in the list of indexes ("m=..."). It will search for the codec inside all streams from all sdp sessions. If it is found anywhere it will be moved to the top of the index list. Returns TRUE if any moves occurred otherwise it will return FALSE. The second parameter is optional, if it is not supplied any clockrate will match and all codecs will be moved to the front while preserving their original ordering. Parameters are CASE INSENSITIVE.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
This function can be used to move a codec down in the list of indexes ("m=..."). It will search for the codec inside all streams from all sdp sessions. If it is found anywhere it will be moved to the back of the index list. Returns TRUE if any moves occurred otherwise it will return FALSE. The second parameter is optional, if it is not supplied any clockrate will match and all codecs will be moved to the back while preserving their original ordering. Parameters are CASE INSENSITIVE.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
Example 1.20. codec_move_down usage
...
codec_move_down("speex");
or
codec_move_down("GSM","8000");
...
Example 1.21. codec_move_down usage
...
/*
This example will move speex with 8000 codec to the back of the list,
then it will erase GSM with 8000 clock, and then it will bring all
speex codecs to the front of the list. Speex/8000 will be behind any
other speex.
*/
codec_move_down("speex","8000");
codec_delete("GSM","8000");
codec_move_up("speex");
...
This function has the same effect as codec_exists ( without the clock parameter ) the only difference is that it takes a POSIX regular expression as a parameter.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
This function has the same effect as codec_delete ( without the clock parameter ) the only difference is that it takes a POSIX regular expression as a parameter.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
This function deletes all the codecs except those specified by the regular expression.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
Example 1.24. codec_delete_except_re usage
...
codec_delete_except_re("PCMA|PCMU");#will delete all codecs except PCMA and PCMU
...
This function has the same effect as codec_move_up ( without the clock parameter ) the only difference is that it takes a POSIX regular expression as a parameter.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
This function has the same effect as codec_move_down ( without the clock parameter ) the only difference is that it takes a POSIX regular expression as a parameter.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
Example 1.27. codec_move_down usage
...
/*
This example will move speex with 8000 codec to the back of the list,
then it will erase GSM with 8000 clock, and then it will bring all
speex codecs to the front of the list. Speex/8000 will be behind any
other speex.
*/
codec_move_down("speex","8000");
codec_delete("GSM","8000");
codec_move_up("speex");
...
Intercept a SIP reply (in any onreply_route) and change its status code and reason phrase prior to propogating it.
Meaning of the parameters is as follows:
code - Status code.
reason - Reason phrase.
This function can be used from ONREPLY_ROUTE.
Example 1.28. change_reply_status usage
...
onreply_route {
if ($rs == "603") {
change_reply_status("404", "Not Found");
exit;
}
}
...
This function can be used to verify if a stream exists inside an sdp payload. It will search for the stream inside all sdp sessions. If it is found anywhere it will return TRUE otherwise it will return FALSE.
Meaning of the parameters is as follows:
regexp - a POSIX regular expression to match the stream media name.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
This function can be used to delete a whole stream from inside an sdp payload. It will search for the stream inside all sdp sessions. If it is found anywhere it will be deleted along with all attributes Returns TRUE if any deletion occurred otherwise it will return FALSE.
Meaning of the parameters is as follows:
regexp - a POSIX regular expression to match the stream media name.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| Name | DevScore | Commits | Lines ++ | Lines -- | |
|---|---|---|---|---|---|
| 1. | Bogdan-Andrei Iancu (@bogdan-iancu) | 40 | 23 | 758 | 593 |
| 2. | Razvan Crainea (@razvancrainea) | 35 | 11 | 2885 | 33 |
| 3. | Liviu Chircu (@liviuchircu) | 16 | 11 | 201 | 153 |
| 4. | Vlad Paiu (@vladpaiu) | 9 | 4 | 281 | 68 |
| 5. | Mihai Tiganus (@tallicamike) | 6 | 3 | 155 | 28 |
| 6. | Boris Ratner | 4 | 1 | 129 | 46 |
| 7. | Julián Moreno Patiño | 3 | 1 | 8 | 8 |
| 8. | Jarrod Baumann (@jarrodb) | 3 | 1 | 2 | 2 |
| 9. | Ezequiel Lovelle | 3 | 1 | 1 | 1 |
| 10. | Peter Lemenkov (@lemenkov) | 3 | 1 | 1 | 1 |
All remaining contributors: Walter Doekes (@wdoekes), Nick Altmann (@nikbyte), Ionut Ionita (@ionutrazvanionita).
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated files
Table 2.2. Most recently active contributors(1) to this module
| Name | Commit Activity | |
|---|---|---|
| 1. | Bogdan-Andrei Iancu (@bogdan-iancu) | Feb 2012 - Jun 2018 |
| 2. | Liviu Chircu (@liviuchircu) | Nov 2012 - Jun 2018 |
| 3. | Razvan Crainea (@razvancrainea) | Feb 2012 - Dec 2016 |
| 4. | Jarrod Baumann (@jarrodb) | Mar 2016 - Mar 2016 |
| 5. | Julián Moreno Patiño | Feb 2016 - Feb 2016 |
| 6. | Ionut Ionita (@ionutrazvanionita) | Dec 2015 - Dec 2015 |
| 7. | Ezequiel Lovelle | Oct 2014 - Oct 2014 |
| 8. | Vlad Paiu (@vladpaiu) | Feb 2012 - Aug 2014 |
| 9. | Mihai Tiganus (@tallicamike) | Aug 2014 - Aug 2014 |
| 10. | Boris Ratner | Jan 2013 - Jan 2013 |
All remaining contributors: Nick Altmann (@nikbyte), Peter Lemenkov (@lemenkov), Walter Doekes (@wdoekes).
(1) including any documentation-related commits, excluding merge commits
Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Liviu Chircu (@liviuchircu), Julián Moreno Patiño, Razvan Crainea (@razvancrainea), Mihai Tiganus (@tallicamike), Vlad Paiu (@vladpaiu), Boris Ratner, Nick Altmann (@nikbyte).
doc copyrights:
Copyright © 2003 FhG FOKUS