Orthanc

Functions to access the content of the Orthanc server. More...

Functions
OrthancPluginErrorCode	OrthancPluginCallRestApi (OrthancPluginContext *context, OrthancPluginMemoryBuffer *answerBody, OrthancPluginMemoryBuffer *answerHeaders, uint16_t *httpStatus, OrthancPluginHttpMethod method, const char *uri, uint32_t headersCount, const char *const *headersKeys, const char *const *headersValues, const void *body, uint32_t bodySize, uint8_t afterPlugins)
	Call the REST API of Orthanc with full flexibility. More...
char *	OrthancPluginGenerateRestApiAuthorizationToken (OrthancPluginContext *context)
	Generate a token to grant full access to the REST API of Orthanc. More...
OrthancPluginErrorCode	OrthancPluginGetDicomForInstance (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *instanceId)
	Retrieve a DICOM instance using its Orthanc identifier. More...
char *	OrthancPluginGetGlobalProperty (OrthancPluginContext *context, int32_t property, const char *defaultValue)
	Get the value of a global property. More...
char *	OrthancPluginLookupInstance (OrthancPluginContext *context, const char *sopInstanceUID)
	Look for an instance. More...
char *	OrthancPluginLookupPatient (OrthancPluginContext *context, const char *patientID)
	Look for a patient. More...
char *	OrthancPluginLookupSeries (OrthancPluginContext *context, const char *seriesUID)
	Look for a series. 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...
OrthancPluginErrorCode	OrthancPluginRestApiDelete (OrthancPluginContext *context, const char *uri)
	Make a DELETE call to the built-in Orthanc REST API. More...
OrthancPluginErrorCode	OrthancPluginRestApiDeleteAfterPlugins (OrthancPluginContext *context, const char *uri)
	Make a DELETE call to the REST API, as tainted by the plugins. More...
OrthancPluginErrorCode	OrthancPluginRestApiGet (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *uri)
	Make a GET call to the built-in Orthanc REST API. More...
OrthancPluginErrorCode	OrthancPluginRestApiGet2 (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *uri, uint32_t headersCount, const char *const *headersKeys, const char *const *headersValues, int32_t afterPlugins)
	Make a GET call to the Orthanc REST API, with custom HTTP headers. More...
OrthancPluginErrorCode	OrthancPluginRestApiGetAfterPlugins (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *uri)
	Make a GET call to the REST API, as tainted by the plugins. More...
OrthancPluginErrorCode	OrthancPluginRestApiPost (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *uri, const void *body, uint32_t bodySize)
	Make a POST call to the built-in Orthanc REST API. More...
OrthancPluginErrorCode	OrthancPluginRestApiPostAfterPlugins (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *uri, const void *body, uint32_t bodySize)
	Make a POST call to the REST API, as tainted by the plugins. More...
OrthancPluginErrorCode	OrthancPluginRestApiPut (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *uri, const void *body, uint32_t bodySize)
	Make a PUT call to the built-in Orthanc REST API. More...
OrthancPluginErrorCode	OrthancPluginRestApiPutAfterPlugins (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const char *uri, const void *body, uint32_t bodySize)
	Make a PUT call to the REST API, as tainted by the plugins. More...
OrthancPluginErrorCode	OrthancPluginSetGlobalProperty (OrthancPluginContext *context, int32_t property, const char *value)
	Set the value of a global property. More...

Detailed Description

Function Documentation

OrthancPluginCallRestApi()

OrthancPluginErrorCode OrthancPluginCallRestApi	(	OrthancPluginContext *	context,
		OrthancPluginMemoryBuffer *	answerBody,
		OrthancPluginMemoryBuffer *	answerHeaders,
		uint16_t *	httpStatus,
		OrthancPluginHttpMethod	method,
		const char *	uri,
		uint32_t	headersCount,
		const char *const *	headersKeys,
		const char *const *	headersValues,
		const void *	body,
		uint32_t	bodySize,
		uint8_t	afterPlugins
	)

Make a call to the given URI in the REST API of Orthanc. The result to the query is stored into a newly allocated memory buffer. This function is always granted full access to the REST API (no credentials, nor security token is needed).

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
answerBody	The target memory buffer (out argument). It must be freed with OrthancPluginFreeMemoryBuffer(). The value of this argument is ignored if the HTTP method is DELETE.
answerHeaders	The target memory buffer for the HTTP headers in the answer (out argument). The answer headers are formatted as a JSON object (associative array). The buffer must be freed with OrthancPluginFreeMemoryBuffer(). This argument can be set to NULL if the plugin has no interest in the answer HTTP headers.
httpStatus	The HTTP status after the execution of the request (out argument).
method	HTTP method to be used.
uri	The URI of interest.
headersCount	The number of HTTP headers.
headersKeys	Array containing the keys of the HTTP headers (can be NULL if no header).
headersValues	Array containing the values of the HTTP headers (can be NULL if no header).
body	The HTTP body for a POST or PUT request.
bodySize	The size of the body.
afterPlugins	If 0, the built-in API of Orthanc is used. If 1, the API is tainted by the plugins.

