diff --git a/docs/index.rst b/docs/index.rst index 9dfb1b2..062bffc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,9 +8,11 @@ Welcome to Mitel OMMClient2's documentation! .. toctree:: :maxdepth: 2 - :caption: Contents: -:ref:`api` + manual/client + manual/connection + manual/messages + api/modules Indices and tables ================== diff --git a/docs/manual/client.rst b/docs/manual/client.rst new file mode 100644 index 0000000..23eaada --- /dev/null +++ b/docs/manual/client.rst @@ -0,0 +1,42 @@ +Client Usage Manual +=================== + +This should give you an introduction on how to use :class:`mitel_ommclient2.client.OMMClient2`. + +If you are not interested in using the abstraction layer, even though it is recommended, +have a look at :doc:`/manual/connection` . + +Creating a client +----------------- + +To start with this client, you need login credentials for your OMM. The permissions +you have using this client are the ones assinged to the user you login with. + +You are required to specify at least the host to connect to, a username and a corresponding +password. For further options see :class:`mitel_ommclient2.client.OMMClient2`. + +.. code-block:: python + + import mitel_ommclient2 + + c = mitel_ommclient2.OMMClient2("omm.local", "admin", "password") + +Creating this object will directly connect to the API of the corresponding host. +Failure in connection or authenticating will raise an excaption. + +Using the API +------------- + +:class:`mitel_ommclient2.client.OMMClient2` ships with several mathods that wraps and +validate common API requests. See class documentation to get and overview and options. + +.. code-block:: python + + c.ping() + +Making custom requests +---------------------- + +:func:`mitel_ommclient2.client.OMMClient2.request` allowes you to send custom requests. +It just passes arguments and results to :func:`mitel_ommclient2.connection.Connection.request`. +See :doc:`/manual/connection` about using this. diff --git a/docs/manual/connection.rst b/docs/manual/connection.rst new file mode 100644 index 0000000..c317310 --- /dev/null +++ b/docs/manual/connection.rst @@ -0,0 +1,73 @@ +Connection Usage Manual +======================= + +This manual documents the underlying connation infrastructure. If you just wanna +use the API, please see :doc:`/manual/client` . + +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 + + >>> request = mitel_ommclient2.messages.Ping() + >>> r = conn.request(request) + >>> 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. diff --git a/docs/manual/messages.rst b/docs/manual/messages.rst new file mode 100644 index 0000000..540ce84 --- /dev/null +++ b/docs/manual/messages.rst @@ -0,0 +1,53 @@ +Message Usage Manual +==================== + +The API consists of three main message types: request, response and event. They +are represented by :class:`mitel_ommclient2.messages.Request`, :class:`mitel_ommclient2.messages.Response` +and events aren't supported yet. + +There are several subclasses for each messages type, but they are just just overlays +to provide a conveinient interface to message content using attributes. + +Each message provides three attributes that define the central interfaces: + + * name + * attrs + * childs + +Using messages +-------------- + +Just choose one of several message classes of :module:`mitel_ommclient2.messages` +and hand it over to :func:`mitel_ommclient2.client.OMMClient2.request` or +:func:`mitel_ommclient2.connection.Connection.request`. + +.. code-block:: python + + import time + + my_time = int(time.time()) + + request = mitel_ommclient2.messages.Ping(timeStamp=my_time) + r = c.request(request) + + ping = r.timeStamp - my_time + +Crafting your own messages +-------------------------- + +It some cases your message class isn't implemented yet. Then you can craft the +message yourself. + +.. code-block:: python + + import time + + my_time = int(time.time()) + + request = mitel_ommclient2.messages.Request("Ping") + request.attrs = { + "timeStamp": my_time, + } + r = c.request(request) + + ping = r.attrs["timeStamp"] - my_time