Orthanc Plugin SDK  1.12.4
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...
 

Typedefs

typedef OrthancPluginErrorCode(* OrthancPluginCallDatabaseBackendV4) (OrthancPluginMemoryBuffer64 *response, void *backend, const void *request, uint64_t requestSize)
 Signature of a callback function that is triggered when the Orthanc core requests an operation from the database plugin. Both request and response are encoded as protobuf buffers.
 
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(* OrthancPluginFinalizeDatabaseBackendV4) (void *backend)
 Signature of a callback function that is triggered when the database plugin must be finalized.
 
typedef void(* OrthancPluginFree) (void *buffer)
 Signature of a function to free dynamic memory.
 
typedef int32_t(* OrthancPluginIncomingCStoreInstanceFilter) (uint16_t *dimseStatus, const OrthancPluginDicomInstance *instance)
 Callback to filter incoming DICOM instances received by Orthanc through C-STORE. More...
 
typedef int32_t(* OrthancPluginIncomingDicomInstanceFilter) (const OrthancPluginDicomInstance *instance)
 Callback to filter incoming DICOM instances received by Orthanc. More...
 
typedef int32_t(* OrthancPluginIncomingHttpRequestFilter) (OrthancPluginHttpMethod method, const char *uri, const char *ip, uint32_t headersCount, const char *const *headersKeys, const char *const *headersValues)
 Callback to filter incoming HTTP requests received by Orthanc. More...
 
typedef int32_t(* OrthancPluginIncomingHttpRequestFilter2) (OrthancPluginHttpMethod method, const char *uri, const char *ip, uint32_t headersCount, const char *const *headersKeys, const char *const *headersValues, uint32_t getArgumentsCount, const char *const *getArgumentsKeys, const char *const *getArgumentsValues)
 Callback to filter incoming HTTP requests received by Orthanc. More...
 
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 OrthancPluginReceivedInstanceAction(* OrthancPluginReceivedInstanceCallback) (OrthancPluginMemoryBuffer64 *modifiedDicomBuffer, const void *receivedDicomBuffer, uint64_t receivedDicomBufferSize, OrthancPluginInstanceOrigin origin)
 Callback to keep/discard/modify a DICOM instance received by Orthanc from any source (C-STORE or REST API) More...
 
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 struct _OrthancPluginRestOutput_t OrthancPluginRestOutput
 Opaque structure that represents the HTTP connection to the client application.
 
typedef struct _OrthancPluginServerChunkedRequestReader_t OrthancPluginServerChunkedRequestReader
 Opaque structure that reads the content of a HTTP request body during a chunked HTTP transfer.
 
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 OrthancPluginErrorCode(* OrthancPluginWebDavAddFile) (OrthancPluginWebDavCollection *collection, const char *name, uint64_t size, const char *mimeType, const char *dateTime)
 Declare a file while returning the content of a folder. More...
 
typedef OrthancPluginErrorCode(* OrthancPluginWebDavAddFolder) (OrthancPluginWebDavCollection *collection, const char *name, const char *dateTime)
 Declare a subfolder while returning the content of a folder. More...
 
typedef struct _OrthancPluginWebDavCollection_t OrthancPluginWebDavCollection
 Opaque structure that represents a WebDAV collection.
 
typedef OrthancPluginErrorCode(* OrthancPluginWebDavCreateFolderCallback) (uint8_t *isReadOnly, uint32_t pathSize, const char *const *pathItems, void *payload)
 Callback to create a folder. More...
 
typedef OrthancPluginErrorCode(* OrthancPluginWebDavDeleteItemCallback) (uint8_t *isReadOnly, uint32_t pathSize, const char *const *pathItems, void *payload)
 Callback to remove a file or a folder. More...
 
typedef OrthancPluginErrorCode(* OrthancPluginWebDavIsExistingFolderCallback) (uint8_t *isExisting, uint32_t pathSize, const char *const *pathItems, void *payload)
 Callback for testing the existence of a folder. More...
 
typedef OrthancPluginErrorCode(* OrthancPluginWebDavListFolderCallback) (uint8_t *isExisting, OrthancPluginWebDavCollection *collection, OrthancPluginWebDavAddFile addFile, OrthancPluginWebDavAddFolder addFolder, uint32_t pathSize, const char *const *pathItems, void *payload)
 Callback for listing the content of a folder. More...
 
typedef OrthancPluginErrorCode(* OrthancPluginWebDavRetrieveFile) (OrthancPluginWebDavCollection *collection, const void *data, uint64_t size, const char *mimeType, const char *dateTime)
 Retrieve the content of a file. More...
 
