.. _creating-plugins:

Creating new plugins
====================

.. contents::

Overview
--------

The recommended way of :ref:`contributing to the Orthanc code
<contributing>` consists in extending it by creating new :ref:`plugins
<plugins>`.

Native Orthanc plugins must use the `plugin SDK
<https://orthanc.uclouvain.be/sdk/>`__ whose interface is available as a
`C header
<https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.2/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__.
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
<https://en.wikipedia.org/wiki/Foreign_function_interface>`__ (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 :ref:`dedicated Python plugin
<python-plugin>` or the :ref:`dedicated Java plugin <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
<http://www.gnu.org/licenses/quick-guide-gplv3.en.html>`__ that is
used by the :ref:`core of Orthanc <licensing>`, 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
  <https://orthanc.uclouvain.be/hg/orthanc/file/default/OrthancServer/Plugins/Samples/>`__
  (in the ``Plugins/Samples`` folder).

* A tutorial showing how to implement a basic WADO server is
  `available on CodeProject
  <https://www.codeproject.com/Articles/797118/Implementing-a-WADO-Server-using-Orthanc>`__.

* Marco Barnig provides `tutorial lessons to create Orthanc plugins
  <https://github.com/mbarnig/RadioLogic/wiki#user-content-orthanc-plugin-development>`__
  as part of his `RadioLogic project
  <https://github.com/mbarnig/RadioLogic/>`__.

* Technical workshop about "`Writing an Orthanc C++ plugin
  <https://bitbucket.org/bgo-osimis/orcon19-plugin-workshop/>`__"
  presented by Benjamin Golinvaux at `OrthancCon 2019
  <https://www.orthanc-server.com/static.php?page=conference-schedule>`__.
  
We suggest developers to adopt the :ref:`coding style of the Orthanc
core <coding-style>`, although this is of course not required.

Do not hesitate to `contact us
<https://www.orthanc-server.com/static.php?page=contact>`__ if you wish
your plugin to be **indexed** in :ref:`the dedicated part of the
Orthanc Book <plugins-contributed>`!

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
<https://en.wikipedia.org/wiki/Application_binary_interface>`__ 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:

* `Plugins/Include/orthanc/OrthancCPlugin.h
  <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.2/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__

`Online documentation <https://orthanc.uclouvain.be/sdk/>`__ for this C
header is available, as generated by `Doxygen
<https://en.wikipedia.org/wiki/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
<https://www.boost.org/>`__ and `JsonCpp
<https://github.com/open-source-parsers/jsoncpp>`__ if macro
``HAS_ORTHANC_EXCEPTION`` is set to ``0``:

* `Plugins/Samples/Common/OrthanPluginCppWrapper.h
  <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.2/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.h>`__
* `Plugins/Samples/Common/OrthanPluginCppWrapper.cpp
  <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.2/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp>`__
* `Plugins/Samples/Common/OrthanPluginException.h
  <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.2/OrthancServer/Plugins/Samples/Common/OrthancPluginException.h>`__