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:
Sample code for plugins can be found in the official Orthanc repository (in the
Plugins/Samplesfolder).A tutorial showing how to implement a basic WADO server is available on CodeProject.
Marco Barnig provides tutorial lessons to create Orthanc plugins as part of his RadioLogic project.
Technical workshop about “Writing an Orthanc C++ plugin” presented by Benjamin Golinvaux at OrthancCon 2019.
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. Thecontextargument 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: