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