pynetdicom.association.Association

class pynetdicom.association.Association(ae, mode)

Manage an Association with a peer AE.

acceptor

Representation of the association’s acceptor AE.

Type

association.ServiceUser

acse

The Association Control Service Element provider.

Type

acse.ACSE

ae

The local AE.

Type

ae.ApplicationEntity

dimse

The DICOM Message Service Element provider.

Type

dimse.DIMSEServiceProvider

dul

The DICOM Upper Layer service provider.

Type

dul.DULServiceProvider

is_aborted

True if the association has been aborted, False otherwise.

Type

bool

is_established

True if the association has been established, False otherwise.

Type

bool

is_rejected

True if the association was rejected, False otherwise.

Type

bool

is_released

True if the association has been released, False otherwise.

Type

bool

mode

The mode of the local AE, either the association ‘requestor’ or association ‘acceptor’.

Type

str

requestor

Representation of the association’s requestor AE.

Type

association.ServiceUser

__init__(ae, mode)

Create a new Association instance.

The association starts in State 1 (idle). Association negotiation won’t begin until an AssociationSocket is assigned using set_socket() and Association.start_server() is called.

Parameters

Methods

__init__(ae, mode)

Create a new Association instance.

abort()

Send an A-ABORT to the remote AE and kill the Association.

bind(event, handler)

Bind a callable handler to an event.

getName()

get_events()

Return a list of currently bound events.

get_handlers(event)

Return handlers bound to a specific event.

isAlive()

Return whether the thread is alive.

isDaemon()

is_alive()

Return whether the thread is alive.

join([timeout])

Wait until the thread terminates.

kill()

Kill the Association thread.

release()

Send an A-RELEASE request and initiate association release.

request()

Request an association with a peer.

run()

The main Association reactor.

send_c_cancel(msg_id, context_id)

Send a C-CANCEL request to the peer AE.

send_c_echo([msg_id])

Send a C-ECHO request to the peer AE.

send_c_find(dataset, query_model[, msg_id, …])

Send a C-FIND request to the peer AE.

send_c_get(dataset, query_model[, msg_id, …])

Send a C-GET request to the peer AE.

send_c_move(dataset, move_aet, query_model)

Send a C-MOVE request to the peer AE.

send_c_store(dataset[, msg_id, priority, …])

Send a C-STORE request to the peer AE.

send_n_action(dataset, action_type, …[, …])

Send an N-ACTION request message to the peer AE.

send_n_create(dataset, class_uid[, …])

Send an N-CREATE request message to the peer AE.

send_n_delete(class_uid, instance_uid[, …])

Send an N-DELETE request message to the peer AE.

send_n_event_report(dataset, event_type, …)

Send an N-EVENT-REPORT request message to the peer AE.

send_n_get(identifier_list, class_uid, …)

Send an N-GET request message to the peer AE.

send_n_set(dataset, class_uid, instance_uid)

Send an N-SET request message to the peer AE.

setDaemon(daemonic)

setName(name)

set_socket(socket)

Set the socket to use for communicating with the peer.

start()

Start the thread’s activity.

unbind(event, handler)

Unbind a callable func from an event.

Attributes

accepted_contexts

Return a list of accepted PresentationContexts.

acse_timeout

Return the ACSE timeout in seconds.

ae

Return the Association’s parent ApplicationEntity.

daemon

A boolean value indicating whether this thread is a daemon thread.

dimse_timeout

Return the DIMSE timeout in seconds.

ident

Thread identifier of this thread or None if it has not been started.

is_acceptor

Return True if the local AE is the association Acceptor.

is_requestor

Return True if the local AE is the association Requestor.

local

Return a dict with information about the local AE.

mode

Return the Association’s mode as a str.

name

A string used for identification purposes only.

native_id

Native integral thread ID of this thread, or None if it has not been started.

network_timeout

Return the network timeout in seconds.

rejected_contexts

Return a list of rejected PresentationContext.

remote

Return a dict with information about the peer AE.

abort()

Send an A-ABORT to the remote AE and kill the Association.

property accepted_contexts

Return a list of accepted PresentationContexts.

property acse_timeout

Return the ACSE timeout in seconds.

property ae

Return the Association’s parent ApplicationEntity.

bind(event, handler)

Bind a callable handler to an event.

Parameters
  • event (namedtuple) – The event to bind the function to.

  • handler (callable) – The function that will be called if the event occurs.

property daemon

A boolean value indicating whether this thread is a daemon thread.

This must be set before start() is called, otherwise RuntimeError is raised. Its initial value is inherited from the creating thread; the main thread is not a daemon thread and therefore all threads created in the main thread default to daemon = False.

The entire Python program exits when only daemon threads are left.

property dimse_timeout

Return the DIMSE timeout in seconds.

get_events()

Return a list of currently bound events.

get_handlers(event)

Return handlers bound to a specific event.

Parameters

event (namedtuple) – The event bound to the handlers.

