DicomCallbacks

Functions to register and manage DICOM callbacks (worklists, C-FIND, C-MOVE, storage commitment). More...

Typedefs
typedef OrthancPluginErrorCode(*	OrthancPluginApplyMove) (void *moveDriver)
	Callback to apply one C-Move suboperation. More...
typedef struct _OrthancPluginFindAnswers_t	OrthancPluginFindAnswers
	Opaque structure to an object that represents the answers to a C-Find query for worklists.
typedef OrthancPluginErrorCode(*	OrthancPluginFindCallback) (OrthancPluginFindAnswers *answers, const OrthancPluginFindQuery *query, const char *issuerAet, const char *calledAet)
	Callback to handle incoming C-Find SCP requests. More...
typedef struct _OrthancPluginFindQuery_t	OrthancPluginFindQuery
	Opaque structure to an object that represents a C-Find query.
typedef void(*	OrthancPluginFreeMove) (void *moveDriver)
	Callback to free one C-Move driver. More...
typedef uint32_t(*	OrthancPluginGetMoveSize) (void *moveDriver)
	Callback to read the size of a C-Move driver. More...
typedef void *(*	OrthancPluginMoveCallback) (OrthancPluginResourceType resourceType, const char *patientId, const char *accessionNumber, const char *studyInstanceUid, const char *seriesInstanceUid, const char *sopInstanceUid, const char *originatorAet, const char *sourceAet, const char *targetAet, uint16_t originatorId)
	Callback to handle incoming C-Move SCP requests. More...
typedef void(*	OrthancPluginStorageCommitmentDestructor) (void *handler)
	Callback to free one storage commitment SCP handler. More...
typedef OrthancPluginErrorCode(*	OrthancPluginStorageCommitmentFactory) (void **handler, const char *jobId, const char *transactionUid, const char *const *sopClassUids, const char *const *sopInstanceUids, uint32_t countInstances, const char *remoteAet, const char *calledAet)
	Callback executed by the storage commitment SCP. More...
typedef OrthancPluginErrorCode(*	OrthancPluginStorageCommitmentLookup) (OrthancPluginStorageCommitmentFailureReason *target, void *handler, const char *sopClassUid, const char *sopInstanceUid)
	Callback to get the status of one DICOM instance in the storage commitment SCP. More...
typedef struct _OrthancPluginWorklistAnswers_t	OrthancPluginWorklistAnswers
	Opaque structure to an object that represents the answers to a C-Find query for worklists.
typedef OrthancPluginErrorCode(*	OrthancPluginWorklistCallback) (OrthancPluginWorklistAnswers *answers, const OrthancPluginWorklistQuery *query, const char *issuerAet, const char *calledAet)
	Callback to handle the C-Find SCP requests for worklists. More...
typedef struct _OrthancPluginWorklistQuery_t	OrthancPluginWorklistQuery
	Opaque structure to an object that represents a C-Find query for worklists.

Functions
OrthancPluginErrorCode	OrthancPluginFindAddAnswer (OrthancPluginContext *context, OrthancPluginFindAnswers *answers, const void *dicom, uint32_t size)
	Add one answer to some C-Find request. More...
OrthancPluginErrorCode	OrthancPluginFindMarkIncomplete (OrthancPluginContext *context, OrthancPluginFindAnswers *answers)
	Mark the set of C-Find answers as incomplete. More...
uint32_t	OrthancPluginGetFindQuerySize (OrthancPluginContext *context, const OrthancPluginFindQuery *query)
	Get the number of tags in a C-Find query. More...
OrthancPluginErrorCode	OrthancPluginGetFindQueryTag (OrthancPluginContext *context, uint16_t *group, uint16_t *element, const OrthancPluginFindQuery *query, uint32_t index)
	Get one tag in a C-Find query. More...
char *	OrthancPluginGetFindQueryTagName (OrthancPluginContext *context, const OrthancPluginFindQuery *query, uint32_t index)
	Get the symbolic name of one tag in a C-Find query. More...
