nx_cloud_storage_sdk  1.0
Cloud Storage SDK
Cloud Storage SDK

// Copyright 2018-present Network Optix, Inc. Licensed under MPL 2.0: www.mozilla.org/MPL/2.0/


License

The whole contents of this package, including all C/C++ source code, is licensed as Open Source under the terms of Mozilla Public License 2.0: www.mozilla.org/MPL/2.0/, with the possible exception of certain files which may be licensed under the terms of other open-source licenses explicitly referenced in those files.

See the license texts in licenses/ directory located in the root directory of this package.


Introduction

This package provides an SDK to create so-called Cloud Storage Plugins for the Video Management System (VMS).

From the business logic point of view, an Cloud Storage Plugin creates its own type of a Storage capable of receiving the video stream from the VMS Server to be recorded into some storage in order to be retrieved afterwards.

This SDK is conceived as an alternative to the long-existing Storage SDK for those cases when the underlying implementation is stream-based rather than file-based. Plugins created with this SDK are used seamlessly by the VMS along with Storage plugins - from the VMS user point of view, both types of plugins create the video recording and playback looks the same whether the conventional storages or stream based are used.

Here are the main ideas behind this SDK:

ATTENTION: This SDK is currently considered a work-in progress. Plugins written with this SDK are not recommended for production systems. This SDK is likely to have breaking changes introduced in the further VMS versions, so the plugins written now will likely not be compatible with the future VMS versions. As part of this work-in-progress, the SDK contains several header files taken from Video Source SDK - camera/camera_plugin.h, camera/camera_plugin_types.h and plugins/plugin_api.h; the entities in these files are named using outdated conventions and may lack proper documentation.

From the developers' point of view, an Cloud Storage Plugin is a dynamic library (.dll on Windows, .so on Linux) which exports a single extern "C" entry point function. Such function is a factory for objects inherited from a dedicated SDK abstract class (in other words, implementing a dedicated interface) class nx::sdk::cloud_storage::IPlugin (src/nx/sdk/cloud_storage/i_plugin.h), derived from class nx::sdk::IPlugin (src/nx/sdk/i_plugin.h). This base interface also defines the name and the prototype of the entry point function.

ATTENTION: If you consider linking your plugin to any dynamic libraries, including the ones from the OS, consult src/nx/sdk/dynamic_libraries.md to avoid potential issues.

To make it possible to develop plugins using a different C++ compiler (e.g. with an incompatible ABI) rather than the one used to compile the VMS itself, or potentially in languages other than C++, a COM-like approach is offered: all objects created in a plugin or passed to a plugin inherit abstract classes declared in header files of this SDK, which have only pure virtual functions with C-style arguments (not using C++ standard library classes). To manage lifetime of such objects, they incorporate a reference counter.

The SDK C++ files have extensive documentation comments in Doxygen format, from which HTML files are generated and included into the SDK: see docs/html/index.html.


Helper tools

To simplify implementation of a plugin, a number of helper classes are provided with this SDK that implement the SDK interfaces and handle such complexities as reference counting and interface requesting. Such classes are located in folders named helpers. If such a helper class does not address all the requirements of the plugin author, it may be subclassed or not used at all - the plugin can always implement everything from scratch using just interfaces from the header files.

Also, some tools are provided with this SDK, which are recommended though not required to be used by a plugin:

This package includes two samples of an Cloud Storage Plugin written in C++, located at samples/.

The first one is called Sample Cloud Storage Plugin, located at samples/sample_cloud_storage_plugin/. It receives the video stream from the Server, ignores it, and returns nothing when the Server tries to retrieve the video stream from the Storage. This plugin has many comments in the source code, which help to better understand how Cloud Storage Plugins should be written.

The second sample is called Stub Cloud Storage Plugin, located at samples/stub_cloud_storage_plugin/. It works using the local file system as the underlying storage, and tends to use every feature available in the SDK.

These samples can be compiled and linked using CMake.

Prerequisites:

- CMake >= 3.3.2
- Windows (7 or 10): Microsoft Visual Studio >= 2019
- Linux (Ubuntu 16.04, 18.04, 20.04) including ARM (e.g. Raspberry Pi or Nvidia Tegra) native or
cross-compiling:
- g++ >= 7.5
- make or Ninja

To compile the samples, execute the commands collected into the provided scripts (use their source code as a reference; run with -h or /? to see the possible options):

# Windows, x64:
build_samples.bat
# Linux or Windows with Cygwin, x64:
build_samples.sh
# Linux, 64-bit ARM cross-compiling (e.g. Nvidia Tegra):
# NOTE: The provided file toolchain_arm64.cmake defines which cross-compiler will be used.
build_samples_arm64.sh
# Linux, 32-bit ARM cross-compiling (e.g. Raspberry Pi):
# NOTE: The provided file toolchain_arm32.cmake defines which cross-compiler will be used.
build_samples_arm32.sh

On Windows, after CMake generation phase, Visual Studio GUI can be used to compile a sample: open ..\cloud_storage_sdk-build\<sample_name>\<sample_name>.sln and build the ALL_BUILD project. Make sure that the platform combo-box is set to "x64".

After the successful build, locate the built artifacts:

# Windows:
..\cloud_storage_sdk-build<sample_name>\Debug<sample_name>.dll
# Linux:
../cloud_storage_sdk-build/<sample_name>/lib<sample_name>.so

To install a plugin, just copy its library file to the dedicated folder in the VMS Server installation directory:

# Windows:
C:\Program Files<vms-installation-dir>\MediaServer\plugins\
# Linux:
/opt/<vms-installation-dir>/mediaserver/bin/plugins/

ATTENTION: After copying a plugin library, the Server has to be restarted.