Orthanc Plugin SDK: DicomCallbacks

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

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