Parrot.Sip.Headers.To (Parrot Platform v0.0.1-alpha.2)

Module for working with SIP To headers as defined in RFC 3261 Section 20.39.

The To header identifies the logical recipient of the request. Like the From header, it contains a URI that identifies the target of the request, an optional display name, and parameters. The tag parameter, which may be added by the UAS in responses, is a critical component for dialog identification.

The To header serves several key functions:

  • Specifying the recipient of the request
  • Contributing to dialog identification (when tag is present)
  • Allowing recipient identification independent of the Request-URI

Initially, requests contain a To header without a tag. The UAS adds a tag parameter in responses, which then becomes part of the dialog identification as described in RFC 3261 Section 12.1.

References:

  • RFC 3261 Section 8.1.1.2: To
  • RFC 3261 Section 12.1: Creation of a Dialog
  • RFC 3261 Section 19.3: Dialog ID Components
  • RFC 3261 Section 20.39: To Header Field

Summary

Types

t()

Functions

format(to)

Converts a To header to a string representation.

get_parameter(to, name)

Gets a parameter from a To header.

new(uri, display_name \\ nil, parameters \\ %{})

Creates a new To header.

new_with_tag(uri, display_name \\ nil, tag)

Creates a new To header with a tag parameter.

parse(string)

Parses a To header string into a To struct.

tag(to)

Gets the tag parameter from a To header.

with_parameter(to, name, value)

Adds or updates a parameter in a To header.

with_tag(to, tag)

Adds a tag parameter to a To header if one doesn't exist.

Types

t()

@type t() :: %Parrot.Sip.Headers.To{
  display_name: String.t() | nil,
  parameters: map(),
  uri: String.t() | Parrot.Sip.Uri.t()
}

Functions

format(to)

@spec format(t()) :: String.t()

Converts a To header to a string representation.

get_parameter(to, name)

@spec get_parameter(t(), String.t()) :: String.t() | nil

Gets a parameter from a To header.

new(uri, display_name \\ nil, parameters \\ %{})

@spec new(String.t(), String.t() | nil, map()) :: t()

Creates a new To header.

new_with_tag(uri, display_name \\ nil, tag)

@spec new_with_tag(String.t(), String.t() | nil, String.t()) :: t()

Creates a new To header with a tag parameter.

parse(string)

@spec parse(String.t()) :: t()

Parses a To header string into a To struct.

Examples

iex> Parrot.Sip.Headers.To.parse("Bob <sip:bob@biloxi.com>;tag=a6c85cf")
%Parrot.Sip.Headers.To{display_name: "Bob", uri: %Parrot.Sip.Uri{scheme: "sip", user: "bob", host: "biloxi.com"}, parameters: %{"tag" => "a6c85cf"}}

iex> Parrot.Sip.Headers.To.parse("<sip:bob@biloxi.com>")
%Parrot.Sip.Headers.To{display_name: nil, uri: %Parrot.Sip.Uri{scheme: "sip", user: "bob", host: "biloxi.com"}, parameters: %{}}

tag(to)

@spec tag(t()) :: String.t() | nil

Gets the tag parameter from a To header.

with_parameter(to, name, value)

@spec with_parameter(t(), String.t(), String.t()) :: t()

Adds or updates a parameter in a To header.

with_tag(to, tag)

@spec with_tag(t(), String.t()) :: t()

Adds a tag parameter to a To header if one doesn't exist.