MSRP Gateway Module

Table of Contents

1. Admin Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. hash_size (int)
1.3.2. cleanup_interval (int)
1.3.3. session_timeout (int)
1.3.4. message_timeout (int)
1.4. Exported Functions
1.4.1. msrp_gw_answer(key, content_types, from, to, ruri)
1.4.2. msg_to_msrp(key, content_types)
1.5. Exported MI Functions
1.5.1. msrp_gw_list_sessions
1.5.2. msrp_gw_end_session
1.6. Exported Events
1.6.1. E_MSRP_GW_SETUP_FAILED
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

List of Examples

1.1. Set hash_size parameter
1.2. Set cleanup_interval parameter
1.3. Set session_timeout parameter
1.4. Set message_timeout parameter
1.5. msrp_gw_answer() usage
1.6. msg_to_msrp() usage

Chapter 1. Admin Guide

1.1. Overview

This module implements a Gateway for translating between Page Mode (SIP MESSAGE method) and Session Mode (MSRP) Instant Messaging.

The module makes use of the msrp_ua module's API for the MSRP UAC/UAS functionalities.

1.2. Dependencies

1.2.1. OpenSIPS Modules

The following modules must be loaded before this module:

  • tm

  • msrp_ua

1.2.2. External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

  • None.

1.3. Exported Parameters

1.3.1. hash_size (int)

The size of the hash table that stores the gateway session information. It is the 2 logarithmic value of the real size.

Default value is “10” (1024 records).

Example 1.1. Set hash_size parameter

...
modparam("msrp_gateway", "hash_size", 16)
...

1.3.2. cleanup_interval (int)

The interval between full iterations of the sessions table in order to clean up lingering sessions.

Default value is “60”. (seconds)

Example 1.2. Set cleanup_interval parameter

...
modparam("msrp_gateway", "cleanup_interval", 60)
...

1.3.3. session_timeout (int)

Amount of time (in seconds) since last message has been received from either side, after which a session should be terminated.

The default value is 12 * 3600 seconds (12 hours).

Example 1.3. Set session_timeout parameter

...
modparam("msrp_gateway", "session_timeout", 7200)
...

1.3.4. message_timeout (int)

Amount of time (in seconds) since last MESSAGE has been received after which a session should be terminated.

The default value is 2 * 3600 seconds (2 hours).

Example 1.4. Set message_timeout parameter

...
modparam("msrp_gateway", "message_timeout", 3600)
...

1.4. Exported Functions

1.4.1.  msrp_gw_answer(key, content_types, from, to, ruri)

This functions initializes a new gateway session by answering an initial INVITE from the MSRP side SIP session. After running this function the call will be completely handled by the MSRP UA engine and MSRP SEND requests will be automatically translated to SIP MESSAGE requests.

The SIP From, To, and RURI coordinates for building MESSAGE requests are passed as parameters to the function.

Parameters:

  • key (string) - gateway session key to be used to correlate the MESSAGE requests with the MSRP side SIP session. A simple example would be to build this key based on the From and To URIs from both sides(from the initial MSRP leg INVITE and SIP MESSAGE requests respectively).

  • content_types (string) - content types adevertised in the SDP offer on the MSRP side SIP session.

  • from (string) - From URI to be used for building SIP MESSAGE requests.

  • to (string) - To URI to be used for building SIP MESSAGE requests.

  • ruri (string) - Request-URI to be used for building SIP MESSAGE requests.

This function can be used only from a request route.

Example 1.5. msrp_gw_answer() usage

...
if (!has_totag() && is_method("INVITE")) {
	msrp_gw_answer($var(corr_key), "text/plain", $fu, $tu, $ru);
	exit;
}
...

1.4.2.  msg_to_msrp(key, content_types)

This functions translates a SIP MESSAGE request into a MSRP SEND request. The function will initialize a new gateway session and establish the MSRP side SIP session if it is not done so already by a previous call.

The SIP From, To, and RURI coordinates for the new MSRP side session are taken from the MESSAGE request and mirrored back when translating a MSRP SEND to SIP MESSAGE with msrp_gw_answer.

Parameters:

  • key (string) - gateway session key to be used to correlate the MESSAGE requests with the MSRP side SIP session. A simple example would be to build this key based on the From and To URIs from both sides(from the initial MSRP leg INVITE and SIP MESSAGE requests respectively).

  • content_types (string) - content types adevertised in the SDP offer on the MSRP side SIP session.

This function can be used only from a request route.

Example 1.6. msg_to_msrp() usage

...
if (is_method("MESSAGE")) {
	msg_to_msrp($var(corr_key), "text/plain");
	exit;
}
...

1.5. Exported MI Functions

1.5.1.  msrp_gw_list_sessions

Lists information about ongoing sessions.

Name: msrp_gw_list_sessions

Parameters

  • None.

MI FIFO Command Format: 

opensips-cli -x mi msrp_gw_list_sessions

1.5.2.  msrp_gw_end_session

Terminate an ongoing session.

Name: msrp_gw_end_session

Parameters

  • key (string) - session key

MI FIFO Command Format: 

opensips-cli -x mi msrp_gw_end_session alice@opensips.org-bob@opensips.org

1.6. Exported Events

1.6.1.  E_MSRP_GW_SETUP_FAILED

This event is triggered when the MSRP side SIP session fails to set up, when using the msg_to_msrp() function.

The event can be used to generate a message with the failure description, back on the MESSAGE side.

Parameters:

  • key - The session key.

  • from_uri - The URI in the SIP From header to use on the MESSAGE side.

  • to_uri - The URI in the SIP To header to use on the MESSAGE side.

  • ruri - The SIP Request URI to use on the MESSAGE side.

  • code - The SIP error code in the negative reply received on the MSRP side. Might be NULL if the MSRP UA session expired before receiving a negative reply.

  • reason - The SIP reason string in the negative reply received on the MSRP side. Might be NULL if the MSRP UA session expired before receiving a negative reply.

Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

 NameDevScoreCommitsLines ++Lines --
1. Vlad Patrascu (@rvlad-patrascu)219121919
2. Maksym Sobolyev (@sobomax)3144
3. Alexandra Titoc2110

(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

2.2. By Commit Activity

Table 2.2. Most recently active contributors(1) to this module

 NameCommit Activity
1. Alexandra TitocSep 2024 - Sep 2024
2. Maksym Sobolyev (@sobomax)Feb 2023 - Feb 2023
3. Vlad Patrascu (@rvlad-patrascu)May 2022 - Jan 2023

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: Vlad Patrascu (@rvlad-patrascu).

Documentation Copyrights:

Copyright © 2022 www.opensips-solutions.com