Returns

0 if success, or the error code if failure.

See also

OrthancPluginRestApiGet2(), OrthancPluginRestApiPost(), OrthancPluginRestApiPut(), OrthancPluginRestApiDelete()

OrthancPluginGenerateRestApiAuthorizationToken()

char* OrthancPluginGenerateRestApiAuthorizationToken

(

OrthancPluginContext *

context

)

This function generates a token that can be set in the HTTP header "Authorization" so as to grant full access to the REST API of Orthanc using an external HTTP client. Using this function avoids the need of adding a separate user in the "RegisteredUsers" configuration of Orthanc, which eases deployments.

This feature is notably useful in multiprocess scenarios, where a subprocess created by a plugin has no access to the "OrthancPluginContext", and thus cannot call "OrthancPluginRestApi[Get|Post|Put|Delete]()".

This situation is frequently encountered in Python plugins, where the "multiprocessing" package can be used to bypass the Global Interpreter Lock (GIL) and thus to improve performance and concurrency.

Parameters

context

The Orthanc plugin context, as received by OrthancPluginInitialize().

Returns

The authorization token, or NULL value in the case of an error. This string must be freed by OrthancPluginFreeString().

OrthancPluginGetDicomForInstance()

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

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
target	The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
instanceId	The Orthanc identifier of the DICOM instance of interest.

Returns

0 if success, or the error code if failure.

OrthancPluginGetGlobalProperty()

char* OrthancPluginGetGlobalProperty	(	OrthancPluginContext *	context,
		int32_t	property,
		const char *	defaultValue
	)

Get the value of a global property that is stored in the Orthanc database. Global properties whose index is below 1024 are reserved by Orthanc.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
property	The global property of interest.
defaultValue	The value to return, if the global property is unset.

Returns

The value of the global property, or NULL in the case of an error. This string must be freed by OrthancPluginFreeString().

OrthancPluginLookupInstance()

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

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
sopInstanceUID	The SOP Instance UID of interest.

Returns

The NULL value if the instance is non-existent, or a string containing the Orthanc ID of the instance. This string must be freed by OrthancPluginFreeString().

OrthancPluginLookupPatient()

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

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
patientID	The Patient ID of interest.

Returns

The NULL value if the patient is non-existent, or a string containing the Orthanc ID of the patient. This string must be freed by OrthancPluginFreeString().

OrthancPluginLookupSeries()

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

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
seriesUID	The Series Instance UID of interest.

Returns

The NULL value if the series is non-existent, or a string containing the Orthanc ID of the series. This string must be freed by OrthancPluginFreeString().

OrthancPluginLookupStudy()

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

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
studyUID	The Study Instance UID of interest.

Returns

The NULL value if the study is non-existent, or a string containing the Orthanc ID of the study. This string must be freed by OrthancPluginFreeString().

OrthancPluginLookupStudyWithAccessionNumber()

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

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
accessionNumber	The Accession Number of interest.

Returns

The NULL value if the study is non-existent, or a string containing the Orthanc ID of the study. This string must be freed by OrthancPluginFreeString().

OrthancPluginRestApiDelete()

OrthancPluginErrorCode OrthancPluginRestApiDelete	(	OrthancPluginContext *	context,
		const char *	uri
	)

Make a DELETE call to the built-in Orthanc REST API.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
uri	The URI to delete in the built-in Orthanc API.

Returns

0 if success, or the error code if failure.

Note

If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.

See also

OrthancPluginRestApiDeleteAfterPlugins()

OrthancPluginRestApiDeleteAfterPlugins()

OrthancPluginErrorCode OrthancPluginRestApiDeleteAfterPlugins	(	OrthancPluginContext *	context,
		const char *	uri
	)

Make a DELETE call to the Orthanc REST API, after all the plugins are applied. In other words, if some plugin overrides or adds the called URI to the built-in Orthanc REST API, this call will return the result provided by this plugin.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
uri	The URI to delete in the built-in Orthanc API.

Returns

0 if success, or the error code if failure.

Note

If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.

See also

OrthancPluginRestApiDelete()

OrthancPluginRestApiGet()

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

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
target	The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
uri	The URI in the built-in Orthanc API.

Returns

0 if success, or the error code if failure.

Note

If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.

See also

OrthancPluginRestApiGetAfterPlugins()

OrthancPluginRestApiGet2()