Returns

If the event is a notification event then returns a list of callable functions bound to event, if the event is an intervention event then returns either a callable function if a handler is bound to the event or None if no handler has been bound.

Return type

callable, list of callable or None

property ident

Thread identifier of this thread or None if it has not been started.

This is a nonzero integer. See the get_ident() function. Thread identifiers may be recycled when a thread exits and another thread is created. The identifier is available even after the thread has exited.

isAlive()

Return whether the thread is alive.

This method is deprecated, use is_alive() instead.

property is_acceptor

Return True if the local AE is the association Acceptor.

is_alive()

Return whether the thread is alive.

This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.

property is_requestor

Return True if the local AE is the association Requestor.

join(timeout=None)

Wait until the thread terminates.

This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.

When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call is_alive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.

When the timeout argument is not present or None, the operation will block until the thread terminates.

A thread can be join()ed many times.

join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.

kill()

Kill the Association thread.

property local

Return a dict with information about the local AE.

property mode

Return the Association’s mode as a str.

property name

A string used for identification purposes only.

It has no semantics. Multiple threads may be given the same name. The initial name is set by the constructor.

property native_id

Native integral thread ID of this thread, or None if it has not been started.

This is a non-negative integer. See the get_native_id() function. This represents the Thread ID as reported by the kernel.

property network_timeout

Return the network timeout in seconds.

property rejected_contexts

Return a list of rejected PresentationContext.

release()

Send an A-RELEASE request and initiate association release.

property remote

Return a dict with information about the peer AE.

request()

Request an association with a peer.

A request can only be made once the Association instance has been configured for requestor mode and been assigned an AssociationSocket.

run()

The main Association reactor.

send_c_cancel(msg_id, context_id)

Send a C-CANCEL request to the peer AE.

Parameters
  • msg_id (int) – The Message ID of the C-GET/C-MOVE/C-FIND operation to be cancelled. Must be between 0 and 65535, inclusive.

  • context_id (int) – The presentation context ID of the original C-GET/C-MOVE/C-FIND service request.

send_c_echo(msg_id=1)

Send a C-ECHO request to the peer AE.

Parameters

msg_id (int, optional) – The DIMSE Message ID, must be between 0 and 65535, inclusive, (default 1).

Returns

status – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a valid response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and, depending on the returned Status value, may optionally contain additional elements (see DICOM Standard Part 7, Annex C).

The DICOM Standard Part 7, Table 9.3-13 indicates that the Status value of a C-ECHO response “shall have a value of Success”. However Section 9.1.5.1.4 indicates it may have any of the following values:

Success
0x0000 - Success
Failure
0x0122 - SOP class not supported
0x0210 - Duplicate invocation
0x0211 - Unrecognised operation
0x0212 - Mistyped argument

As the actual status depends on the peer SCP, it shouldn’t be assumed that it will be one of these.

Return type

pydicom.dataset.Dataset

Raises
  • RuntimeError – If called without an association to a peer SCP.

  • ValueError – If the association has no accepted Presentation Context for ‘Verification SOP Class’.

See also

dimse_primitives.C_ECHO(), service_class.VerificationServiceClass()

References

send_c_find(dataset, query_model, msg_id=1, priority=2)

Send a C-FIND request to the peer AE.

Yields (status, identifier) pairs.

Parameters
  • dataset (pydicom.dataset.Dataset) – The C-FIND request’s Identifier dataset. The exact requirements for the Identifier dataset are Service Class specific (see the DICOM Standard, Part 4).

  • query_model (pydicom.uid.UID or str) –

    The value to use for the C-FIND request’s (0000,0002) Affected SOP Class UID parameter, which usually corresponds to the Information Model that is to be used. If supplying a str key (deprecated, to be removed in v1.5.0) then one of the following:

    • P - 1.2.840.10008.5.1.4.1.2.1.1 - Patient Root Information Model - FIND

    • S - 1.2.840.10008.5.1.4.1.2.2.1 - Study Root Information Model - FIND

    • O - 1.2.840.10008.5.1.4.1.2.3.1 - Patient Study Only Information Model - FIND

    • W - 1.2.840.10008.5.1.4.31 - Modality Worklist Information - FIND

    • G - 1.2.840.10008.5.1.4.37.1 - General Relevant Patient Information Query

    • B - 1.2.840.10008.5.1.4.37.2 - Breast Imaging Relevant Patient Information Query

    • C - 1.2.840.10008.5.1.4.37.3 - Cardiac Relevant Patient Information Query

    • PC - 1.2.840.10008.5.1.4.41 - Product Characteristics Query Information Model - FIND

    • SA - 1.2.840.10008.5.1.4.42 - Substance Approval Query Information Model - FIND

    • H - 1.2.840.10008.5.1.4.38.2 - Hanging Protocol Information Model - FIND

    • D - 1.2.840.10008.5.1.4.20.1 - Defined Procedure Protocol Information Model - FIND

    • CP - 1.2.840.10008.5.1.4.39.2 - Color Palette Information Model - FIND

    • IG - 1.2.840.10008.5.1.4.43.2 - Generic Implant Template Information Model - FIND

    • IA - 1.2.840.10008.5.1.4.44.2 - Implant Assembly Template Information Model - FIND

    • IT - 1.2.840.10008.5.1.4.44.2 - Implant Template Group Information Model - FIND

    • PA - 1.2.840.10008.5.1.4.1.1.200.4 - Protocol Approval Information Model - FIND

  • msg_id (int, optional) – The DIMSE Message ID, must be between 0 and 65535, inclusive, (default 1).

  • priority (int, optional) –

    The C-FIND operation Priority (may not be supported by the peer), one of:

    • 0 - Medium

    • 1 - High

    • 2 - Low (default)

