rtpengineclient

v0.1.6

rtpengineclient v0.1.6 RtpEngineClient

This is a client for the Sipwise NGCP RtpEngine proxy. This client assumes you have configured the daemon to support the NG protocol, where the RtpEngine can rewrite the SDP parameters (argument --listen-ng).

Summary

Types

address_family_option()
ans_opts()
answer_option()
branch_option()
call_id()
delete_option()
delete_options()
direction_option()
dtls_option()
flag_option()
flags_option()
from_tag()
ice_option()
list_option()
list_opts()
media_address_option()
metadata_option()
offer_option()
offer_opts()
on_delete()
on_list()
on_ping()
on_query()
on_reply()
query_option()
query_opts()
received_from_option()
record_call_option()
replace_option()
rtcp_mux_option()
sdes_flags()
sdes_option()
sdp()
to_tag()
to_tag_option()
tos_option()
transport_protocol_option()

Functions

answer(sdp, call_id, from_tag, to_tag, opts \\ [], timeout \\ 10000)

Sends a SDP answer to RtpEngine proxy

delete(call_id, from_tag, opts \\ [], timeout \\ 10000)

Deletes a call created by the offer/5 and answer/6 functions

list(opts \\ [], timeout \\ 10000)

Lists the currently active call-ids

offer(sdp, call_id, from_tag, opts \\ [], timeout \\ 10000)

Sends a SDP offer to RtpEngine proxy

ping(timeout \\ 10000)

Pings the RtpEngine service

query(call_id, opts \\ [], timeout \\ 10000)

Queries a specific active call

start_link(rtpengine_address)

Starts the RtpEngine client

Types

address_family_option() 
address_family_option() :: {:address_family, :inet | :inet6}
ans_opts() 
ans_opts() :: [answer_option]
branch_option() 
branch_option() :: {:branch, String.t}
call_id() 
call_id() :: String.t
delete_option() 
delete_option ::
  branch_option |
  to_tag_option |
  {:flags, [:fatal]} |
  {:delay, seconds :: integer}
delete_options() 
delete_options() :: [delete_option]
direction_option() 
direction_option() :: {:direction, {String.t | :round_robin_calls, String.t | :round_robin_calls}}
dtls_option() 
dtls_option() :: {:dtls, false | :passive}
flag_option() 
flag_option ::
  :sip_source_address |
  :trust_address |
  :symmetric |
  :asymmetric |
  :unidirectional |
  :strict_source |
  :media_handover |
  :reset |
  :port_latching |
  :record_call
flags_option() 
flags_option() :: {:flags, [flag_option]}
from_tag() 
from_tag() :: String.t
ice_option() 
ice_option() :: {:ice, :remove | :force | :force_relay}
list_option() 
list_option() :: {:limit, max_results :: integer}
list_opts() 
list_opts() :: [list_option]
media_address_option() 
media_address_option() :: {:media_address, String.t | :inet.ip_address}
metadata_option() 
metadata_option() :: {:metadata, String.t}
offer_opts() 
offer_opts() :: [offer_option]
on_delete() 
on_delete() :: {:ok, term} | {:error, reason :: term}
on_list() 
on_list() :: {:ok, list :: term} | {:error, reason :: term}
on_ping() 
on_ping() :: :ok | {:error, reason :: term}
on_query() 
on_query() :: {:ok, call_info :: term} | {:error, reason :: term}
on_reply() 
on_reply() :: {:ok, sdp} | {:error, reason :: term}
query_option() 
query_option() :: {:from_tag, String.t} | to_tag_option
query_opts() 
query_opts() :: [query_option]
received_from_option() 
received_from_option() :: {:received_from, {family :: :inet | :inet6, String.t} | :inet.ip_address}
record_call_option() 
record_call_option() :: {:record_call, boolean}
replace_option() 
replace_option() :: {:replace, [:origin | :session_connection]}
rtcp_mux_option() 
rtcp_mux_option() :: {:rtcp_mux, [:offer | :demux | :accept | :reject]}
sdes_flags() 
sdes_flags ::
  :unencrypted_srtp |
  :unencrypted_srtcp |
  :unauthenticated_srtp |
  :encrypted_srtp |
  :encrypted_srtcp |
  :authenticated_srtp
