Orthanc Plugin SDK  1.5.8
Documentation of the plugin interface of Orthanc
Typedefs | Functions
DicomCallbacks

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

Typedefs

typedef struct _OrthancPluginWorklistQuery_t OrthancPluginWorklistQuery
 Opaque structure to an object that represents a C-Find query for worklists.
 
typedef struct _OrthancPluginWorklistAnswers_t OrthancPluginWorklistAnswers
 Opaque structure to an object that represents the answers to a C-Find query for worklists.
 
typedef struct _OrthancPluginFindQuery_t OrthancPluginFindQuery
 Opaque structure to an object that represents a C-Find query.
 
typedef struct _OrthancPluginFindAnswers_t OrthancPluginFindAnswers
 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 OrthancPluginErrorCode(* OrthancPluginFindCallback) (OrthancPluginFindAnswers *answers, const OrthancPluginFindQuery *query, const char *issuerAet, const char *calledAet)
 Callback to handle incoming C-Find SCP requests. 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 uint32_t(* OrthancPluginGetMoveSize) (void *moveDriver)
 Callback to read the size of a C-Move driver. More...
 
typedef OrthancPluginErrorCode(* OrthancPluginApplyMove) (void *moveDriver)
 Callback to apply one C-Move suboperation. More...
 
typedef void(* OrthancPluginFreeMove) (void *moveDriver)
 Callback to free one C-Move driver. More...
 

Functions

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 OrthancPluginWorklistMarkIncomplete (OrthancPluginContext *context, OrthancPluginWorklistAnswers *answers)
 Mark the set of worklist answers as incomplete. More...
 
int32_t OrthancPluginWorklistIsMatch (OrthancPluginContext *context, const OrthancPluginWorklistQuery *query, const void *dicom, uint32_t size)
 Test whether a worklist matches the query. More...
 
OrthancPluginErrorCode OrthancPluginWorklistGetDicomQuery (OrthancPluginContext *context, OrthancPluginMemoryBuffer *target, const OrthancPluginWorklistQuery *query)
 Retrieve the worklist query as a DICOM file. More...
 
OrthancPluginErrorCode OrthancPluginRegisterFindCallback (OrthancPluginContext *context, OrthancPluginFindCallback callback)
 Register a callback to handle C-Find requests. More...
 
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 OrthancPluginRegisterMoveCallback (OrthancPluginContext *context, OrthancPluginMoveCallback callback, OrthancPluginGetMoveSize getMoveSize, OrthancPluginApplyMove applyMove, OrthancPluginFreeMove freeMove)
 Register a callback to handle C-Move requests. More...
 

Detailed Description

Typedef Documentation

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

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