Yields
  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then yields an empty Dataset. If a response was received from the peer then yields a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 9.1.2.1.5 and Annex C).

    The status for the requested C-FIND operation should be one of the following values, but as the value depends on the peer this can’t be assumed:

    General C-FIND (Part 7, Section 9.1.2.1.5 and Annex C)

    Cancel
    0xFE00 - Matching terminated due to Cancel request
    Success
    0x0000 - Matching is complete: no final Identifier is supplied
    Failure
    0x0122 - SOP class not supported

    Query/Retrieve Service, Basic Worklist Management Service, Hanging Protocol Query/Retrieve Service, Defined Procedure Protocol Query/Retrieve Service, Substance Administration Query Service, Color Palette Query/Retrieve Service, Implant Template Query/Retrieve Service, Protocol Approval Query/Retrieve Service and Unified Protocol Step Service specific (DICOM Standard Part 4, Annexes C.4.1, K.4.1.1.4, U.4.1, HH, V.4.1.1.4, X, BB, II and CC):

    Failure
    0xA700 - Out of resources
    0xA900 - Identifier does not match SOP Class
    0xC000 to 0xCFFF - Unable to process
    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)

    Relevant Patient Information Query Service specific (DICOM Standard Part 4, Annex Q.2.1.1.4):

    Failure
    0xA700 - Out of resources
    0xA900 - Identifier does not match SOP Class
    0xC000 - Unable to process
    0xC100 - More than one match found
    0xC200 - Unable to support requested template
    Pending
    0xFF00 - Matches are continuing: current match is supplied and any Optional Keys were supported in the same manner as Required Keys
  • identifier (pydicom.dataset.Dataset or None) – If the status category is ‘Pending’ then the C-FIND response’s Identifier Dataset. If the status category is not ‘Pending’ this will be None. The exact contents of the response Identifier are Service Class specific (see the DICOM Standard, Part 4).

Raises
  • RuntimeError – If send_c_find is called with no established association.

  • ValueError – If no accepted Presentation Context for dataset exists or if unable to encode the Identifier dataset.

See also

dimse_primitives.C_FIND(), service_class.ColorPaletteQueryRetrieveServiceClass(), service_class.DefinedProcedureProtocolQueryRetrieveServiceClass(), service_class.HangingProtocolQueryRetrieveServiceClass(), service_class.ImplantTemplateQueryRetrieveServiceClass(), service_class.ProtocolApprovalQueryRetrieveServiceClass(), service_class.QueryRetrieveFindServiceClass(), service_class.RelevantPatientInformationQueryServiceClass(), service_class.SubstanceAdministrationQueryServiceClass(), service_class.UnifiedProcedureStepServiceClass()

References

send_c_get(dataset, query_model, msg_id=1, priority=2)

Send a C-GET request to the peer AE.

Yields (status, identifier) pairs.

A handler should be implemented and bound to evt.EVT_C_STORE prior to calling send_c_get as the peer will return any matches via a C-STORE sub-operation over the current association. In addition, SCP/SCU Role Selection Negotiation must be supported by the Association.

Parameters
  • dataset (pydicom.dataset.Dataset) – The C-GET request’s Identifier Dataset. The exact requirements for the Identifier are Service Class specific (see the DICOM Standard, Part 4).

  • query_model (pydicom.uid.UID or str) –

    The value to use for the C-GET request’s (0000,0002) Affected SOP Class UID parameter, which usually corresponds to the Information Model that is to be used. If supplying a str key (deprecated, to be removed in v1.5.0) then one of the following:

    • P - 1.2.840.10008.5.1.4.1.2.1.3 - Patient Root Information Model - GET

    • S - 1.2.840.10008.5.1.4.1.2.2.3 - Study Root Information Model - GET

    • O - 1.2.840.10008.5.1.4.1.2.3.3 - Patient Study Only Information Model - GET

    • C - 1.2.840.10008.5.1.4.1.2.4.3 - Composite Instance Root Retrieve - GET

    • CB - 1.2.840.10008.5.1.4.1.2.5.3 - Composite Instance Retrieve Without Bulk Data - GET

    • H - 1.2.840.10008.5.1.4.38.4 - Hanging Protocol Information Model - GET

    • D - 1.2.840.10008.5.1.4.20.3 - Defined Procedure Protocol Information Model - GET

    • CP - 1.2.840.10008.5.1.4.39.4 - Palette Color Information Model - GET

    • IG - 1.2.840.10008.5.1.4.43.4 - Generic Implant Template Information Model - GET

    • IA - 1.2.840.10008.5.1.4.44.4 - Implant Assembly Template Information Model - GET

    • IT - 1.2.840.10008.5.1.4.44.4 - Implant Template Group Information Model - GET

    • PA - 1.2.840.10008.5.1.4.1.1.200.6 - Protocol Approval Information Model - GET

  • msg_id (int, optional) – The DIMSE Message ID, must be between 0 and 65535, inclusive, (default 1).

  • priority (int, optional) –

    The C-GET operation Priority (may not be supported by the peer), one of:

    • 0 - Medium

    • 1 - High

    • 2 - Low (default)

