Mercurial > hg > orthanc-book
annotate Sphinx/source/developers/creating-plugins.rst @ 599:1248dadca1cd
updated mercurial fingerprints
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Thu, 21 Jan 2021 08:42:20 +0100 |
| parents | 090cc988c35e |
| children | eaa6cdfa7ba6 |
| 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 |
| 15 Orthanc plugins must use the `plugin SDK | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
16 <https://sdk.orthanc-server.com/>`__ and must be written in C or |
|
300
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
17 C++. They must also fullfil the terms of the `GPLv3 license |
| 24 | 18 <http://www.gnu.org/licenses/quick-guide-gplv3.en.html>`__ that is |
|
364
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
19 used by the core of Orthanc. |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
20 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
21 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
|
22 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
|
23 :ref:`dedicated Python plugin <python-plugin>`. |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
24 |
|
234de55ed125
usage of the python plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
360
diff
changeset
|
25 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
|
26 |
|
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
27 * 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
|
28 repository |
| 449 | 29 <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
|
30 (in the ``Plugins/Samples`` folder). |
| 25 | 31 |
|
300
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
32 * 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
|
33 `available on CodeProject |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
34 <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
|
35 |
|
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
36 * Marco Barnig provides `tutorial lessons to create Orthanc plugins |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
37 <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
|
38 as part of his `RadioLogic project |
|
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
39 <https://github.com/mbarnig/RadioLogic/>`__. |
| 408 | 40 |
| 41 * Technical workshop about "`Writing an Orthanc C++ plugin | |
| 42 <https://bitbucket.org/bgo-osimis/orcon19-plugin-workshop/>`__" | |
| 43 presented by Benjamin Golinvaux at `OrthancCon 2019 | |
| 44 <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
|
45 |
| 25 | 46 We suggest developers to adopt the :ref:`coding style of the Orthanc |
| 47 core <coding-style>`, although this is of course not required. | |
| 48 | |
| 49 Do not hesitate to `contact us | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
50 <https://www.orthanc-server.com/static.php?page=contact>`__ if you wish |
| 66 | 51 your plugin to be **indexed** in :ref:`the dedicated part of the |
| 52 Orthanc Book <plugins-contributed>`! | |
| 25 | 53 |
| 54 Structure of the plugins | |
| 55 ------------------------ | |
| 24 | 56 |
| 57 A plugin takes the form of a shared library (``.DLL`` under Windows, | |
| 67 | 58 ``.so`` under GNU/Linux, ``.dylib`` under Apple OS X...) that uses the |
| 42 | 59 `ABI of the C language |
| 25 | 60 <https://en.wikipedia.org/wiki/Application_binary_interface>`__ to |
| 61 declare 4 public functions/symbols: | |
| 24 | 62 |
| 63 * ``int32_t OrthancPluginInitialize(OrthancPluginContext* context)``. This | |
| 64 callback function is responsible for initializing the plugin. The | |
| 65 ``context`` argument gives access to the API of Orthanc. | |
| 66 * ``void OrthancPluginFinalize()``. This function is responsible | |
| 67 for finalizing the plugin, releasing all the allocated resources. | |
| 68 * ``const char* OrthancPluginGetName()``. This function must give a | |
| 69 name to the plugin. | |
| 70 * ``const char* OrthancPluginGetVersion()``. This function must | |
| 71 provide the version of the plugin. | |
| 72 | |
| 25 | 73 *Remark:* The size of the memory buffers that are exchanged between |
| 74 the Orthanc core and the plugins must be below 4GB. This is a | |
| 75 consequence of the fact that the Orthanc plugin SDK uses ``uint32_t`` | |
| 76 to encode the size of a memory buffer. We might extend the SDK in | |
| 250 | 77 the future to deal with buffers whose size is above 4GB. |
| 78 | |
| 79 Plugin SDK | |
| 80 ---------- | |
| 81 | |
| 82 Any plugin project should include the **official C header** file | |
| 83 that is part of the Orthanc source distribution: | |
| 84 | |
| 85 * `Plugins/Include/orthanc/OrthancCPlugin.h | |
| 568 | 86 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.8.2/OrthancServer/Plugins/Include/orthanc/OrthancCPlugin.h>`__ |
| 250 | 87 |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
336
diff
changeset
|
88 `Online documentation <https://sdk.orthanc-server.com/>`__ for this C |
| 250 | 89 header is available, as generated by `Doxygen |
| 90 <https://en.wikipedia.org/wiki/Doxygen>`__. | |
| 91 | |
| 92 **Convenience C++ wrappers** around the plain C API are available in | |
| 93 the Orthanc source distribution. The following three files can be used | |
| 94 in your projects, and only depend on `Boost | |
| 95 <https://www.boost.org/>`__ and `JsonCpp | |
| 96 <https://github.com/open-source-parsers/jsoncpp>`__ if macro | |
| 97 ``HAS_ORTHANC_EXCEPTION`` is set to ``0``: | |
| 98 | |
| 99 * `Plugins/Samples/Common/OrthanPluginCppWrapper.h | |
| 568 | 100 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.8.2/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.h>`__ |
| 250 | 101 * `Plugins/Samples/Common/OrthanPluginCppWrapper.cpp |
| 568 | 102 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.8.2/OrthancServer/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp>`__ |
| 250 | 103 * `Plugins/Samples/Common/OrthanPluginException.h |
| 568 | 104 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.8.2/OrthancServer/Plugins/Samples/Common/OrthancPluginException.h>`__ |