.. _rpc:

===============
 RPC Interface
===============

Root Interface
==============

This RPC interface is exposed under a :term:`scope` :samp:`{ROOT}`,
which is configured using the :option:`control-uri` commandline
option. The interface provides the following methods:

.. js:function:: loadStory(story)

   :param string story: Literal story definition (see :ref:`syntax`)
   :returns string: Scope of story interface

   Loads given story. Blocking until story interface set up.

.. js:function:: loadStoryFromFile(filename)

   :param string filename: Name of file containing story definition.
   :returns string: Scope of story interface

   Loads given story from given file. Blocking until story interface set up.

Story Interface
===============

An individual RPC interface is provided for each loaded story object.
Assuming the root RPC interface is exposed under :samp:`{ROOT}`, a
story named :samp:`{NAME}` is exposed under the :term:`scope`
:samp:`{ROOT}/{NAME}`. The interface provides the following methods:

.. js:function:: run()

   Start execution and wait for finish. Returns result (e.g. success or number
   of errors).

.. js:function:: cancel()

   Cancel execution.

.. js:function:: continue()

   Continue story when waiting in a breakpoint.