sdes_option() 
sdes_option() :: {:sdes, false | [sdes_flags]}
sdp() 
sdp() :: String.t
to_tag() 
to_tag() :: String.t
to_tag_option() 
to_tag_option() :: {:to_tag, String.t}
tos_option() 
tos_option() :: {:tos, integer}
transport_protocol_option() 
transport_protocol_option() :: {:transport_protocol, String.t}

Functions

answer(sdp, call_id, from_tag, to_tag, opts \\ [], timeout \\ 10000) 
answer(sdp, call_id, from_tag, to_tag, ans_opts, timeout) :: on_reply

Sends a SDP answer to RtpEngine proxy.

sdp is the complete SDP body as string. call_id is the SIP Call-ID header value as string. from_tag is the SIP From header tag parameter as string. to_tag is the SIP To header tag parameter as string.

The timeout parameter indicates the time in milliseconds to wait for a RtpEngine response, the default is 10 seconds.

The optional parameters are identical to the offer/5 function, except that the :direction does not make sense in the answer message.

delete(call_id, from_tag, opts \\ [], timeout \\ 10000) 
delete(call_id, from_tag, delete_options, timeout) :: on_delete

Deletes a call created by the offer/5 and answer/6 functions.

call_id is the SIP Call-ID header value as string. from_tag is the SIP From header tag parameter as string.

The timeout parameter indicates the time in milliseconds to wait for a RtpEngine response, the default is 10 seconds.

Optional parameters are:

  • :to_tag is the SIP To header tag parameter as string. Used to additionally refine the matching logic between media streams and calls and call branches.
  • :branch is the topmost SIP Via header branch parameter as string. Used to additionally refine the matching logic between media streams and calls and call branches.

  • :flags specifies a list of flags to turn on:

    • :fatal specifies that any non-syntactical error encountered when deleting the stream (such as unknown call_id) shall result in an error. The default is to log warnings and return :ok.
  • :delay specifies an integer representing the time in seconds in which the call should be deleted. If zero, the call will be immediately deleted.
list(opts \\ [], timeout \\ 10000) 
list(list_opts, timeout) :: on_list

Lists the currently active call-ids.

You may specify an optional argument :limit that indicates the maximum number of results in the reply, otherwise the default is 32.

The timeout parameter indicates the time in milliseconds to wait for a RtpEngine response, the default is 10 seconds.

offer(sdp, call_id, from_tag, opts \\ [], timeout \\ 10000) 
offer(sdp, call_id, from_tag, offer_opts, timeout) :: on_reply

Sends a SDP offer to RtpEngine proxy.

sdp is the complete SDP body as string. call_id is the SIP Call-ID header value as string. from_tag is the SIP From header tag parameter as string.

The timeout parameter indicates the time in milliseconds to wait for a RtpEngine response, the default is 10 seconds.

