<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="../plugin.xsl" type="text/xsl"?>
<plugin name="MqttInjector">
  <object class="org.ow2.isac.plugin.mqttinjector.SessionObject">
    <params>
      <param name="client id size" type="String" />
      <param name="library" type="String" />
    </params>
    <help>This ISAC plug-in supports connection and interaction with an MQTT server, as of version 3.1.1 of the MQTT specification. Once connected, the virtual user may publish messages on topics and subscribe to topics. The payload of messages received from a topic subscription may be retrieved and made available as plug-in variables (see sample getMessage, conditions isDefined/isNotDefined and control clear to manage these variables).</help>
  </object>
  <sample name="connect" number="0">
    <params>
      <param name="host" type="String" />
      <param name="port" type="String" />
      <param name="protocol" type="String" />
      <param name="action type" type="String" />
      <param name="comment" type="String" />
      <param name="clientid" type="String" />
      <param name="username" type="String" />
      <param name="password" type="String" />
      <param name="timeout_s" type="String" />
      <param name="message" type="String" />
      <param name="qos" type="String" />
      <param name="topic" type="String" />
      <param name="flags" type="String" />
      <param name="enable" type="String" />
      <param name="keepalive_s" type="String" />
    </params>
    <help>Connects to an MQTT server. Leave the client id input blank if you want it to be generated. Leave user name and password empty if authentication is not required.&#xD;
Any attempt to connect an already connected virtual user will fail and generate an exception.&#xD;
A connection time-out may be set in seconds, zero meaning no time-out (infinite connection delay).&#xD;
Once connected, the client identifier is available via variable #.</help>
  </sample>
  <sample name="publish" number="1">
    <params>
      <param name="message" type="String" />
      <param name="qos" type="String" />
      <param name="topic" type="String" />
      <param name="action type" type="String" />
      <param name="comment" type="String" />
      <param name="flags" type="String" />
    </params>
    <help>Publishes a message over a topic. This virtual user must be connected piori to publish a message.</help>
  </sample>
  <sample name="disconnect" number="4">
    <params>
      <param name="action type" type="String" />
      <param name="comment" type="String" />
    </params>
    <help>Disconnects current virtual user from an MQTT server. Any attempt to disconnect a unconnected server will fail.</help>
  </sample>
  <sample name="subscribe" number="5">
    <params>
      <param name="topic" type="String" />
      <param name="qos" type="String" />
      <param name="action type" type="String" />
      <param name="comment" type="String" />
      <param name="size" type="String" />
      <param name="policy" type="String" />
    </params>
    <help>Subscribes current virtual user to the given topic. The virtual user must be connected prior to subscribe.&#xD;
Once the virtual user has subscribed to a topic, received messages may be retrieved using sample getmessage. In order to enable this feature, the capacity of the incoming messages queue (in terms of maximum number of queued messages) must be set to a value greater than zero. A drop policy must also be chosen to decide what to do when the queue is full: either drop the oldest message, or drop the incoming message.</help>
  </sample>
  <sample name="unsubscribe" number="6">
    <params>
      <param name="topic" type="String" />
      <param name="action type" type="String" />
      <param name="comment" type="String" />
    </params>
    <help>Unsubscribes current virtual user from a topic. The virtual user must be connected to an MQTT and have subscribed to the topic prior to unsubscribe.</help>
  </sample>
  <sample name="getMessage" number="7">
    <params>
      <param name="timeout" type="String" />
      <param name="topics" type="String" />
      <param name="action type" type="String" />
      <param name="comment" type="String" />
      <param name="topic var" type="String" />
      <param name="message var" type="String" />
      <param name="options" type="String" />
    </params>
    <help>Tries to retrieve a message from the message queue associated with one, several or all topic subscriptions (leave empty the list of topics for all currently subscribed topics). A negative timeout means infinite time-out. A zero timeout means no waiting time. If a message could be retrieved and a message name was provided, the message payload is then available as data from a plug-in variable with this name: ${myMqtt:message var}. Moreover, conditions isDefined and isNotDefined are set accordingly for this variable name, making it possible to check whether a message could be retrieved before trying to get the corresponding variable value from the plug-in.&#xD;
Similarly, the actual topic the message was sent to can be retrieved through a variable.</help>
  </sample>
  <test name="isConnected" number="2">
    <params />
    <help>True if this virtual user is connected to an MQTT server, false otherwise.</help>
  </test>
  <test name="isNotConnected" number="3">
    <params />
    <help>True if this virtual user is not connected to an MQTT server, false otherwise.</help>
  </test>
  <test name="isDefined" number="8">
    <params>
      <param name="variable" type="String" />
    </params>
    <help>True if an incoming message (coming from a topic subscription) or its actual topic has been retrieved by sample getMessage and associated to the provided name. False if the last call to getMessage failed or if no name was associated with the retrieved message or associated topic, or if no call to getMessage has been performed since the topic subscription.</help>
  </test>
  <test name="isNotDefined" number="9">
    <params>
      <param name="variable" type="String" />
    </params>
    <help>True if the provided name is unknown in this virtual user's incoming message queue or associated topic. False if the virtual user has subscribed to a topic, received a message on this topic and stored either the message payload or its actual topic in a variable with the same name, using sample getMessage.</help>
  </test>
  <control name="clear" number="10">
    <params>
      <param name="variable" type="String" />
    </params>
    <help>Clears a message previously retrieved and named by a call to sample getMessage. After control clear has been called on a given name, condition isDefined is false and condition isNotDefined is false for this name. Any further reference to the plug-in variable of this name would throw an exception.</help>
  </control>
</plugin>

