annotate Sphinx/source/developers/creating-plugins.rst @ 67:a3050705d836

typo
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 23 Nov 2016 09:13:47 +0100
parents cb712e9d9187
children 19dd28b3a541
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
38
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
1 .. _creating-plugins:
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
2
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3 Creating new plugins
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 ====================
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5
56
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
6 The recommended way of :ref:`contributing to the Orthanc code
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
7 <contributing>` consists in extending it by creating new :ref:`plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
8 <plugins>`.
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 Overview
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11 --------
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
13 Orthanc plugins must use the `plugin SDK
66
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 61
diff changeset
14 <http://sdk.orthanc-server.com/>`__ and must be written
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15 in C or C++. They must also fullfil the terms of the `GPLv3 license
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
16 <http://www.gnu.org/licenses/quick-guide-gplv3.en.html>`__ that is
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17 used by the core of Orthanc. Sample code for plugins can be found `in
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18 the official Orthanc repository
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19 <https://bitbucket.org/sjodogne/orthanc/src/default/Plugins/Samples/>`__
61
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 56
diff changeset
20 (in the ``Plugins/Samples`` folder). A
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
21 tutorial showing how to implement a basic WADO server is `available on
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
22 CodeProject
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
23 <http://www.codeproject.com/Articles/797118/Implementing-a-WADO-Server-using-Orthanc>`__.
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
24
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
25 We suggest developers to adopt the :ref:`coding style of the Orthanc
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
26 core <coding-style>`, although this is of course not required.
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
27
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
28 Do not hesitate to `contact us
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
29 <http://www.orthanc-server.com/static.php?page=contact>`__ if you wish
66
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 61
diff changeset
30 your plugin to be **indexed** in :ref:`the dedicated part of the
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 61
diff changeset
31 Orthanc Book <plugins-contributed>`!
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
32
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
33
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
34 Structure of the plugins
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
35 ------------------------
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
36
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
37 A plugin takes the form of a shared library (``.DLL`` under Windows,
67
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 66
diff changeset
38 ``.so`` under GNU/Linux, ``.dylib`` under Apple OS X...) that uses the
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 38
diff changeset
39 `ABI of the C language
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
40 <https://en.wikipedia.org/wiki/Application_binary_interface>`__ to
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
41 declare 4 public functions/symbols:
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
42
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
43 * ``int32_t OrthancPluginInitialize(OrthancPluginContext* context)``. This
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
44 callback function is responsible for initializing the plugin. The
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
45 ``context`` argument gives access to the API of Orthanc.
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
46 * ``void OrthancPluginFinalize()``. This function is responsible
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
47 for finalizing the plugin, releasing all the allocated resources.
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
48 * ``const char* OrthancPluginGetName()``. This function must give a
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49 name to the plugin.
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50 * ``const char* OrthancPluginGetVersion()``. This function must
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51 provide the version of the plugin.
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
53 *Remark:* The size of the memory buffers that are exchanged between
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
54 the Orthanc core and the plugins must be below 4GB. This is a
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
55 consequence of the fact that the Orthanc plugin SDK uses ``uint32_t``
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
56 to encode the size of a memory buffer. We might extend the SDK in
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
57 the future to deal with buffers whose size if above 4GB.