{% extends "layouts/content.html" %}
{% load i18n %}
{% load utils %}

{% block navigation %}
<div id="lava-extension-navigation">
  <ul>
    <li><a class="lava-back" href="{% url 'lava.home' %}"
      >{% trans "Back to LAVA" %}</a></li>
    <li><a href="{% url 'lava.api_help' %}">{% trans "API Help" %}</a></li>
    <li><a href="{% url 'linaro_django_xmlrpc.views.tokens' %}">{% trans "Authentication Tokens" %}</a></li>
  </ul>
</div>
{% endblock %}


{% block content %}
<h2>Event notifications</h2>
<p>Event notifications are handled by the lava-publisher service on the master. You can subscribe to these events through lava-publisher service and receive events such as:</p>
<ul class="simple">
  <li>metadata on the instance which was the source of the event</li>
  <li>description of a status change on that instance.</li>
</ul>

<p>To subscribe to these events, you can get the lava-publisher protocol and port via XML-RPC call from the server [<a href="#scheduler.get_publisher_event_socket"> scheduler.get_publisher_event_socket </a>].</p>

<p>For more information, visit <a href="{{ STATIC_URL }}docs/v2/data-export.html#event-notifications">lava-publisher docs</a>.</p>

<h2>About XML-RPC API</h2>
<p>LAVA Server offers API services as an XML-RPC server. You can interact with it using any XML-RPC
client. For example, in python3 you can do this:</p>
<pre>
import xmlrpc.client
server = xmlrpc.client.ServerProxy("{{ site_url }}{% url 'lava.api_handler' %}", allow_none=True)
print(server.system.listMethods())
</pre>
<p>The following python3 code shows how to authenticate using an
  XML-RPC client, when a method requires authentication.</p>
<p class="text-warning"><strong>WARNING: <code>https://</code> scheme
    is recommended when using authentication.</strong></p>
<pre>
  import xmlrpc.client
  username = "USERNAME"
  token = "TOKEN_STRING"
  hostname = "HOSTNAME"  # {{ site_domain }}
  server = xmlrpc.client.ServerProxy("{{ site_scheme }}://%s:%s@%s{% url 'lava.api_handler' %}" % (username, token, hostname), allow_none=True)
  print(server.system.listMethods())
</pre>
<p class="text-info">NOTE: <code>USERNAME</code> is a valid username
  in the specified LAVA instance. <code>TOKEN_STRING</code> is a valid token
  associated with the above username in the same LAVA
  instance. <code>HOSTNAME</code> is the fully qualified domain name
  or IP address of the same LAVA instance.
</p>
<p class="text-info"> In the above code snippet the ServerProxy string
  is constructed from different components, with separators, which are
  clearly illustrated as follows:<br>
  <code>USERNAME:TOKEN_STRING@HOSTNAME/HANDLER</code>
</p>
<p><code>allow_none=True</code> allows your client to match the server behaviour
of handling an empty value as a null (<code>None</code> in Python, <code>undef</code> in Perl etc.)
instead of as string like <code>'None'</code>.
</p>
<h2 id="top">Available functions</h2>
<div>
      <h2>Scheduler</h2>
      {{ methods|get_api_by_section:'scheduler' }}
      <h2>Results</h2>
      {% for method in methods.results %}
        [&nbsp;<a href="#{{method.name}}">{{ method.name }}</a>&nbsp;]
      {% endfor %}
      <h2>System and Authentication</h2>
      {% for method in methods.system %}
        [&nbsp;<a href="#{{method.name}}">{{ method.name }}</a>&nbsp;]
      {% endfor %}
</div>

{% for method in methods.scheduler %}
    <hr/>
<div id="{{ method.name }}">
  <h3><a href="#{{method.name}}">{{ method.name }}</a></h3>
  <div><pre>{{ method.help }}</pre></div>
  <a href="#top">Available functions</a>
</div>
{% endfor %}

{% for method in methods.results %}
    <hr/>
<div id="{{ method.name }}">
  <h3><a href="#{{method.name}}">{{ method.name }}</a></h3>
  <div><pre>{{ method.help }}</pre></div>
  <a href="#top">Available functions</a>
</div>
{% endfor %}

{% for method in methods.system %}
    <hr/>
<div id="{{ method.name }}">
  <h3><a href="#{{method.name}}">{{ method.name }}</a></h3>
  <div><pre>{{ method.help }}</pre></div>
  <a href="#top">Available functions</a>
</div>
{% endfor %}


{% endblock %}
