Mercurial > hg > orthanc

comparison Plugins/Include/OrthancCPlugin.h @ 1295:50632b89e294

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
reorganization
author Sebastien Jodogne <s.jodogne@gmail.com>
date Fri, 06 Feb 2015 14:09:55 +0100
parents Plugins/OrthancCPlugin/OrthancCPlugin.h@6e7e5ed91c2d
children 501432928727
comparison
equal deleted inserted replaced
1294:910478b2d4e4 1295:50632b89e294
1 /**
2 * \mainpage
3 *
4 * This C/C++ SDK allows external developers to create plugins that
5 * can be loaded into Orthanc to extend its functionality. Each
6 * Orthanc plugin must expose 4 public functions with the following
7 * signatures:
8 *
9 * -# <tt>int32_t OrthancPluginInitialize(const OrthancPluginContext* context)</tt>:
10 * This function is invoked by Orthanc when it loads the plugin on startup.
11 * The plugin must:
12 * - Check its compatibility with the Orthanc version using
13 * ::OrthancPluginCheckVersion().
14 * - Store the context pointer so that it can use the plugin
15 * services of Orthanc.
16 * - Register all its REST callbacks using ::OrthancPluginRegisterRestCallback().
17 * - Register all its callbacks for received instances using ::OrthancPluginRegisterOnStoredInstanceCallback().
18 * - Possibly register a custom storage area using ::OrthancPluginRegisterStorageArea().
19 * -# <tt>void OrthancPluginFinalize()</tt>:
20 * This function is invoked by Orthanc during its shutdown. The plugin
21 * must free all its memory.
22 * -# <tt>const char* OrthancPluginGetName()</tt>:
23 * The plugin must return a short string to identify itself.
24 * -# <tt>const char* OrthancPluginGetVersion()</tt>:
25 * The plugin must return a string containing its version number.
26 *
27 * The name and the version of a plugin is only used to prevent it
28 * from being loaded twice.
29 *
30 * The various callbacks are guaranteed to be executed in mutual
31 * exclusion since Orthanc 0.8.5.
32 **/
33
34
35
36 /**
37 * @defgroup CInterface C Interface
38 * @brief The C interface to create Orthanc plugins.
39 *
40 * These functions must be used to create C plugins for Orthanc.
41 **/
42
43
44
45 /**
46 * Orthanc - A Lightweight, RESTful DICOM Store
47 * Copyright (C) 2012-2015 Sebastien Jodogne, Medical Physics
48 * Department, University Hospital of Liege, Belgium
49 *
50 * This program is free software: you can redistribute it and/or
51 * modify it under the terms of the GNU General Public License as
52 * published by the Free Software Foundation, either version 3 of the
53 * License, or (at your option) any later version.
54 *
55 * In addition, as a special exception, the copyright holders of this
56 * program give permission to link the code of its release with the
57 * OpenSSL project's "OpenSSL" library (or with modified versions of it
58 * that use the same license as the "OpenSSL" library), and distribute
59 * the linked executables. You must obey the GNU General Public License
60 * in all respects for all of the code used other than "OpenSSL". If you
61 * modify file(s) with this exception, you may extend this exception to
62 * your version of the file(s), but you are not obligated to do so. If
63 * you do not wish to do so, delete this exception statement from your
64 * version. If you delete this exception statement from all source files
65 * in the program, then also delete it here.
66 *
67 * This program is distributed in the hope that it will be useful, but
68 * WITHOUT ANY WARRANTY; without even the implied warranty of
69 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
70 * General Public License for more details.
71 *
72 * You should have received a copy of the GNU General Public License
73 * along with this program. If not, see <http://www.gnu.org/licenses/>.
74 **/
75
76
77
78 #pragma once
79
80
81 #include <stdio.h>
82 #include <string.h>
83
84 #ifdef WIN32
85 #define ORTHANC_PLUGINS_API __declspec(dllexport)
86 #else
87 #define ORTHANC_PLUGINS_API
88 #endif
89
90 #define ORTHANC_PLUGINS_MINIMAL_MAJOR_NUMBER 0
91 #define ORTHANC_PLUGINS_MINIMAL_MINOR_NUMBER 8
92 #define ORTHANC_PLUGINS_MINIMAL_REVISION_NUMBER 6
93
94
95
96 /********************************************************************
97 ** Check that function inlining is properly supported. The use of
98 ** inlining is required, to avoid the duplication of object code
99 ** between two compilation modules that would use the Orthanc Plugin
100 ** API.
101 ********************************************************************/
102
103 /* If the auto-detection of the "inline" keyword below does not work
104 automatically and that your compiler is known to properly support
105 inlining, uncomment the following #define and adapt the definition
106 of "static inline". */
107
108 /* #define ORTHANC_PLUGIN_INLINE static inline */
109
110 #ifndef ORTHANC_PLUGIN_INLINE
111 # if __STDC_VERSION__ >= 199901L
112 /* This is C99 or above: http://predef.sourceforge.net/prestd.html */
113 # define ORTHANC_PLUGIN_INLINE static inline
114 # elif defined(__cplusplus)
115 /* This is C++ */
116 # define ORTHANC_PLUGIN_INLINE static inline
117 # elif defined(__GNUC__)
118 /* This is GCC running in C89 mode */
119 # define ORTHANC_PLUGIN_INLINE static __inline
120 # elif defined(_MSC_VER)
121 /* This is Visual Studio running in C89 mode */
122 # define ORTHANC_PLUGIN_INLINE static __inline
123 # else
124 # error Your compiler is not known to support the "inline" keyword
125 # endif
126 #endif
127
128
129
130 /********************************************************************
131 ** Inclusion of standard libraries.
132 ********************************************************************/
133
134 #ifdef _MSC_VER
135 #include "../../Resources/ThirdParty/VisualStudio/stdint.h"
136 #else
137 #include <stdint.h>
138 #endif
139
140 #include <stdlib.h>
141
142
143
144 /********************************************************************
145 ** Definition of the Orthanc Plugin API.
146 ********************************************************************/
147
148 /** @{ */
149
150 #ifdef __cplusplus
151 extern "C"
152 {
153 #endif
154
155 /**
156 * Forward declaration of one of the mandatory functions for Orthanc
157 * plugins.
158 **/
159 ORTHANC_PLUGINS_API const char* OrthancPluginGetName();
160
161
162 /**
163 * The various HTTP methods for a REST call.
164 **/
165 typedef enum
166 {
167 OrthancPluginHttpMethod_Get = 1, /*!< GET request */
168 OrthancPluginHttpMethod_Post = 2, /*!< POST request */
169 OrthancPluginHttpMethod_Put = 3, /*!< PUT request */
170 OrthancPluginHttpMethod_Delete = 4 /*!< DELETE request */
171 } OrthancPluginHttpMethod;
172
173
174 /**
175 * @brief The parameters of a REST request.
176 **/
177 typedef struct
178 {
179 /**
180 * @brief The HTTP method.
181 **/
182 OrthancPluginHttpMethod method;
183
184 /**
185 * @brief The number of groups of the regular expression.
186 **/
187 uint32_t groupsCount;
188
189 /**
190 * @brief The matched values for the groups of the regular expression.
191 **/
192 const char* const* groups;
193
194 /**
195 * @brief For a GET request, the number of GET parameters.
196 **/
197 uint32_t getCount;
198
199 /**
200 * @brief For a GET request, the keys of the GET parameters.
201 **/
202 const char* const* getKeys;
203
204 /**
205 * @brief For a GET request, the values of the GET parameters.
206 **/
207 const char* const* getValues;
208
209 /**
210 * @brief For a PUT or POST request, the content of the body.
211 **/
212 const char* body;
213
214 /**
215 * @brief For a PUT or POST request, the number of bytes of the body.
216 **/
217 uint32_t bodySize;
218
219
220 /* --------------------------------------------------
221 New in version 0.8.1
222 -------------------------------------------------- */
223
224 /**
225 * @brief The number of HTTP headers.
226 **/
227 uint32_t headersCount;
228
229 /**
230 * @brief The keys of the HTTP headers (always converted to low-case).
231 **/
232 const char* const* headersKeys;
233
234 /**
235 * @brief The values of the HTTP headers.
236 **/
237 const char* const* headersValues;
238
239 } OrthancPluginHttpRequest;
240
241
242 typedef enum
243 {
244 /* Generic services */
245 _OrthancPluginService_LogInfo = 1,
246 _OrthancPluginService_LogWarning = 2,
247 _OrthancPluginService_LogError = 3,
248 _OrthancPluginService_GetOrthancPath = 4,
249 _OrthancPluginService_GetOrthancDirectory = 5,
250 _OrthancPluginService_GetConfigurationPath = 6,
251 _OrthancPluginService_SetPluginProperty = 7,
252 _OrthancPluginService_GetGlobalProperty = 8,
253 _OrthancPluginService_SetGlobalProperty = 9,
254 _OrthancPluginService_GetCommandLineArgumentsCount = 10,
255 _OrthancPluginService_GetCommandLineArgument = 11,
256
257 /* Registration of callbacks */
258 _OrthancPluginService_RegisterRestCallback = 1000,
259 _OrthancPluginService_RegisterOnStoredInstanceCallback = 1001,
260 _OrthancPluginService_RegisterStorageArea = 1002,
261 _OrthancPluginService_RegisterOnChangeCallback = 1003,
262
263 /* Sending answers to REST calls */
264 _OrthancPluginService_AnswerBuffer = 2000,
265 _OrthancPluginService_CompressAndAnswerPngImage = 2001,
266 _OrthancPluginService_Redirect = 2002,
267 _OrthancPluginService_SendHttpStatusCode = 2003,
268 _OrthancPluginService_SendUnauthorized = 2004,
269 _OrthancPluginService_SendMethodNotAllowed = 2005,
270 _OrthancPluginService_SetCookie = 2006,
271 _OrthancPluginService_SetHttpHeader = 2007,
272
273 /* Access to the Orthanc database and API */
274 _OrthancPluginService_GetDicomForInstance = 3000,
275 _OrthancPluginService_RestApiGet = 3001,
276 _OrthancPluginService_RestApiPost = 3002,
277 _OrthancPluginService_RestApiDelete = 3003,
278 _OrthancPluginService_RestApiPut = 3004,
279 _OrthancPluginService_LookupPatient = 3005,
280 _OrthancPluginService_LookupStudy = 3006,
281 _OrthancPluginService_LookupSeries = 3007,
282 _OrthancPluginService_LookupInstance = 3008,
283 _OrthancPluginService_LookupStudyWithAccessionNumber = 3009,
284 _OrthancPluginService_RestApiGetAfterPlugins = 3010,
285 _OrthancPluginService_RestApiPostAfterPlugins = 3011,
286 _OrthancPluginService_RestApiDeleteAfterPlugins = 3012,
287 _OrthancPluginService_RestApiPutAfterPlugins = 3013,
288
289 /* Access to DICOM instances */
290 _OrthancPluginService_GetInstanceRemoteAet = 4000,
291 _OrthancPluginService_GetInstanceSize = 4001,
292 _OrthancPluginService_GetInstanceData = 4002,
293 _OrthancPluginService_GetInstanceJson = 4003,
294 _OrthancPluginService_GetInstanceSimplifiedJson = 4004,
295 _OrthancPluginService_HasInstanceMetadata = 4005,
296 _OrthancPluginService_GetInstanceMetadata = 4006
297 } _OrthancPluginService;
298
299
300 typedef enum
301 {
302 _OrthancPluginProperty_Description = 1,
303 _OrthancPluginProperty_RootUri = 2,
304 _OrthancPluginProperty_OrthancExplorer = 3
305 } _OrthancPluginProperty;
306
307
308
309 /**
310 * The memory layout of the pixels of an image.
311 **/
312 typedef enum
313 {
314 /**
315 * @brief Graylevel 8bpp image.
316 *
317 * The image is graylevel. Each pixel is unsigned and stored in
318 * one byte.
319 **/
320 OrthancPluginPixelFormat_Grayscale8 = 1,
321
322 /**
323 * @brief Graylevel, unsigned 16bpp image.
324 *
325 * The image is graylevel. Each pixel is unsigned and stored in
326 * two bytes.
327 **/
328 OrthancPluginPixelFormat_Grayscale16 = 2,
329
330 /**
331 * @brief Graylevel, signed 16bpp image.
332 *
333 * The image is graylevel. Each pixel is signed and stored in two
334 * bytes.
335 **/
336 OrthancPluginPixelFormat_SignedGrayscale16 = 3,
337
338 /**
339 * @brief Color image in RGB24 format.
340 *
341 * This format describes a color image. The pixels are stored in 3
342 * consecutive bytes. The memory layout is RGB.
343 **/
344 OrthancPluginPixelFormat_RGB24 = 4,
345
346 /**
347 * @brief Color image in RGBA32 format.
348 *
349 * This format describes a color image. The pixels are stored in 4
350 * consecutive bytes. The memory layout is RGBA.
351 **/
352 OrthancPluginPixelFormat_RGBA32 = 5
353 } OrthancPluginPixelFormat;
354
355
356
357 /**
358 * The content types that are supported by Orthanc plugins.
359 **/
360 typedef enum
361 {
362 OrthancPluginContentType_Unknown = 0, /*!< Unknown content type */
363 OrthancPluginContentType_Dicom = 1, /*!< DICOM */
364 OrthancPluginContentType_DicomAsJson = 2 /*!< JSON summary of a DICOM file */
365 } OrthancPluginContentType;
366
367
368
369 /**
370 * The supported type of DICOM resources.
371 **/
372 typedef enum
373 {
374 OrthancPluginResourceType_Patient = 0, /*!< Patient */
375 OrthancPluginResourceType_Study = 1, /*!< Study */
376 OrthancPluginResourceType_Series = 2, /*!< Series */
377 OrthancPluginResourceType_Instance = 3 /*!< Instance */
378 } OrthancPluginResourceType;
379
380
381
382 /**
383 * The supported type of changes that can happen to DICOM resources.
384 **/
385 typedef enum
386 {
387 OrthancPluginChangeType_CompletedSeries = 0, /*!< Series is now complete */
388 OrthancPluginChangeType_Deleted = 1, /*!< Deleted resource */
389 OrthancPluginChangeType_NewChildInstance = 2, /*!< A new instance was added to this resource */
390 OrthancPluginChangeType_NewInstance = 3, /*!< New instance received */
391 OrthancPluginChangeType_NewPatient = 4, /*!< New patient created */
392 OrthancPluginChangeType_NewSeries = 5, /*!< New series created */
393 OrthancPluginChangeType_NewStudy = 6, /*!< New study created */
394 OrthancPluginChangeType_StablePatient = 7, /*!< Timeout: No new instance in this patient */
395 OrthancPluginChangeType_StableSeries = 8, /*!< Timeout: No new instance in this series */
396 OrthancPluginChangeType_StableStudy = 9 /*!< Timeout: No new instance in this study */
397 } OrthancPluginChangeType;
398
399
400
401 /**
402 * @brief A memory buffer allocated by the core system of Orthanc.
403 *
404 * A memory buffer allocated by the core system of Orthanc. When the
405 * content of the buffer is not useful anymore, it must be free by a
406 * call to ::OrthancPluginFreeMemoryBuffer().
407 **/
408 typedef struct
409 {
410 /**
411 * @brief The content of the buffer.
412 **/
413 void* data;
414
415 /**
416 * @brief The number of bytes in the buffer.
417 **/
418 uint32_t size;
419 } OrthancPluginMemoryBuffer;
420
421
422
423
424 /**
425 * @brief Opaque structure that represents the HTTP connection to the client application.
426 **/
427 typedef struct _OrthancPluginRestOutput_t OrthancPluginRestOutput;
428
429
430
431 /**
432 * @brief Opaque structure that represents a DICOM instance received by Orthanc.
433 **/
434 typedef struct _OrthancPluginDicomInstance_t OrthancPluginDicomInstance;
435
436
437
438 /**
439 * @brief Signature of a callback function that answers to a REST request.
440 **/
441 typedef int32_t (*OrthancPluginRestCallback) (
442 OrthancPluginRestOutput* output,
443 const char* url,
444 const OrthancPluginHttpRequest* request);
445
446
447
448 /**
449 * @brief Signature of a callback function that is triggered when Orthanc receives a DICOM instance.
450 **/
451 typedef int32_t (*OrthancPluginOnStoredInstanceCallback) (
452 OrthancPluginDicomInstance* instance,
453 const char* instanceId);
454
455
456
457 /**
458 * @brief Signature of a callback function that is triggered when a change happens to some DICOM resource.
459 **/
460 typedef int32_t (*OrthancPluginOnChangeCallback) (
461 OrthancPluginChangeType changeType,
462 OrthancPluginResourceType resourceType,
463 const char* resourceId);
464
465
466
467 /**
468 * @brief Signature of a function to free dynamic memory.
469 **/
470 typedef void (*OrthancPluginFree) (void* buffer);
471
472
473
474 /**
475 * @brief Callback for writing to the storage area.
476 *
477 * Signature of a callback function that is triggered when Orthanc writes a file to the storage area.
478 *
479 * @param uuid The UUID of the file.
480 * @param content The content of the file.
481 * @param size The size of the file.
482 * @param type The content type corresponding to this file.
483 * @return 0 if success, other value if error.
484 **/
485 typedef int32_t (*OrthancPluginStorageCreate) (
486 const char* uuid,
487 const void* content,
488 int64_t size,
489 OrthancPluginContentType type);
490
491
492
493 /**
494 * @brief Callback for reading from the storage area.
495 *
496 * Signature of a callback function that is triggered when Orthanc reads a file from the storage area.
497 *
498 * @param content The content of the file (output).
499 * @param size The size of the file (output).
500 * @param uuid The UUID of the file of interest.
501 * @param type The content type corresponding to this file.
502 * @return 0 if success, other value if error.
503 **/
504 typedef int32_t (*OrthancPluginStorageRead) (
505 void** content,
506 int64_t* size,
507 const char* uuid,
508 OrthancPluginContentType type);
509
510
511
512 /**
513 * @brief Callback for removing a file from the storage area.
514 *
515 * Signature of a callback function that is triggered when Orthanc deletes a file from the storage area.
516 *
517 * @param uuid The UUID of the file to be removed.
518 * @param type The content type corresponding to this file.
519 * @return 0 if success, other value if error.
520 **/
521 typedef int32_t (*OrthancPluginStorageRemove) (
522 const char* uuid,
523 OrthancPluginContentType type);
524
525
526
527 /**
528 * @brief Opaque structure that contains information about the Orthanc core.
529 **/
530 typedef struct _OrthancPluginContext_t
531 {
532 void* pluginsManager;
533 const char* orthancVersion;
534 OrthancPluginFree Free;
535 int32_t (*InvokeService) (struct _OrthancPluginContext_t* context,
536 _OrthancPluginService service,
537 const void* params);
538 } OrthancPluginContext;
539
540
541
542 /**
543 * @brief Free a string.
544 *
545 * Free a string that was allocated by the core system of Orthanc.
546 *
547 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
548 * @param str The string to be freed.
549 **/
550 ORTHANC_PLUGIN_INLINE void OrthancPluginFreeString(
551 OrthancPluginContext* context,
552 char* str)
553 {
554 if (str != NULL)
555 {
556 context->Free(str);
557 }
558 }
559
560
561 /**
562 * @brief Check the compatibility of the plugin wrt. the version of its hosting Orthanc.
563 *
564 * This function checks whether the version of this C header is
565 * compatible with the current version of Orthanc. The result of
566 * this function should always be checked in the
567 * OrthancPluginInitialize() entry point of the plugin.
568 *
569 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
570 * @return 1 if and only if the versions are compatible. If the
571 * result is 0, the initialization of the plugin should fail.
572 **/
573 ORTHANC_PLUGIN_INLINE int OrthancPluginCheckVersion(
574 OrthancPluginContext* context)
575 {
576 int major, minor, revision;
577
578 /* Assume compatibility with the mainline */
579 if (!strcmp(context->orthancVersion, "mainline"))
580 {
581 return 1;
582 }
583
584 /* Parse the version of the Orthanc core */
585 if (
586 #ifdef _MSC_VER
587 sscanf_s
588 #else
589 sscanf
590 #endif
591 (context->orthancVersion, "%d.%d.%d", &major, &minor, &revision) != 3)
592 {
593 return 0;
594 }
595
596 /* Check the major number of the version */
597
598 if (major > ORTHANC_PLUGINS_MINIMAL_MAJOR_NUMBER)
599 {
600 return 1;
601 }
602
603 if (major < ORTHANC_PLUGINS_MINIMAL_MAJOR_NUMBER)
604 {
605 return 0;
606 }
607
608 /* Check the minor number of the version */
609
610 if (minor > ORTHANC_PLUGINS_MINIMAL_MINOR_NUMBER)
611 {
612 return 1;
613 }
614
615 if (minor < ORTHANC_PLUGINS_MINIMAL_MINOR_NUMBER)
616 {
617 return 0;
618 }
619
620 /* Check the revision number of the version */
621
622 if (revision >= ORTHANC_PLUGINS_MINIMAL_REVISION_NUMBER)
623 {
624 return 1;
625 }
626 else
627 {
628 return 0;
629 }
630 }
631
632
633 /**
634 * @brief Free a memory buffer.
635 *
636 * Free a memory buffer that was allocated by the core system of Orthanc.
637 *
638 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
639 * @param buffer The memory buffer to release.
640 **/
641 ORTHANC_PLUGIN_INLINE void OrthancPluginFreeMemoryBuffer(
642 OrthancPluginContext* context,
643 OrthancPluginMemoryBuffer* buffer)
644 {
645 context->Free(buffer->data);
646 }
647
648
649 /**
650 * @brief Log an error.
651 *
652 * Log an error message using the Orthanc logging system.
653 *
654 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
655 * @param message The message to be logged.
656 **/
657 ORTHANC_PLUGIN_INLINE void OrthancPluginLogError(
658 OrthancPluginContext* context,
659 const char* message)
660 {
661 context->InvokeService(context, _OrthancPluginService_LogError, message);
662 }
663
664
665 /**
666 * @brief Log a warning.
667 *
668 * Log a warning message using the Orthanc logging system.
669 *
670 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
671 * @param message The message to be logged.
672 **/
673 ORTHANC_PLUGIN_INLINE void OrthancPluginLogWarning(
674 OrthancPluginContext* context,
675 const char* message)
676 {
677 context->InvokeService(context, _OrthancPluginService_LogWarning, message);
678 }
679
680
681 /**
682 * @brief Log an information.
683 *
684 * Log an information message using the Orthanc logging system.
685 *
686 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
687 * @param message The message to be logged.
688 **/
689 ORTHANC_PLUGIN_INLINE void OrthancPluginLogInfo(
690 OrthancPluginContext* context,
691 const char* message)
692 {
693 context->InvokeService(context, _OrthancPluginService_LogInfo, message);
694 }
695
696
697
698 typedef struct
699 {
700 const char* pathRegularExpression;
701 OrthancPluginRestCallback callback;
702 } _OrthancPluginRestCallback;
703
704 /**
705 * @brief Register a REST callback.
706 *
707 * This function registers a REST callback against a regular
708 * expression for a URI. This function must be called during the
709 * initialization of the plugin, i.e. inside the
710 * OrthancPluginInitialize() public function.
711 *
712 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
713 * @param pathRegularExpression Regular expression for the URI. May contain groups.
714 * @param callback The callback function to handle the REST call.
715 **/
716 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterRestCallback(
717 OrthancPluginContext* context,
718 const char* pathRegularExpression,
719 OrthancPluginRestCallback callback)
720 {
721 _OrthancPluginRestCallback params;
722 params.pathRegularExpression = pathRegularExpression;
723 params.callback = callback;
724 context->InvokeService(context, _OrthancPluginService_RegisterRestCallback, &params);
725 }
726
727
728
729 typedef struct
730 {
731 OrthancPluginOnStoredInstanceCallback callback;
732 } _OrthancPluginOnStoredInstanceCallback;
733
734 /**
735 * @brief Register a callback for received instances.
736 *
737 * This function registers a callback function that is called
738 * whenever a new DICOM instance is stored into the Orthanc core.
739 *
740 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
741 * @param callback The callback function.
742 **/
743 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterOnStoredInstanceCallback(
744 OrthancPluginContext* context,
745 OrthancPluginOnStoredInstanceCallback callback)
746 {
747 _OrthancPluginOnStoredInstanceCallback params;
748 params.callback = callback;
749
750 context->InvokeService(context, _OrthancPluginService_RegisterOnStoredInstanceCallback, &params);
751 }
752
753
754
755 typedef struct
756 {
757 OrthancPluginRestOutput* output;
758 const char* answer;
759 uint32_t answerSize;
760 const char* mimeType;
761 } _OrthancPluginAnswerBuffer;
762
763 /**
764 * @brief Answer to a REST request.
765 *
766 * This function answers to a REST request with the content of a memory buffer.
767 *
768 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
769 * @param output The HTTP connection to the client application.
770 * @param answer Pointer to the memory buffer containing the answer.
771 * @param answerSize Number of bytes of the answer.
772 * @param mimeType The MIME type of the answer.
773 **/
774 ORTHANC_PLUGIN_INLINE void OrthancPluginAnswerBuffer(
775 OrthancPluginContext* context,
776 OrthancPluginRestOutput* output,
777 const char* answer,
778 uint32_t answerSize,
779 const char* mimeType)
780 {
781 _OrthancPluginAnswerBuffer params;
782 params.output = output;
783 params.answer = answer;
784 params.answerSize = answerSize;
785 params.mimeType = mimeType;
786 context->InvokeService(context, _OrthancPluginService_AnswerBuffer, &params);
787 }
788
789
790 typedef struct
791 {
792 OrthancPluginRestOutput* output;
793 OrthancPluginPixelFormat format;
794 uint32_t width;
795 uint32_t height;
796 uint32_t pitch;
797 const void* buffer;
798 } _OrthancPluginCompressAndAnswerPngImage;
799
800 /**
801 * @brief Answer to a REST request with a PNG image.
802 *
803 * This function answers to a REST request with a PNG image. The
804 * parameters of this function describe a memory buffer that
805 * contains an uncompressed image. The image will be automatically compressed
806 * as a PNG image by the core system of Orthanc.
807 *
808 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
809 * @param output The HTTP connection to the client application.
810 * @param format The memory layout of the uncompressed image.
811 * @param width The width of the image.
812 * @param height The height of the image.
813 * @param pitch The pitch of the image (i.e. the number of bytes
814 * between 2 successive lines of the image in the memory buffer.
815 * @param buffer The memory buffer containing the uncompressed image.
816 **/
817 ORTHANC_PLUGIN_INLINE void OrthancPluginCompressAndAnswerPngImage(
818 OrthancPluginContext* context,
819 OrthancPluginRestOutput* output,
820 OrthancPluginPixelFormat format,
821 uint32_t width,
822 uint32_t height,
823 uint32_t pitch,
824 const void* buffer)
825 {
826 _OrthancPluginCompressAndAnswerPngImage params;
827 params.output = output;
828 params.format = format;
829 params.width = width;
830 params.height = height;
831 params.pitch = pitch;
832 params.buffer = buffer;
833 context->InvokeService(context, _OrthancPluginService_CompressAndAnswerPngImage, &params);
834 }
835
836
837
838 typedef struct
839 {
840 OrthancPluginMemoryBuffer* target;
841 const char* instanceId;
842 } _OrthancPluginGetDicomForInstance;
843
844 /**
845 * @brief Retrieve a DICOM instance using its Orthanc identifier.
846 *
847 * Retrieve a DICOM instance using its Orthanc identifier. The DICOM
848 * file is stored into a newly allocated memory buffer.
849 *
850 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
851 * @param target The target memory buffer.
852 * @param instanceId The Orthanc identifier of the DICOM instance of interest.
853 * @return 0 if success, other value if error.
854 **/
855 ORTHANC_PLUGIN_INLINE int OrthancPluginGetDicomForInstance(
856 OrthancPluginContext* context,
857 OrthancPluginMemoryBuffer* target,
858 const char* instanceId)
859 {
860 _OrthancPluginGetDicomForInstance params;
861 params.target = target;
862 params.instanceId = instanceId;
863 return context->InvokeService(context, _OrthancPluginService_GetDicomForInstance, &params);
864 }
865
866
867
868 typedef struct
869 {
870 OrthancPluginMemoryBuffer* target;
871 const char* uri;
872 } _OrthancPluginRestApiGet;
873
874 /**
875 * @brief Make a GET call to the built-in Orthanc REST API.
876 *
877 * Make a GET call to the built-in Orthanc REST API. The result to
878 * the query is stored into a newly allocated memory buffer.
879 *
880 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
881 * @param target The target memory buffer.
882 * @param uri The URI in the built-in Orthanc API.
883 * @return 0 if success, other value if error.
884 **/
885 ORTHANC_PLUGIN_INLINE int OrthancPluginRestApiGet(
886 OrthancPluginContext* context,
887 OrthancPluginMemoryBuffer* target,
888 const char* uri)
889 {
890 _OrthancPluginRestApiGet params;
891 params.target = target;
892 params.uri = uri;
893 return context->InvokeService(context, _OrthancPluginService_RestApiGet, &params);
894 }
895
896
897
898 /**
899 * @brief Make a GET call to the REST API, as tainted by the plugins.
900 *
901 * Make a GET call to the Orthanc REST API, after all the plugins
902 * are applied. In other words, if some plugin overrides or adds the
903 * called URI to the built-in Orthanc REST API, this call will
904 * return the result provided by this plugin. The result to the
905 * query is stored into a newly allocated memory buffer.
906 *
907 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
908 * @param target The target memory buffer.
909 * @param uri The URI in the built-in Orthanc API.
910 * @return 0 if success, other value if error.
911 **/
912 ORTHANC_PLUGIN_INLINE int OrthancPluginRestApiGetAfterPlugins(
913 OrthancPluginContext* context,
914 OrthancPluginMemoryBuffer* target,
915 const char* uri)
916 {
917 _OrthancPluginRestApiGet params;
918 params.target = target;
919 params.uri = uri;
920 return context->InvokeService(context, _OrthancPluginService_RestApiGetAfterPlugins, &params);
921 }
922
923
924
925 typedef struct
926 {
927 OrthancPluginMemoryBuffer* target;
928 const char* uri;
929 const char* body;
930 uint32_t bodySize;
931 } _OrthancPluginRestApiPostPut;
932
933 /**
934 * @brief Make a POST call to the built-in Orthanc REST API.
935 *
936 * Make a POST call to the built-in Orthanc REST API. The result to
937 * the query is stored into a newly allocated memory buffer.
938 *
939 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
940 * @param target The target memory buffer.
941 * @param uri The URI in the built-in Orthanc API.
942 * @param body The body of the POST request.
943 * @param bodySize The size of the body.
944 * @return 0 if success, other value if error.
945 **/
946 ORTHANC_PLUGIN_INLINE int OrthancPluginRestApiPost(
947 OrthancPluginContext* context,
948 OrthancPluginMemoryBuffer* target,
949 const char* uri,
950 const char* body,
951 uint32_t bodySize)
952 {
953 _OrthancPluginRestApiPostPut params;
954 params.target = target;
955 params.uri = uri;
956 params.body = body;
957 params.bodySize = bodySize;
958 return context->InvokeService(context, _OrthancPluginService_RestApiPost, &params);
959 }
960
961
962 /**
963 * @brief Make a POST call to the REST API, as tainted by the plugins.
964 *
965 * Make a POST call to the Orthanc REST API, after all the plugins
966 * are applied. In other words, if some plugin overrides or adds the
967 * called URI to the built-in Orthanc REST API, this call will
968 * return the result provided by this plugin. The result to the
969 * query is stored into a newly allocated memory buffer.
970 *
971 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
972 * @param target The target memory buffer.
973 * @param uri The URI in the built-in Orthanc API.
974 * @param body The body of the POST request.
975 * @param bodySize The size of the body.
976 * @return 0 if success, other value if error.
977 **/
978 ORTHANC_PLUGIN_INLINE int OrthancPluginRestApiPostAfterPlugins(
979 OrthancPluginContext* context,
980 OrthancPluginMemoryBuffer* target,
981 const char* uri,
982 const char* body,
983 uint32_t bodySize)
984 {
985 _OrthancPluginRestApiPostPut params;
986 params.target = target;
987 params.uri = uri;
988 params.body = body;
989 params.bodySize = bodySize;
990 return context->InvokeService(context, _OrthancPluginService_RestApiPostAfterPlugins, &params);
991 }
992
993
994
995 /**
996 * @brief Make a DELETE call to the built-in Orthanc REST API.
997 *
998 * Make a DELETE call to the built-in Orthanc REST API.
999 *
1000 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1001 * @param uri The URI to delete in the built-in Orthanc API.
1002 * @return 0 if success, other value if error.
1003 **/
1004 ORTHANC_PLUGIN_INLINE int OrthancPluginRestApiDelete(
1005 OrthancPluginContext* context,
1006 const char* uri)
1007 {
1008 return context->InvokeService(context, _OrthancPluginService_RestApiDelete, uri);
1009 }
1010
1011
1012 /**
1013 * @brief Make a DELETE call to the REST API, as tainted by the plugins.
1014 *
1015 * Make a DELETE call to the Orthanc REST API, after all the plugins
1016 * are applied. In other words, if some plugin overrides or adds the
1017 * called URI to the built-in Orthanc REST API, this call will
1018 * return the result provided by this plugin.
1019 *
1020 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1021 * @param uri The URI to delete in the built-in Orthanc API.
1022 * @return 0 if success, other value if error.
1023 **/
1024 ORTHANC_PLUGIN_INLINE int OrthancPluginRestApiDeleteAfterPlugins(
1025 OrthancPluginContext* context,
1026 const char* uri)
1027 {
1028 return context->InvokeService(context, _OrthancPluginService_RestApiDeleteAfterPlugins, uri);
1029 }
1030
1031
1032
1033 /**
1034 * @brief Make a PUT call to the built-in Orthanc REST API.
1035 *
1036 * Make a PUT call to the built-in Orthanc REST API. The result to
1037 * the query is stored into a newly allocated memory buffer.
1038 *
1039 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1040 * @param target The target memory buffer.
1041 * @param uri The URI in the built-in Orthanc API.
1042 * @param body The body of the PUT request.
1043 * @param bodySize The size of the body.
1044 * @return 0 if success, other value if error.
1045 **/
1046 ORTHANC_PLUGIN_INLINE int OrthancPluginRestApiPut(
1047 OrthancPluginContext* context,
1048 OrthancPluginMemoryBuffer* target,
1049 const char* uri,
1050 const char* body,
1051 uint32_t bodySize)
1052 {
1053 _OrthancPluginRestApiPostPut params;
1054 params.target = target;
1055 params.uri = uri;
1056 params.body = body;
1057 params.bodySize = bodySize;
1058 return context->InvokeService(context, _OrthancPluginService_RestApiPut, &params);
1059 }
1060
1061
1062
1063 /**
1064 * @brief Make a PUT call to the REST API, as tainted by the plugins.
1065 *
1066 * Make a PUT call to the Orthanc REST API, after all the plugins
1067 * are applied. In other words, if some plugin overrides or adds the
1068 * called URI to the built-in Orthanc REST API, this call will
1069 * return the result provided by this plugin. The result to the
1070 * query is stored into a newly allocated memory buffer.
1071 *
1072 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1073 * @param target The target memory buffer.
1074 * @param uri The URI in the built-in Orthanc API.
1075 * @param body The body of the PUT request.
1076 * @param bodySize The size of the body.
1077 * @return 0 if success, other value if error.
1078 **/
1079 ORTHANC_PLUGIN_INLINE int OrthancPluginRestApiPutAfterPlugins(
1080 OrthancPluginContext* context,
1081 OrthancPluginMemoryBuffer* target,
1082 const char* uri,
1083 const char* body,
1084 uint32_t bodySize)
1085 {
1086 _OrthancPluginRestApiPostPut params;
1087 params.target = target;
1088 params.uri = uri;
1089 params.body = body;
1090 params.bodySize = bodySize;
1091 return context->InvokeService(context, _OrthancPluginService_RestApiPutAfterPlugins, &params);
1092 }
1093
1094
1095
1096 typedef struct
1097 {
1098 OrthancPluginRestOutput* output;
1099 const char* argument;
1100 } _OrthancPluginOutputPlusArgument;
1101
1102 /**
1103 * @brief Redirect a REST request.
1104 *
1105 * This function answers to a REST request by redirecting the user
1106 * to another URI using HTTP status 301.
1107 *
1108 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1109 * @param output The HTTP connection to the client application.
1110 * @param redirection Where to redirect.
1111 **/
1112 ORTHANC_PLUGIN_INLINE void OrthancPluginRedirect(
1113 OrthancPluginContext* context,
1114 OrthancPluginRestOutput* output,
1115 const char* redirection)
1116 {
1117 _OrthancPluginOutputPlusArgument params;
1118 params.output = output;
1119 params.argument = redirection;
1120 context->InvokeService(context, _OrthancPluginService_Redirect, &params);
1121 }
1122
1123
1124
1125 typedef struct
1126 {
1127 char** result;
1128 const char* argument;
1129 } _OrthancPluginRetrieveDynamicString;
1130
1131 /**
1132 * @brief Look for a patient.
1133 *
1134 * Look for a patient stored in Orthanc, using its Patient ID tag (0x0010, 0x0020).
1135 * This function uses the database index to run as fast as possible (it does not loop
1136 * over all the stored patients).
1137 *
1138 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1139 * @param patientID The Patient ID of interest.
1140 * @return The NULL value if the patient is non-existent, or a string containing the
1141 * Orthanc ID of the patient. This string must be freed by OrthancPluginFreeString().
1142 **/
1143 ORTHANC_PLUGIN_INLINE char* OrthancPluginLookupPatient(
1144 OrthancPluginContext* context,
1145 const char* patientID)
1146 {
1147 char* result;
1148
1149 _OrthancPluginRetrieveDynamicString params;
1150 params.result = &result;
1151 params.argument = patientID;
1152
1153 if (context->InvokeService(context, _OrthancPluginService_LookupPatient, &params))
1154 {
1155 /* Error */
1156 return NULL;
1157 }
1158 else
1159 {
1160 return result;
1161 }
1162 }
1163
1164
1165 /**
1166 * @brief Look for a study.
1167 *
1168 * Look for a study stored in Orthanc, using its Study Instance UID tag (0x0020, 0x000d).
1169 * This function uses the database index to run as fast as possible (it does not loop
1170 * over all the stored studies).
1171 *
1172 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1173 * @param studyUID The Study Instance UID of interest.
1174 * @return The NULL value if the study is non-existent, or a string containing the
1175 * Orthanc ID of the study. This string must be freed by OrthancPluginFreeString().
1176 **/
1177 ORTHANC_PLUGIN_INLINE char* OrthancPluginLookupStudy(
1178 OrthancPluginContext* context,
1179 const char* studyUID)
1180 {
1181 char* result;
1182
1183 _OrthancPluginRetrieveDynamicString params;
1184 params.result = &result;
1185 params.argument = studyUID;
1186
1187 if (context->InvokeService(context, _OrthancPluginService_LookupStudy, &params))
1188 {
1189 /* Error */
1190 return NULL;
1191 }
1192 else
1193 {
1194 return result;
1195 }
1196 }
1197
1198
1199 /**
1200 * @brief Look for a study, using the accession number.
1201 *
1202 * Look for a study stored in Orthanc, using its Accession Number tag (0x0008, 0x0050).
1203 * This function uses the database index to run as fast as possible (it does not loop
1204 * over all the stored studies).
1205 *
1206 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1207 * @param accessionNumber The Accession Number of interest.
1208 * @return The NULL value if the study is non-existent, or a string containing the
1209 * Orthanc ID of the study. This string must be freed by OrthancPluginFreeString().
1210 **/
1211 ORTHANC_PLUGIN_INLINE char* OrthancPluginLookupStudyWithAccessionNumber(
1212 OrthancPluginContext* context,
1213 const char* accessionNumber)
1214 {
1215 char* result;
1216
1217 _OrthancPluginRetrieveDynamicString params;
1218 params.result = &result;
1219 params.argument = accessionNumber;
1220
1221 if (context->InvokeService(context, _OrthancPluginService_LookupStudyWithAccessionNumber, &params))
1222 {
1223 /* Error */
1224 return NULL;
1225 }
1226 else
1227 {
1228 return result;
1229 }
1230 }
1231
1232
1233 /**
1234 * @brief Look for a series.
1235 *
1236 * Look for a series stored in Orthanc, using its Series Instance UID tag (0x0020, 0x000e).
1237 * This function uses the database index to run as fast as possible (it does not loop
1238 * over all the stored series).
1239 *
1240 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1241 * @param seriesUID The Series Instance UID of interest.
1242 * @return The NULL value if the series is non-existent, or a string containing the
1243 * Orthanc ID of the series. This string must be freed by OrthancPluginFreeString().
1244 **/
1245 ORTHANC_PLUGIN_INLINE char* OrthancPluginLookupSeries(
1246 OrthancPluginContext* context,
1247 const char* seriesUID)
1248 {
1249 char* result;
1250
1251 _OrthancPluginRetrieveDynamicString params;
1252 params.result = &result;
1253 params.argument = seriesUID;
1254
1255 if (context->InvokeService(context, _OrthancPluginService_LookupSeries, &params))
1256 {
1257 /* Error */
1258 return NULL;
1259 }
1260 else
1261 {
1262 return result;
1263 }
1264 }
1265
1266
1267 /**
1268 * @brief Look for an instance.
1269 *
1270 * Look for an instance stored in Orthanc, using its SOP Instance UID tag (0x0008, 0x0018).
1271 * This function uses the database index to run as fast as possible (it does not loop
1272 * over all the stored instances).
1273 *
1274 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1275 * @param sopInstanceUID The SOP Instance UID of interest.
1276 * @return The NULL value if the instance is non-existent, or a string containing the
1277 * Orthanc ID of the instance. This string must be freed by OrthancPluginFreeString().
1278 **/
1279 ORTHANC_PLUGIN_INLINE char* OrthancPluginLookupInstance(
1280 OrthancPluginContext* context,
1281 const char* sopInstanceUID)
1282 {
1283 char* result;
1284
1285 _OrthancPluginRetrieveDynamicString params;
1286 params.result = &result;
1287 params.argument = sopInstanceUID;
1288
1289 if (context->InvokeService(context, _OrthancPluginService_LookupInstance, &params))
1290 {
1291 /* Error */
1292 return NULL;
1293 }
1294 else
1295 {
1296 return result;
1297 }
1298 }
1299
1300
1301
1302 typedef struct
1303 {
1304 OrthancPluginRestOutput* output;
1305 uint16_t status;
1306 } _OrthancPluginSendHttpStatusCode;
1307
1308 /**
1309 * @brief Send a HTTP status code.
1310 *
1311 * This function answers to a REST request by sending a HTTP status
1312 * code (such as "400 - Bad Request"). Note that:
1313 * - Successful requests (status 200) must use ::OrthancPluginAnswerBuffer().
1314 * - Redirections (status 301) must use ::OrthancPluginRedirect().
1315 * - Unauthorized access (status 401) must use ::OrthancPluginSendUnauthorized().
1316 * - Methods not allowed (status 405) must use ::OrthancPluginSendMethodNotAllowed().
1317 *
1318 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1319 * @param output The HTTP connection to the client application.
1320 * @param status The HTTP status code to be sent.
1321 **/
1322 ORTHANC_PLUGIN_INLINE void OrthancPluginSendHttpStatusCode(
1323 OrthancPluginContext* context,
1324 OrthancPluginRestOutput* output,
1325 uint16_t status)
1326 {
1327 _OrthancPluginSendHttpStatusCode params;
1328 params.output = output;
1329 params.status = status;
1330 context->InvokeService(context, _OrthancPluginService_SendHttpStatusCode, &params);
1331 }
1332
1333
1334 /**
1335 * @brief Signal that a REST request is not authorized.
1336 *
1337 * This function answers to a REST request by signaling that it is
1338 * not authorized.
1339 *
1340 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1341 * @param output The HTTP connection to the client application.
1342 * @param realm The realm for the authorization process.
1343 **/
1344 ORTHANC_PLUGIN_INLINE void OrthancPluginSendUnauthorized(
1345 OrthancPluginContext* context,
1346 OrthancPluginRestOutput* output,
1347 const char* realm)
1348 {
1349 _OrthancPluginOutputPlusArgument params;
1350 params.output = output;
1351 params.argument = realm;
1352 context->InvokeService(context, _OrthancPluginService_SendUnauthorized, &params);
1353 }
1354
1355
1356 /**
1357 * @brief Signal that this URI does not support this HTTP method.
1358 *
1359 * This function answers to a REST request by signaling that the
1360 * queried URI does not support this method.
1361 *
1362 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1363 * @param output The HTTP connection to the client application.
1364 * @param allowedMethods The allowed methods for this URI (e.g. "GET,POST" after a PUT or a POST request).
1365 **/
1366 ORTHANC_PLUGIN_INLINE void OrthancPluginSendMethodNotAllowed(
1367 OrthancPluginContext* context,
1368 OrthancPluginRestOutput* output,
1369 const char* allowedMethods)
1370 {
1371 _OrthancPluginOutputPlusArgument params;
1372 params.output = output;
1373 params.argument = allowedMethods;
1374 context->InvokeService(context, _OrthancPluginService_SendMethodNotAllowed, &params);
1375 }
1376
1377
1378 typedef struct
1379 {
1380 OrthancPluginRestOutput* output;
1381 const char* key;
1382 const char* value;
1383 } _OrthancPluginSetHttpHeader;
1384
1385 /**
1386 * @brief Set a cookie.
1387 *
1388 * This function sets a cookie in the HTTP client.
1389 *
1390 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1391 * @param output The HTTP connection to the client application.
1392 * @param cookie The cookie to be set.
1393 * @param value The value of the cookie.
1394 **/
1395 ORTHANC_PLUGIN_INLINE void OrthancPluginSetCookie(
1396 OrthancPluginContext* context,
1397 OrthancPluginRestOutput* output,
1398 const char* cookie,
1399 const char* value)
1400 {
1401 _OrthancPluginSetHttpHeader params;
1402 params.output = output;
1403 params.key = cookie;
1404 params.value = value;
1405 context->InvokeService(context, _OrthancPluginService_SetCookie, &params);
1406 }
1407
1408
1409 /**
1410 * @brief Set some HTTP header.
1411 *
1412 * This function sets a HTTP header in the HTTP answer.
1413 *
1414 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1415 * @param output The HTTP connection to the client application.
1416 * @param key The HTTP header to be set.
1417 * @param value The value of the HTTP header.
1418 **/
1419 ORTHANC_PLUGIN_INLINE void OrthancPluginSetHttpHeader(
1420 OrthancPluginContext* context,
1421 OrthancPluginRestOutput* output,
1422 const char* key,
1423 const char* value)
1424 {
1425 _OrthancPluginSetHttpHeader params;
1426 params.output = output;
1427 params.key = key;
1428 params.value = value;
1429 context->InvokeService(context, _OrthancPluginService_SetHttpHeader, &params);
1430 }
1431
1432
1433 typedef struct
1434 {
1435 char** resultStringToFree;
1436 const char** resultString;
1437 int64_t* resultInt64;
1438 const char* key;
1439 OrthancPluginDicomInstance* instance;
1440 } _OrthancPluginAccessDicomInstance;
1441
1442
1443 /**
1444 * @brief Get the AET of a DICOM instance.
1445 *
1446 * This function returns the Application Entity Title (AET) of the
1447 * DICOM modality from which a DICOM instance originates.
1448 *
1449 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1450 * @param instance The instance of interest.
1451 * @return The AET if success, NULL if error.
1452 **/
1453 ORTHANC_PLUGIN_INLINE const char* OrthancPluginGetInstanceRemoteAet(
1454 OrthancPluginContext* context,
1455 OrthancPluginDicomInstance* instance)
1456 {
1457 const char* result;
1458
1459 _OrthancPluginAccessDicomInstance params;
1460 memset(&params, 0, sizeof(params));
1461 params.resultString = &result;
1462 params.instance = instance;
1463
1464 if (context->InvokeService(context, _OrthancPluginService_GetInstanceRemoteAet, &params))
1465 {
1466 /* Error */
1467 return NULL;
1468 }
1469 else
1470 {
1471 return result;
1472 }
1473 }
1474
1475
1476 /**
1477 * @brief Get the size of a DICOM file.
1478 *
1479 * This function returns the number of bytes of the given DICOM instance.
1480 *
1481 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1482 * @param instance The instance of interest.
1483 * @return The size of the file, -1 in case of error.
1484 **/
1485 ORTHANC_PLUGIN_INLINE int64_t OrthancPluginGetInstanceSize(
1486 OrthancPluginContext* context,
1487 OrthancPluginDicomInstance* instance)
1488 {
1489 int64_t size;
1490
1491 _OrthancPluginAccessDicomInstance params;
1492 memset(&params, 0, sizeof(params));
1493 params.resultInt64 = &size;
1494 params.instance = instance;
1495
1496 if (context->InvokeService(context, _OrthancPluginService_GetInstanceSize, &params))
1497 {
1498 /* Error */
1499 return -1;
1500 }
1501 else
1502 {
1503 return size;
1504 }
1505 }
1506
1507
1508 /**
1509 * @brief Get the data of a DICOM file.
1510 *
1511 * This function returns a pointer to the content of the given DICOM instance.
1512 *
1513 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1514 * @param instance The instance of interest.
1515 * @return The pointer to the DICOM data, NULL in case of error.
1516 **/
1517 ORTHANC_PLUGIN_INLINE const char* OrthancPluginGetInstanceData(
1518 OrthancPluginContext* context,
1519 OrthancPluginDicomInstance* instance)
1520 {
1521 const char* result;
1522
1523 _OrthancPluginAccessDicomInstance params;
1524 memset(&params, 0, sizeof(params));
1525 params.resultString = &result;
1526 params.instance = instance;
1527
1528 if (context->InvokeService(context, _OrthancPluginService_GetInstanceData, &params))
1529 {
1530 /* Error */
1531 return NULL;
1532 }
1533 else
1534 {
1535 return result;
1536 }
1537 }
1538
1539
1540 /**
1541 * @brief Get the DICOM tag hierarchy as a JSON file.
1542 *
1543 * This function returns a pointer to a newly created string
1544 * containing a JSON file. This JSON file encodes the tag hierarchy
1545 * of the given DICOM instance.
1546 *
1547 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1548 * @param instance The instance of interest.
1549 * @return The NULL value in case of error, or a string containing the JSON file.
1550 * This string must be freed by OrthancPluginFreeString().
1551 **/
1552 ORTHANC_PLUGIN_INLINE char* OrthancPluginGetInstanceJson(
1553 OrthancPluginContext* context,
1554 OrthancPluginDicomInstance* instance)
1555 {
1556 char* result;
1557
1558 _OrthancPluginAccessDicomInstance params;
1559 memset(&params, 0, sizeof(params));
1560 params.resultStringToFree = &result;
1561 params.instance = instance;
1562
1563 if (context->InvokeService(context, _OrthancPluginService_GetInstanceJson, &params))
1564 {
1565 /* Error */
1566 return NULL;
1567 }
1568 else
1569 {
1570 return result;
1571 }
1572 }
1573
1574
1575 /**
1576 * @brief Get the DICOM tag hierarchy as a JSON file (with simplification).
1577 *
1578 * This function returns a pointer to a newly created string
1579 * containing a JSON file. This JSON file encodes the tag hierarchy
1580 * of the given DICOM instance. In contrast with
1581 * ::OrthancPluginGetInstanceJson(), the returned JSON file is in
1582 * its simplified version.
1583 *
1584 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1585 * @param instance The instance of interest.
1586 * @return The NULL value in case of error, or a string containing the JSON file.
1587 * This string must be freed by OrthancPluginFreeString().
1588 **/
1589 ORTHANC_PLUGIN_INLINE char* OrthancPluginGetInstanceSimplifiedJson(
1590 OrthancPluginContext* context,
1591 OrthancPluginDicomInstance* instance)
1592 {
1593 char* result;
1594
1595 _OrthancPluginAccessDicomInstance params;
1596 memset(&params, 0, sizeof(params));
1597 params.resultStringToFree = &result;
1598 params.instance = instance;
1599
1600 if (context->InvokeService(context, _OrthancPluginService_GetInstanceSimplifiedJson, &params))
1601 {
1602 /* Error */
1603 return NULL;
1604 }
1605 else
1606 {
1607 return result;
1608 }
1609 }
1610
1611
1612 /**
1613 * @brief Check whether a DICOM instance is associated with some metadata.
1614 *
1615 * This function checks whether the DICOM instance of interest is
1616 * associated with some metadata. As of Orthanc 0.8.1, in the
1617 * callbacks registered by
1618 * ::OrthancPluginRegisterOnStoredInstanceCallback(), the only
1619 * possibly available metadata are "ReceptionDate", "RemoteAET" and
1620 * "IndexInSeries".
1621 *
1622 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1623 * @param instance The instance of interest.
1624 * @param metadata The metadata of interest.
1625 * @return 1 if the metadata is present, 0 if it is absent, -1 in case of error.
1626 **/
1627 ORTHANC_PLUGIN_INLINE int OrthancPluginHasInstanceMetadata(
1628 OrthancPluginContext* context,
1629 OrthancPluginDicomInstance* instance,
1630 const char* metadata)
1631 {
1632 int64_t result;
1633
1634 _OrthancPluginAccessDicomInstance params;
1635 memset(&params, 0, sizeof(params));
1636 params.resultInt64 = &result;
1637 params.instance = instance;
1638 params.key = metadata;
1639
1640 if (context->InvokeService(context, _OrthancPluginService_HasInstanceMetadata, &params))
1641 {
1642 /* Error */
1643 return -1;
1644 }
1645 else
1646 {
1647 return (result != 0);
1648 }
1649 }
1650
1651
1652 /**
1653 * @brief Get the value of some metadata associated with a given DICOM instance.
1654 *
1655 * This functions returns the value of some metadata that is associated with the DICOM instance of interest.
1656 * Before calling this function, the existence of the metadata must have been checked with
1657 * ::OrthancPluginHasInstanceMetadata().
1658 *
1659 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1660 * @param instance The instance of interest.
1661 * @param metadata The metadata of interest.
1662 * @return The metadata value if success, NULL if error.
1663 **/
1664 ORTHANC_PLUGIN_INLINE const char* OrthancPluginGetInstanceMetadata(
1665 OrthancPluginContext* context,
1666 OrthancPluginDicomInstance* instance,
1667 const char* metadata)
1668 {
1669 const char* result;
1670
1671 _OrthancPluginAccessDicomInstance params;
1672 memset(&params, 0, sizeof(params));
1673 params.resultString = &result;
1674 params.instance = instance;
1675 params.key = metadata;
1676
1677 if (context->InvokeService(context, _OrthancPluginService_GetInstanceMetadata, &params))
1678 {
1679 /* Error */
1680 return NULL;
1681 }
1682 else
1683 {
1684 return result;
1685 }
1686 }
1687
1688
1689
1690 typedef struct
1691 {
1692 OrthancPluginStorageCreate create;
1693 OrthancPluginStorageRead read;
1694 OrthancPluginStorageRemove remove;
1695 OrthancPluginFree free;
1696 } _OrthancPluginRegisterStorageArea;
1697
1698 /**
1699 * @brief Register a custom storage area.
1700 *
1701 * This function registers a custom storage area, to replace the
1702 * built-in way Orthanc stores its files on the filesystem. This
1703 * function must be called during the initialization of the plugin,
1704 * i.e. inside the OrthancPluginInitialize() public function.
1705 *
1706 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1707 * @param create The callback function to store a file on the custom storage area.
1708 * @param read The callback function to read a file from the custom storage area.
1709 * @param remove The callback function to remove a file from the custom storage area.
1710 **/
1711 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterStorageArea(
1712 OrthancPluginContext* context,
1713 OrthancPluginStorageCreate create,
1714 OrthancPluginStorageRead read,
1715 OrthancPluginStorageRemove remove)
1716 {
1717 _OrthancPluginRegisterStorageArea params;
1718 params.create = create;
1719 params.read = read;
1720 params.remove = remove;
1721
1722 #ifdef __cplusplus
1723 params.free = ::free;
1724 #else
1725 params.free = free;
1726 #endif
1727
1728 context->InvokeService(context, _OrthancPluginService_RegisterStorageArea, &params);
1729 }
1730
1731
1732
1733 /**
1734 * @brief Return the path to the Orthanc executable.
1735 *
1736 * This function returns the path to the Orthanc executable.
1737 *
1738 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1739 * @return NULL in the case of an error, or a newly allocated string
1740 * containing the path. This string must be freed by
1741 * OrthancPluginFreeString().
1742 **/
1743 ORTHANC_PLUGIN_INLINE char *OrthancPluginGetOrthancPath(OrthancPluginContext* context)
1744 {
1745 char* result;
1746
1747 _OrthancPluginRetrieveDynamicString params;
1748 params.result = &result;
1749 params.argument = NULL;
1750
1751 if (context->InvokeService(context, _OrthancPluginService_GetOrthancPath, &params))
1752 {
1753 /* Error */
1754 return NULL;
1755 }
1756 else
1757 {
1758 return result;
1759 }
1760 }
1761
1762
1763 /**
1764 * @brief Return the directory containing the Orthanc.
1765 *
1766 * This function returns the path to the directory containing the Orthanc executable.
1767 *
1768 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1769 * @return NULL in the case of an error, or a newly allocated string
1770 * containing the path. This string must be freed by
1771 * OrthancPluginFreeString().
1772 **/
1773 ORTHANC_PLUGIN_INLINE char *OrthancPluginGetOrthancDirectory(OrthancPluginContext* context)
1774 {
1775 char* result;
1776
1777 _OrthancPluginRetrieveDynamicString params;
1778 params.result = &result;
1779 params.argument = NULL;
1780
1781 if (context->InvokeService(context, _OrthancPluginService_GetOrthancDirectory, &params))
1782 {
1783 /* Error */
1784 return NULL;
1785 }
1786 else
1787 {
1788 return result;
1789 }
1790 }
1791
1792
1793 /**
1794 * @brief Return the path to the configuration file.
1795 *
1796 * This function returns the path to the configuration file that was
1797 * specified when starting Orthanc.
1798 *
1799 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1800 * @return NULL in the case of an error, or a newly allocated string
1801 * containing the path. This string must be freed by
1802 * OrthancPluginFreeString().
1803 **/
1804 ORTHANC_PLUGIN_INLINE char *OrthancPluginGetConfigurationPath(OrthancPluginContext* context)
1805 {
1806 char* result;
1807
1808 _OrthancPluginRetrieveDynamicString params;
1809 params.result = &result;
1810 params.argument = NULL;
1811
1812 if (context->InvokeService(context, _OrthancPluginService_GetConfigurationPath, &params))
1813 {
1814 /* Error */
1815 return NULL;
1816 }
1817 else
1818 {
1819 return result;
1820 }
1821 }
1822
1823
1824
1825 typedef struct
1826 {
1827 OrthancPluginOnChangeCallback callback;
1828 } _OrthancPluginOnChangeCallback;
1829
1830 /**
1831 * @brief Register a callback to monitor changes.
1832 *
1833 * This function registers a callback function that is called
1834 * whenever a change happens to some DICOM resource.
1835 *
1836 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1837 * @param callback The callback function.
1838 **/
1839 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterOnChangeCallback(
1840 OrthancPluginContext* context,
1841 OrthancPluginOnChangeCallback callback)
1842 {
1843 _OrthancPluginOnChangeCallback params;
1844 params.callback = callback;
1845
1846 context->InvokeService(context, _OrthancPluginService_RegisterOnChangeCallback, &params);
1847 }
1848
1849
1850
1851 typedef struct
1852 {
1853 const char* plugin;
1854 _OrthancPluginProperty property;
1855 const char* value;
1856 } _OrthancPluginSetPluginProperty;
1857
1858
1859 /**
1860 * @brief Set the URI where the plugin provides its Web interface.
1861 *
1862 * For plugins that come with a Web interface, this function
1863 * declares the entry path where to find this interface. This
1864 * information is notably used in the "Plugins" page of Orthanc
1865 * Explorer.
1866 *
1867 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1868 * @param uri The root URI for this plugin.
1869 **/
1870 ORTHANC_PLUGIN_INLINE void OrthancPluginSetRootUri(
1871 OrthancPluginContext* context,
1872 const char* uri)
1873 {
1874 _OrthancPluginSetPluginProperty params;
1875 params.plugin = OrthancPluginGetName();
1876 params.property = _OrthancPluginProperty_RootUri;
1877 params.value = uri;
1878
1879 context->InvokeService(context, _OrthancPluginService_SetPluginProperty, &params);
1880 }
1881
1882
1883 /**
1884 * @brief Set a description for this plugin.
1885 *
1886 * Set a description for this plugin. It is displayed in the
1887 * "Plugins" page of Orthanc Explorer.
1888 *
1889 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1890 * @param description The description.
1891 **/
1892 ORTHANC_PLUGIN_INLINE void OrthancPluginSetDescription(
1893 OrthancPluginContext* context,
1894 const char* description)
1895 {
1896 _OrthancPluginSetPluginProperty params;
1897 params.plugin = OrthancPluginGetName();
1898 params.property = _OrthancPluginProperty_Description;
1899 params.value = description;
1900
1901 context->InvokeService(context, _OrthancPluginService_SetPluginProperty, &params);
1902 }
1903
1904
1905 /**
1906 * @brief Extend the JavaScript code of Orthanc Explorer.
1907 *
1908 * Add JavaScript code to customize the default behavior of Orthanc
1909 * Explorer. This can for instance be used to add new buttons.
1910 *
1911 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1912 * @param javascript The custom JavaScript code.
1913 **/
1914 ORTHANC_PLUGIN_INLINE void OrthancPluginExtendOrthancExplorer(
1915 OrthancPluginContext* context,
1916 const char* javascript)
1917 {
1918 _OrthancPluginSetPluginProperty params;
1919 params.plugin = OrthancPluginGetName();
1920 params.property = _OrthancPluginProperty_OrthancExplorer;
1921 params.value = javascript;
1922
1923 context->InvokeService(context, _OrthancPluginService_SetPluginProperty, &params);
1924 }
1925
1926
1927 typedef struct
1928 {
1929 char** result;
1930 int32_t property;
1931 const char* value;
1932 } _OrthancPluginGlobalProperty;
1933
1934
1935 /**
1936 * @brief Get the value of a global property.
1937 *
1938 * Get the value of a global property that is stored in the Orthanc database. Global
1939 * properties whose index is below 1024 are reserved by Orthanc.
1940 *
1941 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1942 * @param property The global property of interest.
1943 * @param defaultValue The value to return, if the global property is unset.
1944 * @return The value of the global property, or NULL in the case of an error. This
1945 * string must be freed by OrthancPluginFreeString().
1946 **/
1947 ORTHANC_PLUGIN_INLINE char* OrthancPluginGetGlobalProperty(
1948 OrthancPluginContext* context,
1949 int32_t property,
1950 const char* defaultValue)
1951 {
1952 char* result;
1953
1954 _OrthancPluginGlobalProperty params;
1955 params.result = &result;
1956 params.property = property;
1957 params.value = defaultValue;
1958
1959 if (context->InvokeService(context, _OrthancPluginService_GetGlobalProperty, &params))
1960 {
1961 /* Error */
1962 return NULL;
1963 }
1964 else
1965 {
1966 return result;
1967 }
1968 }
1969
1970
1971 /**
1972 * @brief Set the value of a global property.
1973 *
1974 * Set the value of a global property into the Orthanc
1975 * database. Setting a global property can be used by plugins to
1976 * save their internal parameters. Plugins are only allowed to set
1977 * properties whose index are above or equal to 1024 (properties
1978 * below 1024 are read-only and reserved by Orthanc).
1979 *
1980 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1981 * @param property The global property of interest.
1982 * @param value The value to be set in the global property.
1983 * @return 0 if success, -1 in case of error.
1984 **/
1985 ORTHANC_PLUGIN_INLINE int32_t OrthancPluginSetGlobalProperty(
1986 OrthancPluginContext* context,
1987 int32_t property,
1988 const char* value)
1989 {
1990 _OrthancPluginGlobalProperty params;
1991 params.result = NULL;
1992 params.property = property;
1993 params.value = value;
1994
1995 if (context->InvokeService(context, _OrthancPluginService_SetGlobalProperty, &params))
1996 {
1997 /* Error */
1998 return -1;
1999 }
2000 else
2001 {
2002 return 0;
2003 }
2004 }
2005
2006
2007
2008 typedef struct
2009 {
2010 int32_t *resultInt32;
2011 uint32_t *resultUint32;
2012 int64_t *resultInt64;
2013 uint64_t *resultUint64;
2014 } _OrthancPluginReturnSingleValue;
2015
2016 /**
2017 * @brief Get the number of command-line arguments.
2018 *
2019 * Retrieve the number of command-line arguments that were used to launch Orthanc.
2020 *
2021 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2022 * @return The number of arguments.
2023 **/
2024 ORTHANC_PLUGIN_INLINE uint32_t OrthancPluginGetCommandLineArgumentsCount(
2025 OrthancPluginContext* context)
2026 {
2027 uint32_t count = 0;
2028
2029 _OrthancPluginReturnSingleValue params;
2030 memset(&params, 0, sizeof(params));
2031 params.resultUint32 = &count;
2032
2033 if (context->InvokeService(context, _OrthancPluginService_GetCommandLineArgumentsCount, &params))
2034 {
2035 /* Error */
2036 return 0;
2037 }
2038 else
2039 {
2040 return count;
2041 }
2042 }
2043
2044
2045
2046 /**
2047 * @brief Get the value of a command-line argument.
2048 *
2049 * Get the value of one of the command-line arguments that were used
2050 * to launch Orthanc. The number of available arguments can be
2051 * retrieved by OrthancPluginGetCommandLineArgumentsCount().
2052 *
2053 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2054 * @param argument The index of the argument.
2055 * @return The value of the argument, or NULL in the case of an error. This
2056 * string must be freed by OrthancPluginFreeString().
2057 **/
2058 ORTHANC_PLUGIN_INLINE char* OrthancPluginGetCommandLineArgument(
2059 OrthancPluginContext* context,
2060 uint32_t argument)
2061 {
2062 char* result;
2063
2064 _OrthancPluginGlobalProperty params;
2065 params.result = &result;
2066 params.property = (int32_t) argument;
2067 params.value = NULL;
2068
2069 if (context->InvokeService(context, _OrthancPluginService_GetCommandLineArgument, &params))
2070 {
2071 /* Error */
2072 return NULL;
2073 }
2074 else
2075 {
2076 return result;
2077 }
2078 }
2079
2080
2081
2082
2083 #ifdef __cplusplus
2084 }
2085 #endif
2086
2087
2088 /** @} */
2089