typedef OrthancPluginErrorCode(* OrthancPluginWebDavRetrieveFileCallback) (OrthancPluginWebDavCollection *collection, OrthancPluginWebDavRetrieveFile retrieveFile, uint32_t pathSize, const char *const *pathItems, void *payload)
 Callback for retrieving the content of a file. More...
 
typedef OrthancPluginErrorCode(* OrthancPluginWebDavStoreFileCallback) (uint8_t *isReadOnly, uint32_t pathSize, const char *const *pathItems, const void *data, uint64_t size, void *payload)
 Callback to store a file. 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 ,
  OrthancPluginChangeType_UpdatedPeers ,
  OrthancPluginChangeType_UpdatedModalities ,
  OrthancPluginChangeType_JobSubmitted ,
  OrthancPluginChangeType_JobSuccess ,
  OrthancPluginChangeType_JobFailure ,
  _OrthancPluginChangeType_INTERNAL
}
 

Functions

int32_t OrthancPluginCheckVersion (OrthancPluginContext *context)
 Check the compatibility of the plugin wrt. the version of its hosting Orthanc. More...
 
int32_t OrthancPluginCheckVersionAdvanced (OrthancPluginContext *context, int32_t expectedMajor, int32_t expectedMinor, int32_t expectedRevision)
 Check that the version of the hosting Orthanc is above a given version. More...
 
uint32_t OrthancPluginGetExpectedDatabaseVersion (OrthancPluginContext *context)
 Get the expected version of the database schema. More...
 
OrthancPluginErrorCode OrthancPluginReconstructMainDicomTags (OrthancPluginContext *context, OrthancPluginStorageArea *storageArea, OrthancPluginResourceType level)
 Reconstruct the main DICOM tags. More...
 
void OrthancPluginRegisterChunkedRestCallback (OrthancPluginContext *context, const char *pathRegularExpression, OrthancPluginRestCallback getHandler, OrthancPluginServerChunkedRequestReaderFactory postHandler, OrthancPluginRestCallback deleteHandler, OrthancPluginServerChunkedRequestReaderFactory putHandler, OrthancPluginServerChunkedRequestReaderAddChunk addChunk, OrthancPluginServerChunkedRequestReaderExecute execute, OrthancPluginServerChunkedRequestReaderFinalize finalize)
 Register a REST callback to handle chunked HTTP transfers. More...
 
OrthancPluginErrorCode OrthancPluginRegisterDatabaseBackendV4 (OrthancPluginContext *context, void *backend, uint32_t maxDatabaseRetries, OrthancPluginCallDatabaseBackendV4 operations, OrthancPluginFinalizeDatabaseBackendV4 finalize)
 Register a custom database back-end. More...
 
OrthancPluginErrorCode OrthancPluginRegisterDecodeImageCallback (OrthancPluginContext *context, OrthancPluginDecodeImageCallback callback)
 Register a callback to handle the decoding of DICOM images. More...
 
OrthancPluginErrorCode OrthancPluginRegisterIncomingCStoreInstanceFilter (OrthancPluginContext *context, OrthancPluginIncomingCStoreInstanceFilter callback)
 Register a callback to filter incoming DICOM instances received by Orthanc through C-STORE. More...
 
OrthancPluginErrorCode OrthancPluginRegisterIncomingDicomInstanceFilter (OrthancPluginContext *context, OrthancPluginIncomingDicomInstanceFilter callback)
 Register a callback to filter incoming DICOM instances. 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...
 
void OrthancPluginRegisterJobsUnserializer (OrthancPluginContext *context, OrthancPluginJobsUnserializer unserializer)
 Register an unserializer for custom jobs. More...
 
void OrthancPluginRegisterOnChangeCallback (OrthancPluginContext *context, OrthancPluginOnChangeCallback callback)
 Register a callback to monitor changes. More...
 
void OrthancPluginRegisterOnStoredInstanceCallback (OrthancPluginContext *context, OrthancPluginOnStoredInstanceCallback callback)
 Register a callback for received instances. More...
 
OrthancPluginErrorCode OrthancPluginRegisterReceivedInstanceCallback (OrthancPluginContext *context, OrthancPluginReceivedInstanceCallback callback)
 Register a callback to keep/discard/modify a DICOM instance received by Orthanc from any source (C-STORE or REST API) More...
 
void OrthancPluginRegisterRefreshMetricsCallback (OrthancPluginContext *context, OrthancPluginRefreshMetricsCallback callback)
 Register a callback to refresh the metrics. 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 OrthancPluginRegisterStorageArea (OrthancPluginContext *context, OrthancPluginStorageCreate create, OrthancPluginStorageRead read, OrthancPluginStorageRemove remove)
 Register a custom storage area. More...
 
