Orthanc Plugin SDK  1.3.0
Documentation of the plugin interface of Orthanc
Classes | Typedefs | Enumerations | Functions
Callbacks

Functions to register and manage callbacks by the plugins. More...

Classes

struct  OrthancPluginHttpRequest
 The parameters of a REST request. More...
 
class  OrthancPlugins::DatabaseException
 
class  OrthancPlugins::DatabaseBackendOutput
 
class  OrthancPlugins::IDatabaseBackend
 
class  OrthancPlugins::DatabaseBackendAdapter
 Bridge between C and C++ database engines. 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 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...
 

Enumerations

enum  OrthancPluginChangeType {
  OrthancPluginChangeType_CompletedSeries,
  OrthancPluginChangeType_Deleted,
  OrthancPluginChangeType_NewChildInstance,
  OrthancPluginChangeType_NewInstance,
  OrthancPluginChangeType_NewPatient,
  OrthancPluginChangeType_NewSeries,
  OrthancPluginChangeType_NewStudy,
  OrthancPluginChangeType_StablePatient,
  OrthancPluginChangeType_StableSeries,
  OrthancPluginChangeType_StableStudy,
  OrthancPluginChangeType_OrthancStarted,
  OrthancPluginChangeType_OrthancStopped,
  OrthancPluginChangeType_UpdatedAttachment,
  OrthancPluginChangeType_UpdatedMetadata
}
 

Functions

int OrthancPluginCheckVersion (OrthancPluginContext *context)
 Check the compatibility of the plugin wrt. the version of its hosting Orthanc. More...
 
void OrthancPluginRegisterRestCallback (OrthancPluginContext *context, const char *pathRegularExpression, OrthancPluginRestCallback callback)
 Register a REST callback. More...
 
void OrthancPluginRegisterRestCallbackNoLock (OrthancPluginContext *context, const char *pathRegularExpression, OrthancPluginRestCallback callback)
 Register a REST callback, without locking. More...
 
void OrthancPluginRegisterOnStoredInstanceCallback (OrthancPluginContext *context, OrthancPluginOnStoredInstanceCallback callback)
 Register a callback for received instances. More...
 
const char * OrthancPluginGetInstanceRemoteAet (OrthancPluginContext *context, OrthancPluginDicomInstance *instance)
 Get the AET of a DICOM instance. More...
 
int64_t OrthancPluginGetInstanceSize (OrthancPluginContext *context, OrthancPluginDicomInstance *instance)
 Get the size of a DICOM file. More...
 
const char * OrthancPluginGetInstanceData (OrthancPluginContext *context, OrthancPluginDicomInstance *instance)
 Get the data of a DICOM file. More...
 
char * OrthancPluginGetInstanceJson (OrthancPluginContext *context, OrthancPluginDicomInstance *instance)
 Get the DICOM tag hierarchy as a JSON file. More...
 
char * OrthancPluginGetInstanceSimplifiedJson (OrthancPluginContext *context, OrthancPluginDicomInstance *instance)
 Get the DICOM tag hierarchy as a JSON file (with simplification). More...
 
int OrthancPluginHasInstanceMetadata (OrthancPluginContext *context, OrthancPluginDicomInstance *instance, const char *metadata)
 Check whether a DICOM instance is associated with some metadata. More...
 
const char * OrthancPluginGetInstanceMetadata (OrthancPluginContext *context, OrthancPluginDicomInstance *instance, const char *metadata)
 Get the value of some metadata associated with a given DICOM instance. More...
 
void OrthancPluginRegisterStorageArea (OrthancPluginContext *context, OrthancPluginStorageCreate create, OrthancPluginStorageRead read, OrthancPluginStorageRemove remove)
 Register a custom storage area. More...
 
void OrthancPluginRegisterOnChangeCallback (OrthancPluginContext *context, OrthancPluginOnChangeCallback callback)
 Register a callback to monitor changes. More...
 
uint32_t OrthancPluginGetExpectedDatabaseVersion (OrthancPluginContext *context)
 Get the expected version of the database schema. More...
 
OrthancPluginErrorCode OrthancPluginStorageAreaCreate (OrthancPluginContext *context, OrthancPluginStorageArea *storageArea, const char *uuid, const void *content, uint64_t size, OrthancPluginContentType type)
 Create a file inside the storage area. More...
 
OrthancPluginErrorCode OrthancPluginStorageAreaRead (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, OrthancPluginStorageArea *storageArea, const char *uuid, OrthancPluginContentType type)
 Read a file from the storage area. More...
 
