####################
Typhoon HIL RPC API
####################

RPC (*Remote Procedure Call*) is an interprocess communication technique that
allows two independent processes to communicate. RPC is most commonly used to
create distributed client/server programs where:

* **client** is a process (program or task) that requests the service provided by another program, and
* **server** is a process (program or task) that provides the service (responds to the requests from a client).

Typhoon HIL's RPC API allows you to write custom APIs in any language you want
as long as it is supported by ZMQ [#]_ library.


Message format
--------------

Messages exchanged between the client and the server side are compatible
with the JSON-RPC protocol [#]_.

**Request** message contains following members:

* **api** - a string specifying the version of the Typhoon HIL RPC API.
* **jsonrpc** - a string specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
* **method** - a string containing the name of the method to be invoked.
* **params** - a list or dictionary of parameter values to be used during the invocation of the method. This member is optional.
* **id** - an identifier established by the client. It can be either a string or an integer.

**Response** message contains following members:

* **jsonrpc** - a string specifying the version of the JSON-RPC protocol. MUST be exactly "2.0".
* **result** - this member exists only if method is invoked and finished successfully.
* **error** - this member exists only if error occurred during the method invocation or execution.
* **warnings** - this member exists only if warnings occurred during the method execution.
* **id** - an identifier that must be the same as the value of the id member in the request.

For more detailed information about message formats, check JSON-RPC specification [#]_.

Examples
--------
Following examples illustrate how you can use Typhoon HIL RPC API.

Example 1
=========
This example shows how *load* method can be invoked.


.. literalinclude:: rst_api_examples/load.py
   :language: python

Example 2
=========
This example shows how *compile* method can be invoked.


.. literalinclude:: rst_api_examples/compile.py
   :language: python

Example 3
=========
This example shows how to send multiple requests at once.


.. literalinclude:: rst_api_examples/multiple.py
   :language: python


.. [#] ZMQ: http://zeromq.org/
.. [#] JSON RPC: http://www.jsonrpc.org/
.. [#] JSON RPC: http://www.jsonrpc.org/specification



