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