Yields
  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then yields an empty Dataset. If a response was received from the peer then yields a Dataset containing at least a (0000,0900) Status element, and depending on the returned value may optionally contain additional elements (see DICOM Standard Part 7, Section 9.1.2.1.5 and Annex C).

    The status for the requested C-GET operation should be one of the following values, but as the value depends on the peer this can’t be assumed:

    General C-GET (DICOM Standard Part 7, Section 9.1.3 and Annex C)

    Success
    0x0000 - Sub-operations complete: no failures or warnings
    Failure
    0x0122 - SOP class not supported
    0x0124 - Not authorised
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument

    Query/Retrieve Service, Hanging Protocol Query/Retrieve Service, Defined Procedure Protocol Query/Retrieve Service, Color Palette Query/Retrieve Service, Implant Template Query/Retrieve Service and Protocol Approval Query/Retrieve Service specific (DICOM Standard Part 4, Annexes C.4.3, Y.C.4.2.1.4, Z.4.2.1.4, U.4.3, X, BB, HH and II):

    Pending
    0xFF00 - Sub-operations are continuing
    Cancel
    0xFE00 - Sub-operations terminated due to Cancel indication
    Failure
    0xA701 - Out of resources: unable to calculate number of matches
    0xA702 - Out of resources: unable to perform sub-operations
    0xA900 - Identifier does not match SOP class
    0xAA00 - None of the frames requested were found in the SOP instance
    0xAA01 - Unable to create new object for this SOP class
    0xAA02 - Unable to extract frames
    0xAA03 - Time-based request received for a non-time-based original SOP Instance
    0xAA04 - Invalid request
    0xC000 to 0xCFFF - Unable to process
    Warning
    0xB000 - Sub-operations completed: one or more failures or warnings
  • identifier (pydicom.dataset.Dataset or None) – If the status category is ‘Pending’ or ‘Success’ then yields None. If the status category is ‘Warning’, ‘Failure’ or ‘Cancel’ then yields a Dataset which should contain an (0008,0058) Failed SOP Instance UID List element, however this is not guaranteed and may instead be an empty Dataset.

Raises
  • RuntimeError – If send_c_get is called with no established association.

  • ValueError – If no accepted Presentation Context for dataset exists or if unable to encode the Identifier dataset.

See also

service_class.QueryRetrieveGetServiceClass(), service_class.HangingProtocolQueryRetrieveServiceClass(), service_class.DefinedProcedureProtocolQueryRetrieveServiceClass(), service_class.ColorPaletteQueryRetrieveServiceClass(), service_class.ImplantTemplateQueryRetrieveServiceClass(), service_class.ProtocolApprovalQueryRetrieveServiceClass(), dimse_primitives.C_GET()

References

send_c_move(dataset, move_aet, query_model, msg_id=1, priority=2)

Send a C-MOVE request to the peer AE.

Yields (status, identifier) pairs.

The peer will attempt to start a new association with the AE with AE Title move_aet and hence must be known to the SCP. Once the association has been established it will use the C-STORE service to send any matching datasets.

