Mercurial > hg > orthanc-java

comparison JavaSDK/be/uclouvain/orthanc/Functions.java @ 0:3ecef5782f2c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial commit
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 18 Oct 2023 17:59:44 +0200
parents
children 26c08ff926a3
comparison
equal deleted inserted replaced
-1:000000000000 0:3ecef5782f2c
1 package be.uclouvain.orthanc;
2
3 /**
4 * SPDX-FileCopyrightText: 2023 Sebastien Jodogne, UCLouvain, Belgium
5 * SPDX-License-Identifier: GPL-3.0-or-later
6 */
7
8 /**
9 * Java plugin for Orthanc
10 * Copyright (C) 2023 Sebastien Jodogne, UCLouvain, Belgium
11 *
12 * This program is free software: you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License as
14 * published by the Free Software Foundation, either version 3 of the
15 * License, or (at your option) any later version.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program. If not, see http://www.gnu.org/licenses/.
24 **/
25
26
27 /**
28 * Wrapper around the global functions provided by the Orthanc SDK.
29 **/
30 public class Functions {
31
32 /**
33 * Check that the version of the hosting Orthanc is above a given version.
34 *
35 * This function checks whether the version of the Orthanc server running this
36 * plugin, is above the given version. Contrarily to OrthancPluginCheckVersion(),
37 * it is up to the developer of the plugin to make sure that all the Orthanc SDK
38 * services called by the plugin are actually implemented in the given version of
39 * Orthanc.
40 *
41 * @param expectedMajor Expected major version.
42 * @param expectedMinor Expected minor version.
43 * @param expectedRevision Expected revision.
44 * @return 1 if and only if the versions are compatible. If the result is 0, the
45 * initialization of the plugin should fail.
46 **/
47 public static int checkVersionAdvanced(
48 int expectedMajor,
49 int expectedMinor,
50 int expectedRevision) {
51 return NativeSDK.OrthancPluginCheckVersionAdvanced(expectedMajor, expectedMinor, expectedRevision);
52 }
53
54 /**
55 * Check the compatibility of the plugin wrt. the version of its hosting Orthanc.
56 *
57 * This function checks whether the version of the Orthanc server running this
58 * plugin, is above the version of the current Orthanc SDK header. This guarantees
59 * that the plugin is compatible with the hosting Orthanc (i.e. it will not call
60 * unavailable services). The result of this function should always be checked in
61 * the OrthancPluginInitialize() entry point of the plugin.
62 *
63 * @return 1 if and only if the versions are compatible. If the result is 0, the
64 * initialization of the plugin should fail.
65 **/
66 public static int checkVersion() {
67 return NativeSDK.OrthancPluginCheckVersion();
68 }
69
70 /**
71 * Log an error.
72 *
73 * Log an error message using the Orthanc logging system.
74 *
75 * @param message The message to be logged.
76 **/
77 public static void logError(
78 String message) {
79 NativeSDK.OrthancPluginLogError(message);
80 }
81
82 /**
83 * Log a warning.
84 *
85 * Log a warning message using the Orthanc logging system.
86 *
87 * @param message The message to be logged.
88 **/
89 public static void logWarning(
90 String message) {
91 NativeSDK.OrthancPluginLogWarning(message);
92 }
93
94 /**
95 * Log an information.
96 *
97 * Log an information message using the Orthanc logging system.
98 *
99 * @param message The message to be logged.
100 **/
101 public static void logInfo(
102 String message) {
103 NativeSDK.OrthancPluginLogInfo(message);
104 }
105
106 /**
107 * Retrieve a DICOM instance using its Orthanc identifier.
108 *
109 * Retrieve a DICOM instance using its Orthanc identifier. The DICOM file is stored
110 * into a newly allocated memory buffer.
111 *
112 * @param instanceId The Orthanc identifier of the DICOM instance of interest.
113 * @return The resulting memory buffer.
114 **/
115 public static byte[] getDicomForInstance(
116 String instanceId) {
117 return NativeSDK.OrthancPluginGetDicomForInstance(instanceId);
118 }
119
120 /**
121 * Make a GET call to the built-in Orthanc REST API.
122 *
123 * Make a GET call to the built-in Orthanc REST API. The result to the query is
124 * stored into a newly allocated memory buffer.
125 *
126 * Remark: If the resource is not existing (error 404), the error code will be
127 * OrthancPluginErrorCode_UnknownResource.
128 *
129 * @param uri The URI in the built-in Orthanc API.
130 * @return The resulting memory buffer.
131 **/
132 public static byte[] restApiGet(
133 String uri) {
134 return NativeSDK.OrthancPluginRestApiGet(uri);
135 }
136
137 /**
138 * Make a GET call to the REST API, as tainted by the plugins.
139 *
140 * Make a GET call to the Orthanc REST API, after all the plugins are applied. In
141 * other words, if some plugin overrides or adds the called URI to the built-in
142 * Orthanc REST API, this call will return the result provided by this plugin. The
143 * result to the query is stored into a newly allocated memory buffer.
144 *
145 * Remark: If the resource is not existing (error 404), the error code will be
146 * OrthancPluginErrorCode_UnknownResource.
147 *
148 * @param uri The URI in the built-in Orthanc API.
149 * @return The resulting memory buffer.
150 **/
151 public static byte[] restApiGetAfterPlugins(
152 String uri) {
153 return NativeSDK.OrthancPluginRestApiGetAfterPlugins(uri);
154 }
155
156 /**
157 * Make a POST call to the built-in Orthanc REST API.
158 *
159 * Make a POST call to the built-in Orthanc REST API. The result to the query is
160 * stored into a newly allocated memory buffer.
161 *
162 * Remark: If the resource is not existing (error 404), the error code will be
163 * OrthancPluginErrorCode_UnknownResource.
164 *
165 * @param uri The URI in the built-in Orthanc API.
166 * @param body The body of the POST request.
167 * @return The resulting memory buffer.
168 **/
169 public static byte[] restApiPost(
170 String uri,
171 byte[] body) {
172 return NativeSDK.OrthancPluginRestApiPost(uri, body);
173 }
174
175 /**
176 * Make a POST call to the REST API, as tainted by the plugins.
177 *
178 * Make a POST call to the Orthanc REST API, after all the plugins are applied. In
179 * other words, if some plugin overrides or adds the called URI to the built-in
180 * Orthanc REST API, this call will return the result provided by this plugin. The
181 * result to the query is stored into a newly allocated memory buffer.
182 *
183 * Remark: If the resource is not existing (error 404), the error code will be
184 * OrthancPluginErrorCode_UnknownResource.
185 *
186 * @param uri The URI in the built-in Orthanc API.
187 * @param body The body of the POST request.
188 * @return The resulting memory buffer.
189 **/
190 public static byte[] restApiPostAfterPlugins(
191 String uri,
192 byte[] body) {
193 return NativeSDK.OrthancPluginRestApiPostAfterPlugins(uri, body);
194 }
195
196 /**
197 * Make a DELETE call to the built-in Orthanc REST API.
198 *
199 * Make a DELETE call to the built-in Orthanc REST API.
200 *
201 * Remark: If the resource is not existing (error 404), the error code will be
202 * OrthancPluginErrorCode_UnknownResource.
203 *
204 * @param uri The URI to delete in the built-in Orthanc API.
205 **/
206 public static void restApiDelete(
207 String uri) {
208 NativeSDK.OrthancPluginRestApiDelete(uri);
209 }
210
211 /**
212 * Make a DELETE call to the REST API, as tainted by the plugins.
213 *
214 * Make a DELETE call to the Orthanc REST API, after all the plugins are applied.
215 * In other words, if some plugin overrides or adds the called URI to the built-in
216 * Orthanc REST API, this call will return the result provided by this plugin.
217 *
218 * Remark: If the resource is not existing (error 404), the error code will be
219 * OrthancPluginErrorCode_UnknownResource.
220 *
221 * @param uri The URI to delete in the built-in Orthanc API.
222 **/
223 public static void restApiDeleteAfterPlugins(
224 String uri) {
225 NativeSDK.OrthancPluginRestApiDeleteAfterPlugins(uri);
226 }
227
228 /**
229 * Make a PUT call to the built-in Orthanc REST API.
230 *
231 * Make a PUT call to the built-in Orthanc REST API. The result to the query is
232 * stored into a newly allocated memory buffer.
233 *
234 * Remark: If the resource is not existing (error 404), the error code will be
235 * OrthancPluginErrorCode_UnknownResource.
236 *
237 * @param uri The URI in the built-in Orthanc API.
238 * @param body The body of the PUT request.
239 * @return The resulting memory buffer.
240 **/
241 public static byte[] restApiPut(
242 String uri,
243 byte[] body) {
244 return NativeSDK.OrthancPluginRestApiPut(uri, body);
245 }
246
247 /**
248 * Make a PUT call to the REST API, as tainted by the plugins.
249 *
250 * Make a PUT call to the Orthanc REST API, after all the plugins are applied. In
251 * other words, if some plugin overrides or adds the called URI to the built-in
252 * Orthanc REST API, this call will return the result provided by this plugin. The
253 * result to the query is stored into a newly allocated memory buffer.
254 *
255 * Remark: If the resource is not existing (error 404), the error code will be
256 * OrthancPluginErrorCode_UnknownResource.
257 *
258 * @param uri The URI in the built-in Orthanc API.
259 * @param body The body of the PUT request.
260 * @return The resulting memory buffer.
261 **/
262 public static byte[] restApiPutAfterPlugins(
263 String uri,
264 byte[] body) {
265 return NativeSDK.OrthancPluginRestApiPutAfterPlugins(uri, body);
266 }
267
268 /**
269 * Look for a patient.
270 *
271 * Look for a patient stored in Orthanc, using its Patient ID tag (0x0010, 0x0020).
272 * This function uses the database index to run as fast as possible (it does not
273 * loop over all the stored patients).
274 *
275 * @param patientID The Patient ID of interest.
276 * @return The resulting string.
277 **/
278 public static String lookupPatient(
279 String patientID) {
280 return NativeSDK.OrthancPluginLookupPatient(patientID);
281 }
282
283 /**
284 * Look for a study.
285 *
286 * Look for a study stored in Orthanc, using its Study Instance UID tag (0x0020,
287 * 0x000d). This function uses the database index to run as fast as possible (it
288 * does not loop over all the stored studies).
289 *
290 * @param studyUID The Study Instance UID of interest.
291 * @return The resulting string.
292 **/
293 public static String lookupStudy(
294 String studyUID) {
295 return NativeSDK.OrthancPluginLookupStudy(studyUID);
296 }
297
298 /**
299 * Look for a study, using the accession number.
300 *
301 * Look for a study stored in Orthanc, using its Accession Number tag (0x0008,
302 * 0x0050). This function uses the database index to run as fast as possible (it
303 * does not loop over all the stored studies).
304 *
305 * @param accessionNumber The Accession Number of interest.
306 * @return The resulting string.
307 **/
308 public static String lookupStudyWithAccessionNumber(
309 String accessionNumber) {
310 return NativeSDK.OrthancPluginLookupStudyWithAccessionNumber(accessionNumber);
311 }
312
313 /**
314 * Look for a series.
315 *
316 * Look for a series stored in Orthanc, using its Series Instance UID tag (0x0020,
317 * 0x000e). This function uses the database index to run as fast as possible (it
318 * does not loop over all the stored series).
319 *
320 * @param seriesUID The Series Instance UID of interest.
321 * @return The resulting string.
322 **/
323 public static String lookupSeries(
324 String seriesUID) {
325 return NativeSDK.OrthancPluginLookupSeries(seriesUID);
326 }
327
328 /**
329 * Look for an instance.
330 *
331 * Look for an instance stored in Orthanc, using its SOP Instance UID tag (0x0008,
332 * 0x0018). This function uses the database index to run as fast as possible (it
333 * does not loop over all the stored instances).
334 *
335 * @param sopInstanceUID The SOP Instance UID of interest.
336 * @return The resulting string.
337 **/
338 public static String lookupInstance(
339 String sopInstanceUID) {
340 return NativeSDK.OrthancPluginLookupInstance(sopInstanceUID);
341 }
342
343 /**
344 * Return the path to the Orthanc executable.
345 *
346 * This function returns the path to the Orthanc executable.
347 *
348 * @return The resulting string.
349 **/
350 public static String getOrthancPath() {
351 return NativeSDK.OrthancPluginGetOrthancPath();
352 }
353
354 /**
355 * Return the directory containing the Orthanc.
356 *
357 * This function returns the path to the directory containing the Orthanc
358 * executable.
359 *
360 * @return The resulting string.
361 **/
362 public static String getOrthancDirectory() {
363 return NativeSDK.OrthancPluginGetOrthancDirectory();
364 }
365
366 /**
367 * Return the path to the configuration file(s).
368 *
369 * This function returns the path to the configuration file(s) that was specified
370 * when starting Orthanc. Since version 0.9.1, this path can refer to a folder that
371 * stores a set of configuration files. This function is deprecated in favor of
372 * OrthancPluginGetConfiguration().
373 *
374 * @return The resulting string.
375 **/
376 public static String getConfigurationPath() {
377 return NativeSDK.OrthancPluginGetConfigurationPath();
378 }
379
380 /**
381 * Set the URI where the plugin provides its Web interface.
382 *
383 * For plugins that come with a Web interface, this function declares the entry
384 * path where to find this interface. This information is notably used in the
385 * "Plugins" page of Orthanc Explorer.
386 *
387 * @param uri The root URI for this plugin.
388 **/
389 public static void setRootUri(
390 String uri) {
391 NativeSDK.OrthancPluginSetRootUri(uri);
392 }
393
394 /**
395 * Set a description for this plugin.
396 *
397 * Set a description for this plugin. It is displayed in the "Plugins" page of
398 * Orthanc Explorer.
399 *
400 * @param description The description.
401 **/
402 public static void setDescription(
403 String description) {
404 NativeSDK.OrthancPluginSetDescription(description);
405 }
406
407 /**
408 * Extend the JavaScript code of Orthanc Explorer.
409 *
410 * Add JavaScript code to customize the default behavior of Orthanc Explorer. This
411 * can for instance be used to add new buttons.
412 *
413 * @param javascript The custom JavaScript code.
414 **/
415 public static void extendOrthancExplorer(
416 String javascript) {
417 NativeSDK.OrthancPluginExtendOrthancExplorer(javascript);
418 }
419
420 /**
421 * Get the value of a global property.
422 *
423 * Get the value of a global property that is stored in the Orthanc database.
424 * Global properties whose index is below 1024 are reserved by Orthanc.
425 *
426 * @param property The global property of interest.
427 * @param defaultValue The value to return, if the global property is unset.
428 * @return The resulting string.
429 **/
430 public static String getGlobalProperty(
431 int property,
432 String defaultValue) {
433 return NativeSDK.OrthancPluginGetGlobalProperty(property, defaultValue);
434 }
435
436 /**
437 * Set the value of a global property.
438 *
439 * Set the value of a global property into the Orthanc database. Setting a global
440 * property can be used by plugins to save their internal parameters. Plugins are
441 * only allowed to set properties whose index are above or equal to 1024
442 * (properties below 1024 are read-only and reserved by Orthanc).
443 *
444 * @param property The global property of interest.
445 * @param value The value to be set in the global property.
446 **/
447 public static void setGlobalProperty(
448 int property,
449 String value) {
450 NativeSDK.OrthancPluginSetGlobalProperty(property, value);
451 }
452
453 /**
454 * Get the number of command-line arguments.
455 *
456 * Retrieve the number of command-line arguments that were used to launch Orthanc.
457 *
458 * @return The number of arguments.
459 **/
460 public static int getCommandLineArgumentsCount() {
461 return NativeSDK.OrthancPluginGetCommandLineArgumentsCount();
462 }
463
464 /**
465 * Get the value of a command-line argument.
466 *
467 * Get the value of one of the command-line arguments that were used to launch
468 * Orthanc. The number of available arguments can be retrieved by
469 * OrthancPluginGetCommandLineArgumentsCount().
470 *
471 * @param argument The index of the argument.
472 * @return The resulting string.
473 **/
474 public static String getCommandLineArgument(
475 int argument) {
476 return NativeSDK.OrthancPluginGetCommandLineArgument(argument);
477 }
478
479 /**
480 * Get the expected version of the database schema.
481 *
482 * Retrieve the expected version of the database schema.
483 *
484 * @return The version.
485 **/
486 public static int getExpectedDatabaseVersion() {
487 return NativeSDK.OrthancPluginGetExpectedDatabaseVersion();
488 }
489
490 /**
491 * Return the content of the configuration file(s).
492 *
493 * This function returns the content of the configuration that is used by Orthanc,
494 * formatted as a JSON string.
495 *
496 * @return The resulting string.
497 **/
498 public static String getConfiguration() {
499 return NativeSDK.OrthancPluginGetConfiguration();
500 }
501
502 /**
503 * Compress or decompress a buffer.
504 *
505 * This function compresses or decompresses a buffer, using the version of the zlib
506 * library that is used by the Orthanc core.
507 *
508 * @param source The source buffer.
509 * @param compression The compression algorithm.
510 * @param uncompress If set to "0", the buffer must be compressed. If set to "1",
511 * the buffer must be uncompressed.
512 * @return The resulting memory buffer.
513 **/
514 public static byte[] bufferCompression(
515 byte[] source,
516 CompressionType compression,
517 byte uncompress) {
518 return NativeSDK.OrthancPluginBufferCompression(source, compression.getValue(), uncompress);
519 }
520
521 /**
522 * Read a file.
523 *
524 * Read the content of a file on the filesystem, and returns it into a newly
525 * allocated memory buffer.
526 *
527 * @param path The path of the file to be read.
528 * @return The resulting memory buffer.
529 **/
530 public static byte[] readFile(
531 String path) {
532 return NativeSDK.OrthancPluginReadFile(path);
533 }
534
535 /**
536 * Write a file.
537 *
538 * Write the content of a memory buffer to the filesystem.
539 *
540 * @param path The path of the file to be written.
541 * @param data The content of the memory buffer.
542 **/
543 public static void writeFile(
544 String path,
545 byte[] data) {
546 NativeSDK.OrthancPluginWriteFile(path, data);
547 }
548
549 /**
550 * Get the description of a given error code.
551 *
552 * This function returns the description of a given error code.
553 *
554 * @param error The error code of interest.
555 * @return The resulting string.
556 **/
557 public static String getErrorDescription(
558 ErrorCode error) {
559 return NativeSDK.OrthancPluginGetErrorDescription(error.getValue());
560 }
561
562 /**
563 * Encode a PNG image.
564 *
565 * This function compresses the given memory buffer containing an image using the
566 * PNG specification, and stores the result of the compression into a newly
567 * allocated memory buffer.
568 *
569 * @param format The memory layout of the uncompressed image.
570 * @param width The width of the image.
571 * @param height The height of the image.
572 * @param pitch The pitch of the image (i.e. the number of bytes between 2
573 * successive lines of the image in the memory buffer).
574 * @param buffer The memory buffer containing the uncompressed image.
575 * @return The resulting memory buffer.
576 **/
577 public static byte[] compressPngImage(
578 PixelFormat format,
579 int width,
580 int height,
581 int pitch,
582 byte[] buffer) {
583 return NativeSDK.OrthancPluginCompressPngImage(format.getValue(), width, height, pitch, buffer);
584 }
585
586 /**
587 * Encode a JPEG image.
588 *
589 * This function compresses the given memory buffer containing an image using the
590 * JPEG specification, and stores the result of the compression into a newly
591 * allocated memory buffer.
592 *
593 * @param format The memory layout of the uncompressed image.
594 * @param width The width of the image.
595 * @param height The height of the image.
596 * @param pitch The pitch of the image (i.e. the number of bytes between 2
597 * successive lines of the image in the memory buffer).
598 * @param buffer The memory buffer containing the uncompressed image.
599 * @param quality The quality of the JPEG encoding, between 1 (worst quality, best
600 * compression) and 100 (best quality, worst compression).
601 * @return The resulting memory buffer.
602 **/
603 public static byte[] compressJpegImage(
604 PixelFormat format,
605 int width,
606 int height,
607 int pitch,
608 byte[] buffer,
609 byte quality) {
610 return NativeSDK.OrthancPluginCompressJpegImage(format.getValue(), width, height, pitch, buffer, quality);
611 }
612
613 /**
614 * Issue a HTTP GET call.
615 *
616 * Make a HTTP GET call to the given URL. The result to the query is stored into a
617 * newly allocated memory buffer. Favor OrthancPluginRestApiGet() if calling the
618 * built-in REST API of the Orthanc instance that hosts this plugin.
619 *
620 * @param url The URL of interest.
621 * @param username The username (can be "NULL" if no password protection).
622 * @param password The password (can be "NULL" if no password protection).
623 * @return The resulting memory buffer.
624 **/
625 public static byte[] httpGet(
626 String url,
627 String username,
628 String password) {
629 return NativeSDK.OrthancPluginHttpGet(url, username, password);
630 }
631
632 /**
633 * Issue a HTTP POST call.
634 *
635 * Make a HTTP POST call to the given URL. The result to the query is stored into a
636 * newly allocated memory buffer. Favor OrthancPluginRestApiPost() if calling the
637 * built-in REST API of the Orthanc instance that hosts this plugin.
638 *
639 * @param url The URL of interest.
640 * @param body The content of the body of the request.
641 * @param username The username (can be "NULL" if no password protection).
642 * @param password The password (can be "NULL" if no password protection).
643 * @return The resulting memory buffer.
644 **/
645 public static byte[] httpPost(
646 String url,
647 byte[] body,
648 String username,
649 String password) {
650 return NativeSDK.OrthancPluginHttpPost(url, body, username, password);
651 }
652
653 /**
654 * Issue a HTTP PUT call.
655 *
656 * Make a HTTP PUT call to the given URL. The result to the query is stored into a
657 * newly allocated memory buffer. Favor OrthancPluginRestApiPut() if calling the
658 * built-in REST API of the Orthanc instance that hosts this plugin.
659 *
660 * @param url The URL of interest.
661 * @param body The content of the body of the request.
662 * @param username The username (can be "NULL" if no password protection).
663 * @param password The password (can be "NULL" if no password protection).
664 * @return The resulting memory buffer.
665 **/
666 public static byte[] httpPut(
667 String url,
668 byte[] body,
669 String username,
670 String password) {
671 return NativeSDK.OrthancPluginHttpPut(url, body, username, password);
672 }
673
674 /**
675 * Issue a HTTP DELETE call.
676 *
677 * Make a HTTP DELETE call to the given URL. Favor OrthancPluginRestApiDelete() if
678 * calling the built-in REST API of the Orthanc instance that hosts this plugin.
679 *
680 * @param url The URL of interest.
681 * @param username The username (can be "NULL" if no password protection).
682 * @param password The password (can be "NULL" if no password protection).
683 **/
684 public static void httpDelete(
685 String url,
686 String username,
687 String password) {
688 NativeSDK.OrthancPluginHttpDelete(url, username, password);
689 }
690
691 /**
692 * Return the number of available fonts.
693 *
694 * This function returns the number of fonts that are built in the Orthanc core.
695 * These fonts can be used to draw texts on images through OrthancPluginDrawText().
696 *
697 * @return The number of fonts.
698 **/
699 public static int getFontsCount() {
700 return NativeSDK.OrthancPluginGetFontsCount();
701 }
702
703 /**
704 * Return the name of a font.
705 *
706 * This function returns the name of a font that is built in the Orthanc core.
707 *
708 * @param fontIndex The index of the font. This value must be less than
709 * OrthancPluginGetFontsCount().
710 * @return The resulting string.
711 **/
712 public static String getFontName(
713 int fontIndex) {
714 return NativeSDK.OrthancPluginGetFontName(fontIndex);
715 }
716
717 /**
718 * Return the size of a font.
719 *
720 * This function returns the size of a font that is built in the Orthanc core.
721 *
722 * @param fontIndex The index of the font. This value must be less than
723 * OrthancPluginGetFontsCount().
724 * @return The font size.
725 **/
726 public static int getFontSize(
727 int fontIndex) {
728 return NativeSDK.OrthancPluginGetFontSize(fontIndex);
729 }
730
731 /**
732 * Declare a custom error code for this plugin.
733 *
734 * This function declares a custom error code that can be generated by this plugin.
735 * This declaration is used to enrich the body of the HTTP answer in the case of an
736 * error, and to set the proper HTTP status code.
737 *
738 * @param code The error code that is internal to this plugin.
739 * @param httpStatus The HTTP status corresponding to this error.
740 * @param message The description of the error.
741 **/
742 public static void registerErrorCode(
743 int code,
744 short httpStatus,
745 String message) {
746 NativeSDK.OrthancPluginRegisterErrorCode(code, httpStatus, message);
747 }
748
749 /**
750 * Register a new tag into the DICOM dictionary.
751 *
752 * This function declares a new public tag in the dictionary of DICOM tags that are
753 * known to Orthanc. This function should be used in the OrthancPluginInitialize()
754 * callback.
755 *
756 * @param group The group of the tag.
757 * @param element The element of the tag.
758 * @param vr The value representation of the tag.
759 * @param name The nickname of the tag.
760 * @param minMultiplicity The minimum multiplicity of the tag (must be above 0).
761 * @param maxMultiplicity The maximum multiplicity of the tag. A value of 0 means
762 * an arbitrary multiplicity (""n"").
763 **/
764 public static void registerDictionaryTag(
765 short group,
766 short element,
767 ValueRepresentation vr,
768 String name,
769 int minMultiplicity,
770 int maxMultiplicity) {
771 NativeSDK.OrthancPluginRegisterDictionaryTag(group, element, vr.getValue(), name, minMultiplicity, maxMultiplicity);
772 }
773
774 /**
775 * Register a new private tag into the DICOM dictionary.
776 *
777 * This function declares a new private tag in the dictionary of DICOM tags that
778 * are known to Orthanc. This function should be used in the
779 * OrthancPluginInitialize() callback.
780 *
781 * @param group The group of the tag.
782 * @param element The element of the tag.
783 * @param vr The value representation of the tag.
784 * @param name The nickname of the tag.
785 * @param minMultiplicity The minimum multiplicity of the tag (must be above 0).
786 * @param maxMultiplicity The maximum multiplicity of the tag. A value of 0 means
787 * an arbitrary multiplicity (""n"").
788 * @param privateCreator The private creator of this private tag.
789 **/
790 public static void registerPrivateDictionaryTag(
791 short group,
792 short element,
793 ValueRepresentation vr,
794 String name,
795 int minMultiplicity,
796 int maxMultiplicity,
797 String privateCreator) {
798 NativeSDK.OrthancPluginRegisterPrivateDictionaryTag(group, element, vr.getValue(), name, minMultiplicity, maxMultiplicity, privateCreator);
799 }
800
801 /**
802 * Format a DICOM memory buffer as a JSON string.
803 *
804 * This function takes as input a memory buffer containing a DICOM file, and
805 * outputs a JSON string representing the tags of this DICOM file.
806 *
807 * @param buffer The memory buffer containing the DICOM file.
808 * @param format The output format.
809 * @param flags Flags governing the output.
810 * @param maxStringLength The maximum length of a field. Too long fields will be
811 * output as "null". The 0 value means no maximum length.
812 * @return The resulting string.
813 **/
814 public static String dicomBufferToJson(
815 byte[] buffer,
816 DicomToJsonFormat format,
817 DicomToJsonFlags flags,
818 int maxStringLength) {
819 return NativeSDK.OrthancPluginDicomBufferToJson(buffer, format.getValue(), flags.getValue(), maxStringLength);
820 }
821
822 /**
823 * Format a DICOM instance as a JSON string.
824 *
825 * This function formats a DICOM instance that is stored in Orthanc, and outputs a
826 * JSON string representing the tags of this DICOM instance.
827 *
828 * @param instanceId The Orthanc identifier of the instance.
829 * @param format The output format.
830 * @param flags Flags governing the output.
831 * @param maxStringLength The maximum length of a field. Too long fields will be
832 * output as "null". The 0 value means no maximum length.
833 * @return The resulting string.
834 **/
835 public static String dicomInstanceToJson(
836 String instanceId,
837 DicomToJsonFormat format,
838 DicomToJsonFlags flags,
839 int maxStringLength) {
840 return NativeSDK.OrthancPluginDicomInstanceToJson(instanceId, format.getValue(), flags.getValue(), maxStringLength);
841 }
842
843 /**
844 * Create a DICOM instance from a JSON string and an image.
845 *
846 * This function takes as input a string containing a JSON file describing the
847 * content of a DICOM instance. As an output, it writes the corresponding DICOM
848 * instance to a newly allocated memory buffer. Additionally, an image to be
849 * encoded within the DICOM instance can also be provided.
850 *
851 * Private tags will be associated with the private creator whose value is
852 * specified in the "DefaultPrivateCreator" configuration option of Orthanc. The
853 * function OrthancPluginCreateDicom2() can be used if another private creator must
854 * be used to create this instance.
855 *
856 * @param json The input JSON file.
857 * @param pixelData The image. Can be NULL, if the pixel data is encoded inside the
858 * JSON with the data URI scheme.
859 * @param flags Flags governing the output.
860 * @return The resulting memory buffer.
861 **/
862 public static byte[] createDicom(
863 String json,
864 Image pixelData,
865 CreateDicomFlags flags) {
866 return NativeSDK.OrthancPluginCreateDicom(json, pixelData.getSelf(), flags.getValue());
867 }
868
869 /**
870 * Compute an MD5 hash.
871 *
872 * This functions computes the MD5 cryptographic hash of the given memory buffer.
873 *
874 * @param buffer The source memory buffer.
875 * @return The resulting string.
876 **/
877 public static String computeMd5(
878 byte[] buffer) {
879 return NativeSDK.OrthancPluginComputeMd5(buffer);
880 }
881
882 /**
883 * Compute a SHA-1 hash.
884 *
885 * This functions computes the SHA-1 cryptographic hash of the given memory buffer.
886 *
887 * @param buffer The source memory buffer.
888 * @return The resulting string.
889 **/
890 public static String computeSha1(
891 byte[] buffer) {
892 return NativeSDK.OrthancPluginComputeSha1(buffer);
893 }
894
895 /**
896 * Generate an UUID.
897 *
898 * Generate a random GUID/UUID (globally unique identifier).
899 *
900 * @return The resulting string.
901 **/
902 public static String generateUuid() {
903 return NativeSDK.OrthancPluginGenerateUuid();
904 }
905
906 /**
907 * Detect the MIME type of a file.
908 *
909 * This function returns the MIME type of a file by inspecting its extension.
910 *
911 * @param path Path to the file.
912 * @return The resulting string.
913 **/
914 public static String autodetectMimeType(
915 String path) {
916 return NativeSDK.OrthancPluginAutodetectMimeType(path);
917 }
918
919 /**
920 * Set the value of a metrics.
921 *
922 * This function sets the value of a metrics to monitor the behavior of the plugin
923 * through tools such as Prometheus. The values of all the metrics are stored
924 * within the Orthanc context.
925 *
926 * @param name The name of the metrics to be set.
927 * @param value The value of the metrics.
928 * @param type The type of the metrics. This parameter is only taken into
929 * consideration the first time this metrics is set.
930 **/
931 public static void setMetricsValue(
932 String name,
933 float value,
934 MetricsType type) {
935 NativeSDK.OrthancPluginSetMetricsValue(name, value, type.getValue());
936 }
937
938 /**
939 * Returns the symbolic name of a DICOM tag.
940 *
941 * This function makes a lookup to the dictionary of DICOM tags that are known to
942 * Orthanc, and returns the symbolic name of a DICOM tag.
943 *
944 * @param group The group of the tag.
945 * @param element The element of the tag.
946 * @param privateCreator For private tags, the name of the private creator (can be
947 * NULL).
948 * @return The resulting string.
949 **/
950 public static String getTagName(
951 short group,
952 short element,
953 String privateCreator) {
954 return NativeSDK.OrthancPluginGetTagName(group, element, privateCreator);
955 }
956
957 /**
958 * Generate a token to grant full access to the REST API of Orthanc
959 *
960 * This function generates a token that can be set in the HTTP header
961 * "Authorization" so as to grant full access to the REST API of Orthanc using an
962 * external HTTP client. Using this function avoids the need of adding a separate
963 * user in the "RegisteredUsers" configuration of Orthanc, which eases deployments.
964 *
965 * This feature is notably useful in multiprocess scenarios, where a subprocess
966 * created by a plugin has no access to the "OrthancPluginContext", and thus cannot
967 * call "OrthancPluginRestApi[Get|Post|Put|Delete]()".
968 *
969 * This situation is frequently encountered in Python plugins, where the
970 * "multiprocessing" package can be used to bypass the Global Interpreter Lock
971 * (GIL) and thus to improve performance and concurrency.
972 *
973 * @return The resulting string.
974 **/
975 public static String generateRestApiAuthorizationToken() {
976 return NativeSDK.OrthancPluginGenerateRestApiAuthorizationToken();
977 }
978
979 /**
980 * Create a DICOM instance from a JSON string and an image, with a private creator.
981 *
982 * This function takes as input a string containing a JSON file describing the
983 * content of a DICOM instance. As an output, it writes the corresponding DICOM
984 * instance to a newly allocated memory buffer. Additionally, an image to be
985 * encoded within the DICOM instance can also be provided.
986 *
987 * Contrarily to the function OrthancPluginCreateDicom(), this function can be
988 * explicitly provided with a private creator.
989 *
990 * @param json The input JSON file.
991 * @param pixelData The image. Can be NULL, if the pixel data is encoded inside the
992 * JSON with the data URI scheme.
993 * @param flags Flags governing the output.
994 * @param privateCreator The private creator to be used for the private DICOM tags.
995 * Check out the global configuration option "Dictionary" of Orthanc.
996 * @return The resulting memory buffer.
997 **/
998 public static byte[] createDicom2(
999 String json,
1000 Image pixelData,
1001 CreateDicomFlags flags,
1002 String privateCreator) {
1003 return NativeSDK.OrthancPluginCreateDicom2(json, pixelData.getSelf(), flags.getValue(), privateCreator);
1004 }
1005
1006 }