pynetdicom.ae.ApplicationEntity

class pynetdicom.ae.ApplicationEntity(ae_title=b'PYNETDICOM', port=0)[source][source]

Represents a DICOM Application Entity (AE).

An AE may be a Service Class Provider (SCP), a Service Class User (SCU) or both.

acse_timeout

The maximum amount of time (in seconds) to wait for association related messages. A value of None means no timeout. (default: 60)

Type:int or float or None
active_associations

The currently active associations between the local and peer AEs.

Type:list of association.Association
address

The local AE’s TCP/IP address.

Type:str
ae_title

The local AE’s AE title.

Type:bytes
bind_addr

The network interface to listen to (default: all available network interfaces on the machine).

Type:str
client_socket

The socket used for connections with peer AEs

Type:socket.socket
dimse_timeout

The maximum amount of time (in seconds) to wait for DIMSE related messages. A value of None means no timeout. (default: None)

Type:int or float or None
network_timeout

The maximum amount of time (in seconds) to wait for network messages. A value of None means no timeout. (default: None)

Type:int or float or None
maximum_associations

The maximum number of simultaneous associations (default: 2)

Type:int
maximum_pdu_size

The maximum PDU receive size in bytes. A value of 0 means there is no maximum size (default: 16382)

Type:int
port

The local AE’s listen port number when acting as an SCP or connection port when acting as an SCU. A value of 0 indicates that the operating system should choose the port.

Type:int
require_calling_aet

If not empty bytes, the calling AE title must match require_calling_aet (SCP only).

Type:bytes
require_called_aet

If not empty bytes the called AE title must match required_called_aet (SCP only).

Type:bytes

Examples

SCP

To use AE as an SCP, you need to specify:

  • The listen port number that SCUs can use to send Association requests and DIMSE messages
  • The Presentation Contexts that the SCP supports.

If the SCP is being used for any DICOM Service Classes other than the Verification Service Class you also need to implement one or more of the callbacks corresponding to the DIMSE-C services (on_c_store, on_c_find, on_c_get, on_c_move).

The SCP can then be started using ApplicationEntity.start()

C-STORE SCP Example

from pynetdicom import AE, StoragePresentationContexts

# Create the AE and specify the listen port
ae = AE(port=11112)

# Set the supported Presentation Contexts
ae.supported_contexts = StoragePresentationContexts

# Define the callback for receiving a C-STORE request
def on_c_store(dataset, context, info):
    # Insert your C-STORE handling code here

    # Must return a valid C-STORE status - 0x0000 is Success
    return 0x0000

ae.on_c_store = on_c_store

# Start the SCP
ae.start()

SCU

To use AE as an SCU you only need to specify the Presentation Contexts that the SCU is requesting for support by the SCP. You can then call ApplicationEntity.associate(addr, port) where addr and port are the TCP/IP address and the listen port number of the peer SCP, respectively.

Once the Association is established you can then request the use of the peer’s DIMSE-C services.

C-ECHO SCU Example

from pynetdicom import AE, VerificationPresentationContexts

# Create the AE with an AE Title 'MYAE'
ae = AE(ae_title=b'MYAE')

# Specify which SOP Classes are supported as an SCU
ae.requested_contexts = VerificationPresentationContexts

# Request an association with a peer SCP
assoc = ae.associate('192.168.2.1', 104)

if assoc.is_established:
    # Send a C-ECHO request to the peer
    status = assoc.send_c_echo()

    # Release the association
    assoc.release()
__init__(ae_title=b'PYNETDICOM', port=0)[source][source]

Create a new Application Entity.

Parameters:
  • ae_title (bytes, optional) – The AE title of the Application Entity (default: b'PYNETDICOM')
  • port (int, optional) – The port number to listen for association requests when acting as an SCP and to use when requesting an association as an SCU. When set to 0 the OS will use the first available port (default 0).

Methods

__init__([ae_title, port]) Create a new Application Entity.
add_requested_context(abstract_syntax[, …]) Add a Presentation Context to be proposed when sending Association requests.
add_supported_context(abstract_syntax[, …]) Add a supported presentation context.
associate(addr, port[, contexts, ae_title, …]) Send an association request to a remote AE.
cleanup_associations() Remove dead associations.
on_association_aborted([primitive]) Callback for when an association is aborted.
on_association_accepted(primitive) Callback for when an association is accepted.
on_association_rejected(primitive) Callback for when an association is rejected.
on_association_released([primitive]) Callback for when an association is released.
on_association_requested(primitive) Callback for an association is requested.
on_async_ops_window(nr_invoked, nr_performed) Callback for when an Asynchronous Operations Window Negotiation item is include in the association request.
on_c_echo(context, info) Callback for when a C-ECHO request is received.
on_c_find(dataset, context, info) Callback for when a C-FIND request is received.
on_c_find_cancel() Callback for when a C-FIND-CANCEL request is received.
on_c_get(dataset, context, info) Callback for when a C-GET request is received.
on_c_get_cancel() Callback for when a C-GET-CANCEL request is received.
on_c_move(dataset, move_aet, context, info) Callback for when a C-MOVE request is received.
on_c_move_cancel() Callback for when a C-MOVE-CANCEL request is received.
on_c_store(dataset, context, info) Callback for when a C-STORE request is received.
on_make_connection() Callback for a connection is made.
on_n_action(dataset, context, info) Callback for when a N-ACTION is received.
on_n_create(dataset, context, info) Callback for when a N-CREATE is received.
on_n_delete(context, info) Callback for when a N-DELETE is received.
on_n_event_report(dataset, context, info) Callback for when a N-EVENT-REPORT is received.
on_n_get(attr, context, info) Callback for when an N-GET request is received.
on_n_set(dataset, context, info) Callback for when a N-SET is received.
on_receive_connection() Callback for a connection is received.
on_sop_class_common_extended(items) Callback for when one or more SOP Class Common Extended Negotiation items are included in the association request.
on_sop_class_extended(app_info) Callback for when one or more SOP Class Extended Negotiation items are included in the association request.
on_user_identity(user_id_type, …) Callback for when a user identity negotiation item is included with the association request.
quit() Stop the SCP.
remove_requested_context(abstract_syntax[, …]) Remove a requested Presentation Context.
remove_supported_context(abstract_syntax[, …]) Remove a supported presentation context.
start() Start the AE as an SCP.
stop() Stop the SCP.