Parameters
  • dataset (pydicom.dataset.Dataset) – The C-MOVE request’s Identifier Dataset. The exact requirements for the Identifier are Service Class specific (see the DICOM Standard, Part 4).

  • move_aet (bytes) – The value of the Move Destination parameter for the C-MOVE request, should be the AE title of the Storage SCP for the C-STORE sub-operations performed by the peer.

  • query_model (pydicom.uid.UID or str) –

    The value to use for the C-MOVE request’s (0000,0002) Affected SOP Class UID parameter, which usually corresponds to the Information Model that is to be used. If supplying a str key (deprecated, to be removed in v1.5.0) then one of the following:

    • P - 1.2.840.10008.5.1.4.1.2.1.2 - Patient Root Information Model - MOVE

    • S - 1.2.840.10008.5.1.4.1.2.2.2 - Study Root Information Model - MOVE

    • O - 1.2.840.10008.5.1.4.1.2.3.2 - Patient Study Only Information Model - MOVE

    • C - 1.2.840.10008.5.1.4.1.2.4.2 - Composite Instance Root Retrieve - MOVE

    • H - 1.2.840.10008.5.1.4.38.3 - Hanging Protocol Information Model - MOVE

    • D - 1.2.840.10008.5.1.4.20.2 - Defined Procedure Protocol Information Model - MOVE

    • CP - 1.2.840.10008.5.1.4.39.3 - Color Palette Information Model - MOVE

    • IG - 1.2.840.10008.5.1.4.43.3 - Generic Implant Template Information Model - MOVE

    • IA - 1.2.840.10008.5.1.4.44.3 - Implant Assembly Template Information Model - MOVE

    • IT - 1.2.840.10008.5.1.4.44.3 - Implant Template Group Information Model - MOVE

    • PA - 1.2.840.10008.5.1.4.1.1.200.5 - Protocol Approval Information Model - MOVE

  • msg_id (int, optional) – The DIMSE Message ID, must be between 0 and 65535, inclusive, (default 1).

  • priority (int, optional) –

    The value of the Priority parameter (if supported by the peer), one of:

    • 0 - Medium

    • 1 - High

    • 2 - Low (default)

Yields
  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then yields an empty Dataset. If a response was received from the peer then yields a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see DICOM Standard Part 7, Section 9.1.4 and Annex C).

    The status for the requested C-MOVE operation should be one of the following values, but as the value depends on the peer this can’t be assumed:

    General C-MOVE (DICOM Standard Part 7, 9.1.4.1.7 and Annex C)

    Cancel
    0xFE00 - Sub-operations terminated due to Cancel indication
    Success
    0x0000 - Sub-operations complete: no failures
    Failure
    0x0122 - SOP class not supported

    Query/Retrieve Service, Hanging Protocol Query/Retrieve Service, Defined Procedure Protocol Query/Retrieve Service, Color Palette Query/Retrieve Service , Implant Template Query/Retreive Service and Protocol Approval Query/Retrieve Service specific (DICOM Standard Part 4, Annexes C, U, Y, X, BB and HH):

    Failure
    0xA701 - Out of resources: unable to calculate number of matches
    0xA702 - Out of resources: unable to perform sub-operations
    0xA801 - Move destination unknown
    0xA900 - Identifier does not match SOP Class
    0xAA00 - None of the frames requested were found in the SOP instance
    0xAA01 - Unable to create new object for this SOP class
    0xAA02 - Unable to extract frames
    0xAA03 - Time-based request received for a non-time-based original SOP Instance
    0xAA04 - Invalid request
    0xC000 to 0xCFFF - Unable to process
    Pending
    0xFF00 - Sub-operations are continuing
    Warning
    0xB000 - Sub-operations complete: one or more failures
  • identifier (pydicom.dataset.Dataset or None) – If the status category is ‘Pending’ or ‘Success’ then yields None. If the status category is ‘Warning’, ‘Failure’ or ‘Cancel’ then yields a Dataset which should contain an (0008,0058) Failed SOP Instance UID List element, however this is not guaranteed and may instead be an empty Dataset.

See also

dimse_primitives.C_MOVE(), service_class.QueryRetrieveMoveServiceClass(), service_class.HangingProtocolQueryRetrieveServiceClass(), service_class.ColorPaletteQueryRetrieveServiceClass(), service_class.ImplantTemplateQueryRetrieveServiceClass(), service_class.ProtocolApprovalQueryRetrieveServiceClass()

References

send_c_store(dataset, msg_id=1, priority=2, originator_aet=None, originator_id=None)

Send a C-STORE request to the peer AE.

Parameters
  • dataset (pydicom.dataset.Dataset) – The DICOM dataset to send to the peer.

  • msg_id (int, optional) – The DIMSE Message ID, must be between 0 and 65535, inclusive, (default 1).

  • priority (int, optional) –

    The C-STORE operation Priority (may not be supported by the peer), one of:

    • 0 - Medium

    • 1 - High

    • 2 - Low (default)

  • originator_aet (bytes, optional) – The value of the Move Originator Application Entity Title parameter for the C-STORE request. This is the AE title of the peer that invoked the C-MOVE operation for which this C-STORE sub-operation is being performed (default None).

  • originator_id (int, optional) – The value of the Move Originator Message ID parameter for the C-STORE request. This is the original Message ID parameter value for the C-MOVE request primitive for which the C-STORE sub-operation is being performed (default None).

Returns

status – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a valid response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and, depending on the returned value, may optionally contain additional elements (see DICOM Standard Part 7, Annex C).

The status for the requested C-STORE operation should be one of the following, but as the value depends on the peer SCP this can’t be assumed:

General C-STORE (DICOM Standard Part 7, 9.1.1.1.9 and Annex C):