OrthancPluginErrorCode OrthancPluginStorageAreaRemove (OrthancPluginContext *context, OrthancPluginStorageArea *storageArea, const char *uuid, OrthancPluginContentType type)
 Remove a file from the storage area. More...
 
OrthancPluginErrorCode OrthancPluginReconstructMainDicomTags (OrthancPluginContext *context, OrthancPluginStorageArea *storageArea, OrthancPluginResourceType level)
 Reconstruct the main DICOM tags. More...
 
OrthancPluginInstanceOrigin OrthancPluginGetInstanceOrigin (OrthancPluginContext *context, OrthancPluginDicomInstance *instance)
 Get the origin of a DICOM file. More...
 
OrthancPluginErrorCode OrthancPluginRegisterDecodeImageCallback (OrthancPluginContext *context, OrthancPluginDecodeImageCallback callback)
 Register a callback to handle the decoding of DICOM images. More...
 
OrthancPluginErrorCode OrthancPluginRegisterIncomingHttpRequestFilter (OrthancPluginContext *context, OrthancPluginIncomingHttpRequestFilter callback)
 Register a callback to filter incoming HTTP requests. More...
 
OrthancPluginErrorCode OrthancPluginRegisterIncomingHttpRequestFilter2 (OrthancPluginContext *context, OrthancPluginIncomingHttpRequestFilter2 callback)
 Register a callback to filter incoming HTTP requests. More...
 
typedef struct _OrthancPluginDatabaseContext_t OrthancPluginDatabaseContext
 
OrthancPluginDatabaseContextOrthancPluginRegisterDatabaseBackend (OrthancPluginContext *context, const OrthancPluginDatabaseBackend *backend, void *payload)
 
OrthancPluginDatabaseContextOrthancPluginRegisterDatabaseBackendV2 (OrthancPluginContext *context, const OrthancPluginDatabaseBackend *backend, const OrthancPluginDatabaseExtensions *extensions, void *payload)
 

Detailed Description

Typedef Documentation

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 Osimis, 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 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.

Parameters
uuidThe UUID of the file.
contentThe content of the file.
sizeThe size of the file.
typeThe content type corresponding to this file.
Returns
0 if success, other value if error.
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.

Parameters
contentThe content of the file (output).
sizeThe size of the file (output).
uuidThe UUID of the file of interest.
typeThe content type corresponding to this file.
Returns
0 if success, other value if error.
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.

Parameters
uuidThe UUID of the file to be removed.
typeThe content type corresponding to this file.
Returns
0 if success, other value if error.

Enumeration Type Documentation

The supported types of changes that can happen to DICOM resources.

Enumerator
OrthancPluginChangeType_CompletedSeries 

Series is now complete

OrthancPluginChangeType_Deleted 

Deleted resource

OrthancPluginChangeType_NewChildInstance 

A new instance was added to this resource

OrthancPluginChangeType_NewInstance 

New instance received

OrthancPluginChangeType_NewPatient 

New patient created

OrthancPluginChangeType_NewSeries 

New series created

OrthancPluginChangeType_NewStudy 

New study created

OrthancPluginChangeType_StablePatient 

Timeout: No new instance in this patient

OrthancPluginChangeType_StableSeries 

Timeout: No new instance in this series

OrthancPluginChangeType_StableStudy 

Timeout: No new instance in this study

OrthancPluginChangeType_OrthancStarted 

Orthanc has started

OrthancPluginChangeType_OrthancStopped 

Orthanc is stopping

OrthancPluginChangeType_UpdatedAttachment 

Some user-defined attachment has changed for this resource

OrthancPluginChangeType_UpdatedMetadata 

Some user-defined metadata has changed for this resource

Function Documentation

int OrthancPluginCheckVersion ( OrthancPluginContext context)

This function checks whether the version of this C header is compatible with the current version of Orthanc. The result of this function should always be checked in the OrthancPluginInitialize() entry point of the plugin.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
Returns
1 if and only if the versions are compatible. If the result is 0, the initialization of the plugin should fail.
uint32_t OrthancPluginGetExpectedDatabaseVersion ( OrthancPluginContext context)

Retrieve the expected version of the database schema.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
Returns
The version.
Deprecated:
Please instead use IDatabaseBackend::UpgradeDatabase()
const char* OrthancPluginGetInstanceData ( OrthancPluginContext context,
OrthancPluginDicomInstance instance 
)

