Mercurial > hg > orthanc-book
annotate Sphinx/source/developers/creating-plugins.rst @ 1021:a3436ae3709c Orthanc-1.12.3
Orthanc 1.12.3
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Wed, 31 Jan 2024 14:01:54 +0100 |
parents | 56da617938f0 |
children | d2be251975d1 |
rev | line source |
---|---|
38 | 1 .. _creating-plugins: |
2 | |
24 | 3 Creating new plugins |
4 ==================== | |
5 | |
250 | 6 .. contents:: |
7 | |
8 Overview | |
9 -------- | |
10 | |
56 | 11 The recommended way of :ref:`contributing to the Orthanc code |
12 <contributing>` consists in extending it by creating new :ref:`plugins | |
13 <plugins>`. | |
24 | 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 |
993
05b106383b2a
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
991
diff
changeset
|
16 <https://orthanc.uclouvain.be/sdk/>`__ whose interface is available as a |
794
e22c1284ea0e
plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
763
diff
changeset
|
17 `C header |
1021 | 18 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.3/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__. |
794
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 |
999 | 26 For developers who are more familiar with Python or Java, it is also |
27 possible to create plugins using either of those simpler | |
28 languages. Check out the :ref:`dedicated Python plugin | |
29 <python-plugin>` or the :ref:`dedicated Java plugin <java-plugin>`. | |
364
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
30 |
794
e22c1284ea0e
plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
763
diff
changeset
|
31 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
|
32 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
|
33 under the `GPLv3 license |
e22c1284ea0e
plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
763
diff
changeset
|
34 <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
|
35 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
|
36 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
|
37 AGPL). |
e22c1284ea0e
plugins can be written in rust
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
763
diff
changeset
|
38 |
364
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
39 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
|
40 |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
41 * 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
|
42 repository |
991
1316bc62b5d5
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
963
diff
changeset
|
43 <https://orthanc.uclouvain.be/hg/orthanc/file/default/OrthancServer/Plugins/Samples/>`__ |
300
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
44 (in the ``Plugins/Samples`` folder). |
25 | 45 |
300
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
46 * 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
|
47 `available on CodeProject |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
48 <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
|
49 |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
50 * Marco Barnig provides `tutorial lessons to create Orthanc plugins |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
51 <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
|
52 as part of his `RadioLogic project |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
53 <https://github.com/mbarnig/RadioLogic/>`__. |
408 | 54 |
55 * Technical workshop about "`Writing an Orthanc C++ plugin | |
56 <https://bitbucket.org/bgo-osimis/orcon19-plugin-workshop/>`__" | |
57 presented by Benjamin Golinvaux at `OrthancCon 2019 | |
58 <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
|
59 |
25 | 60 We suggest developers to adopt the :ref:`coding style of the Orthanc |
61 core <coding-style>`, although this is of course not required. | |
62 | |
63 Do not hesitate to `contact us | |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
64 <https://www.orthanc-server.com/static.php?page=contact>`__ if you wish |
66 | 65 your plugin to be **indexed** in :ref:`the dedicated part of the |
66 Orthanc Book <plugins-contributed>`! | |
25 | 67 |
68 Structure of the plugins | |
69 ------------------------ | |
24 | 70 |
71 A plugin takes the form of a shared library (``.DLL`` under Windows, | |
67 | 72 ``.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
|
73 `FFI of the C language |
25 | 74 <https://en.wikipedia.org/wiki/Application_binary_interface>`__ to |
75 declare 4 public functions/symbols: | |
24 | 76 |
77 * ``int32_t OrthancPluginInitialize(OrthancPluginContext* context)``. This | |
78 callback function is responsible for initializing the plugin. The | |
79 ``context`` argument gives access to the API of Orthanc. | |
80 * ``void OrthancPluginFinalize()``. This function is responsible | |
81 for finalizing the plugin, releasing all the allocated resources. | |
82 * ``const char* OrthancPluginGetName()``. This function must give a | |
83 name to the plugin. | |
84 * ``const char* OrthancPluginGetVersion()``. This function must | |
85 provide the version of the plugin. | |
86 | |
25 | 87 *Remark:* The size of the memory buffers that are exchanged between |
88 the Orthanc core and the plugins must be below 4GB. This is a | |
89 consequence of the fact that the Orthanc plugin SDK uses ``uint32_t`` | |
90 to encode the size of a memory buffer. We might extend the SDK in | |
250 | 91 the future to deal with buffers whose size is above 4GB. |
92 | |
93 Plugin SDK | |
94 ---------- | |
95 | |
96 Any plugin project should include the **official C header** file | |
97 that is part of the Orthanc source distribution: | |
98 | |
99 * `Plugins/Include/orthanc/OrthancCPlugin.h | |
1021 | 100 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.3/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ |
250 | 101 |
993
05b106383b2a
migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
991
diff
changeset
|
102 `Online documentation <https://orthanc.uclouvain.be/sdk/>`__ for this C |
250 | 103 header is available, as generated by `Doxygen |
104 <https://en.wikipedia.org/wiki/Doxygen>`__. | |
105 | |
106 **Convenience C++ wrappers** around the plain C API are available in | |
107 the Orthanc source distribution. The following three files can be used | |
108 in your projects, and only depend on `Boost | |
109 <https://www.boost.org/>`__ and `JsonCpp | |
110 <https://github.com/open-source-parsers/jsoncpp>`__ if macro | |
111 ``HAS_ORTHANC_EXCEPTION`` is set to ``0``: | |
112 | |
113 * `Plugins/Samples/Common/OrthanPluginCppWrapper.h | |
1021 | 114 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.3/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.h>`__ |
250 | 115 * `Plugins/Samples/Common/OrthanPluginCppWrapper.cpp |
1021 | 116 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.3/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp>`__ |
250 | 117 * `Plugins/Samples/Common/OrthanPluginException.h |
1021 | 118 <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.3/OrthancServer/Plugins/Samples/Common/OrthancPluginException.h>`__ |