sippet v0.1.8 Sippet.Message

Message primitive for composing SIP messages. Build a SIP message with the Sippet.Message struct.

request =
  Sippet.Message.build_request("INVITE", "sip:joe@example.com")
  |> Sippet.Message.put_header(:to,
      {"", Sippet.URI.parse("sip:joe@example.com"), %{}})
  ...

Summary

Types

header()

method()

multiple_value()

protocol()

request()

response()

single_value()

t()

token_params()

type_subtype_params()

uri()

uri_params()

value()

via_value()

Functions

build_request(method, request_uri)

Build a SIP request

build_response(status_line)

Build a SIP response

build_response(status_code, reason_phrase)

build_response(request, status_code, reason_phrase)

create_branch()

Creates an unique local branch (72-bit random string, 7+12 characters long)

create_call_id()

Creates an unique Call-ID (120-bit random string, 20 characters long)

create_tag()

Creates a local tag (48-bit random string, 8 characters long)

delete_header(message, header)

Deletes all header values in message

delete_header_back(message, header)

Deletes the last value of header in message

delete_header_front(message, header)

Deletes the first value of header in message

drop_headers(message, headers)

Drops all given headers from message

fetch_header(message, header)

Fetches all values for a specific header and returns it in a tuple

fetch_header!(message, header)

Fetches all values for a specific header in the given message, erroring out if message doesn’t contain header

fetch_header_back(message, header)

Fetches the last value of a specific header and returns it in a tuple

fetch_header_back!(message, header)

Fetches the last value of a specific header in the given message, erroring out if message doesn’t contain header

fetch_header_front(message, header)

Fetches the first value of a specific header and returns it in a tuple

fetch_header_front!(message, header)

Fetches the first value of a specific header in the given message, erroring out if message doesn’t contain header

get_and_update_header(message, header, fun)

Gets the values from header and updates it, all in one pass

get_and_update_header_back(message, header, fun)

Gets the last value from header and updates it, all in one pass

get_and_update_header_front(message, header, fun)

Gets the first value from header and updates it, all in one pass

get_header(message, header, default \\ nil)

Gets all values for a specific header in message

get_header_back(message, header, default \\ nil)

Gets the last value of a specific header in message

get_header_front(message, header, default \\ nil)

Gets the first value of a specific header in message

has_header?(message, header)

Returns whether a given header exists in the given message

parse(data)

Parses a SIP message header block as received by the transport layer

parse!(data)

Parses a SIP message header block as received by the transport layer

pop_header(message, header, default \\ nil)

Returns and removes the values associated with header in message

pop_header_back(message, header, default \\ nil)

Returns and removes the last value associated with header in message

pop_header_front(message, header, default \\ nil)

Returns and removes the first value associated with header in message

put_header(message, header, value)

Puts the value under header on the message

put_header_back(message, header, value)

Puts the value under header on the message, as last element

put_header_front(message, header, value)

Puts the value under header on the message, as front element

put_new_header(message, header, value)

Puts the value under header on the message unless the header already exists

put_new_lazy_header(message, header, fun)

Evaluates fun and puts the result under header in message unless header is already present

request?()

Shortcut to check if the message is a request

response?()

Shortcut to check if the message is a response

to_iodata(message)

Returns the iodata representation of the given Sippet.Message struct

to_string(value)

Returns the string representation of the given Sippet.Message struct

update_header(message, header, initial \\ nil, fun)

Updates the header in message with the given function

update_header_back(message, header, initial \\ nil, fun)

Updates the last header value in message with the given function

update_header_front(message, header, initial \\ nil, fun)

Updates the first header value in message with the given function

validate(message)

Checks whether a message is valid

validate(message, from)

Checks whether a message is valid, also checking if it corresponds to the indicated incoming transport tuple {protocol, host, port}

Types

header()

