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