Mercurial > hg > orthanc-book
annotate Sphinx/source/developers/creating-plugins.rst @ 336:a5f7fc9fb611
Orthanc 1.6.0
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Wed, 18 Mar 2020 15:15:39 +0100 |
parents | 22d567933381 |
children | 011b01ccf52d |
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 | |
300
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
16 <http://sdk.orthanc-server.com/>`__ and must be written in C or |
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 |
300
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
19 used by the core of Orthanc. Here are some resources about creating |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
20 plugins: |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
21 |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
22 * 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
|
23 repository |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
24 <https://bitbucket.org/sjodogne/orthanc/src/default/Plugins/Samples/>`__ |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
25 (in the ``Plugins/Samples`` folder). |
25 | 26 |
300
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
27 * 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
|
28 `available on CodeProject |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
29 <http://www.codeproject.com/Articles/797118/Implementing-a-WADO-Server-using-Orthanc>`__. |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
30 |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
31 * Marco Barnig provides `tutorial lessons to create Orthanc plugins |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
32 <https://github.com/mbarnig/RadioLogic/wiki#orthanc-plugin-development>`__ |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
33 as part of his `RadioLogic project |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
34 <https://github.com/mbarnig/RadioLogic/>`__. |
22d567933381
tutorials about plugins by Marco Barnig
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
290
diff
changeset
|
35 |
25 | 36 We suggest developers to adopt the :ref:`coding style of the Orthanc |
37 core <coding-style>`, although this is of course not required. | |
38 | |
39 Do not hesitate to `contact us | |
40 <http://www.orthanc-server.com/static.php?page=contact>`__ if you wish | |
66 | 41 your plugin to be **indexed** in :ref:`the dedicated part of the |
42 Orthanc Book <plugins-contributed>`! | |
25 | 43 |
44 Structure of the plugins | |
45 ------------------------ | |
24 | 46 |
47 A plugin takes the form of a shared library (``.DLL`` under Windows, | |
67 | 48 ``.so`` under GNU/Linux, ``.dylib`` under Apple OS X...) that uses the |
42 | 49 `ABI of the C language |
25 | 50 <https://en.wikipedia.org/wiki/Application_binary_interface>`__ to |
51 declare 4 public functions/symbols: | |
24 | 52 |
53 * ``int32_t OrthancPluginInitialize(OrthancPluginContext* context)``. This | |
54 callback function is responsible for initializing the plugin. The | |
55 ``context`` argument gives access to the API of Orthanc. | |
56 * ``void OrthancPluginFinalize()``. This function is responsible | |
57 for finalizing the plugin, releasing all the allocated resources. | |
58 * ``const char* OrthancPluginGetName()``. This function must give a | |
59 name to the plugin. | |
60 * ``const char* OrthancPluginGetVersion()``. This function must | |
61 provide the version of the plugin. | |
62 | |
25 | 63 *Remark:* The size of the memory buffers that are exchanged between |
64 the Orthanc core and the plugins must be below 4GB. This is a | |
65 consequence of the fact that the Orthanc plugin SDK uses ``uint32_t`` | |
66 to encode the size of a memory buffer. We might extend the SDK in | |
250 | 67 the future to deal with buffers whose size is above 4GB. |
68 | |
69 Plugin SDK | |
70 ---------- | |
71 | |
72 Any plugin project should include the **official C header** file | |
73 that is part of the Orthanc source distribution: | |
74 | |
75 * `Plugins/Include/orthanc/OrthancCPlugin.h | |
336 | 76 <https://bitbucket.org/sjodogne/orthanc/src/Orthanc-1.6.0/Plugins/Include/orthanc/OrthancCPlugin.h>`__ |
250 | 77 |
78 `Online documentation <http://sdk.orthanc-server.com/>`__ for this C | |
79 header is available, as generated by `Doxygen | |
80 <https://en.wikipedia.org/wiki/Doxygen>`__. | |
81 | |
82 **Convenience C++ wrappers** around the plain C API are available in | |
83 the Orthanc source distribution. The following three files can be used | |
84 in your projects, and only depend on `Boost | |
85 <https://www.boost.org/>`__ and `JsonCpp | |
86 <https://github.com/open-source-parsers/jsoncpp>`__ if macro | |
87 ``HAS_ORTHANC_EXCEPTION`` is set to ``0``: | |
88 | |
89 * `Plugins/Samples/Common/OrthanPluginCppWrapper.h | |
336 | 90 <https://bitbucket.org/sjodogne/orthanc/src/Orthanc-1.6.0/Plugins/Samples/Common/OrthancPluginCppWrapper.h>`__ |
250 | 91 * `Plugins/Samples/Common/OrthanPluginCppWrapper.cpp |
336 | 92 <https://bitbucket.org/sjodogne/orthanc/src/Orthanc-1.6.0/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp>`__ |
250 | 93 * `Plugins/Samples/Common/OrthanPluginException.h |
336 | 94 <https://bitbucket.org/sjodogne/orthanc/src/Orthanc-1.6.0/Plugins/Samples/Common/OrthancPluginException.h>`__ |