Connection Usage Manual
=======================

This manual documents the underlying connation infrastructure. If you just wanna
use the API, please see :doc:`/manual/client` . Ideally you don't use to use this
class directly, except for expanding the clients functionality.

Using connections
-----------------

The :class:`mitel_ommclient2.connection.Connection` requires just host and port
to establish a transport to the API.

.. code-block:: python

    import mitel_ommclient2

    conn = mitel_ommclient2.connection.Connection("omm.local")

To actually connect to the OMM, you need to call :func:`mitel_ommclient2.connection.Connection.connect`.

.. code-block:: python

    conn.connect()

This establishes a connections and spawns a thread that reads new messages from
the connection.

Please use :func:`mitel_ommclient2.connection.Connection.close` when finishing
with talking to the API.

.. code-block:: python

    conn.close()

This stops the thread and closes the connection.

Making requests
---------------

:func:`mitel_ommclient2.connection.Connection.request` provides a synchronous way
to work with the asynchronous API of the OMM.

You hand over a Request object and receive a response object.

.. code-block:: python

    >>> m = mitel_ommclient2.messages.Ping()
    >>> r = conn.request(m)
    >>> r.name
    'PingResp'

Request will generate an internal sequence number and attach this to you request
object. After sending you request to the OMM it will wait for a response with the
corresponding sequence number. Please note: Even though you can set your own sequence
number in the request object, it will be overridden by :func:`mitel_ommclient2.connection.Connection.request`.
The response object will contain the sequence number generated by :func:`mitel_ommclient2.connection.Connection.request`
and not the one set by your own.

See :doc:`/manual/messages` on how to work with message objects.

Authenticate
------------

Before you can send general requests, you need to authenticate youself agains the
OMM. The only allowed message on a new connection is :func:`mitel_ommclient2.messages.Open`.

.. code-block:: python

    >>> r = conn.request(mitel_ommclient2.messages.Open("username", "password"))
    >>> r.raise_on_error()

If this throws no exception, login is was successful and you can send other requests.
If your authentication request failed, you can just send a new Open message to try again.