Attributes

acse_timeout Return the ACSE timeout value.
ae_title Get the AE title.
dimse_timeout Get the DIMSE timeout.
implementation_class_uid Return the current Implementation Class UID.
implementation_version_name Return the current Implementation Version Name.
maximum_associations Return the number of maximum associations as int.
maximum_pdu_size Return the maximum PDU size accepted by the AE as int.
network_timeout Get the network timeout.
port Return the port number as an int.
requested_contexts Return a list of the requested PresentationContext items.
require_called_aet Return the required called AE title as a length 16 bytes.
require_calling_aet Return the required calling AE title as a length 16 bytes.
supported_contexts Return a list of the supported PresentationContexts items.
acse_timeout

Return the ACSE timeout value.

add_requested_context(abstract_syntax, transfer_syntax=['1.2.840.10008.1.2', '1.2.840.10008.1.2.1', '1.2.840.10008.1.2.2'])[source][source]

Add a Presentation Context to be proposed when sending Association requests.

When an SCU sends an Association request to a peer it includes a list of presentation contexts it would like the peer to support [1]. This method adds a single PresentationContext to the list of the SCU’s requested contexts.

Only 128 presentation contexts can be included in the association request [2]. Multiple presentation contexts may be requested with the same abstract syntax.

To remove a requested context or one or more of its transfer syntaxes see the remove_requested_context method.

Parameters:
  • abstract_syntax (str or pydicom.uid.UID) – The abstract syntax of the presentation context to request.
  • transfer_syntax (str/pydicom.uid.UID or list of str/pydicom.uid.UID) – The transfer syntax(es) to request (default: Implicit VR Little Endian, Explicit VR Little Endian, Explicit VR Big Endian).
Raises:

ValueError – If 128 requested presentation contexts have already been added.

Examples

Add a requested presentation context for Verification SOP Class with the default transfer syntaxes by using its UID value.

>>> from pynetdicom import AE
>>> ae = AE()
>>> ae.add_requested_context('1.2.840.10008.1.1')
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Little Endian
    =Explicit VR Big Endian

Add a requested presentation context for Verification SOP Class with the default transfer syntaxes by using the inbuilt VerificationSOPClass object.

>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_requested_context(VerificationSOPClass)

Add a requested presentation context for Verification SOP Class with a transfer syntax of Implicit VR Little Endian.

>>> from pydicom.uid import ImplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_requested_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian

Add two requested presentation contexts for Verification SOP Class using different transfer syntaxes for each.

>>> from pydicom.uid import (
...     ImplicitVRLittleEndian, ExplicitVRLittleEndian, ExplicitVRBigEndian
... )
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_requested_context(VerificationSOPClass,
...                          [ImplicitVRLittleEndian, ExplicitVRBigEndian])
>>> ae.add_requested_context(VerificationSOPClass, ExplicitVRLittleEndian)
>>> len(ae.requested_contexts)
2
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Big Endian
>>> print(ae.requested_contexts[1])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Explicit VR Little Endian

References

[1]DICOM Standard, Part 8, Section 7.1.1.13
[2]DICOM Standard, Part 8, Table 9-18
add_supported_context(abstract_syntax, transfer_syntax=['1.2.840.10008.1.2', '1.2.840.10008.1.2.1', '1.2.840.10008.1.2.2'], scu_role=None, scp_role=None)[source][source]

Add a supported presentation context.

When an Association request is received from a peer it supplies a list of presentation contexts that it would like the SCP to support. This method adds a PresentationContext to the list of the SCP’s supported contexts.

Where the abstract syntax is already supported the transfer syntaxes will be extended by the those supplied in transfer_syntax. To remove a supported context or one or more of its transfer syntaxes see the remove_supported_context method.

Parameters:
  • abstract_syntax (str, pydicom.uid.UID or sop_class.SOPClass) – The abstract syntax of the presentation context to be supported.
  • transfer_syntax (str/pydicom.uid.UID or list of str/pydicom.uid.UID) – The transfer syntax(es) to support (default: Implicit VR Little Endian, Explicit VR Little Endian, Explicit VR Big Endian).
  • scu_role (bool or None, optional) –

    If the association requestor includes an SCP/SCU Role Selection Negotiation item for this context then:

    • If None then ignore the proposal (if either scp_role or scu_role is None then both are assumed to be) and use the default roles.
    • If True accept the proposed SCU role
    • If False reject the proposed SCU role
  • scp_role (bool or None, optional) –

    If the association requestor includes an SCP/SCU Role Selection Negotiation item for this context then:

    • If None then ignore the proposal (if either scp_role or scu_role is None then both are assumed to be) and use the default roles.
    • If True accept the proposed SCP role
    • If False reject the proposed SCP role

Examples

Add support for presentation contexts with an abstract syntax of Verification SOP Class and the default transfer syntaxes by using its UID value.

>>> from pynetdicom import AE
>>> ae = AE()
>>> ae.add_supported_context('1.2.840.10008.1.1')
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Little Endian
    =Explicit VR Big Endian

Add support for presentation contexts with an abstract syntax of Verification SOP Class and the default transfer syntaxes by using the inbuilt VerificationSOPClass object.

>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_supported_context(VerificationSOPClass)

Add support for presentation contexts with an abstract syntax of Verification SOP Class and a transfer syntax of Implicit VR Little Endian.

>>> from pydicom.uid import ImplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_supported_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian

Add support for presentation contexts with an abstract syntax of Verification SOP Class and transfer syntaxes of Implicit VR Little Endian and Explicit VR Big Endian and then update the context to also support Explicit VR Little Endian.

>>> from pydicom.uid import (
...     ImplicitVRLittleEndian, ExplicitVRLittleEndian, ExplicitVRBigEndian
... )
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_supported_context(VerificationSOPClass,
                             [ImplicitVRLittleEndian, ExplicitVRBigEndian])
>>> ae.add_supported_context(VerificationSOPClass, ExplicitVRLittleEndian)
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
    =Implicit VR Little Endian
    =Explicit VR Little Endian
    =Explicit VR Big Endian

Add support for CTImageStorage and if the association requestor includes an SCP/SCU Role Selection Negotiation item for CT Image Storage requesting the SCU and SCP roles then accept the proposal.

>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import CTImageStorage
>>> ae = AE()
>>> ae.add_supported_context(
...     CTImageStorage, scu_role=True, scp_role=True
... )
ae_title

Get the AE title.

associate(addr, port, contexts=None, ae_title=b'ANY-SCP', max_pdu=16382, ext_neg=None)[source][source]

Send an association request to a remote AE.

When requesting an association the local AE is acting as an SCU. The Association thread is returned whether or not the association is accepted and should be checked using Association.is_established before sending any messages.

Parameters:
  • addr (str) – The peer AE’s TCP/IP address.
  • port (int) – The peer AE’s listen port number.
  • contexts (list of presentation.PresentationContext, optional) – The presentation contexts that will be requested by the AE for support by the peer. If not used then the presentation contexts in the AE.requested_contexts property will be requested instead.
  • ae_title (bytes, optional) – The peer’s AE title, will be used as the ‘Called AE Title’ parameter value (default b’ANY-SCP’).
  • max_pdu (int, optional) – The maximum PDV receive size in bytes to use when negotiating the association (default 16832).
  • ext_neg (list of UserInformation objects, optional) – Used if extended association negotiation is required.
Returns:

assoc – The Association thread
Return type:

association.Association
Raises:

RuntimeError – If called with no requested presentation contexts (i.e. contexts has not been supplied and ApplicationEntity.requested_contexts is empty).
cleanup_associations()[source][source]

Remove dead associations.

dimse_timeout

Get the DIMSE timeout.

implementation_class_uid

Return the current Implementation Class UID.

implementation_version_name

Return the current Implementation Version Name.

maximum_associations

Return the number of maximum associations as int.

maximum_pdu_size

Return the maximum PDU size accepted by the AE as int.

network_timeout

Get the network timeout.

on_association_aborted(primitive=None)[source][source]

Callback for when an association is aborted.

** NOT IMPLEMENTED **

on_association_accepted(primitive)[source][source]

Callback for when an association is accepted.

** NOT IMPLEMENTED **

Placeholder for a function callback. Function will be called when an association attempt is accepted by either the local or peer AE

Parameters:pdu_primitives.A_ASSOCIATE – The A-ASSOCIATE (accept) primitive.
on_association_rejected(primitive)[source][source]

Callback for when an association is rejected.

** NOT IMPLEMENTED **

Placeholder for a function callback. Function will be called when an association attempt is rejected by a peer AE

Parameters:associate_rq_pdu (pynetdicom.pdu.A_ASSOCIATE_RJ) – The A-ASSOCIATE-RJ PDU instance received from the peer AE
on_association_released(primitive=None)[source][source]

Callback for when an association is released.

** NOT IMPLEMENTED **

on_association_requested(primitive)[source][source]

Callback for an association is requested.

** NOT IMPLEMENTED **

on_async_ops_window(nr_invoked, nr_performed)[source][source]

Callback for when an Asynchronous Operations Window Negotiation item is include in the association request.

Asynchronous operations are not supported by pynetdicom and any request will always return the default number of operations invoked/performed (1, 1), regardless of what values are returned by this callback.

