Orthanc Plugin SDK: Callbacks

| Orthanc Plugin SDK 1.12.7 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.
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.
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.
typedef int32_t(* | OrthancPluginIncomingDicomInstanceFilter) (const OrthancPluginDicomInstance *instance)
| Callback to filter incoming DICOM instances received by Orthanc.
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.
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.
typedef OrthancPluginJob *(* | OrthancPluginJobsUnserializer) (const char *jobType, const char *serialized)
| Callback executed to unserialize a custom job.
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).
typedef void(* | OrthancPluginRefreshMetricsCallback) ()
| Callback executed to update the metrics of the plugin.
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.
typedef OrthancPluginErrorCode(* | OrthancPluginStorageRead) (void **content, int64_t *size, const char *uuid, OrthancPluginContentType type)
| Callback for reading from the storage area.
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.
typedef OrthancPluginErrorCode(* | OrthancPluginStorageReadWhole) (OrthancPluginMemoryBuffer64 *target, const char *uuid, OrthancPluginContentType type)
| Callback for reading a whole file from the storage area.
typedef OrthancPluginErrorCode(* | OrthancPluginStorageRemove) (const char *uuid, OrthancPluginContentType type)
| Callback for removing a file from the storage area.
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.
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.
typedef OrthancPluginErrorCode(* | OrthancPluginWebDavAddFolder) (OrthancPluginWebDavCollection *collection, const char *name, const char *dateTime)
| Declare a subfolder while returning the content of a folder.
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.
typedef OrthancPluginErrorCode(* | OrthancPluginWebDavDeleteItemCallback) (uint8_t *isReadOnly, uint32_t pathSize, const char *const *pathItems, void *payload)
| Callback to remove a file or a folder.
typedef OrthancPluginErrorCode(* | OrthancPluginWebDavIsExistingFolderCallback) (uint8_t *isExisting, uint32_t pathSize, const char *const *pathItems, void *payload)
| Callback for testing the existence of a folder.
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.
typedef OrthancPluginErrorCode(* | OrthancPluginWebDavRetrieveFile) (OrthancPluginWebDavCollection *collection, const void *data, uint64_t size, const char *mimeType, const char *dateTime)
| Retrieve the content of a file.
typedef OrthancPluginErrorCode(* | OrthancPluginWebDavRetrieveFileCallback) (OrthancPluginWebDavCollection *collection, OrthancPluginWebDavRetrieveFile retrieveFile, uint32_t pathSize, const char *const *pathItems, void *payload)
| Callback for retrieving the content of a file.
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.

