|
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
|
|
66
|
16 <http://sdk.orthanc-server.com/>`__ and must be written
|
|
24
|
17 in C or C++. They must also fullfil the terms of the `GPLv3 license
|
|
|
18 <http://www.gnu.org/licenses/quick-guide-gplv3.en.html>`__ that is
|
|
|
19 used by the core of Orthanc. Sample code for plugins can be found `in
|
|
|
20 the official Orthanc repository
|
|
|
21 <https://bitbucket.org/sjodogne/orthanc/src/default/Plugins/Samples/>`__
|
|
61
|
22 (in the ``Plugins/Samples`` folder). A
|
|
24
|
23 tutorial showing how to implement a basic WADO server is `available on
|
|
|
24 CodeProject
|
|
25
|
25 <http://www.codeproject.com/Articles/797118/Implementing-a-WADO-Server-using-Orthanc>`__.
|
|
|
26
|
|
|
27 We suggest developers to adopt the :ref:`coding style of the Orthanc
|
|
|
28 core <coding-style>`, although this is of course not required.
|
|
|
29
|
|
|
30 Do not hesitate to `contact us
|
|
|
31 <http://www.orthanc-server.com/static.php?page=contact>`__ if you wish
|
|
66
|
32 your plugin to be **indexed** in :ref:`the dedicated part of the
|
|
|
33 Orthanc Book <plugins-contributed>`!
|
|
25
|
34
|
|
|
35 Structure of the plugins
|
|
|
36 ------------------------
|
|
24
|
37
|
|
|
38 A plugin takes the form of a shared library (``.DLL`` under Windows,
|
|
67
|
39 ``.so`` under GNU/Linux, ``.dylib`` under Apple OS X...) that uses the
|
|
42
|
40 `ABI of the C language
|
|
25
|
41 <https://en.wikipedia.org/wiki/Application_binary_interface>`__ to
|
|
|
42 declare 4 public functions/symbols:
|
|
24
|
43
|
|
|
44 * ``int32_t OrthancPluginInitialize(OrthancPluginContext* context)``. This
|
|
|
45 callback function is responsible for initializing the plugin. The
|
|
|
46 ``context`` argument gives access to the API of Orthanc.
|
|
|
47 * ``void OrthancPluginFinalize()``. This function is responsible
|
|
|
48 for finalizing the plugin, releasing all the allocated resources.
|
|
|
49 * ``const char* OrthancPluginGetName()``. This function must give a
|
|
|
50 name to the plugin.
|
|
|
51 * ``const char* OrthancPluginGetVersion()``. This function must
|
|
|
52 provide the version of the plugin.
|
|
|
53
|
|
25
|
54 *Remark:* The size of the memory buffers that are exchanged between
|
|
|
55 the Orthanc core and the plugins must be below 4GB. This is a
|
|
|
56 consequence of the fact that the Orthanc plugin SDK uses ``uint32_t``
|
|
|
57 to encode the size of a memory buffer. We might extend the SDK in
|
|
250
|
58 the future to deal with buffers whose size is above 4GB.
|
|
|
59
|
|
|
60 Plugin SDK
|
|
|
61 ----------
|
|
|
62
|
|
|
63 Any plugin project should include the **official C header** file
|
|
|
64 that is part of the Orthanc source distribution:
|
|
|
65
|
|
|
66 * `Plugins/Include/orthanc/OrthancCPlugin.h
|
|
|
67 <https://bitbucket.org/sjodogne/orthanc/src/Orthanc-1.5.6/Plugins/Include/orthanc/OrthancCPlugin.h>`__
|
|
|
68
|
|
|
69 `Online documentation <http://sdk.orthanc-server.com/>`__ for this C
|
|
|
70 header is available, as generated by `Doxygen
|
|
|
71 <https://en.wikipedia.org/wiki/Doxygen>`__.
|
|
|
72
|
|
|
73 **Convenience C++ wrappers** around the plain C API are available in
|
|
|
74 the Orthanc source distribution. The following three files can be used
|
|
|
75 in your projects, and only depend on `Boost
|
|
|
76 <https://www.boost.org/>`__ and `JsonCpp
|
|
|
77 <https://github.com/open-source-parsers/jsoncpp>`__ if macro
|
|
|
78 ``HAS_ORTHANC_EXCEPTION`` is set to ``0``:
|
|
|
79
|
|
|
80 * `Plugins/Samples/Common/OrthanPluginCppWrapper.h
|
|
|
81 <https://bitbucket.org/sjodogne/orthanc/src/default/Plugins/Samples/Common/OrthancPluginCppWrapper.h>`__
|
|
|
82 * `Plugins/Samples/Common/OrthanPluginCppWrapper.cpp
|
|
|
83 <https://bitbucket.org/sjodogne/orthanc/src/default/Plugins/Samples/Common/OrthancPluginCppWrapper.cpp>`__
|
|
|
84 * `Plugins/Samples/Common/OrthanPluginException.h
|
|
|
85 <https://bitbucket.org/sjodogne/orthanc/src/default/Plugins/Samples/Common/OrthancPluginException.h>`__
|
