.. _app-tok:

Application Tokens
******************

The :class:`.AppToken` represents the higher-level Application that the *Conductor
Device* is being integrated into.

.. note::
    In order to receive permission to access a *Conductor Device*, the
    :ref:`c-devices` themselfs must be registered to an :class:`.AppToken` that
    your :class:`.ConductorAccount` owns.

To create an Application Token for your device, all you have to do is ::

    my_app_token = account.create_app_token("My Cool Application")

Now, that Application Token has been created by your account and can be shared
to a :ref:`module` or :ref:`ltem` to pass data into the cloud. Additionally,
since the Application Token inherits from the :class:`.UplinkSubject` and
:class:`.DownlinkSubject`, it can handle both *Uplink* (messages **from**
:ref:`c-devices`), and *Downlink* (messages **to** :ref:`c-devices`).

When receiving *Uplink Messages* from an :class:`.AppToken`, you will see
messages from every single device registered to that Application Token. The
quickest way to pull messaages is with the :meth:`AppToken.get_recent_messages`
method, which receives the last messages within the supplied amount of minutes.
This example will get messages from the last hour ::

    msgs = my_app_token.get_recent_messages(60)

When a :class:`.DownlinkMessaage` is sent to your all of an Application's
devices, it is refered to as a **Multicast** Downlink. See :ref:`dl_modes` for
more information.

.. warning::
  A **Multicast** :class:`.DowlinkMessage` cannot be Acknowledgedged through Conductor,
  so an additional mechanism must be implemented to confirm whether
  a particular device received the message or not.

A *Multicast* :class:`.DownlinkMessage` can be sent with the :meth:`AppToken.send_message`
method and can be received by any device in the correct :ref:`dl_modes` at the
time of being sent, see :ref:`dl_modes` for more ::

  dl_msg = my_app_token.send_message(b'Hello Devices!')

To limit the devices receiving the message, the `gateway` parameter can be
supplied. This routes the *Multicast* :class:`.DownlinkMessage` through that
specified :ref:`gateway` explicitly, and will not be receivable to any other
device on that Application Token, that is not connected through that Gateway ::

  my_gw = account.get_gateway("$101$0-0-0-dbXXXXXXX")
  dl_msg = my_app_token.send_message(b'Hello Some Devices!', gateway=my_gw)