If the callback is not implemented then no response to the Asynchronous Operations Window Negotiation will be sent to the association requestor.

Parameters:
  • nr_invoked (int) – The Maximum Number Operations Invoked parameter value of the Asynchronous Operations Window request. If the value is 0 then an unlimited number of invocations are requested.
  • nr_performed (int) – The Maximum Number Operations Performed parameter value of the Asynchronous Operations Window request. If the value is 0 then an unlimited number of performances are requested.
Returns:

The (maximum number operations invoked, maximum number operations performed). A value of 0 indicates that an unlimited number of operations is supported. As asynchronous operations are not currently supported the return value will be ignored and (1, 1). sent in response.
Return type:

int, int
on_c_echo(context, info)[source][source]

Callback for when a C-ECHO request is received.

User implementation is not required for the C-ECHO service, but if you intend to do so it should be defined prior to calling ApplicationEntity.start() and must return either an int or a pydicom Dataset containing a (0000,0900) Status element with a valid C-ECHO status value.

Supported Service Classes

Verification Service Class

Status

Success
0x0000 Success
Failure
0x0122 Refused: SOP Class Not Supported
0x0210 Refused: Duplicate Invocation
0x0211 Refused: Unrecognised Operation
0x0212 Refused: Mistyped Argument
Parameters:
  • context (presentation.PresentationContextTuple) – The presentation context that the C-ECHO message was sent under as a namedtuple with field names context_id, abstract_syntax and transfer_syntax.
  • info (dict) –

    A dict containing information about the current association, with the keys:

    'requestor' : {
    'ae_title' : bytes, the requestor's calling AE title
    'called_aet' : bytes, the requestor's called AE title
    'address' : str, the requestor's IP address
    'port' : int, the requestor's port number
}
'acceptor' : {
    'ae_title' : bytes, the acceptor's AE title
    'address' : str, the acceptor's IP address
    'port' : int, the acceptor's port number
}
'parameters' : {
    'message_id' : int, the DIMSE message ID
    'priority' : int, the requested operation priority
    'originator_aet' : bytes or None, the move originator's AE title
    'originator_message_id' : int or None, the move originator's message ID
}
'sop_class_extended' : {
    SOP Class UID : Service Class Application Information,
}
Returns:

status – The status returned to the peer AE in the C-ECHO response. Must be a valid C-ECHO status value 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 the DICOM Standard Part 7, Annex C).
Return type:

pydicom.dataset.Dataset or int

See also

association.Association.send_c_echo(), dimse_primitives.C_ECHO(), service_class.VerificationServiceClass()

References

on_c_find(dataset, context, info)[source][source]

Callback for when a C-FIND request is received.

Must be defined by the user prior to calling AE.start() and must yield (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.

Supported Service Classes

  • Query/Retrieve Service Class
  • Basic Worklist Management Service
  • Relevant Patient Information Query Service
  • Substance Administration Query Service
  • Hanging Protocol Query/Retrieve Service
  • Defined Procedure Protocol Query/Retrieve Service
  • Color Palette Query/Retrieve Service
  • Implant Template Query/Retrieve Service

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:
  • dataset (pydicom.dataset.Dataset) – The DICOM Identifier dataset sent by the peer in the C-FIND request.
  • context (presentation.PresentationContextTuple) – The presentation context that the C-FIND message was sent under as a namedtuple with field names context_id, abstract_syntax and transfer_syntax.
  • info (dict) –

    A dict containing information about the current association, with the keys:

    'requestor' : {
    'ae_title' : bytes, the requestor's calling AE title
    'called_aet' : bytes, the requestor's called AE title
    'address' : str, the requestor's IP address
    'port' : int, the requestor's port number
}
'acceptor' : {
    'ae_title' : bytes, the acceptor's AE title
    'address' : str, the acceptor's IP address
    'port' : int, the acceptor's port number
}
'parameters' : {
    'message_id' : int, the DIMSE message ID
    'priority' : int, the requested operation priority
}
'sop_class_extended' : {
    SOP Class UID : Service Class Application Information,
}
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 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 is ‘Failure’ or ‘Cancel’ then yield None.

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

See also

association.Association.send_c_find(), dimse_primitives.C_FIND(), service_class.QueryRetrieveFindServiceClass(), service_class.BasicWorklistManagementServiceClass(), service_class.RelevantPatientInformationQueryServiceClass(), service_class.SubstanceAdministrationQueryServiceClass(), service_class.HangingProtocolQueryRetrieveServiceClass(), service_class.DefinedProcedureProtocolQueryRetrieveServiceClass(), service_class.ColorPaletteQueryRetrieveServiceClass(), service_class.ImplantTemplateQueryRetrieveServiceClass()

References

on_c_find_cancel()[source][source]

Callback for when a C-FIND-CANCEL request is received.

Returns:True if you want to stop the C-FIND operation, False otherwise.
Return type:bool
on_c_get(dataset, context, info)[source][source]

Callback for when a C-GET request is received.

Must be defined by the user prior to calling ApplicationEntity.start() and must yield a int containing the total number of C-STORE sub-operations, then yield (status, dataset) pairs.

Supported Service Classes

  • Query/Retrieve Service Class
  • Hanging Protocol Query/Retrieve Service
  • Defined Procedure Protocol Query/Retrieve Service
  • Color Palette Query/Retrieve Service
  • Implant Template Query/Retrieve Service

Status

Success
0x0000 Sub-operations complete, no failures or warnings
Failure
0xA701 Out of resources: unable to calculate the 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
Cancel
0xFE00 Sub-operations terminated due to Cancel request
Warning
0xB000 Sub-operations complete, one or more failures or warnings
Pending
0xFF00 Matches are continuing - Current Match is supplied and any Optional Keys were supported in the same manner as Required Keys
Parameters:
  • dataset (pydicom.dataset.Dataset) – The DICOM Identifier dataset sent by the peer in the C-GET request.
  • context (presentation.PresentationContextTuple) – The presentation context that the C-GET message was sent under as a namedtuple with field names context_id, abstract_syntax and transfer_syntax.
  • info (dict) –

    A dict containing information about the current association, with the keys:

    'requestor' : {
    'ae_title' : bytes, the requestor's calling AE title
    'called_aet' : bytes, the requestor's called AE title
    'address' : str, the requestor's IP address
    'port' : int, the requestor's port number
}
'acceptor' : {
    'ae_title' : bytes, the acceptor's AE title
    'address' : str, the acceptor's IP address
    'port' : int, the acceptor's port number
}
'parameters' : {
    'message_id' : int, the DIMSE message ID
    'priority' : int, the requested operation priority
}
'sop_class_extended' : {
    SOP Class UID : Service Class Application Information,
}
Yields:

  • int – The first yielded value should be the total number of C-STORE sub-operations necessary to complete the C-GET operation. In other words, this is the number of matching SOP Instances to be sent to the peer.

  • status (pydicom.dataset.Dataset or int) – The status returned to the peer AE in the C-GET response. Must be a valid C-GET status value 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).

  • dataset (pydicom.dataset.Dataset or None) – If the status is ‘Pending’ then yield the Dataset to send to the peer via a C-STORE sub-operation over the current association.

    If the status is ‘Failed’, ‘Warning’ or ‘Cancel’ then yield a Dataset with a (0008,0058) Failed SOP Instance UID List element containing a list of the C-STORE sub-operation SOP Instance UIDs for which the C-GET operation has failed.

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