header ::
  :accept |
  :accept_encoding |
  :accept_language |
  :alert_info |
  :allow |
  :authentication_info |
  :authorization |
  :call_id |
  :call_info |
  :contact |
  :content_disposition |
  :content_encoding |
  :content_language |
  :content_length |
  :content_type |
  :cseq |
  :date |
  :error_info |
  :expires |
  :from |
  :in_reply_to |
  :max_forwards |
  :mime_version |
  :min_expires |
  :organization |
  :priority |
  :proxy_authenticate |
  :proxy_authorization |
  :proxy_require |
  :reason |
  :record_route |
  :reply_to |
  :require |
  :retry_after |
  :route |
  :server |
  :subject |
  :supported |
  :timestamp |
  :to |
  :unsupported |
  :user_agent |
  :via |
  :warning |
  :www_authenticate |
  binary

method()

method ::
  :ack |
  :bye |
  :cancel |
  :info |
  :invite |
  :message |
  :notify |
  :options |
  :prack |
  :publish |
  :pull |
  :push |
  :refer |
  :register |
  :store |
  :subscribe |
  :update |
  binary

multiple_value()

multiple_value() :: token_params | type_subtype_params | uri_params | via_value | auth_params :: %{} | {scheme :: binary, params :: %{}} | {code :: integer, agent :: binary, text :: binary}

protocol()

protocol ::
  :dccp |
  :dtls |
  :sctp |
  :stomp |
  :tcp |
  :tls |
  :udp |
  :ws |
  :wss |
  binary

request()

request() :: %Sippet.Message{body: term, headers: term, start_line: Sippet.Message.RequestLine.t, target: term}

response()

response() :: %Sippet.Message{body: term, headers: term, start_line: Sippet.Message.StatusLine.t, target: term}

single_value()

single_value ::
  binary |
  integer |
  {sequence :: integer, method} |
  {major :: integer, minor :: integer} |
  token_params |
  type_subtype_params |
  uri_params |
  {delta_seconds :: integer, comment :: binary, params :: %{}} |
  {timestamp :: integer, delay :: integer} |
  NativeDateTime.t

t()

t() :: %Sippet.Message{body: String.t | nil, headers: %{optional(header) => value}, start_line: Sippet.Message.RequestLine.t | Sippet.Message.StatusLine.t, target: nil | {protocol :: atom | binary, host :: binary, dport :: integer}}

token_params()

token_params() :: {token :: binary, params :: %{}}

type_subtype_params()

type_subtype_params() :: {{type :: binary, subtype :: binary}, params :: %{}}

uri()

uri() :: Sippet.URI.t

uri_params()

uri_params() :: {display_name :: binary, uri :: Sippet.URI.t, params :: %{}}

value()

value() :: single_value | [multiple_value]

via_value()

via_value() :: {{major :: integer, minor :: integer}, protocol, {host :: binary, port :: integer}, params :: %{}}

Functions

build_request(method, request_uri)

build_request(method, uri | binary) :: request

Build a SIP request.

build_response(status_line)

build_response(integer | Sippet.Message.StatusLine.t) :: response

Build a SIP response.

build_response(status_code, reason_phrase)

build_response(integer | request, integer | String.t | Sippet.Message.StatusLine.t) :: response

build_response(request, status_code, reason_phrase)

build_response(request, integer, String.t) :: response

create_branch()

create_branch() :: binary

Creates an unique local branch (72-bit random string, 7+12 characters long).

create_call_id()

create_call_id() :: binary

Creates an unique Call-ID (120-bit random string, 20 characters long).

create_tag()

create_tag() :: binary

Creates a local tag (48-bit random string, 8 characters long).

delete_header(message, header)

delete_header(t, header) :: t

Deletes all header values in message.

delete_header_back(message, header)

delete_header_back(t, header) :: t

Deletes the last value of header in message.

delete_header_front(message, header)

delete_header_front(t, header) :: t

Deletes the first value of header in message.

drop_headers(message, headers)

drop_headers(t, [header]) :: t

Drops all given headers from message.

fetch_header(message, header)

fetch_header(t, header) :: {:ok, value} | :error

Fetches all values for a specific header and returns it in a tuple.

If the header does not exist, returns :error.