void OrthancPluginRegisterStorageArea2 (OrthancPluginContext *context, OrthancPluginStorageCreate create, OrthancPluginStorageReadWhole readWhole, OrthancPluginStorageReadRange readRange, OrthancPluginStorageRemove remove)
 Register a custom storage area, with support for range request. More...
 
OrthancPluginErrorCode OrthancPluginRegisterTranscoderCallback (OrthancPluginContext *context, OrthancPluginTranscoderCallback callback)
 Register a callback to handle the transcoding of DICOM images. More...
 
OrthancPluginErrorCode OrthancPluginRegisterWebDavCollection (OrthancPluginContext *context, const char *uri, OrthancPluginWebDavIsExistingFolderCallback isExistingFolder, OrthancPluginWebDavListFolderCallback listFolder, OrthancPluginWebDavRetrieveFileCallback retrieveFile, OrthancPluginWebDavStoreFileCallback storeFile, OrthancPluginWebDavCreateFolderCallback createFolder, OrthancPluginWebDavDeleteItemCallback deleteItem, void *payload)
 Register a WebDAV virtual filesystem. 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...
 
typedef struct _OrthancPluginDatabaseContext_t OrthancPluginDatabaseContext
 
typedef struct _OrthancPluginDatabaseTransaction_t OrthancPluginDatabaseTransaction
 
OrthancPluginDatabaseContextOrthancPluginRegisterDatabaseBackend (OrthancPluginContext *context, const OrthancPluginDatabaseBackend *backend, void *payload)
 
OrthancPluginDatabaseContextOrthancPluginRegisterDatabaseBackendV2 (OrthancPluginContext *context, const OrthancPluginDatabaseBackend *backend, const OrthancPluginDatabaseExtensions *extensions, void *payload)
 
OrthancPluginErrorCode OrthancPluginRegisterDatabaseBackendV3 (OrthancPluginContext *context, const OrthancPluginDatabaseBackendV3 *backend, uint32_t backendSize, uint32_t maxDatabaseRetries, void *database)
 

Detailed Description

Typedef Documentation

◆ OrthancPluginDatabaseContext

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-2023 Osimis S.A., Belgium Copyright (C) 2024-2024 Orthanc Team SRL, Belgium Copyright (C) 2021-2024 Sebastien Jodogne, ICTEAM UCLouvain, 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.

◆ OrthancPluginDatabaseTransaction

typedef struct _OrthancPluginDatabaseTransaction_t OrthancPluginDatabaseTransaction

Opaque structure that represents a transaction of a custom database engine. New in Orthanc 1.9.2.

◆ OrthancPluginDicomWebBinaryCallback

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.

See also
OrthancPluginEncodeDicomWebJson() and OrthancPluginEncodeDicomWebXml()
Parameters
nodeThe node being generated, as provided by Orthanc.
setterThe 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.
levelDepthThe depth of the node in the DICOM hierarchy of sequences. This parameter gives the number of elements in the "levelTagGroup", "levelTagElement", and "levelIndex" arrays.
levelTagGroupThe group of the parent DICOM tags in the hierarchy.
levelTagElementThe element of the parent DICOM tags in the hierarchy.
levelIndexThe index of the node in the parent sequences of the hierarchy.
tagGroupThe group of the DICOM tag of interest.
tagElementThe element of the DICOM tag of interest.
vrThe value representation of the binary DICOM node.

◆ OrthancPluginDicomWebBinaryCallback2

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.

See also
OrthancPluginEncodeDicomWebJson() and OrthancPluginEncodeDicomWebXml()
Parameters
nodeThe node being generated, as provided by Orthanc.
setterThe 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.
levelDepthThe depth of the node in the DICOM hierarchy of sequences. This parameter gives the number of elements in the "levelTagGroup", "levelTagElement", and "levelIndex" arrays.
levelTagGroupThe group of the parent DICOM tags in the hierarchy.
levelTagElementThe element of the parent DICOM tags in the hierarchy.
levelIndexThe index of the node in the parent sequences of the hierarchy.
tagGroupThe group of the DICOM tag of interest.
tagElementThe element of the DICOM tag of interest.
vrThe value representation of the binary DICOM node.
payloadThe user payload.

◆ OrthancPluginIncomingCStoreInstanceFilter

typedef int32_t(* OrthancPluginIncomingCStoreInstanceFilter) (uint16_t *dimseStatus, const OrthancPluginDicomInstance *instance)

Signature of a callback function that is triggered whenever Orthanc receives a new DICOM instance using DICOM C-STORE, and that answers whether this DICOM instance should be accepted or discarded by Orthanc. If the instance is discarded, the callback can specify the DIMSE error code answered by the Orthanc C-STORE SCP.

Note that the metadata information is not available (i.e. GetInstanceMetadata() should not be used on "instance").

