Mercurial > hg > orthanc-book
view Sphinx/source/developers/creating-plugins.rst @ 878:2e3493d618ad
auth 0.3.0
author | Alain Mazy <am@osimis.io> |
---|---|
date | Mon, 26 Sep 2022 19:13:45 +0200 |
parents | f72b2dd172da |
children | 6474e299918b |
line wrap: on
line source
.. _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://sdk.orthanc-server.com/>`__ whose interface is available as a `C header <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.11.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, it is also possible to create plugins using this simpler language. Check out the :ref:`dedicated Python plugin <python-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://hg.orthanc-server.com/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://hg.orthanc-server.com/orthanc/file/Orthanc-1.11.2/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ `Online documentation <https://sdk.orthanc-server.com/>`__ 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://hg.orthanc-server.com/orthanc/file/Orthanc-1.11.2/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.h>`__ * `Plugins/Samples/Common/OrthanPluginCppWrapper.cpp <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.11.2/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp>`__ * `Plugins/Samples/Common/OrthanPluginException.h <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.11.2/OrthancServer/Plugins/Samples/Common/OrthancPluginException.h>`__