Sippet v0.5.2 Sippet.Transactions

The Sippet.Transactions is responsible to dispatch messages from Sippet.Transports and Sippet.Core modules to transactions, creating when necessary.

Summary

Types

A client transaction identifier

An network error that occurred while sending a message

A SIP message request

A SIP message response

A server transaction identifier

Functions

Receives a transport error

Receives a message from the transport

Sends a request using client transactions

Sends a response to a server transaction

Sends a response to a server transaction

Handles the sigil ~K

See Sippet.Transactions.Supervisor.start_client/2

Starts the transaction process hierarchy

See Sippet.Transactions.Supervisor.start_server/2

Terminates a client or server transaction forcefully

Types

client_key()

A client transaction identifier

reason()
reason() :: term

An network error that occurred while sending a message

request()
request() :: Sippet.Message.request

A SIP message request

response()
response() :: Sippet.Message.response

A SIP message response

server_key()

A server transaction identifier

Functions

receive_error(key, reason)
receive_error(client_key | server_key, reason) :: :ok

Receives a transport error.

The client and server identifiers are passed to the transport by the transactions. If the transport faces an error, it has to inform the transaction using this function.

If a transaction with such a key does not exist, it will be silently ignored.

receive_message(incoming_request)
receive_message(request | response) :: :ok | {:error, reason}

Receives a message from the transport.

If the message is a request, then it will look if a server transaction already exists for it and redirect to it. Otherwise, if the request method is :ack, it will redirect the request directly to Sippet.Core; if not :ack, then a new Sippet.Transactions.Server will be created.

If the message is a response, it looks if a client transaction already exists in order to handle it, and if so, redirects to it. Otherwise the response is redirected directly to the Sippet.Core. The latter is done so because of the usual SIP behavior or handling the 200 OK response retransmissions for requests with :invite method directly.

When receiving a burst of equivalent requests, it is possible that another entity has already created the server transaction, and then the function will return a {:error, reason} tuple.

In case of success, returns :ok.

send_request(outgoing_request)
send_request(request) :: :ok | {:error, reason}

Sends a request using client transactions.

Requests of method :ack shall be sent directly to Sippet.Transports. If an :ack request is detected, it returns {:error, :not_allowed}.

A Sippet.Transactions.Client is created to handle retransmissions, when the transport presumes it, and match response retransmissions, so the Sippet.Core doesn’t get retransmissions other than 200 OK for :invite requests.

In case of success, returns :ok.

send_response(outgoing_response)
send_response(response) :: :ok | {:error, reason}

Sends a response to a server transaction.

The server transaction identifier is obtained from the message attributes.

See send_response/2.

send_response(outgoing_response, server_key)
send_response(response, server_key) :: :ok | {:error, reason}

Sends a response to a server transaction.

Server transactions are created when the incoming request is received, see receive_message/1. The first parameter server_key indicates the reference passed to Sippet.Core when the request is received.

If there is no such server transaction, returns {:error, :no_transaction}.

In case of success, returns :ok.

sigil_K(string, )

Handles the sigil ~K.

It returns a client or server transaction key depending on the number of parameters passed.

Examples

iex> import Sippet.Transactions, only: [sigil_K: 2]

iex> Sippet.Transactions.Client.Key.new("z9hG4bK230f2.1", :invite)
~K[z9hG4bK230f2.1|:invite]

iex> ~K[z9hG4bK230f2.1|INVITE]
~K[z9hG4bK230f2.1|:invite]

iex> Sippet.Transactions.Server.Key.new("z9hG4bK74b21", :invite, {"client.biloxi.example.com", 5060})
~K[z9hG4bK74b21|:invite|client.biloxi.example.com:5060]

iex> ~K[z9hG4bK74b21|INVITE|client.biloxi.example.com:5060]
~K[z9hG4bK74b21|:invite|client.biloxi.example.com:5060]
start_client(transaction, outgoing_request)

See Sippet.Transactions.Supervisor.start_client/2.

start_link()

Starts the transaction process hierarchy.

start_server(transaction, incoming_request)

See Sippet.Transactions.Supervisor.start_server/2.

terminate(key)
terminate(client_key | server_key) :: :ok

Terminates a client or server transaction forcefully.

This function is not generally executed by entities; there is a single case where it is fundamental, which is when a client transaction is in proceeding state for a long time, and the transaction has to be finished forcibly, or it will never finish by itself.

If a transaction with such a key does not exist, it will be silently ignored.