This article explains how the Server interacts with integrations, manages their lifecycle, and handles data flow.

Integration initialization

1. The Server loads the integrations dynamic library and calls its entry point function, createNxIntegration() (defined in i_integration.h). This function returns a pointer to the nx::sdk::IIntegration interface instance.

2. The Server creates an Engine instance by passing this pointer to IIntegration::createEngine().

   • createEngine() calls the doCreateEngine() virtual method of the interface class, which is implemented in the Integrationhelper class.

   • doCreateEngine() then calls the virtual method doObtainEngine(), which is overridden in the Integration helper class.

   • IIntegration::createEngine() returns a pointer to the IEngine interface instance.

DeviceAgent creation

When you enable an integration for a specific camera in the Desktop Client, the Server creates a DeviceAgent instance using the following process:

1. The Desktop Client displays the configuration options defined in the deviceAgentSettingsModel which is returned by the Engine::manifestString() method.

2. When a user clicks OK or Apply in the Desktop Client, the Server calls the IEngine::obtainDeviceAgent() virtual method.

3. IEngine::obtainDeviceAgent() calls the doObtainDeviceAgent() virtual method, which is overridden in the Engine helper class.

Data processing flow

The Server delivers data packets, such as video frames, directly to the integration.

1. Whenever the Server retrieves a frame, it invokes the doPushDataPacket() method of the IConsumingDeviceAgent interface. This is a universal method used across all integration types (analytics, video source, and storage) and executes entirely within the Server without external resources.

2. Within the Metadata SDK, pushDataPacket invokes the doPushDataPacket() virtual method defined in src/nx/sdk/analytics/i_consuming_device_agent.h.

3. The doPushDataPacket() method is overridden in the ConsumingDeviceAgent helper class located in src/nx/sdk/analytics/helpers/consuming_device_agent.cpp.

To simplify development, the helper class implements several additional methods:

• pushCompressedVideoFrame()

• pushUncompressedVideoFrame()

• pullMetadataPackets()

• pushMetadataPacket()

When the Server retrieves a new frame from a camera, it simultaneously calls the following methods:

• pushUncompressedFrame() or pushUncompressedVideoFrame() to deliver the frame to the integration.

• pullMetadataPackets() to request and receive metadata back from the integration.

Alternatively, the DeviceAgent can call pushMetadataPacket() at any time.

Push vs. pull paradigms

You can choose either a push or a pull workflow based on your integrations architectural needs.

• Push paradigm (pushMetadataPacket())

  • Initiated by: The integration

  • Expected data: A single metadata packet

• Pull paradigm (pullMetadataPackets())

  • Initiated by: The Server

  • Expected data: A std::vector of metadata packets

Recommended helper classes

To build analytics integrations efficiently, we recommend using these three built-in helper classes:

• Integration: Implemented in integration.cpp and integration.h.

• Engine: Implemented in engine.cpp and engine.h.

• DeviceAgent: Implemented in device_agent.cpp and device_agent.h.