See also

association.Association.send_c_get(), dimse_primitives.C_GET(), service_class.QueryRetrieveGetServiceClass(), service_class.HangingProtocolQueryRetrieveServiceClass(), service_class.DefinedProcedureProtocolQueryRetrieveServiceClass(), service_class.ColorPaletteQueryRetrieveServiceClass(), service_class.ImplantTemplateQueryRetrieveServiceClass()

References

on_c_get_cancel()[source][source]

Callback for when a C-GET-CANCEL request is received.

on_c_move(dataset, move_aet, context, info)[source][source]

Callback for when a C-MOVE request is received.

Must be defined by the user prior to calling ApplicationEntity.start().

The first yield should be the (addr, port) of the move destination, the second yield the number of required C-STORE sub-operations as an int, and the remaining yields the (status, dataset) pairs.

Matching SOP Instances will be sent to the peer AE with AE title move_aet over a new association. If move_aet is unknown then the SCP will send a response with a ‘Failure’ status of 0xA801 ‘Move Destination Unknown’.

Supported Service Classes

  • Query/Retrieve Service
  • Hanging Protocol Query/Retrieve Service
  • Defined Procedure Protocol Query/Retrieve Service
  • Color Palette Query/Retrieve Service
  • Implant Template Query/Retrieve Service

Status

Success
0x0000 Sub-operations complete, no failures
Pending
0xFF00 Sub-operations are continuing
Cancel
0xFE00 Sub-operations terminated due to Cancel indication
Failure
0x0122 SOP class not supported
0x0124 Not authorised
0x0210 Duplicate invocation
0x0211 Unrecognised operation
0x0212 Mistyped argument
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
Parameters:
  • dataset (pydicom.dataset.Dataset) – The DICOM Identifier dataset sent by the peer in the C-MOVE request.
  • move_aet (bytes) – The destination AE title that matching SOP Instances will be sent to using C-STORE sub-operations. move_aet will be a correctly formatted AE title (16 chars, with trailing spaces as padding).
  • context (presentation.PresentationContextTuple) – The presentation context that the C-MOVE message was sent under as a namedtuple with field names context_id, abstract_syntax and transfer_syntax.
  • info (dict) –

    A dict containing information about the current association, with the keys:

    'requestor' : {
    'ae_title' : bytes, the requestor's calling AE title
    'called_aet' : bytes, the requestor's called AE title
    'address' : str, the requestor's IP address
    'port' : int, the requestor's port number
}
'acceptor' : {
    'ae_title' : bytes, the acceptor's AE title
    'address' : str, the acceptor's IP address
    'port' : int, the acceptor's port number
}
'parameters' : {
    'message_id' : int, the DIMSE message ID
    'priority' : int, the requested operation priority
}
'sop_class_extended' : {
    SOP Class UID : Service Class Application Information,
}
Yields:

  • addr, port (str, int or None, None) – The first yield should be the TCP/IP address and port number of the destination AE (if known) or (None, None) if unknown. If (None, None) is yielded then the SCP will send a C-MOVE response with a ‘Failure’ Status of 0xA801 (move destination unknown), in which case nothing more needs to be yielded.

  • int – The second yield should be the number of C-STORE sub-operations required to complete the C-MOVE operation. In other words, this is the number of matching SOP Instances to be sent to the peer.

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

  • dataset (pydicom.dataset.Dataset or None) – If the status is ‘Pending’ then yield the Dataset to send to the peer via a C-STORE sub-operation over a new association.

    If the status is ‘Failed’, ‘Warning’ or ‘Cancel’ then yield a Dataset with a (0008,0058) Failed SOP Instance UID List element containing the list of the C-STORE sub-operation SOP Instance UIDs for which the C-MOVE operation has failed.

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

