pynetdicom._handlers.doc_handle_find

pynetdicom._handlers.doc_handle_find(event: Event, *args: Sequence[Any]) → Iterator[Tuple[int | Dataset, Dataset | None]][source]

Documentation for handlers bound to evt.EVT_C_FIND.

User implementation of this event handler is required if one or more services that use C-FIND are to be supported. If a handler is not implemented and bound to evt.EVT_C_FIND then the C-FIND request will be responded to using a Status value of 0xC311 - Failure.

Yields (status, identifier) pairs, where status is either an int or pydicom Dataset containing a (0000,0900) Status element and identifier is a C-FIND Identifier Dataset.

Event

evt.EVT_C_FIND

Supported Service Classes

Status

Success
0x0000 - Success
Failure
0xA700 - Out of resources
0xA900 - Identifier does not match SOP class
0xC000 to 0xCFFF - Unable to process
Cancel
0xFE00 - Matching terminated due to Cancel request
Pending
0xFF00 - Matches are continuing: current match is supplied and any Optional Keys were supported in the same manner as Required Keys
0xFF01 - Matches are continuing: warning that one or more Optional Keys were not supported for existence and/or matching for this Identifier
Parameters:

  • event (events.Event) –

    The event representing a service class receiving a C-FIND request message. Event attributes are:

    Event properties are:

    • identifier: the decoded Dataset contained within the C-FIND request’s Identifier parameter. Because pydicom uses a deferred read when decoding data, if the decode fails the returned Dataset will only raise an exception at the time of use.

    • is_cancelled: returns True if a C-CANCEL request has been received, False otherwise. If a C-CANCEL is received then the handler should yield (0xFE00, None) and return.

    • message_id: the C-FIND request’s Message ID as int.

  • args – If the handler was bound to the event using bind(event, handler, args) or by passing evt_handlers=[(event, handler, args), ...], where args is a list then there will be one or more optional extra parameters matching the contents of args.

Yields:

  • status (pydicom.dataset.Dataset or int) – The status returned to the peer AE in the C-FIND response. Must be a valid C-FIND status vuale for the applicable Service Class as either an int or a Dataset object containing (at a minimum) a (0000,0900) Status element. If returning a Dataset object then it may also contain optional elements related to the Status (as in DICOM Standard, Part 7, Annex C).

  • identifier (pydicom.dataset.Dataset or None) – If the status category is ‘Pending’ then the Identifier Dataset for a matching SOP Instance. The exact requirements for the C-FIND response Identifier are Service Class specific (see the DICOM Standard, Part 4).

    If the status category is ‘Failure’ or ‘Cancel’ then yield None.

    If the status category is ‘Success’ then yield None, however yielding a final ‘Success’ status is not required and will be ignored if necessary.

See also

send_c_find(), C_FIND, QueryRetrieveServiceClass, BasicWorklistManagementServiceClass, RelevantPatientInformationQueryServiceClass, SubstanceAdministrationQueryServiceClass, HangingProtocolQueryRetrieveServiceClass, DefinedProcedureProtocolQueryRetrieveServiceClass, ColorPaletteQueryRetrieveServiceClass, ImplantTemplateQueryRetrieveServiceClass, UnifiedProcedureStepServiceClass, ProtocolApprovalQueryRetrieveServiceClass

References