OrthancPluginErrorCode OrthancPluginRestApiGet2	(	OrthancPluginContext *	context,
		OrthancPluginMemoryBuffer *	target,
		const char *	uri,
		uint32_t	headersCount,
		const char *const *	headersKeys,
		const char *const *	headersValues,
		int32_t	afterPlugins
	)

Make a GET call to the Orthanc REST API with extended parameters. The result to the query is stored into a newly allocated memory buffer.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
target	The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
uri	The URI in the built-in Orthanc API.
headersCount	The number of HTTP headers.
headersKeys	Array containing the keys of the HTTP headers (can be NULL if no header).
headersValues	Array containing the values of the HTTP headers (can be NULL if no header).
afterPlugins	If 0, the built-in API of Orthanc is used. If 1, the API is tainted by the plugins.

Returns

0 if success, or the error code if failure.

See also

OrthancPluginRestApiGet(), OrthancPluginRestApiGetAfterPlugins()

OrthancPluginRestApiGetAfterPlugins()

OrthancPluginErrorCode OrthancPluginRestApiGetAfterPlugins	(	OrthancPluginContext *	context,
		OrthancPluginMemoryBuffer *	target,
		const char *	uri
	)

Make a GET call to the Orthanc REST API, after all the plugins are applied. In other words, if some plugin overrides or adds the called URI to the built-in Orthanc REST API, this call will return the result provided by this plugin. The result to the query is stored into a newly allocated memory buffer.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
target	The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
uri	The URI in the built-in Orthanc API.

Returns

0 if success, or the error code if failure.

Note

If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.

See also

OrthancPluginRestApiGet()

OrthancPluginRestApiPost()

OrthancPluginErrorCode OrthancPluginRestApiPost	(	OrthancPluginContext *	context,
		OrthancPluginMemoryBuffer *	target,
		const char *	uri,
		const void *	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.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
target	The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
uri	The URI in the built-in Orthanc API.
body	The body of the POST request.
bodySize	The size of the body.

Returns

0 if success, or the error code if failure.

Note

If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.

See also

OrthancPluginRestApiPostAfterPlugins()

OrthancPluginRestApiPostAfterPlugins()

OrthancPluginErrorCode OrthancPluginRestApiPostAfterPlugins	(	OrthancPluginContext *	context,
		OrthancPluginMemoryBuffer *	target,
		const char *	uri,
		const void *	body,
		uint32_t	bodySize
	)

Make a POST call to the Orthanc REST API, after all the plugins are applied. In other words, if some plugin overrides or adds the called URI to the built-in Orthanc REST API, this call will return the result provided by this plugin. The result to the query is stored into a newly allocated memory buffer.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
target	The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
uri	The URI in the built-in Orthanc API.
body	The body of the POST request.
bodySize	The size of the body.

Returns

0 if success, or the error code if failure.

Note

If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.

See also

OrthancPluginRestApiPost()

OrthancPluginRestApiPut()

OrthancPluginErrorCode OrthancPluginRestApiPut	(	OrthancPluginContext *	context,
		OrthancPluginMemoryBuffer *	target,
		const char *	uri,
		const void *	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.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
target	The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
uri	The URI in the built-in Orthanc API.
body	The body of the PUT request.
bodySize	The size of the body.

Returns

0 if success, or the error code if failure.

Note

If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.

See also

OrthancPluginRestApiPutAfterPlugins()

OrthancPluginRestApiPutAfterPlugins()

OrthancPluginErrorCode OrthancPluginRestApiPutAfterPlugins	(	OrthancPluginContext *	context,
		OrthancPluginMemoryBuffer *	target,
		const char *	uri,
		const void *	body,
		uint32_t	bodySize
	)

Make a PUT call to the Orthanc REST API, after all the plugins are applied. In other words, if some plugin overrides or adds the called URI to the built-in Orthanc REST API, this call will return the result provided by this plugin. The result to the query is stored into a newly allocated memory buffer.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
target	The target memory buffer. It must be freed with OrthancPluginFreeMemoryBuffer().
uri	The URI in the built-in Orthanc API.
body	The body of the PUT request.
bodySize	The size of the body.

Returns

0 if success, or the error code if failure.

Note

If the resource is not existing (error 404), the error code will be OrthancPluginErrorCode_UnknownResource.

See also

OrthancPluginRestApiPut()

OrthancPluginSetGlobalProperty()

OrthancPluginErrorCode OrthancPluginSetGlobalProperty	(	OrthancPluginContext *	context,
		int32_t	property,
		const char *	value
	)

Set the value of a global property into the Orthanc database. Setting a global property can be used by plugins to save their internal parameters. Plugins are only allowed to set properties whose index are above or equal to 1024 (properties below 1024 are read-only and reserved by Orthanc).

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
property	The global property of interest.
value	The value to be set in the global property.

Returns

0 if success, or the error code if failure.