4. HTTP API Message List

2N^® Helios HTTP API defines the following types of messages:

Subscribe
SubscribeResponse
CreatePullPoint
CreatePullPointResponse
Renew
RenewResponse
Unsubscribe
UnsubscribeResponse
GetMessages
GetMessagesResponse
Notify

See below for details on the messages and their parameters and use.

Subscribe

The Subscribe request helps you subscribe to retrieval of 2N Helios IP events in the Subscribe mode, in which 2N Helios IP sends events autonomously in the form of Notify messages to the HTTP address specified in the request.

Send the Subscribe request to the 2N Helios IP address: http://helios_ip_address/notification.

2N Helios IP will reply with the SubscribeResponse message.

Subscribe request format:

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
    xmlns:a="http://www.w3.org/2005/08/addressing"
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
  </s:Header>
  <s:Body>
    <wsnt:Subscribe>
      <wsnt:ConsumerReference>
        <a:Address>
          {HTTP_CONSUMER_ADDRESS}
        </a:Address>
      </wsnt:ConsumerReference>
      <wsnt:Filter>
        <wsnt:TopicExpression Dialect= 
            "http://www.2n.cz/2013/TopicExpression/Multiple">
          {EVENTS_LIST}
        </wsnt:TopicExpression>
      </wsnt:Filter>
      <wsnt:InitialTerminationTime>
        {DATETIME_OR_DURATION}
      </wsnt:InitialTerminationTime>
      <wsnt:SubscriptionPolicy>
        <event2n:MaximumNumber>
          {MAX_NUMBER_OF_MSGS_AT_ONCE}
        </event2n:MaximumNumber>
        <event2n:StartRecordId>
          {START_RECORD_ID}
        </event2n:StartRecordId>
        <event2n:StartTimestamp>
          {START_TIMESTAMP}
        </event2n:StartTimestamp>
      </wsnt:SubscriptionPolicy>
    </wsnt:Subscribe>
  </s:Body>
</s:Envelope>

Message Parameters

HTTP_CONSUMER_ADDRESS

Specify the address to which the Notify messages including the requested events shall be sent. Keep the HTP URI address format, e.g. http://192.168.23.73/notify_server. The parameter is obligatory.

DATETIME_OR_DURATION

Set the subscription time. Subscription will be cancelled automatically by when this time period expires. Send the Renew request before expiry to extend the subscription time. Enter the absolute time (DateTime) or relative duration (Duration) to specify the subscription time; refer to the Format of Selected Parameters subsection. The parameter is obligatory.

EVENTS_LIST

Make up a list of requested events. Separate the event types with a comma, e.g. event2n:KeyPressed, event2n:CardEntered. The parameter is optional. If you define no events, you will get all types of events.

MAX_NUMBER_OF_MSGS_AT_ONCE

Set the maximum count of events to be sent within one Notify message. The parameter is optional. If no value is completed, up to 10 events will be sent in one Notify message.

START_TIMESTAMP

Set the data and time for the oldest log event to be the first in the Notify message. The parameter is optional. If no value is set, all log events will be sent.

START_RECORD_ID

Set the RecordId for the log event to be the first in the Notify message. The parameter is optional. If no value is set, all log events will be sent.

SubscribeResponse

2N Helios IP sends the SubscribeResponse message in reply to the Subscribe request to inform the client that the client’s subscription has been completed successfully.

<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsa5="http://www.w3.org/2005/08/addressing"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <wsa5:Action s:mustUnderstand="true">
      http://docs.oasis-open.org/wsn/bw-2/NotificationProducer/SubscribeResponse
    </wsa5:Action>
  <s:Header>
  <s:Body>
    <wsnt:SubscribeResponse>
      <wsnt:SubscriptionReference>
        <wsa5:Address>
          {NOTIFICATIONS_PRODUCER_ADDRESS}
        </wsa5:Address>
        <wsa5:ReferenceParameters>
          <event2n:SubscriptionId>
            {SUBSCRIPTION_ID}
          </event2n:SubscriptionId>
        </wsa5:ReferenceParameters>
      </wsnt:SubscriptionReference>
      <wsnt:CurrentTime>
        {CURRENT_TIME}
      </wsnt:CurrentTime>
      <wsnt:TerminationTime>
        {EXPIRE_TIME}
      </wsnt:TerminationTime>
    </wsnt:SubscribeResponse>
  </s:Body>
</s:Envelope>

Message Parameters

NOTIFICATIONS_PRODUCER_ADDRESS

Specify the address for subsequent subscription communication with 2N Helios IP (i.e. a new address for Unsubscribe and Renew requests). In the present implementation, the address is http://helios_ip_address/notification.

SUBSCRIPTION_ID

A unique subscription identification code to be used for subsequent Renew and Unsubscribe communication with 2N Helios IP. Edit the Id as a common text.

CURRENT_TIME

Subscription date and time from the viewpoint of 2N Helios IP. Refer to the Format of Selected Parameters for format details.

EXPIRE_TIME

