Introduction
============

.. contents::

Terminology
-----------

MQTT is a server-client protocol in which all clients *must* connect to a server
in order to exchange information which have to go through the server.

Network connection
~~~~~~~~~~~~~~~~~~

The standard defines network connection as the following.

::

	A construct provided by the underlying transport protocol that is being
	used by MQTT.
	* It connects the Client to the Server.
	* It provides the means to send an ordered, lossless, stream of bytes in
	  both directions.

I believe that this definition was mainly provided as to not limit the network
connection, specifically the network protocol, to TCP as it is possibly the most
common network protocol used when implementing MQTT. You can emulate the bullet
points under non-TCP network protocols e.g., UDP and implement MQTT on top of
it.

Session
~~~~~~~

::

	A stateful interaction between a Client and a Server. Some Sessions last
	only as long as the Network Connection, others can span multiple
	consecutive Network Connections between a Client and a Server.

This allows for the possibility of attempting re-connection after it has been
lost to preserve the same session.

Application message
~~~~~~~~~~~~~~~~~~~

The information sent between clients through servers is called the application
message which is carried by the MQTT protocol across the network. It contains
payload data, a Quality of Service (QoS), a collection of properties and a topic
name.

Subscription
^^^^^^^^^^^^

A subscription comprises a topic filter and a maximum QoS. A subscription is
associated with a single session. A session can contain more than one
subscription. Each subscription within a session has a different topic filter.

Shared subscription can be associated with more than one session. I assume this
is used for the case of multiple servers? I don't see the need to have multiple
sessions to the same server but it is allowed by the standard.

Wildcard subscription is a subscription with a topic filter containing one or
more wildcard characters. This allows the subscription to match more than one
topic name. Basically ``*`` in regular expression.

write UML diagram about  user <-- session 0..* -- 1..1 subscription

Topic name
^^^^^^^^^^

The label attached to an application message which is matched against the
subscriptions known to the server. This is up to the application to use it
efficiently. In the case of media synchronization, would you rather use do
central topics e.g., ``/media/filename`` and users push to that topic or would
you do per-user topics ``/renken/media/filename`` and only ``renken`` can
publish to that topic. Similar ideas to that come to mind I guess.

Topic filter
^^^^^^^^^^^^

An expression contained in a subscription to indicate an interest in one or more
topics. A topic filter can include wildcard characters.

Client
~~~~~~

As discussed before, in MQTT, the client can only communicate with a server and
not with other clients. Note that the client is not limited to a single server.
It also not limited to a fixed number of application messages published or
requested.

The server acts as an intermediary between clients which publish application
messages and clients which have made subscriptions.

.. uml:: client.uml