char *	OrthancPluginGetFindQueryValue (OrthancPluginContext *context, const OrthancPluginFindQuery *query, uint32_t index)
	Get the value associated with one tag in a C-Find query. More...
OrthancPluginErrorCode	OrthancPluginRegisterFindCallback (OrthancPluginContext *context, OrthancPluginFindCallback callback)
	Register a callback to handle C-Find requests. More...
OrthancPluginErrorCode	OrthancPluginRegisterMoveCallback (OrthancPluginContext *context, OrthancPluginMoveCallback callback, OrthancPluginGetMoveSize getMoveSize, OrthancPluginApplyMove applyMove, OrthancPluginFreeMove freeMove)
	Register a callback to handle C-Move requests. More...
OrthancPluginErrorCode	OrthancPluginRegisterStorageCommitmentScpCallback (OrthancPluginContext *context, OrthancPluginStorageCommitmentFactory factory, OrthancPluginStorageCommitmentDestructor destructor, OrthancPluginStorageCommitmentLookup lookup)
	Register a callback to handle incoming requests to the storage commitment SCP. More...
OrthancPluginErrorCode	OrthancPluginRegisterWorklistCallback (OrthancPluginContext *context, OrthancPluginWorklistCallback callback)
	Register a callback to handle modality worklists requests. More...
OrthancPluginErrorCode	OrthancPluginWorklistAddAnswer (OrthancPluginContext *context, OrthancPluginWorklistAnswers *answers, const OrthancPluginWorklistQuery *query, const void *dicom, uint32_t size)
	Add one answer to some modality worklist request. More...
OrthancPluginErrorCode	OrthancPluginWorklistGetDicomQuery (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const OrthancPluginWorklistQuery *query)
	Retrieve the worklist query as a DICOM file. More...
int32_t	OrthancPluginWorklistIsMatch (OrthancPluginContext *context, const OrthancPluginWorklistQuery *query, const void *dicom, uint32_t size)
	Test whether a worklist matches the query. More...
OrthancPluginErrorCode	OrthancPluginWorklistMarkIncomplete (OrthancPluginContext *context, OrthancPluginWorklistAnswers *answers)
	Mark the set of worklist answers as incomplete. More...

Detailed Description

Typedef Documentation

OrthancPluginApplyMove

typedef OrthancPluginErrorCode(* OrthancPluginApplyMove) (void *moveDriver)

Signature of a callback function that applies the next C-Move suboperation that os to be achieved by the given C-Move driver. This driver is the return value of a previous call to the OrthancPluginMoveCallback() callback.

Parameters

moveDriver

The C-Move driver of interest.

Returns

0 if success, or the error code if failure.

OrthancPluginFindCallback

typedef OrthancPluginErrorCode(* OrthancPluginFindCallback) (OrthancPluginFindAnswers *answers, const OrthancPluginFindQuery *query, const char *issuerAet, const char *calledAet)

Signature of a callback function that is triggered whenever Orthanc receives a C-Find SCP request not concerning modality worklists.

Parameters

answers	The target structure where answers must be stored.
query	The worklist query.
issuerAet	The Application Entity Title (AET) of the modality from which the request originates.
calledAet	The Application Entity Title (AET) of the modality that is called by the request.

Returns

0 if success, other value if error.

OrthancPluginFreeMove

typedef void(* OrthancPluginFreeMove) (void *moveDriver)

Signature of a callback function that releases the resources allocated by the given C-Move driver. This driver is the return value of a previous call to the OrthancPluginMoveCallback() callback.

Parameters

moveDriver

The C-Move driver of interest.

OrthancPluginGetMoveSize

typedef uint32_t(* OrthancPluginGetMoveSize) (void *moveDriver)

Signature of a callback function that returns the number of C-Move suboperations that are to be achieved by the given C-Move driver. This driver is the return value of a previous call to the OrthancPluginMoveCallback() callback.

Parameters

moveDriver

The C-Move driver of interest.

Returns

The number of suboperations.

OrthancPluginMoveCallback