Success
0x0000 - Success
Failure
0x0117 - Invalid SOP instance
0x0122 - SOP class not supported
0x0124 - Not authorised
0x0210 - Duplicate invocation
0x0211 - Unrecognised operation
0x0212 - Mistyped argument

Storage Service and Non-Patient Object Storage Service specific (DICOM Standard Part 4, Annexes B.2.3 and GG):

Failure
0xA700 to 0xA7FF - Out of resources
0xA900 to 0xA9FF - Data set does not match SOP class
0xC000 to 0xCFFF - Cannot understand
Warning
0xB000 - Coercion of data elements
0xB006 - Element discarded
0xB007 - Data set does not match SOP class

Non-Patient Object Service Class specific (DICOM Standard Part 4, Annex GG.4.2)

Failure
0xA700 - Out of resources
0xA900 - Data set does not match SOP class
0xC000 - Cannot understand

Return type

pydicom.dataset.Dataset

Raises
  • RuntimeError – If send_c_store is called with no established association.

  • AttributeError – If dataset is missing (0008,0016) SOP Class UID, (0008,0018) SOP Instance UID elements or the (0002,0010) Transfer Syntax UID file meta information element.

  • ValueError – If no accepted Presentation Context for dataset exists or if unable to encode the dataset.

See also

dimse_primitives.C_STORE(), service_class.StorageServiceClass(), service_class.NonPatientObjectStorageServiceClass()

References

  • DICOM Standard Part 4, Annex B

  • DICOM Standard Part 4, Annex GG

  • DICOM Standard Part 7, Sections 9.1.1, 9.3.1 and Annex C

send_n_action(dataset, action_type, class_uid, instance_uid, msg_id=1, meta_uid=None)

Send an N-ACTION request message to the peer AE.

Parameters
  • dataset (pydicom.dataset.Dataset or None) – The dataset that will be sent as the Action Information parameter in the N-ACTION request, or None if not required.

  • action_type (int) – The value of the request’s (0000,1008) Action Type ID parameter.

  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0003) Requested SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,1001) Requested SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 9.1.2.1.5 and Annex C).

    General N-ACTION (DICOM Standard Part 7, Section 10.1.4 and Annex C)

    Success
    0x0000 - Successful operation
    Failure
    0x0110 - Processing failure
    0x0112 - No such SOP Instance
    0x0114 - No such argument
    0x0115 - Invalid argument value
    0x0117 - Invalid object instance
    0x0118 - No such SOP Class
    0x0119 - Class-Instance conflict
    0x0123 - No such action
    0x0124 - Not authorised
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument
    0x0213 - Resource limitation
  • action_reply (pydicom.dataset.Dataset or None) – If the status category is ‘Success’ or ‘Warning’ then a Dataset containing attributes corresponding to those supplied in the Action Reply. Because Action Reply is optional the returned Dataset may be empty.

    If the status category is ‘Failure’ or if the peer timed-out, aborted, or sent an invalid response then returns None.

See also

dimse_primitives.N_ACTION()

References

send_n_create(dataset, class_uid, instance_uid=None, msg_id=1, meta_uid=None)

Send an N-CREATE request message to the peer AE.

Parameters
  • dataset (pydicom.dataset.Dataset or None) – The dataset that will be sent as the Attribute List parameter in the N-CREATE request, or None if not required.

  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0002) Affected SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID, optional) – The UID to be sent for the request’s (0000,1000) Affected SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 9.1.2.1.5 and Annex C).

    General N-CREATE (DICOM Standard Part 7, Section 10.1.5 and Annex C)

    Success
    0x0000 - Successful operation
    Failure
    0x0110 - Processing failure
    0x0112 - No such SOP Instance
    0x0114 - No such argument
    0x0115 - Invalid argument value
    0x0117 - Invalid object instance
    0x0118 - No such SOP Class
    0x0119 - Class-Instance conflict
    0x0123 - No such action
    0x0124 - Not authorised
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument
    0x0213 - Resource limitation

    Print Management Service specific (DICOM Standard Part 4, Annex H.4.1.2.1.2, H.4.2.2.1.2 and H.4.9.2.1.2):

    Warning
    0xB600 - Memory allocation not supported
    0xB605 - Requested Min Density or Max Density outside of printer’s operating range. The printer will use its respective minimum or maximum density value instead
    Failure
    0xC616 - There is an existing Film Box that has not been printed and N-ACTION at the Film Session level is not supported. A new Film Box will not be created when a previous Film Box has not been printed

    Media Creation Management Service specific (DICOM Standard Part 4, Annex S.3.2.1.4):

    Failure
    0xA510 - Failed: an initiate media creation action has already been received for this SOP Instance

    Unified Procedure Step Service specific (DICOM Standard Part 4, Annex CC.2.5.4):

    Warning
    0xB300 - THE UPS was created with modifications
    Failure
    0xC309 - The provided value of UPS State was not ‘SCHEDULED’

    RT Machine Verification Service specific (DICOM Standard Part 4, Annex DD.3.2.1.2):

    Failure
    0xC221 - The Referenced Fraction Group Number does not exist in the referenced plan
    0xC222 - No beams exist within the referenced fraction group
    0xC223 - SCU already verifying and cannot currently process this request
    0xC227 - No such object instance - Referenced RT Plan not found
  • attribute_list (pydicom.dataset.Dataset or None) – If the status category is ‘Success’ or ‘Warning’ then a Dataset containing attributes corresponding to those supplied in the Attribute List. Because Attribute List is optional the returned Dataset may be empty.

    If the status category is ‘Failure’ or if the peer timed-out, aborted, or sent an invalid response then returns None.