This function returns a pointer to the content of the given DICOM instance.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe instance of interest.
Returns
The pointer to the DICOM data, NULL in case of error.
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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe instance of interest.
Returns
The NULL value in case of error, or a string containing the JSON file. This string must be freed by OrthancPluginFreeString().
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().

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe instance of interest.
metadataThe metadata of interest.
Returns
The metadata value if success, NULL if error.
OrthancPluginInstanceOrigin OrthancPluginGetInstanceOrigin ( OrthancPluginContext context,
OrthancPluginDicomInstance instance 
)

This function returns the origin of a DICOM instance that has been received by Orthanc.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe instance of interest.
Returns
The origin of the instance.
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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe instance of interest.
Returns
The AET if success, NULL if error.
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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe instance of interest.
Returns
The NULL value in case of error, or a string containing the JSON file. This string must be freed by OrthancPluginFreeString().
int64_t OrthancPluginGetInstanceSize ( OrthancPluginContext context,
OrthancPluginDicomInstance instance 
)

This function returns the number of bytes of the given DICOM instance.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe instance of interest.
Returns
The size of the file, -1 in case of error.
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".

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
instanceThe instance of interest.
metadataThe metadata of interest.
Returns
1 if the metadata is present, 0 if it is absent, -1 in case of error.
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 (cf. OrthancPlugins::IDatabaseBackend::UpgradeDatabase). A database transaction will be automatically setup.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
storageAreaThe storage area.
levelThe type of the resources of interest.
Returns
0 if success, other value if error.
OrthancPluginDatabaseContext* OrthancPluginRegisterDatabaseBackend ( OrthancPluginContext context,
const OrthancPluginDatabaseBackend *  backend,
void *  payload 
)

Register a custom database back-end.

Instead of manually filling the OrthancPluginDatabaseBackend structure, you should instead implement a concrete C++ class deriving from OrthancPlugins::IDatabaseBackend, and register it using OrthancPlugins::DatabaseBackendAdapter::Register().

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
backendThe callbacks of the custom database engine.
payloadPointer containing private information for the database engine.
Returns
The context of the database engine (it must not be manually freed).
Deprecated:
See also
OrthancPluginRegisterDatabaseBackendV2
OrthancPluginDatabaseContext* OrthancPluginRegisterDatabaseBackendV2 ( OrthancPluginContext context,
const OrthancPluginDatabaseBackend *  backend,
const OrthancPluginDatabaseExtensions *  extensions,
void *  payload 
)

Register a custom database back-end.

Instead of manually filling the OrthancPluginDatabaseBackendV2 structure, you should instead implement a concrete C++ class deriving from OrthancPlugins::IDatabaseBackend, and register it using OrthancPlugins::DatabaseBackendAdapter::Register().

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
backendThe callbacks of the custom database engine.
payloadPointer containing private information for the database engine.
extensionsExtensions to the base database SDK that was shipped until Orthanc 0.9.3.
Returns
The context of the database engine (it must not be manually freed).
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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe callback.
Returns
0 if success, other value if error.
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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe callback.
Returns
0 if success, other value if error.
Deprecated:
Please instead use OrthancPluginRegisterIncomingHttpRequestFilter2()
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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe callback.
Returns
0 if success, other value if error.
void OrthancPluginRegisterOnChangeCallback ( OrthancPluginContext context,
OrthancPluginOnChangeCallback  callback 
)

This function registers a callback function that is called whenever a change happens to some DICOM resource.

Warning
If your change callback has to call the REST API of Orthanc, you should make these calls in a separate thread (with the events passing through a message queue). Otherwise, this could result in deadlocks in the presence of other plugins or Lua scripts.
Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe 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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe callback function.
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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
pathRegularExpressionRegular expression for the URI. May contain groups.
callbackThe callback function to handle the REST call.
See also
OrthancPluginRegisterRestCallbackNoLock()
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, it is up to the plugin to implement the required locking mechanisms.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
pathRegularExpressionRegular expression for the URI. May contain groups.
callbackThe callback function to handle the REST call.
See also
OrthancPluginRegisterRestCallback()
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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
createThe callback function to store a file on the custom storage area.
readThe callback function to read a file from the custom storage area.
removeThe 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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
storageAreaThe storage area.
uuidThe identifier of the file to be created.
contentThe content to store in the newly created file.
sizeThe size of the content.
typeThe type of the file content.
Returns
0 if success, other value if error.
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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
targetThe target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
storageAreaThe storage area.
uuidThe identifier of the file to be read.
typeThe type of the file content.
Returns
0 if success, other value if error.
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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
storageAreaThe storage area.
uuidThe identifier of the file to be removed.
typeThe type of the file content.
Returns
0 if success, other value if error.