typedef void*(* OrthancPluginMoveCallback) (OrthancPluginResourceType resourceType, const char *patientId, const char *accessionNumber, const char *studyInstanceUid, const char *seriesInstanceUid, const char *sopInstanceUid, const char *originatorAet, const char *sourceAet, const char *targetAet, uint16_t originatorId)

Signature of a callback function that is triggered whenever Orthanc receives a C-Move SCP request. The callback receives the type of the resource of interest (study, series, instance...) together with the DICOM tags containing its identifiers. In turn, the plugin must create a driver object that will be responsible for driving the successive move suboperations.

Parameters

resourceType	The type of the resource of interest. Note that this might be set to ResourceType_None if the QueryRetrieveLevel (0008,0052) tag was not provided by the issuer (i.e. the originator modality).
patientId	Content of the PatientID (0x0010, 0x0020) tag of the resource of interest. Might be NULL.
accessionNumber	Content of the AccessionNumber (0x0008, 0x0050) tag. Might be NULL.
studyInstanceUid	Content of the StudyInstanceUID (0x0020, 0x000d) tag. Might be NULL.
seriesInstanceUid	Content of the SeriesInstanceUID (0x0020, 0x000e) tag. Might be NULL.
sopInstanceUid	Content of the SOPInstanceUID (0x0008, 0x0018) tag. Might be NULL.
originatorAet	The Application Entity Title (AET) of the modality from which the request originates.
sourceAet	The Application Entity Title (AET) of the modality that should send its DICOM files to another modality.
targetAet	The Application Entity Title (AET) of the modality that should receive the DICOM files.
originatorId	The Message ID issued by the originator modality, as found in tag (0000,0110) of the DICOM query emitted by the issuer.

Returns

The NULL value if the plugin cannot deal with this query, or a pointer to the driver object that is responsible for handling the successive move suboperations.

Note

If targetAet equals sourceAet, this is actually a query/retrieve operation.

OrthancPluginStorageCommitmentDestructor

typedef void(* OrthancPluginStorageCommitmentDestructor) (void *handler)

Signature of a callback function that releases the resources allocated by the factory of the storage commitment SCP. The handler is the return value of a previous call to the OrthancPluginStorageCommitmentFactory() callback.

Parameters

handler

The handler object to be destructed.

OrthancPluginStorageCommitmentFactory

typedef OrthancPluginErrorCode(* OrthancPluginStorageCommitmentFactory) (void **handler, const char *jobId, const char *transactionUid, const char *const *sopClassUids, const char *const *sopInstanceUids, uint32_t countInstances, const char *remoteAet, const char *calledAet)

Signature of a factory function that creates an object to handle one incoming storage commitment request.

Remarks

The factory receives the list of the SOP class/instance UIDs of interest to the remote storage commitment SCU. This gives the factory the possibility to start some prefetch process upfront in the background, before the handler object is actually queried about the status of these DICOM instances.

Parameters

handler	Output variable where the factory puts the handler object it created.
jobId	ID of the Orthanc job that is responsible for handling the storage commitment request. This job will successively look for the status of all the individual queried DICOM instances.
transactionUid	UID of the storage commitment transaction provided by the storage commitment SCU. It contains the value of the (0008,1195) DICOM tag.
sopClassUids	Array of the SOP class UIDs (0008,0016) that are queried by the SCU.
sopInstanceUids	Array of the SOP instance UIDs (0008,0018) that are queried by the SCU.
countInstances	Number of DICOM instances that are queried. This is the size of the sopClassUids and sopInstanceUids arrays.
remoteAet	The AET of the storage commitment SCU.
calledAet	The AET used by the SCU to contact the storage commitment SCP (i.e. Orthanc).

Returns

0 if success, other value if error.

OrthancPluginStorageCommitmentLookup

typedef OrthancPluginErrorCode(* OrthancPluginStorageCommitmentLookup) (OrthancPluginStorageCommitmentFailureReason *target, void *handler, const char *sopClassUid, const char *sopInstanceUid)

Signature of a callback function that is successively invoked for each DICOM instance that is queried by the remote storage commitment SCU. The function must be tought of as a method of the handler object that was created by a previous call to the OrthancPluginStorageCommitmentFactory() callback. After each call to this method, the progress of the associated Orthanc job is updated.

