RZDCX - Fast Strike DICOM Toolkit  Release 2.0.7.4
DICOM Query/Retreive SCU

Functions

HRESULT IDCXREQ::Query ([in] BSTR callingTitle, [in] BSTR calledTitle, [in] BSTR host, [in] unsigned short port, [in] BSTR sopClassUid, [in] IDCXOBJ *obj, [out, retval] IDCXOBJIterator **i)
 send a DICOM C-FIND command More...
 
HRESULT IDCXREQ::Move ([in] BSTR callingTitle, [in] BSTR calledTitle, [in] BSTR host, [in] unsigned short port, [in] BSTR targetAETitle, [in] IDCXOBJ *query)
 Send a DICOM C-MOVE command. This is a C-MOVE SCU. The Query Model that is used for the C-MOVE command is Patient Root Q/R Move Information Model. More...
 
HRESULT IDCXREQ::MovePatient ([in] BSTR callingTitle, [in] BSTR calledTitle, [in] BSTR host, [in] unsigned short port, [in] BSTR targetAETitle, [in] BSTR patientName, [in] BSTR patientID)
 Retrieve images of a specific patint. More...
 
HRESULT IDCXREQ::MoveStudy ([in] BSTR callingTitle, [in] BSTR calledTitle, [in] BSTR host, [in] unsigned short port, [in] BSTR targetAETitle, [in] BSTR patientID, [in] BSTR studyInstanceUID)
 Retrieve images of a specific study. More...
 
HRESULT IDCXREQ::MoveSeries ([in] BSTR callingTitle, [in] BSTR calledTitle, [in] BSTR host, [in] unsigned short port, [in] BSTR targetAETitle, [in] BSTR patientID, [in] BSTR studyInstanceUID, [in] BSTR seriesInstanceUID)
 Retrieve images of a specific series. More...
 
HRESULT IDCXREQ::MoveInstances ([in] BSTR callingTitle, [in] BSTR calledTitle, [in] BSTR host, [in] unsigned short port, [in] BSTR targetAETitle, [in] BSTR patientID, [in] BSTR studyInstanceUID, [in] BSTR seriesInstanceUID, [in] BSTR instanceUIDs)
 Retrieve images of a specific instance or instances. More...
 
HRESULT IDCXREQ::QueryPatients ([in] BSTR callingTitle, [in] BSTR calledTitle, [in] BSTR host, [in] unsigned short port, [in] BSTR patientName, [in] BSTR patientId, [out, retval] IDCXOBJIterator **i)
 Make a Patients Query. More...
 
HRESULT IDCXREQ::QueryStudies ([in] BSTR callingTitle, [in] BSTR calledTitle, [in] BSTR host, [in] unsigned short port, [in] BSTR patientName, [in] BSTR patientId, [in] BSTR studyInstanceUID, [out, retval] IDCXOBJIterator **i)
 Make a Studies Query. More...
 
HRESULT IDCXREQ::QuerySeries ([in] BSTR callingTitle, [in] BSTR calledTitle, [in] BSTR host, [in] unsigned short port, [in] BSTR patientName, [in] BSTR patientId, [in] BSTR studyInstanceUID, [in] BSTR seriesInstanceUID, [out, retval] IDCXOBJIterator **i)
 Make a Series Query. More...
 
HRESULT IDCXREQ::QueryInstances ([in] BSTR callingTitle, [in] BSTR calledTitle, [in] BSTR host, [in] unsigned short port, [in] BSTR patientName, [in] BSTR patientId, [in] BSTR studyInstanceUID, [in] BSTR seriesInstanceUID, [in] BSTR sopInstanceUID, [out, retval] IDCXOBJIterator **i)
 Make a Instances Query. More...
 
HRESULT IDCXREQ::MoveAndStore ([in] BSTR callingTitle, [in] BSTR calledTitle, [in] BSTR host, [in] unsigned short called_port, [in] BSTR targetAETitle, [in] IDCXOBJ *query, [in] unsigned short calling_port, [in] IDCXACC *inAssocAccepter)
 Send a DICOM C-MOVE command and handle incomming association on provided port. More...
 
HRESULT rzdcxLib::IDCXREQEvents::OnQueryResponseRecieved (IDCXOBJ *obj)
 Called by Query after recieving a query result. More...
 
HRESULT rzdcxLib::IDCXREQEvents::OnMoveResponseRecieved (VARIANT_BOOL succeeded)
 Called by all the Move methods whenever a C-MOVE response is recieved. More...
 
