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

Module for working with SIP From headers as defined in RFC 3261 Section 20.20.

The From header identifies the logical initiator of the request. It contains a URI (typically a SIP URI) that identifies the originator of the request, an optional display name, and parameters including a mandatory 'tag' parameter that serves as a dialog identifier.

The From header plays a critical role in:

  • Identifying the sender of the message
  • Dialog identification and matching (through the tag parameter)
  • Establishing associations between requests and responses

The tag parameter is required for all requests and responses, and once assigned, it must remain constant throughout the dialog's lifetime as specified in RFC 3261 Section 19.3.

References:

  • RFC 3261 Section 8.1.1.3: From
  • RFC 3261 Section 19.3: Dialog ID Components
  • RFC 3261 Section 20.20: From Header Field

Summary

Types

t()

Functions

format(from)

Converts a From header to a string representation.

generate_tag()

Generates a unique tag parameter for a From header.

get_parameter(from, name)

Gets a parameter from a From header.

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

Creates a new From header.

new_with_tag(uri, display_name \\ nil, parameters_or_tag \\ nil)

Creates a new From header with a randomly generated tag parameter.

parse(string)

Parses a From header string into a From struct.

tag(from)

Gets the tag parameter from a From header.

with_parameter(from, name, value)

Adds or updates a parameter in a From header.

with_tag(from, tag \\ nil)

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

Types

t()

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

Functions

format(from)

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

Converts a From header to a string representation.

generate_tag()

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

Generates a unique tag parameter for a From header.

get_parameter(from, name)

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

Gets a parameter from a From header.

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

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

Creates a new From header.

new_with_tag(uri, display_name \\ nil, parameters_or_tag \\ nil)

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

Creates a new From header with a randomly generated tag parameter.

parse(string)

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

Parses a From header string into a From struct.

Examples

iex> Parrot.Sip.Headers.From.parse("Alice <sip:alice@atlanta.com>;tag=1928301774")
%Parrot.Sip.Headers.From{display_name: "Alice", uri: "sip:alice@atlanta.com", parameters: %{"tag" => "1928301774"}}

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

tag(from)

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

Gets the tag parameter from a From header.

with_parameter(from, name, value)

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

Adds or updates a parameter in a From header.

with_tag(from, tag \\ nil)

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

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