Specify the subscription date and time. Use the Renew request to extend the subscription time before expiry. Refer to the Format of Selected Parameters for format details.

CreatePullPoint

The CreatePullPoint request helps you subscribe to 2N Helios IP event retrieval in the PullPoint mode, in which you read out events from the log actively using the GetMessages request.

Send the CreatePullPoint request to the 2N Helios IP address: http://helios_ip_address/notification

2N Helios IP will reply with the CreatePullPointResponse.

CreatePullPoint request format:

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
  </s:Header>
  <s:Body>
    <wsnt:CreatePullPoint>
      <wsnt:Filter>
        <wsnt:TopicExpression Dialect=
           "http://www.2n.cz/2013/TopicExpression/Multiple">
          {EVENTS_LIST}
        </wsnt:TopicExpression>
      </wsnt:Filter>      
      <wsnt:InitialTerminationTime>
        {DATETIME_OR_DURATION}
      </wsnt:InitialTerminationTime>
      <wsnt:SubscriptionPolicy>
        <event2n:StartRecordId>
          {START_RECORD_ID}
        </event2n:StartRecordId>
        <event2n:StartTimestamp>
          {START_TIMESTAMP}
        </event2n:StartTimestamp>
      </wsnt:SubscriptionPolicy>
    </wsnt:CreatePullPoint>
  </s:Body>
</s:Envelope>

CreatePullPointResponse

2N Helios IP sends the CreatePullPointResponse in reply to the CreatePullPoint request to inform the client that the client’s subscription has been completed successfully.

<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsa5="http://www.w3.org/2005/08/addressing" 
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2" 
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <wsa5:Action>//http://docs.oasis-open.org/wsn/bw-2/CreatePullPoint/CreatePullPointResponse
    </wsa5:Action>
  </s:Header>
  <s:Body>
    <wsnt:CreatePullPointResponse>
      <wsnt:SubscriptionReference>
        <wsa5:Address>
          {NOTIFICATIONS_PRODUCER_ADDRESS}
        </wsa5:Address>
        <wsa5:ReferenceParameters>
          <event2n:SubscriptionId>
            {SUBSCRIPTION_ID}
          </event2n:SubscriptionId>
        </wsa5:ReferenceParameters>
      </wsnt:SubscriptionReference>
      <wsnt:CurrentTime>
        {CURRENT_TIME}
      </wsnt:CurrentTime>
      <wsnt:TerminationTime>
        {EXPIRE_TIME}
      </wsnt:TerminationTime>
    </wsnt:CreatePullPointResponse>
  </s:Body>
</s:Envelope>

Message Parameters

NOTIFICATIONS_PRODUCER_ADDRESS

Specify the address for subsequent subscription communication with 2N Helios IP (i.e. a new address for Unsubscribe, Renew and GetMessages requests). In the present implementation, the address is http://helios_ip_address/notification .

SUBSCRIPTION_ID

A unique subscription identification code to be used for subsequent Renew, Unsubscribe and GetMessages communication with 2N Helios IP. Edit the Id as a common text.

CURRENT_TIME

Subscription date and time from the viewpoint of 2N Helios IP. Refer to the Format of Selected Parameters for format details.

EXPIRE_TIME

Specify the subscription date and time. Use the Renew request to extend the subscription time before expiry. Refer to the Format of Selected Parameters for format details.

Renew

The Renew request helps you extend your subscription time. Send the request to the address included in the SubscribeResponse message. 2N Helios IP replies with the RenewResponse message.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope
    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <event2n:SubscriptionId a:IsReferenceParameter="true">
      {SUBSCRIPTION_ID}
    </event2n:SubscriptionId>
  </s:Header>
  <s:Body>
    <wsnt:Renew>
      <wsnt:TerminationTime>
        {DATETIME_OR_DURATION}
      </wsnt:TerminationTime>
    </wsnt:Renew>
  </s:Body>
</s:Envelope>

Message Parameters

SUBSCRIPTION_ID

A unique subscription identification code included in the SubscriptionResponse. The parameter is obligatory.

DATETIME_OR_DURATION

Extend the subscription time. Subscription will be cancelled automatically by 2N Helios IP when this time period expires. Send another Renew request before expiry to extend the subscription time. Enter the absolute time (DateTime) or relative duration (Duration) to specify the subscription time; refer to the Format of Selected Parameters subsection. The parameter is obligatory.

RenewResponse

The RenewResponse message is a reply to the Renew request, in which 2N Helios IP informs the client of the prolongation of the client’s subscription time.

<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsa5="http://www.w3.org/2005/08/addressing"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2">
  <s:Header>
    <wsa5:Action s:mustUnderstand="true">
      http://docs.oasis-open.org/wsn/bw-2/SubscriptionManager/RenewResponse
    </wsa5:Action>
  </s:Header>
  <s:Body>
    <wsnt:RenewResponse>
      <wsnt:TerminationTime>
        {CURRENT_TIME}
      </wsnt:TerminationTime>
      <wsnt:CurrentTime>
        {EXPIRE_TIME}
      </wsnt:CurrentTime>
    </wsnt:RenewResponse>
  </s:Body>
