tortoise v0.10.0 Tortoise.Connection 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

Link to this function child_spec(init_arg) View Source
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.

Link to this function disconnect(client_id) View Source
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.

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
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
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()}
       | {: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
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
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
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
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
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.