Warning
Your callback function will be called synchronously with the core of Orthanc. This implies that deadlocks might emerge if you call other core primitives of Orthanc in your callback (such deadlocks are particularly visible in the presence of other plugins or Lua scripts). It is thus strongly advised to avoid any call to the REST API of Orthanc in the callback. If you have to call other primitives of Orthanc, you should make these calls in a separate thread, passing the pending events to be processed through a message queue.
Parameters
dimseStatusIf the DICOM instance is discarded, DIMSE status to be sent by the C-STORE SCP of Orthanc
instanceThe received DICOM instance.
Returns
0 to discard the instance, 1 to store the instance, -1 if error.

◆ OrthancPluginIncomingDicomInstanceFilter

typedef int32_t(* OrthancPluginIncomingDicomInstanceFilter) (const OrthancPluginDicomInstance *instance)

Signature of a callback function that is triggered whenever Orthanc receives a new DICOM instance (e.g. through REST API or DICOM protocol), and that answers whether this DICOM instance should be accepted or discarded by Orthanc.

Note that the metadata information is not available (i.e. GetInstanceMetadata() should not be used on "instance").

Warning
Your callback function will be called synchronously with the core of Orthanc. This implies that deadlocks might emerge if you call other core primitives of Orthanc in your callback (such deadlocks are particularly visible in the presence of other plugins or Lua scripts). It is thus strongly advised to avoid any call to the REST API of Orthanc in the callback. If you have to call other primitives of Orthanc, you should make these calls in a separate thread, passing the pending events to be processed through a message queue.
Parameters
instanceThe received DICOM instance.
Returns
0 to discard the instance, 1 to store the instance, -1 if error.

◆ OrthancPluginIncomingHttpRequestFilter

typedef int32_t(* OrthancPluginIncomingHttpRequestFilter) (OrthancPluginHttpMethod method, const char *uri, const char *ip, uint32_t headersCount, const char *const *headersKeys, const char *const *headersValues)

Signature of a callback function that is triggered whenever Orthanc receives an HTTP/REST request, and that answers whether this request should be allowed. If the callback returns "0" ("false"), the server answers with HTTP status code 403 (Forbidden).

Pay attention to the fact that this function may be invoked concurrently by different threads of the Web server of Orthanc. You must implement proper locking if applicable.

Parameters
methodThe HTTP method used by the request.
uriThe URI of interest.
ipThe IP address of the HTTP client.
headersCountThe number of HTTP headers.
headersKeysThe keys of the HTTP headers (always converted to low-case).
headersValuesThe values of the HTTP headers.
Returns
0 if forbidden access, 1 if allowed access, -1 if error.
Deprecated:
Please instead use OrthancPluginIncomingHttpRequestFilter2()

◆ OrthancPluginIncomingHttpRequestFilter2

typedef int32_t(* OrthancPluginIncomingHttpRequestFilter2) (OrthancPluginHttpMethod method, const char *uri, const char *ip, uint32_t headersCount, const char *const *headersKeys, const char *const *headersValues, uint32_t getArgumentsCount, const char *const *getArgumentsKeys, const char *const *getArgumentsValues)

Signature of a callback function that is triggered whenever Orthanc receives an HTTP/REST request, and that answers whether this request should be allowed. If the callback returns "0" ("false"), the server answers with HTTP status code 403 (Forbidden).

Pay attention to the fact that this function may be invoked concurrently by different threads of the Web server of Orthanc. You must implement proper locking if applicable.

Parameters
methodThe HTTP method used by the request.
uriThe URI of interest.
ipThe IP address of the HTTP client.
headersCountThe number of HTTP headers.
headersKeysThe keys of the HTTP headers (always converted to low-case).
headersValuesThe values of the HTTP headers.
getArgumentsCountThe number of GET arguments (only for the GET HTTP method).
getArgumentsKeysThe keys of the GET arguments (only for the GET HTTP method).
getArgumentsValuesThe values of the GET arguments (only for the GET HTTP method).
Returns
0 if forbidden access, 1 if allowed access, -1 if error.

◆ OrthancPluginJobsUnserializer

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.

Parameters
jobTypeThe type of the job, as provided to OrthancPluginCreateJob().
serializedThe serialization of the job, as provided by OrthancPluginJobGetSerialized.
Returns
The unserialized job (as created by OrthancPluginCreateJob()), or NULL if this unserializer cannot handle this job type.
See also
OrthancPluginRegisterJobsUnserializer()

◆ OrthancPluginReceivedInstanceCallback

