Mercurial > hg > orthanc-databases

comparison Resources/Orthanc/Sdk-1.5.2/orthanc/OrthancCPlugin.h @ 94:badc89b06477 db-changes

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
upgrading orthanc sdk from 1.4.0 to 1.5.2
author Sebastien Jodogne <s.jodogne@gmail.com>
date Mon, 21 Jan 2019 14:21:02 +0100
parents
children 4cd7e45b671e
comparison
equal deleted inserted replaced
93:5571a6554db0 94:badc89b06477
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 * - Possibly register its callback for received DICOM instances using ::OrthancPluginRegisterOnStoredInstanceCallback().
18 * - Possibly register its callback for changes to the DICOM store using ::OrthancPluginRegisterOnChangeCallback().
19 * - Possibly register a custom storage area using ::OrthancPluginRegisterStorageArea().
20 * - Possibly register a custom database back-end area using OrthancPluginRegisterDatabaseBackendV2().
21 * - Possibly register a handler for C-Find SCP using OrthancPluginRegisterFindCallback().
22 * - Possibly register a handler for C-Find SCP against DICOM worklists using OrthancPluginRegisterWorklistCallback().
23 * - Possibly register a handler for C-Move SCP using OrthancPluginRegisterMoveCallback().
24 * - Possibly register a custom decoder for DICOM images using OrthancPluginRegisterDecodeImageCallback().
25 * - Possibly register a callback to filter incoming HTTP requests using OrthancPluginRegisterIncomingHttpRequestFilter2().
26 * - Possibly register a callback to unserialize jobs using OrthancPluginRegisterJobsUnserializer().
27 * -# <tt>void OrthancPluginFinalize()</tt>:
28 * This function is invoked by Orthanc during its shutdown. The plugin
29 * must free all its memory.
30 * -# <tt>const char* OrthancPluginGetName()</tt>:
31 * The plugin must return a short string to identify itself.
32 * -# <tt>const char* OrthancPluginGetVersion()</tt>:
33 * The plugin must return a string containing its version number.
34 *
35 * The name and the version of a plugin is only used to prevent it
36 * from being loaded twice. Note that, in C++, it is mandatory to
37 * declare these functions within an <tt>extern "C"</tt> section.
38 *
39 * To ensure multi-threading safety, the various REST callbacks are
40 * guaranteed to be executed in mutual exclusion since Orthanc
41 * 0.8.5. If this feature is undesired (notably when developing
42 * high-performance plugins handling simultaneous requests), use
43 * ::OrthancPluginRegisterRestCallbackNoLock().
44 **/
45
46
47
48 /**
49 * @defgroup Images Images and compression
50 * @brief Functions to deal with images and compressed buffers.
51 *
52 * @defgroup REST REST
53 * @brief Functions to answer REST requests in a callback.
54 *
55 * @defgroup Callbacks Callbacks
56 * @brief Functions to register and manage callbacks by the plugins.
57 *
58 * @defgroup DicomCallbacks DicomCallbacks
59 * @brief Functions to register and manage DICOM callbacks (worklists, C-Find, C-MOVE).
60 *
61 * @defgroup Orthanc Orthanc
62 * @brief Functions to access the content of the Orthanc server.
63 **/
64
65
66
67 /**
68 * @defgroup Toolbox Toolbox
69 * @brief Generic functions to help with the creation of plugins.
70 **/
71
72
73
74 /**
75 * Orthanc - A Lightweight, RESTful DICOM Store
76 * Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics
77 * Department, University Hospital of Liege, Belgium
78 * Copyright (C) 2017-2019 Osimis S.A., Belgium
79 *
80 * This program is free software: you can redistribute it and/or
81 * modify it under the terms of the GNU General Public License as
82 * published by the Free Software Foundation, either version 3 of the
83 * License, or (at your option) any later version.
84 *
85 * In addition, as a special exception, the copyright holders of this
86 * program give permission to link the code of its release with the
87 * OpenSSL project's "OpenSSL" library (or with modified versions of it
88 * that use the same license as the "OpenSSL" library), and distribute
89 * the linked executables. You must obey the GNU General Public License
90 * in all respects for all of the code used other than "OpenSSL". If you
91 * modify file(s) with this exception, you may extend this exception to
92 * your version of the file(s), but you are not obligated to do so. If
93 * you do not wish to do so, delete this exception statement from your
94 * version. If you delete this exception statement from all source files
95 * in the program, then also delete it here.
96 *
97 * This program is distributed in the hope that it will be useful, but
98 * WITHOUT ANY WARRANTY; without even the implied warranty of
99 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
100 * General Public License for more details.
101 *
102 * You should have received a copy of the GNU General Public License
103 * along with this program. If not, see <http://www.gnu.org/licenses/>.
104 **/
105
106
107
108 #pragma once
109
110
111 #include <stdio.h>
112 #include <string.h>
113
114 #ifdef WIN32
115 #define ORTHANC_PLUGINS_API __declspec(dllexport)
116 #else
117 #define ORTHANC_PLUGINS_API
118 #endif
119
120 #define ORTHANC_PLUGINS_MINIMAL_MAJOR_NUMBER 1
121 #define ORTHANC_PLUGINS_MINIMAL_MINOR_NUMBER 5
122 #define ORTHANC_PLUGINS_MINIMAL_REVISION_NUMBER 2
123
124
125 #if !defined(ORTHANC_PLUGINS_VERSION_IS_ABOVE)
126 #define ORTHANC_PLUGINS_VERSION_IS_ABOVE(major, minor, revision) \
127 (ORTHANC_PLUGINS_MINIMAL_MAJOR_NUMBER > major || \
128 (ORTHANC_PLUGINS_MINIMAL_MAJOR_NUMBER == major && \
129 (ORTHANC_PLUGINS_MINIMAL_MINOR_NUMBER > minor || \
130 (ORTHANC_PLUGINS_MINIMAL_MINOR_NUMBER == minor && \
131 ORTHANC_PLUGINS_MINIMAL_REVISION_NUMBER >= revision))))
132 #endif
133
134
135
136 /********************************************************************
137 ** Check that function inlining is properly supported. The use of
138 ** inlining is required, to avoid the duplication of object code
139 ** between two compilation modules that would use the Orthanc Plugin
140 ** API.
141 ********************************************************************/
142
143 /* If the auto-detection of the "inline" keyword below does not work
144 automatically and that your compiler is known to properly support
145 inlining, uncomment the following #define and adapt the definition
146 of "static inline". */
147
148 /* #define ORTHANC_PLUGIN_INLINE static inline */
149
150 #ifndef ORTHANC_PLUGIN_INLINE
151 # if __STDC_VERSION__ >= 199901L
152 /* This is C99 or above: http://predef.sourceforge.net/prestd.html */
153 # define ORTHANC_PLUGIN_INLINE static inline
154 # elif defined(__cplusplus)
155 /* This is C++ */
156 # define ORTHANC_PLUGIN_INLINE static inline
157 # elif defined(__GNUC__)
158 /* This is GCC running in C89 mode */
159 # define ORTHANC_PLUGIN_INLINE static __inline
160 # elif defined(_MSC_VER)
161 /* This is Visual Studio running in C89 mode */
162 # define ORTHANC_PLUGIN_INLINE static __inline
163 # else
164 # error Your compiler is not known to support the "inline" keyword
165 # endif
166 #endif
167
168
169
170 /********************************************************************
171 ** Inclusion of standard libraries.
172 ********************************************************************/
173
174 /**
175 * For Microsoft Visual Studio, a compatibility "stdint.h" can be
176 * downloaded at the following URL:
177 * https://orthanc.googlecode.com/hg/Resources/ThirdParty/VisualStudio/stdint.h
178 **/
179 #include <stdint.h>
180
181 #include <stdlib.h>
182
183
184
185 /********************************************************************
186 ** Definition of the Orthanc Plugin API.
187 ********************************************************************/
188
189 /** @{ */
190
191 #ifdef __cplusplus
192 extern "C"
193 {
194 #endif
195
196 /**
197 * The various error codes that can be returned by the Orthanc core.
198 **/
199 typedef enum
200 {
201 OrthancPluginErrorCode_InternalError = -1 /*!< Internal error */,
202 OrthancPluginErrorCode_Success = 0 /*!< Success */,
203 OrthancPluginErrorCode_Plugin = 1 /*!< Error encountered within the plugin engine */,
204 OrthancPluginErrorCode_NotImplemented = 2 /*!< Not implemented yet */,
205 OrthancPluginErrorCode_ParameterOutOfRange = 3 /*!< Parameter out of range */,
206 OrthancPluginErrorCode_NotEnoughMemory = 4 /*!< The server hosting Orthanc is running out of memory */,
207 OrthancPluginErrorCode_BadParameterType = 5 /*!< Bad type for a parameter */,
208 OrthancPluginErrorCode_BadSequenceOfCalls = 6 /*!< Bad sequence of calls */,
209 OrthancPluginErrorCode_InexistentItem = 7 /*!< Accessing an inexistent item */,
210 OrthancPluginErrorCode_BadRequest = 8 /*!< Bad request */,
211 OrthancPluginErrorCode_NetworkProtocol = 9 /*!< Error in the network protocol */,
212 OrthancPluginErrorCode_SystemCommand = 10 /*!< Error while calling a system command */,
213 OrthancPluginErrorCode_Database = 11 /*!< Error with the database engine */,
214 OrthancPluginErrorCode_UriSyntax = 12 /*!< Badly formatted URI */,
215 OrthancPluginErrorCode_InexistentFile = 13 /*!< Inexistent file */,
216 OrthancPluginErrorCode_CannotWriteFile = 14 /*!< Cannot write to file */,
217 OrthancPluginErrorCode_BadFileFormat = 15 /*!< Bad file format */,
218 OrthancPluginErrorCode_Timeout = 16 /*!< Timeout */,
219 OrthancPluginErrorCode_UnknownResource = 17 /*!< Unknown resource */,
220 OrthancPluginErrorCode_IncompatibleDatabaseVersion = 18 /*!< Incompatible version of the database */,
221 OrthancPluginErrorCode_FullStorage = 19 /*!< The file storage is full */,
222 OrthancPluginErrorCode_CorruptedFile = 20 /*!< Corrupted file (e.g. inconsistent MD5 hash) */,
223 OrthancPluginErrorCode_InexistentTag = 21 /*!< Inexistent tag */,
224 OrthancPluginErrorCode_ReadOnly = 22 /*!< Cannot modify a read-only data structure */,
225 OrthancPluginErrorCode_IncompatibleImageFormat = 23 /*!< Incompatible format of the images */,
226 OrthancPluginErrorCode_IncompatibleImageSize = 24 /*!< Incompatible size of the images */,
227 OrthancPluginErrorCode_SharedLibrary = 25 /*!< Error while using a shared library (plugin) */,
228 OrthancPluginErrorCode_UnknownPluginService = 26 /*!< Plugin invoking an unknown service */,
229 OrthancPluginErrorCode_UnknownDicomTag = 27 /*!< Unknown DICOM tag */,
230 OrthancPluginErrorCode_BadJson = 28 /*!< Cannot parse a JSON document */,
231 OrthancPluginErrorCode_Unauthorized = 29 /*!< Bad credentials were provided to an HTTP request */,
232 OrthancPluginErrorCode_BadFont = 30 /*!< Badly formatted font file */,
233 OrthancPluginErrorCode_DatabasePlugin = 31 /*!< The plugin implementing a custom database back-end does not fulfill the proper interface */,
234 OrthancPluginErrorCode_StorageAreaPlugin = 32 /*!< Error in the plugin implementing a custom storage area */,
235 OrthancPluginErrorCode_EmptyRequest = 33 /*!< The request is empty */,
236 OrthancPluginErrorCode_NotAcceptable = 34 /*!< Cannot send a response which is acceptable according to the Accept HTTP header */,
237 OrthancPluginErrorCode_NullPointer = 35 /*!< Cannot handle a NULL pointer */,
238 OrthancPluginErrorCode_DatabaseUnavailable = 36 /*!< The database is currently not available (probably a transient situation) */,
239 OrthancPluginErrorCode_CanceledJob = 37 /*!< This job was canceled */,
240 OrthancPluginErrorCode_SQLiteNotOpened = 1000 /*!< SQLite: The database is not opened */,
241 OrthancPluginErrorCode_SQLiteAlreadyOpened = 1001 /*!< SQLite: Connection is already open */,
242 OrthancPluginErrorCode_SQLiteCannotOpen = 1002 /*!< SQLite: Unable to open the database */,
243 OrthancPluginErrorCode_SQLiteStatementAlreadyUsed = 1003 /*!< SQLite: This cached statement is already being referred to */,
244 OrthancPluginErrorCode_SQLiteExecute = 1004 /*!< SQLite: Cannot execute a command */,
245 OrthancPluginErrorCode_SQLiteRollbackWithoutTransaction = 1005 /*!< SQLite: Rolling back a nonexistent transaction (have you called Begin()?) */,
246 OrthancPluginErrorCode_SQLiteCommitWithoutTransaction = 1006 /*!< SQLite: Committing a nonexistent transaction */,
247 OrthancPluginErrorCode_SQLiteRegisterFunction = 1007 /*!< SQLite: Unable to register a function */,
248 OrthancPluginErrorCode_SQLiteFlush = 1008 /*!< SQLite: Unable to flush the database */,
249 OrthancPluginErrorCode_SQLiteCannotRun = 1009 /*!< SQLite: Cannot run a cached statement */,
250 OrthancPluginErrorCode_SQLiteCannotStep = 1010 /*!< SQLite: Cannot step over a cached statement */,
251 OrthancPluginErrorCode_SQLiteBindOutOfRange = 1011 /*!< SQLite: Bing a value while out of range (serious error) */,
252 OrthancPluginErrorCode_SQLitePrepareStatement = 1012 /*!< SQLite: Cannot prepare a cached statement */,
253 OrthancPluginErrorCode_SQLiteTransactionAlreadyStarted = 1013 /*!< SQLite: Beginning the same transaction twice */,
254 OrthancPluginErrorCode_SQLiteTransactionCommit = 1014 /*!< SQLite: Failure when committing the transaction */,
255 OrthancPluginErrorCode_SQLiteTransactionBegin = 1015 /*!< SQLite: Cannot start a transaction */,
256 OrthancPluginErrorCode_DirectoryOverFile = 2000 /*!< The directory to be created is already occupied by a regular file */,
257 OrthancPluginErrorCode_FileStorageCannotWrite = 2001 /*!< Unable to create a subdirectory or a file in the file storage */,
258 OrthancPluginErrorCode_DirectoryExpected = 2002 /*!< The specified path does not point to a directory */,
259 OrthancPluginErrorCode_HttpPortInUse = 2003 /*!< The TCP port of the HTTP server is privileged or already in use */,
260 OrthancPluginErrorCode_DicomPortInUse = 2004 /*!< The TCP port of the DICOM server is privileged or already in use */,
261 OrthancPluginErrorCode_BadHttpStatusInRest = 2005 /*!< This HTTP status is not allowed in a REST API */,
262 OrthancPluginErrorCode_RegularFileExpected = 2006 /*!< The specified path does not point to a regular file */,
263 OrthancPluginErrorCode_PathToExecutable = 2007 /*!< Unable to get the path to the executable */,
264 OrthancPluginErrorCode_MakeDirectory = 2008 /*!< Cannot create a directory */,
265 OrthancPluginErrorCode_BadApplicationEntityTitle = 2009 /*!< An application entity title (AET) cannot be empty or be longer than 16 characters */,
266 OrthancPluginErrorCode_NoCFindHandler = 2010 /*!< No request handler factory for DICOM C-FIND SCP */,
267 OrthancPluginErrorCode_NoCMoveHandler = 2011 /*!< No request handler factory for DICOM C-MOVE SCP */,
268 OrthancPluginErrorCode_NoCStoreHandler = 2012 /*!< No request handler factory for DICOM C-STORE SCP */,
269 OrthancPluginErrorCode_NoApplicationEntityFilter = 2013 /*!< No application entity filter */,
270 OrthancPluginErrorCode_NoSopClassOrInstance = 2014 /*!< DicomUserConnection: Unable to find the SOP class and instance */,
271 OrthancPluginErrorCode_NoPresentationContext = 2015 /*!< DicomUserConnection: No acceptable presentation context for modality */,
272 OrthancPluginErrorCode_DicomFindUnavailable = 2016 /*!< DicomUserConnection: The C-FIND command is not supported by the remote SCP */,
273 OrthancPluginErrorCode_DicomMoveUnavailable = 2017 /*!< DicomUserConnection: The C-MOVE command is not supported by the remote SCP */,
274 OrthancPluginErrorCode_CannotStoreInstance = 2018 /*!< Cannot store an instance */,
275 OrthancPluginErrorCode_CreateDicomNotString = 2019 /*!< Only string values are supported when creating DICOM instances */,
276 OrthancPluginErrorCode_CreateDicomOverrideTag = 2020 /*!< Trying to override a value inherited from a parent module */,
277 OrthancPluginErrorCode_CreateDicomUseContent = 2021 /*!< Use \"Content\" to inject an image into a new DICOM instance */,
278 OrthancPluginErrorCode_CreateDicomNoPayload = 2022 /*!< No payload is present for one instance in the series */,
279 OrthancPluginErrorCode_CreateDicomUseDataUriScheme = 2023 /*!< The payload of the DICOM instance must be specified according to Data URI scheme */,
280 OrthancPluginErrorCode_CreateDicomBadParent = 2024 /*!< Trying to attach a new DICOM instance to an inexistent resource */,
281 OrthancPluginErrorCode_CreateDicomParentIsInstance = 2025 /*!< Trying to attach a new DICOM instance to an instance (must be a series, study or patient) */,
282 OrthancPluginErrorCode_CreateDicomParentEncoding = 2026 /*!< Unable to get the encoding of the parent resource */,
283 OrthancPluginErrorCode_UnknownModality = 2027 /*!< Unknown modality */,
284 OrthancPluginErrorCode_BadJobOrdering = 2028 /*!< Bad ordering of filters in a job */,
285 OrthancPluginErrorCode_JsonToLuaTable = 2029 /*!< Cannot convert the given JSON object to a Lua table */,
286 OrthancPluginErrorCode_CannotCreateLua = 2030 /*!< Cannot create the Lua context */,
287 OrthancPluginErrorCode_CannotExecuteLua = 2031 /*!< Cannot execute a Lua command */,
288 OrthancPluginErrorCode_LuaAlreadyExecuted = 2032 /*!< Arguments cannot be pushed after the Lua function is executed */,
289 OrthancPluginErrorCode_LuaBadOutput = 2033 /*!< The Lua function does not give the expected number of outputs */,
290 OrthancPluginErrorCode_NotLuaPredicate = 2034 /*!< The Lua function is not a predicate (only true/false outputs allowed) */,
291 OrthancPluginErrorCode_LuaReturnsNoString = 2035 /*!< The Lua function does not return a string */,
292 OrthancPluginErrorCode_StorageAreaAlreadyRegistered = 2036 /*!< Another plugin has already registered a custom storage area */,
293 OrthancPluginErrorCode_DatabaseBackendAlreadyRegistered = 2037 /*!< Another plugin has already registered a custom database back-end */,
294 OrthancPluginErrorCode_DatabaseNotInitialized = 2038 /*!< Plugin trying to call the database during its initialization */,
295 OrthancPluginErrorCode_SslDisabled = 2039 /*!< Orthanc has been built without SSL support */,
296 OrthancPluginErrorCode_CannotOrderSlices = 2040 /*!< Unable to order the slices of the series */,
297 OrthancPluginErrorCode_NoWorklistHandler = 2041 /*!< No request handler factory for DICOM C-Find Modality SCP */,
298 OrthancPluginErrorCode_AlreadyExistingTag = 2042 /*!< Cannot override the value of a tag that already exists */,
299
300 _OrthancPluginErrorCode_INTERNAL = 0x7fffffff
301 } OrthancPluginErrorCode;
302
303
304 /**
305 * Forward declaration of one of the mandatory functions for Orthanc
306 * plugins.
307 **/
308 ORTHANC_PLUGINS_API const char* OrthancPluginGetName();
309
310
311 /**
312 * The various HTTP methods for a REST call.
313 **/
314 typedef enum
315 {
316 OrthancPluginHttpMethod_Get = 1, /*!< GET request */
317 OrthancPluginHttpMethod_Post = 2, /*!< POST request */
318 OrthancPluginHttpMethod_Put = 3, /*!< PUT request */
319 OrthancPluginHttpMethod_Delete = 4, /*!< DELETE request */
320
321 _OrthancPluginHttpMethod_INTERNAL = 0x7fffffff
322 } OrthancPluginHttpMethod;
323
324
325 /**
326 * @brief The parameters of a REST request.
327 * @ingroup Callbacks
328 **/
329 typedef struct
330 {
331 /**
332 * @brief The HTTP method.
333 **/
334 OrthancPluginHttpMethod method;
335
336 /**
337 * @brief The number of groups of the regular expression.
338 **/
339 uint32_t groupsCount;
340
341 /**
342 * @brief The matched values for the groups of the regular expression.
343 **/
344 const char* const* groups;
345
346 /**
347 * @brief For a GET request, the number of GET parameters.
348 **/
349 uint32_t getCount;
350
351 /**
352 * @brief For a GET request, the keys of the GET parameters.
353 **/
354 const char* const* getKeys;
355
356 /**
357 * @brief For a GET request, the values of the GET parameters.
358 **/
359 const char* const* getValues;
360
361 /**
362 * @brief For a PUT or POST request, the content of the body.
363 **/
364 const char* body;
365
366 /**
367 * @brief For a PUT or POST request, the number of bytes of the body.
368 **/
369 uint32_t bodySize;
370
371
372 /* --------------------------------------------------
373 New in version 0.8.1
374 -------------------------------------------------- */
375
376 /**
377 * @brief The number of HTTP headers.
378 **/
379 uint32_t headersCount;
380
381 /**
382 * @brief The keys of the HTTP headers (always converted to low-case).
383 **/
384 const char* const* headersKeys;
385
386 /**
387 * @brief The values of the HTTP headers.
388 **/
389 const char* const* headersValues;
390
391 } OrthancPluginHttpRequest;
392
393
394 typedef enum
395 {
396 /* Generic services */
397 _OrthancPluginService_LogInfo = 1,
398 _OrthancPluginService_LogWarning = 2,
399 _OrthancPluginService_LogError = 3,
400 _OrthancPluginService_GetOrthancPath = 4,
401 _OrthancPluginService_GetOrthancDirectory = 5,
402 _OrthancPluginService_GetConfigurationPath = 6,
403 _OrthancPluginService_SetPluginProperty = 7,
404 _OrthancPluginService_GetGlobalProperty = 8,
405 _OrthancPluginService_SetGlobalProperty = 9,
406 _OrthancPluginService_GetCommandLineArgumentsCount = 10,
407 _OrthancPluginService_GetCommandLineArgument = 11,
408 _OrthancPluginService_GetExpectedDatabaseVersion = 12,
409 _OrthancPluginService_GetConfiguration = 13,
410 _OrthancPluginService_BufferCompression = 14,
411 _OrthancPluginService_ReadFile = 15,
412 _OrthancPluginService_WriteFile = 16,
413 _OrthancPluginService_GetErrorDescription = 17,
414 _OrthancPluginService_CallHttpClient = 18,
415 _OrthancPluginService_RegisterErrorCode = 19,
416 _OrthancPluginService_RegisterDictionaryTag = 20,
417 _OrthancPluginService_DicomBufferToJson = 21,
418 _OrthancPluginService_DicomInstanceToJson = 22,
419 _OrthancPluginService_CreateDicom = 23,
420 _OrthancPluginService_ComputeMd5 = 24,
421 _OrthancPluginService_ComputeSha1 = 25,
422 _OrthancPluginService_LookupDictionary = 26,
423 _OrthancPluginService_CallHttpClient2 = 27,
424 _OrthancPluginService_GenerateUuid = 28,
425 _OrthancPluginService_RegisterPrivateDictionaryTag = 29,
426 _OrthancPluginService_AutodetectMimeType = 30,
427
428 /* Registration of callbacks */
429 _OrthancPluginService_RegisterRestCallback = 1000,
430 _OrthancPluginService_RegisterOnStoredInstanceCallback = 1001,
431 _OrthancPluginService_RegisterStorageArea = 1002,
432 _OrthancPluginService_RegisterOnChangeCallback = 1003,
433 _OrthancPluginService_RegisterRestCallbackNoLock = 1004,
434 _OrthancPluginService_RegisterWorklistCallback = 1005,
435 _OrthancPluginService_RegisterDecodeImageCallback = 1006,
436 _OrthancPluginService_RegisterIncomingHttpRequestFilter = 1007,
437 _OrthancPluginService_RegisterFindCallback = 1008,
438 _OrthancPluginService_RegisterMoveCallback = 1009,
439 _OrthancPluginService_RegisterIncomingHttpRequestFilter2 = 1010,
440
441 /* Sending answers to REST calls */
442 _OrthancPluginService_AnswerBuffer = 2000,
443 _OrthancPluginService_CompressAndAnswerPngImage = 2001, /* Unused as of Orthanc 0.9.4 */
444 _OrthancPluginService_Redirect = 2002,
445 _OrthancPluginService_SendHttpStatusCode = 2003,
446 _OrthancPluginService_SendUnauthorized = 2004,
447 _OrthancPluginService_SendMethodNotAllowed = 2005,
448 _OrthancPluginService_SetCookie = 2006,
449 _OrthancPluginService_SetHttpHeader = 2007,
450 _OrthancPluginService_StartMultipartAnswer = 2008,
451 _OrthancPluginService_SendMultipartItem = 2009,
452 _OrthancPluginService_SendHttpStatus = 2010,
453 _OrthancPluginService_CompressAndAnswerImage = 2011,
454 _OrthancPluginService_SendMultipartItem2 = 2012,
455 _OrthancPluginService_SetHttpErrorDetails = 2013,
456
457 /* Access to the Orthanc database and API */
458 _OrthancPluginService_GetDicomForInstance = 3000,
459 _OrthancPluginService_RestApiGet = 3001,
460 _OrthancPluginService_RestApiPost = 3002,
461 _OrthancPluginService_RestApiDelete = 3003,
462 _OrthancPluginService_RestApiPut = 3004,
463 _OrthancPluginService_LookupPatient = 3005,
464 _OrthancPluginService_LookupStudy = 3006,
465 _OrthancPluginService_LookupSeries = 3007,
466 _OrthancPluginService_LookupInstance = 3008,
467 _OrthancPluginService_LookupStudyWithAccessionNumber = 3009,
468 _OrthancPluginService_RestApiGetAfterPlugins = 3010,
469 _OrthancPluginService_RestApiPostAfterPlugins = 3011,
470 _OrthancPluginService_RestApiDeleteAfterPlugins = 3012,
471 _OrthancPluginService_RestApiPutAfterPlugins = 3013,
472 _OrthancPluginService_ReconstructMainDicomTags = 3014,
473 _OrthancPluginService_RestApiGet2 = 3015,
474
475 /* Access to DICOM instances */
476 _OrthancPluginService_GetInstanceRemoteAet = 4000,
477 _OrthancPluginService_GetInstanceSize = 4001,
478 _OrthancPluginService_GetInstanceData = 4002,
479 _OrthancPluginService_GetInstanceJson = 4003,
480 _OrthancPluginService_GetInstanceSimplifiedJson = 4004,
481 _OrthancPluginService_HasInstanceMetadata = 4005,
482 _OrthancPluginService_GetInstanceMetadata = 4006,
483 _OrthancPluginService_GetInstanceOrigin = 4007,
484
485 /* Services for plugins implementing a database back-end */
486 _OrthancPluginService_RegisterDatabaseBackend = 5000,
487 _OrthancPluginService_DatabaseAnswer = 5001,
488 _OrthancPluginService_RegisterDatabaseBackendV2 = 5002,
489 _OrthancPluginService_StorageAreaCreate = 5003,
490 _OrthancPluginService_StorageAreaRead = 5004,
491 _OrthancPluginService_StorageAreaRemove = 5005,
492
493 /* Primitives for handling images */
494 _OrthancPluginService_GetImagePixelFormat = 6000,
495 _OrthancPluginService_GetImageWidth = 6001,
496 _OrthancPluginService_GetImageHeight = 6002,
497 _OrthancPluginService_GetImagePitch = 6003,
498 _OrthancPluginService_GetImageBuffer = 6004,
499 _OrthancPluginService_UncompressImage = 6005,
500 _OrthancPluginService_FreeImage = 6006,
501 _OrthancPluginService_CompressImage = 6007,
502 _OrthancPluginService_ConvertPixelFormat = 6008,
503 _OrthancPluginService_GetFontsCount = 6009,
504 _OrthancPluginService_GetFontInfo = 6010,
505 _OrthancPluginService_DrawText = 6011,
506 _OrthancPluginService_CreateImage = 6012,
507 _OrthancPluginService_CreateImageAccessor = 6013,
508 _OrthancPluginService_DecodeDicomImage = 6014,
509
510 /* Primitives for handling C-Find, C-Move and worklists */
511 _OrthancPluginService_WorklistAddAnswer = 7000,
512 _OrthancPluginService_WorklistMarkIncomplete = 7001,
513 _OrthancPluginService_WorklistIsMatch = 7002,
514 _OrthancPluginService_WorklistGetDicomQuery = 7003,
515 _OrthancPluginService_FindAddAnswer = 7004,
516 _OrthancPluginService_FindMarkIncomplete = 7005,
517 _OrthancPluginService_GetFindQuerySize = 7006,
518 _OrthancPluginService_GetFindQueryTag = 7007,
519 _OrthancPluginService_GetFindQueryTagName = 7008,
520 _OrthancPluginService_GetFindQueryValue = 7009,
521 _OrthancPluginService_CreateFindMatcher = 7010,
522 _OrthancPluginService_FreeFindMatcher = 7011,
523 _OrthancPluginService_FindMatcherIsMatch = 7012,
524
525 /* Primitives for accessing Orthanc Peers (new in 1.4.2) */
526 _OrthancPluginService_GetPeers = 8000,
527 _OrthancPluginService_FreePeers = 8001,
528 _OrthancPluginService_GetPeersCount = 8003,
529 _OrthancPluginService_GetPeerName = 8004,
530 _OrthancPluginService_GetPeerUrl = 8005,
531 _OrthancPluginService_CallPeerApi = 8006,
532 _OrthancPluginService_GetPeerUserProperty = 8007,
533
534 /* Primitives for handling jobs (new in 1.4.2) */
535 _OrthancPluginService_CreateJob = 9000,
536 _OrthancPluginService_FreeJob = 9001,
537 _OrthancPluginService_SubmitJob = 9002,
538 _OrthancPluginService_RegisterJobsUnserializer = 9003,
539
540 _OrthancPluginService_INTERNAL = 0x7fffffff
541 } _OrthancPluginService;
542
543
544 typedef enum
545 {
546 _OrthancPluginProperty_Description = 1,
547 _OrthancPluginProperty_RootUri = 2,
548 _OrthancPluginProperty_OrthancExplorer = 3,
549
550 _OrthancPluginProperty_INTERNAL = 0x7fffffff
551 } _OrthancPluginProperty;
552
553
554
555 /**
556 * The memory layout of the pixels of an image.
557 * @ingroup Images
558 **/
559 typedef enum
560 {
561 /**
562 * @brief Graylevel 8bpp image.
563 *
564 * The image is graylevel. Each pixel is unsigned and stored in
565 * one byte.
566 **/
567 OrthancPluginPixelFormat_Grayscale8 = 1,
568
569 /**
570 * @brief Graylevel, unsigned 16bpp image.
571 *
572 * The image is graylevel. Each pixel is unsigned and stored in
573 * two bytes.
574 **/
575 OrthancPluginPixelFormat_Grayscale16 = 2,
576
577 /**
578 * @brief Graylevel, signed 16bpp image.
579 *
580 * The image is graylevel. Each pixel is signed and stored in two
581 * bytes.
582 **/
583 OrthancPluginPixelFormat_SignedGrayscale16 = 3,
584
585 /**
586 * @brief Color image in RGB24 format.
587 *
588 * This format describes a color image. The pixels are stored in 3
589 * consecutive bytes. The memory layout is RGB.
590 **/
591 OrthancPluginPixelFormat_RGB24 = 4,
592
593 /**
594 * @brief Color image in RGBA32 format.
595 *
596 * This format describes a color image. The pixels are stored in 4
597 * consecutive bytes. The memory layout is RGBA.
598 **/
599 OrthancPluginPixelFormat_RGBA32 = 5,
600
601 OrthancPluginPixelFormat_Unknown = 6, /*!< Unknown pixel format */
602
603 /**
604 * @brief Color image in RGB48 format.
605 *
606 * This format describes a color image. The pixels are stored in 6
607 * consecutive bytes. The memory layout is RRGGBB.
608 **/
609 OrthancPluginPixelFormat_RGB48 = 7,
610
611 /**
612 * @brief Graylevel, unsigned 32bpp image.
613 *
614 * The image is graylevel. Each pixel is unsigned and stored in
615 * four bytes.
616 **/
617 OrthancPluginPixelFormat_Grayscale32 = 8,
618
619 /**
620 * @brief Graylevel, floating-point 32bpp image.
621 *
622 * The image is graylevel. Each pixel is floating-point and stored
623 * in four bytes.
624 **/
625 OrthancPluginPixelFormat_Float32 = 9,
626
627 /**
628 * @brief Color image in BGRA32 format.
629 *
630 * This format describes a color image. The pixels are stored in 4
631 * consecutive bytes. The memory layout is BGRA.
632 **/
633 OrthancPluginPixelFormat_BGRA32 = 10,
634
635 /**
636 * @brief Graylevel, unsigned 64bpp image.
637 *
638 * The image is graylevel. Each pixel is unsigned and stored in
639 * eight bytes.
640 **/
641 OrthancPluginPixelFormat_Grayscale64 = 11,
642
643 _OrthancPluginPixelFormat_INTERNAL = 0x7fffffff
644 } OrthancPluginPixelFormat;
645
646
647
648 /**
649 * The content types that are supported by Orthanc plugins.
650 **/
651 typedef enum
652 {
653 OrthancPluginContentType_Unknown = 0, /*!< Unknown content type */
654 OrthancPluginContentType_Dicom = 1, /*!< DICOM */
655 OrthancPluginContentType_DicomAsJson = 2, /*!< JSON summary of a DICOM file */
656
657 _OrthancPluginContentType_INTERNAL = 0x7fffffff
658 } OrthancPluginContentType;
659
660
661
662 /**
663 * The supported types of DICOM resources.
664 **/
665 typedef enum
666 {
667 OrthancPluginResourceType_Patient = 0, /*!< Patient */
668 OrthancPluginResourceType_Study = 1, /*!< Study */
669 OrthancPluginResourceType_Series = 2, /*!< Series */
670 OrthancPluginResourceType_Instance = 3, /*!< Instance */
671 OrthancPluginResourceType_None = 4, /*!< Unavailable resource type */
672
673 _OrthancPluginResourceType_INTERNAL = 0x7fffffff
674 } OrthancPluginResourceType;
675
676
677
678 /**
679 * The supported types of changes that can happen to DICOM resources.
680 * @ingroup Callbacks
681 **/
682 typedef enum
683 {
684 OrthancPluginChangeType_CompletedSeries = 0, /*!< Series is now complete */
685 OrthancPluginChangeType_Deleted = 1, /*!< Deleted resource */
686 OrthancPluginChangeType_NewChildInstance = 2, /*!< A new instance was added to this resource */
687 OrthancPluginChangeType_NewInstance = 3, /*!< New instance received */
688 OrthancPluginChangeType_NewPatient = 4, /*!< New patient created */
689 OrthancPluginChangeType_NewSeries = 5, /*!< New series created */
690 OrthancPluginChangeType_NewStudy = 6, /*!< New study created */
691 OrthancPluginChangeType_StablePatient = 7, /*!< Timeout: No new instance in this patient */
692 OrthancPluginChangeType_StableSeries = 8, /*!< Timeout: No new instance in this series */
693 OrthancPluginChangeType_StableStudy = 9, /*!< Timeout: No new instance in this study */
694 OrthancPluginChangeType_OrthancStarted = 10, /*!< Orthanc has started */
695 OrthancPluginChangeType_OrthancStopped = 11, /*!< Orthanc is stopping */
696 OrthancPluginChangeType_UpdatedAttachment = 12, /*!< Some user-defined attachment has changed for this resource */
697 OrthancPluginChangeType_UpdatedMetadata = 13, /*!< Some user-defined metadata has changed for this resource */
698 OrthancPluginChangeType_UpdatedPeers = 14, /*!< The list of Orthanc peers has changed */
699 OrthancPluginChangeType_UpdatedModalities = 15, /*!< The list of DICOM modalities has changed */
700
701 _OrthancPluginChangeType_INTERNAL = 0x7fffffff
702 } OrthancPluginChangeType;
703
704
705 /**
706 * The compression algorithms that are supported by the Orthanc core.
707 * @ingroup Images
708 **/
709 typedef enum
710 {
711 OrthancPluginCompressionType_Zlib = 0, /*!< Standard zlib compression */
712 OrthancPluginCompressionType_ZlibWithSize = 1, /*!< zlib, prefixed with uncompressed size (uint64_t) */
713 OrthancPluginCompressionType_Gzip = 2, /*!< Standard gzip compression */
714 OrthancPluginCompressionType_GzipWithSize = 3, /*!< gzip, prefixed with uncompressed size (uint64_t) */
715
716 _OrthancPluginCompressionType_INTERNAL = 0x7fffffff
717 } OrthancPluginCompressionType;
718
719
720 /**
721 * The image formats that are supported by the Orthanc core.
722 * @ingroup Images
723 **/
724 typedef enum
725 {
726 OrthancPluginImageFormat_Png = 0, /*!< Image compressed using PNG */
727 OrthancPluginImageFormat_Jpeg = 1, /*!< Image compressed using JPEG */
728 OrthancPluginImageFormat_Dicom = 2, /*!< Image compressed using DICOM */
729
730 _OrthancPluginImageFormat_INTERNAL = 0x7fffffff
731 } OrthancPluginImageFormat;
732
733
734 /**
735 * The value representations present in the DICOM standard (version 2013).
736 * @ingroup Toolbox
737 **/
738 typedef enum
739 {
740 OrthancPluginValueRepresentation_AE = 1, /*!< Application Entity */
741 OrthancPluginValueRepresentation_AS = 2, /*!< Age String */
742 OrthancPluginValueRepresentation_AT = 3, /*!< Attribute Tag */
743 OrthancPluginValueRepresentation_CS = 4, /*!< Code String */
744 OrthancPluginValueRepresentation_DA = 5, /*!< Date */
745 OrthancPluginValueRepresentation_DS = 6, /*!< Decimal String */
746 OrthancPluginValueRepresentation_DT = 7, /*!< Date Time */
747 OrthancPluginValueRepresentation_FD = 8, /*!< Floating Point Double */
748 OrthancPluginValueRepresentation_FL = 9, /*!< Floating Point Single */
749 OrthancPluginValueRepresentation_IS = 10, /*!< Integer String */
750 OrthancPluginValueRepresentation_LO = 11, /*!< Long String */
751 OrthancPluginValueRepresentation_LT = 12, /*!< Long Text */
752 OrthancPluginValueRepresentation_OB = 13, /*!< Other Byte String */
753 OrthancPluginValueRepresentation_OF = 14, /*!< Other Float String */
754 OrthancPluginValueRepresentation_OW = 15, /*!< Other Word String */
755 OrthancPluginValueRepresentation_PN = 16, /*!< Person Name */
756 OrthancPluginValueRepresentation_SH = 17, /*!< Short String */
757 OrthancPluginValueRepresentation_SL = 18, /*!< Signed Long */
758 OrthancPluginValueRepresentation_SQ = 19, /*!< Sequence of Items */
759 OrthancPluginValueRepresentation_SS = 20, /*!< Signed Short */
760 OrthancPluginValueRepresentation_ST = 21, /*!< Short Text */
761 OrthancPluginValueRepresentation_TM = 22, /*!< Time */
762 OrthancPluginValueRepresentation_UI = 23, /*!< Unique Identifier (UID) */
763 OrthancPluginValueRepresentation_UL = 24, /*!< Unsigned Long */
764 OrthancPluginValueRepresentation_UN = 25, /*!< Unknown */
765 OrthancPluginValueRepresentation_US = 26, /*!< Unsigned Short */
766 OrthancPluginValueRepresentation_UT = 27, /*!< Unlimited Text */
767
768 _OrthancPluginValueRepresentation_INTERNAL = 0x7fffffff
769 } OrthancPluginValueRepresentation;
770
771
772 /**
773 * The possible output formats for a DICOM-to-JSON conversion.
774 * @ingroup Toolbox
775 * @see OrthancPluginDicomToJson()
776 **/
777 typedef enum
778 {
779 OrthancPluginDicomToJsonFormat_Full = 1, /*!< Full output, with most details */
780 OrthancPluginDicomToJsonFormat_Short = 2, /*!< Tags output as hexadecimal numbers */
781 OrthancPluginDicomToJsonFormat_Human = 3, /*!< Human-readable JSON */
782
783 _OrthancPluginDicomToJsonFormat_INTERNAL = 0x7fffffff
784 } OrthancPluginDicomToJsonFormat;
785
786
787 /**
788 * Flags to customize a DICOM-to-JSON conversion. By default, binary
789 * tags are formatted using Data URI scheme.
790 * @ingroup Toolbox
791 **/
792 typedef enum
793 {
794 OrthancPluginDicomToJsonFlags_None = 0,
795 OrthancPluginDicomToJsonFlags_IncludeBinary = (1 << 0), /*!< Include the binary tags */
796 OrthancPluginDicomToJsonFlags_IncludePrivateTags = (1 << 1), /*!< Include the private tags */
797 OrthancPluginDicomToJsonFlags_IncludeUnknownTags = (1 << 2), /*!< Include the tags unknown by the dictionary */
798 OrthancPluginDicomToJsonFlags_IncludePixelData = (1 << 3), /*!< Include the pixel data */
799 OrthancPluginDicomToJsonFlags_ConvertBinaryToAscii = (1 << 4), /*!< Output binary tags as-is, dropping non-ASCII */
800 OrthancPluginDicomToJsonFlags_ConvertBinaryToNull = (1 << 5), /*!< Signal binary tags as null values */
801
802 _OrthancPluginDicomToJsonFlags_INTERNAL = 0x7fffffff
803 } OrthancPluginDicomToJsonFlags;
804
805
806 /**
807 * Flags to the creation of a DICOM file.
808 * @ingroup Toolbox
809 * @see OrthancPluginCreateDicom()
810 **/
811 typedef enum
812 {
813 OrthancPluginCreateDicomFlags_None = 0,
814 OrthancPluginCreateDicomFlags_DecodeDataUriScheme = (1 << 0), /*!< Decode fields encoded using data URI scheme */
815 OrthancPluginCreateDicomFlags_GenerateIdentifiers = (1 << 1), /*!< Automatically generate DICOM identifiers */
816
817 _OrthancPluginCreateDicomFlags_INTERNAL = 0x7fffffff
818 } OrthancPluginCreateDicomFlags;
819
820
821 /**
822 * The constraints on the DICOM identifiers that must be supported
823 * by the database plugins.
824 * @deprecated Plugins using OrthancPluginConstraintType will be faster
825 **/
826 typedef enum
827 {
828 OrthancPluginIdentifierConstraint_Equal = 1, /*!< Equal */
829 OrthancPluginIdentifierConstraint_SmallerOrEqual = 2, /*!< Less or equal */
830 OrthancPluginIdentifierConstraint_GreaterOrEqual = 3, /*!< More or equal */
831 OrthancPluginIdentifierConstraint_Wildcard = 4, /*!< Case-sensitive wildcard matching (with * and ?) */
832
833 _OrthancPluginIdentifierConstraint_INTERNAL = 0x7fffffff
834 } OrthancPluginIdentifierConstraint;
835
836
837 /**
838 * The constraints on the tags (main DICOM tags and identifier tags)
839 * that must be supported by the database plugins.
840 **/
841 typedef enum
842 {
843 OrthancPluginConstraintType_Equal = 1, /*!< Equal */
844 OrthancPluginConstraintType_SmallerOrEqual = 2, /*!< Less or equal */
845 OrthancPluginConstraintType_GreaterOrEqual = 3, /*!< More or equal */
846 OrthancPluginConstraintType_Wildcard = 4, /*!< Wildcard matching */
847 OrthancPluginConstraintType_List = 5, /*!< List of values */
848
849 _OrthancPluginConstraintType_INTERNAL = 0x7fffffff
850 } OrthancPluginConstraintType;
851
852
853 /**
854 * The origin of a DICOM instance that has been received by Orthanc.
855 **/
856 typedef enum
857 {
858 OrthancPluginInstanceOrigin_Unknown = 1, /*!< Unknown origin */
859 OrthancPluginInstanceOrigin_DicomProtocol = 2, /*!< Instance received through DICOM protocol */
860 OrthancPluginInstanceOrigin_RestApi = 3, /*!< Instance received through REST API of Orthanc */
861 OrthancPluginInstanceOrigin_Plugin = 4, /*!< Instance added to Orthanc by a plugin */
862 OrthancPluginInstanceOrigin_Lua = 5, /*!< Instance added to Orthanc by a Lua script */
863
864 _OrthancPluginInstanceOrigin_INTERNAL = 0x7fffffff
865 } OrthancPluginInstanceOrigin;
866
867
868 /**
869 * The possible status for one single step of a job.
870 **/
871 typedef enum
872 {
873 OrthancPluginJobStepStatus_Success = 1, /*!< The job has successfully executed all its steps */
874 OrthancPluginJobStepStatus_Failure = 2, /*!< The job has failed while executing this step */
875 OrthancPluginJobStepStatus_Continue = 3 /*!< The job has still data to process after this step */
876 } OrthancPluginJobStepStatus;
877
878
879 /**
880 * Explains why the job should stop and release the resources it has
881 * allocated. This is especially important to disambiguate between
882 * the "paused" condition and the "final" conditions (success,
883 * failure, or canceled).
884 **/
885 typedef enum
886 {
887 OrthancPluginJobStopReason_Success = 1, /*!< The job has succeeded */
888 OrthancPluginJobStopReason_Paused = 2, /*!< The job was paused, and will be resumed later */
889 OrthancPluginJobStopReason_Failure = 3, /*!< The job has failed, and might be resubmitted later */
890 OrthancPluginJobStopReason_Canceled = 4 /*!< The job was canceled, and might be resubmitted later */
891 } OrthancPluginJobStopReason;
892
893
894 /**
895 * @brief A memory buffer allocated by the core system of Orthanc.
896 *
897 * A memory buffer allocated by the core system of Orthanc. When the
898 * content of the buffer is not useful anymore, it must be free by a
899 * call to ::OrthancPluginFreeMemoryBuffer().
900 **/
901 typedef struct
902 {
903 /**
904 * @brief The content of the buffer.
905 **/
906 void* data;
907
908 /**
909 * @brief The number of bytes in the buffer.
910 **/
911 uint32_t size;
912 } OrthancPluginMemoryBuffer;
913
914
915
916
917 /**
918 * @brief Opaque structure that represents the HTTP connection to the client application.
919 * @ingroup Callback
920 **/
921 typedef struct _OrthancPluginRestOutput_t OrthancPluginRestOutput;
922
923
924
925 /**
926 * @brief Opaque structure that represents a DICOM instance received by Orthanc.
927 **/
928 typedef struct _OrthancPluginDicomInstance_t OrthancPluginDicomInstance;
929
930
931
932 /**
933 * @brief Opaque structure that represents an image that is uncompressed in memory.
934 * @ingroup Images
935 **/
936 typedef struct _OrthancPluginImage_t OrthancPluginImage;
937
938
939
940 /**
941 * @brief Opaque structure that represents the storage area that is actually used by Orthanc.
942 * @ingroup Images
943 **/
944 typedef struct _OrthancPluginStorageArea_t OrthancPluginStorageArea;
945
946
947
948 /**
949 * @brief Opaque structure to an object that represents a C-Find query for worklists.
950 * @ingroup DicomCallbacks
951 **/
952 typedef struct _OrthancPluginWorklistQuery_t OrthancPluginWorklistQuery;
953
954
955
956 /**
957 * @brief Opaque structure to an object that represents the answers to a C-Find query for worklists.
958 * @ingroup DicomCallbacks
959 **/
960 typedef struct _OrthancPluginWorklistAnswers_t OrthancPluginWorklistAnswers;
961
962
963
964 /**
965 * @brief Opaque structure to an object that represents a C-Find query.
966 * @ingroup DicomCallbacks
967 **/
968 typedef struct _OrthancPluginFindQuery_t OrthancPluginFindQuery;
969
970
971
972 /**
973 * @brief Opaque structure to an object that represents the answers to a C-Find query for worklists.
974 * @ingroup DicomCallbacks
975 **/
976 typedef struct _OrthancPluginFindAnswers_t OrthancPluginFindAnswers;
977
978
979
980 /**
981 * @brief Opaque structure to an object that can be used to check whether a DICOM instance matches a C-Find query.
982 * @ingroup Toolbox
983 **/
984 typedef struct _OrthancPluginFindAnswers_t OrthancPluginFindMatcher;
985
986
987
988 /**
989 * @brief Opaque structure to the set of remote Orthanc Peers that are known to the local Orthanc server.
990 * @ingroup Toolbox
991 **/
992 typedef struct _OrthancPluginPeers_t OrthancPluginPeers;
993
994
995
996 /**
997 * @brief Opaque structure to a job to be executed by Orthanc.
998 * @ingroup Toolbox
999 **/
1000 typedef struct _OrthancPluginJob_t OrthancPluginJob;
1001
1002
1003
1004 /**
1005 * @brief Signature of a callback function that answers to a REST request.
1006 * @ingroup Callbacks
1007 **/
1008 typedef OrthancPluginErrorCode (*OrthancPluginRestCallback) (
1009 OrthancPluginRestOutput* output,
1010 const char* url,
1011 const OrthancPluginHttpRequest* request);
1012
1013
1014
1015 /**
1016 * @brief Signature of a callback function that is triggered when Orthanc receives a DICOM instance.
1017 * @ingroup Callbacks
1018 **/
1019 typedef OrthancPluginErrorCode (*OrthancPluginOnStoredInstanceCallback) (
1020 OrthancPluginDicomInstance* instance,
1021 const char* instanceId);
1022
1023
1024
1025 /**
1026 * @brief Signature of a callback function that is triggered when a change happens to some DICOM resource.
1027 * @ingroup Callbacks
1028 **/
1029 typedef OrthancPluginErrorCode (*OrthancPluginOnChangeCallback) (
1030 OrthancPluginChangeType changeType,
1031 OrthancPluginResourceType resourceType,
1032 const char* resourceId);
1033
1034
1035
1036 /**
1037 * @brief Signature of a callback function to decode a DICOM instance as an image.
1038 * @ingroup Callbacks
1039 **/
1040 typedef OrthancPluginErrorCode (*OrthancPluginDecodeImageCallback) (
1041 OrthancPluginImage** target,
1042 const void* dicom,
1043 const uint32_t size,
1044 uint32_t frameIndex);
1045
1046
1047
1048 /**
1049 * @brief Signature of a function to free dynamic memory.
1050 **/
1051 typedef void (*OrthancPluginFree) (void* buffer);
1052
1053
1054
1055 /**
1056 * @brief Callback for writing to the storage area.
1057 *
1058 * Signature of a callback function that is triggered when Orthanc writes a file to the storage area.
1059 *
1060 * @param uuid The UUID of the file.
1061 * @param content The content of the file.
1062 * @param size The size of the file.
1063 * @param type The content type corresponding to this file.
1064 * @return 0 if success, other value if error.
1065 * @ingroup Callbacks
1066 **/
1067 typedef OrthancPluginErrorCode (*OrthancPluginStorageCreate) (
1068 const char* uuid,
1069 const void* content,
1070 int64_t size,
1071 OrthancPluginContentType type);
1072
1073
1074
1075 /**
1076 * @brief Callback for reading from the storage area.
1077 *
1078 * Signature of a callback function that is triggered when Orthanc reads a file from the storage area.
1079 *
1080 * @param content The content of the file (output).
1081 * @param size The size of the file (output).
1082 * @param uuid The UUID of the file of interest.
1083 * @param type The content type corresponding to this file.
1084 * @return 0 if success, other value if error.
1085 * @ingroup Callbacks
1086 **/
1087 typedef OrthancPluginErrorCode (*OrthancPluginStorageRead) (
1088 void** content,
1089 int64_t* size,
1090 const char* uuid,
1091 OrthancPluginContentType type);
1092
1093
1094
1095 /**
1096 * @brief Callback for removing a file from the storage area.
1097 *
1098 * Signature of a callback function that is triggered when Orthanc deletes a file from the storage area.
1099 *
1100 * @param uuid The UUID of the file to be removed.
1101 * @param type The content type corresponding to this file.
1102 * @return 0 if success, other value if error.
1103 * @ingroup Callbacks
1104 **/
1105 typedef OrthancPluginErrorCode (*OrthancPluginStorageRemove) (
1106 const char* uuid,
1107 OrthancPluginContentType type);
1108
1109
1110
1111 /**
1112 * @brief Callback to handle the C-Find SCP requests for worklists.
1113 *
1114 * Signature of a callback function that is triggered when Orthanc
1115 * receives a C-Find SCP request against modality worklists.
1116 *
1117 * @param answers The target structure where answers must be stored.
1118 * @param query The worklist query.
1119 * @param issuerAet The Application Entity Title (AET) of the modality from which the request originates.
1120 * @param calledAet The Application Entity Title (AET) of the modality that is called by the request.
1121 * @return 0 if success, other value if error.
1122 * @ingroup DicomCallbacks
1123 **/
1124 typedef OrthancPluginErrorCode (*OrthancPluginWorklistCallback) (
1125 OrthancPluginWorklistAnswers* answers,
1126 const OrthancPluginWorklistQuery* query,
1127 const char* issuerAet,
1128 const char* calledAet);
1129
1130
1131
1132 /**
1133 * @brief Callback to filter incoming HTTP requests received by Orthanc.
1134 *
1135 * Signature of a callback function that is triggered whenever
1136 * Orthanc receives an HTTP/REST request, and that answers whether
1137 * this request should be allowed. If the callback returns "0"
1138 * ("false"), the server answers with HTTP status code 403
1139 * (Forbidden).
1140 *
1141 * @param method The HTTP method used by the request.
1142 * @param uri The URI of interest.
1143 * @param ip The IP address of the HTTP client.
1144 * @param headersCount The number of HTTP headers.
1145 * @param headersKeys The keys of the HTTP headers (always converted to low-case).
1146 * @param headersValues The values of the HTTP headers.
1147 * @return 0 if forbidden access, 1 if allowed access, -1 if error.
1148 * @ingroup Callback
1149 * @deprecated Please instead use OrthancPluginIncomingHttpRequestFilter2()
1150 **/
1151 typedef int32_t (*OrthancPluginIncomingHttpRequestFilter) (
1152 OrthancPluginHttpMethod method,
1153 const char* uri,
1154 const char* ip,
1155 uint32_t headersCount,
1156 const char* const* headersKeys,
1157 const char* const* headersValues);
1158
1159
1160
1161 /**
1162 * @brief Callback to filter incoming HTTP requests received by Orthanc.
1163 *
1164 * Signature of a callback function that is triggered whenever
1165 * Orthanc receives an HTTP/REST request, and that answers whether
1166 * this request should be allowed. If the callback returns "0"
1167 * ("false"), the server answers with HTTP status code 403
1168 * (Forbidden).
1169 *
1170 * @param method The HTTP method used by the request.
1171 * @param uri The URI of interest.
1172 * @param ip The IP address of the HTTP client.
1173 * @param headersCount The number of HTTP headers.
1174 * @param headersKeys The keys of the HTTP headers (always converted to low-case).
1175 * @param headersValues The values of the HTTP headers.
1176 * @param getArgumentsCount The number of GET arguments (only for the GET HTTP method).
1177 * @param getArgumentsKeys The keys of the GET arguments (only for the GET HTTP method).
1178 * @param getArgumentsValues The values of the GET arguments (only for the GET HTTP method).
1179 * @return 0 if forbidden access, 1 if allowed access, -1 if error.
1180 * @ingroup Callback
1181 **/
1182 typedef int32_t (*OrthancPluginIncomingHttpRequestFilter2) (
1183 OrthancPluginHttpMethod method,
1184 const char* uri,
1185 const char* ip,
1186 uint32_t headersCount,
1187 const char* const* headersKeys,
1188 const char* const* headersValues,
1189 uint32_t getArgumentsCount,
1190 const char* const* getArgumentsKeys,
1191 const char* const* getArgumentsValues);
1192
1193
1194
1195 /**
1196 * @brief Callback to handle incoming C-Find SCP requests.
1197 *
1198 * Signature of a callback function that is triggered whenever
1199 * Orthanc receives a C-Find SCP request not concerning modality
1200 * worklists.
1201 *
1202 * @param answers The target structure where answers must be stored.
1203 * @param query The worklist query.
1204 * @param issuerAet The Application Entity Title (AET) of the modality from which the request originates.
1205 * @param calledAet The Application Entity Title (AET) of the modality that is called by the request.
1206 * @return 0 if success, other value if error.
1207 * @ingroup DicomCallbacks
1208 **/
1209 typedef OrthancPluginErrorCode (*OrthancPluginFindCallback) (
1210 OrthancPluginFindAnswers* answers,
1211 const OrthancPluginFindQuery* query,
1212 const char* issuerAet,
1213 const char* calledAet);
1214
1215
1216
1217 /**
1218 * @brief Callback to handle incoming C-Move SCP requests.
1219 *
1220 * Signature of a callback function that is triggered whenever
1221 * Orthanc receives a C-Move SCP request. The callback receives the
1222 * type of the resource of interest (study, series, instance...)
1223 * together with the DICOM tags containing its identifiers. In turn,
1224 * the plugin must create a driver object that will be responsible
1225 * for driving the successive move suboperations.
1226 *
1227 * @param resourceType The type of the resource of interest. Note
1228 * that this might be set to ResourceType_None if the
1229 * QueryRetrieveLevel (0008,0052) tag was not provided by the
1230 * issuer (i.e. the originator modality).
1231 * @param patientId Content of the PatientID (0x0010, 0x0020) tag of the resource of interest. Might be NULL.
1232 * @param accessionNumber Content of the AccessionNumber (0x0008, 0x0050) tag. Might be NULL.
1233 * @param studyInstanceUid Content of the StudyInstanceUID (0x0020, 0x000d) tag. Might be NULL.
1234 * @param seriesInstanceUid Content of the SeriesInstanceUID (0x0020, 0x000e) tag. Might be NULL.
1235 * @param sopInstanceUid Content of the SOPInstanceUID (0x0008, 0x0018) tag. Might be NULL.
1236 * @param originatorAet The Application Entity Title (AET) of the
1237 * modality from which the request originates.
1238 * @param sourceAet The Application Entity Title (AET) of the
1239 * modality that should send its DICOM files to another modality.
1240 * @param targetAet The Application Entity Title (AET) of the
1241 * modality that should receive the DICOM files.
1242 * @param originatorId The Message ID issued by the originator modality,
1243 * as found in tag (0000,0110) of the DICOM query emitted by the issuer.
1244 *
1245 * @return The NULL value if the plugin cannot deal with this query,
1246 * or a pointer to the driver object that is responsible for
1247 * handling the successive move suboperations.
1248 *
1249 * @note If targetAet equals sourceAet, this is actually a query/retrieve operation.
1250 * @ingroup DicomCallbacks
1251 **/
1252 typedef void* (*OrthancPluginMoveCallback) (
1253 OrthancPluginResourceType resourceType,
1254 const char* patientId,
1255 const char* accessionNumber,
1256 const char* studyInstanceUid,
1257 const char* seriesInstanceUid,
1258 const char* sopInstanceUid,
1259 const char* originatorAet,
1260 const char* sourceAet,
1261 const char* targetAet,
1262 uint16_t originatorId);
1263
1264
1265 /**
1266 * @brief Callback to read the size of a C-Move driver.
1267 *
1268 * Signature of a callback function that returns the number of
1269 * C-Move suboperations that are to be achieved by the given C-Move
1270 * driver. This driver is the return value of a previous call to the
1271 * OrthancPluginMoveCallback() callback.
1272 *
1273 * @param moveDriver The C-Move driver of interest.
1274 * @return The number of suboperations.
1275 * @ingroup DicomCallbacks
1276 **/
1277 typedef uint32_t (*OrthancPluginGetMoveSize) (void* moveDriver);
1278
1279
1280 /**
1281 * @brief Callback to apply one C-Move suboperation.
1282 *
1283 * Signature of a callback function that applies the next C-Move
1284 * suboperation that os to be achieved by the given C-Move
1285 * driver. This driver is the return value of a previous call to the
1286 * OrthancPluginMoveCallback() callback.
1287 *
1288 * @param moveDriver The C-Move driver of interest.
1289 * @return 0 if success, or the error code if failure.
1290 * @ingroup DicomCallbacks
1291 **/
1292 typedef OrthancPluginErrorCode (*OrthancPluginApplyMove) (void* moveDriver);
1293
1294
1295 /**
1296 * @brief Callback to free one C-Move driver.
1297 *
1298 * Signature of a callback function that releases the resources
1299 * allocated by the given C-Move driver. This driver is the return
1300 * value of a previous call to the OrthancPluginMoveCallback()
1301 * callback.
1302 *
1303 * @param moveDriver The C-Move driver of interest.
1304 * @ingroup DicomCallbacks
1305 **/
1306 typedef void (*OrthancPluginFreeMove) (void* moveDriver);
1307
1308
1309 /**
1310 * @brief Callback to finalize one custom job.
1311 *
1312 * Signature of a callback function that releases all the resources
1313 * allocated by the given job. This job is the argument provided to
1314 * OrthancPluginCreateJob().
1315 *
1316 * @param job The job of interest.
1317 * @ingroup Toolbox
1318 **/
1319 typedef void (*OrthancPluginJobFinalize) (void* job);
1320
1321
1322 /**
1323 * @brief Callback to check the progress of one custom job.
1324 *
1325 * Signature of a callback function that returns the progress of the
1326 * job.
1327 *
1328 * @param job The job of interest.
1329 * @return The progress, as a floating-point number ranging from 0 to 1.
1330 * @ingroup Toolbox
1331 **/
1332 typedef float (*OrthancPluginJobGetProgress) (void* job);
1333
1334
1335 /**
1336 * @brief Callback to retrieve the content of one custom job.
1337 *
1338 * Signature of a callback function that returns human-readable
1339 * statistics about the job. This statistics must be formatted as a
1340 * JSON object. This information is notably displayed in the "Jobs"
1341 * tab of "Orthanc Explorer".
1342 *
1343 * @param job The job of interest.
1344 * @return The statistics, as a JSON object encoded as a string.
1345 * @ingroup Toolbox
1346 **/
1347 typedef const char* (*OrthancPluginJobGetContent) (void* job);
1348
1349
1350 /**
1351 * @brief Callback to serialize one custom job.
1352 *
1353 * Signature of a callback function that returns a serialized
1354 * version of the job, formatted as a JSON object. This
1355 * serialization is stored in the Orthanc database, and is used to
1356 * reload the job on the restart of Orthanc. The "unserialization"
1357 * callback (with OrthancPluginJobsUnserializer signature) will
1358 * receive this serialized object.
1359 *
1360 * @param job The job of interest.
1361 * @return The serialized job, as a JSON object encoded as a string.
1362 * @see OrthancPluginRegisterJobsUnserializer()
1363 * @ingroup Toolbox
1364 **/
1365 typedef const char* (*OrthancPluginJobGetSerialized) (void* job);
1366
1367
1368 /**
1369 * @brief Callback to execute one step of a custom job.
1370 *
1371 * Signature of a callback function that executes one step in the
1372 * job. The jobs engine of Orthanc will make successive calls to
1373 * this method, as long as it returns
1374 * OrthancPluginJobStepStatus_Continue.
1375 *
1376 * @param job The job of interest.
1377 * @return The status of execution.
1378 * @ingroup Toolbox
1379 **/
1380 typedef OrthancPluginJobStepStatus (*OrthancPluginJobStep) (void* job);
1381
1382
1383 /**
1384 * @brief Callback executed once one custom job leaves the "running" state.
1385 *
1386 * Signature of a callback function that is invoked once a job
1387 * leaves the "running" state. This can happen if the previous call
1388 * to OrthancPluginJobStep has failed/succeeded, if the host Orthanc
1389 * server is being stopped, or if the user manually tags the job as
1390 * paused/canceled. This callback allows the plugin to free
1391 * resources allocated for running this custom job (e.g. to stop
1392 * threads, or to remove temporary files).
1393 *
1394 * Note that handling pauses might involves a specific treatment
1395 * (such a stopping threads, but keeping temporary files on the
1396 * disk). This "paused" situation can be checked by looking at the
1397 * "reason" parameter.
1398 *
1399 * @param job The job of interest.
1400 * @param reason The reason for leaving the "running" state.
1401 * @return 0 if success, or the error code if failure.
1402 * @ingroup Toolbox
1403 **/
1404 typedef OrthancPluginErrorCode (*OrthancPluginJobStop) (void* job,
1405 OrthancPluginJobStopReason reason);
1406
1407
1408 /**
1409 * @brief Callback executed once one stopped custom job is started again.
1410 *
1411 * Signature of a callback function that is invoked once a job
1412 * leaves the "failure/canceled" state, to be started again. This
1413 * function will typically reset the progress to zero. Note that
1414 * before being actually executed, the job would first be tagged as
1415 * "pending" in the Orthanc jobs engine.
1416 *
1417 * @param job The job of interest.
1418 * @return 0 if success, or the error code if failure.
1419 * @ingroup Toolbox
1420 **/
1421 typedef OrthancPluginErrorCode (*OrthancPluginJobReset) (void* job);
1422
1423
1424 /**
1425 * @brief Callback executed to unserialized a custom job.
1426 *
1427 * Signature of a callback function that unserializes a job that was
1428 * saved in the Orthanc database.
1429 *
1430 * @param jobType The type of the job, as provided to OrthancPluginCreateJob().
1431 * @param serialized The serialization of the job, as provided by OrthancPluginJobGetSerialized.
1432 * @return The unserialized job (as created by OrthancPluginCreateJob()), or NULL
1433 * if this unserializer cannot handle this job type.
1434 * @see OrthancPluginRegisterJobsUnserializer()
1435 * @ingroup Callbacks
1436 **/
1437 typedef OrthancPluginJob* (*OrthancPluginJobsUnserializer) (const char* jobType,
1438 const char* serialized);
1439
1440
1441
1442 /**
1443 * @brief Data structure that contains information about the Orthanc core.
1444 **/
1445 typedef struct _OrthancPluginContext_t
1446 {
1447 void* pluginsManager;
1448 const char* orthancVersion;
1449 OrthancPluginFree Free;
1450 OrthancPluginErrorCode (*InvokeService) (struct _OrthancPluginContext_t* context,
1451 _OrthancPluginService service,
1452 const void* params);
1453 } OrthancPluginContext;
1454
1455
1456
1457 /**
1458 * @brief An entry in the dictionary of DICOM tags.
1459 **/
1460 typedef struct
1461 {
1462 uint16_t group; /*!< The group of the tag */
1463 uint16_t element; /*!< The element of the tag */
1464 OrthancPluginValueRepresentation vr; /*!< The value representation of the tag */
1465 uint32_t minMultiplicity; /*!< The minimum multiplicity of the tag */
1466 uint32_t maxMultiplicity; /*!< The maximum multiplicity of the tag (0 means arbitrary) */
1467 } OrthancPluginDictionaryEntry;
1468
1469
1470
1471 /**
1472 * @brief Free a string.
1473 *
1474 * Free a string that was allocated by the core system of Orthanc.
1475 *
1476 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1477 * @param str The string to be freed.
1478 **/
1479 ORTHANC_PLUGIN_INLINE void OrthancPluginFreeString(
1480 OrthancPluginContext* context,
1481 char* str)
1482 {
1483 if (str != NULL)
1484 {
1485 context->Free(str);
1486 }
1487 }
1488
1489
1490 /**
1491 * @brief Check that the version of the hosting Orthanc is above a given version.
1492 *
1493 * This function checks whether the version of the Orthanc server
1494 * running this plugin, is above the given version. Contrarily to
1495 * OrthancPluginCheckVersion(), it is up to the developer of the
1496 * plugin to make sure that all the Orthanc SDK services called by
1497 * the plugin are actually implemented in the given version of
1498 * Orthanc.
1499 *
1500 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1501 * @param expectedMajor Expected major version.
1502 * @param expectedMinor Expected minor version.
1503 * @param expectedRevision Expected revision.
1504 * @return 1 if and only if the versions are compatible. If the
1505 * result is 0, the initialization of the plugin should fail.
1506 * @see OrthancPluginCheckVersion
1507 * @ingroup Callbacks
1508 **/
1509 ORTHANC_PLUGIN_INLINE int OrthancPluginCheckVersionAdvanced(
1510 OrthancPluginContext* context,
1511 int expectedMajor,
1512 int expectedMinor,
1513 int expectedRevision)
1514 {
1515 int major, minor, revision;
1516
1517 if (sizeof(int32_t) != sizeof(OrthancPluginErrorCode) ||
1518 sizeof(int32_t) != sizeof(OrthancPluginHttpMethod) ||
1519 sizeof(int32_t) != sizeof(_OrthancPluginService) ||
1520 sizeof(int32_t) != sizeof(_OrthancPluginProperty) ||
1521 sizeof(int32_t) != sizeof(OrthancPluginPixelFormat) ||
1522 sizeof(int32_t) != sizeof(OrthancPluginContentType) ||
1523 sizeof(int32_t) != sizeof(OrthancPluginResourceType) ||
1524 sizeof(int32_t) != sizeof(OrthancPluginChangeType) ||
1525 sizeof(int32_t) != sizeof(OrthancPluginCompressionType) ||
1526 sizeof(int32_t) != sizeof(OrthancPluginImageFormat) ||
1527 sizeof(int32_t) != sizeof(OrthancPluginValueRepresentation) ||
1528 sizeof(int32_t) != sizeof(OrthancPluginDicomToJsonFormat) ||
1529 sizeof(int32_t) != sizeof(OrthancPluginDicomToJsonFlags) ||
1530 sizeof(int32_t) != sizeof(OrthancPluginCreateDicomFlags) ||
1531 sizeof(int32_t) != sizeof(OrthancPluginIdentifierConstraint) ||
1532 sizeof(int32_t) != sizeof(OrthancPluginInstanceOrigin) ||
1533 sizeof(int32_t) != sizeof(OrthancPluginJobStepStatus) ||
1534 sizeof(int32_t) != sizeof(OrthancPluginConstraintType))
1535 {
1536 /* Mismatch in the size of the enumerations */
1537 return 0;
1538 }
1539
1540 /* Assume compatibility with the mainline */
1541 if (!strcmp(context->orthancVersion, "mainline"))
1542 {
1543 return 1;
1544 }
1545
1546 /* Parse the version of the Orthanc core */
1547 if (
1548 #ifdef _MSC_VER
1549 sscanf_s
1550 #else
1551 sscanf
1552 #endif
1553 (context->orthancVersion, "%4d.%4d.%4d", &major, &minor, &revision) != 3)
1554 {
1555 return 0;
1556 }
1557
1558 /* Check the major number of the version */
1559
1560 if (major > expectedMajor)
1561 {
1562 return 1;
1563 }
1564
1565 if (major < expectedMajor)
1566 {
1567 return 0;
1568 }
1569
1570 /* Check the minor number of the version */
1571
1572 if (minor > expectedMinor)
1573 {
1574 return 1;
1575 }
1576
1577 if (minor < expectedMinor)
1578 {
1579 return 0;
1580 }
1581
1582 /* Check the revision number of the version */
1583
1584 if (revision >= expectedRevision)
1585 {
1586 return 1;
1587 }
1588 else
1589 {
1590 return 0;
1591 }
1592 }
1593
1594
1595 /**
1596 * @brief Check the compatibility of the plugin wrt. the version of its hosting Orthanc.
1597 *
1598 * This function checks whether the version of the Orthanc server
1599 * running this plugin, is above the version of the current Orthanc
1600 * SDK header. This guarantees that the plugin is compatible with
1601 * the hosting Orthanc (i.e. it will not call unavailable services).
1602 * The result of this function should always be checked in the
1603 * OrthancPluginInitialize() entry point of the plugin.
1604 *
1605 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1606 * @return 1 if and only if the versions are compatible. If the
1607 * result is 0, the initialization of the plugin should fail.
1608 * @see OrthancPluginCheckVersionAdvanced
1609 * @ingroup Callbacks
1610 **/
1611 ORTHANC_PLUGIN_INLINE int OrthancPluginCheckVersion(
1612 OrthancPluginContext* context)
1613 {
1614 return OrthancPluginCheckVersionAdvanced(
1615 context,
1616 ORTHANC_PLUGINS_MINIMAL_MAJOR_NUMBER,
1617 ORTHANC_PLUGINS_MINIMAL_MINOR_NUMBER,
1618 ORTHANC_PLUGINS_MINIMAL_REVISION_NUMBER);
1619 }
1620
1621
1622 /**
1623 * @brief Free a memory buffer.
1624 *
1625 * Free a memory buffer that was allocated by the core system of Orthanc.
1626 *
1627 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1628 * @param buffer The memory buffer to release.
1629 **/
1630 ORTHANC_PLUGIN_INLINE void OrthancPluginFreeMemoryBuffer(
1631 OrthancPluginContext* context,
1632 OrthancPluginMemoryBuffer* buffer)
1633 {
1634 context->Free(buffer->data);
1635 }
1636
1637
1638 /**
1639 * @brief Log an error.
1640 *
1641 * Log an error message using the Orthanc logging system.
1642 *
1643 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1644 * @param message The message to be logged.
1645 **/
1646 ORTHANC_PLUGIN_INLINE void OrthancPluginLogError(
1647 OrthancPluginContext* context,
1648 const char* message)
1649 {
1650 context->InvokeService(context, _OrthancPluginService_LogError, message);
1651 }
1652
1653
1654 /**
1655 * @brief Log a warning.
1656 *
1657 * Log a warning message using the Orthanc logging system.
1658 *
1659 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1660 * @param message The message to be logged.
1661 **/
1662 ORTHANC_PLUGIN_INLINE void OrthancPluginLogWarning(
1663 OrthancPluginContext* context,
1664 const char* message)
1665 {
1666 context->InvokeService(context, _OrthancPluginService_LogWarning, message);
1667 }
1668
1669
1670 /**
1671 * @brief Log an information.
1672 *
1673 * Log an information message using the Orthanc logging system.
1674 *
1675 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1676 * @param message The message to be logged.
1677 **/
1678 ORTHANC_PLUGIN_INLINE void OrthancPluginLogInfo(
1679 OrthancPluginContext* context,
1680 const char* message)
1681 {
1682 context->InvokeService(context, _OrthancPluginService_LogInfo, message);
1683 }
1684
1685
1686
1687 typedef struct
1688 {
1689 const char* pathRegularExpression;
1690 OrthancPluginRestCallback callback;
1691 } _OrthancPluginRestCallback;
1692
1693 /**
1694 * @brief Register a REST callback.
1695 *
1696 * This function registers a REST callback against a regular
1697 * expression for a URI. This function must be called during the
1698 * initialization of the plugin, i.e. inside the
1699 * OrthancPluginInitialize() public function.
1700 *
1701 * Each REST callback is guaranteed to run in mutual exclusion.
1702 *
1703 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1704 * @param pathRegularExpression Regular expression for the URI. May contain groups.
1705 * @param callback The callback function to handle the REST call.
1706 * @see OrthancPluginRegisterRestCallbackNoLock()
1707 *
1708 * @note
1709 * The regular expression is case sensitive and must follow the
1710 * [Perl syntax](https://www.boost.org/doc/libs/1_67_0/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html).
1711 *
1712 * @ingroup Callbacks
1713 **/
1714 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterRestCallback(
1715 OrthancPluginContext* context,
1716 const char* pathRegularExpression,
1717 OrthancPluginRestCallback callback)
1718 {
1719 _OrthancPluginRestCallback params;
1720 params.pathRegularExpression = pathRegularExpression;
1721 params.callback = callback;
1722 context->InvokeService(context, _OrthancPluginService_RegisterRestCallback, &params);
1723 }
1724
1725
1726
1727 /**
1728 * @brief Register a REST callback, without locking.
1729 *
1730 * This function registers a REST callback against a regular
1731 * expression for a URI. This function must be called during the
1732 * initialization of the plugin, i.e. inside the
1733 * OrthancPluginInitialize() public function.
1734 *
1735 * Contrarily to OrthancPluginRegisterRestCallback(), the callback
1736 * will NOT be invoked in mutual exclusion. This can be useful for
1737 * high-performance plugins that must handle concurrent requests
1738 * (Orthanc uses a pool of threads, one thread being assigned to
1739 * each incoming HTTP request). Of course, if using this function,
1740 * it is up to the plugin to implement the required locking
1741 * mechanisms.
1742 *
1743 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1744 * @param pathRegularExpression Regular expression for the URI. May contain groups.
1745 * @param callback The callback function to handle the REST call.
1746 * @see OrthancPluginRegisterRestCallback()
1747 *
1748 * @note
1749 * The regular expression is case sensitive and must follow the
1750 * [Perl syntax](https://www.boost.org/doc/libs/1_67_0/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html).
1751 *
1752 * @ingroup Callbacks
1753 **/
1754 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterRestCallbackNoLock(
1755 OrthancPluginContext* context,
1756 const char* pathRegularExpression,
1757 OrthancPluginRestCallback callback)
1758 {
1759 _OrthancPluginRestCallback params;
1760 params.pathRegularExpression = pathRegularExpression;
1761 params.callback = callback;
1762 context->InvokeService(context, _OrthancPluginService_RegisterRestCallbackNoLock, &params);
1763 }
1764
1765
1766
1767 typedef struct
1768 {
1769 OrthancPluginOnStoredInstanceCallback callback;
1770 } _OrthancPluginOnStoredInstanceCallback;
1771
1772 /**
1773 * @brief Register a callback for received instances.
1774 *
1775 * This function registers a callback function that is called
1776 * whenever a new DICOM instance is stored into the Orthanc core.
1777 *
1778 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1779 * @param callback The callback function.
1780 * @ingroup Callbacks
1781 **/
1782 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterOnStoredInstanceCallback(
1783 OrthancPluginContext* context,
1784 OrthancPluginOnStoredInstanceCallback callback)
1785 {
1786 _OrthancPluginOnStoredInstanceCallback params;
1787 params.callback = callback;
1788
1789 context->InvokeService(context, _OrthancPluginService_RegisterOnStoredInstanceCallback, &params);
1790 }
1791
1792
1793
1794 typedef struct
1795 {
1796 OrthancPluginRestOutput* output;
1797 const char* answer;
1798 uint32_t answerSize;
1799 const char* mimeType;
1800 } _OrthancPluginAnswerBuffer;
1801
1802 /**
1803 * @brief Answer to a REST request.
1804 *
1805 * This function answers to a REST request with the content of a memory buffer.
1806 *
1807 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1808 * @param output The HTTP connection to the client application.
1809 * @param answer Pointer to the memory buffer containing the answer.
1810 * @param answerSize Number of bytes of the answer.
1811 * @param mimeType The MIME type of the answer.
1812 * @ingroup REST
1813 **/
1814 ORTHANC_PLUGIN_INLINE void OrthancPluginAnswerBuffer(
1815 OrthancPluginContext* context,
1816 OrthancPluginRestOutput* output,
1817 const char* answer,
1818 uint32_t answerSize,
1819 const char* mimeType)
1820 {
1821 _OrthancPluginAnswerBuffer params;
1822 params.output = output;
1823 params.answer = answer;
1824 params.answerSize = answerSize;
1825 params.mimeType = mimeType;
1826 context->InvokeService(context, _OrthancPluginService_AnswerBuffer, &params);
1827 }
1828
1829
1830 typedef struct
1831 {
1832 OrthancPluginRestOutput* output;
1833 OrthancPluginPixelFormat format;
1834 uint32_t width;
1835 uint32_t height;
1836 uint32_t pitch;
1837 const void* buffer;
1838 } _OrthancPluginCompressAndAnswerPngImage;
1839
1840 typedef struct
1841 {
1842 OrthancPluginRestOutput* output;
1843 OrthancPluginImageFormat imageFormat;
1844 OrthancPluginPixelFormat pixelFormat;
1845 uint32_t width;
1846 uint32_t height;
1847 uint32_t pitch;
1848 const void* buffer;
1849 uint8_t quality;
1850 } _OrthancPluginCompressAndAnswerImage;
1851
1852
1853 /**
1854 * @brief Answer to a REST request with a PNG image.
1855 *
1856 * This function answers to a REST request with a PNG image. The
1857 * parameters of this function describe a memory buffer that
1858 * contains an uncompressed image. The image will be automatically compressed
1859 * as a PNG image by the core system of Orthanc.
1860 *
1861 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1862 * @param output The HTTP connection to the client application.
1863 * @param format The memory layout of the uncompressed image.
1864 * @param width The width of the image.
1865 * @param height The height of the image.
1866 * @param pitch The pitch of the image (i.e. the number of bytes
1867 * between 2 successive lines of the image in the memory buffer).
1868 * @param buffer The memory buffer containing the uncompressed image.
1869 * @ingroup REST
1870 **/
1871 ORTHANC_PLUGIN_INLINE void OrthancPluginCompressAndAnswerPngImage(
1872 OrthancPluginContext* context,
1873 OrthancPluginRestOutput* output,
1874 OrthancPluginPixelFormat format,
1875 uint32_t width,
1876 uint32_t height,
1877 uint32_t pitch,
1878 const void* buffer)
1879 {
1880 _OrthancPluginCompressAndAnswerImage params;
1881 params.output = output;
1882 params.imageFormat = OrthancPluginImageFormat_Png;
1883 params.pixelFormat = format;
1884 params.width = width;
1885 params.height = height;
1886 params.pitch = pitch;
1887 params.buffer = buffer;
1888 params.quality = 0; /* No quality for PNG */
1889 context->InvokeService(context, _OrthancPluginService_CompressAndAnswerImage, &params);
1890 }
1891
1892
1893
1894 typedef struct
1895 {
1896 OrthancPluginMemoryBuffer* target;
1897 const char* instanceId;
1898 } _OrthancPluginGetDicomForInstance;
1899
1900 /**
1901 * @brief Retrieve a DICOM instance using its Orthanc identifier.
1902 *
1903 * Retrieve a DICOM instance using its Orthanc identifier. The DICOM
1904 * file is stored into a newly allocated memory buffer.
1905 *
1906 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1907 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
1908 * @param instanceId The Orthanc identifier of the DICOM instance of interest.
1909 * @return 0 if success, or the error code if failure.
1910 * @ingroup Orthanc
1911 **/
1912 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginGetDicomForInstance(
1913 OrthancPluginContext* context,
1914 OrthancPluginMemoryBuffer* target,
1915 const char* instanceId)
1916 {
1917 _OrthancPluginGetDicomForInstance params;
1918 params.target = target;
1919 params.instanceId = instanceId;
1920 return context->InvokeService(context, _OrthancPluginService_GetDicomForInstance, &params);
1921 }
1922
1923
1924
1925 typedef struct
1926 {
1927 OrthancPluginMemoryBuffer* target;
1928 const char* uri;
1929 } _OrthancPluginRestApiGet;
1930
1931 /**
1932 * @brief Make a GET call to the built-in Orthanc REST API.
1933 *
1934 * Make a GET call to the built-in Orthanc REST API. The result to
1935 * the query is stored into a newly allocated memory buffer.
1936 *
1937 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1938 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
1939 * @param uri The URI in the built-in Orthanc API.
1940 * @return 0 if success, or the error code if failure.
1941 * @note If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.
1942 * @see OrthancPluginRestApiGetAfterPlugins
1943 * @ingroup Orthanc
1944 **/
1945 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRestApiGet(
1946 OrthancPluginContext* context,
1947 OrthancPluginMemoryBuffer* target,
1948 const char* uri)
1949 {
1950 _OrthancPluginRestApiGet params;
1951 params.target = target;
1952 params.uri = uri;
1953 return context->InvokeService(context, _OrthancPluginService_RestApiGet, &params);
1954 }
1955
1956
1957
1958 /**
1959 * @brief Make a GET call to the REST API, as tainted by the plugins.
1960 *
1961 * Make a GET call to the Orthanc REST API, after all the plugins
1962 * are applied. In other words, if some plugin overrides or adds the
1963 * called URI to the built-in Orthanc REST API, this call will
1964 * return the result provided by this plugin. The result to the
1965 * query is stored into a newly allocated memory buffer.
1966 *
1967 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
1968 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
1969 * @param uri The URI in the built-in Orthanc API.
1970 * @return 0 if success, or the error code if failure.
1971 * @note If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.
1972 * @see OrthancPluginRestApiGet
1973 * @ingroup Orthanc
1974 **/
1975 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRestApiGetAfterPlugins(
1976 OrthancPluginContext* context,
1977 OrthancPluginMemoryBuffer* target,
1978 const char* uri)
1979 {
1980 _OrthancPluginRestApiGet params;
1981 params.target = target;
1982 params.uri = uri;
1983 return context->InvokeService(context, _OrthancPluginService_RestApiGetAfterPlugins, &params);
1984 }
1985
1986
1987
1988 typedef struct
1989 {
1990 OrthancPluginMemoryBuffer* target;
1991 const char* uri;
1992 const char* body;
1993 uint32_t bodySize;
1994 } _OrthancPluginRestApiPostPut;
1995
1996 /**
1997 * @brief Make a POST call to the built-in Orthanc REST API.
1998 *
1999 * Make a POST call to the built-in Orthanc REST API. The result to
2000 * the query is stored into a newly allocated memory buffer.
2001 *
2002 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2003 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
2004 * @param uri The URI in the built-in Orthanc API.
2005 * @param body The body of the POST request.
2006 * @param bodySize The size of the body.
2007 * @return 0 if success, or the error code if failure.
2008 * @note If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.
2009 * @see OrthancPluginRestApiPostAfterPlugins
2010 * @ingroup Orthanc
2011 **/
2012 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRestApiPost(
2013 OrthancPluginContext* context,
2014 OrthancPluginMemoryBuffer* target,
2015 const char* uri,
2016 const char* body,
2017 uint32_t bodySize)
2018 {
2019 _OrthancPluginRestApiPostPut params;
2020 params.target = target;
2021 params.uri = uri;
2022 params.body = body;
2023 params.bodySize = bodySize;
2024 return context->InvokeService(context, _OrthancPluginService_RestApiPost, &params);
2025 }
2026
2027
2028 /**
2029 * @brief Make a POST call to the REST API, as tainted by the plugins.
2030 *
2031 * Make a POST call to the Orthanc REST API, after all the plugins
2032 * are applied. In other words, if some plugin overrides or adds the
2033 * called URI to the built-in Orthanc REST API, this call will
2034 * return the result provided by this plugin. The result to the
2035 * query is stored into a newly allocated memory buffer.
2036 *
2037 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2038 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
2039 * @param uri The URI in the built-in Orthanc API.
2040 * @param body The body of the POST request.
2041 * @param bodySize The size of the body.
2042 * @return 0 if success, or the error code if failure.
2043 * @note If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.
2044 * @see OrthancPluginRestApiPost
2045 * @ingroup Orthanc
2046 **/
2047 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRestApiPostAfterPlugins(
2048 OrthancPluginContext* context,
2049 OrthancPluginMemoryBuffer* target,
2050 const char* uri,
2051 const char* body,
2052 uint32_t bodySize)
2053 {
2054 _OrthancPluginRestApiPostPut params;
2055 params.target = target;
2056 params.uri = uri;
2057 params.body = body;
2058 params.bodySize = bodySize;
2059 return context->InvokeService(context, _OrthancPluginService_RestApiPostAfterPlugins, &params);
2060 }
2061
2062
2063
2064 /**
2065 * @brief Make a DELETE call to the built-in Orthanc REST API.
2066 *
2067 * Make a DELETE call to the built-in Orthanc REST API.
2068 *
2069 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2070 * @param uri The URI to delete in the built-in Orthanc API.
2071 * @return 0 if success, or the error code if failure.
2072 * @note If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.
2073 * @see OrthancPluginRestApiDeleteAfterPlugins
2074 * @ingroup Orthanc
2075 **/
2076 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRestApiDelete(
2077 OrthancPluginContext* context,
2078 const char* uri)
2079 {
2080 return context->InvokeService(context, _OrthancPluginService_RestApiDelete, uri);
2081 }
2082
2083
2084 /**
2085 * @brief Make a DELETE call to the REST API, as tainted by the plugins.
2086 *
2087 * Make a DELETE call to the Orthanc REST API, after all the plugins
2088 * are applied. In other words, if some plugin overrides or adds the
2089 * called URI to the built-in Orthanc REST API, this call will
2090 * return the result provided by this plugin.
2091 *
2092 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2093 * @param uri The URI to delete in the built-in Orthanc API.
2094 * @return 0 if success, or the error code if failure.
2095 * @note If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.
2096 * @see OrthancPluginRestApiDelete
2097 * @ingroup Orthanc
2098 **/
2099 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRestApiDeleteAfterPlugins(
2100 OrthancPluginContext* context,
2101 const char* uri)
2102 {
2103 return context->InvokeService(context, _OrthancPluginService_RestApiDeleteAfterPlugins, uri);
2104 }
2105
2106
2107
2108 /**
2109 * @brief Make a PUT call to the built-in Orthanc REST API.
2110 *
2111 * Make a PUT call to the built-in Orthanc REST API. The result to
2112 * the query is stored into a newly allocated memory buffer.
2113 *
2114 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2115 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
2116 * @param uri The URI in the built-in Orthanc API.
2117 * @param body The body of the PUT request.
2118 * @param bodySize The size of the body.
2119 * @return 0 if success, or the error code if failure.
2120 * @note If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.
2121 * @see OrthancPluginRestApiPutAfterPlugins
2122 * @ingroup Orthanc
2123 **/
2124 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRestApiPut(
2125 OrthancPluginContext* context,
2126 OrthancPluginMemoryBuffer* target,
2127 const char* uri,
2128 const char* body,
2129 uint32_t bodySize)
2130 {
2131 _OrthancPluginRestApiPostPut params;
2132 params.target = target;
2133 params.uri = uri;
2134 params.body = body;
2135 params.bodySize = bodySize;
2136 return context->InvokeService(context, _OrthancPluginService_RestApiPut, &params);
2137 }
2138
2139
2140
2141 /**
2142 * @brief Make a PUT call to the REST API, as tainted by the plugins.
2143 *
2144 * Make a PUT call to the Orthanc REST API, after all the plugins
2145 * are applied. In other words, if some plugin overrides or adds the
2146 * called URI to the built-in Orthanc REST API, this call will
2147 * return the result provided by this plugin. The result to the
2148 * query is stored into a newly allocated memory buffer.
2149 *
2150 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2151 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
2152 * @param uri The URI in the built-in Orthanc API.
2153 * @param body The body of the PUT request.
2154 * @param bodySize The size of the body.
2155 * @return 0 if success, or the error code if failure.
2156 * @note If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.
2157 * @see OrthancPluginRestApiPut
2158 * @ingroup Orthanc
2159 **/
2160 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRestApiPutAfterPlugins(
2161 OrthancPluginContext* context,
2162 OrthancPluginMemoryBuffer* target,
2163 const char* uri,
2164 const char* body,
2165 uint32_t bodySize)
2166 {
2167 _OrthancPluginRestApiPostPut params;
2168 params.target = target;
2169 params.uri = uri;
2170 params.body = body;
2171 params.bodySize = bodySize;
2172 return context->InvokeService(context, _OrthancPluginService_RestApiPutAfterPlugins, &params);
2173 }
2174
2175
2176
2177 typedef struct
2178 {
2179 OrthancPluginRestOutput* output;
2180 const char* argument;
2181 } _OrthancPluginOutputPlusArgument;
2182
2183 /**
2184 * @brief Redirect a REST request.
2185 *
2186 * This function answers to a REST request by redirecting the user
2187 * to another URI using HTTP status 301.
2188 *
2189 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2190 * @param output The HTTP connection to the client application.
2191 * @param redirection Where to redirect.
2192 * @ingroup REST
2193 **/
2194 ORTHANC_PLUGIN_INLINE void OrthancPluginRedirect(
2195 OrthancPluginContext* context,
2196 OrthancPluginRestOutput* output,
2197 const char* redirection)
2198 {
2199 _OrthancPluginOutputPlusArgument params;
2200 params.output = output;
2201 params.argument = redirection;
2202 context->InvokeService(context, _OrthancPluginService_Redirect, &params);
2203 }
2204
2205
2206
2207 typedef struct
2208 {
2209 char** result;
2210 const char* argument;
2211 } _OrthancPluginRetrieveDynamicString;
2212
2213 /**
2214 * @brief Look for a patient.
2215 *
2216 * Look for a patient stored in Orthanc, using its Patient ID tag (0x0010, 0x0020).
2217 * This function uses the database index to run as fast as possible (it does not loop
2218 * over all the stored patients).
2219 *
2220 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2221 * @param patientID The Patient ID of interest.
2222 * @return The NULL value if the patient is non-existent, or a string containing the
2223 * Orthanc ID of the patient. This string must be freed by OrthancPluginFreeString().
2224 * @ingroup Orthanc
2225 **/
2226 ORTHANC_PLUGIN_INLINE char* OrthancPluginLookupPatient(
2227 OrthancPluginContext* context,
2228 const char* patientID)
2229 {
2230 char* result;
2231
2232 _OrthancPluginRetrieveDynamicString params;
2233 params.result = &result;
2234 params.argument = patientID;
2235
2236 if (context->InvokeService(context, _OrthancPluginService_LookupPatient, &params) != OrthancPluginErrorCode_Success)
2237 {
2238 /* Error */
2239 return NULL;
2240 }
2241 else
2242 {
2243 return result;
2244 }
2245 }
2246
2247
2248 /**
2249 * @brief Look for a study.
2250 *
2251 * Look for a study stored in Orthanc, using its Study Instance UID tag (0x0020, 0x000d).
2252 * This function uses the database index to run as fast as possible (it does not loop
2253 * over all the stored studies).
2254 *
2255 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2256 * @param studyUID The Study Instance UID of interest.
2257 * @return The NULL value if the study is non-existent, or a string containing the
2258 * Orthanc ID of the study. This string must be freed by OrthancPluginFreeString().
2259 * @ingroup Orthanc
2260 **/
2261 ORTHANC_PLUGIN_INLINE char* OrthancPluginLookupStudy(
2262 OrthancPluginContext* context,
2263 const char* studyUID)
2264 {
2265 char* result;
2266
2267 _OrthancPluginRetrieveDynamicString params;
2268 params.result = &result;
2269 params.argument = studyUID;
2270
2271 if (context->InvokeService(context, _OrthancPluginService_LookupStudy, &params) != OrthancPluginErrorCode_Success)
2272 {
2273 /* Error */
2274 return NULL;
2275 }
2276 else
2277 {
2278 return result;
2279 }
2280 }
2281
2282
2283 /**
2284 * @brief Look for a study, using the accession number.
2285 *
2286 * Look for a study stored in Orthanc, using its Accession Number tag (0x0008, 0x0050).
2287 * This function uses the database index to run as fast as possible (it does not loop
2288 * over all the stored studies).
2289 *
2290 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2291 * @param accessionNumber The Accession Number of interest.
2292 * @return The NULL value if the study is non-existent, or a string containing the
2293 * Orthanc ID of the study. This string must be freed by OrthancPluginFreeString().
2294 * @ingroup Orthanc
2295 **/
2296 ORTHANC_PLUGIN_INLINE char* OrthancPluginLookupStudyWithAccessionNumber(
2297 OrthancPluginContext* context,
2298 const char* accessionNumber)
2299 {
2300 char* result;
2301
2302 _OrthancPluginRetrieveDynamicString params;
2303 params.result = &result;
2304 params.argument = accessionNumber;
2305
2306 if (context->InvokeService(context, _OrthancPluginService_LookupStudyWithAccessionNumber, &params) != OrthancPluginErrorCode_Success)
2307 {
2308 /* Error */
2309 return NULL;
2310 }
2311 else
2312 {
2313 return result;
2314 }
2315 }
2316
2317
2318 /**
2319 * @brief Look for a series.
2320 *
2321 * Look for a series stored in Orthanc, using its Series Instance UID tag (0x0020, 0x000e).
2322 * This function uses the database index to run as fast as possible (it does not loop
2323 * over all the stored series).
2324 *
2325 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2326 * @param seriesUID The Series Instance UID of interest.
2327 * @return The NULL value if the series is non-existent, or a string containing the
2328 * Orthanc ID of the series. This string must be freed by OrthancPluginFreeString().
2329 * @ingroup Orthanc
2330 **/
2331 ORTHANC_PLUGIN_INLINE char* OrthancPluginLookupSeries(
2332 OrthancPluginContext* context,
2333 const char* seriesUID)
2334 {
2335 char* result;
2336
2337 _OrthancPluginRetrieveDynamicString params;
2338 params.result = &result;
2339 params.argument = seriesUID;
2340
2341 if (context->InvokeService(context, _OrthancPluginService_LookupSeries, &params) != OrthancPluginErrorCode_Success)
2342 {
2343 /* Error */
2344 return NULL;
2345 }
2346 else
2347 {
2348 return result;
2349 }
2350 }
2351
2352
2353 /**
2354 * @brief Look for an instance.
2355 *
2356 * Look for an instance stored in Orthanc, using its SOP Instance UID tag (0x0008, 0x0018).
2357 * This function uses the database index to run as fast as possible (it does not loop
2358 * over all the stored instances).
2359 *
2360 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2361 * @param sopInstanceUID The SOP Instance UID of interest.
2362 * @return The NULL value if the instance is non-existent, or a string containing the
2363 * Orthanc ID of the instance. This string must be freed by OrthancPluginFreeString().
2364 * @ingroup Orthanc
2365 **/
2366 ORTHANC_PLUGIN_INLINE char* OrthancPluginLookupInstance(
2367 OrthancPluginContext* context,
2368 const char* sopInstanceUID)
2369 {
2370 char* result;
2371
2372 _OrthancPluginRetrieveDynamicString params;
2373 params.result = &result;
2374 params.argument = sopInstanceUID;
2375
2376 if (context->InvokeService(context, _OrthancPluginService_LookupInstance, &params) != OrthancPluginErrorCode_Success)
2377 {
2378 /* Error */
2379 return NULL;
2380 }
2381 else
2382 {
2383 return result;
2384 }
2385 }
2386
2387
2388
2389 typedef struct
2390 {
2391 OrthancPluginRestOutput* output;
2392 uint16_t status;
2393 } _OrthancPluginSendHttpStatusCode;
2394
2395 /**
2396 * @brief Send a HTTP status code.
2397 *
2398 * This function answers to a REST request by sending a HTTP status
2399 * code (such as "400 - Bad Request"). Note that:
2400 * - Successful requests (status 200) must use ::OrthancPluginAnswerBuffer().
2401 * - Redirections (status 301) must use ::OrthancPluginRedirect().
2402 * - Unauthorized access (status 401) must use ::OrthancPluginSendUnauthorized().
2403 * - Methods not allowed (status 405) must use ::OrthancPluginSendMethodNotAllowed().
2404 *
2405 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2406 * @param output The HTTP connection to the client application.
2407 * @param status The HTTP status code to be sent.
2408 * @ingroup REST
2409 * @see OrthancPluginSendHttpStatus()
2410 **/
2411 ORTHANC_PLUGIN_INLINE void OrthancPluginSendHttpStatusCode(
2412 OrthancPluginContext* context,
2413 OrthancPluginRestOutput* output,
2414 uint16_t status)
2415 {
2416 _OrthancPluginSendHttpStatusCode params;
2417 params.output = output;
2418 params.status = status;
2419 context->InvokeService(context, _OrthancPluginService_SendHttpStatusCode, &params);
2420 }
2421
2422
2423 /**
2424 * @brief Signal that a REST request is not authorized.
2425 *
2426 * This function answers to a REST request by signaling that it is
2427 * not authorized.
2428 *
2429 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2430 * @param output The HTTP connection to the client application.
2431 * @param realm The realm for the authorization process.
2432 * @ingroup REST
2433 **/
2434 ORTHANC_PLUGIN_INLINE void OrthancPluginSendUnauthorized(
2435 OrthancPluginContext* context,
2436 OrthancPluginRestOutput* output,
2437 const char* realm)
2438 {
2439 _OrthancPluginOutputPlusArgument params;
2440 params.output = output;
2441 params.argument = realm;
2442 context->InvokeService(context, _OrthancPluginService_SendUnauthorized, &params);
2443 }
2444
2445
2446 /**
2447 * @brief Signal that this URI does not support this HTTP method.
2448 *
2449 * This function answers to a REST request by signaling that the
2450 * queried URI does not support this method.
2451 *
2452 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2453 * @param output The HTTP connection to the client application.
2454 * @param allowedMethods The allowed methods for this URI (e.g. "GET,POST" after a PUT or a POST request).
2455 * @ingroup REST
2456 **/
2457 ORTHANC_PLUGIN_INLINE void OrthancPluginSendMethodNotAllowed(
2458 OrthancPluginContext* context,
2459 OrthancPluginRestOutput* output,
2460 const char* allowedMethods)
2461 {
2462 _OrthancPluginOutputPlusArgument params;
2463 params.output = output;
2464 params.argument = allowedMethods;
2465 context->InvokeService(context, _OrthancPluginService_SendMethodNotAllowed, &params);
2466 }
2467
2468
2469 typedef struct
2470 {
2471 OrthancPluginRestOutput* output;
2472 const char* key;
2473 const char* value;
2474 } _OrthancPluginSetHttpHeader;
2475
2476 /**
2477 * @brief Set a cookie.
2478 *
2479 * This function sets a cookie in the HTTP client.
2480 *
2481 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2482 * @param output The HTTP connection to the client application.
2483 * @param cookie The cookie to be set.
2484 * @param value The value of the cookie.
2485 * @ingroup REST
2486 **/
2487 ORTHANC_PLUGIN_INLINE void OrthancPluginSetCookie(
2488 OrthancPluginContext* context,
2489 OrthancPluginRestOutput* output,
2490 const char* cookie,
2491 const char* value)
2492 {
2493 _OrthancPluginSetHttpHeader params;
2494 params.output = output;
2495 params.key = cookie;
2496 params.value = value;
2497 context->InvokeService(context, _OrthancPluginService_SetCookie, &params);
2498 }
2499
2500
2501 /**
2502 * @brief Set some HTTP header.
2503 *
2504 * This function sets a HTTP header in the HTTP answer.
2505 *
2506 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2507 * @param output The HTTP connection to the client application.
2508 * @param key The HTTP header to be set.
2509 * @param value The value of the HTTP header.
2510 * @ingroup REST
2511 **/
2512 ORTHANC_PLUGIN_INLINE void OrthancPluginSetHttpHeader(
2513 OrthancPluginContext* context,
2514 OrthancPluginRestOutput* output,
2515 const char* key,
2516 const char* value)
2517 {
2518 _OrthancPluginSetHttpHeader params;
2519 params.output = output;
2520 params.key = key;
2521 params.value = value;
2522 context->InvokeService(context, _OrthancPluginService_SetHttpHeader, &params);
2523 }
2524
2525
2526 typedef struct
2527 {
2528 char** resultStringToFree;
2529 const char** resultString;
2530 int64_t* resultInt64;
2531 const char* key;
2532 OrthancPluginDicomInstance* instance;
2533 OrthancPluginInstanceOrigin* resultOrigin; /* New in Orthanc 0.9.5 SDK */
2534 } _OrthancPluginAccessDicomInstance;
2535
2536
2537 /**
2538 * @brief Get the AET of a DICOM instance.
2539 *
2540 * This function returns the Application Entity Title (AET) of the
2541 * DICOM modality from which a DICOM instance originates.
2542 *
2543 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2544 * @param instance The instance of interest.
2545 * @return The AET if success, NULL if error.
2546 * @ingroup Callbacks
2547 **/
2548 ORTHANC_PLUGIN_INLINE const char* OrthancPluginGetInstanceRemoteAet(
2549 OrthancPluginContext* context,
2550 OrthancPluginDicomInstance* instance)
2551 {
2552 const char* result;
2553
2554 _OrthancPluginAccessDicomInstance params;
2555 memset(&params, 0, sizeof(params));
2556 params.resultString = &result;
2557 params.instance = instance;
2558
2559 if (context->InvokeService(context, _OrthancPluginService_GetInstanceRemoteAet, &params) != OrthancPluginErrorCode_Success)
2560 {
2561 /* Error */
2562 return NULL;
2563 }
2564 else
2565 {
2566 return result;
2567 }
2568 }
2569
2570
2571 /**
2572 * @brief Get the size of a DICOM file.
2573 *
2574 * This function returns the number of bytes of the given DICOM instance.
2575 *
2576 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2577 * @param instance The instance of interest.
2578 * @return The size of the file, -1 in case of error.
2579 * @ingroup Callbacks
2580 **/
2581 ORTHANC_PLUGIN_INLINE int64_t OrthancPluginGetInstanceSize(
2582 OrthancPluginContext* context,
2583 OrthancPluginDicomInstance* instance)
2584 {
2585 int64_t size;
2586
2587 _OrthancPluginAccessDicomInstance params;
2588 memset(&params, 0, sizeof(params));
2589 params.resultInt64 = &size;
2590 params.instance = instance;
2591
2592 if (context->InvokeService(context, _OrthancPluginService_GetInstanceSize, &params) != OrthancPluginErrorCode_Success)
2593 {
2594 /* Error */
2595 return -1;
2596 }
2597 else
2598 {
2599 return size;
2600 }
2601 }
2602
2603
2604 /**
2605 * @brief Get the data of a DICOM file.
2606 *
2607 * This function returns a pointer to the content of the given DICOM instance.
2608 *
2609 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2610 * @param instance The instance of interest.
2611 * @return The pointer to the DICOM data, NULL in case of error.
2612 * @ingroup Callbacks
2613 **/
2614 ORTHANC_PLUGIN_INLINE const char* OrthancPluginGetInstanceData(
2615 OrthancPluginContext* context,
2616 OrthancPluginDicomInstance* instance)
2617 {
2618 const char* result;
2619
2620 _OrthancPluginAccessDicomInstance params;
2621 memset(&params, 0, sizeof(params));
2622 params.resultString = &result;
2623 params.instance = instance;
2624
2625 if (context->InvokeService(context, _OrthancPluginService_GetInstanceData, &params) != OrthancPluginErrorCode_Success)
2626 {
2627 /* Error */
2628 return NULL;
2629 }
2630 else
2631 {
2632 return result;
2633 }
2634 }
2635
2636
2637 /**
2638 * @brief Get the DICOM tag hierarchy as a JSON file.
2639 *
2640 * This function returns a pointer to a newly created string
2641 * containing a JSON file. This JSON file encodes the tag hierarchy
2642 * of the given DICOM instance.
2643 *
2644 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2645 * @param instance The instance of interest.
2646 * @return The NULL value in case of error, or a string containing the JSON file.
2647 * This string must be freed by OrthancPluginFreeString().
2648 * @ingroup Callbacks
2649 **/
2650 ORTHANC_PLUGIN_INLINE char* OrthancPluginGetInstanceJson(
2651 OrthancPluginContext* context,
2652 OrthancPluginDicomInstance* instance)
2653 {
2654 char* result;
2655
2656 _OrthancPluginAccessDicomInstance params;
2657 memset(&params, 0, sizeof(params));
2658 params.resultStringToFree = &result;
2659 params.instance = instance;
2660
2661 if (context->InvokeService(context, _OrthancPluginService_GetInstanceJson, &params) != OrthancPluginErrorCode_Success)
2662 {
2663 /* Error */
2664 return NULL;
2665 }
2666 else
2667 {
2668 return result;
2669 }
2670 }
2671
2672
2673 /**
2674 * @brief Get the DICOM tag hierarchy as a JSON file (with simplification).
2675 *
2676 * This function returns a pointer to a newly created string
2677 * containing a JSON file. This JSON file encodes the tag hierarchy
2678 * of the given DICOM instance. In contrast with
2679 * ::OrthancPluginGetInstanceJson(), the returned JSON file is in
2680 * its simplified version.
2681 *
2682 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2683 * @param instance The instance of interest.
2684 * @return The NULL value in case of error, or a string containing the JSON file.
2685 * This string must be freed by OrthancPluginFreeString().
2686 * @ingroup Callbacks
2687 **/
2688 ORTHANC_PLUGIN_INLINE char* OrthancPluginGetInstanceSimplifiedJson(
2689 OrthancPluginContext* context,
2690 OrthancPluginDicomInstance* instance)
2691 {
2692 char* result;
2693
2694 _OrthancPluginAccessDicomInstance params;
2695 memset(&params, 0, sizeof(params));
2696 params.resultStringToFree = &result;
2697 params.instance = instance;
2698
2699 if (context->InvokeService(context, _OrthancPluginService_GetInstanceSimplifiedJson, &params) != OrthancPluginErrorCode_Success)
2700 {
2701 /* Error */
2702 return NULL;
2703 }
2704 else
2705 {
2706 return result;
2707 }
2708 }
2709
2710
2711 /**
2712 * @brief Check whether a DICOM instance is associated with some metadata.
2713 *
2714 * This function checks whether the DICOM instance of interest is
2715 * associated with some metadata. As of Orthanc 0.8.1, in the
2716 * callbacks registered by
2717 * ::OrthancPluginRegisterOnStoredInstanceCallback(), the only
2718 * possibly available metadata are "ReceptionDate", "RemoteAET" and
2719 * "IndexInSeries".
2720 *
2721 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2722 * @param instance The instance of interest.
2723 * @param metadata The metadata of interest.
2724 * @return 1 if the metadata is present, 0 if it is absent, -1 in case of error.
2725 * @ingroup Callbacks
2726 **/
2727 ORTHANC_PLUGIN_INLINE int OrthancPluginHasInstanceMetadata(
2728 OrthancPluginContext* context,
2729 OrthancPluginDicomInstance* instance,
2730 const char* metadata)
2731 {
2732 int64_t result;
2733
2734 _OrthancPluginAccessDicomInstance params;
2735 memset(&params, 0, sizeof(params));
2736 params.resultInt64 = &result;
2737 params.instance = instance;
2738 params.key = metadata;
2739
2740 if (context->InvokeService(context, _OrthancPluginService_HasInstanceMetadata, &params) != OrthancPluginErrorCode_Success)
2741 {
2742 /* Error */
2743 return -1;
2744 }
2745 else
2746 {
2747 return (result != 0);
2748 }
2749 }
2750
2751
2752 /**
2753 * @brief Get the value of some metadata associated with a given DICOM instance.
2754 *
2755 * This functions returns the value of some metadata that is associated with the DICOM instance of interest.
2756 * Before calling this function, the existence of the metadata must have been checked with
2757 * ::OrthancPluginHasInstanceMetadata().
2758 *
2759 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2760 * @param instance The instance of interest.
2761 * @param metadata The metadata of interest.
2762 * @return The metadata value if success, NULL if error.
2763 * @ingroup Callbacks
2764 **/
2765 ORTHANC_PLUGIN_INLINE const char* OrthancPluginGetInstanceMetadata(
2766 OrthancPluginContext* context,
2767 OrthancPluginDicomInstance* instance,
2768 const char* metadata)
2769 {
2770 const char* result;
2771
2772 _OrthancPluginAccessDicomInstance params;
2773 memset(&params, 0, sizeof(params));
2774 params.resultString = &result;
2775 params.instance = instance;
2776 params.key = metadata;
2777
2778 if (context->InvokeService(context, _OrthancPluginService_GetInstanceMetadata, &params) != OrthancPluginErrorCode_Success)
2779 {
2780 /* Error */
2781 return NULL;
2782 }
2783 else
2784 {
2785 return result;
2786 }
2787 }
2788
2789
2790
2791 typedef struct
2792 {
2793 OrthancPluginStorageCreate create;
2794 OrthancPluginStorageRead read;
2795 OrthancPluginStorageRemove remove;
2796 OrthancPluginFree free;
2797 } _OrthancPluginRegisterStorageArea;
2798
2799 /**
2800 * @brief Register a custom storage area.
2801 *
2802 * This function registers a custom storage area, to replace the
2803 * built-in way Orthanc stores its files on the filesystem. This
2804 * function must be called during the initialization of the plugin,
2805 * i.e. inside the OrthancPluginInitialize() public function.
2806 *
2807 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2808 * @param create The callback function to store a file on the custom storage area.
2809 * @param read The callback function to read a file from the custom storage area.
2810 * @param remove The callback function to remove a file from the custom storage area.
2811 * @ingroup Callbacks
2812 **/
2813 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterStorageArea(
2814 OrthancPluginContext* context,
2815 OrthancPluginStorageCreate create,
2816 OrthancPluginStorageRead read,
2817 OrthancPluginStorageRemove remove)
2818 {
2819 _OrthancPluginRegisterStorageArea params;
2820 params.create = create;
2821 params.read = read;
2822 params.remove = remove;
2823
2824 #ifdef __cplusplus
2825 params.free = ::free;
2826 #else
2827 params.free = free;
2828 #endif
2829
2830 context->InvokeService(context, _OrthancPluginService_RegisterStorageArea, &params);
2831 }
2832
2833
2834
2835 /**
2836 * @brief Return the path to the Orthanc executable.
2837 *
2838 * This function returns the path to the Orthanc executable.
2839 *
2840 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2841 * @return NULL in the case of an error, or a newly allocated string
2842 * containing the path. This string must be freed by
2843 * OrthancPluginFreeString().
2844 **/
2845 ORTHANC_PLUGIN_INLINE char *OrthancPluginGetOrthancPath(OrthancPluginContext* context)
2846 {
2847 char* result;
2848
2849 _OrthancPluginRetrieveDynamicString params;
2850 params.result = &result;
2851 params.argument = NULL;
2852
2853 if (context->InvokeService(context, _OrthancPluginService_GetOrthancPath, &params) != OrthancPluginErrorCode_Success)
2854 {
2855 /* Error */
2856 return NULL;
2857 }
2858 else
2859 {
2860 return result;
2861 }
2862 }
2863
2864
2865 /**
2866 * @brief Return the directory containing the Orthanc.
2867 *
2868 * This function returns the path to the directory containing the Orthanc executable.
2869 *
2870 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2871 * @return NULL in the case of an error, or a newly allocated string
2872 * containing the path. This string must be freed by
2873 * OrthancPluginFreeString().
2874 **/
2875 ORTHANC_PLUGIN_INLINE char *OrthancPluginGetOrthancDirectory(OrthancPluginContext* context)
2876 {
2877 char* result;
2878
2879 _OrthancPluginRetrieveDynamicString params;
2880 params.result = &result;
2881 params.argument = NULL;
2882
2883 if (context->InvokeService(context, _OrthancPluginService_GetOrthancDirectory, &params) != OrthancPluginErrorCode_Success)
2884 {
2885 /* Error */
2886 return NULL;
2887 }
2888 else
2889 {
2890 return result;
2891 }
2892 }
2893
2894
2895 /**
2896 * @brief Return the path to the configuration file(s).
2897 *
2898 * This function returns the path to the configuration file(s) that
2899 * was specified when starting Orthanc. Since version 0.9.1, this
2900 * path can refer to a folder that stores a set of configuration
2901 * files. This function is deprecated in favor of
2902 * OrthancPluginGetConfiguration().
2903 *
2904 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2905 * @return NULL in the case of an error, or a newly allocated string
2906 * containing the path. This string must be freed by
2907 * OrthancPluginFreeString().
2908 * @see OrthancPluginGetConfiguration()
2909 **/
2910 ORTHANC_PLUGIN_INLINE char *OrthancPluginGetConfigurationPath(OrthancPluginContext* context)
2911 {
2912 char* result;
2913
2914 _OrthancPluginRetrieveDynamicString params;
2915 params.result = &result;
2916 params.argument = NULL;
2917
2918 if (context->InvokeService(context, _OrthancPluginService_GetConfigurationPath, &params) != OrthancPluginErrorCode_Success)
2919 {
2920 /* Error */
2921 return NULL;
2922 }
2923 else
2924 {
2925 return result;
2926 }
2927 }
2928
2929
2930
2931 typedef struct
2932 {
2933 OrthancPluginOnChangeCallback callback;
2934 } _OrthancPluginOnChangeCallback;
2935
2936 /**
2937 * @brief Register a callback to monitor changes.
2938 *
2939 * This function registers a callback function that is called
2940 * whenever a change happens to some DICOM resource.
2941 *
2942 * @warning If your change callback has to call the REST API of
2943 * Orthanc, you should make these calls in a separate thread (with
2944 * the events passing through a message queue). Otherwise, this
2945 * could result in deadlocks in the presence of other plugins or Lua
2946 * scripts.
2947 *
2948 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2949 * @param callback The callback function.
2950 * @ingroup Callbacks
2951 **/
2952 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterOnChangeCallback(
2953 OrthancPluginContext* context,
2954 OrthancPluginOnChangeCallback callback)
2955 {
2956 _OrthancPluginOnChangeCallback params;
2957 params.callback = callback;
2958
2959 context->InvokeService(context, _OrthancPluginService_RegisterOnChangeCallback, &params);
2960 }
2961
2962
2963
2964 typedef struct
2965 {
2966 const char* plugin;
2967 _OrthancPluginProperty property;
2968 const char* value;
2969 } _OrthancPluginSetPluginProperty;
2970
2971
2972 /**
2973 * @brief Set the URI where the plugin provides its Web interface.
2974 *
2975 * For plugins that come with a Web interface, this function
2976 * declares the entry path where to find this interface. This
2977 * information is notably used in the "Plugins" page of Orthanc
2978 * Explorer.
2979 *
2980 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
2981 * @param uri The root URI for this plugin.
2982 **/
2983 ORTHANC_PLUGIN_INLINE void OrthancPluginSetRootUri(
2984 OrthancPluginContext* context,
2985 const char* uri)
2986 {
2987 _OrthancPluginSetPluginProperty params;
2988 params.plugin = OrthancPluginGetName();
2989 params.property = _OrthancPluginProperty_RootUri;
2990 params.value = uri;
2991
2992 context->InvokeService(context, _OrthancPluginService_SetPluginProperty, &params);
2993 }
2994
2995
2996 /**
2997 * @brief Set a description for this plugin.
2998 *
2999 * Set a description for this plugin. It is displayed in the
3000 * "Plugins" page of Orthanc Explorer.
3001 *
3002 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3003 * @param description The description.
3004 **/
3005 ORTHANC_PLUGIN_INLINE void OrthancPluginSetDescription(
3006 OrthancPluginContext* context,
3007 const char* description)
3008 {
3009 _OrthancPluginSetPluginProperty params;
3010 params.plugin = OrthancPluginGetName();
3011 params.property = _OrthancPluginProperty_Description;
3012 params.value = description;
3013
3014 context->InvokeService(context, _OrthancPluginService_SetPluginProperty, &params);
3015 }
3016
3017
3018 /**
3019 * @brief Extend the JavaScript code of Orthanc Explorer.
3020 *
3021 * Add JavaScript code to customize the default behavior of Orthanc
3022 * Explorer. This can for instance be used to add new buttons.
3023 *
3024 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3025 * @param javascript The custom JavaScript code.
3026 **/
3027 ORTHANC_PLUGIN_INLINE void OrthancPluginExtendOrthancExplorer(
3028 OrthancPluginContext* context,
3029 const char* javascript)
3030 {
3031 _OrthancPluginSetPluginProperty params;
3032 params.plugin = OrthancPluginGetName();
3033 params.property = _OrthancPluginProperty_OrthancExplorer;
3034 params.value = javascript;
3035
3036 context->InvokeService(context, _OrthancPluginService_SetPluginProperty, &params);
3037 }
3038
3039
3040 typedef struct
3041 {
3042 char** result;
3043 int32_t property;
3044 const char* value;
3045 } _OrthancPluginGlobalProperty;
3046
3047
3048 /**
3049 * @brief Get the value of a global property.
3050 *
3051 * Get the value of a global property that is stored in the Orthanc database. Global
3052 * properties whose index is below 1024 are reserved by Orthanc.
3053 *
3054 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3055 * @param property The global property of interest.
3056 * @param defaultValue The value to return, if the global property is unset.
3057 * @return The value of the global property, or NULL in the case of an error. This
3058 * string must be freed by OrthancPluginFreeString().
3059 * @ingroup Orthanc
3060 **/
3061 ORTHANC_PLUGIN_INLINE char* OrthancPluginGetGlobalProperty(
3062 OrthancPluginContext* context,
3063 int32_t property,
3064 const char* defaultValue)
3065 {
3066 char* result;
3067
3068 _OrthancPluginGlobalProperty params;
3069 params.result = &result;
3070 params.property = property;
3071 params.value = defaultValue;
3072
3073 if (context->InvokeService(context, _OrthancPluginService_GetGlobalProperty, &params) != OrthancPluginErrorCode_Success)
3074 {
3075 /* Error */
3076 return NULL;
3077 }
3078 else
3079 {
3080 return result;
3081 }
3082 }
3083
3084
3085 /**
3086 * @brief Set the value of a global property.
3087 *
3088 * Set the value of a global property into the Orthanc
3089 * database. Setting a global property can be used by plugins to
3090 * save their internal parameters. Plugins are only allowed to set
3091 * properties whose index are above or equal to 1024 (properties
3092 * below 1024 are read-only and reserved by Orthanc).
3093 *
3094 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3095 * @param property The global property of interest.
3096 * @param value The value to be set in the global property.
3097 * @return 0 if success, or the error code if failure.
3098 * @ingroup Orthanc
3099 **/
3100 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginSetGlobalProperty(
3101 OrthancPluginContext* context,
3102 int32_t property,
3103 const char* value)
3104 {
3105 _OrthancPluginGlobalProperty params;
3106 params.result = NULL;
3107 params.property = property;
3108 params.value = value;
3109
3110 return context->InvokeService(context, _OrthancPluginService_SetGlobalProperty, &params);
3111 }
3112
3113
3114
3115 typedef struct
3116 {
3117 int32_t *resultInt32;
3118 uint32_t *resultUint32;
3119 int64_t *resultInt64;
3120 uint64_t *resultUint64;
3121 } _OrthancPluginReturnSingleValue;
3122
3123 /**
3124 * @brief Get the number of command-line arguments.
3125 *
3126 * Retrieve the number of command-line arguments that were used to launch Orthanc.
3127 *
3128 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3129 * @return The number of arguments.
3130 **/
3131 ORTHANC_PLUGIN_INLINE uint32_t OrthancPluginGetCommandLineArgumentsCount(
3132 OrthancPluginContext* context)
3133 {
3134 uint32_t count = 0;
3135
3136 _OrthancPluginReturnSingleValue params;
3137 memset(&params, 0, sizeof(params));
3138 params.resultUint32 = &count;
3139
3140 if (context->InvokeService(context, _OrthancPluginService_GetCommandLineArgumentsCount, &params) != OrthancPluginErrorCode_Success)
3141 {
3142 /* Error */
3143 return 0;
3144 }
3145 else
3146 {
3147 return count;
3148 }
3149 }
3150
3151
3152
3153 /**
3154 * @brief Get the value of a command-line argument.
3155 *
3156 * Get the value of one of the command-line arguments that were used
3157 * to launch Orthanc. The number of available arguments can be
3158 * retrieved by OrthancPluginGetCommandLineArgumentsCount().
3159 *
3160 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3161 * @param argument The index of the argument.
3162 * @return The value of the argument, or NULL in the case of an error. This
3163 * string must be freed by OrthancPluginFreeString().
3164 **/
3165 ORTHANC_PLUGIN_INLINE char* OrthancPluginGetCommandLineArgument(
3166 OrthancPluginContext* context,
3167 uint32_t argument)
3168 {
3169 char* result;
3170
3171 _OrthancPluginGlobalProperty params;
3172 params.result = &result;
3173 params.property = (int32_t) argument;
3174 params.value = NULL;
3175
3176 if (context->InvokeService(context, _OrthancPluginService_GetCommandLineArgument, &params) != OrthancPluginErrorCode_Success)
3177 {
3178 /* Error */
3179 return NULL;
3180 }
3181 else
3182 {
3183 return result;
3184 }
3185 }
3186
3187
3188 /**
3189 * @brief Get the expected version of the database schema.
3190 *
3191 * Retrieve the expected version of the database schema.
3192 *
3193 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3194 * @return The version.
3195 * @ingroup Callbacks
3196 **/
3197 ORTHANC_PLUGIN_INLINE uint32_t OrthancPluginGetExpectedDatabaseVersion(
3198 OrthancPluginContext* context)
3199 {
3200 uint32_t count = 0;
3201
3202 _OrthancPluginReturnSingleValue params;
3203 memset(&params, 0, sizeof(params));
3204 params.resultUint32 = &count;
3205
3206 if (context->InvokeService(context, _OrthancPluginService_GetExpectedDatabaseVersion, &params) != OrthancPluginErrorCode_Success)
3207 {
3208 /* Error */
3209 return 0;
3210 }
3211 else
3212 {
3213 return count;
3214 }
3215 }
3216
3217
3218
3219 /**
3220 * @brief Return the content of the configuration file(s).
3221 *
3222 * This function returns the content of the configuration that is
3223 * used by Orthanc, formatted as a JSON string.
3224 *
3225 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3226 * @return NULL in the case of an error, or a newly allocated string
3227 * containing the configuration. This string must be freed by
3228 * OrthancPluginFreeString().
3229 **/
3230 ORTHANC_PLUGIN_INLINE char *OrthancPluginGetConfiguration(OrthancPluginContext* context)
3231 {
3232 char* result;
3233
3234 _OrthancPluginRetrieveDynamicString params;
3235 params.result = &result;
3236 params.argument = NULL;
3237
3238 if (context->InvokeService(context, _OrthancPluginService_GetConfiguration, &params) != OrthancPluginErrorCode_Success)
3239 {
3240 /* Error */
3241 return NULL;
3242 }
3243 else
3244 {
3245 return result;
3246 }
3247 }
3248
3249
3250
3251 typedef struct
3252 {
3253 OrthancPluginRestOutput* output;
3254 const char* subType;
3255 const char* contentType;
3256 } _OrthancPluginStartMultipartAnswer;
3257
3258 /**
3259 * @brief Start an HTTP multipart answer.
3260 *
3261 * Initiates a HTTP multipart answer, as the result of a REST request.
3262 *
3263 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3264 * @param output The HTTP connection to the client application.
3265 * @param subType The sub-type of the multipart answer ("mixed" or "related").
3266 * @param contentType The MIME type of the items in the multipart answer.
3267 * @return 0 if success, or the error code if failure.
3268 * @see OrthancPluginSendMultipartItem(), OrthancPluginSendMultipartItem2()
3269 * @ingroup REST
3270 **/
3271 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginStartMultipartAnswer(
3272 OrthancPluginContext* context,
3273 OrthancPluginRestOutput* output,
3274 const char* subType,
3275 const char* contentType)
3276 {
3277 _OrthancPluginStartMultipartAnswer params;
3278 params.output = output;
3279 params.subType = subType;
3280 params.contentType = contentType;
3281 return context->InvokeService(context, _OrthancPluginService_StartMultipartAnswer, &params);
3282 }
3283
3284
3285 /**
3286 * @brief Send an item as a part of some HTTP multipart answer.
3287 *
3288 * This function sends an item as a part of some HTTP multipart
3289 * answer that was initiated by OrthancPluginStartMultipartAnswer().
3290 *
3291 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3292 * @param output The HTTP connection to the client application.
3293 * @param answer Pointer to the memory buffer containing the item.
3294 * @param answerSize Number of bytes of the item.
3295 * @return 0 if success, or the error code if failure (this notably happens
3296 * if the connection is closed by the client).
3297 * @see OrthancPluginSendMultipartItem2()
3298 * @ingroup REST
3299 **/
3300 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginSendMultipartItem(
3301 OrthancPluginContext* context,
3302 OrthancPluginRestOutput* output,
3303 const char* answer,
3304 uint32_t answerSize)
3305 {
3306 _OrthancPluginAnswerBuffer params;
3307 params.output = output;
3308 params.answer = answer;
3309 params.answerSize = answerSize;
3310 params.mimeType = NULL;
3311 return context->InvokeService(context, _OrthancPluginService_SendMultipartItem, &params);
3312 }
3313
3314
3315
3316 typedef struct
3317 {
3318 OrthancPluginMemoryBuffer* target;
3319 const void* source;
3320 uint32_t size;
3321 OrthancPluginCompressionType compression;
3322 uint8_t uncompress;
3323 } _OrthancPluginBufferCompression;
3324
3325
3326 /**
3327 * @brief Compress or decompress a buffer.
3328 *
3329 * This function compresses or decompresses a buffer, using the
3330 * version of the zlib library that is used by the Orthanc core.
3331 *
3332 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3333 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
3334 * @param source The source buffer.
3335 * @param size The size in bytes of the source buffer.
3336 * @param compression The compression algorithm.
3337 * @param uncompress If set to "0", the buffer must be compressed.
3338 * If set to "1", the buffer must be uncompressed.
3339 * @return 0 if success, or the error code if failure.
3340 * @ingroup Images
3341 **/
3342 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginBufferCompression(
3343 OrthancPluginContext* context,
3344 OrthancPluginMemoryBuffer* target,
3345 const void* source,
3346 uint32_t size,
3347 OrthancPluginCompressionType compression,
3348 uint8_t uncompress)
3349 {
3350 _OrthancPluginBufferCompression params;
3351 params.target = target;
3352 params.source = source;
3353 params.size = size;
3354 params.compression = compression;
3355 params.uncompress = uncompress;
3356
3357 return context->InvokeService(context, _OrthancPluginService_BufferCompression, &params);
3358 }
3359
3360
3361
3362 typedef struct
3363 {
3364 OrthancPluginMemoryBuffer* target;
3365 const char* path;
3366 } _OrthancPluginReadFile;
3367
3368 /**
3369 * @brief Read a file.
3370 *
3371 * Read the content of a file on the filesystem, and returns it into
3372 * a newly allocated memory buffer.
3373 *
3374 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3375 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
3376 * @param path The path of the file to be read.
3377 * @return 0 if success, or the error code if failure.
3378 **/
3379 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginReadFile(
3380 OrthancPluginContext* context,
3381 OrthancPluginMemoryBuffer* target,
3382 const char* path)
3383 {
3384 _OrthancPluginReadFile params;
3385 params.target = target;
3386 params.path = path;
3387 return context->InvokeService(context, _OrthancPluginService_ReadFile, &params);
3388 }
3389
3390
3391
3392 typedef struct
3393 {
3394 const char* path;
3395 const void* data;
3396 uint32_t size;
3397 } _OrthancPluginWriteFile;
3398
3399 /**
3400 * @brief Write a file.
3401 *
3402 * Write the content of a memory buffer to the filesystem.
3403 *
3404 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3405 * @param path The path of the file to be written.
3406 * @param data The content of the memory buffer.
3407 * @param size The size of the memory buffer.
3408 * @return 0 if success, or the error code if failure.
3409 **/
3410 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginWriteFile(
3411 OrthancPluginContext* context,
3412 const char* path,
3413 const void* data,
3414 uint32_t size)
3415 {
3416 _OrthancPluginWriteFile params;
3417 params.path = path;
3418 params.data = data;
3419 params.size = size;
3420 return context->InvokeService(context, _OrthancPluginService_WriteFile, &params);
3421 }
3422
3423
3424
3425 typedef struct
3426 {
3427 const char** target;
3428 OrthancPluginErrorCode error;
3429 } _OrthancPluginGetErrorDescription;
3430
3431 /**
3432 * @brief Get the description of a given error code.
3433 *
3434 * This function returns the description of a given error code.
3435 *
3436 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3437 * @param error The error code of interest.
3438 * @return The error description. This is a statically-allocated
3439 * string, do not free it.
3440 **/
3441 ORTHANC_PLUGIN_INLINE const char* OrthancPluginGetErrorDescription(
3442 OrthancPluginContext* context,
3443 OrthancPluginErrorCode error)
3444 {
3445 const char* result = NULL;
3446
3447 _OrthancPluginGetErrorDescription params;
3448 params.target = &result;
3449 params.error = error;
3450
3451 if (context->InvokeService(context, _OrthancPluginService_GetErrorDescription, &params) != OrthancPluginErrorCode_Success ||
3452 result == NULL)
3453 {
3454 return "Unknown error code";
3455 }
3456 else
3457 {
3458 return result;
3459 }
3460 }
3461
3462
3463
3464 typedef struct
3465 {
3466 OrthancPluginRestOutput* output;
3467 uint16_t status;
3468 const char* body;
3469 uint32_t bodySize;
3470 } _OrthancPluginSendHttpStatus;
3471
3472 /**
3473 * @brief Send a HTTP status, with a custom body.
3474 *
3475 * This function answers to a HTTP request by sending a HTTP status
3476 * code (such as "400 - Bad Request"), together with a body
3477 * describing the error. The body will only be returned if the
3478 * configuration option "HttpDescribeErrors" of Orthanc is set to "true".
3479 *
3480 * Note that:
3481 * - Successful requests (status 200) must use ::OrthancPluginAnswerBuffer().
3482 * - Redirections (status 301) must use ::OrthancPluginRedirect().
3483 * - Unauthorized access (status 401) must use ::OrthancPluginSendUnauthorized().
3484 * - Methods not allowed (status 405) must use ::OrthancPluginSendMethodNotAllowed().
3485 *
3486 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3487 * @param output The HTTP connection to the client application.
3488 * @param status The HTTP status code to be sent.
3489 * @param body The body of the answer.
3490 * @param bodySize The size of the body.
3491 * @see OrthancPluginSendHttpStatusCode()
3492 * @ingroup REST
3493 **/
3494 ORTHANC_PLUGIN_INLINE void OrthancPluginSendHttpStatus(
3495 OrthancPluginContext* context,
3496 OrthancPluginRestOutput* output,
3497 uint16_t status,
3498 const char* body,
3499 uint32_t bodySize)
3500 {
3501 _OrthancPluginSendHttpStatus params;
3502 params.output = output;
3503 params.status = status;
3504 params.body = body;
3505 params.bodySize = bodySize;
3506 context->InvokeService(context, _OrthancPluginService_SendHttpStatus, &params);
3507 }
3508
3509
3510
3511 typedef struct
3512 {
3513 const OrthancPluginImage* image;
3514 uint32_t* resultUint32;
3515 OrthancPluginPixelFormat* resultPixelFormat;
3516 void** resultBuffer;
3517 } _OrthancPluginGetImageInfo;
3518
3519
3520 /**
3521 * @brief Return the pixel format of an image.
3522 *
3523 * This function returns the type of memory layout for the pixels of the given image.
3524 *
3525 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3526 * @param image The image of interest.
3527 * @return The pixel format.
3528 * @ingroup Images
3529 **/
3530 ORTHANC_PLUGIN_INLINE OrthancPluginPixelFormat OrthancPluginGetImagePixelFormat(
3531 OrthancPluginContext* context,
3532 const OrthancPluginImage* image)
3533 {
3534 OrthancPluginPixelFormat target;
3535
3536 _OrthancPluginGetImageInfo params;
3537 memset(&params, 0, sizeof(params));
3538 params.image = image;
3539 params.resultPixelFormat = &target;
3540
3541 if (context->InvokeService(context, _OrthancPluginService_GetImagePixelFormat, &params) != OrthancPluginErrorCode_Success)
3542 {
3543 return OrthancPluginPixelFormat_Unknown;
3544 }
3545 else
3546 {
3547 return (OrthancPluginPixelFormat) target;
3548 }
3549 }
3550
3551
3552
3553 /**
3554 * @brief Return the width of an image.
3555 *
3556 * This function returns the width of the given image.
3557 *
3558 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3559 * @param image The image of interest.
3560 * @return The width.
3561 * @ingroup Images
3562 **/
3563 ORTHANC_PLUGIN_INLINE uint32_t OrthancPluginGetImageWidth(
3564 OrthancPluginContext* context,
3565 const OrthancPluginImage* image)
3566 {
3567 uint32_t width;
3568
3569 _OrthancPluginGetImageInfo params;
3570 memset(&params, 0, sizeof(params));
3571 params.image = image;
3572 params.resultUint32 = &width;
3573
3574 if (context->InvokeService(context, _OrthancPluginService_GetImageWidth, &params) != OrthancPluginErrorCode_Success)
3575 {
3576 return 0;
3577 }
3578 else
3579 {
3580 return width;
3581 }
3582 }
3583
3584
3585
3586 /**
3587 * @brief Return the height of an image.
3588 *
3589 * This function returns the height of the given image.
3590 *
3591 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3592 * @param image The image of interest.
3593 * @return The height.
3594 * @ingroup Images
3595 **/
3596 ORTHANC_PLUGIN_INLINE uint32_t OrthancPluginGetImageHeight(
3597 OrthancPluginContext* context,
3598 const OrthancPluginImage* image)
3599 {
3600 uint32_t height;
3601
3602 _OrthancPluginGetImageInfo params;
3603 memset(&params, 0, sizeof(params));
3604 params.image = image;
3605 params.resultUint32 = &height;
3606
3607 if (context->InvokeService(context, _OrthancPluginService_GetImageHeight, &params) != OrthancPluginErrorCode_Success)
3608 {
3609 return 0;
3610 }
3611 else
3612 {
3613 return height;
3614 }
3615 }
3616
3617
3618
3619 /**
3620 * @brief Return the pitch of an image.
3621 *
3622 * This function returns the pitch of the given image. The pitch is
3623 * defined as the number of bytes between 2 successive lines of the
3624 * image in the memory buffer.
3625 *
3626 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3627 * @param image The image of interest.
3628 * @return The pitch.
3629 * @ingroup Images
3630 **/
3631 ORTHANC_PLUGIN_INLINE uint32_t OrthancPluginGetImagePitch(
3632 OrthancPluginContext* context,
3633 const OrthancPluginImage* image)
3634 {
3635 uint32_t pitch;
3636
3637 _OrthancPluginGetImageInfo params;
3638 memset(&params, 0, sizeof(params));
3639 params.image = image;
3640 params.resultUint32 = &pitch;
3641
3642 if (context->InvokeService(context, _OrthancPluginService_GetImagePitch, &params) != OrthancPluginErrorCode_Success)
3643 {
3644 return 0;
3645 }
3646 else
3647 {
3648 return pitch;
3649 }
3650 }
3651
3652
3653
3654 /**
3655 * @brief Return a pointer to the content of an image.
3656 *
3657 * This function returns a pointer to the memory buffer that
3658 * contains the pixels of the image.
3659 *
3660 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3661 * @param image The image of interest.
3662 * @return The pointer.
3663 * @ingroup Images
3664 **/
3665 ORTHANC_PLUGIN_INLINE void* OrthancPluginGetImageBuffer(
3666 OrthancPluginContext* context,
3667 const OrthancPluginImage* image)
3668 {
3669 void* target = NULL;
3670
3671 _OrthancPluginGetImageInfo params;
3672 memset(&params, 0, sizeof(params));
3673 params.resultBuffer = &target;
3674 params.image = image;
3675
3676 if (context->InvokeService(context, _OrthancPluginService_GetImageBuffer, &params) != OrthancPluginErrorCode_Success)
3677 {
3678 return NULL;
3679 }
3680 else
3681 {
3682 return target;
3683 }
3684 }
3685
3686
3687 typedef struct
3688 {
3689 OrthancPluginImage** target;
3690 const void* data;
3691 uint32_t size;
3692 OrthancPluginImageFormat format;
3693 } _OrthancPluginUncompressImage;
3694
3695
3696 /**
3697 * @brief Decode a compressed image.
3698 *
3699 * This function decodes a compressed image from a memory buffer.
3700 *
3701 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3702 * @param data Pointer to a memory buffer containing the compressed image.
3703 * @param size Size of the memory buffer containing the compressed image.
3704 * @param format The file format of the compressed image.
3705 * @return The uncompressed image. It must be freed with OrthancPluginFreeImage().
3706 * @ingroup Images
3707 **/
3708 ORTHANC_PLUGIN_INLINE OrthancPluginImage *OrthancPluginUncompressImage(
3709 OrthancPluginContext* context,
3710 const void* data,
3711 uint32_t size,
3712 OrthancPluginImageFormat format)
3713 {
3714 OrthancPluginImage* target = NULL;
3715
3716 _OrthancPluginUncompressImage params;
3717 memset(&params, 0, sizeof(params));
3718 params.target = &target;
3719 params.data = data;
3720 params.size = size;
3721 params.format = format;
3722
3723 if (context->InvokeService(context, _OrthancPluginService_UncompressImage, &params) != OrthancPluginErrorCode_Success)
3724 {
3725 return NULL;
3726 }
3727 else
3728 {
3729 return target;
3730 }
3731 }
3732
3733
3734
3735
3736 typedef struct
3737 {
3738 OrthancPluginImage* image;
3739 } _OrthancPluginFreeImage;
3740
3741 /**
3742 * @brief Free an image.
3743 *
3744 * This function frees an image that was decoded with OrthancPluginUncompressImage().
3745 *
3746 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3747 * @param image The image.
3748 * @ingroup Images
3749 **/
3750 ORTHANC_PLUGIN_INLINE void OrthancPluginFreeImage(
3751 OrthancPluginContext* context,
3752 OrthancPluginImage* image)
3753 {
3754 _OrthancPluginFreeImage params;
3755 params.image = image;
3756
3757 context->InvokeService(context, _OrthancPluginService_FreeImage, &params);
3758 }
3759
3760
3761
3762
3763 typedef struct
3764 {
3765 OrthancPluginMemoryBuffer* target;
3766 OrthancPluginImageFormat imageFormat;
3767 OrthancPluginPixelFormat pixelFormat;
3768 uint32_t width;
3769 uint32_t height;
3770 uint32_t pitch;
3771 const void* buffer;
3772 uint8_t quality;
3773 } _OrthancPluginCompressImage;
3774
3775
3776 /**
3777 * @brief Encode a PNG image.
3778 *
3779 * This function compresses the given memory buffer containing an
3780 * image using the PNG specification, and stores the result of the
3781 * compression into a newly allocated memory buffer.
3782 *
3783 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3784 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
3785 * @param format The memory layout of the uncompressed image.
3786 * @param width The width of the image.
3787 * @param height The height of the image.
3788 * @param pitch The pitch of the image (i.e. the number of bytes
3789 * between 2 successive lines of the image in the memory buffer).
3790 * @param buffer The memory buffer containing the uncompressed image.
3791 * @return 0 if success, or the error code if failure.
3792 * @see OrthancPluginCompressAndAnswerPngImage()
3793 * @ingroup Images
3794 **/
3795 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginCompressPngImage(
3796 OrthancPluginContext* context,
3797 OrthancPluginMemoryBuffer* target,
3798 OrthancPluginPixelFormat format,
3799 uint32_t width,
3800 uint32_t height,
3801 uint32_t pitch,
3802 const void* buffer)
3803 {
3804 _OrthancPluginCompressImage params;
3805 memset(&params, 0, sizeof(params));
3806 params.target = target;
3807 params.imageFormat = OrthancPluginImageFormat_Png;
3808 params.pixelFormat = format;
3809 params.width = width;
3810 params.height = height;
3811 params.pitch = pitch;
3812 params.buffer = buffer;
3813 params.quality = 0; /* Unused for PNG */
3814
3815 return context->InvokeService(context, _OrthancPluginService_CompressImage, &params);
3816 }
3817
3818
3819 /**
3820 * @brief Encode a JPEG image.
3821 *
3822 * This function compresses the given memory buffer containing an
3823 * image using the JPEG specification, and stores the result of the
3824 * compression into a newly allocated memory buffer.
3825 *
3826 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3827 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
3828 * @param format The memory layout of the uncompressed image.
3829 * @param width The width of the image.
3830 * @param height The height of the image.
3831 * @param pitch The pitch of the image (i.e. the number of bytes
3832 * between 2 successive lines of the image in the memory buffer).
3833 * @param buffer The memory buffer containing the uncompressed image.
3834 * @param quality The quality of the JPEG encoding, between 1 (worst
3835 * quality, best compression) and 100 (best quality, worst
3836 * compression).
3837 * @return 0 if success, or the error code if failure.
3838 * @ingroup Images
3839 **/
3840 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginCompressJpegImage(
3841 OrthancPluginContext* context,
3842 OrthancPluginMemoryBuffer* target,
3843 OrthancPluginPixelFormat format,
3844 uint32_t width,
3845 uint32_t height,
3846 uint32_t pitch,
3847 const void* buffer,
3848 uint8_t quality)
3849 {
3850 _OrthancPluginCompressImage params;
3851 memset(&params, 0, sizeof(params));
3852 params.target = target;
3853 params.imageFormat = OrthancPluginImageFormat_Jpeg;
3854 params.pixelFormat = format;
3855 params.width = width;
3856 params.height = height;
3857 params.pitch = pitch;
3858 params.buffer = buffer;
3859 params.quality = quality;
3860
3861 return context->InvokeService(context, _OrthancPluginService_CompressImage, &params);
3862 }
3863
3864
3865
3866 /**
3867 * @brief Answer to a REST request with a JPEG image.
3868 *
3869 * This function answers to a REST request with a JPEG image. The
3870 * parameters of this function describe a memory buffer that
3871 * contains an uncompressed image. The image will be automatically compressed
3872 * as a JPEG image by the core system of Orthanc.
3873 *
3874 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3875 * @param output The HTTP connection to the client application.
3876 * @param format The memory layout of the uncompressed image.
3877 * @param width The width of the image.
3878 * @param height The height of the image.
3879 * @param pitch The pitch of the image (i.e. the number of bytes
3880 * between 2 successive lines of the image in the memory buffer).
3881 * @param buffer The memory buffer containing the uncompressed image.
3882 * @param quality The quality of the JPEG encoding, between 1 (worst
3883 * quality, best compression) and 100 (best quality, worst
3884 * compression).
3885 * @ingroup REST
3886 **/
3887 ORTHANC_PLUGIN_INLINE void OrthancPluginCompressAndAnswerJpegImage(
3888 OrthancPluginContext* context,
3889 OrthancPluginRestOutput* output,
3890 OrthancPluginPixelFormat format,
3891 uint32_t width,
3892 uint32_t height,
3893 uint32_t pitch,
3894 const void* buffer,
3895 uint8_t quality)
3896 {
3897 _OrthancPluginCompressAndAnswerImage params;
3898 params.output = output;
3899 params.imageFormat = OrthancPluginImageFormat_Jpeg;
3900 params.pixelFormat = format;
3901 params.width = width;
3902 params.height = height;
3903 params.pitch = pitch;
3904 params.buffer = buffer;
3905 params.quality = quality;
3906 context->InvokeService(context, _OrthancPluginService_CompressAndAnswerImage, &params);
3907 }
3908
3909
3910
3911
3912 typedef struct
3913 {
3914 OrthancPluginMemoryBuffer* target;
3915 OrthancPluginHttpMethod method;
3916 const char* url;
3917 const char* username;
3918 const char* password;
3919 const char* body;
3920 uint32_t bodySize;
3921 } _OrthancPluginCallHttpClient;
3922
3923
3924 /**
3925 * @brief Issue a HTTP GET call.
3926 *
3927 * Make a HTTP GET call to the given URL. The result to the query is
3928 * stored into a newly allocated memory buffer. Favor
3929 * OrthancPluginRestApiGet() if calling the built-in REST API of the
3930 * Orthanc instance that hosts this plugin.
3931 *
3932 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3933 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
3934 * @param url The URL of interest.
3935 * @param username The username (can be <tt>NULL</tt> if no password protection).
3936 * @param password The password (can be <tt>NULL</tt> if no password protection).
3937 * @return 0 if success, or the error code if failure.
3938 **/
3939 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginHttpGet(
3940 OrthancPluginContext* context,
3941 OrthancPluginMemoryBuffer* target,
3942 const char* url,
3943 const char* username,
3944 const char* password)
3945 {
3946 _OrthancPluginCallHttpClient params;
3947 memset(&params, 0, sizeof(params));
3948
3949 params.target = target;
3950 params.method = OrthancPluginHttpMethod_Get;
3951 params.url = url;
3952 params.username = username;
3953 params.password = password;
3954
3955 return context->InvokeService(context, _OrthancPluginService_CallHttpClient, &params);
3956 }
3957
3958
3959 /**
3960 * @brief Issue a HTTP POST call.
3961 *
3962 * Make a HTTP POST call to the given URL. The result to the query
3963 * is stored into a newly allocated memory buffer. Favor
3964 * OrthancPluginRestApiPost() if calling the built-in REST API of
3965 * the Orthanc instance that hosts this plugin.
3966 *
3967 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
3968 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
3969 * @param url The URL of interest.
3970 * @param body The content of the body of the request.
3971 * @param bodySize The size of the body of the request.
3972 * @param username The username (can be <tt>NULL</tt> if no password protection).
3973 * @param password The password (can be <tt>NULL</tt> if no password protection).
3974 * @return 0 if success, or the error code if failure.
3975 **/
3976 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginHttpPost(
3977 OrthancPluginContext* context,
3978 OrthancPluginMemoryBuffer* target,
3979 const char* url,
3980 const char* body,
3981 uint32_t bodySize,
3982 const char* username,
3983 const char* password)
3984 {
3985 _OrthancPluginCallHttpClient params;
3986 memset(&params, 0, sizeof(params));
3987
3988 params.target = target;
3989 params.method = OrthancPluginHttpMethod_Post;
3990 params.url = url;
3991 params.body = body;
3992 params.bodySize = bodySize;
3993 params.username = username;
3994 params.password = password;
3995
3996 return context->InvokeService(context, _OrthancPluginService_CallHttpClient, &params);
3997 }
3998
3999
4000 /**
4001 * @brief Issue a HTTP PUT call.
4002 *
4003 * Make a HTTP PUT call to the given URL. The result to the query is
4004 * stored into a newly allocated memory buffer. Favor
4005 * OrthancPluginRestApiPut() if calling the built-in REST API of the
4006 * Orthanc instance that hosts this plugin.
4007 *
4008 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4009 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
4010 * @param url The URL of interest.
4011 * @param body The content of the body of the request.
4012 * @param bodySize The size of the body of the request.
4013 * @param username The username (can be <tt>NULL</tt> if no password protection).
4014 * @param password The password (can be <tt>NULL</tt> if no password protection).
4015 * @return 0 if success, or the error code if failure.
4016 **/
4017 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginHttpPut(
4018 OrthancPluginContext* context,
4019 OrthancPluginMemoryBuffer* target,
4020 const char* url,
4021 const char* body,
4022 uint32_t bodySize,
4023 const char* username,
4024 const char* password)
4025 {
4026 _OrthancPluginCallHttpClient params;
4027 memset(&params, 0, sizeof(params));
4028
4029 params.target = target;
4030 params.method = OrthancPluginHttpMethod_Put;
4031 params.url = url;
4032 params.body = body;
4033 params.bodySize = bodySize;
4034 params.username = username;
4035 params.password = password;
4036
4037 return context->InvokeService(context, _OrthancPluginService_CallHttpClient, &params);
4038 }
4039
4040
4041 /**
4042 * @brief Issue a HTTP DELETE call.
4043 *
4044 * Make a HTTP DELETE call to the given URL. Favor
4045 * OrthancPluginRestApiDelete() if calling the built-in REST API of
4046 * the Orthanc instance that hosts this plugin.
4047 *
4048 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4049 * @param url The URL of interest.
4050 * @param username The username (can be <tt>NULL</tt> if no password protection).
4051 * @param password The password (can be <tt>NULL</tt> if no password protection).
4052 * @return 0 if success, or the error code if failure.
4053 **/
4054 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginHttpDelete(
4055 OrthancPluginContext* context,
4056 const char* url,
4057 const char* username,
4058 const char* password)
4059 {
4060 _OrthancPluginCallHttpClient params;
4061 memset(&params, 0, sizeof(params));
4062
4063 params.method = OrthancPluginHttpMethod_Delete;
4064 params.url = url;
4065 params.username = username;
4066 params.password = password;
4067
4068 return context->InvokeService(context, _OrthancPluginService_CallHttpClient, &params);
4069 }
4070
4071
4072
4073 typedef struct
4074 {
4075 OrthancPluginImage** target;
4076 const OrthancPluginImage* source;
4077 OrthancPluginPixelFormat targetFormat;
4078 } _OrthancPluginConvertPixelFormat;
4079
4080
4081 /**
4082 * @brief Change the pixel format of an image.
4083 *
4084 * This function creates a new image, changing the memory layout of the pixels.
4085 *
4086 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4087 * @param source The source image.
4088 * @param targetFormat The target pixel format.
4089 * @return The resulting image. It must be freed with OrthancPluginFreeImage().
4090 * @ingroup Images
4091 **/
4092 ORTHANC_PLUGIN_INLINE OrthancPluginImage *OrthancPluginConvertPixelFormat(
4093 OrthancPluginContext* context,
4094 const OrthancPluginImage* source,
4095 OrthancPluginPixelFormat targetFormat)
4096 {
4097 OrthancPluginImage* target = NULL;
4098
4099 _OrthancPluginConvertPixelFormat params;
4100 params.target = &target;
4101 params.source = source;
4102 params.targetFormat = targetFormat;
4103
4104 if (context->InvokeService(context, _OrthancPluginService_ConvertPixelFormat, &params) != OrthancPluginErrorCode_Success)
4105 {
4106 return NULL;
4107 }
4108 else
4109 {
4110 return target;
4111 }
4112 }
4113
4114
4115
4116 /**
4117 * @brief Return the number of available fonts.
4118 *
4119 * This function returns the number of fonts that are built in the
4120 * Orthanc core. These fonts can be used to draw texts on images
4121 * through OrthancPluginDrawText().
4122 *
4123 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4124 * @return The number of fonts.
4125 * @ingroup Images
4126 **/
4127 ORTHANC_PLUGIN_INLINE uint32_t OrthancPluginGetFontsCount(
4128 OrthancPluginContext* context)
4129 {
4130 uint32_t count = 0;
4131
4132 _OrthancPluginReturnSingleValue params;
4133 memset(&params, 0, sizeof(params));
4134 params.resultUint32 = &count;
4135
4136 if (context->InvokeService(context, _OrthancPluginService_GetFontsCount, &params) != OrthancPluginErrorCode_Success)
4137 {
4138 /* Error */
4139 return 0;
4140 }
4141 else
4142 {
4143 return count;
4144 }
4145 }
4146
4147
4148
4149
4150 typedef struct
4151 {
4152 uint32_t fontIndex; /* in */
4153 const char** name; /* out */
4154 uint32_t* size; /* out */
4155 } _OrthancPluginGetFontInfo;
4156
4157 /**
4158 * @brief Return the name of a font.
4159 *
4160 * This function returns the name of a font that is built in the Orthanc core.
4161 *
4162 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4163 * @param fontIndex The index of the font. This value must be less than OrthancPluginGetFontsCount().
4164 * @return The font name. This is a statically-allocated string, do not free it.
4165 * @ingroup Images
4166 **/
4167 ORTHANC_PLUGIN_INLINE const char* OrthancPluginGetFontName(
4168 OrthancPluginContext* context,
4169 uint32_t fontIndex)
4170 {
4171 const char* result = NULL;
4172
4173 _OrthancPluginGetFontInfo params;
4174 memset(&params, 0, sizeof(params));
4175 params.name = &result;
4176 params.fontIndex = fontIndex;
4177
4178 if (context->InvokeService(context, _OrthancPluginService_GetFontInfo, &params) != OrthancPluginErrorCode_Success)
4179 {
4180 return NULL;
4181 }
4182 else
4183 {
4184 return result;
4185 }
4186 }
4187
4188
4189 /**
4190 * @brief Return the size of a font.
4191 *
4192 * This function returns the size of a font that is built in the Orthanc core.
4193 *
4194 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4195 * @param fontIndex The index of the font. This value must be less than OrthancPluginGetFontsCount().
4196 * @return The font size.
4197 * @ingroup Images
4198 **/
4199 ORTHANC_PLUGIN_INLINE uint32_t OrthancPluginGetFontSize(
4200 OrthancPluginContext* context,
4201 uint32_t fontIndex)
4202 {
4203 uint32_t result;
4204
4205 _OrthancPluginGetFontInfo params;
4206 memset(&params, 0, sizeof(params));
4207 params.size = &result;
4208 params.fontIndex = fontIndex;
4209
4210 if (context->InvokeService(context, _OrthancPluginService_GetFontInfo, &params) != OrthancPluginErrorCode_Success)
4211 {
4212 return 0;
4213 }
4214 else
4215 {
4216 return result;
4217 }
4218 }
4219
4220
4221
4222 typedef struct
4223 {
4224 OrthancPluginImage* image;
4225 uint32_t fontIndex;
4226 const char* utf8Text;
4227 int32_t x;
4228 int32_t y;
4229 uint8_t r;
4230 uint8_t g;
4231 uint8_t b;
4232 } _OrthancPluginDrawText;
4233
4234
4235 /**
4236 * @brief Draw text on an image.
4237 *
4238 * This function draws some text on some image.
4239 *
4240 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4241 * @param image The image upon which to draw the text.
4242 * @param fontIndex The index of the font. This value must be less than OrthancPluginGetFontsCount().
4243 * @param utf8Text The text to be drawn, encoded as an UTF-8 zero-terminated string.
4244 * @param x The X position of the text over the image.
4245 * @param y The Y position of the text over the image.
4246 * @param r The value of the red color channel of the text.
4247 * @param g The value of the green color channel of the text.
4248 * @param b The value of the blue color channel of the text.
4249 * @return 0 if success, other value if error.
4250 * @ingroup Images
4251 **/
4252 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginDrawText(
4253 OrthancPluginContext* context,
4254 OrthancPluginImage* image,
4255 uint32_t fontIndex,
4256 const char* utf8Text,
4257 int32_t x,
4258 int32_t y,
4259 uint8_t r,
4260 uint8_t g,
4261 uint8_t b)
4262 {
4263 _OrthancPluginDrawText params;
4264 memset(&params, 0, sizeof(params));
4265 params.image = image;
4266 params.fontIndex = fontIndex;
4267 params.utf8Text = utf8Text;
4268 params.x = x;
4269 params.y = y;
4270 params.r = r;
4271 params.g = g;
4272 params.b = b;
4273
4274 return context->InvokeService(context, _OrthancPluginService_DrawText, &params);
4275 }
4276
4277
4278
4279 typedef struct
4280 {
4281 OrthancPluginStorageArea* storageArea;
4282 const char* uuid;
4283 const void* content;
4284 uint64_t size;
4285 OrthancPluginContentType type;
4286 } _OrthancPluginStorageAreaCreate;
4287
4288
4289 /**
4290 * @brief Create a file inside the storage area.
4291 *
4292 * This function creates a new file inside the storage area that is
4293 * currently used by Orthanc.
4294 *
4295 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4296 * @param storageArea The storage area.
4297 * @param uuid The identifier of the file to be created.
4298 * @param content The content to store in the newly created file.
4299 * @param size The size of the content.
4300 * @param type The type of the file content.
4301 * @return 0 if success, other value if error.
4302 * @ingroup Callbacks
4303 **/
4304 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginStorageAreaCreate(
4305 OrthancPluginContext* context,
4306 OrthancPluginStorageArea* storageArea,
4307 const char* uuid,
4308 const void* content,
4309 uint64_t size,
4310 OrthancPluginContentType type)
4311 {
4312 _OrthancPluginStorageAreaCreate params;
4313 params.storageArea = storageArea;
4314 params.uuid = uuid;
4315 params.content = content;
4316 params.size = size;
4317 params.type = type;
4318
4319 return context->InvokeService(context, _OrthancPluginService_StorageAreaCreate, &params);
4320 }
4321
4322
4323 typedef struct
4324 {
4325 OrthancPluginMemoryBuffer* target;
4326 OrthancPluginStorageArea* storageArea;
4327 const char* uuid;
4328 OrthancPluginContentType type;
4329 } _OrthancPluginStorageAreaRead;
4330
4331
4332 /**
4333 * @brief Read a file from the storage area.
4334 *
4335 * This function reads the content of a given file from the storage
4336 * area that is currently used by Orthanc.
4337 *
4338 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4339 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
4340 * @param storageArea The storage area.
4341 * @param uuid The identifier of the file to be read.
4342 * @param type The type of the file content.
4343 * @return 0 if success, other value if error.
4344 * @ingroup Callbacks
4345 **/
4346 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginStorageAreaRead(
4347 OrthancPluginContext* context,
4348 OrthancPluginMemoryBuffer* target,
4349 OrthancPluginStorageArea* storageArea,
4350 const char* uuid,
4351 OrthancPluginContentType type)
4352 {
4353 _OrthancPluginStorageAreaRead params;
4354 params.target = target;
4355 params.storageArea = storageArea;
4356 params.uuid = uuid;
4357 params.type = type;
4358
4359 return context->InvokeService(context, _OrthancPluginService_StorageAreaRead, &params);
4360 }
4361
4362
4363 typedef struct
4364 {
4365 OrthancPluginStorageArea* storageArea;
4366 const char* uuid;
4367 OrthancPluginContentType type;
4368 } _OrthancPluginStorageAreaRemove;
4369
4370 /**
4371 * @brief Remove a file from the storage area.
4372 *
4373 * This function removes a given file from the storage area that is
4374 * currently used by Orthanc.
4375 *
4376 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4377 * @param storageArea The storage area.
4378 * @param uuid The identifier of the file to be removed.
4379 * @param type The type of the file content.
4380 * @return 0 if success, other value if error.
4381 * @ingroup Callbacks
4382 **/
4383 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginStorageAreaRemove(
4384 OrthancPluginContext* context,
4385 OrthancPluginStorageArea* storageArea,
4386 const char* uuid,
4387 OrthancPluginContentType type)
4388 {
4389 _OrthancPluginStorageAreaRemove params;
4390 params.storageArea = storageArea;
4391 params.uuid = uuid;
4392 params.type = type;
4393
4394 return context->InvokeService(context, _OrthancPluginService_StorageAreaRemove, &params);
4395 }
4396
4397
4398
4399 typedef struct
4400 {
4401 OrthancPluginErrorCode* target;
4402 int32_t code;
4403 uint16_t httpStatus;
4404 const char* message;
4405 } _OrthancPluginRegisterErrorCode;
4406
4407 /**
4408 * @brief Declare a custom error code for this plugin.
4409 *
4410 * This function declares a custom error code that can be generated
4411 * by this plugin. This declaration is used to enrich the body of
4412 * the HTTP answer in the case of an error, and to set the proper
4413 * HTTP status code.
4414 *
4415 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4416 * @param code The error code that is internal to this plugin.
4417 * @param httpStatus The HTTP status corresponding to this error.
4418 * @param message The description of the error.
4419 * @return The error code that has been assigned inside the Orthanc core.
4420 * @ingroup Toolbox
4421 **/
4422 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRegisterErrorCode(
4423 OrthancPluginContext* context,
4424 int32_t code,
4425 uint16_t httpStatus,
4426 const char* message)
4427 {
4428 OrthancPluginErrorCode target;
4429
4430 _OrthancPluginRegisterErrorCode params;
4431 params.target = &target;
4432 params.code = code;
4433 params.httpStatus = httpStatus;
4434 params.message = message;
4435
4436 if (context->InvokeService(context, _OrthancPluginService_RegisterErrorCode, &params) == OrthancPluginErrorCode_Success)
4437 {
4438 return target;
4439 }
4440 else
4441 {
4442 /* There was an error while assigned the error. Use a generic code. */
4443 return OrthancPluginErrorCode_Plugin;
4444 }
4445 }
4446
4447
4448
4449 typedef struct
4450 {
4451 uint16_t group;
4452 uint16_t element;
4453 OrthancPluginValueRepresentation vr;
4454 const char* name;
4455 uint32_t minMultiplicity;
4456 uint32_t maxMultiplicity;
4457 } _OrthancPluginRegisterDictionaryTag;
4458
4459 /**
4460 * @brief Register a new tag into the DICOM dictionary.
4461 *
4462 * This function declares a new public tag in the dictionary of
4463 * DICOM tags that are known to Orthanc. This function should be
4464 * used in the OrthancPluginInitialize() callback.
4465 *
4466 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4467 * @param group The group of the tag.
4468 * @param element The element of the tag.
4469 * @param vr The value representation of the tag.
4470 * @param name The nickname of the tag.
4471 * @param minMultiplicity The minimum multiplicity of the tag (must be above 0).
4472 * @param maxMultiplicity The maximum multiplicity of the tag. A value of 0 means
4473 * an arbitrary multiplicity ("<tt>n</tt>").
4474 * @return 0 if success, other value if error.
4475 * @see OrthancPluginRegisterPrivateDictionaryTag()
4476 * @ingroup Toolbox
4477 **/
4478 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRegisterDictionaryTag(
4479 OrthancPluginContext* context,
4480 uint16_t group,
4481 uint16_t element,
4482 OrthancPluginValueRepresentation vr,
4483 const char* name,
4484 uint32_t minMultiplicity,
4485 uint32_t maxMultiplicity)
4486 {
4487 _OrthancPluginRegisterDictionaryTag params;
4488 params.group = group;
4489 params.element = element;
4490 params.vr = vr;
4491 params.name = name;
4492 params.minMultiplicity = minMultiplicity;
4493 params.maxMultiplicity = maxMultiplicity;
4494
4495 return context->InvokeService(context, _OrthancPluginService_RegisterDictionaryTag, &params);
4496 }
4497
4498
4499
4500 typedef struct
4501 {
4502 uint16_t group;
4503 uint16_t element;
4504 OrthancPluginValueRepresentation vr;
4505 const char* name;
4506 uint32_t minMultiplicity;
4507 uint32_t maxMultiplicity;
4508 const char* privateCreator;
4509 } _OrthancPluginRegisterPrivateDictionaryTag;
4510
4511 /**
4512 * @brief Register a new private tag into the DICOM dictionary.
4513 *
4514 * This function declares a new private tag in the dictionary of
4515 * DICOM tags that are known to Orthanc. This function should be
4516 * used in the OrthancPluginInitialize() callback.
4517 *
4518 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4519 * @param group The group of the tag.
4520 * @param element The element of the tag.
4521 * @param vr The value representation of the tag.
4522 * @param name The nickname of the tag.
4523 * @param minMultiplicity The minimum multiplicity of the tag (must be above 0).
4524 * @param maxMultiplicity The maximum multiplicity of the tag. A value of 0 means
4525 * an arbitrary multiplicity ("<tt>n</tt>").
4526 * @param privateCreator The private creator of this private tag.
4527 * @return 0 if success, other value if error.
4528 * @see OrthancPluginRegisterDictionaryTag()
4529 * @ingroup Toolbox
4530 **/
4531 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRegisterPrivateDictionaryTag(
4532 OrthancPluginContext* context,
4533 uint16_t group,
4534 uint16_t element,
4535 OrthancPluginValueRepresentation vr,
4536 const char* name,
4537 uint32_t minMultiplicity,
4538 uint32_t maxMultiplicity,
4539 const char* privateCreator)
4540 {
4541 _OrthancPluginRegisterPrivateDictionaryTag params;
4542 params.group = group;
4543 params.element = element;
4544 params.vr = vr;
4545 params.name = name;
4546 params.minMultiplicity = minMultiplicity;
4547 params.maxMultiplicity = maxMultiplicity;
4548 params.privateCreator = privateCreator;
4549
4550 return context->InvokeService(context, _OrthancPluginService_RegisterPrivateDictionaryTag, &params);
4551 }
4552
4553
4554
4555 typedef struct
4556 {
4557 OrthancPluginStorageArea* storageArea;
4558 OrthancPluginResourceType level;
4559 } _OrthancPluginReconstructMainDicomTags;
4560
4561 /**
4562 * @brief Reconstruct the main DICOM tags.
4563 *
4564 * This function requests the Orthanc core to reconstruct the main
4565 * DICOM tags of all the resources of the given type. This function
4566 * can only be used as a part of the upgrade of a custom database
4567 * back-end. A database transaction will be automatically setup.
4568 *
4569 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4570 * @param storageArea The storage area.
4571 * @param level The type of the resources of interest.
4572 * @return 0 if success, other value if error.
4573 * @ingroup Callbacks
4574 **/
4575 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginReconstructMainDicomTags(
4576 OrthancPluginContext* context,
4577 OrthancPluginStorageArea* storageArea,
4578 OrthancPluginResourceType level)
4579 {
4580 _OrthancPluginReconstructMainDicomTags params;
4581 params.level = level;
4582 params.storageArea = storageArea;
4583
4584 return context->InvokeService(context, _OrthancPluginService_ReconstructMainDicomTags, &params);
4585 }
4586
4587
4588 typedef struct
4589 {
4590 char** result;
4591 const char* instanceId;
4592 const void* buffer;
4593 uint32_t size;
4594 OrthancPluginDicomToJsonFormat format;
4595 OrthancPluginDicomToJsonFlags flags;
4596 uint32_t maxStringLength;
4597 } _OrthancPluginDicomToJson;
4598
4599
4600 /**
4601 * @brief Format a DICOM memory buffer as a JSON string.
4602 *
4603 * This function takes as input a memory buffer containing a DICOM
4604 * file, and outputs a JSON string representing the tags of this
4605 * DICOM file.
4606 *
4607 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4608 * @param buffer The memory buffer containing the DICOM file.
4609 * @param size The size of the memory buffer.
4610 * @param format The output format.
4611 * @param flags Flags governing the output.
4612 * @param maxStringLength The maximum length of a field. Too long fields will
4613 * be output as "null". The 0 value means no maximum length.
4614 * @return The NULL value if the case of an error, or the JSON
4615 * string. This string must be freed by OrthancPluginFreeString().
4616 * @ingroup Toolbox
4617 * @see OrthancPluginDicomInstanceToJson
4618 **/
4619 ORTHANC_PLUGIN_INLINE char* OrthancPluginDicomBufferToJson(
4620 OrthancPluginContext* context,
4621 const void* buffer,
4622 uint32_t size,
4623 OrthancPluginDicomToJsonFormat format,
4624 OrthancPluginDicomToJsonFlags flags,
4625 uint32_t maxStringLength)
4626 {
4627 char* result;
4628
4629 _OrthancPluginDicomToJson params;
4630 memset(&params, 0, sizeof(params));
4631 params.result = &result;
4632 params.buffer = buffer;
4633 params.size = size;
4634 params.format = format;
4635 params.flags = flags;
4636 params.maxStringLength = maxStringLength;
4637
4638 if (context->InvokeService(context, _OrthancPluginService_DicomBufferToJson, &params) != OrthancPluginErrorCode_Success)
4639 {
4640 /* Error */
4641 return NULL;
4642 }
4643 else
4644 {
4645 return result;
4646 }
4647 }
4648
4649
4650 /**
4651 * @brief Format a DICOM instance as a JSON string.
4652 *
4653 * This function formats a DICOM instance that is stored in Orthanc,
4654 * and outputs a JSON string representing the tags of this DICOM
4655 * instance.
4656 *
4657 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4658 * @param instanceId The Orthanc identifier of the instance.
4659 * @param format The output format.
4660 * @param flags Flags governing the output.
4661 * @param maxStringLength The maximum length of a field. Too long fields will
4662 * be output as "null". The 0 value means no maximum length.
4663 * @return The NULL value if the case of an error, or the JSON
4664 * string. This string must be freed by OrthancPluginFreeString().
4665 * @ingroup Toolbox
4666 * @see OrthancPluginDicomInstanceToJson
4667 **/
4668 ORTHANC_PLUGIN_INLINE char* OrthancPluginDicomInstanceToJson(
4669 OrthancPluginContext* context,
4670 const char* instanceId,
4671 OrthancPluginDicomToJsonFormat format,
4672 OrthancPluginDicomToJsonFlags flags,
4673 uint32_t maxStringLength)
4674 {
4675 char* result;
4676
4677 _OrthancPluginDicomToJson params;
4678 memset(&params, 0, sizeof(params));
4679 params.result = &result;
4680 params.instanceId = instanceId;
4681 params.format = format;
4682 params.flags = flags;
4683 params.maxStringLength = maxStringLength;
4684
4685 if (context->InvokeService(context, _OrthancPluginService_DicomInstanceToJson, &params) != OrthancPluginErrorCode_Success)
4686 {
4687 /* Error */
4688 return NULL;
4689 }
4690 else
4691 {
4692 return result;
4693 }
4694 }
4695
4696
4697 typedef struct
4698 {
4699 OrthancPluginMemoryBuffer* target;
4700 const char* uri;
4701 uint32_t headersCount;
4702 const char* const* headersKeys;
4703 const char* const* headersValues;
4704 int32_t afterPlugins;
4705 } _OrthancPluginRestApiGet2;
4706
4707 /**
4708 * @brief Make a GET call to the Orthanc REST API, with custom HTTP headers.
4709 *
4710 * Make a GET call to the Orthanc REST API with extended
4711 * parameters. The result to the query is stored into a newly
4712 * allocated memory buffer.
4713 *
4714 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4715 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
4716 * @param uri The URI in the built-in Orthanc API.
4717 * @param headersCount The number of HTTP headers.
4718 * @param headersKeys Array containing the keys of the HTTP headers (can be <tt>NULL</tt> if no header).
4719 * @param headersValues Array containing the values of the HTTP headers (can be <tt>NULL</tt> if no header).
4720 * @param afterPlugins If 0, the built-in API of Orthanc is used.
4721 * If 1, the API is tainted by the plugins.
4722 * @return 0 if success, or the error code if failure.
4723 * @see OrthancPluginRestApiGet, OrthancPluginRestApiGetAfterPlugins
4724 * @ingroup Orthanc
4725 **/
4726 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRestApiGet2(
4727 OrthancPluginContext* context,
4728 OrthancPluginMemoryBuffer* target,
4729 const char* uri,
4730 uint32_t headersCount,
4731 const char* const* headersKeys,
4732 const char* const* headersValues,
4733 int32_t afterPlugins)
4734 {
4735 _OrthancPluginRestApiGet2 params;
4736 params.target = target;
4737 params.uri = uri;
4738 params.headersCount = headersCount;
4739 params.headersKeys = headersKeys;
4740 params.headersValues = headersValues;
4741 params.afterPlugins = afterPlugins;
4742
4743 return context->InvokeService(context, _OrthancPluginService_RestApiGet2, &params);
4744 }
4745
4746
4747
4748 typedef struct
4749 {
4750 OrthancPluginWorklistCallback callback;
4751 } _OrthancPluginWorklistCallback;
4752
4753 /**
4754 * @brief Register a callback to handle modality worklists requests.
4755 *
4756 * This function registers a callback to handle C-Find SCP requests
4757 * on modality worklists.
4758 *
4759 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4760 * @param callback The callback.
4761 * @return 0 if success, other value if error.
4762 * @ingroup DicomCallbacks
4763 **/
4764 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRegisterWorklistCallback(
4765 OrthancPluginContext* context,
4766 OrthancPluginWorklistCallback callback)
4767 {
4768 _OrthancPluginWorklistCallback params;
4769 params.callback = callback;
4770
4771 return context->InvokeService(context, _OrthancPluginService_RegisterWorklistCallback, &params);
4772 }
4773
4774
4775
4776 typedef struct
4777 {
4778 OrthancPluginWorklistAnswers* answers;
4779 const OrthancPluginWorklistQuery* query;
4780 const void* dicom;
4781 uint32_t size;
4782 } _OrthancPluginWorklistAnswersOperation;
4783
4784 /**
4785 * @brief Add one answer to some modality worklist request.
4786 *
4787 * This function adds one worklist (encoded as a DICOM file) to the
4788 * set of answers corresponding to some C-Find SCP request against
4789 * modality worklists.
4790 *
4791 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4792 * @param answers The set of answers.
4793 * @param query The worklist query, as received by the callback.
4794 * @param dicom The worklist to answer, encoded as a DICOM file.
4795 * @param size The size of the DICOM file.
4796 * @return 0 if success, other value if error.
4797 * @ingroup DicomCallbacks
4798 * @see OrthancPluginCreateDicom()
4799 **/
4800 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginWorklistAddAnswer(
4801 OrthancPluginContext* context,
4802 OrthancPluginWorklistAnswers* answers,
4803 const OrthancPluginWorklistQuery* query,
4804 const void* dicom,
4805 uint32_t size)
4806 {
4807 _OrthancPluginWorklistAnswersOperation params;
4808 params.answers = answers;
4809 params.query = query;
4810 params.dicom = dicom;
4811 params.size = size;
4812
4813 return context->InvokeService(context, _OrthancPluginService_WorklistAddAnswer, &params);
4814 }
4815
4816
4817 /**
4818 * @brief Mark the set of worklist answers as incomplete.
4819 *
4820 * This function marks as incomplete the set of answers
4821 * corresponding to some C-Find SCP request against modality
4822 * worklists. This must be used if canceling the handling of a
4823 * request when too many answers are to be returned.
4824 *
4825 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4826 * @param answers The set of answers.
4827 * @return 0 if success, other value if error.
4828 * @ingroup DicomCallbacks
4829 **/
4830 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginWorklistMarkIncomplete(
4831 OrthancPluginContext* context,
4832 OrthancPluginWorklistAnswers* answers)
4833 {
4834 _OrthancPluginWorklistAnswersOperation params;
4835 params.answers = answers;
4836 params.query = NULL;
4837 params.dicom = NULL;
4838 params.size = 0;
4839
4840 return context->InvokeService(context, _OrthancPluginService_WorklistMarkIncomplete, &params);
4841 }
4842
4843
4844 typedef struct
4845 {
4846 const OrthancPluginWorklistQuery* query;
4847 const void* dicom;
4848 uint32_t size;
4849 int32_t* isMatch;
4850 OrthancPluginMemoryBuffer* target;
4851 } _OrthancPluginWorklistQueryOperation;
4852
4853 /**
4854 * @brief Test whether a worklist matches the query.
4855 *
4856 * This function checks whether one worklist (encoded as a DICOM
4857 * file) matches the C-Find SCP query against modality
4858 * worklists. This function must be called before adding the
4859 * worklist as an answer through OrthancPluginWorklistAddAnswer().
4860 *
4861 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4862 * @param query The worklist query, as received by the callback.
4863 * @param dicom The worklist to answer, encoded as a DICOM file.
4864 * @param size The size of the DICOM file.
4865 * @return 1 if the worklist matches the query, 0 otherwise.
4866 * @ingroup DicomCallbacks
4867 **/
4868 ORTHANC_PLUGIN_INLINE int32_t OrthancPluginWorklistIsMatch(
4869 OrthancPluginContext* context,
4870 const OrthancPluginWorklistQuery* query,
4871 const void* dicom,
4872 uint32_t size)
4873 {
4874 int32_t isMatch = 0;
4875
4876 _OrthancPluginWorklistQueryOperation params;
4877 params.query = query;
4878 params.dicom = dicom;
4879 params.size = size;
4880 params.isMatch = &isMatch;
4881 params.target = NULL;
4882
4883 if (context->InvokeService(context, _OrthancPluginService_WorklistIsMatch, &params) == OrthancPluginErrorCode_Success)
4884 {
4885 return isMatch;
4886 }
4887 else
4888 {
4889 /* Error: Assume non-match */
4890 return 0;
4891 }
4892 }
4893
4894
4895 /**
4896 * @brief Retrieve the worklist query as a DICOM file.
4897 *
4898 * This function retrieves the DICOM file that underlies a C-Find
4899 * SCP query against modality worklists.
4900 *
4901 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4902 * @param target Memory buffer where to store the DICOM file. It must be freed with OrthancPluginFreeMemoryBuffer().
4903 * @param query The worklist query, as received by the callback.
4904 * @return 0 if success, other value if error.
4905 * @ingroup DicomCallbacks
4906 **/
4907 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginWorklistGetDicomQuery(
4908 OrthancPluginContext* context,
4909 OrthancPluginMemoryBuffer* target,
4910 const OrthancPluginWorklistQuery* query)
4911 {
4912 _OrthancPluginWorklistQueryOperation params;
4913 params.query = query;
4914 params.dicom = NULL;
4915 params.size = 0;
4916 params.isMatch = NULL;
4917 params.target = target;
4918
4919 return context->InvokeService(context, _OrthancPluginService_WorklistGetDicomQuery, &params);
4920 }
4921
4922
4923 /**
4924 * @brief Get the origin of a DICOM file.
4925 *
4926 * This function returns the origin of a DICOM instance that has been received by Orthanc.
4927 *
4928 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4929 * @param instance The instance of interest.
4930 * @return The origin of the instance.
4931 * @ingroup Callbacks
4932 **/
4933 ORTHANC_PLUGIN_INLINE OrthancPluginInstanceOrigin OrthancPluginGetInstanceOrigin(
4934 OrthancPluginContext* context,
4935 OrthancPluginDicomInstance* instance)
4936 {
4937 OrthancPluginInstanceOrigin origin;
4938
4939 _OrthancPluginAccessDicomInstance params;
4940 memset(&params, 0, sizeof(params));
4941 params.resultOrigin = &origin;
4942 params.instance = instance;
4943
4944 if (context->InvokeService(context, _OrthancPluginService_GetInstanceOrigin, &params) != OrthancPluginErrorCode_Success)
4945 {
4946 /* Error */
4947 return OrthancPluginInstanceOrigin_Unknown;
4948 }
4949 else
4950 {
4951 return origin;
4952 }
4953 }
4954
4955
4956 typedef struct
4957 {
4958 OrthancPluginMemoryBuffer* target;
4959 const char* json;
4960 const OrthancPluginImage* pixelData;
4961 OrthancPluginCreateDicomFlags flags;
4962 } _OrthancPluginCreateDicom;
4963
4964 /**
4965 * @brief Create a DICOM instance from a JSON string and an image.
4966 *
4967 * This function takes as input a string containing a JSON file
4968 * describing the content of a DICOM instance. As an output, it
4969 * writes the corresponding DICOM instance to a newly allocated
4970 * memory buffer. Additionally, an image to be encoded within the
4971 * DICOM instance can also be provided.
4972 *
4973 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
4974 * @param target The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
4975 * @param json The input JSON file.
4976 * @param pixelData The image. Can be NULL, if the pixel data is encoded inside the JSON with the data URI scheme.
4977 * @param flags Flags governing the output.
4978 * @return 0 if success, other value if error.
4979 * @ingroup Toolbox
4980 * @see OrthancPluginDicomBufferToJson
4981 **/
4982 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginCreateDicom(
4983 OrthancPluginContext* context,
4984 OrthancPluginMemoryBuffer* target,
4985 const char* json,
4986 const OrthancPluginImage* pixelData,
4987 OrthancPluginCreateDicomFlags flags)
4988 {
4989 _OrthancPluginCreateDicom params;
4990 params.target = target;
4991 params.json = json;
4992 params.pixelData = pixelData;
4993 params.flags = flags;
4994
4995 return context->InvokeService(context, _OrthancPluginService_CreateDicom, &params);
4996 }
4997
4998
4999 typedef struct
5000 {
5001 OrthancPluginDecodeImageCallback callback;
5002 } _OrthancPluginDecodeImageCallback;
5003
5004 /**
5005 * @brief Register a callback to handle the decoding of DICOM images.
5006 *
5007 * This function registers a custom callback to the decoding of
5008 * DICOM images, replacing the built-in decoder of Orthanc.
5009 *
5010 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5011 * @param callback The callback.
5012 * @return 0 if success, other value if error.
5013 * @ingroup Callbacks
5014 **/
5015 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRegisterDecodeImageCallback(
5016 OrthancPluginContext* context,
5017 OrthancPluginDecodeImageCallback callback)
5018 {
5019 _OrthancPluginDecodeImageCallback params;
5020 params.callback = callback;
5021
5022 return context->InvokeService(context, _OrthancPluginService_RegisterDecodeImageCallback, &params);
5023 }
5024
5025
5026
5027 typedef struct
5028 {
5029 OrthancPluginImage** target;
5030 OrthancPluginPixelFormat format;
5031 uint32_t width;
5032 uint32_t height;
5033 uint32_t pitch;
5034 void* buffer;
5035 const void* constBuffer;
5036 uint32_t bufferSize;
5037 uint32_t frameIndex;
5038 } _OrthancPluginCreateImage;
5039
5040
5041 /**
5042 * @brief Create an image.
5043 *
5044 * This function creates an image of given size and format.
5045 *
5046 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5047 * @param format The format of the pixels.
5048 * @param width The width of the image.
5049 * @param height The height of the image.
5050 * @return The newly allocated image. It must be freed with OrthancPluginFreeImage().
5051 * @ingroup Images
5052 **/
5053 ORTHANC_PLUGIN_INLINE OrthancPluginImage* OrthancPluginCreateImage(
5054 OrthancPluginContext* context,
5055 OrthancPluginPixelFormat format,
5056 uint32_t width,
5057 uint32_t height)
5058 {
5059 OrthancPluginImage* target = NULL;
5060
5061 _OrthancPluginCreateImage params;
5062 memset(&params, 0, sizeof(params));
5063 params.target = &target;
5064 params.format = format;
5065 params.width = width;
5066 params.height = height;
5067
5068 if (context->InvokeService(context, _OrthancPluginService_CreateImage, &params) != OrthancPluginErrorCode_Success)
5069 {
5070 return NULL;
5071 }
5072 else
5073 {
5074 return target;
5075 }
5076 }
5077
5078
5079 /**
5080 * @brief Create an image pointing to a memory buffer.
5081 *
5082 * This function creates an image whose content points to a memory
5083 * buffer managed by the plugin. Note that the buffer is directly
5084 * accessed, no memory is allocated and no data is copied.
5085 *
5086 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5087 * @param format The format of the pixels.
5088 * @param width The width of the image.
5089 * @param height The height of the image.
5090 * @param pitch The pitch of the image (i.e. the number of bytes
5091 * between 2 successive lines of the image in the memory buffer).
5092 * @param buffer The memory buffer.
5093 * @return The newly allocated image. It must be freed with OrthancPluginFreeImage().
5094 * @ingroup Images
5095 **/
5096 ORTHANC_PLUGIN_INLINE OrthancPluginImage* OrthancPluginCreateImageAccessor(
5097 OrthancPluginContext* context,
5098 OrthancPluginPixelFormat format,
5099 uint32_t width,
5100 uint32_t height,
5101 uint32_t pitch,
5102 void* buffer)
5103 {
5104 OrthancPluginImage* target = NULL;
5105
5106 _OrthancPluginCreateImage params;
5107 memset(&params, 0, sizeof(params));
5108 params.target = &target;
5109 params.format = format;
5110 params.width = width;
5111 params.height = height;
5112 params.pitch = pitch;
5113 params.buffer = buffer;
5114
5115 if (context->InvokeService(context, _OrthancPluginService_CreateImageAccessor, &params) != OrthancPluginErrorCode_Success)
5116 {
5117 return NULL;
5118 }
5119 else
5120 {
5121 return target;
5122 }
5123 }
5124
5125
5126
5127 /**
5128 * @brief Decode one frame from a DICOM instance.
5129 *
5130 * This function decodes one frame of a DICOM image that is stored
5131 * in a memory buffer. This function will give the same result as
5132 * OrthancPluginUncompressImage() for single-frame DICOM images.
5133 *
5134 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5135 * @param buffer Pointer to a memory buffer containing the DICOM image.
5136 * @param bufferSize Size of the memory buffer containing the DICOM image.
5137 * @param frameIndex The index of the frame of interest in a multi-frame image.
5138 * @return The uncompressed image. It must be freed with OrthancPluginFreeImage().
5139 * @ingroup Images
5140 **/
5141 ORTHANC_PLUGIN_INLINE OrthancPluginImage* OrthancPluginDecodeDicomImage(
5142 OrthancPluginContext* context,
5143 const void* buffer,
5144 uint32_t bufferSize,
5145 uint32_t frameIndex)
5146 {
5147 OrthancPluginImage* target = NULL;
5148
5149 _OrthancPluginCreateImage params;
5150 memset(&params, 0, sizeof(params));
5151 params.target = &target;
5152 params.constBuffer = buffer;
5153 params.bufferSize = bufferSize;
5154 params.frameIndex = frameIndex;
5155
5156 if (context->InvokeService(context, _OrthancPluginService_DecodeDicomImage, &params) != OrthancPluginErrorCode_Success)
5157 {
5158 return NULL;
5159 }
5160 else
5161 {
5162 return target;
5163 }
5164 }
5165
5166
5167
5168 typedef struct
5169 {
5170 char** result;
5171 const void* buffer;
5172 uint32_t size;
5173 } _OrthancPluginComputeHash;
5174
5175 /**
5176 * @brief Compute an MD5 hash.
5177 *
5178 * This functions computes the MD5 cryptographic hash of the given memory buffer.
5179 *
5180 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5181 * @param buffer The source memory buffer.
5182 * @param size The size in bytes of the source buffer.
5183 * @return The NULL value in case of error, or a string containing the cryptographic hash.
5184 * This string must be freed by OrthancPluginFreeString().
5185 * @ingroup Toolbox
5186 **/
5187 ORTHANC_PLUGIN_INLINE char* OrthancPluginComputeMd5(
5188 OrthancPluginContext* context,
5189 const void* buffer,
5190 uint32_t size)
5191 {
5192 char* result;
5193
5194 _OrthancPluginComputeHash params;
5195 params.result = &result;
5196 params.buffer = buffer;
5197 params.size = size;
5198
5199 if (context->InvokeService(context, _OrthancPluginService_ComputeMd5, &params) != OrthancPluginErrorCode_Success)
5200 {
5201 /* Error */
5202 return NULL;
5203 }
5204 else
5205 {
5206 return result;
5207 }
5208 }
5209
5210
5211 /**
5212 * @brief Compute a SHA-1 hash.
5213 *
5214 * This functions computes the SHA-1 cryptographic hash of the given memory buffer.
5215 *
5216 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5217 * @param buffer The source memory buffer.
5218 * @param size The size in bytes of the source buffer.
5219 * @return The NULL value in case of error, or a string containing the cryptographic hash.
5220 * This string must be freed by OrthancPluginFreeString().
5221 * @ingroup Toolbox
5222 **/
5223 ORTHANC_PLUGIN_INLINE char* OrthancPluginComputeSha1(
5224 OrthancPluginContext* context,
5225 const void* buffer,
5226 uint32_t size)
5227 {
5228 char* result;
5229
5230 _OrthancPluginComputeHash params;
5231 params.result = &result;
5232 params.buffer = buffer;
5233 params.size = size;
5234
5235 if (context->InvokeService(context, _OrthancPluginService_ComputeSha1, &params) != OrthancPluginErrorCode_Success)
5236 {
5237 /* Error */
5238 return NULL;
5239 }
5240 else
5241 {
5242 return result;
5243 }
5244 }
5245
5246
5247
5248 typedef struct
5249 {
5250 OrthancPluginDictionaryEntry* target;
5251 const char* name;
5252 } _OrthancPluginLookupDictionary;
5253
5254 /**
5255 * @brief Get information about the given DICOM tag.
5256 *
5257 * This functions makes a lookup in the dictionary of DICOM tags
5258 * that are known to Orthanc, and returns information about this
5259 * tag. The tag can be specified using its human-readable name
5260 * (e.g. "PatientName") or a set of two hexadecimal numbers
5261 * (e.g. "0010-0020").
5262 *
5263 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5264 * @param target Where to store the information about the tag.
5265 * @param name The name of the DICOM tag.
5266 * @return 0 if success, other value if error.
5267 * @ingroup Toolbox
5268 **/
5269 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginLookupDictionary(
5270 OrthancPluginContext* context,
5271 OrthancPluginDictionaryEntry* target,
5272 const char* name)
5273 {
5274 _OrthancPluginLookupDictionary params;
5275 params.target = target;
5276 params.name = name;
5277 return context->InvokeService(context, _OrthancPluginService_LookupDictionary, &params);
5278 }
5279
5280
5281
5282 typedef struct
5283 {
5284 OrthancPluginRestOutput* output;
5285 const char* answer;
5286 uint32_t answerSize;
5287 uint32_t headersCount;
5288 const char* const* headersKeys;
5289 const char* const* headersValues;
5290 } _OrthancPluginSendMultipartItem2;
5291
5292 /**
5293 * @brief Send an item as a part of some HTTP multipart answer, with custom headers.
5294 *
5295 * This function sends an item as a part of some HTTP multipart
5296 * answer that was initiated by OrthancPluginStartMultipartAnswer(). In addition to
5297 * OrthancPluginSendMultipartItem(), this function will set HTTP header associated
5298 * with the item.
5299 *
5300 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5301 * @param output The HTTP connection to the client application.
5302 * @param answer Pointer to the memory buffer containing the item.
5303 * @param answerSize Number of bytes of the item.
5304 * @param headersCount The number of HTTP headers.
5305 * @param headersKeys Array containing the keys of the HTTP headers.
5306 * @param headersValues Array containing the values of the HTTP headers.
5307 * @return 0 if success, or the error code if failure (this notably happens
5308 * if the connection is closed by the client).
5309 * @see OrthancPluginSendMultipartItem()
5310 * @ingroup REST
5311 **/
5312 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginSendMultipartItem2(
5313 OrthancPluginContext* context,
5314 OrthancPluginRestOutput* output,
5315 const char* answer,
5316 uint32_t answerSize,
5317 uint32_t headersCount,
5318 const char* const* headersKeys,
5319 const char* const* headersValues)
5320 {
5321 _OrthancPluginSendMultipartItem2 params;
5322 params.output = output;
5323 params.answer = answer;
5324 params.answerSize = answerSize;
5325 params.headersCount = headersCount;
5326 params.headersKeys = headersKeys;
5327 params.headersValues = headersValues;
5328
5329 return context->InvokeService(context, _OrthancPluginService_SendMultipartItem2, &params);
5330 }
5331
5332
5333 typedef struct
5334 {
5335 OrthancPluginIncomingHttpRequestFilter callback;
5336 } _OrthancPluginIncomingHttpRequestFilter;
5337
5338 /**
5339 * @brief Register a callback to filter incoming HTTP requests.
5340 *
5341 * This function registers a custom callback to filter incoming HTTP/REST
5342 * requests received by the HTTP server of Orthanc.
5343 *
5344 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5345 * @param callback The callback.
5346 * @return 0 if success, other value if error.
5347 * @ingroup Callbacks
5348 * @deprecated Please instead use OrthancPluginRegisterIncomingHttpRequestFilter2()
5349 **/
5350 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRegisterIncomingHttpRequestFilter(
5351 OrthancPluginContext* context,
5352 OrthancPluginIncomingHttpRequestFilter callback)
5353 {
5354 _OrthancPluginIncomingHttpRequestFilter params;
5355 params.callback = callback;
5356
5357 return context->InvokeService(context, _OrthancPluginService_RegisterIncomingHttpRequestFilter, &params);
5358 }
5359
5360
5361
5362 typedef struct
5363 {
5364 OrthancPluginMemoryBuffer* answerBody;
5365 OrthancPluginMemoryBuffer* answerHeaders;
5366 uint16_t* httpStatus;
5367 OrthancPluginHttpMethod method;
5368 const char* url;
5369 uint32_t headersCount;
5370 const char* const* headersKeys;
5371 const char* const* headersValues;
5372 const char* body;
5373 uint32_t bodySize;
5374 const char* username;
5375 const char* password;
5376 uint32_t timeout;
5377 const char* certificateFile;
5378 const char* certificateKeyFile;
5379 const char* certificateKeyPassword;
5380 uint8_t pkcs11;
5381 } _OrthancPluginCallHttpClient2;
5382
5383
5384
5385 /**
5386 * @brief Issue a HTTP call with full flexibility.
5387 *
5388 * Make a HTTP call to the given URL. The result to the query is
5389 * stored into a newly allocated memory buffer. The HTTP request
5390 * will be done accordingly to the global configuration of Orthanc
5391 * (in particular, the options "HttpProxy", "HttpTimeout",
5392 * "HttpsVerifyPeers", "HttpsCACertificates", and "Pkcs11" will be
5393 * taken into account).
5394 *
5395 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5396 * @param answerBody The target memory buffer (out argument).
5397 * It must be freed with OrthancPluginFreeMemoryBuffer().
5398 * @param answerHeaders The target memory buffer for the HTTP headers in the answers (out argument).
5399 * The answer headers are formatted as a JSON object (associative array).
5400 * The buffer must be freed with OrthancPluginFreeMemoryBuffer().
5401 * This argument can be set to NULL if the plugin has no interest in the HTTP headers.
5402 * @param httpStatus The HTTP status after the execution of the request (out argument).
5403 * @param method HTTP method to be used.
5404 * @param url The URL of interest.
5405 * @param headersCount The number of HTTP headers.
5406 * @param headersKeys Array containing the keys of the HTTP headers (can be <tt>NULL</tt> if no header).
5407 * @param headersValues Array containing the values of the HTTP headers (can be <tt>NULL</tt> if no header).
5408 * @param username The username (can be <tt>NULL</tt> if no password protection).
5409 * @param password The password (can be <tt>NULL</tt> if no password protection).
5410 * @param body The HTTP body for a POST or PUT request.
5411 * @param bodySize The size of the body.
5412 * @param timeout Timeout in seconds (0 for default timeout).
5413 * @param certificateFile Path to the client certificate for HTTPS, in PEM format
5414 * (can be <tt>NULL</tt> if no client certificate or if not using HTTPS).
5415 * @param certificateKeyFile Path to the key of the client certificate for HTTPS, in PEM format
5416 * (can be <tt>NULL</tt> if no client certificate or if not using HTTPS).
5417 * @param certificateKeyPassword Password to unlock the key of the client certificate
5418 * (can be <tt>NULL</tt> if no client certificate or if not using HTTPS).
5419 * @param pkcs11 Enable PKCS#11 client authentication for hardware security modules and smart cards.
5420 * @return 0 if success, or the error code if failure.
5421 * @see OrthancPluginCallPeerApi()
5422 **/
5423 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginHttpClient(
5424 OrthancPluginContext* context,
5425 OrthancPluginMemoryBuffer* answerBody,
5426 OrthancPluginMemoryBuffer* answerHeaders,
5427 uint16_t* httpStatus,
5428 OrthancPluginHttpMethod method,
5429 const char* url,
5430 uint32_t headersCount,
5431 const char* const* headersKeys,
5432 const char* const* headersValues,
5433 const char* body,
5434 uint32_t bodySize,
5435 const char* username,
5436 const char* password,
5437 uint32_t timeout,
5438 const char* certificateFile,
5439 const char* certificateKeyFile,
5440 const char* certificateKeyPassword,
5441 uint8_t pkcs11)
5442 {
5443 _OrthancPluginCallHttpClient2 params;
5444 memset(&params, 0, sizeof(params));
5445
5446 params.answerBody = answerBody;
5447 params.answerHeaders = answerHeaders;
5448 params.httpStatus = httpStatus;
5449 params.method = method;
5450 params.url = url;
5451 params.headersCount = headersCount;
5452 params.headersKeys = headersKeys;
5453 params.headersValues = headersValues;
5454 params.body = body;
5455 params.bodySize = bodySize;
5456 params.username = username;
5457 params.password = password;
5458 params.timeout = timeout;
5459 params.certificateFile = certificateFile;
5460 params.certificateKeyFile = certificateKeyFile;
5461 params.certificateKeyPassword = certificateKeyPassword;
5462 params.pkcs11 = pkcs11;
5463
5464 return context->InvokeService(context, _OrthancPluginService_CallHttpClient2, &params);
5465 }
5466
5467
5468 /**
5469 * @brief Generate an UUID.
5470 *
5471 * Generate a random GUID/UUID (globally unique identifier).
5472 *
5473 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5474 * @return NULL in the case of an error, or a newly allocated string
5475 * containing the UUID. This string must be freed by OrthancPluginFreeString().
5476 * @ingroup Toolbox
5477 **/
5478 ORTHANC_PLUGIN_INLINE char* OrthancPluginGenerateUuid(
5479 OrthancPluginContext* context)
5480 {
5481 char* result;
5482
5483 _OrthancPluginRetrieveDynamicString params;
5484 params.result = &result;
5485 params.argument = NULL;
5486
5487 if (context->InvokeService(context, _OrthancPluginService_GenerateUuid, &params) != OrthancPluginErrorCode_Success)
5488 {
5489 /* Error */
5490 return NULL;
5491 }
5492 else
5493 {
5494 return result;
5495 }
5496 }
5497
5498
5499
5500
5501 typedef struct
5502 {
5503 OrthancPluginFindCallback callback;
5504 } _OrthancPluginFindCallback;
5505
5506 /**
5507 * @brief Register a callback to handle C-Find requests.
5508 *
5509 * This function registers a callback to handle C-Find SCP requests
5510 * that are not related to modality worklists.
5511 *
5512 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5513 * @param callback The callback.
5514 * @return 0 if success, other value if error.
5515 * @ingroup DicomCallbacks
5516 **/
5517 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRegisterFindCallback(
5518 OrthancPluginContext* context,
5519 OrthancPluginFindCallback callback)
5520 {
5521 _OrthancPluginFindCallback params;
5522 params.callback = callback;
5523
5524 return context->InvokeService(context, _OrthancPluginService_RegisterFindCallback, &params);
5525 }
5526
5527
5528 typedef struct
5529 {
5530 OrthancPluginFindAnswers *answers;
5531 const OrthancPluginFindQuery *query;
5532 const void *dicom;
5533 uint32_t size;
5534 uint32_t index;
5535 uint32_t *resultUint32;
5536 uint16_t *resultGroup;
5537 uint16_t *resultElement;
5538 char **resultString;
5539 } _OrthancPluginFindOperation;
5540
5541 /**
5542 * @brief Add one answer to some C-Find request.
5543 *
5544 * This function adds one answer (encoded as a DICOM file) to the
5545 * set of answers corresponding to some C-Find SCP request that is
5546 * not related to modality worklists.
5547 *
5548 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5549 * @param answers The set of answers.
5550 * @param dicom The answer to be added, encoded as a DICOM file.
5551 * @param size The size of the DICOM file.
5552 * @return 0 if success, other value if error.
5553 * @ingroup DicomCallbacks
5554 * @see OrthancPluginCreateDicom()
5555 **/
5556 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginFindAddAnswer(
5557 OrthancPluginContext* context,
5558 OrthancPluginFindAnswers* answers,
5559 const void* dicom,
5560 uint32_t size)
5561 {
5562 _OrthancPluginFindOperation params;
5563 memset(&params, 0, sizeof(params));
5564 params.answers = answers;
5565 params.dicom = dicom;
5566 params.size = size;
5567
5568 return context->InvokeService(context, _OrthancPluginService_FindAddAnswer, &params);
5569 }
5570
5571
5572 /**
5573 * @brief Mark the set of C-Find answers as incomplete.
5574 *
5575 * This function marks as incomplete the set of answers
5576 * corresponding to some C-Find SCP request that is not related to
5577 * modality worklists. This must be used if canceling the handling
5578 * of a request when too many answers are to be returned.
5579 *
5580 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5581 * @param answers The set of answers.
5582 * @return 0 if success, other value if error.
5583 * @ingroup DicomCallbacks
5584 **/
5585 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginFindMarkIncomplete(
5586 OrthancPluginContext* context,
5587 OrthancPluginFindAnswers* answers)
5588 {
5589 _OrthancPluginFindOperation params;
5590 memset(&params, 0, sizeof(params));
5591 params.answers = answers;
5592
5593 return context->InvokeService(context, _OrthancPluginService_FindMarkIncomplete, &params);
5594 }
5595
5596
5597
5598 /**
5599 * @brief Get the number of tags in a C-Find query.
5600 *
5601 * This function returns the number of tags that are contained in
5602 * the given C-Find query.
5603 *
5604 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5605 * @param query The C-Find query.
5606 * @return The number of tags.
5607 * @ingroup DicomCallbacks
5608 **/
5609 ORTHANC_PLUGIN_INLINE uint32_t OrthancPluginGetFindQuerySize(
5610 OrthancPluginContext* context,
5611 const OrthancPluginFindQuery* query)
5612 {
5613 uint32_t count = 0;
5614
5615 _OrthancPluginFindOperation params;
5616 memset(&params, 0, sizeof(params));
5617 params.query = query;
5618 params.resultUint32 = &count;
5619
5620 if (context->InvokeService(context, _OrthancPluginService_GetFindQuerySize, &params) != OrthancPluginErrorCode_Success)
5621 {
5622 /* Error */
5623 return 0;
5624 }
5625 else
5626 {
5627 return count;
5628 }
5629 }
5630
5631
5632 /**
5633 * @brief Get one tag in a C-Find query.
5634 *
5635 * This function returns the group and the element of one DICOM tag
5636 * in the given C-Find query.
5637 *
5638 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5639 * @param group The group of the tag (output).
5640 * @param element The element of the tag (output).
5641 * @param query The C-Find query.
5642 * @param index The index of the tag of interest.
5643 * @return 0 if success, other value if error.
5644 * @ingroup DicomCallbacks
5645 **/
5646 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginGetFindQueryTag(
5647 OrthancPluginContext* context,
5648 uint16_t* group,
5649 uint16_t* element,
5650 const OrthancPluginFindQuery* query,
5651 uint32_t index)
5652 {
5653 _OrthancPluginFindOperation params;
5654 memset(&params, 0, sizeof(params));
5655 params.query = query;
5656 params.index = index;
5657 params.resultGroup = group;
5658 params.resultElement = element;
5659
5660 return context->InvokeService(context, _OrthancPluginService_GetFindQueryTag, &params);
5661 }
5662
5663
5664 /**
5665 * @brief Get the symbolic name of one tag in a C-Find query.
5666 *
5667 * This function returns the symbolic name of one DICOM tag in the
5668 * given C-Find query.
5669 *
5670 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5671 * @param query The C-Find query.
5672 * @param index The index of the tag of interest.
5673 * @return The NULL value in case of error, or a string containing the name of the tag.
5674 * @return 0 if success, other value if error.
5675 * @ingroup DicomCallbacks
5676 **/
5677 ORTHANC_PLUGIN_INLINE char* OrthancPluginGetFindQueryTagName(
5678 OrthancPluginContext* context,
5679 const OrthancPluginFindQuery* query,
5680 uint32_t index)
5681 {
5682 char* result;
5683
5684 _OrthancPluginFindOperation params;
5685 memset(&params, 0, sizeof(params));
5686 params.query = query;
5687 params.index = index;
5688 params.resultString = &result;
5689
5690 if (context->InvokeService(context, _OrthancPluginService_GetFindQueryTagName, &params) != OrthancPluginErrorCode_Success)
5691 {
5692 /* Error */
5693 return NULL;
5694 }
5695 else
5696 {
5697 return result;
5698 }
5699 }
5700
5701
5702 /**
5703 * @brief Get the value associated with one tag in a C-Find query.
5704 *
5705 * This function returns the value associated with one tag in the
5706 * given C-Find query.
5707 *
5708 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5709 * @param query The C-Find query.
5710 * @param index The index of the tag of interest.
5711 * @return The NULL value in case of error, or a string containing the value of the tag.
5712 * @return 0 if success, other value if error.
5713 * @ingroup DicomCallbacks
5714 **/
5715 ORTHANC_PLUGIN_INLINE char* OrthancPluginGetFindQueryValue(
5716 OrthancPluginContext* context,
5717 const OrthancPluginFindQuery* query,
5718 uint32_t index)
5719 {
5720 char* result;
5721
5722 _OrthancPluginFindOperation params;
5723 memset(&params, 0, sizeof(params));
5724 params.query = query;
5725 params.index = index;
5726 params.resultString = &result;
5727
5728 if (context->InvokeService(context, _OrthancPluginService_GetFindQueryValue, &params) != OrthancPluginErrorCode_Success)
5729 {
5730 /* Error */
5731 return NULL;
5732 }
5733 else
5734 {
5735 return result;
5736 }
5737 }
5738
5739
5740
5741
5742 typedef struct
5743 {
5744 OrthancPluginMoveCallback callback;
5745 OrthancPluginGetMoveSize getMoveSize;
5746 OrthancPluginApplyMove applyMove;
5747 OrthancPluginFreeMove freeMove;
5748 } _OrthancPluginMoveCallback;
5749
5750 /**
5751 * @brief Register a callback to handle C-Move requests.
5752 *
5753 * This function registers a callback to handle C-Move SCP requests.
5754 *
5755 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5756 * @param callback The main callback.
5757 * @param getMoveSize Callback to read the number of C-Move suboperations.
5758 * @param applyMove Callback to apply one C-Move suboperations.
5759 * @param freeMove Callback to free the C-Move driver.
5760 * @return 0 if success, other value if error.
5761 * @ingroup DicomCallbacks
5762 **/
5763 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRegisterMoveCallback(
5764 OrthancPluginContext* context,
5765 OrthancPluginMoveCallback callback,
5766 OrthancPluginGetMoveSize getMoveSize,
5767 OrthancPluginApplyMove applyMove,
5768 OrthancPluginFreeMove freeMove)
5769 {
5770 _OrthancPluginMoveCallback params;
5771 params.callback = callback;
5772 params.getMoveSize = getMoveSize;
5773 params.applyMove = applyMove;
5774 params.freeMove = freeMove;
5775
5776 return context->InvokeService(context, _OrthancPluginService_RegisterMoveCallback, &params);
5777 }
5778
5779
5780
5781 typedef struct
5782 {
5783 OrthancPluginFindMatcher** target;
5784 const void* query;
5785 uint32_t size;
5786 } _OrthancPluginCreateFindMatcher;
5787
5788
5789 /**
5790 * @brief Create a C-Find matcher.
5791 *
5792 * This function creates a "matcher" object that can be used to
5793 * check whether a DICOM instance matches a C-Find query. The C-Find
5794 * query must be expressed as a DICOM buffer.
5795 *
5796 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5797 * @param query The C-Find DICOM query.
5798 * @param size The size of the DICOM query.
5799 * @return The newly allocated matcher. It must be freed with OrthancPluginFreeFindMatcher().
5800 * @ingroup Toolbox
5801 **/
5802 ORTHANC_PLUGIN_INLINE OrthancPluginFindMatcher* OrthancPluginCreateFindMatcher(
5803 OrthancPluginContext* context,
5804 const void* query,
5805 uint32_t size)
5806 {
5807 OrthancPluginFindMatcher* target = NULL;
5808
5809 _OrthancPluginCreateFindMatcher params;
5810 memset(&params, 0, sizeof(params));
5811 params.target = &target;
5812 params.query = query;
5813 params.size = size;
5814
5815 if (context->InvokeService(context, _OrthancPluginService_CreateFindMatcher, &params) != OrthancPluginErrorCode_Success)
5816 {
5817 return NULL;
5818 }
5819 else
5820 {
5821 return target;
5822 }
5823 }
5824
5825
5826 typedef struct
5827 {
5828 OrthancPluginFindMatcher* matcher;
5829 } _OrthancPluginFreeFindMatcher;
5830
5831 /**
5832 * @brief Free a C-Find matcher.
5833 *
5834 * This function frees a matcher that was created using OrthancPluginCreateFindMatcher().
5835 *
5836 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5837 * @param matcher The matcher of interest.
5838 * @ingroup Toolbox
5839 **/
5840 ORTHANC_PLUGIN_INLINE void OrthancPluginFreeFindMatcher(
5841 OrthancPluginContext* context,
5842 OrthancPluginFindMatcher* matcher)
5843 {
5844 _OrthancPluginFreeFindMatcher params;
5845 params.matcher = matcher;
5846
5847 context->InvokeService(context, _OrthancPluginService_FreeFindMatcher, &params);
5848 }
5849
5850
5851 typedef struct
5852 {
5853 const OrthancPluginFindMatcher* matcher;
5854 const void* dicom;
5855 uint32_t size;
5856 int32_t* isMatch;
5857 } _OrthancPluginFindMatcherIsMatch;
5858
5859 /**
5860 * @brief Test whether a DICOM instance matches a C-Find query.
5861 *
5862 * This function checks whether one DICOM instance matches C-Find
5863 * matcher that was previously allocated using
5864 * OrthancPluginCreateFindMatcher().
5865 *
5866 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5867 * @param matcher The matcher of interest.
5868 * @param dicom The DICOM instance to be matched.
5869 * @param size The size of the DICOM instance.
5870 * @return 1 if the DICOM instance matches the query, 0 otherwise.
5871 * @ingroup Toolbox
5872 **/
5873 ORTHANC_PLUGIN_INLINE int32_t OrthancPluginFindMatcherIsMatch(
5874 OrthancPluginContext* context,
5875 const OrthancPluginFindMatcher* matcher,
5876 const void* dicom,
5877 uint32_t size)
5878 {
5879 int32_t isMatch = 0;
5880
5881 _OrthancPluginFindMatcherIsMatch params;
5882 params.matcher = matcher;
5883 params.dicom = dicom;
5884 params.size = size;
5885 params.isMatch = &isMatch;
5886
5887 if (context->InvokeService(context, _OrthancPluginService_FindMatcherIsMatch, &params) == OrthancPluginErrorCode_Success)
5888 {
5889 return isMatch;
5890 }
5891 else
5892 {
5893 /* Error: Assume non-match */
5894 return 0;
5895 }
5896 }
5897
5898
5899 typedef struct
5900 {
5901 OrthancPluginIncomingHttpRequestFilter2 callback;
5902 } _OrthancPluginIncomingHttpRequestFilter2;
5903
5904 /**
5905 * @brief Register a callback to filter incoming HTTP requests.
5906 *
5907 * This function registers a custom callback to filter incoming HTTP/REST
5908 * requests received by the HTTP server of Orthanc.
5909 *
5910 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5911 * @param callback The callback.
5912 * @return 0 if success, other value if error.
5913 * @ingroup Callbacks
5914 **/
5915 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginRegisterIncomingHttpRequestFilter2(
5916 OrthancPluginContext* context,
5917 OrthancPluginIncomingHttpRequestFilter2 callback)
5918 {
5919 _OrthancPluginIncomingHttpRequestFilter2 params;
5920 params.callback = callback;
5921
5922 return context->InvokeService(context, _OrthancPluginService_RegisterIncomingHttpRequestFilter2, &params);
5923 }
5924
5925
5926
5927 typedef struct
5928 {
5929 OrthancPluginPeers** peers;
5930 } _OrthancPluginGetPeers;
5931
5932 /**
5933 * @brief Return the list of available Orthanc peers.
5934 *
5935 * This function returns the parameters of the Orthanc peers that are known to
5936 * the Orthanc server hosting the plugin.
5937 *
5938 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5939 * @return NULL if error, or a newly allocated opaque data structure containing the peers.
5940 * This structure must be freed with OrthancPluginFreePeers().
5941 * @ingroup Toolbox
5942 **/
5943 ORTHANC_PLUGIN_INLINE OrthancPluginPeers* OrthancPluginGetPeers(
5944 OrthancPluginContext* context)
5945 {
5946 OrthancPluginPeers* peers = NULL;
5947
5948 _OrthancPluginGetPeers params;
5949 memset(&params, 0, sizeof(params));
5950 params.peers = &peers;
5951
5952 if (context->InvokeService(context, _OrthancPluginService_GetPeers, &params) != OrthancPluginErrorCode_Success)
5953 {
5954 return NULL;
5955 }
5956 else
5957 {
5958 return peers;
5959 }
5960 }
5961
5962
5963 typedef struct
5964 {
5965 OrthancPluginPeers* peers;
5966 } _OrthancPluginFreePeers;
5967
5968 /**
5969 * @brief Free the list of available Orthanc peers.
5970 *
5971 * This function frees the data structure returned by OrthancPluginGetPeers().
5972 *
5973 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
5974 * @param peers The data structure describing the Orthanc peers.
5975 * @ingroup Toolbox
5976 **/
5977 ORTHANC_PLUGIN_INLINE void OrthancPluginFreePeers(
5978 OrthancPluginContext* context,
5979 OrthancPluginPeers* peers)
5980 {
5981 _OrthancPluginFreePeers params;
5982 params.peers = peers;
5983
5984 context->InvokeService(context, _OrthancPluginService_FreePeers, &params);
5985 }
5986
5987
5988 typedef struct
5989 {
5990 uint32_t* target;
5991 const OrthancPluginPeers* peers;
5992 } _OrthancPluginGetPeersCount;
5993
5994 /**
5995 * @brief Get the number of Orthanc peers.
5996 *
5997 * This function returns the number of Orthanc peers.
5998 *
5999 * This function is thread-safe: Several threads sharing the same
6000 * OrthancPluginPeers object can simultaneously call this function.
6001 *
6002 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
6003 * @param peers The data structure describing the Orthanc peers.
6004 * @result The number of peers.
6005 * @ingroup Toolbox
6006 **/
6007 ORTHANC_PLUGIN_INLINE uint32_t OrthancPluginGetPeersCount(
6008 OrthancPluginContext* context,
6009 const OrthancPluginPeers* peers)
6010 {
6011 uint32_t target = 0;
6012
6013 _OrthancPluginGetPeersCount params;
6014 memset(&params, 0, sizeof(params));
6015 params.target = &target;
6016 params.peers = peers;
6017
6018 if (context->InvokeService(context, _OrthancPluginService_GetPeersCount, &params) != OrthancPluginErrorCode_Success)
6019 {
6020 /* Error */
6021 return 0;
6022 }
6023 else
6024 {
6025 return target;
6026 }
6027 }
6028
6029
6030 typedef struct
6031 {
6032 const char** target;
6033 const OrthancPluginPeers* peers;
6034 uint32_t peerIndex;
6035 const char* userProperty;
6036 } _OrthancPluginGetPeerProperty;
6037
6038 /**
6039 * @brief Get the symbolic name of an Orthanc peer.
6040 *
6041 * This function returns the symbolic name of the Orthanc peer,
6042 * which corresponds to the key of the "OrthancPeers" configuration
6043 * option of Orthanc.
6044 *
6045 * This function is thread-safe: Several threads sharing the same
6046 * OrthancPluginPeers object can simultaneously call this function.
6047 *
6048 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
6049 * @param peers The data structure describing the Orthanc peers.
6050 * @param peerIndex The index of the peer of interest.
6051 * This value must be lower than OrthancPluginGetPeersCount().
6052 * @result The symbolic name, or NULL in the case of an error.
6053 * @ingroup Toolbox
6054 **/
6055 ORTHANC_PLUGIN_INLINE const char* OrthancPluginGetPeerName(
6056 OrthancPluginContext* context,
6057 const OrthancPluginPeers* peers,
6058 uint32_t peerIndex)
6059 {
6060 const char* target = NULL;
6061
6062 _OrthancPluginGetPeerProperty params;
6063 memset(&params, 0, sizeof(params));
6064 params.target = &target;
6065 params.peers = peers;
6066 params.peerIndex = peerIndex;
6067 params.userProperty = NULL;
6068
6069 if (context->InvokeService(context, _OrthancPluginService_GetPeerName, &params) != OrthancPluginErrorCode_Success)
6070 {
6071 /* Error */
6072 return NULL;
6073 }
6074 else
6075 {
6076 return target;
6077 }
6078 }
6079
6080
6081 /**
6082 * @brief Get the base URL of an Orthanc peer.
6083 *
6084 * This function returns the base URL to the REST API of some Orthanc peer.
6085 *
6086 * This function is thread-safe: Several threads sharing the same
6087 * OrthancPluginPeers object can simultaneously call this function.
6088 *
6089 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
6090 * @param peers The data structure describing the Orthanc peers.
6091 * @param peerIndex The index of the peer of interest.
6092 * This value must be lower than OrthancPluginGetPeersCount().
6093 * @result The URL, or NULL in the case of an error.
6094 * @ingroup Toolbox
6095 **/
6096 ORTHANC_PLUGIN_INLINE const char* OrthancPluginGetPeerUrl(
6097 OrthancPluginContext* context,
6098 const OrthancPluginPeers* peers,
6099 uint32_t peerIndex)
6100 {
6101 const char* target = NULL;
6102
6103 _OrthancPluginGetPeerProperty params;
6104 memset(&params, 0, sizeof(params));
6105 params.target = &target;
6106 params.peers = peers;
6107 params.peerIndex = peerIndex;
6108 params.userProperty = NULL;
6109
6110 if (context->InvokeService(context, _OrthancPluginService_GetPeerUrl, &params) != OrthancPluginErrorCode_Success)
6111 {
6112 /* Error */
6113 return NULL;
6114 }
6115 else
6116 {
6117 return target;
6118 }
6119 }
6120
6121
6122
6123 /**
6124 * @brief Get some user-defined property of an Orthanc peer.
6125 *
6126 * This function returns some user-defined property of some Orthanc
6127 * peer. An user-defined property is a property that is associated
6128 * with the peer in the Orthanc configuration file, but that is not
6129 * recognized by the Orthanc core.
6130 *
6131 * This function is thread-safe: Several threads sharing the same
6132 * OrthancPluginPeers object can simultaneously call this function.
6133 *
6134 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
6135 * @param peers The data structure describing the Orthanc peers.
6136 * @param peerIndex The index of the peer of interest.
6137 * This value must be lower than OrthancPluginGetPeersCount().
6138 * @param userProperty The user property of interest.
6139 * @result The value of the user property, or NULL if it is not defined.
6140 * @ingroup Toolbox
6141 **/
6142 ORTHANC_PLUGIN_INLINE const char* OrthancPluginGetPeerUserProperty(
6143 OrthancPluginContext* context,
6144 const OrthancPluginPeers* peers,
6145 uint32_t peerIndex,
6146 const char* userProperty)
6147 {
6148 const char* target = NULL;
6149
6150 _OrthancPluginGetPeerProperty params;
6151 memset(&params, 0, sizeof(params));
6152 params.target = &target;
6153 params.peers = peers;
6154 params.peerIndex = peerIndex;
6155 params.userProperty = userProperty;
6156
6157 if (context->InvokeService(context, _OrthancPluginService_GetPeerUserProperty, &params) != OrthancPluginErrorCode_Success)
6158 {
6159 /* No such user property */
6160 return NULL;
6161 }
6162 else
6163 {
6164 return target;
6165 }
6166 }
6167
6168
6169
6170 typedef struct
6171 {
6172 OrthancPluginMemoryBuffer* answerBody;
6173 OrthancPluginMemoryBuffer* answerHeaders;
6174 uint16_t* httpStatus;
6175 const OrthancPluginPeers* peers;
6176 uint32_t peerIndex;
6177 OrthancPluginHttpMethod method;
6178 const char* uri;
6179 uint32_t additionalHeadersCount;
6180 const char* const* additionalHeadersKeys;
6181 const char* const* additionalHeadersValues;
6182 const char* body;
6183 uint32_t bodySize;
6184 uint32_t timeout;
6185 } _OrthancPluginCallPeerApi;
6186
6187 /**
6188 * @brief Call the REST API of an Orthanc peer.
6189 *
6190 * Make a REST call to the given URI in the REST API of a remote
6191 * Orthanc peer. The result to the query is stored into a newly
6192 * allocated memory buffer. The HTTP request will be done according
6193 * to the "OrthancPeers" configuration option of Orthanc.
6194 *
6195 * This function is thread-safe: Several threads sharing the same
6196 * OrthancPluginPeers object can simultaneously call this function.
6197 *
6198 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
6199 * @param answerBody The target memory buffer (out argument).
6200 * It must be freed with OrthancPluginFreeMemoryBuffer().
6201 * @param answerHeaders The target memory buffer for the HTTP headers in the answers (out argument).
6202 * The answer headers are formatted as a JSON object (associative array).
6203 * The buffer must be freed with OrthancPluginFreeMemoryBuffer().
6204 * This argument can be set to NULL if the plugin has no interest in the HTTP headers.
6205 * @param httpStatus The HTTP status after the execution of the request (out argument).
6206 * @param peers The data structure describing the Orthanc peers.
6207 * @param peerIndex The index of the peer of interest.
6208 * This value must be lower than OrthancPluginGetPeersCount().
6209 * @param method HTTP method to be used.
6210 * @param uri The URI of interest in the REST API.
6211 * @param additionalHeadersCount The number of HTTP headers to be added to the
6212 * HTTP headers provided in the global configuration of Orthanc.
6213 * @param additionalHeadersKeys Array containing the keys of the HTTP headers (can be <tt>NULL</tt> if no header).
6214 * @param additionalHeadersValues Array containing the values of the HTTP headers (can be <tt>NULL</tt> if no header).
6215 * @param body The HTTP body for a POST or PUT request.
6216 * @param bodySize The size of the body.
6217 * @param timeout Timeout in seconds (0 for default timeout).
6218 * @return 0 if success, or the error code if failure.
6219 * @see OrthancPluginHttpClient()
6220 * @ingroup Toolbox
6221 **/
6222 ORTHANC_PLUGIN_INLINE OrthancPluginErrorCode OrthancPluginCallPeerApi(
6223 OrthancPluginContext* context,
6224 OrthancPluginMemoryBuffer* answerBody,
6225 OrthancPluginMemoryBuffer* answerHeaders,
6226 uint16_t* httpStatus,
6227 const OrthancPluginPeers* peers,
6228 uint32_t peerIndex,
6229 OrthancPluginHttpMethod method,
6230 const char* uri,
6231 uint32_t additionalHeadersCount,
6232 const char* const* additionalHeadersKeys,
6233 const char* const* additionalHeadersValues,
6234 const char* body,
6235 uint32_t bodySize,
6236 uint32_t timeout)
6237 {
6238 _OrthancPluginCallPeerApi params;
6239 memset(&params, 0, sizeof(params));
6240
6241 params.answerBody = answerBody;
6242 params.answerHeaders = answerHeaders;
6243 params.httpStatus = httpStatus;
6244 params.peers = peers;
6245 params.peerIndex = peerIndex;
6246 params.method = method;
6247 params.uri = uri;
6248 params.additionalHeadersCount = additionalHeadersCount;
6249 params.additionalHeadersKeys = additionalHeadersKeys;
6250 params.additionalHeadersValues = additionalHeadersValues;
6251 params.body = body;
6252 params.bodySize = bodySize;
6253 params.timeout = timeout;
6254
6255 return context->InvokeService(context, _OrthancPluginService_CallPeerApi, &params);
6256 }
6257
6258
6259
6260
6261
6262 typedef struct
6263 {
6264 OrthancPluginJob** target;
6265 void *job;
6266 OrthancPluginJobFinalize finalize;
6267 const char *type;
6268 OrthancPluginJobGetProgress getProgress;
6269 OrthancPluginJobGetContent getContent;
6270 OrthancPluginJobGetSerialized getSerialized;
6271 OrthancPluginJobStep step;
6272 OrthancPluginJobStop stop;
6273 OrthancPluginJobReset reset;
6274 } _OrthancPluginCreateJob;
6275
6276 /**
6277 * @brief Create a custom job.
6278 *
6279 * This function creates a custom job to be run by the jobs engine
6280 * of Orthanc.
6281 *
6282 * Orthanc starts one dedicated thread per custom job that is
6283 * running. It is guaranteed that all the callbacks will only be
6284 * called from this single dedicated thread, in mutual exclusion: As
6285 * a consequence, it is *not* mandatory to protect the various
6286 * callbacks by mutexes.
6287 *
6288 * The custom job can nonetheless launch its own processing threads
6289 * on the first call to the "step()" callback, and stop them once
6290 * the "stop()" callback is called.
6291 *
6292 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
6293 * @param job The job to be executed.
6294 * @param finalize The finalization callback.
6295 * @param type The type of the job, provided to the job unserializer.
6296 * See OrthancPluginRegisterJobsUnserializer().
6297 * @param getProgress The progress callback.
6298 * @param getContent The content callback.
6299 * @param getSerialized The serialization callback.
6300 * @param step The callback to execute the individual steps of the job.
6301 * @param stop The callback that is invoked once the job leaves the "running" state.
6302 * @param reset The callback that is invoked if a stopped job is started again.
6303 * @return The newly allocated job. It must be freed with OrthancPluginFreeJob(),
6304 * as long as it is not submitted with OrthancPluginSubmitJob().
6305 * @ingroup Toolbox
6306 **/
6307 ORTHANC_PLUGIN_INLINE OrthancPluginJob *OrthancPluginCreateJob(
6308 OrthancPluginContext *context,
6309 void *job,
6310 OrthancPluginJobFinalize finalize,
6311 const char *type,
6312 OrthancPluginJobGetProgress getProgress,
6313 OrthancPluginJobGetContent getContent,
6314 OrthancPluginJobGetSerialized getSerialized,
6315 OrthancPluginJobStep step,
6316 OrthancPluginJobStop stop,
6317 OrthancPluginJobReset reset)
6318 {
6319 OrthancPluginJob* target = NULL;
6320
6321 _OrthancPluginCreateJob params;
6322 memset(&params, 0, sizeof(params));
6323
6324 params.target = &target;
6325 params.job = job;
6326 params.finalize = finalize;
6327 params.type = type;
6328 params.getProgress = getProgress;
6329 params.getContent = getContent;
6330 params.getSerialized = getSerialized;
6331 params.step = step;
6332 params.stop = stop;
6333 params.reset = reset;
6334
6335 if (context->InvokeService(context, _OrthancPluginService_CreateJob, &params) != OrthancPluginErrorCode_Success ||
6336 target == NULL)
6337 {
6338 /* Error */
6339 return NULL;
6340 }
6341 else
6342 {
6343 return target;
6344 }
6345 }
6346
6347
6348 typedef struct
6349 {
6350 OrthancPluginJob* job;
6351 } _OrthancPluginFreeJob;
6352
6353 /**
6354 * @brief Free a custom job.
6355 *
6356 * This function frees an image that was created with OrthancPluginCreateJob().
6357 *
6358 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
6359 * @param job The job.
6360 * @ingroup Toolbox
6361 **/
6362 ORTHANC_PLUGIN_INLINE void OrthancPluginFreeJob(
6363 OrthancPluginContext* context,
6364 OrthancPluginJob* job)
6365 {
6366 _OrthancPluginFreeJob params;
6367 params.job = job;
6368
6369 context->InvokeService(context, _OrthancPluginService_FreeJob, &params);
6370 }
6371
6372
6373
6374 typedef struct
6375 {
6376 char** resultId;
6377 OrthancPluginJob *job;
6378 int priority;
6379 } _OrthancPluginSubmitJob;
6380
6381 /**
6382 * @brief Submit a new job to the jobs engine of Orthanc.
6383 *
6384 * This function adds the given job to the pending jobs of
6385 * Orthanc. Orthanc will take take of freeing it by invoking the
6386 * finalization callback provided to OrthancPluginCreateJob().
6387 *
6388 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
6389 * @param job The job, as received by OrthancPluginCreateJob().
6390 * @param priority The priority of the job.
6391 * @return ID of the newly-submitted job. This string must be freed by OrthancPluginFreeString().
6392 * @ingroup Toolbox
6393 **/
6394 ORTHANC_PLUGIN_INLINE char *OrthancPluginSubmitJob(
6395 OrthancPluginContext *context,
6396 OrthancPluginJob *job,
6397 int priority)
6398 {
6399 char* resultId = NULL;
6400
6401 _OrthancPluginSubmitJob params;
6402 memset(&params, 0, sizeof(params));
6403
6404 params.resultId = &resultId;
6405 params.job = job;
6406 params.priority = priority;
6407
6408 if (context->InvokeService(context, _OrthancPluginService_SubmitJob, &params) != OrthancPluginErrorCode_Success ||
6409 resultId == NULL)
6410 {
6411 /* Error */
6412 return NULL;
6413 }
6414 else
6415 {
6416 return resultId;
6417 }
6418 }
6419
6420
6421
6422 typedef struct
6423 {
6424 OrthancPluginJobsUnserializer unserializer;
6425 } _OrthancPluginJobsUnserializer;
6426
6427 /**
6428 * @brief Register an unserializer for custom jobs.
6429 *
6430 * This function registers an unserializer that decodes custom jobs
6431 * from a JSON string. This callback is invoked when the jobs engine
6432 * of Orthanc is started (on Orthanc initialization), for each job
6433 * that is stored in the Orthanc database.
6434 *
6435 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
6436 * @param unserializer The job unserializer.
6437 * @ingroup Callbacks
6438 **/
6439 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterJobsUnserializer(
6440 OrthancPluginContext* context,
6441 OrthancPluginJobsUnserializer unserializer)
6442 {
6443 _OrthancPluginJobsUnserializer params;
6444 params.unserializer = unserializer;
6445
6446 context->InvokeService(context, _OrthancPluginService_RegisterJobsUnserializer, &params);
6447 }
6448
6449
6450
6451 typedef struct
6452 {
6453 OrthancPluginRestOutput* output;
6454 const char* details;
6455 uint8_t log;
6456 } _OrthancPluginSetHttpErrorDetails;
6457
6458 /**
6459 * @brief Provide a detailed description for an HTTP error.
6460 *
6461 * This function sets the detailed description associated with an
6462 * HTTP error. This description will be displayed in the "Details"
6463 * field of the JSON body of the HTTP answer. It is only taken into
6464 * consideration if the REST callback returns an error code that is
6465 * different from "OrthancPluginErrorCode_Success", and if the
6466 * "HttpDescribeErrors" configuration option of Orthanc is set to
6467 * "true".
6468 *
6469 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
6470 * @param output The HTTP connection to the client application.
6471 * @param details The details of the error message.
6472 * @param log Whether to also write the detailed error to the Orthanc logs.
6473 * @ingroup REST
6474 **/
6475 ORTHANC_PLUGIN_INLINE void OrthancPluginSetHttpErrorDetails(
6476 OrthancPluginContext* context,
6477 OrthancPluginRestOutput* output,
6478 const char* details,
6479 uint8_t log)
6480 {
6481 _OrthancPluginSetHttpErrorDetails params;
6482 params.output = output;
6483 params.details = details;
6484 params.log = log;
6485 context->InvokeService(context, _OrthancPluginService_SetHttpErrorDetails, &params);
6486 }
6487
6488
6489
6490 typedef struct
6491 {
6492 const char** result;
6493 const char* argument;
6494 } _OrthancPluginRetrieveStaticString;
6495
6496 /**
6497 * @brief Detect the MIME type of a file.
6498 *
6499 * This function returns the MIME type of a file by inspecting its extension.
6500 *
6501 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize().
6502 * @param path Path to the file.
6503 * @return The MIME type. This is a statically-allocated
6504 * string, do not free it.
6505 * @ingroup Toolbox
6506 **/
6507 ORTHANC_PLUGIN_INLINE const char* OrthancPluginAutodetectMimeType(
6508 OrthancPluginContext* context,
6509 const char* path)
6510 {
6511 const char* result = NULL;
6512
6513 _OrthancPluginRetrieveStaticString params;
6514 params.result = &result;
6515 params.argument = path;
6516
6517 if (context->InvokeService(context, _OrthancPluginService_AutodetectMimeType, &params) != OrthancPluginErrorCode_Success)
6518 {
6519 /* Error */
6520 return NULL;
6521 }
6522 else
6523 {
6524 return result;
6525 }
6526 }
6527
6528
6529 #ifdef __cplusplus
6530 }
6531 #endif
6532
6533
6534 /** @} */
6535