mitel_ommclient2/docs/manual/connection.rst

75 lines
2.4 KiB
ReStructuredText
Raw Normal View History

2022-01-17 13:52:56 +01:00
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.
2022-01-17 13:52:56 +01:00
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")
2022-01-17 13:52:56 +01:00
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)
2022-01-17 13:52:56 +01:00
>>> 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.