Optional parameters are:

  • :branch is the topmost SIP Via header branch parameter as string. Used to additionally refine the matching logic between media streams and calls and call branches.

  • :flags is an atom list of:

    • :sip_source_address ignores any IP addresses given in the SDP body and use the source address of the received SIP message (given in :received_from) as default endpoint address. This was the default behaviour of older versions of RtpEngine and can still be made the default behaviour through the --sip-source CLI switch. Can be overridden through the :media_address key.
    • :trust_address does the opposite of :sip_source_address. This is the default behaviour unless the CLI switch --sip-source is active. Corresponds to the rtpproxy r flag. Can be overridden through the :media_address key.
    • :symmetric corresponds to the rtpproxy w flag. Not used by RtpEngine as this is the default, unless :asymmetric is specified.
    • :asymmetric corresponds to the rtpproxy a flag. Advertises an RTP endpoint which uses asymmetric RTP, which disables learning of endpoint addresses (see below).
    • :unidirectional kernelizes also one-way rtp media.
    • :strict_source continues to inspect the source address and port of incoming packets after the learning phase and compare them with the endpoint address that has been learned before. If there’s a mismatch, the packet will be dropped and not forwarded. Without this flag, RtpEngine will attempt to learn the correct endpoint address for every stream during the first few seconds after signalling by observing the source address and port of incoming packets (unless :asymmetric is specified). Afterwards, source address and port of incoming packets are normally ignored and packets are forwarded regardless of where they’re coming from.
    • :media_handover is similar to the :strict_source option, but instead of dropping packets when the source address or port don’t match, the endpoint address will be re-learned and moved to the new address. This allows endpoint addresses to change on the fly without going through signalling again. Note that this opens a security hole and potentially allows RTP streams to be hijacked, either partly or in whole.
    • :reset causes RtpEngine to un-learn certain aspects of the RTP endpoints involved, such as support for ICE or support for SRTP. For example, if ice: :force is given, then RtpEngine will initially offer ICE to the remote endpoint. However, if a subsequent answer from that same endpoint indicates that it doesn’t support ICE, then no more ICE offers will be made towards that endpoint, even if ice: :force is still specified. With the reset flag given, this aspect will be un-learned and RtpEngine will again offer ICE to this endpoint. This flag is valid only in an offer message and is useful when the call has been transferred to a new endpoint without change of From or To tags.
    • :port_latching forces RtpEngine to retain its local ports during a signalling exchange even when the remote endpoint changes its port.
    • :record_call is identical to setting record_call: true (see below).

  • :replace is similar to the flags list. Controls which parts of the SDP body should be rewritten. Contains zero or more of:

    • :origin replaces the address found in the origin (o=) line of the SDP body. Corresponds to rtpproxy o flag.
    • :session_connection replaces the address found in the session-level connection (c=) line of the SDP body. Corresponds to rtpproxy c flag.
  • :direction contains a tuple of two strings and corresponds to the rtpproxy e and i flags. Each element must correspond to one of the named logical interfaces configured on the command line (through --interface). For example, if there is one logical interface named pub and another one named priv, then if side A (originator of the message) is considered to be on the private network and side B (destination of the message) on the public network, then that would be rendered as direction: {"priv", "pub"}. This only needs to be done for an initial offer; for the answer and any subsequent offers (between the same endpoints) RtpEngine will remember the selected network interface. A direction keyword is :round_robin_calls. If this is specified, a round robin algorithm runs for choosing the logical interface for the current stream (e.g. audio, video). The algorithm checks that all local interfaces of the tried logical interface have free ports for call streams. If a logical interface fails the check, the next one is tried. If there is no logical interface found with this property, it fallbacks to the default behaviour (e.g. return first logical interface in --interface list even if no free ports are available). The attribute is ignored for answers because the logical interface was already selected at offers. Note that naming an interface as round-robin-calls and trying to select it using direction will run the above algorithm!
  • :received_from contains a tuple of two elements where the first element denotes the address family (:inet or :inet6) and the second element is the SIP message’s source address itself. It can be also the SIP message’s source IP address tuple as specified in :inet.ip_address(), and in this case the family is obtained automatically. Used if SDP addresses are neither trusted (through the flag :sip_source_address or the command line argument --sip-source) nor the :media_address key is present.
  • :ice contains either :remove, :force or :force_relay. With :remove, any ICE attributes are stripped from the SDP body. With :force, ICE attributes are first stripped, then new attributes are generated and inserted, which leaves the media proxy as the only ICE candidate. The default behavior (no ICE key present at all) is: if no ICE attributes are present, a new set is generated and the media proxy lists itself as ICE candidate; otherwise, the media proxy inserts itself as a low-priority candidate. With :force_relay, existing ICE candidates are left in place except relay type candidates, and RtpEngine inserts itself as a relay candidate. It will also leave SDP c= and m= lines unchanged. This flag operates independently of the replace flags.
  • :transport_protocol rewrites the transport protocol specified in the SDP body. The media proxy expects to receive this protocol on the allocated ports, and will talk this protocol when sending packets out. Translation between different transport protocols will happen as necessary. Valid values are: "RTP/AVP", "RTP/AVPF", "RTP/SAVP", "RTP/SAVPF".
  • :media_address can be used to override both the addresses present in the SDP body and the received from address. Contains either an IPv4 or an IPv6 address, expressed as simple string or one of the :inet.ip_address() tuples. The format must be dotted-quad notation for IPv4 or RFC 5952 notation for IPv6. It’s up to the RTP proxy to determine the address family type.
  • :address_family is either :inet or :inet6 to select the primary address family in the substituted SDP body. The default is to auto-detect the address family if possible (if the recieving end is known already) or otherwise to leave it unchanged.

  • :rtcp_mux is a list of atoms controlling the behaviour regarding rtcp-mux (multiplexing RTP and RTCP on a single port, RFC 5761). The default behaviour is to go along with the client’s preference. The list can contain zero of more of the following atoms. Note that some of them are mutually exclusive.

    • :offer instructs RtpEngine to always offer rtcp-mux, even if the client itself doesn’t offer it.
    • :demux don’t offer it to the other side if the client is offering rtcp-mux, but accept it back to the offering client.
    • :accept instructs RtpEngine to accept rtcp-mux and also offer it to the other side if it has been offered.
    • :reject rejects rtcp-mux if it has been offered. Can be used together with :offer to achieve the opposite effect of :demux.
  • :tos contains an integer representing the TOS value used in outgoing RTP packets of all RTP streams in all directions. If a negative value is used, the previously used TOS value is left unchanged. If this key is not present or its value is too large (256 or more), then the TOS value is reverted to the default (as per --tos command line argument).

  • :dtls contains either false or :passive, and influences the behaviour of DTLS-SRTP. Their meanings are:

    • false prevents RtpEngine from offering or acceping DTLS-SRTP when otherwise it would. The default is to offer DTLS-SRTP when encryption is desired and to favour it over SDES when accepting an offer.
    • :passive instructs RtpEngine to prefer the passive (i.e. server) role for the DTLS handshake. The default is to take the active (client) role if possible. This is useful in cases where the SRTP endpoint isn’t able to receive or process the DTLS handshake packets, for example when it’s behind NAT or needs to finish ICE processing first.

  • :sdes is a list of options controlling the behaviour regarding SDES. The default is to offer SDES without any session parameters when encryption is desired, and to accept it when DTLS-SRTP is unavailable. If two SDES endpoints are connected to each other, then the default is to offer SDES with the same options as were received from the other endpoint.

    • false prevents RtpEngine from offering SDES, leaving DTLS-SRTP as the other option.
    • :unencrypted_srtp, :unencrypted_srtcp and :unauthenticated_srtp enable the respective SDES session parameter (see section 6.3 or RFC 4568). The default is to copy these options from the offering client, or not to have them enabled if SDES wasn’t offered.
    • :encrypted_srtp, :encrypted_srtcp and :authenticated_srtp negates the respective option. This is useful if one of the session parameters was offered by an SDES endpoint, but it should not be offered on the far side if this endpoint also speaks SDES.
  • :record_call is a boolean flag telling whether to record the call to PCAP files. If the call is recorded, it will generate PCAP files for each stream and a metadata file for each call. Note that RtpEngine will not force itself into the media path, and other flags like ice: :force may be necessary to ensure the call is recorded. See the --recording-dir RtpEngine argument. Enabling call recording via this option has the same effect as doing it separately via the start recording message, except that this option guarantees that the entirety of the call gets recorded, including all details such as SDP bodies passing through RtpEngine.
  • :metadata is a generic metadata string. The metadata will be written to the bottom of metadata files within /path/to/recording_dir/metadata/. This can be used to record additional information about recorded calls. :metadata values passed in through subsequent messages will overwrite previous metadata values. See the --recording-dir RtpEngine argument.
ping(timeout \\ 10000) 
ping(timeout :: integer) :: on_ping

Pings the RtpEngine service.

query(call_id, opts \\ [], timeout \\ 10000) 
query(call_id, query_opts, timeout) :: on_query

Queries a specific active call.

call_id is the SIP Call-ID header value as string.

Among the optional parameters, you may specify the from_tag as being the SIP From header tag parameter as string, and the to_tag as the SIP To header tag parameter as string.

start_link(rtpengine_address) 
start_link(String.t) :: GenServer.on_start

Starts the RtpEngine client.

The rtpengine_address parameter is an URI in the form of "udp://hostname:port", where the hostname and port are those of the RtpEngine instance to access. If port is omitted, the UDP port 2223 is assumed.