See also

dimse_primitives.N_CREATE()

References

send_n_delete(class_uid, instance_uid, msg_id=1, meta_uid=None)

Send an N-DELETE request message to the peer AE.

Parameters
  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0003) Requested SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,1001) Requested SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns

status – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 9.1.2.1.5 and Annex C).

General N-DELETE (DICOM Standard Part 7, Section 10.1.6 and Annex C)

Success
0x0000 - Successful operation
Failure
0x0110 - Processing failure
0x0112 - No such SOP Instance
0x0117 - Invalid object instance
0x0118 - No such SOP Class
0x0119 - Class-Instance conflict
0x0124 - Not authorised
0x0210 - Duplicate invocation
0x0211 - Unrecognised operation
0x0212 - Mistyped argument
0x0213 - Resource limitation

Return type

pydicom.dataset.Dataset

See also

dimse_primitives.N_DELETE()

References

send_n_event_report(dataset, event_type, class_uid, instance_uid, msg_id=1, meta_uid=None)

Send an N-EVENT-REPORT request message to the peer AE.

Parameters
  • dataset (pydicom.dataset.Dataset or None) – The dataset that will be sent as the Event Information parameter in the N-EVENT-REPORT request, if no Event Information parameter is needed then None.

  • event_type (int) – The value to be sent for the request’s (0000,1002) Event Type ID parameter.

  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0003) Affected SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,1000) Affected SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 9.1.2.1.5 and Annex C).

    General N-EVENT-REPORT (DICOM Standard Part 7, Section 10.1.1 and Annex C)

    Success
    0x0000 - Successful operation
    Failure
    0x0110 - Processing failure
    0x0112 - No such SOP Instance
    0x0113 - No such event type
    0x0114 - No such argument
    0x0115 - Invalid argument value
    0x0117 - Invalid object instance
    0x0118 - No such SOP Class
    0x0119 - Class-Instance conflict
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument
    0x0213 - Resource limitation
  • event_reply (pydicom.dataset.Dataset or None) – If the status category is ‘Success’ or ‘Warning’ then a Dataset containing attributes corresponding to those supplied in the Event Reply. Because Event Reply is optional the returned Dataset may be empty.

    If the status category is ‘Failure’ or if the peer timed-out, aborted, or sent an invalid response then returns None.

See also

dimse_primitives.N_EVENT_REPORT()

References

send_n_get(identifier_list, class_uid, instance_uid, msg_id=1, meta_uid=None)

Send an N-GET request message to the peer AE.

Parameters
  • identifier_list (list of pydicom.tag.Tag) – A list of DICOM Data Element tags to be sent for the request’s (0000,1005) Attribute Identifier List parameter. Should either be a list of pydicom Tag objects or a list of values that is acceptable for creating pydicom Tag objects.

  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0003) Requested SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,1001) Requested SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 9.1.2.1.5 and Annex C).

    General N-GET (DICOM Standard Part 7, Section 10.1.2 and Annex C)

    Success
    0x0000 - Successful operation
    Warning
    0x0107 - Attribute list error
    Failure
    0x0110 - Processing failure
    0x0112 - No such SOP Instance
    0x0117 - Invalid object instance
    0x0118 - No such SOP Class
    0x0119 - Class-Instance conflict
    0x0122 - SOP class not supported
    0x0124 - Not authorised
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument
    0x0213 - Resource limitation

    Modality Performed Procedure Step Management Service and Media Creation Management Service specific (DICOM Standard Part 4, Annex F.8.2.1.4 and Annex S.3.2.4.4):

    Warning
    0x0001 - Requested optional Attributes are not supported

    Unified Procedure Step Service specific (DICOM Standard Part 4, Annex CC.2.7.4):

    Warning
    0x0001 - Requested optional Attributes are not supported
    Failure
    0xC307 - Specified SOP Instance UID doesn’t exist or is not a UPS Instance managed by this SCP

    RT Machine Verification Service specific (DICOM Standard Part 4, Annex DD.3.2.2.3):

    Failure
    0xC112 - Applicable Machine Verification Instance not found
  • attribute_list (pydicom.dataset.Dataset or None) – If the status category is ‘Success’ or ‘Warning’ then a Dataset containing attributes corresponding to those supplied in the Attribute List. Because Attribute List is optional the returned Dataset may be empty.

    If the status category is ‘Failure’ or if the peer timed-out, aborted, or sent an invalid response then returns None.