Parameters

target	Output variable where to put the status for the queried instance.
handler	The handler object associated with this storage commitment request.
sopClassUid	The SOP class UID (0008,0016) of interest.
sopInstanceUid	The SOP instance UID (0008,0018) of interest.

OrthancPluginWorklistCallback

typedef OrthancPluginErrorCode(* OrthancPluginWorklistCallback) (OrthancPluginWorklistAnswers *answers, const OrthancPluginWorklistQuery *query, const char *issuerAet, const char *calledAet)

Signature of a callback function that is triggered when Orthanc receives a C-Find SCP request against modality worklists.

Parameters

answers	The target structure where answers must be stored.
query	The worklist query.
issuerAet	The Application Entity Title (AET) of the modality from which the request originates.
calledAet	The Application Entity Title (AET) of the modality that is called by the request.

Returns

0 if success, other value if error.

Function Documentation

OrthancPluginFindAddAnswer()

OrthancPluginErrorCode OrthancPluginFindAddAnswer	(	OrthancPluginContext *	context,
		OrthancPluginFindAnswers *	answers,
		const void *	dicom,
		uint32_t	size
	)

This function adds one answer (encoded as a DICOM file) to the set of answers corresponding to some C-Find SCP request that is not related to modality worklists.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
answers	The set of answers.
dicom	The answer to be added, encoded as a DICOM file.
size	The size of the DICOM file.

Returns

0 if success, other value if error.

See also

OrthancPluginCreateDicom()

OrthancPluginFindMarkIncomplete()

OrthancPluginErrorCode OrthancPluginFindMarkIncomplete	(	OrthancPluginContext *	context,
		OrthancPluginFindAnswers *	answers
	)

This function marks as incomplete the set of answers corresponding to some C-Find SCP request that is not related to modality worklists. This must be used if canceling the handling of a request when too many answers are to be returned.

Parameters

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

Returns

0 if success, other value if error.

OrthancPluginGetFindQuerySize()

uint32_t OrthancPluginGetFindQuerySize	(	OrthancPluginContext *	context,
		const OrthancPluginFindQuery *	query
	)

This function returns the number of tags that are contained in the given C-Find query.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
query	The C-Find query.

Returns

The number of tags.

OrthancPluginGetFindQueryTag()

OrthancPluginErrorCode OrthancPluginGetFindQueryTag	(	OrthancPluginContext *	context,
		uint16_t *	group,
		uint16_t *	element,
		const OrthancPluginFindQuery *	query,
		uint32_t	index
	)

This function returns the group and the element of one DICOM tag in the given C-Find query.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
group	The group of the tag (output).
element	The element of the tag (output).
query	The C-Find query.
index	The index of the tag of interest.

Returns

0 if success, other value if error.

OrthancPluginGetFindQueryTagName()

char* OrthancPluginGetFindQueryTagName	(	OrthancPluginContext *	context,
		const OrthancPluginFindQuery *	query,
		uint32_t	index
	)

This function returns the symbolic name of one DICOM tag in the given C-Find query.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
query	The C-Find query.
index	The index of the tag of interest.

Returns

The NULL value in case of error, or a string containing the name of the tag.

0 if success, other value if error.

OrthancPluginGetFindQueryValue()

char* OrthancPluginGetFindQueryValue	(	OrthancPluginContext *	context,
		const OrthancPluginFindQuery *	query,
		uint32_t	index
	)

This function returns the value associated with one tag in the given C-Find query.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
query	The C-Find query.
index	The index of the tag of interest.

Returns

The NULL value in case of error, or a string containing the value of the tag.

0 if success, other value if error.

OrthancPluginRegisterFindCallback()

OrthancPluginErrorCode OrthancPluginRegisterFindCallback	(	OrthancPluginContext *	context,
		OrthancPluginFindCallback	callback
	)

This function registers a callback to handle C-Find SCP requests that are not related to modality worklists.

Parameters

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

Returns

0 if success, other value if error.

OrthancPluginRegisterMoveCallback()

OrthancPluginErrorCode OrthancPluginRegisterMoveCallback	(	OrthancPluginContext *	context,
		OrthancPluginMoveCallback	callback,
		OrthancPluginGetMoveSize	getMoveSize,
		OrthancPluginApplyMove	applyMove,
		OrthancPluginFreeMove	freeMove
	)

This function registers a callback to handle C-Move SCP requests.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
callback	The main callback.
getMoveSize	Callback to read the number of C-Move suboperations.
applyMove	Callback to apply one C-Move suboperation.
freeMove	Callback to free the C-Move driver.

Returns

0 if success, other value if error.

OrthancPluginRegisterStorageCommitmentScpCallback()

OrthancPluginErrorCode OrthancPluginRegisterStorageCommitmentScpCallback	(	OrthancPluginContext *	context,
		OrthancPluginStorageCommitmentFactory	factory,
		OrthancPluginStorageCommitmentDestructor	destructor,
		OrthancPluginStorageCommitmentLookup	lookup
	)

This function registers a callback to handle storage commitment SCP requests.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
factory	Factory function that creates the handler object for incoming storage commitment requests.
destructor	Destructor function to destroy the handler object.
lookup	Callback function to get the status of one DICOM instance.

Returns

0 if success, other value if error.

OrthancPluginRegisterWorklistCallback()

OrthancPluginErrorCode OrthancPluginRegisterWorklistCallback	(	OrthancPluginContext *	context,
		OrthancPluginWorklistCallback	callback
	)

This function registers a callback to handle C-Find SCP requests on modality worklists.

Parameters

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

Returns

0 if success, other value if error.

OrthancPluginWorklistAddAnswer()

OrthancPluginErrorCode OrthancPluginWorklistAddAnswer	(	OrthancPluginContext *	context,
		OrthancPluginWorklistAnswers *	answers,
		const OrthancPluginWorklistQuery *	query,
		const void *	dicom,
		uint32_t	size
	)

This function adds one worklist (encoded as a DICOM file) to the set of answers corresponding to some C-Find SCP request against modality worklists.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
answers	The set of answers.
query	The worklist query, as received by the callback.
dicom	The worklist to answer, encoded as a DICOM file.
size	The size of the DICOM file.

Returns

0 if success, other value if error.

See also

OrthancPluginCreateDicom()

OrthancPluginWorklistGetDicomQuery()

OrthancPluginErrorCode OrthancPluginWorklistGetDicomQuery	(	OrthancPluginContext *	context,
		OrthancPluginMemoryBuffer *	target,
		const OrthancPluginWorklistQuery *	query
	)

This function retrieves the DICOM file that underlies a C-Find SCP query against modality worklists.

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
target	Memory buffer where to store the DICOM file. It must be freed with OrthancPluginFreeMemoryBuffer().
query	The worklist query, as received by the callback.

Returns

0 if success, other value if error.

OrthancPluginWorklistIsMatch()

int32_t OrthancPluginWorklistIsMatch	(	OrthancPluginContext *	context,
		const OrthancPluginWorklistQuery *	query,
		const void *	dicom,
		uint32_t	size
	)

This function checks whether one worklist (encoded as a DICOM file) matches the C-Find SCP query against modality worklists. This function must be called before adding the worklist as an answer through OrthancPluginWorklistAddAnswer().

Parameters

context	The Orthanc plugin context, as received by OrthancPluginInitialize().
query	The worklist query, as received by the callback.
dicom	The worklist to answer, encoded as a DICOM file.
size	The size of the DICOM file.

Returns

1 if the worklist matches the query, 0 otherwise.

OrthancPluginWorklistMarkIncomplete()

OrthancPluginErrorCode OrthancPluginWorklistMarkIncomplete	(	OrthancPluginContext *	context,
		OrthancPluginWorklistAnswers *	answers
	)

This function marks as incomplete the set of answers corresponding to some C-Find SCP request against modality worklists. This must be used if canceling the handling of a request when too many answers are to be returned.

Parameters

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

Returns

0 if success, other value if error.