typedef OrthancPluginReceivedInstanceAction(* OrthancPluginReceivedInstanceCallback) (OrthancPluginMemoryBuffer64 *modifiedDicomBuffer, const void *receivedDicomBuffer, uint64_t receivedDicomBufferSize, OrthancPluginInstanceOrigin origin)

Signature of a callback function that is triggered whenever Orthanc receives a new DICOM instance (through DICOM protocol or REST API), and that specifies an action to be applied to this newly received instance. The instance can be kept as it is, can be modified by the plugin, or can be discarded.

This callback is invoked immediately after reception, i.e. before transcoding and before filtering (cf. OrthancPluginRegisterIncomingDicomInstanceFilter()).

Warning
Your callback function will be called synchronously with the core of Orthanc. This implies that deadlocks might emerge if you call other core primitives of Orthanc in your callback (such deadlocks are particularly visible in the presence of other plugins or Lua scripts). It is thus strongly advised to avoid any call to the REST API of Orthanc in the callback. If you have to call other primitives of Orthanc, you should make these calls in a separate thread, passing the pending events to be processed through a message queue.
Parameters
modifiedDicomBufferA buffer containing the modified DICOM (output). This buffer must be allocated using OrthancPluginCreateMemoryBuffer64() and will be freed by the Orthanc core.
receivedDicomBufferA buffer containing the received DICOM (input).
receivedDicomBufferSizeThe size of the received DICOM (input).
originThe origin of the DICOM instance (input).
Returns
OrthancPluginReceivedInstanceAction_KeepAsIs to accept the instance as is,
OrthancPluginReceivedInstanceAction_Modify to store the modified DICOM contained in modifiedDicomBuffer,
OrthancPluginReceivedInstanceAction_Discard to tell Orthanc to discard the instance.

◆ OrthancPluginRefreshMetricsCallback

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() or OrthancPluginSetMetricsIntegerValue(). This is typically useful for metrics that are expensive to acquire.

See also
OrthancPluginRegisterRefreshMetrics()

◆ OrthancPluginStorageCreate

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.

◆ OrthancPluginStorageRead

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.
Deprecated:
New plugins should use OrthancPluginStorageRead2
Warning
The "content" buffer must have been allocated using the "malloc()" function of your C standard library (i.e. nor "new[]", neither a pointer to a buffer). The "free()" function of your C standard library will automatically be invoked on the "content" pointer.

◆ OrthancPluginStorageReadRange

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.

Parameters
targetMemory 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.
uuidThe UUID of the file of interest.
typeThe content type corresponding to this file.
rangeStartStart position of the requested range in the file.
Returns
0 if success, other value if error.

◆ OrthancPluginStorageReadWhole

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.

Parameters
targetMemory 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.
uuidThe UUID of the file of interest.
typeThe content type corresponding to this file.

◆ OrthancPluginStorageRemove

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.

◆ OrthancPluginTranscoderCallback

typedef OrthancPluginErrorCode(* OrthancPluginTranscoderCallback) (OrthancPluginMemoryBuffer *transcoded, const void *buffer, uint64_t size, const char *const *allowedSyntaxes, uint32_t countSyntaxes, uint8_t allowNewSopInstanceUid)
Parameters
transcodedTarget memory buffer. It must be allocated by the plugin using OrthancPluginCreateMemoryBuffer().
bufferMemory buffer containing the source DICOM instance.
sizeSize of the source memory buffer.
allowedSyntaxesA 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.
countSyntaxesThe number of transfer syntaxes that are contained in the "allowedSyntaxes" array.
allowNewSopInstanceUidWhether 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).
Returns
0 if success (i.e. image successfully transcoded and stored into "transcoded"), or the error code if failure.

◆ OrthancPluginWebDavAddFile

typedef OrthancPluginErrorCode(* OrthancPluginWebDavAddFile) (OrthancPluginWebDavCollection *collection, const char *name, uint64_t size, const char *mimeType, const char *dateTime)

This function declares a file while returning the content of a WebDAV folder.

Parameters
collectionContext of the collection.
nameBase name of the file.
dateTimeThe date and time of creation of the file. Check out the documentation of OrthancPluginWebDavRetrieveFile() for more information.
sizeSize of the file.
mimeTypeThe MIME type of the file. If empty or set to NULL, Orthanc will do a best guess depending on the file extension.
Returns
0 if success, other value if error.

◆ OrthancPluginWebDavAddFolder

typedef OrthancPluginErrorCode(* OrthancPluginWebDavAddFolder) (OrthancPluginWebDavCollection *collection, const char *name, const char *dateTime)

This function declares a subfolder while returning the content of a WebDAV folder.

Parameters
collectionContext of the collection.
nameBase name of the subfolder.
dateTimeThe date and time of creation of the subfolder. Check out the documentation of OrthancPluginWebDavRetrieveFile() for more information.
Returns
0 if success, other value if error.