See also

dimse_primitives.N_GET(), service_class.DisplaySystemManagementServiceClass()

References

send_n_set(dataset, class_uid, instance_uid, msg_id=1, meta_uid=None)

Send an N-SET request message to the peer AE.

Parameters
  • dataset (pydicom.dataset.Dataset) – The dataset that will be sent as the Modification List parameter in the N-SET request.

  • class_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,0003) Requested SOP Class UID parameter.

  • instance_uid (pydicom.uid.UID) – The UID to be sent for the request’s (0000,1001) Requested SOP Instance UID parameter.

  • msg_id (int, optional) – The request’s Message ID parameter value, must be between 0 and 65535, inclusive, (default 1).

  • meta_uid (pydicom.uid.UID, optional) – If the service class operates under a presentation context negotiated using a Meta SOP Class rather than a standard SOP Class (such as with Print Management service class and its Basic Grayscale Print Management Meta SOP Class) then this value will be used to determine the corresponding presentation context.

Returns

  • status (pydicom.dataset.Dataset) – If the peer timed out, aborted or sent an invalid response then returns an empty Dataset. If a response was received from the peer then returns a Dataset containing at least a (0000,0900) Status element, and depending on the returned value, may optionally contain additional elements (see the DICOM Standard, Part 7, Section 9.1.2.1.5 and Annex C).

    General N-SET (DICOM Standard Part 7, Section 10.1.3 and Annex C)

    Success
    0x0000 - Successful operation
    Warning
    0x0107 - Attribute list error
    0x0116 - Attribute value out of range
    Failure
    0x0105 - No such attribute
    0x0106 - Invalid attribute value
    0x0110 - Processing failure
    0x0112 - No such SOP Instance
    0x0117 - Invalid object instance
    0x0118 - No such SOP Class
    0x0119 - Class-Instance conflict
    0x0121 - Missing attribute value
    0x0122 - SOP class not supported
    0x0124 - Not authorised
    0x0210 - Duplicate invocation
    0x0211 - Unrecognised operation
    0x0212 - Mistyped argument
    0x0213 - Resource limitation

    Print Management Service specific (DICOM Standard Part 4, Annex H.4.1.2.1.2, H.4.2.2.1.2, H.4.3.1.2.1.2 and H.4.3.2.2.1.2):

    Warning
    0xB600 - Memory allocation not supported
    0xB604 - Image size larger than image box size, the image has been demagnified
    0xB605 - Requested Min Density or Max Density outside of printer’s operating range. The printer will use its respective minimum or maximum density value instead
    0xB609 - Image size is larger than the Image Box. The Image has been cropped to fit
    0xB60A - Image size or Combined Print Image size is larger than the Image Box size. The Image or Combined Print Image has been decimated to fit
    Failure
    0xC603 - Image size is larger than image box size
    0xC605 - Insufficient memory in printer to store the image
    0xC613 - Combined Print Image size is larger than the Image Box size
    0xC616 - There is an existing Film Box that has not been printed and N-ACTION at the Film Session level is not supported. A new Film Box will not be created when a previous Film Box has not been printed

    Unified Procedure Step Service specific (DICOM Standard Part 4, Annex CC.2.6.4):

    Warning
    0x0001 - Requested optional attributes are not supported
    0xB305 - Coerced invalid values to valid values
    Failure
    0xC300 - The UPS may no longer be updated
    0xC301 - The correct Transaction UID was not provided
    0xC307 - Specified SOP Instance UID does not exist or is not a UPS Instance managed by this SCP
    0xC310 - The UPS is not in the ‘IN PROGRESS’ state

    RT Machine Verification Service specific (DICOM Standard Part 4, Annex DD.3.2.1.2):

    Failure
    0xC224 - Reference Beam Number not found within the referenced Fraction Group
    0xC225 - Referenced device or accessory not supported
    0xC226 - Referenced device or accessory not found with the referenced beam
  • attribute_list (pydicom.dataset.Dataset or None) – If the status category is ‘Success’ or ‘Warning’ then a Dataset containing attributes corresponding to those supplied in the Attribute List. Because Attribute List is optional the returned Dataset may be empty.

    If the status category is ‘Failure’ or if the peer timed-out, aborted, or sent an invalid response then returns None.

See also

dimse_primitives.N_SET()

References

set_socket(socket)

Set the socket to use for communicating with the peer.

Parameters

socket (transport.AssociationSocket) – The socket to use.

Raises

RuntimeError – If the Association already has a socket set.

start()

Start the thread’s activity.

It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

This method will raise a RuntimeError if called more than once on the same thread object.

unbind(event, handler)

Unbind a callable func from an event.

Parameters
  • event (namedtuple) – The event to unbind the function from.

  • handler (callable) – The function that will no longer be called if the event occurs.