Mercurial > hg > orthanc-book
annotate Sphinx/source/developers/creating-plugins.rst @ 249:19dd28b3a541
note about c++ plugins
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Fri, 07 Jun 2019 08:51:27 +0200 |
parents | a3050705d836 |
children | 540c2884cdf4 |
rev | line source |
---|---|
38 | 1 .. _creating-plugins: |
2 | |
24 | 3 Creating new plugins |
4 ==================== | |
5 | |
56 | 6 The recommended way of :ref:`contributing to the Orthanc code |
7 <contributing>` consists in extending it by creating new :ref:`plugins | |
8 <plugins>`. | |
24 | 9 |
10 Overview | |
11 -------- | |
12 | |
13 Orthanc plugins must use the `plugin SDK | |
66 | 14 <http://sdk.orthanc-server.com/>`__ and must be written |
24 | 15 in C or C++. They must also fullfil the terms of the `GPLv3 license |
16 <http://www.gnu.org/licenses/quick-guide-gplv3.en.html>`__ that is | |
17 used by the core of Orthanc. Sample code for plugins can be found `in | |
18 the official Orthanc repository | |
19 <https://bitbucket.org/sjodogne/orthanc/src/default/Plugins/Samples/>`__ | |
61 | 20 (in the ``Plugins/Samples`` folder). A |
24 | 21 tutorial showing how to implement a basic WADO server is `available on |
22 CodeProject | |
25 | 23 <http://www.codeproject.com/Articles/797118/Implementing-a-WADO-Server-using-Orthanc>`__. |
24 | |
25 We suggest developers to adopt the :ref:`coding style of the Orthanc | |
26 core <coding-style>`, although this is of course not required. | |
27 | |
28 Do not hesitate to `contact us | |
29 <http://www.orthanc-server.com/static.php?page=contact>`__ if you wish | |
66 | 30 your plugin to be **indexed** in :ref:`the dedicated part of the |
31 Orthanc Book <plugins-contributed>`! | |
25 | 32 |
249
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
33 **Note for C++ developers**: Convenience C++ wrappers around the plain |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
34 C API are available in the source Orthanc distribution. The following |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
35 three files can be used in your projects, and only depend on `Boost |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
36 <https://www.boost.org/>`__ and `JsonCpp |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
37 <https://github.com/open-source-parsers/jsoncpp>`__ if macro |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
38 ``HAS_ORTHANC_EXCEPTION`` is set to ``0``: |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
39 |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
40 * `Plugins/Samples/Common/OrthanPluginCppWrapper.h |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
41 <https://bitbucket.org/sjodogne/orthanc/src/default/Plugins/Samples/Common/OrthancPluginCppWrapper.h>`__ |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
42 * `Plugins/Samples/Common/OrthanPluginCppWrapper.cpp |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
43 <https://bitbucket.org/sjodogne/orthanc/src/default/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp>`__ |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
44 * `Plugins/Samples/Common/OrthanPluginException.h |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
45 <https://bitbucket.org/sjodogne/orthanc/src/default/Plugins/Samples/Common/OrthancPluginException.h>`__ |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
46 |
19dd28b3a541
note about c++ plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
67
diff
changeset
|
47 |
25 | 48 |
49 Structure of the plugins | |
50 ------------------------ | |
24 | 51 |
52 A plugin takes the form of a shared library (``.DLL`` under Windows, | |
67 | 53 ``.so`` under GNU/Linux, ``.dylib`` under Apple OS X...) that uses the |
42 | 54 `ABI of the C language |
25 | 55 <https://en.wikipedia.org/wiki/Application_binary_interface>`__ to |
56 declare 4 public functions/symbols: | |
24 | 57 |
58 * ``int32_t OrthancPluginInitialize(OrthancPluginContext* context)``. This | |
59 callback function is responsible for initializing the plugin. The | |
60 ``context`` argument gives access to the API of Orthanc. | |
61 * ``void OrthancPluginFinalize()``. This function is responsible | |
62 for finalizing the plugin, releasing all the allocated resources. | |
63 * ``const char* OrthancPluginGetName()``. This function must give a | |
64 name to the plugin. | |
65 * ``const char* OrthancPluginGetVersion()``. This function must | |
66 provide the version of the plugin. | |
67 | |
25 | 68 *Remark:* The size of the memory buffers that are exchanged between |
69 the Orthanc core and the plugins must be below 4GB. This is a | |
70 consequence of the fact that the Orthanc plugin SDK uses ``uint32_t`` | |
71 to encode the size of a memory buffer. We might extend the SDK in | |
72 the future to deal with buffers whose size if above 4GB. |