See also

association.Association.send_c_move(), dimse_primitives.C_MOVE(), service_class.QueryRetrieveMoveServiceClass(), service_class.HangingProtocolQueryRetrieveServiceClass(), service_class.DefinedProcedureProtocolQueryRetrieveServiceClass(), service_class.ColorPaletteQueryRetrieveServiceClass(), service_class.ImplantTemplateQueryRetrieveServiceClass()

References

on_c_move_cancel()[source][source]

Callback for when a C-MOVE-CANCEL request is received.

on_c_store(dataset, context, info)[source][source]

Callback for when a C-STORE request is received.

Must be defined by the user prior to calling ApplicationEntity.start() and must return either an int or a pydicom Dataset containing a (0000,0900) Status element with a valid C-STORE status value.

If the user is storing dataset in the DICOM File Format (as in the DICOM Standard Part 10, Section 7) then they are responsible for adding the DICOM File Meta Information.

Supported Service Classes

  • Storage Service Class
  • Non-Patient Object Storage Service Class

Status

Success
0x0000 - Success
Warning
0xB000 Coercion of data elements
0xB006 Elements discarded
0xB007 Dataset does not match SOP class
Failure
0x0117 Invalid SOP instance
0x0122 SOP class not supported
0x0124 Not authorised
0x0210 Duplicate invocation
0x0211 Unrecognised operation
0x0212 Mistyped argument
0xA700 to 0xA7FF Out of resources
0xA900 to 0xA9FF Dataset does not match SOP class
0xC000 to 0xCFFF Cannot understand
Parameters:
  • dataset (pydicom.dataset.Dataset) – The DICOM dataset sent by the peer in the C-STORE request.
  • context (presentation.PresentationContextTuple) – The presentation context that the C-STORE message was sent under as a namedtuple with field names context_id, abstract_syntax and transfer_syntax.
  • info (dict) –

    A dict containing information about the current association, with the keys:

    'requestor' : {
    'ae_title' : bytes, the requestor's calling AE title
    'called_aet' : bytes, the requestor's called AE title
    'address' : str, the requestor's IP address
    'port' : int, the requestor's port number
}
'acceptor' : {
    'ae_title' : bytes, the acceptor's AE title
    'address' : str, the acceptor's IP address
    'port' : int, the acceptor's port number
}
'parameters' : {
    'message_id' : int, the DIMSE message ID
    'priority' : int, the requested operation priority
    'originator_aet' : bytes or None, the move originator's AE title
    'originator_message_id' : int or None, the move originator's message ID
}
'sop_class_extended' : {
    SOP Class UID : Service Class Application Information,
}
Returns:

status – The status returned to the peer AE in the C-STORE response. Must be a valid C-STORE status value 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 the DICOM Standard Part 7, Annex C).
Return type:

pydicom.dataset.Dataset or int
Raises:

NotImplementedError – If the callback has not been implemented by the user

See also

association.Association.send_c_store(), dimse_primitives.C_STORE(), service_class.StorageServiceClass(), service_class.NonPatientObjectStorageServiceClass()

References

on_make_connection()[source][source]

Callback for a connection is made.

** NOT IMPLEMENTED **

on_n_action(dataset, context, info)[source][source]

Callback for when a N-ACTION is received.

References

DICOM Standard Part 4, Annexes H, J, P, S, CC and DD

on_n_create(dataset, context, info)[source][source]

Callback for when a N-CREATE is received.

References

DICOM Standard Part 4, Annexes F, H, R, S, CC and DD

on_n_delete(context, info)[source][source]

Callback for when a N-DELETE is received.

References

DICOM Standard Part 4, Annexes H and DD

on_n_event_report(dataset, context, info)[source][source]

Callback for when a N-EVENT-REPORT is received.

References

DICOM Standard Part 4, Annexes F, H, J, CC and DD

on_n_get(attr, context, info)[source][source]

Callback for when an N-GET request is received.

