Call history: the History-Info (RFC 7044) and Diversion (RFC 5806)
headers, that tell the final destination of a request (a voicemail, a
forwarded phone...) the targets it went through, and why it was
retargeted.
Proxies retarget requests with retarget/3, a sip_route/5 result:
defcb sip_route(_scheme, "alice", "example.com", req, _call) do
if MyApp.forwarding?("alice"),
do: Caracola.History.retarget(req, ["sip:voicemail@example.com"], cause: 302),
else: :proxy
endEach destination gets a new History-Info entry, child of the one of the
current Request-URI (which is added first if the request has none), and
the cause (RFC 4458) is added to its URI. With :diversion, a
Diversion header is added too, for the equipment that only understands
it.
entries/1 and diversions/1 read the headers of a received request.
Summary
Types
A Diversion: the diverted URI, the reason and the counter.
A History-Info entry: the URI (with its cause param and the Reason
header, if any), its index (as "1.1.2"), and how it was retargeted
from its parent: :rc (to a registered contact), :mp (mapped to
another user) or :np (not changed), with the index of the parent.
Functions
The Diversion headers of a message, the most recent first.
The History-Info entries of a message, in order.
A sip_route/5 result proxying req to targets (URIs, tried in
parallel), with a History-Info entry for each of them.
Types
@type diversion() :: %{ uri: Caracola.URI.t(), reason: String.t() | nil, counter: pos_integer() }
A Diversion: the diverted URI, the reason and the counter.
@type entry() :: %{ uri: Caracola.URI.t(), index: String.t() | nil, type: {:rc | :mp | :np, String.t()} | nil, cause: non_neg_integer() | nil, reason: String.t() | nil }
A History-Info entry: the URI (with its cause param and the Reason
header, if any), its index (as "1.1.2"), and how it was retargeted
from its parent: :rc (to a registered contact), :mp (mapped to
another user) or :np (not changed), with the index of the parent.
Functions
@spec diversions(Caracola.Message.t()) :: [diversion()]
The Diversion headers of a message, the most recent first.
@spec entries(Caracola.Message.t()) :: [entry()]
The History-Info entries of a message, in order.
@spec retarget(Caracola.Message.t(), [String.t() | Caracola.URI.t()], list()) :: {:proxy, [Caracola.URI.t()], list()}
A sip_route/5 result proxying req to targets (URIs, tried in
parallel), with a History-Info entry for each of them.
Options:
{:cause, code}- the reason of the retargeting (RFC 4458): 302 (unconditional forwarding), 486 (busy), 408 (no answer), 404 (unknown or not available), 480 or 487 (deflection) and 503 (not reachable). It is added ascauseparam to the targets.{:type, :mp | :rc}-:mp(the default) when the target is another user,:rcfor the registered contacts of the same one.:diversionor{:diversion, reason}- add a Diversion header with the current Request-URI, and the reason (by default, the one of the cause).{:proxy_opts, opts}- options of the proxy.
iex> {:ok, req, ""} = Caracola.Parser.parse("INVITE sip:alice@example.com SIP/2.0\r\nVia: SIP/2.0/UDP h;branch=z9hG4bKa\r\nFrom: <sip:a@h>;tag=1\r\nTo: <sip:alice@example.com>\r\nCall-ID: c\r\nCSeq: 1 INVITE\r\n\r\n")
iex> {:proxy, [target], []} = Caracola.History.retarget(req, ["sip:vm@example.com"], cause: 302)
iex> for {"History-Info", value} <- target.headers, do: URI.decode_www_form(value)
["<sip:alice@example.com>;index=1", "<sip:vm@example.com;cause=302>;index=1.1;mp=1"]