HRESULT rzdcxLib::IDCXREQEvents::OnMoveResponseRecievedEx (unsigned short status, unsigned short remaining, unsigned short completed, unsigned short failed, unsigned short warning)
 

Detailed Description

Function Documentation

◆ Move()

HRESULT IDCXREQ::Move ( [in] BSTR  callingTitle,
[in] BSTR  calledTitle,
[in] BSTR  host,
[in] unsigned short  port,
[in] BSTR  targetAETitle,
[in] IDCXOBJ query 
)

Send a DICOM C-MOVE command. This is a C-MOVE SCU. The Query Model that is used for the C-MOVE command is Patient Root Q/R Move Information Model.

DICOM Conformance:
  • Requested Presentation Contexts:
    • Verification SOP Class - 1.2.840.10008.1.1
    • C-MOVE Patient Root Information Model - 1.2.840.10008.5.1.4.1.2.1.2
  • Proposed Transfer Syntaxes (for all verification and C-MOVE Model SOP Class):
    • Little Endian Implicit - 1.2.840.10008.1.2
    • Little Endian Explicit - 1.2.840.10008.1.2.1
    • Big Endian Explicit - 1.2.840.10008.1.2.2
Parameters
callingTitleCalling AE Title (us)
calledTitleCalled AE Title (them)
hostHost name or IP address (their)
portThe port number they are listening to,
targetAETitleThe AE Title that we want the SCP to send the files to
queryThe query object (identifier)

◆ MoveAndStore()

HRESULT IDCXREQ::MoveAndStore ( [in] BSTR  callingTitle,
[in] BSTR  calledTitle,
[in] BSTR  host,
[in] unsigned short  called_port,
[in] BSTR  targetAETitle,
[in] IDCXOBJ query,
[in] unsigned short  calling_port,
[in] IDCXACC inAssocAccepter 
)

Send a DICOM C-MOVE command and handle incomming association on provided port.

This is a C-MOVE SCU combined with a C-STORE SCP in a single command. It handles both the control channel of the outgoing C-MOVE request and the data channel of the incomming C-STORE commands on a separate association. The Query Model that is used for the C-MOVE command is Patient Root Q/R Move Information Model. The calling port must not be taked by another accepter. Be careful not to run simultaneous MoveAndStore command with the same port number.

DICOM Conformance:
  • Requested Presentation Contexts (outbound association):
    • Verification SOP Class - 1.2.840.10008.1.1
    • C-MOVE Patient Root Information Model - 1.2.840.10008.5.1.4.1.2.1.2
  • Proposed Transfer Syntaxes (for verification and C-MOVE Model SOP Class):
    • Little Endian Implicit - 1.2.840.10008.1.2
    • Little Endian Explicit - 1.2.840.10008.1.2.1
    • Big Endian Explicit - 1.2.840.10008.1.2.2
  • For the inbound association see conformance of IDCXACC methods
Parameters
callingTitleCalling AE Title (us)
calledTitleCalled AE Title (them)
hostHost name or IP address (their)
called_portThe port number they are listening to,
targetAETitleThe AE Title that we want the SCP to send the files to
queryThe query object (identifier)
inAssocAccepterThe port that we are going to listen on for incomming connections An accepter to handle the incomming association

◆ MoveInstances()

HRESULT IDCXREQ::MoveInstances ( [in] BSTR  callingTitle,
[in] BSTR  calledTitle,
[in] BSTR  host,
[in] unsigned short  port,
[in] BSTR  targetAETitle,
[in] BSTR  patientID,
[in] BSTR  studyInstanceUID,
[in] BSTR  seriesInstanceUID,
[in] BSTR  instanceUIDs 
)

Retrieve images of a specific instance or instances.

This method is the same as the Move method where the query object holds instance, series, study and patient attributes. Multiple instance uid's should be separated by ()

  • Requested Presentation Contexts:
    • Verification SOP Class - 1.2.840.10008.1.1
    • C-MOVE Study Root Information Model - 1.2.840.10008.5.1.4.1.2.2.2
  • Proposed Transfer Syntaxes (for all verification and C-MOVE Model SOP Class):
    • Little Endian Implicit - 1.2.840.10008.1.2
    • Little Endian Explicit - 1.2.840.10008.1.2.1
    • Big Endian Explicit - 1.2.840.10008.1.2.2
  • Query Retrieve Level (0008,0052) is "IMAGE"