Parameters:
  • attr (list of pydicom.tag.Tag) – The value of the (0000,1005) Attribute Idenfier List element containing the attribute tags for the N-GET operation.
  • context (presentation.PresentationContextTuple) – The presentation context that the N-GET message was sent under as a namedtuple with field names context_id, abstract_syntax and transfer_syntax.
  • info (dict) –

    A dict containing information about the current association, with the keys:

    'requestor' : {
    'ae_title' : bytes, the requestor's calling AE title
    'called_aet' : bytes, the requestor's called AE title
    'address' : str, the requestor's IP address
    'port' : int, the requestor's port number
}
'acceptor' : {
    'ae_title' : bytes, the acceptor's AE title
    'address' : str, the acceptor's IP address
    'port' : int, the acceptor's port number
}
'parameters' : {
    'message_id' : int, the DIMSE message ID
    'requested_sop_class' : str, the N-GET-RQ's requested SOP
    Class UID value
    'requested_sop_instance' : str, the N-GET-RQ's requested SOP
    Instance UID value
}
'sop_class_extended' : {
    SOP Class UID : Service Class Application Information,
}
Returns:

  • status (pydicom.dataset.Dataset or int) – The status returned to the peer AE in the N-GET response. Must be a valid N-GET status value 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).

  • dataset (pydicom.dataset.Dataset or None) – If the status category is ‘Success’ or ‘Warning’ then a dataset containing elements matching the request’s Attribute List conformant to the specifications in the corresponding Service Class.

    If the status is not ‘Successs’ or ‘Warning’ then return None.

See also

association.Association.send_n_get(), dimse_primitives.N_GET(), service_class.DisplaySystemManagementServiceClass()

References

on_n_set(dataset, context, info)[source][source]

Callback for when a N-SET is received.

References

DICOM Standard Part 4, Annexes F, H, CC and DD

on_receive_connection()[source][source]

Callback for a connection is received.

** NOT IMPLEMENTED **

on_sop_class_common_extended(items)[source][source]

Callback for when one or more SOP Class Common Extended Negotiation items are included in the association request.

Parameters:items (dict) – The {SOP Class UID : SOPClassCommonExtendedNegotiation} items sent by the requestor.
Returns:The {SOP Class UID : SOPClassCommonExtendedNegotiation} accepted by the acceptor. When receiving DIMSE messages containing datasets corresponding to the SOP Class UID in an accepted item the corresponding Service Class will be used.
Return type:dict

References

on_sop_class_extended(app_info)[source][source]

Callback for when one or more SOP Class Extended Negotiation items are included in the association request.

Parameters:app_info (dict of pydicom.uid.UID, bytes) – The {SOP Class UID : Service Class Application Information} parameter values for the included items, with the service class application information being the raw encoded data sent by the requestor.
Returns:The {SOP Class UID : Service Class Application Information} parameter values to be sent in response to the request, with the service class application information being the encoded data that will be sent to the peer as-is. Return None if no response is to be sent.
Return type:dict of pydicom.uid.UID, bytes or None

References

on_user_identity(user_id_type, primary_field, secondary_field, info)[source][source]

Callback for when a user identity negotiation item is included with the association request.

If not implemented by the user then the association will be accepted (provided there’s no other reason to reject it) and no User Identity response will be sent even if one is requested.

Parameters:
  • user_id_type (int) –

    The User Identity Type value, which indicates the form of user identity being provided:

    • 1 - Username as a UTF-8 string
    • 2 - Username as a UTF-8 string and passcode
    • 3 - Kerberos Service ticket
    • 4 - SAML Assertion
    • 5 - JSON Web Token
  • primary_field (bytes) – The Primary Field value, contains the username, the encoded Kerberos ticket or the JSON web token.
  • secondary_field (bytes or None) – The Secondary Field value. Will be None unless the user_id_type is 2 in which case it will be bytes.
  • info (dict) –

    A dict containing information about the association request and the association requestor, with the keys:

    'requestor' : {
    'ae_title' : bytes, the requestor's AE title
    'address' : str, the requestor's IP address
    'port' : int, the requestor's port number
}
Returns:

  • is_verified (bool) – Return True if the user identity has been confirmed and you wish to proceed with association establishment, False otherwise.
  • response (bytes or None) – If user_id_type is:
    • 1 or 2, then return None
    • 3 then return the Kerberos Server ticket as bytes
    • 4 then return the SAML response as bytes
    • 5 then return the JSON web token as bytes

References

port

Return the port number as an int.

quit()[source][source]

Stop the SCP.

remove_requested_context(abstract_syntax, transfer_syntax=None)[source][source]

Remove a requested Presentation Context.

Depending on the supplied parameters one of the following will occur:

  • abstract_syntax alone - all contexts with a matching abstract syntax all be removed.
  • abstract_syntax and transfer_syntax - for all contexts with a matching abstract syntax; if the supplied transfer_syntax list contains all of the context’s requested transfer syntaxes then the entire context will be removed. Otherwise only the matching transfer syntaxes will be removed from the context (and the context will remain with one or more transfer syntaxes).
Parameters:
  • abstract_syntax (str, pydicom.uid.UID or sop_class.SOPClass) – The abstract syntax of the presentation context you wish to stop requesting when sending association requests.
  • transfer_syntax (str/pydicom.uid.UID or list of str/pydicom.uid.UID, optional) – The transfer syntax(ex) you wish to stop requesting. If a list of str/UID then only those transfer syntaxes specified will no longer be requested. If not specified then the abstract syntax and all associated transfer syntaxes will no longer be requested (default).

Examples

Remove all requested presentation contexts with an abstract syntax of Verification SOP Class using its UID value.

