Integrator C Series API

Synchronous API calls

The API is by nature asynchronous; meaning that there is no guarantee that command responses will arrive in the same order as the commands were issued. The codec may also respond with feedback between your request and the response due to changes (e.g. status changes or events) on the system.

For some applications it might be crucial to match requests with responses. The API therefore supports a response-tagging mechanism for such cases. The example below shows how this works and how to use it.

xcommand Video Layout Add | resultId="mytag_1"

OK
*r VideoLayoutAddResult (status=OK):
    LayoutId: 1
** resultId: "mytag_1"
** end

In XML mode the resultId will be added as an attribute to the top-level XmlDoc tag:

xgetxml /Configuration/Video/Layout/Scaling | resultId="mytag_2"
<XmlDoc resultId="mytag_2">
<Configuration item="1">
  <Video item="1">
    <Layout item="1">
      <Scaling item="1" valueSpaceRef="...">Off</Scaling>
    </Layout>
  </Video>
</Configuration>
</XmlDoc>

This mechanism works with all commands (xcommand, xconfiguration and xstatus). A typical use of this would be to create a command queue in your application and assign unique IDs to every command sent to the codec. A listener would listen to all feedback from the codec and match the ID on the response with the corresponding ID in the command queue, thus enabling matching the original request with the specific response.