Parameters
callingTitleCalling AE Title (us)
calledTitleCalled AE Title (them)
hostHost name or IP address (their)
portThe port number they are listening to,
targetAETitleThe AE Title that we want the SCP to send the files to
patientIDThe patient ID
studyInstanceUIDThe Study Instance UID
seriesInstanceUIDThe Series Instance UID
instanceUIDsThe SOP Instance UID(s)

◆ MovePatient()

HRESULT IDCXREQ::MovePatient ( [in] BSTR  callingTitle,
[in] BSTR  calledTitle,
[in] BSTR  host,
[in] unsigned short  port,
[in] BSTR  targetAETitle,
[in] BSTR  patientName,
[in] BSTR  patientID 
)

Retrieve images of a specific patint.

This method is the same as the Move method where the query object holds patient name and id. Multi-value () and/or wildchar matching (* and ?) may be used.

DICOM Conformance:
  • Requested Presentation Contexts:
    • Verification SOP Class - 1.2.840.10008.1.1
    • C-MOVE Patient Root Information Model - 1.2.840.10008.5.1.4.1.2.1.2
  • Proposed Transfer Syntaxes (for all verification and C-MOVE Model SOP Class):
    • Little Endian Implicit - 1.2.840.10008.1.2
    • Little Endian Explicit - 1.2.840.10008.1.2.1
    • Big Endian Explicit - 1.2.840.10008.1.2.2
  • Query Retrieve Level (0008,0052) is "PATIENT"
Parameters
callingTitleCalling AE Title (us)
calledTitleCalled AE Title (them)
hostHost name or IP address (their)
portThe port number they are listening to,
targetAETitleThe AE Title that we want the SCP to send the files to
patientNameA matching string for patient name attribute
patientIDA matching string for patient id attribute

◆ MoveSeries()

HRESULT IDCXREQ::MoveSeries ( [in] BSTR  callingTitle,
[in] BSTR  calledTitle,
[in] BSTR  host,
[in] unsigned short  port,
[in] BSTR  targetAETitle,
[in] BSTR  patientID,
[in] BSTR  studyInstanceUID,
[in] BSTR  seriesInstanceUID 
)

Retrieve images of a specific series.

This method is the same as the Move method where the query object holds series, study and patient attributes. Multi-value () and/or wildchar matching (* and ?) may be used.

  • Requested Presentation Contexts:
    • Verification SOP Class - 1.2.840.10008.1.1
    • C-MOVE Study Root Information Model - 1.2.840.10008.5.1.4.1.2.2.2
  • Proposed Transfer Syntaxes (for all verification and C-MOVE Model SOP Class):
    • Little Endian Implicit - 1.2.840.10008.1.2
    • Little Endian Explicit - 1.2.840.10008.1.2.1
    • Big Endian Explicit - 1.2.840.10008.1.2.2
  • Query Retrieve Level (0008,0052) is "SERIES"
Parameters
callingTitleCalling AE Title (us)
calledTitleCalled AE Title (them)
hostHost name or IP address (their)
portThe port number they are listening to,
targetAETitleThe AE Title that we want the SCP to send the files to
patientIDThe patient ID
studyInstanceUIDThe Study Instance UID
seriesInstanceUIDThe Series Instance UID

◆ MoveStudy()

HRESULT IDCXREQ::MoveStudy ( [in] BSTR  callingTitle,
[in] BSTR  calledTitle,
[in] BSTR  host,
[in] unsigned short  port,
[in] BSTR  targetAETitle,
[in] BSTR  patientID,
[in] BSTR  studyInstanceUID 
)

Retrieve images of a specific study.

This method is the same as the Move method where the query object holds study and patient attributes.

  • Requested Presentation Contexts:
    • Verification SOP Class - 1.2.840.10008.1.1
    • C-MOVE Study Root Information Model - 1.2.840.10008.5.1.4.1.2.2.2
  • Proposed Transfer Syntaxes (for all verification and C-MOVE Model SOP Class):
    • Little Endian Implicit - 1.2.840.10008.1.2
    • Little Endian Explicit - 1.2.840.10008.1.2.1
    • Big Endian Explicit - 1.2.840.10008.1.2.2
  • Query Retrieve Level (0008,0052) is "STUDY"