◆ OrthancPluginWebDavCreateFolderCallback

typedef OrthancPluginErrorCode(* OrthancPluginWebDavCreateFolderCallback) (uint8_t *isReadOnly, uint32_t pathSize, const char *const *pathItems, void *payload)

Signature of a callback function that creates a folder in the WebDAV collection.

Parameters
isReadOnlyPointer to a Boolean that must be set to 1 if the collection is read-only, or 0 otherwise.
pathSizeNumber of levels in the path.
pathItemsItems making the path.
payloadThe user payload.
Returns
0 if success, other value if error.

◆ OrthancPluginWebDavDeleteItemCallback

typedef OrthancPluginErrorCode(* OrthancPluginWebDavDeleteItemCallback) (uint8_t *isReadOnly, uint32_t pathSize, const char *const *pathItems, void *payload)

Signature of a callback function that removes a file or a folder from the WebDAV collection.

Parameters
isReadOnlyPointer to a Boolean that must be set to 1 if the collection is read-only, or 0 otherwise.
pathSizeNumber of levels in the path.
pathItemsItems making the path.
payloadThe user payload.
Returns
0 if success, other value if error.

◆ OrthancPluginWebDavIsExistingFolderCallback

typedef OrthancPluginErrorCode(* OrthancPluginWebDavIsExistingFolderCallback) (uint8_t *isExisting, uint32_t pathSize, const char *const *pathItems, void *payload)

Signature of a callback function that tests whether the given path in the WebDAV collection exists and corresponds to a folder.

Parameters
isExistingPointer to a Boolean that must be set to 1 if the folder exists, or 0 otherwise.
pathSizeNumber of levels in the path.
pathItemsItems making the path.
payloadThe user payload.
Returns
0 if success, other value if error.

◆ OrthancPluginWebDavListFolderCallback

typedef OrthancPluginErrorCode(* OrthancPluginWebDavListFolderCallback) (uint8_t *isExisting, OrthancPluginWebDavCollection *collection, OrthancPluginWebDavAddFile addFile, OrthancPluginWebDavAddFolder addFolder, uint32_t pathSize, const char *const *pathItems, void *payload)

Signature of a callback function that lists the content of a folder in the WebDAV collection. The callback must call the provided addFile() and addFolder() functions to emit the content of the folder.

Parameters
isExistingPointer to a Boolean that must be set to 1 if the folder exists, or 0 otherwise.
collectionContext to be provided to addFile() and addFolder() functions.
addFileFunction to add a file to the list.
addFolderFunction to add a folder to the list.
pathSizeNumber of levels in the path.
pathItemsItems making the path.
payloadThe user payload.
Returns
0 if success, other value if error.

◆ OrthancPluginWebDavRetrieveFile

typedef OrthancPluginErrorCode(* OrthancPluginWebDavRetrieveFile) (OrthancPluginWebDavCollection *collection, const void *data, uint64_t size, const char *mimeType, const char *dateTime)

This function is used to forward the content of a file from a WebDAV collection, to the core of Orthanc.

Parameters
collectionContext of the collection.
dataContent of the file.
sizeSize of the file.
mimeTypeThe MIME type of the file. If empty or set to NULL, Orthanc will do a best guess depending on the file extension.
dateTimeThe date and time of creation of the file. It must be formatted as an ISO string of form YYYYMMDDTHHMMSS,fffffffff where T is the date-time separator. It must be expressed in UTC (it is the responsibility of the plugin to do the possible timezone conversions). Internally, this string will be parsed using boost::posix_time::from_iso_string().
Returns
0 if success, other value if error.

◆ OrthancPluginWebDavRetrieveFileCallback

typedef OrthancPluginErrorCode(* OrthancPluginWebDavRetrieveFileCallback) (OrthancPluginWebDavCollection *collection, OrthancPluginWebDavRetrieveFile retrieveFile, uint32_t pathSize, const char *const *pathItems, void *payload)

Signature of a callback function that retrieves the content of a file in the WebDAV collection. The callback must call the provided retrieveFile() function to emit the actual content of the file.

Parameters
collectionContext to be provided to retrieveFile() function.
retrieveFileFunction to return the content of the file.
pathSizeNumber of levels in the path.
pathItemsItems making the path.
payloadThe user payload.
Returns
0 if success, other value if error.

◆ OrthancPluginWebDavStoreFileCallback

typedef OrthancPluginErrorCode(* OrthancPluginWebDavStoreFileCallback) (uint8_t *isReadOnly, uint32_t pathSize, const char *const *pathItems, const void *data, uint64_t size, void *payload)

Signature of a callback function that stores a file into the WebDAV collection.

