![]() |
Orthanc Plugin SDK
1.9.1
Documentation of the plugin interface of Orthanc
|
Functions to register and manage callbacks by the plugins. More...
Classes | |
struct | OrthancPluginHttpRequest |
The parameters of a REST request. More... | |
Typedefs | |
typedef OrthancPluginErrorCode(* | OrthancPluginDecodeImageCallback) (OrthancPluginImage **target, const void *dicom, const uint32_t size, uint32_t frameIndex) |
Signature of a callback function to decode a DICOM instance as an image. | |
typedef void(* | OrthancPluginDicomWebBinaryCallback) (OrthancPluginDicomWebNode *node, OrthancPluginDicomWebSetBinaryNode setter, uint32_t levelDepth, const uint16_t *levelTagGroup, const uint16_t *levelTagElement, const uint32_t *levelIndex, uint16_t tagGroup, uint16_t tagElement, OrthancPluginValueRepresentation vr) |
Callback executed to encode a binary tag in DICOMweb. More... | |
typedef void(* | OrthancPluginDicomWebBinaryCallback2) (OrthancPluginDicomWebNode *node, OrthancPluginDicomWebSetBinaryNode setter, uint32_t levelDepth, const uint16_t *levelTagGroup, const uint16_t *levelTagElement, const uint32_t *levelIndex, uint16_t tagGroup, uint16_t tagElement, OrthancPluginValueRepresentation vr, void *payload) |
Callback executed to encode a binary tag in DICOMweb. More... | |
typedef void(* | OrthancPluginDicomWebSetBinaryNode) (OrthancPluginDicomWebNode *node, OrthancPluginDicomWebBinaryMode mode, const char *bulkDataUri) |
Signature of a function to set the content of a node encoding a binary DICOM tag, into a JSON or XML document generated for DICOMweb. | |
typedef void(* | OrthancPluginFree) (void *buffer) |
Signature of a function to free dynamic memory. | |
typedef OrthancPluginJob *(* | OrthancPluginJobsUnserializer) (const char *jobType, const char *serialized) |
Callback executed to unserialize a custom job. More... | |
typedef OrthancPluginErrorCode(* | OrthancPluginOnChangeCallback) (OrthancPluginChangeType changeType, OrthancPluginResourceType resourceType, const char *resourceId) |
Signature of a callback function that is triggered when a change happens to some DICOM resource. | |
typedef OrthancPluginErrorCode(* | OrthancPluginOnStoredInstanceCallback) (const OrthancPluginDicomInstance *instance, const char *instanceId) |
Signature of a callback function that is triggered when Orthanc stores a new DICOM instance. | |
typedef void(* | OrthancPluginRefreshMetricsCallback) () |
Callback executed to update the metrics of the plugin. More... | |
typedef OrthancPluginErrorCode(* | OrthancPluginRestCallback) (OrthancPluginRestOutput *output, const char *url, const OrthancPluginHttpRequest *request) |
Signature of a callback function that answers to a REST request. | |
typedef OrthancPluginErrorCode(* | OrthancPluginStorageCreate) (const char *uuid, const void *content, int64_t size, OrthancPluginContentType type) |
Callback for writing to the storage area. More... | |
typedef OrthancPluginErrorCode(* | OrthancPluginStorageRead) (void **content, int64_t *size, const char *uuid, OrthancPluginContentType type) |
Callback for reading from the storage area. More... | |
typedef OrthancPluginErrorCode(* | OrthancPluginStorageReadRange) (OrthancPluginMemoryBuffer64 *target, const char *uuid, OrthancPluginContentType type, uint64_t rangeStart) |
Callback for reading a range of a file from the storage area. More... | |
typedef OrthancPluginErrorCode(* | OrthancPluginStorageReadWhole) (OrthancPluginMemoryBuffer64 *target, const char *uuid, OrthancPluginContentType type) |
Callback for reading a whole file from the storage area. More... | |
typedef OrthancPluginErrorCode(* | OrthancPluginStorageRemove) (const char *uuid, OrthancPluginContentType type) |
Callback for removing a file from the storage area. More... | |
typedef OrthancPluginErrorCode(* | OrthancPluginTranscoderCallback) (OrthancPluginMemoryBuffer *transcoded, const void *buffer, uint64_t size, const char *const *allowedSyntaxes, uint32_t countSyntaxes, uint8_t allowNewSopInstanceUid) |
Signature of a callback function to transcode a DICOM instance. More... | |
typedef struct _OrthancPluginDatabaseContext_t OrthancPluginDatabaseContext |
Orthanc - A Lightweight, RESTful DICOM Store Copyright (C) 2012-2016 Sebastien Jodogne, Medical Physics Department, University Hospital of Liege, Belgium Copyright (C) 2017-2021 Osimis S.A., Belgium
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/. Opaque structure that represents the context of a custom database engine.
typedef void(* OrthancPluginDicomWebBinaryCallback) (OrthancPluginDicomWebNode *node, OrthancPluginDicomWebSetBinaryNode setter, uint32_t levelDepth, const uint16_t *levelTagGroup, const uint16_t *levelTagElement, const uint32_t *levelIndex, uint16_t tagGroup, uint16_t tagElement, OrthancPluginValueRepresentation vr) |
Signature of a callback function that is called by Orthanc whenever a DICOM tag that contains a binary value must be written to a JSON or XML node, while a DICOMweb document is being generated. The value representation (VR) of the DICOM tag can be OB, OD, OF, OL, OW, or UN.
node | The node being generated, as provided by Orthanc. |
setter | The setter to be used to encode the content of the node. If the setter is not called, the binary tag is not written to the output document. |
levelDepth | The depth of the node in the DICOM hierarchy of sequences. This parameter gives the number of elements in the "levelTagGroup", "levelTagElement", and "levelIndex" arrays. |
levelTagGroup | The group of the parent DICOM tags in the hierarchy. |
levelTagElement | The element of the parent DICOM tags in the hierarchy. |
levelIndex | The index of the node in the parent sequences of the hierarchy. |
tagGroup | The group of the DICOM tag of interest. |
tagElement | The element of the DICOM tag of interest. |
vr | The value representation of the binary DICOM node. |
typedef void(* OrthancPluginDicomWebBinaryCallback2) (OrthancPluginDicomWebNode *node, OrthancPluginDicomWebSetBinaryNode setter, uint32_t levelDepth, const uint16_t *levelTagGroup, const uint16_t *levelTagElement, const uint32_t *levelIndex, uint16_t tagGroup, uint16_t tagElement, OrthancPluginValueRepresentation vr, void *payload) |
Signature of a callback function that is called by Orthanc whenever a DICOM tag that contains a binary value must be written to a JSON or XML node, while a DICOMweb document is being generated. The value representation (VR) of the DICOM tag can be OB, OD, OF, OL, OW, or UN.
node | The node being generated, as provided by Orthanc. |
setter | The setter to be used to encode the content of the node. If the setter is not called, the binary tag is not written to the output document. |
levelDepth | The depth of the node in the DICOM hierarchy of sequences. This parameter gives the number of elements in the "levelTagGroup", "levelTagElement", and "levelIndex" arrays. |
levelTagGroup | The group of the parent DICOM tags in the hierarchy. |
levelTagElement | The element of the parent DICOM tags in the hierarchy. |
levelIndex | The index of the node in the parent sequences of the hierarchy. |
tagGroup | The group of the DICOM tag of interest. |
tagElement | The element of the DICOM tag of interest. |
vr | The value representation of the binary DICOM node. |
payload | The user payload. |
typedef OrthancPluginJob*(* OrthancPluginJobsUnserializer) (const char *jobType, const char *serialized) |
Signature of a callback function that unserializes a job that was saved in the Orthanc database.
jobType | The type of the job, as provided to OrthancPluginCreateJob(). |
serialized | The serialization of the job, as provided by OrthancPluginJobGetSerialized. |
typedef void(* OrthancPluginRefreshMetricsCallback) () |
Signature of a callback function that is called by Orthanc whenever a monitoring tool (such as Prometheus) asks the current values of the metrics. This callback gives the plugin a chance to update its metrics, by calling OrthancPluginSetMetricsValue(). This is typically useful for metrics that are expensive to acquire.
typedef OrthancPluginErrorCode(* OrthancPluginStorageCreate) (const char *uuid, const void *content, int64_t size, OrthancPluginContentType type) |
Signature of a callback function that is triggered when Orthanc writes a file to the storage area.
uuid | The UUID of the file. |
content | The content of the file. |
size | The size of the file. |
type | The content type corresponding to this file. |
typedef OrthancPluginErrorCode(* OrthancPluginStorageRead) (void **content, int64_t *size, const char *uuid, OrthancPluginContentType type) |
Signature of a callback function that is triggered when Orthanc reads a file from the storage area.
content | The content of the file (output). |
size | The size of the file (output). |
uuid | The UUID of the file of interest. |
type | The content type corresponding to this file. |
typedef OrthancPluginErrorCode(* OrthancPluginStorageReadRange) (OrthancPluginMemoryBuffer64 *target, const char *uuid, OrthancPluginContentType type, uint64_t rangeStart) |
Signature of a callback function that is triggered when Orthanc reads a portion of a file from the storage area. Orthanc indicates the start position and the length of the range.
target | Memory buffer where to store the content of the range. The memory buffer is allocated and freed by Orthanc. The length of the range of interest corresponds to the size of this buffer. |
uuid | The UUID of the file of interest. |
type | The content type corresponding to this file. |
rangeStart | Start position of the requested range in the file. |
typedef OrthancPluginErrorCode(* OrthancPluginStorageReadWhole) (OrthancPluginMemoryBuffer64 *target, const char *uuid, OrthancPluginContentType type) |
Signature of a callback function that is triggered when Orthanc reads a whole file from the storage area.
target | Memory buffer where to store the content of the file. It must be allocated by the plugin using OrthancPluginCreateMemoryBuffer64(). The core of Orthanc will free it. |
uuid | The UUID of the file of interest. |
type | The content type corresponding to this file. |
typedef OrthancPluginErrorCode(* OrthancPluginStorageRemove) (const char *uuid, OrthancPluginContentType type) |
Signature of a callback function that is triggered when Orthanc deletes a file from the storage area.
uuid | The UUID of the file to be removed. |
type | The content type corresponding to this file. |
typedef OrthancPluginErrorCode(* OrthancPluginTranscoderCallback) (OrthancPluginMemoryBuffer *transcoded, const void *buffer, uint64_t size, const char *const *allowedSyntaxes, uint32_t countSyntaxes, uint8_t allowNewSopInstanceUid) |
transcoded | Target memory buffer. It must be allocated by the plugin using OrthancPluginCreateMemoryBuffer(). |
buffer | Memory buffer containing the source DICOM instance. |
size | Size of the source memory buffer. |
allowedSyntaxes | A C array of possible transfer syntaxes UIDs for the result of the transcoding. The plugin must choose by itself the transfer syntax that will be used for the resulting DICOM image. |
countSyntaxes | The number of transfer syntaxes that are contained in the "allowedSyntaxes" array. |
allowNewSopInstanceUid | Whether the transcoding plugin can select a transfer syntax that will change the SOP instance UID (or, in other terms, whether the plugin can transcode using lossy compression). |
The supported types of changes that can be signaled to the change callback.
int OrthancPluginCheckVersion | ( | OrthancPluginContext * | context | ) |
This function checks whether the version of the Orthanc server running this plugin, is above the version of the current Orthanc SDK header. This guarantees that the plugin is compatible with the hosting Orthanc (i.e. it will not call unavailable services). The result of this function should always be checked in the OrthancPluginInitialize() entry point of the plugin.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
int OrthancPluginCheckVersionAdvanced | ( | OrthancPluginContext * | context, |
int | expectedMajor, | ||
int | expectedMinor, | ||
int | expectedRevision | ||
) |
This function checks whether the version of the Orthanc server running this plugin, is above the given version. Contrarily to OrthancPluginCheckVersion(), it is up to the developer of the plugin to make sure that all the Orthanc SDK services called by the plugin are actually implemented in the given version of Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
expectedMajor | Expected major version. |
expectedMinor | Expected minor version. |
expectedRevision | Expected revision. |
uint32_t OrthancPluginGetExpectedDatabaseVersion | ( | OrthancPluginContext * | context | ) |
Retrieve the expected version of the database schema.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
OrthancPluginErrorCode OrthancPluginReconstructMainDicomTags | ( | OrthancPluginContext * | context, |
OrthancPluginStorageArea * | storageArea, | ||
OrthancPluginResourceType | level | ||
) |
This function requests the Orthanc core to reconstruct the main DICOM tags of all the resources of the given type. This function can only be used as a part of the upgrade of a custom database back-end. A database transaction will be automatically setup.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
storageArea | The storage area. |
level | The type of the resources of interest. |
void OrthancPluginRegisterChunkedRestCallback | ( | OrthancPluginContext * | context, |
const char * | pathRegularExpression, | ||
OrthancPluginRestCallback | getHandler, | ||
OrthancPluginServerChunkedRequestReaderFactory | postHandler, | ||
OrthancPluginRestCallback | deleteHandler, | ||
OrthancPluginServerChunkedRequestReaderFactory | putHandler, | ||
OrthancPluginServerChunkedRequestReaderAddChunk | addChunk, | ||
OrthancPluginServerChunkedRequestReaderExecute | execute, | ||
OrthancPluginServerChunkedRequestReaderFinalize | finalize | ||
) |
This function registers a REST callback against a regular expression for a URI. This function must be called during the initialization of the plugin, i.e. inside the OrthancPluginInitialize() public function.
Contrarily to OrthancPluginRegisterRestCallback(), the callbacks will NOT be invoked in mutual exclusion, so it is up to the plugin to implement the required locking mechanisms.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
pathRegularExpression | Regular expression for the URI. May contain groups. |
getHandler | The callback function to handle REST calls using the GET HTTP method. |
postHandler | The callback function to handle REST calls using the GET POST method. |
deleteHandler | The callback function to handle REST calls using the GET DELETE method. |
putHandler | The callback function to handle REST calls using the GET PUT method. |
addChunk | The callback invoked when a new chunk is available for the request body of a POST or PUT call. |
execute | The callback invoked once the entire body of a POST or PUT call is read. |
finalize | The callback invoked to release the resources associated with a POST or PUT call. |
OrthancPluginDatabaseContext* OrthancPluginRegisterDatabaseBackend | ( | OrthancPluginContext * | context, |
const OrthancPluginDatabaseBackend * | backend, | ||
void * | payload | ||
) |
Register a custom database back-end (for legacy plugins).
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
backend | The callbacks of the custom database engine. |
payload | Pointer containing private information for the database engine. |
OrthancPluginDatabaseContext* OrthancPluginRegisterDatabaseBackendV2 | ( | OrthancPluginContext * | context, |
const OrthancPluginDatabaseBackend * | backend, | ||
const OrthancPluginDatabaseExtensions * | extensions, | ||
void * | payload | ||
) |
Register a custom database back-end.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
backend | The callbacks of the custom database engine. |
payload | Pointer containing private information for the database engine. |
extensions | Extensions to the base database SDK that was shipped until Orthanc 0.9.3. |
OrthancPluginErrorCode OrthancPluginRegisterDecodeImageCallback | ( | OrthancPluginContext * | context, |
OrthancPluginDecodeImageCallback | callback | ||
) |
This function registers a custom callback to decode DICOM images, extending the built-in decoder of Orthanc that uses DCMTK. Starting with Orthanc 1.7.0, the exact behavior is affected by the configuration option "BuiltinDecoderTranscoderOrder" of Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
callback | The callback. |
OrthancPluginErrorCode OrthancPluginRegisterIncomingDicomInstanceFilter | ( | OrthancPluginContext * | context, |
OrthancPluginIncomingDicomInstanceFilter | callback | ||
) |
This function registers a custom callback to filter incoming DICOM instances received by Orthanc (either through the REST API or through the DICOM protocol).
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
callback | The callback. |
OrthancPluginErrorCode OrthancPluginRegisterIncomingHttpRequestFilter | ( | OrthancPluginContext * | context, |
OrthancPluginIncomingHttpRequestFilter | callback | ||
) |
This function registers a custom callback to filter incoming HTTP/REST requests received by the HTTP server of Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
callback | The callback. |
OrthancPluginErrorCode OrthancPluginRegisterIncomingHttpRequestFilter2 | ( | OrthancPluginContext * | context, |
OrthancPluginIncomingHttpRequestFilter2 | callback | ||
) |
This function registers a custom callback to filter incoming HTTP/REST requests received by the HTTP server of Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
callback | The callback. |
void OrthancPluginRegisterJobsUnserializer | ( | OrthancPluginContext * | context, |
OrthancPluginJobsUnserializer | unserializer | ||
) |
This function registers an unserializer that decodes custom jobs from a JSON string. This callback is invoked when the jobs engine of Orthanc is started (on Orthanc initialization), for each job that is stored in the Orthanc database.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
unserializer | The job unserializer. |
void OrthancPluginRegisterOnChangeCallback | ( | OrthancPluginContext * | context, |
OrthancPluginOnChangeCallback | callback | ||
) |
This function registers a callback function that is called whenever a change happens to some DICOM resource.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
callback | The callback function. |
void OrthancPluginRegisterOnStoredInstanceCallback | ( | OrthancPluginContext * | context, |
OrthancPluginOnStoredInstanceCallback | callback | ||
) |
This function registers a callback function that is called whenever a new DICOM instance is stored into the Orthanc core.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
callback | The callback function. |
void OrthancPluginRegisterRefreshMetricsCallback | ( | OrthancPluginContext * | context, |
OrthancPluginRefreshMetricsCallback | callback | ||
) |
This function registers a callback to refresh the metrics. The callback must make calls to OrthancPluginSetMetricsValue().
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
callback | The callback function to handle the refresh. |
void OrthancPluginRegisterRestCallback | ( | OrthancPluginContext * | context, |
const char * | pathRegularExpression, | ||
OrthancPluginRestCallback | callback | ||
) |
This function registers a REST callback against a regular expression for a URI. This function must be called during the initialization of the plugin, i.e. inside the OrthancPluginInitialize() public function.
Each REST callback is guaranteed to run in mutual exclusion.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
pathRegularExpression | Regular expression for the URI. May contain groups. |
callback | The callback function to handle the REST call. |
void OrthancPluginRegisterRestCallbackNoLock | ( | OrthancPluginContext * | context, |
const char * | pathRegularExpression, | ||
OrthancPluginRestCallback | callback | ||
) |
This function registers a REST callback against a regular expression for a URI. This function must be called during the initialization of the plugin, i.e. inside the OrthancPluginInitialize() public function.
Contrarily to OrthancPluginRegisterRestCallback(), the callback will NOT be invoked in mutual exclusion. This can be useful for high-performance plugins that must handle concurrent requests (Orthanc uses a pool of threads, one thread being assigned to each incoming HTTP request). Of course, if using this function, it is up to the plugin to implement the required locking mechanisms.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
pathRegularExpression | Regular expression for the URI. May contain groups. |
callback | The callback function to handle the REST call. |
void OrthancPluginRegisterStorageArea | ( | OrthancPluginContext * | context, |
OrthancPluginStorageCreate | create, | ||
OrthancPluginStorageRead | read, | ||
OrthancPluginStorageRemove | remove | ||
) |
This function registers a custom storage area, to replace the built-in way Orthanc stores its files on the filesystem. This function must be called during the initialization of the plugin, i.e. inside the OrthancPluginInitialize() public function.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
create | The callback function to store a file on the custom storage area. |
read | The callback function to read a file from the custom storage area. |
remove | The callback function to remove a file from the custom storage area. |
void OrthancPluginRegisterStorageArea2 | ( | OrthancPluginContext * | context, |
OrthancPluginStorageCreate | create, | ||
OrthancPluginStorageReadWhole | readWhole, | ||
OrthancPluginStorageReadRange | readRange, | ||
OrthancPluginStorageRemove | remove | ||
) |
This function registers a custom storage area, to replace the built-in way Orthanc stores its files on the filesystem. This function must be called during the initialization of the plugin, i.e. inside the OrthancPluginInitialize() public function.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
create | The callback function to store a file on the custom storage area. |
readWhole | The callback function to read a whole file from the custom storage area. |
readRange | The callback function to read some range of a file from the custom storage area. If this feature is not supported by the plugin, this value can be set to NULL. |
remove | The callback function to remove a file from the custom storage area. |
OrthancPluginErrorCode OrthancPluginRegisterTranscoderCallback | ( | OrthancPluginContext * | context, |
OrthancPluginTranscoderCallback | callback | ||
) |
This function registers a custom callback to transcode DICOM images, extending the built-in transcoder of Orthanc that uses DCMTK. The exact behavior is affected by the configuration option "BuiltinDecoderTranscoderOrder" of Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
callback | The callback. |
OrthancPluginErrorCode OrthancPluginStorageAreaCreate | ( | OrthancPluginContext * | context, |
OrthancPluginStorageArea * | storageArea, | ||
const char * | uuid, | ||
const void * | content, | ||
uint64_t | size, | ||
OrthancPluginContentType | type | ||
) |
This function creates a new file inside the storage area that is currently used by Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
storageArea | The storage area. |
uuid | The identifier of the file to be created. |
content | The content to store in the newly created file. |
size | The size of the content. |
type | The type of the file content. |
OrthancPluginErrorCode OrthancPluginStorageAreaRead | ( | OrthancPluginContext * | context, |
OrthancPluginMemoryBuffer * | target, | ||
OrthancPluginStorageArea * | storageArea, | ||
const char * | uuid, | ||
OrthancPluginContentType | type | ||
) |
This function reads the content of a given file from the storage area that is currently used by Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
target | The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer(). |
storageArea | The storage area. |
uuid | The identifier of the file to be read. |
type | The type of the file content. |
OrthancPluginErrorCode OrthancPluginStorageAreaRemove | ( | OrthancPluginContext * | context, |
OrthancPluginStorageArea * | storageArea, | ||
const char * | uuid, | ||
OrthancPluginContentType | type | ||
) |
This function removes a given file from the storage area that is currently used by Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
storageArea | The storage area. |
uuid | The identifier of the file to be removed. |
type | The type of the file content. |