## 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.
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.
uint32_t | OrthancPluginGetExpectedDatabaseVersion (OrthancPluginContext *context)
| Get the expected version of the database schema.
OrthancPluginErrorCode | OrthancPluginReconstructMainDicomTags (OrthancPluginContext *context, OrthancPluginStorageArea *storageArea, OrthancPluginResourceType level)
| Reconstruct the main DICOM tags.
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.
OrthancPluginErrorCode | OrthancPluginRegisterDatabaseBackendV4 (OrthancPluginContext *context, void *backend, uint32_t maxDatabaseRetries, OrthancPluginCallDatabaseBackendV4 operations, OrthancPluginFinalizeDatabaseBackendV4 finalize)
| Register a custom database back-end.
OrthancPluginErrorCode | OrthancPluginRegisterDecodeImageCallback (OrthancPluginContext *context, OrthancPluginDecodeImageCallback callback)
| Register a callback to handle the decoding of DICOM images.
OrthancPluginErrorCode | OrthancPluginRegisterIncomingCStoreInstanceFilter (OrthancPluginContext *context, OrthancPluginIncomingCStoreInstanceFilter callback)
| Register a callback to filter incoming DICOM instances received by Orthanc through C-STORE.
OrthancPluginErrorCode | OrthancPluginRegisterIncomingDicomInstanceFilter (OrthancPluginContext *context, OrthancPluginIncomingDicomInstanceFilter callback)
| Register a callback to filter incoming DICOM instances.
OrthancPluginErrorCode | OrthancPluginRegisterIncomingHttpRequestFilter (OrthancPluginContext *context, OrthancPluginIncomingHttpRequestFilter callback)
| Register a callback to filter incoming HTTP requests.
OrthancPluginErrorCode | OrthancPluginRegisterIncomingHttpRequestFilter2 (OrthancPluginContext *context, OrthancPluginIncomingHttpRequestFilter2 callback)
| Register a callback to filter incoming HTTP requests.
void | OrthancPluginRegisterJobsUnserializer (OrthancPluginContext *context, OrthancPluginJobsUnserializer unserializer)
| Register an unserializer for custom jobs.
void | OrthancPluginRegisterOnChangeCallback (OrthancPluginContext *context, OrthancPluginOnChangeCallback callback)
| Register a callback to monitor changes.
void | OrthancPluginRegisterOnStoredInstanceCallback (OrthancPluginContext *context, OrthancPluginOnStoredInstanceCallback callback)
| Register a callback for received instances.
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).
void | OrthancPluginRegisterRefreshMetricsCallback (OrthancPluginContext *context, OrthancPluginRefreshMetricsCallback callback)
| Register a callback to refresh the metrics.
void | OrthancPluginRegisterRestCallback (OrthancPluginContext *context, const char *pathRegularExpression, OrthancPluginRestCallback callback)
| Register a REST callback.
void | OrthancPluginRegisterRestCallbackNoLock (OrthancPluginContext *context, const char *pathRegularExpression, OrthancPluginRestCallback callback)
| Register a REST callback, without locking.
void | OrthancPluginRegisterStorageArea (OrthancPluginContext *context, OrthancPluginStorageCreate create, OrthancPluginStorageRead read, OrthancPluginStorageRemove remove)
| Register a custom storage area.
void | OrthancPluginRegisterStorageArea2 (OrthancPluginContext *context, OrthancPluginStorageCreate create, OrthancPluginStorageReadWhole readWhole, OrthancPluginStorageReadRange readRange, OrthancPluginStorageRemove remove)
| Register a custom storage area, with support for range request.
OrthancPluginErrorCode | OrthancPluginRegisterTranscoderCallback (OrthancPluginContext *context, OrthancPluginTranscoderCallback callback)
| Register a callback to handle the transcoding of DICOM images.
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.
OrthancPluginErrorCode | OrthancPluginStorageAreaCreate (OrthancPluginContext *context, OrthancPluginStorageArea *storageArea, const char *uuid, const void *content, uint64_t size, OrthancPluginContentType type)
| Create a file inside the storage area.
OrthancPluginErrorCode | OrthancPluginStorageAreaRead (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, OrthancPluginStorageArea *storageArea, const char *uuid, OrthancPluginContentType type)
| Read a file from the storage area.
OrthancPluginErrorCode | OrthancPluginStorageAreaRemove (OrthancPluginContext *context, OrthancPluginStorageArea *storageArea, const char *uuid, OrthancPluginContentType type)
| Remove a file from the storage area.
typedef struct _OrthancPluginDatabaseContext_t | OrthancPluginDatabaseContext
typedef struct _OrthancPluginDatabaseTransaction_t | OrthancPluginDatabaseTransaction
OrthancPluginDatabaseContext * | OrthancPluginRegisterDatabaseBackend (OrthancPluginContext *context, const OrthancPluginDatabaseBackend *backend, void *payload)
OrthancPluginDatabaseContext * | OrthancPluginRegisterDatabaseBackendV2 (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-2025 Orthanc Team SRL, Belgium Copyright (C) 2021-2025 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

  node | The node being generated, as provided by Orthanc.
  setter | The setter to be used to encode the content of the node. If the setter is not called, the binary tag is not written to the output document.
  levelDepth | The depth of the node in the DICOM hierarchy of sequences. This parameter gives the number of elements in the "levelTagGroup", "levelTagElement", and "levelIndex" arrays.
  levelTagGroup | The group of the parent DICOM tags in the hierarchy.
  levelTagElement | The element of the parent DICOM tags in the hierarchy.
  levelIndex | The index of the node in the parent sequences of the hierarchy.
  tagGroup | The group of the DICOM tag of interest.
  tagElement | The element of the DICOM tag of interest.
  vr | The value representation of the binary DICOM node.

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

  node | The node being generated, as provided by Orthanc.
  setter | The setter to be used to encode the content of the node. If the setter is not called, the binary tag is not written to the output document.
  levelDepth | The depth of the node in the DICOM hierarchy of sequences. This parameter gives the number of elements in the "levelTagGroup", "levelTagElement", and "levelIndex" arrays.
  levelTagGroup | The group of the parent DICOM tags in the hierarchy.
  levelTagElement | The element of the parent DICOM tags in the hierarchy.
  levelIndex | The index of the node in the parent sequences of the hierarchy.
  tagGroup | The group of the DICOM tag of interest.
  tagElement | The element of the DICOM tag of interest.
  vr | The value representation of the binary DICOM node.
  payload | The user payload.

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

  dimseStatus | If the DICOM instance is discarded, DIMSE status to be sent by the C-STORE SCP of Orthanc
  instance | The 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

  instance | The 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

  method | The HTTP method used by the request.
  uri | The URI of interest.
  ip | The IP address of the HTTP client.
  headersCount | The number of HTTP headers.
  headersKeys | The keys of the HTTP headers (always converted to low-case).
  headersValues | The 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

  method | The HTTP method used by the request.
  uri | The URI of interest.
  ip | The IP address of the HTTP client.
  headersCount | The number of HTTP headers.
  headersKeys | The keys of the HTTP headers (always converted to low-case).
  headersValues | The values of the HTTP headers.
  getArgumentsCount | The number of GET arguments (only for the GET HTTP method).
  getArgumentsKeys | The keys of the GET arguments (only for the GET HTTP method).
  getArgumentsValues | The 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

  jobType | The type of the job, as provided to OrthancPluginCreateJob().
  serialized | The 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

  modifiedDicomBuffer | A buffer containing the modified DICOM (output). This buffer must be allocated using OrthancPluginCreateMemoryBuffer64() and will be freed by the Orthanc core.
  receivedDicomBuffer | A buffer containing the received DICOM (input).
  receivedDicomBufferSize | The size of the received DICOM (input).
  origin | The 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

  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.

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

  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.

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

  target | Memory buffer where to store the content of the range. The memory buffer is allocated and freed by Orthanc. The length of the range of interest corresponds to the size of this buffer.
  uuid | The UUID of the file of interest.
  type | The content type corresponding to this file.
  rangeStart | Start position of the requested range in the file.

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

  target | Memory buffer where to store the content of the file. It must be allocated by the plugin using OrthancPluginCreateMemoryBuffer64(). The core of Orthanc will free it.
  uuid | The UUID of the file of interest.
  type | The content type corresponding to this file.

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

  uuid | The UUID of the file to be removed.
  type | The 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

  transcoded | Target memory buffer. It must be allocated by the plugin using OrthancPluginCreateMemoryBuffer().
  buffer | Memory buffer containing the source DICOM instance.
  size | Size of the source memory buffer.
  allowedSyntaxes | A C array of possible transfer syntaxes UIDs for the result of the transcoding. The plugin must choose by itself the transfer syntax that will be used for the resulting DICOM image.
  countSyntaxes | The number of transfer syntaxes that are contained in the "allowedSyntaxes" array.
  allowNewSopInstanceUid | Whether the transcoding plugin can select a transfer syntax that will change the SOP instance UID (or, in other terms, whether the plugin can transcode using lossy compression).

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

  collection | Context of the collection.
  name | Base name of the file.
  dateTime | The date and time of creation of the file. Check out the documentation of OrthancPluginWebDavRetrieveFile() for more information.
  size | Size of the file.
  mimeType | The 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

  collection | Context of the collection.
  name | Base name of the subfolder.
  dateTime | The 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

  isReadOnly | Pointer to a Boolean that must be set to 1 if the collection is read-only, or 0 otherwise.
  pathSize | Number of levels in the path.
  pathItems | Items making the path.
  payload | The 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

  isReadOnly | Pointer to a Boolean that must be set to 1 if the collection is read-only, or 0 otherwise.
  pathSize | Number of levels in the path.
  pathItems | Items making the path.
  payload | The 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

  isExisting | Pointer to a Boolean that must be set to 1 if the folder exists, or 0 otherwise.
  pathSize | Number of levels in the path.
  pathItems | Items making the path.
  payload | The 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

  isExisting | Pointer to a Boolean that must be set to 1 if the folder exists, or 0 otherwise.
  collection | Context to be provided to addFile() and addFolder() functions.
  addFile | Function to add a file to the list.
  addFolder | Function to add a folder to the list.
  pathSize | Number of levels in the path.
  pathItems | Items making the path.
  payload | The 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

  collection | Context of the collection.
  data | Content of the file.
  size | Size of the file.
  mimeType | The MIME type of the file. If empty or set to NULL, Orthanc will do a best guess depending on the file extension.
  dateTime | The 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

  collection | Context to be provided to retrieveFile() function.
  retrieveFile | Function to return the content of the file.
  pathSize | Number of levels in the path.
  pathItems | Items making the path.
  payload | The 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

  isReadOnly | Pointer to a Boolean that must be set to 1 if the collection is read-only, or 0 otherwise.
  pathSize | Number of levels in the path.
  pathItems | Items making the path.
  data | Content of the file to be stored.
  size | Size of the file to be stored.
  payload | The user payload.

Returns
  0 if success, other value if error.

## Enumeration Type Documentation

## ◆ OrthancPluginChangeType

enum OrthancPluginChangeType

The supported types of changes that can be signaled to the change callback. Note: this enum is not used to store changes in the DB !

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

  context | The 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

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  expectedMajor | Expected major version.
  expectedMinor | Expected minor version.
  expectedRevision | Expected 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

  context | The 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

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  storageArea | The storage area.
  level | The 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

  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 POST HTTP method.
  deleteHandler | The callback function to handle REST calls using the DELETE HTTP method.
  putHandler | The callback function to handle REST calls using the PUT HTTP 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.

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

  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.

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

  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.

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

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  backend | Pointer to the custom database backend.
  maxDatabaseRetries | Maximum number of retries if transaction doesn't succeed. If no retry is successful, OrthancPluginErrorCode_DatabaseCannotSerialize is generated.
  operations | Access to the operations of the custom database backend.
  finalize | Callback 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

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

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

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

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

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

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  unserializer | The 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

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

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

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

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

  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.

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

  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.

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

  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.

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

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  create | The callback function to store a file on the custom storage area.
  readWhole | The callback function to read a whole file from the custom storage area.
  readRange | The callback function to read some range of a file from the custom storage area. If this feature is not supported by the plugin, this value can be set to NULL.
  remove | The callback function to remove a file from the custom storage area.

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

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

  context | The Orthanc plugin context, as received by OrthancPluginInitialize().
  uri | URI where to map the WebDAV collection (must start with a / character).
  isExistingFolder | Callback method to test for the existence of a folder.
  listFolder | Callback method to list the content of a folder.
  retrieveFile | Callback method to retrieve the content of a file.
  storeFile | Callback method to store a file into the WebDAV collection.
  createFolder | Callback method to create a folder.
  deleteItem | Callback method to delete a file or a folder.
  payload | The 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

  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.

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

  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.

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

  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.

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.