Mercurial > hg > orthanc-book

annotate Sphinx/source/developers/creating-plugins.rst @ 795:23271902921a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
replace ABI by more adequate FFI
author Sebastien Jodogne <s.jodogne@gmail.com>
date Mon, 06 Dec 2021 13:19:11 +0100
parents e22c1284ea0e
children 01fa632daae9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
38
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
1 .. _creating-plugins:
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
2
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3 Creating new plugins
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 ====================
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5
250
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
6 .. contents::
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
7
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
8 Overview
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
9 --------
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
10
56
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
11 The recommended way of :ref:`contributing to the Orthanc code
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
12 <contributing>` consists in extending it by creating new :ref:`plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
13 <plugins>`.
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14
794
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
15 Native Orthanc plugins must use the `plugin SDK
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
16 <https://sdk.orthanc-server.com/>`__ whose interface is available as a
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
17 `C header
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
18 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.9.7/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__.
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
19 As a consequence, an Orthanc plugin will typically be written using C
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
20 or C++, although it is also possible to create native plugins using
795
23271902921a replace ABI by more adequate FFI
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 794
diff changeset
21 languages that feature compatibility with C headers and with `FFI of
23271902921a replace ABI by more adequate FFI
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 794
diff changeset
22 the C language
23271902921a replace ABI by more adequate FFI
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 794
diff changeset
23 <https://en.wikipedia.org/wiki/Foreign_function_interface>`__ (such as
23271902921a replace ABI by more adequate FFI
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 794
diff changeset
24 Rust or Objective-C).
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
25
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
26 For developers who are more familiar with Python, it is also possible
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
27 to create plugins using this simpler language. Check out the
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
28 :ref:`dedicated Python plugin <python-plugin>`.
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
29
794
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
30 Because the C header providing the Orthanc SDK interface is licensed
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
31 using the GPLv3 license, any Orthanc plugin must be licensed either
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
32 under the `GPLv3 license
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
33 <http://www.gnu.org/licenses/quick-guide-gplv3.en.html>`__ that is
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
34 used by the :ref:`core of Orthanc <licensing>`, or under a more
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
35 restrictive license that is compatible with the GPL (typically the
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
36 AGPL).
e22c1284ea0e plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 763
diff changeset
37
364
234de55ed125 usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
38 Here are some resources about creating C/C++ plugins:
300
22d567933381 tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 290
diff changeset
39
22d567933381 tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 290
diff changeset
40 * Sample code for plugins can be found `in the official Orthanc
22d567933381 tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 290
diff changeset
41 repository
449
2922fb1bd65e fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 441
diff changeset
42 <https://hg.orthanc-server.com/orthanc/file/default/OrthancServer/Plugins/Samples/>`__
300
22d567933381 tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 290
diff changeset
43 (in the ``Plugins/Samples`` folder).
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
44
300
22d567933381 tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 290
diff changeset
45 * A tutorial showing how to implement a basic WADO server is
22d567933381 tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 290
diff changeset
46 `available on CodeProject
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 336
diff changeset
47 <https://www.codeproject.com/Articles/797118/Implementing-a-WADO-Server-using-Orthanc>`__.
300
22d567933381 tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 290
diff changeset
48
22d567933381 tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 290
diff changeset
49 * Marco Barnig provides `tutorial lessons to create Orthanc plugins
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 336
diff changeset
50 <https://github.com/mbarnig/RadioLogic/wiki#user-content-orthanc-plugin-development>`__
300
22d567933381 tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 290
diff changeset
51 as part of his `RadioLogic project
22d567933381 tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 290
diff changeset
52 <https://github.com/mbarnig/RadioLogic/>`__.
408
f97e9c9bb173 bgo tutorial
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 392
diff changeset
53
f97e9c9bb173 bgo tutorial
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 392
diff changeset
54 * Technical workshop about "`Writing an Orthanc C++ plugin
f97e9c9bb173 bgo tutorial
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 392
diff changeset
55 <https://bitbucket.org/bgo-osimis/orcon19-plugin-workshop/>`__"
f97e9c9bb173 bgo tutorial
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 392
diff changeset
56 presented by Benjamin Golinvaux at `OrthancCon 2019
f97e9c9bb173 bgo tutorial
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 392
diff changeset
57 <https://www.orthanc-server.com/static.php?page=conference-schedule>`__.
300
22d567933381 tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 290
diff changeset
58
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
59 We suggest developers to adopt the :ref:`coding style of the Orthanc
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
60 core <coding-style>`, although this is of course not required.
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
61
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
62 Do not hesitate to `contact us
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 336
diff changeset
63 <https://www.orthanc-server.com/static.php?page=contact>`__ if you wish
66
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 61
diff changeset
64 your plugin to be **indexed** in :ref:`the dedicated part of the
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 61
diff changeset
65 Orthanc Book <plugins-contributed>`!
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
66
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
67 Structure of the plugins
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
68 ------------------------
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
69
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70 A plugin takes the form of a shared library (``.DLL`` under Windows,
67
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 66
diff changeset
71 ``.so`` under GNU/Linux, ``.dylib`` under Apple OS X...) that uses the
795
23271902921a replace ABI by more adequate FFI
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 794
diff changeset
72 `FFI of the C language
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
73 <https://en.wikipedia.org/wiki/Application_binary_interface>`__ to
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
74 declare 4 public functions/symbols:
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
75
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
76 * ``int32_t OrthancPluginInitialize(OrthancPluginContext* context)``. This
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
77 callback function is responsible for initializing the plugin. The
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
78 ``context`` argument gives access to the API of Orthanc.
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
79 * ``void OrthancPluginFinalize()``. This function is responsible
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
80 for finalizing the plugin, releasing all the allocated resources.
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
81 * ``const char* OrthancPluginGetName()``. This function must give a
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
82 name to the plugin.
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
83 * ``const char* OrthancPluginGetVersion()``. This function must
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
84 provide the version of the plugin.
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
85
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
86 *Remark:* The size of the memory buffers that are exchanged between
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
87 the Orthanc core and the plugins must be below 4GB. This is a
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
88 consequence of the fact that the Orthanc plugin SDK uses ``uint32_t``
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
89 to encode the size of a memory buffer. We might extend the SDK in
250
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
90 the future to deal with buffers whose size is above 4GB.
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
91
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
92 Plugin SDK
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
93 ----------
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
94
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
95 Any plugin project should include the **official C header** file
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
96 that is part of the Orthanc source distribution:
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
97
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
98 * `Plugins/Include/orthanc/OrthancCPlugin.h
763
4e9dc26a5cb9 Orthanc 1.9.7
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 741
diff changeset
99 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.9.7/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__
250
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
100
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 336
diff changeset
101 `Online documentation <https://sdk.orthanc-server.com/>`__ for this C
250
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
102 header is available, as generated by `Doxygen
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
103 <https://en.wikipedia.org/wiki/Doxygen>`__.
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
104
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
105 **Convenience C++ wrappers** around the plain C API are available in
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
106 the Orthanc source distribution. The following three files can be used
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
107 in your projects, and only depend on `Boost
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
108 <https://www.boost.org/>`__ and `JsonCpp
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
109 <https://github.com/open-source-parsers/jsoncpp>`__ if macro
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
110 ``HAS_ORTHANC_EXCEPTION`` is set to ``0``:
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
111
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
112 * `Plugins/Samples/Common/OrthanPluginCppWrapper.h
763
4e9dc26a5cb9 Orthanc 1.9.7
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 741
diff changeset
113 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.9.7/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.h>`__
250
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
114 * `Plugins/Samples/Common/OrthanPluginCppWrapper.cpp
763
4e9dc26a5cb9 Orthanc 1.9.7
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 741
diff changeset
115 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.9.7/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp>`__
250
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 249
diff changeset
116 * `Plugins/Samples/Common/OrthanPluginException.h
763
4e9dc26a5cb9 Orthanc 1.9.7
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 741
diff changeset
117 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.9.7/OrthancServer/Plugins/Samples/Common/OrthancPluginException.h>`__