Mercurial > hg > orthanc-java
comparison JavaSDK/be/uclouvain/orthanc/Functions.java @ 0:3ecef5782f2c
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 } |