Parameters
callingTitleCalling AE Title (us)
calledTitleCalled AE Title (them)
hostHost name or IP address (their)
portThe port number they are listening to,
targetAETitleThe AE Title that we want the SCP to send the files to
patientIDThe patient ID
studyInstanceUIDThe Study Instance UID

◆ OnMoveResponseRecieved()

HRESULT rzdcxLib::IDCXREQEvents::OnMoveResponseRecieved ( VARIANT_BOOL  succeeded)

Called by all the Move methods whenever a C-MOVE response is recieved.

Deprecated:
This method is no longer called in version 2.0.2.8 or later. See OnMoveResponseRecievedEx To stop a running C-MOVE command by sending a C-CANCEL command to the SCP return a failed HRESULT (e.g. E_ABORT) status from the callback implementation or simply throw an exception.

◆ OnMoveResponseRecievedEx()

HRESULT rzdcxLib::IDCXREQEvents::OnMoveResponseRecievedEx ( unsigned short  status,
unsigned short  remaining,
unsigned short  completed,
unsigned short  failed,
unsigned short  warning 
)

Extended version of OnMoveResponseRecieved that adds the move response counters

Parameters
statusThe status from the response. 0x0000 is success, 0xFF00 and 0xFF01 are pending, 0x0001 and 0xBxxx are warning, 0xAxxx and 0xCxxx are Failure, 0xFE00 is cancel
remainingRemaining sub operations, relevant only when status is pending
completedcompleted sub operations, relevant only when status is pending
failedFailed sub operations, relevant only when status is pending
warningWarning sub operations, relevant only when status is pending

◆ OnQueryResponseRecieved()

HRESULT rzdcxLib::IDCXREQEvents::OnQueryResponseRecieved ( IDCXOBJ obj)

Called by Query after recieving a query result.

This event will be fired one time for each query result Using this event is an alternative to using the IDCXOBJIterator returned by the Query method. To stop a running C-FIND command by sending a C-CANCEL command to the SCP return a failed HRESULT (e.g. E_ABORT) status from the callback implementation or simply throw an exception.

◆ Query()

HRESULT IDCXREQ::Query ( [in] BSTR  callingTitle,
[in] BSTR  calledTitle,
[in] BSTR  host,
[in] unsigned short  port,
[in] BSTR  sopClassUid,
[in] IDCXOBJ obj,
[out, retval] IDCXOBJIterator **  i 
)

send a DICOM C-FIND command

This method performs a DICOM Query to a remote DICOM System (Archive, PACS etc.). The query matching attributes should be set in the Query Object parameter as well as the query level (DICOM Tag (0008,00052)). For more information about how to set the query elements see the DICOM Standard Part 4 in the seqtion describing DICOM Q/R Service. Alternativly you can use the simpler query methods:

  • QueryPatients,
  • QueryStudies,
  • QuerySeries,
  • QueryInstances or
  • QueryModalityWorklist. The results are returned as an Object Iterator (IDCXOBJIterator). Additionally, an event is fired for every result. You can use this method in two ways:
  • Wait for the query to complete and then go over the results in the iterator or,
  • Implement the event and collect the results there.
    Returns
    a IDCXOBJIterator holding the results
    DICOM Conformance:
Parameters
callingTitleCalling AE Title (us)
calledTitleCalled AE Title (them)
hostHost name or IP address (their)
portThe port number they are listening to
sopClassUidThe query model to use
objThe query object
iThe results

◆ QueryInstances()

HRESULT IDCXREQ::QueryInstances ( [in] BSTR  callingTitle,
[in] BSTR  calledTitle,
[in] BSTR  host,
[in] unsigned short  port,
[in] BSTR  patientName,
[in] BSTR  patientId,
[in] BSTR  studyInstanceUID,
[in] BSTR  seriesInstanceUID,
[in] BSTR  sopInstanceUID,
[out, retval] IDCXOBJIterator **  i 
)

Make a Instances Query.

Not implemented! This methods sends a C-FIND command. The Query is made using the Study Root Q/R Model with Query Level "IMAGE". The most common use of this query is to verify that all the instances of a study or series were retreived before or after a C-MOVE command. The more detailed Query method can be used if control over the query model and level is required.

