Tortoise.Connection (tortoise311 v0.10.4) View Source

Establish a connection to a MQTT broker.

Todo.

Link to this section Summary

Functions

Returns a specification to start this module under a supervisor.

Close the connection to the broker.

Ping the broker.

Ping the server and await the ping latency reply.

Start a connection process and link it to the current process.

Subscribe to one or more topics using topic filters on client_id

Subscribe to topics and block until the server acknowledges.

Return the list of subscribed topics.

Unsubscribe from one of more topic filters. The topic filters are given as strings. Multiple topic filters can be given at once by passing in a list of strings.

Unsubscribe from topics and block until the server acknowledges.

Link to this section Functions

Specs

child_spec(Keyword.t()) :: %{
  id: term(),
  start: {Tortoise.Connection, :start_link, [Keyword.t()]},
  restart: :transient | :permanent | :temporary,
  type: :worker
}

Returns a specification to start this module under a supervisor.

See Supervisor.

Specs

disconnect(Tortoise.client_id()) :: :ok

Close the connection to the broker.

Given the client_id of a running connection it will cancel the inflight messages and send the proper disconnect message to the broker. The session will get terminated on the server.

Specs

ping(Tortoise.client_id()) :: {:ok, reference()}

Ping the broker.

When the round-trip is complete a message with the time taken in milliseconds will be send to the process that invoked the ping command.

The connection will automatically ping the broker at the interval specified in the connection configuration, so there is no need to setup a reoccurring ping. This ping function is exposed for debugging purposes. If ping latency over time is desired it is better to listen on :ping_response using the Tortoise.Events PubSub.

Link to this function

ping_sync(client_id, timeout \\ :infinity)

View Source

Specs

ping_sync(Tortoise.client_id(), timeout()) ::
  {:ok, reference()} | {:error, :timeout}

Ping the server and await the ping latency reply.

Takes a client_id and an optional timeout.

Like ping/1 but will block the caller process until a response is received from the server. The response will contain the ping latency in milliseconds. The timeout defaults to :infinity, so it is advisable to specify a reasonable time one is willing to wait for a response.

Link to this function

start_link(connection_opts, opts \\ [])

View Source

Specs

start_link(options, GenServer.options()) :: GenServer.on_start()
when option:
       {:client_id, Tortoise.client_id()}
       | {:server, {atom(), term()}}
       | {:user_name, String.t()}
       | {:password, String.t()}
       | {:keep_alive, non_neg_integer()}
       | {:will, Tortoise.Package.Publish.t()}
       | {:subscriptions,
          [{Tortoise.topic_filter(), Tortoise.qos()}]
          | Tortoise.Package.Subscribe.t()}
       | {:clean_session, boolean()}
       | {:handler, {atom(), term()}},
     options: [option]

Start a connection process and link it to the current process.

Read the documentation on child_spec/1 if you want... (todo!)

Link to this function

subscribe(client_id, topics, opts \\ [])

View Source

Specs

subscribe(Tortoise.client_id(), topic | topics, [options]) :: {:ok, reference()}
when topics: [topic],
     topic: {Tortoise.topic_filter(), Tortoise.qos()},
     options:
       {:timeout, timeout()} | {:identifier, Tortoise.package_identifier()}

Subscribe to one or more topics using topic filters on client_id

The topic filter should be a 2-tuple, {topic_filter, qos}, where the topic_filter is a valid MQTT topic filter, and qos an integer value 0 through 2.

Multiple topics can be given as a list.

The subscribe function is asynchronous, so it will return {:ok, ref}. Eventually a response will get delivered to the process mailbox, tagged with the reference stored in ref. It will take the form of:

{{Tortoise, ^client_id}, ^ref, ^result}

Where the result can be one of :ok, or {:error, reason}.

Read the documentation for Tortoise.Connection.subscribe_sync/3 for a blocking version of this call.

Link to this function

subscribe_sync(client_id, topics, opts \\ [])

View Source

Specs

subscribe_sync(Tortoise.client_id(), topic | topics, [options]) ::
  :ok | {:error, :timeout}
when topics: [topic],
     topic: {Tortoise.topic_filter(), Tortoise.qos()},
     options:
       {:timeout, timeout()} | {:identifier, Tortoise.package_identifier()}

Subscribe to topics and block until the server acknowledges.

This is a synchronous version of the Tortoise.Connection.subscribe/3. In fact it calls into Tortoise.Connection.subscribe/3 but will handle the selective receive loop, making it much easier to work with. Also, this function can be used to block a process that cannot continue before it has a subscription to the given topics.

See Tortoise.Connection.subscribe/3 for configuration options.

Link to this function

subscriptions(client_id)

View Source

Specs

subscriptions(Tortoise.client_id()) :: Tortoise.Package.Subscribe.t()

Return the list of subscribed topics.

Given the client_id of a running connection return its current subscriptions. This is helpful in a debugging situation.

Link to this function

unsubscribe(client_id, topics, opts \\ [])

View Source

Specs

unsubscribe(Tortoise.client_id(), topic | topics, [options]) ::
  {:ok, reference()}
when topics: [topic],
     topic: Tortoise.topic_filter(),
     options:
       {:timeout, timeout()} | {:identifier, Tortoise.package_identifier()}

Unsubscribe from one of more topic filters. The topic filters are given as strings. Multiple topic filters can be given at once by passing in a list of strings.

Tortoise.Connection.unsubscribe(client_id, ["foo/bar", "quux"])

This operation is asynchronous. When the operation is done a message will be received in mailbox of the originating process.

Link to this function

unsubscribe_sync(client_id, topics, opts \\ [])

View Source

Specs

unsubscribe_sync(Tortoise.client_id(), topic | topics, [options]) ::
  :ok | {:error, :timeout}
when topics: [topic],
     topic: Tortoise.topic_filter(),
     options:
       {:timeout, timeout()} | {:identifier, Tortoise.package_identifier()}

Unsubscribe from topics and block until the server acknowledges.

This is a synchronous version of Tortoise.Connection.unsubscribe/3. It will block until the server has send the acknowledge message.

See Tortoise.Connection.unsubscribe/3 for configuration options.