fetch_header!(message, header)

fetch_header!(t, header) :: value | no_return

Fetches all values for a specific header in the given message, erroring out if message doesn’t contain header.

If message contains the given header, all corresponding values are returned in a list. If message doesn’t contain the header, a KeyError exception is raised.

fetch_header_back(message, header)

fetch_header_back(t, header) :: {:ok, value} | :error

Fetches the last value of a specific header and returns it in a tuple.

If the header does not exist, returns :error. If the header exists but it is an empty list, returns {:ok, nil}.

fetch_header_back!(message, header)

fetch_header_back!(t, header) :: value | no_return

Fetches the last value of a specific header in the given message, erroring out if message doesn’t contain header.

If message contains the given header, the last value is returned, which may be nil case the values list is empty. If message doesn’t contain the header, a KeyError exception is raised.

fetch_header_front(message, header)

fetch_header_front(t, header) :: {:ok, value} | :error

Fetches the first value of a specific header and returns it in a tuple.

If the header does not exist, returns :error. If the header exists but it is an empty list, returns {:ok, nil}.

fetch_header_front!(message, header)

fetch_header_front!(t, header) :: value | no_return

Fetches the first value of a specific header in the given message, erroring out if message doesn’t contain header.

If message contains the given header, the first value is returned, which may be nil case the values list is empty. If message doesn’t contain the header, a KeyError exception is raised.

get_and_update_header(message, header, fun)

get_and_update_header(t, header, (value -> {get, value} | :pop)) :: {get, t} when get: value

Gets the values from header and updates it, all in one pass.

