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.