Creating new plugins

Overview

The recommended way of contributing to the Orthanc code consists in extending it by creating new plugins.

Native Orthanc plugins must use the plugin SDK whose interface is available as a C header. As a consequence, an Orthanc plugin will typically be written using C or C++, although it is also possible to create native plugins using languages that feature compatibility with C headers and with FFI of the C language (such as Rust or Objective-C).

For developers who are more familiar with Python or Java, it is also possible to create plugins using either of those simpler languages. Check out the dedicated Python plugin or the dedicated Java plugin.

Because the C header providing the Orthanc SDK interface is licensed using the GPLv3 license, any Orthanc plugin must be licensed either under the GPLv3 license that is used by the core of Orthanc, or under a more restrictive license that is compatible with the GPL (typically the AGPL).

Here are some resources about creating C/C++ plugins:

We suggest developers to adopt the coding style of the Orthanc core, although this is of course not required.

Do not hesitate to contact us if you wish your plugin to be indexed in the dedicated part of the Orthanc Book!

Structure of the plugins

A plugin takes the form of a shared library (.DLL under Windows, .so under GNU/Linux, .dylib under Apple OS X…) that uses the FFI of the C language to declare 4 public functions/symbols:

  • int32_t OrthancPluginInitialize(OrthancPluginContext* context). This callback function is responsible for initializing the plugin. The context argument gives access to the API of Orthanc.

  • void OrthancPluginFinalize(). This function is responsible for finalizing the plugin, releasing all the allocated resources.

  • const char* OrthancPluginGetName(). This function must give a name to the plugin.

  • const char* OrthancPluginGetVersion(). This function must provide the version of the plugin.

Remark: The size of the memory buffers that are exchanged between the Orthanc core and the plugins must be below 4GB. This is a consequence of the fact that the Orthanc plugin SDK uses uint32_t to encode the size of a memory buffer. We might extend the SDK in the future to deal with buffers whose size is above 4GB.

Plugin SDK

Any plugin project should include the official C header file that is part of the Orthanc source distribution:

Online documentation for this C header is available, as generated by Doxygen.

Convenience C++ wrappers around the plain C API are available in the Orthanc source distribution. The following three files can be used in your projects, and only depend on Boost and JsonCpp if macro HAS_ORTHANC_EXCEPTION is set to 0: