Orthanc Plugin SDK  1.12.3
Documentation of the plugin interface of Orthanc
Typedefs | Functions
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
moveDriverThe 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
answersThe target structure where answers must be stored.
queryThe worklist query.
issuerAetThe Application Entity Title (AET) of the modality from which the request originates.
calledAetThe 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
moveDriverThe 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
moveDriverThe 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
resourceTypeThe 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).
patientIdContent of the PatientID (0x0010, 0x0020) tag of the resource of interest. Might be NULL.
accessionNumberContent of the AccessionNumber (0x0008, 0x0050) tag. Might be NULL.
studyInstanceUidContent of the StudyInstanceUID (0x0020, 0x000d) tag. Might be NULL.
seriesInstanceUidContent of the SeriesInstanceUID (0x0020, 0x000e) tag. Might be NULL.
sopInstanceUidContent of the SOPInstanceUID (0x0008, 0x0018) tag. Might be NULL.
originatorAetThe Application Entity Title (AET) of the modality from which the request originates.
sourceAetThe Application Entity Title (AET) of the modality that should send its DICOM files to another modality.
targetAetThe Application Entity Title (AET) of the modality that should receive the DICOM files.
originatorIdThe 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
handlerThe 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
handlerOutput variable where the factory puts the handler object it created.
jobIdID 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.
transactionUidUID of the storage commitment transaction provided by the storage commitment SCU. It contains the value of the (0008,1195) DICOM tag.
sopClassUidsArray of the SOP class UIDs (0008,0016) that are queried by the SCU.
sopInstanceUidsArray of the SOP instance UIDs (0008,0018) that are queried by the SCU.
countInstancesNumber of DICOM instances that are queried. This is the size of the sopClassUids and sopInstanceUids arrays.
remoteAetThe AET of the storage commitment SCU.
calledAetThe 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
targetOutput variable where to put the status for the queried instance.
handlerThe handler object associated with this storage commitment request.
sopClassUidThe SOP class UID (0008,0016) of interest.
sopInstanceUidThe 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
answersThe target structure where answers must be stored.
queryThe worklist query.
issuerAetThe Application Entity Title (AET) of the modality from which the request originates.
calledAetThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
answersThe set of answers.
dicomThe answer to be added, encoded as a DICOM file.
sizeThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
answersThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
queryThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
groupThe group of the tag (output).
elementThe element of the tag (output).
queryThe C-Find query.
indexThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
queryThe C-Find query.
indexThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
queryThe C-Find query.
indexThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe main callback.
getMoveSizeCallback to read the number of C-Move suboperations.
applyMoveCallback to apply one C-Move suboperation.
freeMoveCallback 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
factoryFactory function that creates the handler object for incoming storage commitment requests.
destructorDestructor function to destroy the handler object.
lookupCallback 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
callbackThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
answersThe set of answers.
queryThe worklist query, as received by the callback.
dicomThe worklist to answer, encoded as a DICOM file.
sizeThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
targetMemory buffer where to store the DICOM file. It must be freed with OrthancPluginFreeMemoryBuffer().
queryThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
queryThe worklist query, as received by the callback.
dicomThe worklist to answer, encoded as a DICOM file.
sizeThe 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
contextThe Orthanc plugin context, as received by OrthancPluginInitialize().
answersThe set of answers.
Returns
0 if success, other value if error.