See also
Query
Parameters
callingTitleCalling AE Title (us)
calledTitleCalled AE Title (them)
hostHost name or IP address (their)
portThe port number they are listening to
patientNameThe Patient Name to look for. Wildcards (* and ?) and multiple values separated by (/) can be used though not all Q/R SCP's will allow that.
patientIdThe patient ID to look for. Wildcards (* and ?) and multiple values separated by (/) can be used though not all Q/R SCP's will allow that.
studyInstanceUIDThe Study Instance UID to look for.
seriesInstanceUIDUse a 0 length string to get all Patient Studies. Multi value matching can be made using the (/) character. The Series Instance UID to look for.
sopInstanceUIDUse a 0 length string to get all Series. Multi value matching can be made using the (/) character. The SOP Instance UID to look for.
iUse a 0 length string to get all Instances. Multi value matching can be made using the (/) character. The results

◆ QueryPatients()

HRESULT IDCXREQ::QueryPatients ( [in] BSTR  callingTitle,
[in] BSTR  calledTitle,
[in] BSTR  host,
[in] unsigned short  port,
[in] BSTR  patientName,
[in] BSTR  patientId,
[out, retval] IDCXOBJIterator **  i 
)

Make a Patients Query.

This methods sends a C-FIND command. The Query is made using the Patient Root Q/R Model with Query Level "PATIENT". The matching attributes are:

  • Patient Name
  • Patient ID and the fetch attributes are:
  • Patient Date of Birth,
  • Patient Sex The more detailed Query method can be used if control over the query model and level is required.
    See also
    Query
Parameters
callingTitleCalling AE Title (us)
calledTitleCalled AE Title (them)
hostHost name or IP address (their)
portThe port number they are listening to
patientNameThe Patient Name to look for. Wildcards (* and ?) and multiple values separated by (/) can be used though not all Q/R SCP's will allow that.
patientIdThe patient ID to look for. Wildcards (* and ?) and multiple values separated by (/) can be used though not all Q/R SCP's will allow that.
iThe results

◆ QuerySeries()

HRESULT IDCXREQ::QuerySeries ( [in] BSTR  callingTitle,
[in] BSTR  calledTitle,
[in] BSTR  host,
[in] unsigned short  port,
[in] BSTR  patientName,
[in] BSTR  patientId,
[in] BSTR  studyInstanceUID,
[in] BSTR  seriesInstanceUID,
[out, retval] IDCXOBJIterator **  i 
)

Make a Series Query.

Not implemented! This methods sends a C-FIND command. The Query is made using the Study Root Q/R Model with Query Level "SERIES". The more detailed Query method can be used if control over the query model and level is required.

See also
Query
Parameters
callingTitleCalling AE Title (us)
calledTitleCalled AE Title (them)
hostHost name or IP address (their)
portThe port number they are listening to
patientNameThe Patient Name to look for. Wildcards (* and ?) and multiple values separated by (/) can be used though not all Q/R SCP's will allow that.
patientIdThe patient ID to look for. Wildcards (* and ?) and multiple values separated by (/) can be used though not all Q/R SCP's will allow that.
studyInstanceUIDThe Study Instance UID to look for. Use a 0 length string to get all Patient Studies. Multi value matching can be made using the (/) character.
seriesInstanceUIDThe Series Instance UID to look for.
iUse a 0 length string to get all Patient Studies. Multi value matching can be made using the (/) character. The results

◆ QueryStudies()

HRESULT IDCXREQ::QueryStudies ( [in] BSTR  callingTitle,
[in] BSTR  calledTitle,
[in] BSTR  host,
[in] unsigned short  port,
[in] BSTR  patientName,
[in] BSTR  patientId,
[in] BSTR  studyInstanceUID,
[out, retval] IDCXOBJIterator **  i 
)

Make a Studies Query.

Not implemented! This methods sends a C-FIND command. The Query is made using the Study Root Q/R Model with Query Level "STUDY". It usefull for example to get the list of studies for a specific patient. The more detailed Query method can be used if control over the query model and level is required.

See also
Query
Parameters
callingTitleCalling AE Title (us)
calledTitleCalled AE Title (them)
hostHost name or IP address (their)
portThe port number they are listening to
patientNameThe Patient Name to look for. Wildcards (* and ?) and multiple values separated by (/) can be used though not all Q/R SCP's will allow that.
patientIdThe patient ID to look for. Wildcards (* and ?) and multiple values separated by (/) can be used though not all Q/R SCP's will allow that.
studyInstanceUIDThe study instance UID to look for. Use a 0 length string to get all Patient Studies. Multi value matching can be made using the (/) character.
iThe results