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

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

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.

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.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ OrthancPluginDatabaseContext

◆ OrthancPluginDatabaseTransaction

◆ OrthancPluginDicomWebBinaryCallback

◆ OrthancPluginDicomWebBinaryCallback2

◆ OrthancPluginIncomingCStoreInstanceFilter

◆ OrthancPluginIncomingDicomInstanceFilter

◆ OrthancPluginIncomingHttpRequestFilter

◆ OrthancPluginIncomingHttpRequestFilter2

◆ OrthancPluginJobsUnserializer

◆ OrthancPluginReceivedInstanceCallback

◆ OrthancPluginRefreshMetricsCallback

◆ OrthancPluginStorageCreate

◆ OrthancPluginStorageRead

◆ OrthancPluginStorageReadRange

◆ OrthancPluginStorageReadWhole

◆ OrthancPluginStorageRemove

◆ OrthancPluginTranscoderCallback

◆ OrthancPluginWebDavAddFile

◆ OrthancPluginWebDavAddFolder

◆ OrthancPluginWebDavCreateFolderCallback

◆ OrthancPluginWebDavDeleteItemCallback

◆ OrthancPluginWebDavIsExistingFolderCallback

◆ OrthancPluginWebDavListFolderCallback

◆ OrthancPluginWebDavRetrieveFile

◆ OrthancPluginWebDavRetrieveFileCallback

◆ OrthancPluginWebDavStoreFileCallback

Enumeration Type Documentation

◆ OrthancPluginChangeType

Function Documentation

◆ OrthancPluginCheckVersion()

◆ OrthancPluginCheckVersionAdvanced()

◆ OrthancPluginGetExpectedDatabaseVersion()

◆ OrthancPluginReconstructMainDicomTags()

◆ OrthancPluginRegisterChunkedRestCallback()

◆ OrthancPluginRegisterDatabaseBackend()

◆ OrthancPluginRegisterDatabaseBackendV2()

◆ OrthancPluginRegisterDatabaseBackendV4()

◆ OrthancPluginRegisterDecodeImageCallback()

◆ OrthancPluginRegisterIncomingCStoreInstanceFilter()

◆ OrthancPluginRegisterIncomingDicomInstanceFilter()

◆ OrthancPluginRegisterIncomingHttpRequestFilter()

◆ OrthancPluginRegisterIncomingHttpRequestFilter2()

◆ OrthancPluginRegisterJobsUnserializer()

◆ OrthancPluginRegisterOnChangeCallback()

◆ OrthancPluginRegisterOnStoredInstanceCallback()

◆ OrthancPluginRegisterReceivedInstanceCallback()

◆ OrthancPluginRegisterRefreshMetricsCallback()

◆ OrthancPluginRegisterRestCallback()

◆ OrthancPluginRegisterRestCallbackNoLock()

◆ OrthancPluginRegisterStorageArea()

◆ OrthancPluginRegisterStorageArea2()

◆ OrthancPluginRegisterTranscoderCallback()

◆ OrthancPluginRegisterWebDavCollection()

◆ OrthancPluginStorageAreaCreate()

◆ OrthancPluginStorageAreaRead()

◆ OrthancPluginStorageAreaRemove()