![]() |
Orthanc Plugin SDK
Documentation of the plugin interface of Orthanc
|
The C interface to create Orthanc plugins. More...
Classes | |
struct | OrthancPluginHttpRequest |
The parameters of a REST request. More... | |
struct | OrthancPluginMemoryBuffer |
A memory buffer allocated by the core system of Orthanc. More... | |
Typedefs | |
typedef struct _OrthancPluginRestOutput_t | OrthancPluginRestOutput |
Opaque structure that represents the HTTP connection to the client application. | |
typedef struct _OrthancPluginDicomInstance_t | OrthancPluginDicomInstance |
Opaque structure that represents a DICOM instance received by Orthanc. | |
typedef int32_t(* | OrthancPluginRestCallback) (OrthancPluginRestOutput *output, const char *url, const OrthancPluginHttpRequest *request) |
Signature of a callback function that answers to a REST request. | |
typedef int32_t(* | OrthancPluginOnStoredInstanceCallback) (OrthancPluginDicomInstance *instance, const char *instanceId) |
Signature of a callback function that is triggered when Orthanc receives a DICOM instance. | |
typedef int32_t(* | 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 void(* | OrthancPluginFree) (void *buffer) |
Signature of a function to free dynamic memory. | |
typedef int32_t(* | OrthancPluginStorageCreate) (const char *uuid, const void *content, int64_t size, OrthancPluginContentType type) |
Callback for writing to the storage area. More... | |
typedef int32_t(* | OrthancPluginStorageRead) (void **content, int64_t *size, const char *uuid, OrthancPluginContentType type) |
Callback for reading from the storage area. More... | |
typedef int32_t(* | OrthancPluginStorageRemove) (const char *uuid, OrthancPluginContentType type) |
Callback for removing a file from the storage area. More... | |
typedef struct _OrthancPluginContext_t | OrthancPluginContext |
Opaque structure that contains information about the Orthanc core. | |
Functions | |
void | OrthancPluginFreeString (OrthancPluginContext *context, char *str) |
Free a string. More... | |
int | OrthancPluginCheckVersion (OrthancPluginContext *context) |
Check the compatibility of the plugin wrt. the version of its hosting Orthanc. More... | |
void | OrthancPluginFreeMemoryBuffer (OrthancPluginContext *context, OrthancPluginMemoryBuffer *buffer) |
Free a memory buffer. More... | |
void | OrthancPluginLogError (OrthancPluginContext *context, const char *message) |
Log an error. More... | |
void | OrthancPluginLogWarning (OrthancPluginContext *context, const char *message) |
Log a warning. More... | |
void | OrthancPluginLogInfo (OrthancPluginContext *context, const char *message) |
Log an information. More... | |
void | OrthancPluginRegisterRestCallback (OrthancPluginContext *context, const char *pathRegularExpression, OrthancPluginRestCallback callback) |
Register a REST callback. More... | |
void | OrthancPluginRegisterOnStoredInstanceCallback (OrthancPluginContext *context, OrthancPluginOnStoredInstanceCallback callback) |
Register a callback for received instances. More... | |
void | OrthancPluginAnswerBuffer (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *answer, uint32_t answerSize, const char *mimeType) |
Answer to a REST request. More... | |
void | OrthancPluginCompressAndAnswerPngImage (OrthancPluginContext *context, OrthancPluginRestOutput *output, OrthancPluginPixelFormat format, uint32_t width, uint32_t height, uint32_t pitch, const void *buffer) |
Answer to a REST request with a PNG image. More... | |
int | OrthancPluginGetDicomForInstance (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *instanceId) |
Retrieve a DICOM instance using its Orthanc identifier. More... | |
int | OrthancPluginRestApiGet (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *uri) |
Make a GET call to the built-in Orthanc REST API. More... | |
int | OrthancPluginRestApiPost (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *uri, const char *body, uint32_t bodySize) |
Make a POST call to the built-in Orthanc REST API. More... | |
int | OrthancPluginRestApiDelete (OrthancPluginContext *context, const char *uri) |
Make a DELETE call to the built-in Orthanc REST API. More... | |
int | OrthancPluginRestApiPut (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *uri, const char *body, uint32_t bodySize) |
Make a PUT call to the built-in Orthanc REST API. More... | |
void | OrthancPluginRedirect (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *redirection) |
Redirect a REST request. More... | |
char * | OrthancPluginLookupPatient (OrthancPluginContext *context, const char *patientID) |
Look for a patient. More... | |
char * | OrthancPluginLookupStudy (OrthancPluginContext *context, const char *studyUID) |
Look for a study. More... | |
char * | OrthancPluginLookupStudyWithAccessionNumber (OrthancPluginContext *context, const char *accessionNumber) |
Look for a study, using the accession number. More... | |
char * | OrthancPluginLookupSeries (OrthancPluginContext *context, const char *seriesUID) |
Look for a series. More... | |
char * | OrthancPluginLookupInstance (OrthancPluginContext *context, const char *sopInstanceUID) |
Look for an instance. More... | |
void | OrthancPluginSendHttpStatusCode (OrthancPluginContext *context, OrthancPluginRestOutput *output, uint16_t status) |
Send a HTTP status code. More... | |
void | OrthancPluginSendUnauthorized (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *realm) |
Signal that a REST request is not authorized. More... | |
void | OrthancPluginSendMethodNotAllowed (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *allowedMethods) |
Signal that this URI does not support this HTTP method. More... | |
void | OrthancPluginSetCookie (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *cookie, const char *value) |
Set a cookie. More... | |
void | OrthancPluginSetHttpHeader (OrthancPluginContext *context, OrthancPluginRestOutput *output, const char *key, const char *value) |
Set some HTTP header. More... | |
const char * | OrthancPluginGetInstanceRemoteAet (OrthancPluginContext *context, OrthancPluginDicomInstance *instance) |
Get the AET of a DICOM instance. More... | |
int64_t | OrthancPluginGetInstanceSize (OrthancPluginContext *context, OrthancPluginDicomInstance *instance) |
Get the size of a DICOM file. More... | |
const char * | OrthancPluginGetInstanceData (OrthancPluginContext *context, OrthancPluginDicomInstance *instance) |
Get the data of a DICOM file. More... | |
char * | OrthancPluginGetInstanceJson (OrthancPluginContext *context, OrthancPluginDicomInstance *instance) |
Get the DICOM tag hierarchy as a JSON file. More... | |
char * | OrthancPluginGetInstanceSimplifiedJson (OrthancPluginContext *context, OrthancPluginDicomInstance *instance) |
Get the DICOM tag hierarchy as a JSON file (with simplification). More... | |
int | OrthancPluginHasInstanceMetadata (OrthancPluginContext *context, OrthancPluginDicomInstance *instance, const char *metadata) |
Check whether a DICOM instance is associated with some metadata. More... | |
const char * | OrthancPluginGetInstanceMetadata (OrthancPluginContext *context, OrthancPluginDicomInstance *instance, const char *metadata) |
Get the value of some metadata associated with a given DICOM instance. More... | |
void | OrthancPluginRegisterStorageArea (OrthancPluginContext *context, OrthancPluginStorageCreate create, OrthancPluginStorageRead read, OrthancPluginStorageRemove remove) |
Register a custom storage area. More... | |
char * | OrthancPluginGetOrthancPath (OrthancPluginContext *context) |
Return the path to the Orthanc executable. More... | |
char * | OrthancPluginGetOrthancDirectory (OrthancPluginContext *context) |
Return the directory containing the Orthanc. More... | |
char * | OrthancPluginGetConfigurationPath (OrthancPluginContext *context) |
Return the path to the configuration file. More... | |
void | OrthancPluginRegisterOnChangeCallback (OrthancPluginContext *context, OrthancPluginOnChangeCallback callback) |
Register a callback to monitor changes. More... | |
These functions must be used to create C plugins for Orthanc.
typedef int32_t(* OrthancPluginStorageCreate) (const char *uuid, const void *content, int64_t size, OrthancPluginContentType type) |
Signature of a callback function that is triggered when Orthanc writes a file to the storage area.
uuid | The UUID of the file. |
content | The content of the file. |
size | The size of the file. |
type | The content type corresponding to this file. |
typedef int32_t(* OrthancPluginStorageRead) (void **content, int64_t *size, const char *uuid, OrthancPluginContentType type) |
Signature of a callback function that is triggered when Orthanc reads a file from the storage area.
content | The content of the file (output). |
size | The size of the file (output). |
uuid | The UUID of the file of interest. |
type | The content type corresponding to this file. |
typedef int32_t(* OrthancPluginStorageRemove) (const char *uuid, OrthancPluginContentType type) |
Signature of a callback function that is triggered when Orthanc deletes a file from the storage area.
uuid | The UUID of the file to be removed. |
type | The content type corresponding to this file. |
The supported type of changes that can happen to DICOM resources.
The memory layout of the pixels of an image.
void OrthancPluginAnswerBuffer | ( | OrthancPluginContext * | context, |
OrthancPluginRestOutput * | output, | ||
const char * | answer, | ||
uint32_t | answerSize, | ||
const char * | mimeType | ||
) |
This function answers to a REST request with the content of a memory buffer.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
output | The HTTP connection to the client application. |
answer | Pointer to the memory buffer containing the answer. |
answerSize | Number of bytes of the answer. |
mimeType | The MIME type of the answer. |
int OrthancPluginCheckVersion | ( | OrthancPluginContext * | context | ) |
This function checks whether the version of this C header is compatible with the current version of Orthanc. The result of this function should always be checked in the OrthancPluginInitialize() entry point of the plugin.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
void OrthancPluginCompressAndAnswerPngImage | ( | OrthancPluginContext * | context, |
OrthancPluginRestOutput * | output, | ||
OrthancPluginPixelFormat | format, | ||
uint32_t | width, | ||
uint32_t | height, | ||
uint32_t | pitch, | ||
const void * | buffer | ||
) |
This function answers to a REST request with a PNG image. The parameters of this function describe a memory buffer that contains an uncompressed image. The image will be automatically compressed as a PNG image by the core system of Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
output | The HTTP connection to the client application. |
format | The memory layout of the uncompressed image. |
width | The width of the image. |
height | The height of the image. |
pitch | The pitch of the image (i.e. the number of bytes between 2 successive lines of the image in the memory buffer. |
buffer | The memory buffer containing the uncompressed image. |
void OrthancPluginFreeMemoryBuffer | ( | OrthancPluginContext * | context, |
OrthancPluginMemoryBuffer * | buffer | ||
) |
Free a memory buffer that was allocated by the core system of Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
buffer | The memory buffer to release. |
void OrthancPluginFreeString | ( | OrthancPluginContext * | context, |
char * | str | ||
) |
Free a string that was allocated by the core system of Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
str | The string to be freed. |
char* OrthancPluginGetConfigurationPath | ( | OrthancPluginContext * | context | ) |
This function returns the path to the configuration file that was specified when starting Orthanc.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
int OrthancPluginGetDicomForInstance | ( | OrthancPluginContext * | context, |
OrthancPluginMemoryBuffer * | target, | ||
const char * | instanceId | ||
) |
Retrieve a DICOM instance using its Orthanc identifier. The DICOM file is stored into a newly allocated memory buffer.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
target | The target memory buffer. |
instanceId | The Orthanc identifier of the DICOM instance of interest. |
const char* OrthancPluginGetInstanceData | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance | ||
) |
This function returns a pointer to the content of the given DICOM instance.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
char* OrthancPluginGetInstanceJson | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance | ||
) |
This function returns a pointer to a newly created string containing a JSON file. This JSON file encodes the tag hierarchy of the given DICOM instance.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
const char* OrthancPluginGetInstanceMetadata | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance, | ||
const char * | metadata | ||
) |
This functions returns the value of some metadata that is associated with the DICOM instance of interest. Before calling this function, the existence of the metadata must have been checked with OrthancPluginHasInstanceMetadata().
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
metadata | The metadata of interest. |
const char* OrthancPluginGetInstanceRemoteAet | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance | ||
) |
This function returns the Application Entity Title (AET) of the DICOM modality from which a DICOM instance originates.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
char* OrthancPluginGetInstanceSimplifiedJson | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance | ||
) |
This function returns a pointer to a newly created string containing a JSON file. This JSON file encodes the tag hierarchy of the given DICOM instance. In contrast with OrthancPluginGetInstanceJson(), the returned JSON file is in its simplified version.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
int64_t OrthancPluginGetInstanceSize | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance | ||
) |
This function returns the number of bytes of the given DICOM instance.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
char* OrthancPluginGetOrthancDirectory | ( | OrthancPluginContext * | context | ) |
This function returns the path to the directory containing the Orthanc executable.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
char* OrthancPluginGetOrthancPath | ( | OrthancPluginContext * | context | ) |
This function returns the path to the Orthanc executable.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
int OrthancPluginHasInstanceMetadata | ( | OrthancPluginContext * | context, |
OrthancPluginDicomInstance * | instance, | ||
const char * | metadata | ||
) |
This function checks whether the DICOM instance of interest is associated with some metadata. As of Orthanc 0.8.1, in the callbacks registered by OrthancPluginRegisterOnStoredInstanceCallback(), the only possibly available metadata are "ReceptionDate", "RemoteAET" and "IndexInSeries".
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
instance | The instance of interest. |
metadata | The metadata of interest. |
void OrthancPluginLogError | ( | OrthancPluginContext * | context, |
const char * | message | ||
) |
Log an error message using the Orthanc logging system.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
message | The message to be logged. |
void OrthancPluginLogInfo | ( | OrthancPluginContext * | context, |
const char * | message | ||
) |
Log an information message using the Orthanc logging system.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
message | The message to be logged. |
void OrthancPluginLogWarning | ( | OrthancPluginContext * | context, |
const char * | message | ||
) |
Log a warning message using the Orthanc logging system.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
message | The message to be logged. |
char* OrthancPluginLookupInstance | ( | OrthancPluginContext * | context, |
const char * | sopInstanceUID | ||
) |
Look for an instance stored in Orthanc, using its SOP Instance UID tag (0x0008, 0x0018). This function uses the database index to run as fast as possible (it does not loop over all the stored instances).
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
sopInstanceUID | The SOP Instance UID of interest. |
char* OrthancPluginLookupPatient | ( | OrthancPluginContext * | context, |
const char * | patientID | ||
) |
Look for a patient stored in Orthanc, using its Patient ID tag (0x0010, 0x0020). This function uses the database index to run as fast as possible (it does not loop over all the stored patients).
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
patientID | The Patient ID of interest. |
char* OrthancPluginLookupSeries | ( | OrthancPluginContext * | context, |
const char * | seriesUID | ||
) |
Look for a series stored in Orthanc, using its Series Instance UID tag (0x0020, 0x000e). This function uses the database index to run as fast as possible (it does not loop over all the stored series).
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
seriesUID | The Series Instance UID of interest. |
char* OrthancPluginLookupStudy | ( | OrthancPluginContext * | context, |
const char * | studyUID | ||
) |
Look for a study stored in Orthanc, using its Study Instance UID tag (0x0020, 0x000d). This function uses the database index to run as fast as possible (it does not loop over all the stored studies).
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
studyUID | The Study Instance UID of interest. |
char* OrthancPluginLookupStudyWithAccessionNumber | ( | OrthancPluginContext * | context, |
const char * | accessionNumber | ||
) |
Look for a study stored in Orthanc, using its Accession Number tag (0x0008, 0x0050). This function uses the database index to run as fast as possible (it does not loop over all the stored studies).
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
accessionNumber | The Accession Number of interest. |
void OrthancPluginRedirect | ( | OrthancPluginContext * | context, |
OrthancPluginRestOutput * | output, | ||
const char * | redirection | ||
) |
This function answers to a REST request by redirecting the user to another URI using HTTP status 301.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
output | The HTTP connection to the client application. |
redirection | Where to redirect. |
void OrthancPluginRegisterOnChangeCallback | ( | OrthancPluginContext * | context, |
OrthancPluginOnChangeCallback | callback | ||
) |
This function registers a callback function that is called whenever a change happens to some DICOM resource.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
callback | The callback function. |
void OrthancPluginRegisterOnStoredInstanceCallback | ( | OrthancPluginContext * | context, |
OrthancPluginOnStoredInstanceCallback | callback | ||
) |
This function registers a callback function that is called whenever a new DICOM instance is stored into the Orthanc core.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
callback | The callback function. |
void 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.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
pathRegularExpression | Regular expression for the URI. May contain groups. |
callback | The callback function to handle the REST call. |
void OrthancPluginRegisterStorageArea | ( | OrthancPluginContext * | context, |
OrthancPluginStorageCreate | create, | ||
OrthancPluginStorageRead | read, | ||
OrthancPluginStorageRemove | remove | ||
) |
This function registers a custom storage area, to replace the built-in way Orthanc stores its files on the filesystem. This function must be called during the initialization of the plugin, i.e. inside the OrthancPluginInitialize() public function.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
create | The callback function to store a file on the custom storage area. |
read | The callback function to read a file from the custom storage area. |
remove | The callback function to remove a file from the custom storage area. |
int OrthancPluginRestApiDelete | ( | OrthancPluginContext * | context, |
const char * | uri | ||
) |
Make a DELETE call to the built-in Orthanc REST API.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
uri | The URI to delete in the built-in Orthanc API. |
int OrthancPluginRestApiGet | ( | OrthancPluginContext * | context, |
OrthancPluginMemoryBuffer * | target, | ||
const char * | uri | ||
) |
Make a GET call to the built-in Orthanc REST API. The result to the query is stored into a newly allocated memory buffer.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
target | The target memory buffer. |
uri | The URI in the built-in Orthanc API. |
int OrthancPluginRestApiPost | ( | OrthancPluginContext * | context, |
OrthancPluginMemoryBuffer * | target, | ||
const char * | uri, | ||
const char * | body, | ||
uint32_t | bodySize | ||
) |
Make a POST call to the built-in Orthanc REST API. The result to the query is stored into a newly allocated memory buffer.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
target | The target memory buffer. |
uri | The URI in the built-in Orthanc API. |
body | The body of the POST request. |
bodySize | The size of the body. |
int OrthancPluginRestApiPut | ( | OrthancPluginContext * | context, |
OrthancPluginMemoryBuffer * | target, | ||
const char * | uri, | ||
const char * | body, | ||
uint32_t | bodySize | ||
) |
Make a PUT call to the built-in Orthanc REST API. The result to the query is stored into a newly allocated memory buffer.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
target | The target memory buffer. |
uri | The URI in the built-in Orthanc API. |
body | The body of the PUT request. |
bodySize | The size of the body. |
void OrthancPluginSendHttpStatusCode | ( | OrthancPluginContext * | context, |
OrthancPluginRestOutput * | output, | ||
uint16_t | status | ||
) |
This function answers to a REST request by sending a HTTP status code (such as "400 - Bad Request"). Note that:
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
output | The HTTP connection to the client application. |
status | The HTTP status code to be sent. |
void OrthancPluginSendMethodNotAllowed | ( | OrthancPluginContext * | context, |
OrthancPluginRestOutput * | output, | ||
const char * | allowedMethods | ||
) |
This function answers to a REST request by signaling that the queried URI does not support this method.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
output | The HTTP connection to the client application. |
allowedMethods | The allowed methods for this URI (e.g. "GET,POST" after a PUT or a POST request). |
void OrthancPluginSendUnauthorized | ( | OrthancPluginContext * | context, |
OrthancPluginRestOutput * | output, | ||
const char * | realm | ||
) |
This function answers to a REST request by signaling that it is not authorized.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
output | The HTTP connection to the client application. |
realm | The realm for the authorization process. |
void OrthancPluginSetCookie | ( | OrthancPluginContext * | context, |
OrthancPluginRestOutput * | output, | ||
const char * | cookie, | ||
const char * | value | ||
) |
This function sets a cookie in the HTTP client.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
output | The HTTP connection to the client application. |
cookie | The cookie to be set. |
value | The value of the cookie. |
void OrthancPluginSetHttpHeader | ( | OrthancPluginContext * | context, |
OrthancPluginRestOutput * | output, | ||
const char * | key, | ||
const char * | value | ||
) |
This function sets a HTTP header in the HTTP answer.
context | The Orthanc plugin context, as received by OrthancPluginInitialize(). |
output | The HTTP connection to the client application. |
key | The HTTP header to be set. |
value | The value of the HTTP header. |