</s:Envelope>

Message Parameters

CURRENT_TIME

Subscription date and time from the viewpoint of 2N Helios IP. Refer to the Format of selected parameters for format details.

EXPIRE_TIME

Specify the subscription date and time. Use the Renew request to extend the subscription time before expiry. Refer to the Format of Selected Parameters for format details.

Unsubscribe

The Unsubscribe request helps you terminate your subscription. Send this request to the address included in the SubscribeResponse message. 2N Helios IP replies with the UnsubscribeResponse.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope
    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <event2n:SubscriptionId a:IsReferenceParameter="true">
      {SUBSCRIPTION_ID}
    </event2n:SubscriptionId>
  </s:Header>
  <s:Body>
    <wsnt:Unsubscribe>
    </wsnt:Unsubscribe>
  </s:Body>
</s:Envelope>

Message Parameters

SUBSCRIPTION_ID

A unique subscription identification code included in the SubscriptionResponse. The parameter is obligatory.

UnsubscribeResponse

The UnsubscribeResponse message is a reply to the Unsubscribe request, in which 2N Helios IP confirms the client’s subscription termination.

<s:Envelope
    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsa5="http://www.w3.org/2005/08/addressing"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2">
  <s:Header>
    <wsa5:Action s:mustUnderstand="true">
      http://docs.oasis-open.org/wsn/bw-2/SubscriptionManager/UnsubscribeResponse
    </wsa5:Action>
  </s:Header>
  <s:Body>
    <wsnt:UnsubscribeResponse>
    </wsnt:UnsubscribeResponse>
  </s:Body>
</s:Envelope>

GetMessages

The GetMessages request helps you read out events actively from 2N Helios IP. Send the request to the address included in the CreatePullPointResponse. 2N Helios IP replies with the GetMessageResponse.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2" 
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <event2n:SubscriptionId a:IsReferenceParameter="true">
      {SUBSCRIPTION_ID}
    </event2n:SubscriptionId>
  </s:Header>
  <s:Body>
    <wsnt:GetMessages>
      <wsnt:MaximumNumber>
        {MAXIMUM_MSGS_IN_RESPONSE}
      </wsnt:MaximumNumber>      
      <wsnt:Timeout>
        {WAIT_TIMEOUT}
      </wsnt:Timeout>
 </wsnt:GetMessages>
  </s:Body>
</s:Envelope>

Message Parameters

SUBSCRIPTION_ID

A unique subscription identification code included in the SubscriptionResponse. The parameter is obligatory.

MAXIMUM_MSGS_IN_RESPONSE

Set the maximum count of events to be sent within the GetMessagesResponse. The parameter is optional. If no value is completed, up to 10 events will be sent in one GetMessagesResponse message.

WAIT_TIMEOUT

Delay for the answer. Value can be in the range of 0–90 (time in seconds). If the value is bigger than 90 then 90 will be applied. If the parameter is not defined then no delay will be appplied. The parameter is optional.

GetMessagesResponse

The GetMessagesResponse message is a reply to the GetMessages request.

<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:topic2n="http://www.2n.cz/2013/event/topics" 
    xmlns:wsa5="http://www.w3.org/2005/08/addressing" 
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2" 
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <wsa5:Action s:mustUnderstand="true">
      http://docs.oasis-open.org/wsn/bw-2/PullPoint/GetMessagesResponse
    </wsa5:Action>
  </s:Header>
  <s:Body>
    <wsnt:GetMessagesResponse>
       {EVENT_LIST}
    </wsnt:GetMessagesResponse>
  </s:Body>
</s:Envelope>

Message Parameters

EVENT_LIST

Refer to the Logged Events subsection for the list of events. The event list can be empty. Specify the maximum count of events to be sent at one time in the CreatePullPoint request in the Subscribe or the GetMessages request.

Notify

The Notify message informs you of the rise of a new event in the Subscription mode. 2N Helios IP sends Notify to the address specified in the Subscribe request. The Notify message have to be confirmed by the OK message from the opposite party. The next Notify message is sent after confirmation or after aprox 5 s timeout.

<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:topic2n="http://www.2n.cz/2013/event/topics" 
    xmlns:event2n="http://www.2n.cz/2013/event"
    xmlns:wsa5="http://www.w3.org/2005/08/addressing"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2">
  <s:Header>
    <wsa5:Action s:mustUnderstand="true">
      http://docs.oasis-open.org/wsn/bw-2/NotificationConsumer/Notify
    </wsa5:Action>
  </s:Header>
  <s:Body>
    <wsnt:Notify>
       {EVENT_LIST}
    </wsnt:Notify>
  </s:Body>
</s:Envelope>

Message Parameters

EVENT_LIST

Refer to the Logged Events subsection for the list of events. The message always includes one event at least. Specify the maximum count of events in the Subscribe request.