>>> from pynetdicom import AE
>>> ae = AE()
>>> ae.add_requested_context('1.2.840.10008.1.1')
>>> print(ae.reqested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
        =Implicit VR Little Endian
        =Explicit VR Little Endian
        =Explicit VR Big Endian
>>> ae.remove_requested_context('1.2.840.10008.1.1')
>>> len(ae.requested_contexts)
0

Remove all requested presentation contexts with an abstract syntax of Verification SOP Class using the inbuilt VerificationSOPClass object.

>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_requested_context(VerificationSOPClass)
>>> ae.remove_requested_context(VerificationSOPClass)
>>> len(ae.requested_contexts)
0

For all requested presentation contexts with an abstract syntax of Verification SOP Class, stop requesting a transfer syntax of Implicit VR Little Endian. If a presentation context exists which only has a single Implicit VR Little Endian transfer syntax then it will be completely removed, otherwise it will be kept with its remaining transfer syntaxes.

Presentation context has only a single matching transfer syntax:

>>> from pydicom.uid import ImplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae.add_requested_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
        =Implicit VR Little Endian
>>> ae.remove_requested_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> len(ae.requested_contexts)
0

Presentation context has at least one remaining transfer syntax:

>>> from pydicom.uid import ImplicitVRLittleEndian, ExplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_requested_context(VerificationSOPClass)
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
        =Implicit VR Little Endian
        =Explicit VR Little Endian
        =Explicit VR Big Endian
>>> ae.remove_requested_context(VerificationSOPClass,
...                             [ImplicitVRLittleEndian, ExplicitVRLittleEndian])
>>> print(ae.requested_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
        =Explicit VR Big Endian
remove_supported_context(abstract_syntax, transfer_syntax=None)[source][source]

Remove a supported presentation context.

Depending on the supplied parameters one of the following will occur:

  • abstract_syntax alone- the entire supported context will be removed.
  • abstract_syntax and transfer_syntax - If the supplied transfer_syntax list contains all of the context’s supported transfer syntaxes then the entire context will be removed. Otherwise only the matching transfer syntaxes will be removed from the context (and the context will remain with one or more transfer syntaxes).
Parameters:
  • abstract_syntax (str, pydicom.uid.UID or sop_class.SOPClass) – The abstract syntax of the presentation context you wish to stop supporting.
  • transfer_syntax (str/pydicom.uid.UID or list of str/pydicom.uid.UID, optional) – The transfer syntax(ex) you wish to stop supporting. If a list of str/UID then only those transfer syntaxes specified will no longer be supported. If not specified then the abstract syntax and all associated transfer syntaxes will no longer be supported (default).

Examples

Remove the supported presentation context with an abstract syntax of Verification SOP Class using its UID value.

>>> from pynetdicom import AE
>>> ae = AE()
>>> ae.add_supported_context('1.2.840.10008.1.1')
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
        =Implicit VR Little Endian
        =Explicit VR Little Endian
        =Explicit VR Big Endian
>>> ae.remove_supported_context('1.2.840.10008.1.1')
>>> len(ae.supported_contexts)
0

Remove the supported presentation context with an abstract syntax of Verification SOP Class using the inbuilt VerificationSOPClass object.

>>> from pynetdicom import AE, VerificationPresentationContexts
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.supported_contexts = VerificationPresentationContexts
>>> ae.remove_supported_context(VerificationSOPClass)

For the presentation contexts with an abstract syntax of Verification SOP Class, stop supporting the Implicit VR Little Endian transfer syntax. If the presentation context only has the single Implicit VR Little Endian transfer syntax then it will be completely removed, otherwise it will be kept with the remaining transfer syntaxes.

Presentation context has only a single matching transfer syntax:

>>> from pydicom.uid import ImplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_supported_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
        =Implicit VR Little Endian
>>> ae.remove_supported_context(VerificationSOPClass, ImplicitVRLittleEndian)
>>> len(ae.supported_contexts)
0

Presentation context has at least one remaining transfer syntax:

>>> from pydicom.uid import ImplicitVRLittleEndian, ExplicitVRLittleEndian
>>> from pynetdicom import AE
>>> from pynetdicom.sop_class import VerificationSOPClass
>>> ae = AE()
>>> ae.add_supported_context(VerificationSOPClass)
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
        =Implicit VR Little Endian
        =Explicit VR Little Endian
        =Explicit VR Big Endian
>>> ae.remove_supported_context(VerificationSOPClass,
...                             [ImplicitVRLittleEndian, ExplicitVRLittleEndian])
>>> print(ae.supported_contexts[0])
Abstract Syntax: Verification SOP Class
Transfer Syntax(es):
        =Explicit VR Big Endian
requested_contexts

Return a list of the requested PresentationContext items.

Returns:The SCU’s requested Presentation Contexts.
Return type:list of presentation.PresentationContext
require_called_aet

Return the required called AE title as a length 16 bytes.

require_calling_aet

Return the required calling AE title as a length 16 bytes.

start()[source][source]

Start the AE as an SCP.

When running the AE as an SCP this needs to be called to start the main loop, it listens for connections on local_socket and if they request association starts a new Association thread

Successful associations get added to active_associations

stop()[source][source]

Stop the SCP.

When running as an SCP, calling stop() will kill all associations, close the listen socket and quit

supported_contexts

Return a list of the supported PresentationContexts items.

Returns:The SCP’s supported Presentation Contexts, ordered by abstract syntax.
Return type:list of presentation.PresentationContext