Parameters
isReadOnlyPointer to a Boolean that must be set to 1 if the collection is read-only, or 0 otherwise.
pathSizeNumber of levels in the path.
pathItemsItems making the path.
dataContent of the file to be stored.
sizeSize of the file to be stored.
payloadThe user payload.
Returns
0 if success, other value if error.

Enumeration Type Documentation

◆ OrthancPluginChangeType

The supported types of changes that can be signaled to the change callback.

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

OrthancPluginChangeType_UpdatedPeers 

The list of Orthanc peers has changed

OrthancPluginChangeType_UpdatedModalities 

The list of DICOM modalities has changed

OrthancPluginChangeType_JobSubmitted 

New Job submitted

OrthancPluginChangeType_JobSuccess 

A Job has completed successfully

OrthancPluginChangeType_JobFailure 

A Job has failed

Function Documentation

◆ OrthancPluginCheckVersion()

int32_t 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.

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.
See also
OrthancPluginCheckVersionAdvanced()

◆ OrthancPluginCheckVersionAdvanced()

int32_t OrthancPluginCheckVersionAdvanced ( OrthancPluginContext context,
int32_t  expectedMajor,
int32_t  expectedMinor,
int32_t  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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
expectedMajorExpected major version.
expectedMinorExpected minor version.
expectedRevisionExpected revision.
Returns
1 if and only if the versions are compatible. If the result is 0, the initialization of the plugin should fail.
See also
OrthancPluginCheckVersion()

◆ OrthancPluginGetExpectedDatabaseVersion()

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.

◆ OrthancPluginReconstructMainDicomTags()

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.

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.

◆ OrthancPluginRegisterChunkedRestCallback()

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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
pathRegularExpressionRegular expression for the URI. May contain groups.
getHandlerThe callback function to handle REST calls using the GET HTTP method.
postHandlerThe callback function to handle REST calls using the POST HTTP method.
deleteHandlerThe callback function to handle REST calls using the DELETE HTTP method.
putHandlerThe callback function to handle REST calls using the PUT HTTP method.
addChunkThe callback invoked when a new chunk is available for the request body of a POST or PUT call.
executeThe callback invoked once the entire body of a POST or PUT call is read.
finalizeThe callback invoked to release the resources associated with a POST or PUT call.
See also
OrthancPluginRegisterRestCallbackNoLock()
Note
The regular expression is case sensitive and must follow the Perl syntax.

◆ OrthancPluginRegisterDatabaseBackend()

OrthancPluginDatabaseContext* OrthancPluginRegisterDatabaseBackend ( OrthancPluginContext context,
const OrthancPluginDatabaseBackend *  backend,
void *  payload 
)

Register a custom database back-end (for legacy plugins).

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

◆ OrthancPluginRegisterDatabaseBackendV2()

OrthancPluginDatabaseContext* OrthancPluginRegisterDatabaseBackendV2 ( OrthancPluginContext context,
const OrthancPluginDatabaseBackend *  backend,
const OrthancPluginDatabaseExtensions *  extensions,
void *  payload 
)

Register a custom database back-end.

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).

◆ OrthancPluginRegisterDatabaseBackendV4()

OrthancPluginErrorCode OrthancPluginRegisterDatabaseBackendV4 ( OrthancPluginContext context,
void *  backend,
uint32_t  maxDatabaseRetries,
OrthancPluginCallDatabaseBackendV4  operations,
OrthancPluginFinalizeDatabaseBackendV4  finalize 
)

This function was added in Orthanc SDK 1.12.0. It uses Google Protocol Buffers for the communications between the Orthanc core and database plugins. Check out "OrthancDatabasePlugin.proto" for the definition of the protobuf messages.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
backendPointer to the custom database backend.
maxDatabaseRetriesMaximum number of retries if transaction doesn't succeed. If no retry is successful, OrthancPluginErrorCode_DatabaseCannotSerialize is generated.
operationsAccess to the operations of the custom database backend.
finalizeCallback to deallocate the custom database backend.
Returns
0 if success, other value if error.

◆ OrthancPluginRegisterDecodeImageCallback()

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.

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

◆ OrthancPluginRegisterIncomingCStoreInstanceFilter()

OrthancPluginErrorCode OrthancPluginRegisterIncomingCStoreInstanceFilter ( OrthancPluginContext context,
OrthancPluginIncomingCStoreInstanceFilter  callback 
)

This function registers a custom callback to filter incoming DICOM instances received by Orthanc through the DICOM protocol.

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

◆ OrthancPluginRegisterIncomingDicomInstanceFilter()

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).

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

◆ OrthancPluginRegisterIncomingHttpRequestFilter()

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()

◆ 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.

