Mercurial > hg > orthanc
comparison Plugins/OrthancCPlugin/OrthancCPlugin.h @ 907:9b8298234254 plugins
documentation
author | Sebastien Jodogne <s.jodogne@gmail.com> |
---|---|
date | Thu, 19 Jun 2014 14:28:43 +0200 |
parents | cbc0ea03dffe |
children | e078ea944089 |
comparison
equal
deleted
inserted
replaced
906:cbc0ea03dffe | 907:9b8298234254 |
---|---|
1 /** | 1 /** |
2 * \mainpage | 2 * \mainpage |
3 * | 3 * |
4 * This SDK allows external developers to create plugins that can be | 4 * This C/C++ SDK allows external developers to create plugins that |
5 * loaded into Orthanc to extend its functionality. Each Orthanc | 5 * can be loaded into Orthanc to extend its functionality. Each |
6 * plugin must expose 4 public functions with the following | 6 * Orthanc plugin must expose 4 public functions with the following |
7 * signatures: | 7 * signatures: |
8 * | 8 * |
9 * - <tt>int32_t OrthancPluginInitialize(const OrthancPluginContext*)</tt>: | 9 * -# <tt>int32_t OrthancPluginInitialize(const OrthancPluginContext* context)</tt>: |
10 * This function is invoked by Orthanc | 10 * This function is invoked by Orthanc when it loads the plugin on startup. |
11 * - <tt>void OrthancPluginFinalize()</tt> | 11 * The plugin must store the context pointer so that it can use the plugin |
12 * - <tt>const char* OrthancPluginGetName()</tt> | 12 * services of Orthanc. It must also register all its callbacks using |
13 * - <tt>const char* OrthancPluginGetVersion()</tt> | 13 * ::OrthancPluginRegisterRestCallback(). |
14 * -# <tt>void OrthancPluginFinalize()</tt>: | |
15 * This function is invoked by Orthanc during its shutdown. The plugin | |
16 * must free all its memory. | |
17 * -# <tt>const char* OrthancPluginGetName()</tt>: | |
18 * The plugin must return a short string to identify itself. | |
19 * -# <tt>const char* OrthancPluginGetVersion()</tt> | |
20 * The plugin must return a string containing its version number. | |
21 * | |
22 * The name and the version of a plugin is only used to prevent it | |
23 * from being loaded twice. | |
24 * | |
25 * | |
14 **/ | 26 **/ |
15 | 27 |
16 | 28 |
17 | 29 |
18 /** | 30 /** |
104 #endif | 116 #endif |
105 | 117 |
106 | 118 |
107 | 119 |
108 /******************************************************************** | 120 /******************************************************************** |
109 ** Inclusion of standard libaries. | 121 ** Inclusion of standard libraries. |
110 ********************************************************************/ | 122 ********************************************************************/ |
111 | 123 |
112 #ifdef _MSC_VER | 124 #ifdef _MSC_VER |
113 #include "../../Resources/VisualStudio/stdint.h" | 125 #include "../../Resources/VisualStudio/stdint.h" |
114 #else | 126 #else |
128 #ifdef __cplusplus | 140 #ifdef __cplusplus |
129 extern "C" | 141 extern "C" |
130 { | 142 { |
131 #endif | 143 #endif |
132 | 144 |
145 /** | |
146 * The various HTTP methods for a REST call. | |
147 **/ | |
133 typedef enum | 148 typedef enum |
134 { | 149 { |
135 OrthancPluginHttpMethod_Get = 1, | 150 OrthancPluginHttpMethod_Get = 1, /*!< GET request */ |
136 OrthancPluginHttpMethod_Post = 2, | 151 OrthancPluginHttpMethod_Post = 2, /*!< POST request */ |
137 OrthancPluginHttpMethod_Put = 3, | 152 OrthancPluginHttpMethod_Put = 3, /*!< PUT request */ |
138 OrthancPluginHttpMethod_Delete = 4 | 153 OrthancPluginHttpMethod_Delete = 4 /*!< DELETE request */ |
139 } OrthancPluginHttpMethod; | 154 } OrthancPluginHttpMethod; |
140 | 155 |
156 | |
157 /** | |
158 * @brief The parameters of a REST request. | |
159 **/ | |
141 typedef struct | 160 typedef struct |
142 { | 161 { |
143 OrthancPluginHttpMethod method; | 162 /** |
144 | 163 * @brief The HTTP method. |
145 /* Groups of the regular expression */ | 164 **/ |
165 OrthancPluginHttpMethod method; | |
166 | |
167 /** | |
168 * @brief The number of groups of the regular expression. | |
169 **/ | |
170 uint32_t groupsCount; | |
171 | |
172 /** | |
173 * @brief The matched values for the groups of the regular expression. | |
174 **/ | |
146 const char* const* groups; | 175 const char* const* groups; |
147 uint32_t groupsCount; | 176 |
148 | 177 /** |
149 /* For GET requests */ | 178 * @brief For a GET request, the number of GET parameters. |
179 **/ | |
180 uint32_t getCount; | |
181 | |
182 /** | |
183 * @brief For a GET request, the keys of the GET parameters. | |
184 **/ | |
150 const char* const* getKeys; | 185 const char* const* getKeys; |
186 | |
187 /** | |
188 * @brief For a GET request, the values of the GET parameters. | |
189 **/ | |
151 const char* const* getValues; | 190 const char* const* getValues; |
152 uint32_t getCount; | 191 |
153 | 192 /** |
154 /* For POST and PUT requests */ | 193 * @brief For a PUT or POST request, the content of the body. |
194 **/ | |
155 const char* body; | 195 const char* body; |
196 | |
197 /** | |
198 * @brief For a PUT or POST request, the number of bytes of the body. | |
199 **/ | |
156 uint32_t bodySize; | 200 uint32_t bodySize; |
157 } OrthancPluginHttpRequest; | 201 } OrthancPluginHttpRequest; |
158 | 202 |
159 typedef enum | 203 typedef enum |
160 { | 204 { |
161 /* Generic services */ | 205 /* Generic services */ |
162 OrthancPluginService_LogInfo = 1, | 206 _OrthancPluginService_LogInfo = 1, |
163 OrthancPluginService_LogWarning = 2, | 207 _OrthancPluginService_LogWarning = 2, |
164 OrthancPluginService_LogError = 3, | 208 _OrthancPluginService_LogError = 3, |
165 | 209 |
166 /* Registration of callbacks */ | 210 /* Registration of callbacks */ |
167 OrthancPluginService_RegisterRestCallback = 1000, | 211 _OrthancPluginService_RegisterRestCallback = 1000, |
168 | 212 |
169 /* Sending answers to REST calls */ | 213 /* Sending answers to REST calls */ |
170 OrthancPluginService_AnswerBuffer = 2000, | 214 _OrthancPluginService_AnswerBuffer = 2000, |
171 OrthancPluginService_CompressAndAnswerPngImage = 2001, | 215 _OrthancPluginService_CompressAndAnswerPngImage = 2001, |
172 | 216 |
173 /* Access to the Orthanc database */ | 217 /* Access to the Orthanc database */ |
174 OrthancPluginService_GetDicomForInstance = 3000 | 218 _OrthancPluginService_GetDicomForInstance = 3000 |
175 } OrthancPluginService; | 219 } _OrthancPluginService; |
176 | 220 |
177 | 221 |
178 | 222 |
179 /** | 223 /** |
180 * The memory layout of the pixels of an image. | 224 * The memory layout of the pixels of an image. |
221 **/ | 265 **/ |
222 OrthancPluginPixelFormat_RGBA32 = 5 | 266 OrthancPluginPixelFormat_RGBA32 = 5 |
223 } OrthancPluginPixelFormat; | 267 } OrthancPluginPixelFormat; |
224 | 268 |
225 | 269 |
270 /** | |
271 * @brief A memory buffer allocated by the core system of Orthanc. | |
272 * | |
273 * A memory buffer allocated by the core system of Orthanc. When the | |
274 * content of the buffer is not useful anymore, it must be free by a | |
275 * call to ::OrthancPluginFreeMemoryBuffer(). | |
276 **/ | |
226 typedef struct | 277 typedef struct |
227 { | 278 { |
279 /** | |
280 * @brief The content of the buffer. | |
281 **/ | |
228 void* data; | 282 void* data; |
283 | |
284 /** | |
285 * @brief The number of bytes in the buffer. | |
286 **/ | |
229 uint32_t size; | 287 uint32_t size; |
230 } OrthancPluginMemoryBuffer; | 288 } OrthancPluginMemoryBuffer; |
231 | 289 |
232 | 290 |
233 | 291 |
234 | 292 |
293 /** | |
294 * @brief Opaque structure that represents the HTTP connection to the client application. | |
295 **/ | |
235 typedef struct _OrthancPluginRestOutput_t OrthancPluginRestOutput; | 296 typedef struct _OrthancPluginRestOutput_t OrthancPluginRestOutput; |
236 | 297 |
298 | |
299 /** | |
300 * @brief Signature of a function that answers to a REST request. | |
301 **/ | |
237 typedef int32_t (*OrthancPluginRestCallback) ( | 302 typedef int32_t (*OrthancPluginRestCallback) ( |
238 OrthancPluginRestOutput* output, | 303 OrthancPluginRestOutput* output, |
239 const char* url, | 304 const char* url, |
240 const OrthancPluginHttpRequest* request); | 305 const OrthancPluginHttpRequest* request); |
241 | 306 |
307 | |
308 /** | |
309 * @brief Opaque structure that contains information about the Orthanc core. | |
310 **/ | |
242 typedef struct _OrthancPluginContext_t | 311 typedef struct _OrthancPluginContext_t |
243 { | 312 { |
244 void* pluginsManager; | 313 void* pluginsManager; |
245 const char* orthancVersion; | 314 const char* orthancVersion; |
246 void (*Free) (void* buffer); | 315 void (*Free) (void* buffer); |
247 int32_t (*InvokeService) (struct _OrthancPluginContext_t* context, | 316 int32_t (*InvokeService) (struct _OrthancPluginContext_t* context, |
248 OrthancPluginService service, | 317 _OrthancPluginService service, |
249 const void* params); | 318 const void* params); |
250 } OrthancPluginContext; | 319 } OrthancPluginContext; |
251 | 320 |
252 | 321 |
322 | |
323 /** | |
324 * @brief Free a string. | |
325 * | |
326 * Free a string that was allocated by the core system of Orthanc. | |
327 * | |
328 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). | |
329 * @param str The string to be freed. | |
330 **/ | |
253 ORTHANC_PLUGIN_INLINE void OrthancPluginFreeString( | 331 ORTHANC_PLUGIN_INLINE void OrthancPluginFreeString( |
254 OrthancPluginContext* context, | 332 OrthancPluginContext* context, |
255 char* str) | 333 char* str) |
256 { | 334 { |
257 context->Free(str); | 335 context->Free(str); |
258 } | 336 } |
259 | 337 |
260 | 338 |
339 /** | |
340 * @brief Free a memory buffer. | |
341 * | |
342 * Free a memory buffer that was allocated by the core system of Orthanc. | |
343 * | |
344 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). | |
345 * @param buffer The memory buffer to release. | |
346 **/ | |
261 ORTHANC_PLUGIN_INLINE void OrthancPluginFreeMemoryBuffer( | 347 ORTHANC_PLUGIN_INLINE void OrthancPluginFreeMemoryBuffer( |
262 OrthancPluginContext* context, | 348 OrthancPluginContext* context, |
263 OrthancPluginMemoryBuffer* buffer) | 349 OrthancPluginMemoryBuffer* buffer) |
264 { | 350 { |
265 context->Free(buffer->data); | 351 context->Free(buffer->data); |
266 } | 352 } |
267 | 353 |
268 | 354 |
355 /** | |
356 * @brief Log an error. | |
357 * | |
358 * Log an error message using the Orthanc logging system. | |
359 * | |
360 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). | |
361 * @param message The message to be logged. | |
362 **/ | |
269 ORTHANC_PLUGIN_INLINE void OrthancPluginLogError( | 363 ORTHANC_PLUGIN_INLINE void OrthancPluginLogError( |
270 OrthancPluginContext* context, | 364 OrthancPluginContext* context, |
271 const char* str) | 365 const char* message) |
272 { | 366 { |
273 context->InvokeService(context, OrthancPluginService_LogError, str); | 367 context->InvokeService(context, _OrthancPluginService_LogError, message); |
274 } | 368 } |
275 | 369 |
276 | 370 |
371 /** | |
372 * @brief Log a warning. | |
373 * | |
374 * Log a warning message using the Orthanc logging system. | |
375 * | |
376 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). | |
377 * @param message The message to be logged. | |
378 **/ | |
277 ORTHANC_PLUGIN_INLINE void OrthancPluginLogWarning( | 379 ORTHANC_PLUGIN_INLINE void OrthancPluginLogWarning( |
278 OrthancPluginContext* context, | 380 OrthancPluginContext* context, |
279 const char* str) | 381 const char* message) |
280 { | 382 { |
281 context->InvokeService(context, OrthancPluginService_LogWarning, str); | 383 context->InvokeService(context, _OrthancPluginService_LogWarning, message); |
282 } | 384 } |
283 | 385 |
284 | 386 |
387 /** | |
388 * @brief Log an information. | |
389 * | |
390 * Log an information message using the Orthanc logging system. | |
391 * | |
392 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). | |
393 * @param message The message to be logged. | |
394 **/ | |
285 ORTHANC_PLUGIN_INLINE void OrthancPluginLogInfo( | 395 ORTHANC_PLUGIN_INLINE void OrthancPluginLogInfo( |
286 OrthancPluginContext* context, | 396 OrthancPluginContext* context, |
287 const char* str) | 397 const char* message) |
288 { | 398 { |
289 context->InvokeService(context, OrthancPluginService_LogInfo, str); | 399 context->InvokeService(context, _OrthancPluginService_LogInfo, message); |
290 } | 400 } |
291 | 401 |
292 | 402 |
293 typedef struct | 403 typedef struct |
294 { | 404 { |
295 const char* pathRegularExpression; | 405 const char* pathRegularExpression; |
296 OrthancPluginRestCallback callback; | 406 OrthancPluginRestCallback callback; |
297 } _OrthancPluginRestCallback; | 407 } _OrthancPluginRestCallback; |
298 | 408 |
299 | 409 |
410 /** | |
411 * @brief Register a REST callback. | |
412 * | |
413 * This function registers a REST callback against a regular | |
414 * expression for a URI. This function must be called during the | |
415 * initialization of the plugin, i.e. inside the | |
416 * OrthancPluginInitialize() public function. | |
417 * | |
418 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). | |
419 * @param pathRegularExpression Regular expression for the URI. May contain groups. | |
420 * @param callback The callback function to handle the REST call. | |
421 **/ | |
300 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterRestCallback( | 422 ORTHANC_PLUGIN_INLINE void OrthancPluginRegisterRestCallback( |
301 OrthancPluginContext* context, | 423 OrthancPluginContext* context, |
302 const char* pathRegularExpression, | 424 const char* pathRegularExpression, |
303 OrthancPluginRestCallback callback) | 425 OrthancPluginRestCallback callback) |
304 { | 426 { |
305 _OrthancPluginRestCallback params; | 427 _OrthancPluginRestCallback params; |
306 params.pathRegularExpression = pathRegularExpression; | 428 params.pathRegularExpression = pathRegularExpression; |
307 params.callback = callback; | 429 params.callback = callback; |
308 context->InvokeService(context, OrthancPluginService_RegisterRestCallback, ¶ms); | 430 context->InvokeService(context, _OrthancPluginService_RegisterRestCallback, ¶ms); |
309 } | 431 } |
310 | 432 |
311 | 433 |
312 typedef struct | 434 typedef struct |
313 { | 435 { |
315 const char* answer; | 437 const char* answer; |
316 uint32_t answerSize; | 438 uint32_t answerSize; |
317 const char* mimeType; | 439 const char* mimeType; |
318 } _OrthancPluginAnswerBuffer; | 440 } _OrthancPluginAnswerBuffer; |
319 | 441 |
442 | |
443 /** | |
444 * @brief Answer to a REST request. | |
445 * | |
446 * This function answers to a REST request with the content of a memory buffer. | |
447 * | |
448 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). | |
449 * @param output The HTTP connection to the client application. | |
450 * @param answer Pointer to the memory buffer containing the answer. | |
451 * @param answerSize Number of bytes of the answer. | |
452 * @param mimeType The MIME type of the answer. | |
453 **/ | |
320 ORTHANC_PLUGIN_INLINE void OrthancPluginAnswerBuffer( | 454 ORTHANC_PLUGIN_INLINE void OrthancPluginAnswerBuffer( |
321 OrthancPluginContext* context, | 455 OrthancPluginContext* context, |
322 OrthancPluginRestOutput* output, | 456 OrthancPluginRestOutput* output, |
323 const char* answer, | 457 const char* answer, |
324 uint32_t answerSize, | 458 uint32_t answerSize, |
327 _OrthancPluginAnswerBuffer params; | 461 _OrthancPluginAnswerBuffer params; |
328 params.output = output; | 462 params.output = output; |
329 params.answer = answer; | 463 params.answer = answer; |
330 params.answerSize = answerSize; | 464 params.answerSize = answerSize; |
331 params.mimeType = mimeType; | 465 params.mimeType = mimeType; |
332 context->InvokeService(context, OrthancPluginService_AnswerBuffer, ¶ms); | 466 context->InvokeService(context, _OrthancPluginService_AnswerBuffer, ¶ms); |
333 } | 467 } |
334 | 468 |
335 | 469 |
336 typedef struct | 470 typedef struct |
337 { | 471 { |
341 uint32_t height; | 475 uint32_t height; |
342 uint32_t pitch; | 476 uint32_t pitch; |
343 const void* buffer; | 477 const void* buffer; |
344 } _OrthancPluginCompressAndAnswerPngImage; | 478 } _OrthancPluginCompressAndAnswerPngImage; |
345 | 479 |
480 /** | |
481 * @brief Answer to a REST request with a PNG image. | |
482 * | |
483 * This function answers to a REST request with a PNG image. The | |
484 * parameters of this function describe a memory buffer that | |
485 * contains an uncompressed image. The image will be automatically compressed | |
486 * as a PNG image by the core system of Orthanc. | |
487 * | |
488 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). | |
489 * @param output The HTTP connection to the client application. | |
490 * @param format The memory layout of the uncompressed image. | |
491 * @param width The width of the image. | |
492 * @param height The height of the image. | |
493 * @param pitch The pitch of the image (i.e. the number of bytes | |
494 * between 2 successive lines of the image in the memory buffer. | |
495 * @param buffer The memory buffer containing the uncompressed image. | |
496 **/ | |
346 ORTHANC_PLUGIN_INLINE void OrthancPluginCompressAndAnswerPngImage( | 497 ORTHANC_PLUGIN_INLINE void OrthancPluginCompressAndAnswerPngImage( |
347 OrthancPluginContext* context, | 498 OrthancPluginContext* context, |
348 OrthancPluginRestOutput* output, | 499 OrthancPluginRestOutput* output, |
349 OrthancPluginPixelFormat format, | 500 OrthancPluginPixelFormat format, |
350 uint32_t width, | 501 uint32_t width, |
357 params.format = format; | 508 params.format = format; |
358 params.width = width; | 509 params.width = width; |
359 params.height = height; | 510 params.height = height; |
360 params.pitch = pitch; | 511 params.pitch = pitch; |
361 params.buffer = buffer; | 512 params.buffer = buffer; |
362 context->InvokeService(context, OrthancPluginService_CompressAndAnswerPngImage, ¶ms); | 513 context->InvokeService(context, _OrthancPluginService_CompressAndAnswerPngImage, ¶ms); |
363 } | 514 } |
364 | 515 |
365 | 516 |
366 typedef struct | 517 typedef struct |
367 { | 518 { |
368 OrthancPluginMemoryBuffer* target; | 519 OrthancPluginMemoryBuffer* target; |
369 const char* instanceId; | 520 const char* instanceId; |
370 } _OrthancPluginGetDicomForInstance; | 521 } _OrthancPluginGetDicomForInstance; |
371 | 522 |
523 | |
524 /** | |
525 * @brief Retrieve a DICOM instance using its Orthanc identifier. | |
526 * | |
527 * Retrieve a DICOM instance using its Orthanc identifier. The DICOM | |
528 * file is stored into a newly allocated memory buffer. | |
529 * | |
530 * @param context The Orthanc plugin context, as received by OrthancPluginInitialize(). | |
531 * @param target The target memory buffer. | |
532 * @param instanceId The Orthanc identifier of the DICOM instance of interest. | |
533 * @return 0 if success, other value if error. | |
534 **/ | |
372 ORTHANC_PLUGIN_INLINE int OrthancPluginGetDicomForInstance( | 535 ORTHANC_PLUGIN_INLINE int OrthancPluginGetDicomForInstance( |
373 OrthancPluginContext* context, | 536 OrthancPluginContext* context, |
374 OrthancPluginMemoryBuffer* target, | 537 OrthancPluginMemoryBuffer* target, |
375 const char* instanceId) | 538 const char* instanceId) |
376 { | 539 { |
377 _OrthancPluginGetDicomForInstance params; | 540 _OrthancPluginGetDicomForInstance params; |
378 params.target = target; | 541 params.target = target; |
379 params.instanceId = instanceId; | 542 params.instanceId = instanceId; |
380 return context->InvokeService(context, OrthancPluginService_GetDicomForInstance, ¶ms); | 543 return context->InvokeService(context, _OrthancPluginService_GetDicomForInstance, ¶ms); |
381 } | 544 } |
382 | 545 |
383 | 546 |
384 #ifdef __cplusplus | 547 #ifdef __cplusplus |
385 } | 548 } |