fun is called with the current values under header in message (or nil if key is not present in message) and must return a two-element tuple: the “get” value (the retrieved values, which can be operated on before being returned) and the new values to be stored under header in the resulting new message. fun may also return :pop, which means all current values shall be removed from message and returned (making this function behave like Sippet.Message.pop_header(message, header). The returned value is a tuple with the “get” value returned by fun and a new message with the updated values under header.

get_and_update_header_back(message, header, fun)

get_and_update_header_back(t, header, (value -> {get, value} | :pop)) :: {get, t} when get: value

Gets the last value from header and updates it, all in one pass.

fun is called with the current last value under header in message (or nil if key is not present in message) and must return a two-element tuple: the “get” value (the retrieved value, which can be operated on before being returned) and the new value to be stored under header in the resulting new message. fun may also return :pop, which means the current value shall be removed from message and returned (making this function behave like Sippet.Message.pop_header_back(message, header). The returned value is a tuple with the “get” value returned by fun and a new message with the updated values under header.

get_and_update_header_front(message, header, fun)

get_and_update_header_front(t, header, (value -> {get, value} | :pop)) :: {get, t} when get: value

Gets the first value from header and updates it, all in one pass.

fun is called with the current first value under header in message (or nil if key is not present in message) and must return a two-element tuple: the “get” value (the retrieved value, which can be operated on before being returned) and the new value to be stored under header in the resulting new message. fun may also return :pop, which means the current value shall be removed from message and returned (making this function behave like Sippet.Message.pop_header_front(message, header). The returned value is a tuple with the “get” value returned by fun and a new message with the updated values under header.

get_header(message, header, default \\ nil)

get_header(t, header, any) :: value | any

Gets all values for a specific header in message.

If header is present in message, then all values are returned in a list. Otherwise, default is returned (which is nil unless specified otherwise).

get_header_back(message, header, default \\ nil)

get_header_back(t, header, any) :: value | any

Gets the last value of a specific header in message.

If header is present in message, then the last value is returned. Otherwise, default is returned (which is nil unless specified otherwise).

get_header_front(message, header, default \\ nil)

get_header_front(t, header, any) :: value | any

Gets the first value of a specific header in message.

If header is present in message, then the first value is returned. Otherwise, default is returned (which is nil unless specified otherwise).

has_header?(message, header)

has_header?(t, header) :: boolean

Returns whether a given header exists in the given message.

parse(data)

parse(iodata) :: {:ok, t} | {:error, atom}

Parses a SIP message header block as received by the transport layer.

In order to correctly set the message body, you have to verify the :content_length header; if it exists, it reflects the body size and you have to set it manually on the returned message.

parse!(data)

parse!(String.t | charlist) :: t | no_return

Parses a SIP message header block as received by the transport layer.

Raises if the string is an invalid SIP header.

In order to correctly set the message body, you have to verify the :content_length header; if it exists, it reflects the body size and you have to set it manually on the returned message.

pop_header(message, header, default \\ nil)

pop_header(t, header, any) :: {value | any, t}

Returns and removes the values associated with header in message.

If header is present in message with values [value], {[value], new_message} is returned where new_message is the result of removing header from message. If header is not present in message, {default, message} is returned.

pop_header_back(message, header, default \\ nil)

pop_header_back(t, header, any) :: {value | any, t}

Returns and removes the last value associated with header in message.

If header is present in message with values values, {List.last(values), new_message} is returned where new_message is the result of removing List.last(values) from header. If header is not present in message or it is an empty list, {default, message} is returned. When the header results in an empty list, message gets updated by removing the header.

pop_header_front(message, header, default \\ nil)

pop_header_front(t, header, any) :: {value | any, t}

Returns and removes the first value associated with header in message.

If header is present in message with values values, {List.first(values), new_message} is returned where new_message is the result of removing List.first(values) from header. If header is not present in message or it is an empty list, {default, message} is returned. When the header results in an empty list, message gets updated by removing the header.

put_header(message, header, value)

put_header(t, header, value) :: t

Puts the value under header on the message.

put_header_back(message, header, value)

put_header_back(t, header, value) :: t

Puts the value under header on the message, as last element.

If the parameter value is nil, then the empty list will be appended to the header.

put_header_front(message, header, value)

put_header_front(t, header, value) :: t

Puts the value under header on the message, as front element.

If the parameter value is nil, then the empty list will be prefixed to the header.

put_new_header(message, header, value)

put_new_header(t, header, value) :: t

Puts the value under header on the message unless the header already exists.

put_new_lazy_header(message, header, fun)

put_new_lazy_header(t, header, (() -> value)) :: t

Evaluates fun and puts the result under header in message unless header is already present.

This function is useful in case you want to compute the value to put under header only if header is not already present (e.g., the value is expensive to calculate or generally difficult to setup and teardown again).

request?()

request?(t) :: boolean

Shortcut to check if the message is a request.

response?()

response?(t) :: boolean

Shortcut to check if the message is a response.

to_iodata(message)

to_iodata(t) :: iodata

Returns the iodata representation of the given Sippet.Message struct.

to_string(value)

to_string(t) :: binary

Returns the string representation of the given Sippet.Message struct.

update_header(message, header, initial \\ nil, fun)

update_header(t, header, value, (value -> value)) :: t

Updates the header in message with the given function.

If header is present in message with value value, fun is invoked with argument value and its result is used as the new value of header. If header is not present in message, initial is inserted as the value of header.

update_header_back(message, header, initial \\ nil, fun)

update_header_back(t, header, value, (value -> value)) :: t

Updates the last header value in message with the given function.

If header is present in message with value [value], fun is invoked with for last element of [value] and its result is used as the new value of header back. If header is not present in message, or it is an empty list, initial is inserted as the single value of header.

update_header_front(message, header, initial \\ nil, fun)

update_header_front(t, header, value, (value -> value)) :: t

Updates the first header value in message with the given function.

If header is present in message with value [value], fun is invoked with for first element of [value] and its result is used as the new value of header front. If header is not present in message, or it is an empty list, initial is inserted as the single value of header.

validate(message)

validate(t) :: :ok | {:error, reason :: term}

Checks whether a message is valid.

validate(message, from)

validate(t, {protocol, host :: String.t, port :: integer}) ::
  :ok |
  {:error, reason :: term}

Checks whether a message is valid, also checking if it corresponds to the indicated incoming transport tuple {protocol, host, port}.