◆ OrthancPluginRegisterJobsUnserializer()

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.

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
unserializerThe job unserializer.

◆ OrthancPluginRegisterOnChangeCallback()

void OrthancPluginRegisterOnChangeCallback ( OrthancPluginContext context,
OrthancPluginOnChangeCallback  callback 
)

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

Warning
Your callback function will be called synchronously with the core of Orthanc. This implies that deadlocks might emerge if you call other core primitives of Orthanc in your callback (such deadlocks are particularly visible in the presence of other plugins or Lua scripts). It is thus strongly advised to avoid any call to the REST API of Orthanc in the callback. If you have to call other primitives of Orthanc, you should make these calls in a separate thread, passing the pending events to be processed through a message queue.
Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe callback function.

◆ OrthancPluginRegisterOnStoredInstanceCallback()

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.

Warning
Your callback function will be called synchronously with the core of Orthanc. This implies that deadlocks might emerge if you call other core primitives of Orthanc in your callback (such deadlocks are particularly visible in the presence of other plugins or Lua scripts). It is thus strongly advised to avoid any call to the REST API of Orthanc in the callback. If you have to call other primitives of Orthanc, you should make these calls in a separate thread, passing the pending events to be processed through a message queue.
Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe callback function.

◆ OrthancPluginRegisterReceivedInstanceCallback()

OrthancPluginErrorCode OrthancPluginRegisterReceivedInstanceCallback ( OrthancPluginContext context,
OrthancPluginReceivedInstanceCallback  callback 
)

This function registers a custom callback to keep/discard/modify incoming DICOM instances received by Orthanc from any source (C-STORE or REST API).

Warning
Contrarily to OrthancPluginRegisterIncomingCStoreInstanceFilter() and OrthancPluginRegisterIncomingDicomInstanceFilter() that can be called by multiple plugins, OrthancPluginRegisterReceivedInstanceCallback() can only be used by one single plugin.
Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe callback.
Returns
0 if success, other value if error.

◆ OrthancPluginRegisterRefreshMetricsCallback()

void OrthancPluginRegisterRefreshMetricsCallback ( OrthancPluginContext context,
OrthancPluginRefreshMetricsCallback  callback 
)

This function registers a callback to refresh the metrics. The callback must make calls to OrthancPluginSetMetricsValue() or OrthancPluginSetMetricsIntegerValue().

Parameters
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe callback function to handle the refresh.

◆ OrthancPluginRegisterRestCallback()

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()
Note
The regular expression is case sensitive and must follow the Perl syntax.

◆ 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, if using this function, 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()
Note
The regular expression is case sensitive and must follow the Perl syntax.

◆ OrthancPluginRegisterStorageArea()

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.
Deprecated:
Please use OrthancPluginRegisterStorageArea2()

◆ OrthancPluginRegisterStorageArea2()

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.

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

◆ OrthancPluginRegisterTranscoderCallback()

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.

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

◆ OrthancPluginRegisterWebDavCollection()

OrthancPluginErrorCode OrthancPluginRegisterWebDavCollection ( OrthancPluginContext context,
const char *  uri,
OrthancPluginWebDavIsExistingFolderCallback  isExistingFolder,
OrthancPluginWebDavListFolderCallback  listFolder,
OrthancPluginWebDavRetrieveFileCallback  retrieveFile,
OrthancPluginWebDavStoreFileCallback  storeFile,
OrthancPluginWebDavCreateFolderCallback  createFolder,
OrthancPluginWebDavDeleteItemCallback  deleteItem,
void *  payload 
)

This function maps a WebDAV collection onto the given URI in the REST API of Orthanc. 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().
uriURI where to map the WebDAV collection (must start with a / character).
isExistingFolderCallback method to test for the existence of a folder.
listFolderCallback method to list the content of a folder.
retrieveFileCallback method to retrieve the content of a file.
storeFileCallback method to store a file into the WebDAV collection.
createFolderCallback method to create a folder.
deleteItemCallback method to delete a file or a folder.
payloadThe user payload.
Returns
0 if success, other value if error.

◆ OrthancPluginStorageAreaCreate()

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.
Deprecated:
This function should not be used anymore. Use "OrthancPluginRestApiPut()" on "/{patients|studies|series|instances}/{id}/attachments/{name}" instead.

◆ OrthancPluginStorageAreaRead()

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.
Deprecated:
This function should not be used anymore. Use "OrthancPluginRestApiGet()" on "/{patients|studies|series|instances}/{id}/attachments/{name}" instead.

◆ OrthancPluginStorageAreaRemove()

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.
Deprecated:
This function should not be used anymore. Use "OrthancPluginRestApiDelete()" on "/{patients|studies|series|instances}/{id}/attachments/{name}" instead.