![]() |
Orthanc Plugin SDK
1.5.7
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(* | OrthancPluginRestCallback) (OrthancPluginRestOutput *output, const char *url, const OrthancPluginHttpRequest *request) |
Signature of a callback function that answers to a REST request. | |
typedef OrthancPluginErrorCode(* | OrthancPluginOnStoredInstanceCallback) (OrthancPluginDicomInstance *instance, const char *instanceId) |
Signature of a callback function that is triggered when Orthanc receives a DICOM instance. | |
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(* | 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(* | OrthancPluginFree) (void *buffer) |
Signature of a function to free dynamic memory. | |
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 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(* | OrthancPluginStorageRemove) (const char *uuid, OrthancPluginContentType type) |
Callback for removing a file from the storage area. More... | |
typedef OrthancPluginJob *(* | OrthancPluginJobsUnserializer) (const char *jobType, const char *serialized) |
Callback executed to unserialize a custom job. More... | |
typedef void(* | OrthancPluginRefreshMetricsCallback) () |
Callback executed to update the metrics of the plugin. More... | |
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 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-2019 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.
In addition, as a special exception, the copyright holders of this program give permission to link the code of its release with the OpenSSL project's "OpenSSL" library (or with modified versions of it that use the same license as the "OpenSSL" library), and distribute the linked executables. You must obey the GNU General Public License in all respects for all of the code used other than "OpenSSL". If you modify file(s) with this exception, you may extend this exception to your version of the file(s), but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version. If you delete this exception statement from all source files in the program, then also delete it here.
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 hiearchy. |
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 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(* 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. |
The supported types of changes that can happen to DICOM resources.
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(). |
const char* OrthancPluginGetInstanceData | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance | ||
) |
This function returns a pointer to the content of the given DICOM instance.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
char* OrthancPluginGetInstanceJson | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance | ||
) |
This function returns a pointer to a newly created string containing a JSON file. This JSON file encodes the tag hierarchy of the given DICOM instance.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
const char* OrthancPluginGetInstanceMetadata | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance, | ||
const char * | metadata | ||
) |
This functions returns the value of some metadata that is associated with the DICOM instance of interest. Before calling this function, the existence of the metadata must have been checked with OrthancPluginHasInstanceMetadata().
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
metadata | The metadata of interest. |
OrthancPluginInstanceOrigin OrthancPluginGetInstanceOrigin | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance | ||
) |
This function returns the origin of a DICOM instance that has been received by Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
const char* OrthancPluginGetInstanceRemoteAet | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance | ||
) |
This function returns the Application Entity Title (AET) of the DICOM modality from which a DICOM instance originates.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
char* OrthancPluginGetInstanceSimplifiedJson | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance | ||
) |
This function returns a pointer to a newly created string containing a JSON file. This JSON file encodes the tag hierarchy of the given DICOM instance. In contrast with OrthancPluginGetInstanceJson(), the returned JSON file is in its simplified version.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
int64_t OrthancPluginGetInstanceSize | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance | ||
) |
This function returns the number of bytes of the given DICOM instance.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
int OrthancPluginHasInstanceMetadata | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance, | ||
const char * | metadata | ||
) |
This function checks whether the DICOM instance of interest is associated with some metadata. As of Orthanc 0.8.1, in the callbacks registered by OrthancPluginRegisterOnStoredInstanceCallback(), the only possibly available metadata are "ReceptionDate", "RemoteAET" and "IndexInSeries".
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
metadata | The metadata of interest. |
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 the decoding of DICOM images, replacing the built-in decoder of Orthanc.
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. |
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. |