User Data Sub-items (userdataitems)

This module contains User Data sub-item helper classes. Each sub-item class provides means for serialization and deserialization to and from binary formats as specified in PS 3.7 of DICOM standard.

class pynetdicom2.userdataitems.MaximumLengthSubItem(maximum_length_received: int, reserved: int = 0, item_length: int = 4)

Represents sub-item described in PS 3.8 D.1 Maximum Length Negotiation

Note that item is used in both A-ASSOCIATE-RQ and A-ASSOCIATE-AC PDUs.

Variables:

• reserved – this reserved field shall be sent with a value 00H but not tested to this value when received.

• item_length – item length, in the case of this item it’s fixed to 0x0004

• maximum_length_received – P-DATA-TF PDUs size limit

property total_length: int

Returns item total length.

This item has a fixed length of 8, so method always returns 8 regardless of specific instance :return item total length

encode() → bytes

Encodes itself into binary form

Returns:

binary representation of an item

classmethod decode(stream: BytesIO) → MaximumLengthSubItem

Decodes maximum length sub-item from data stream

Parameters:

stream – raw data stream

Returns:

decoded maximum length sub-item

class pynetdicom2.userdataitems.ImplementationClassUIDSubItem(implementation_class_uid: str, reserved: int = 0)

Represents sub-item described in PS 3.8 D.3.3.2 Implementation Identification Notification

Note that item is used in both A-ASSOCIATE-RQ and A-ASSOCIATE-AC PDUs.

Variables:

• reserved – this reserved field shall be sent with a value 00H but not tested to this value when received.

• implementation_class_uid – This variable field shall contain the Implementation-class-uid

property item_length: int

Calculates item length

Returns:

item length

property total_length: int

Returns total item length, including header.

Returns:

total item length

encode() → bytes

Encodes itself into binary form

Returns:

binary representation of an item

classmethod decode(stream: BytesIO) → ImplementationClassUIDSubItem

Decodes Implementation Class UID sub-item from data stream

Parameters:

stream – raw data stream

Returns:

decoded implementation class UID sub-item

class pynetdicom2.userdataitems.ImplementationVersionNameSubItem(implementation_version_name: str, reserved: int = 0)

Represents sub-item described in PS 3.8 D.3.3.2 Implementation Identification Notification

Note that item is used in both A-ASSOCIATE-RQ and A-ASSOCIATE-AC PDUs.

Variables:

• reserved – this reserved field shall be sent with a value 00H but not tested to this value when received.

• implementation_version_name – This variable field shall contain the Implementation-version-name

property item_length: int

Calculates item length

Returns:

item length

property total_length: int

Returns total item length, including header.

Returns:

total item length

encode() → bytes

Encodes itself into binary form

Returns:

binary representation of an item

classmethod decode(stream: BytesIO) → ImplementationVersionNameSubItem

Decodes Implementation Version Name sub-item from data stream

Parameters:

stream – raw data stream

Returns:

decoded Implementation Version Name sub-item

class pynetdicom2.userdataitems.AsynchronousOperationsWindowSubItem(max_num_ops_invoked: int, max_num_ops_performed: int, reserved: int = 0, item_length: int = 4)

Represents sub-item described in PS 3.8 D.3.3.3 Asynchronous Operations (And Sub-Operations) Window Negotiation

Note that item is used in both A-ASSOCIATE-RQ and A-ASSOCIATE-AC PDUs.

Variables:

• reserved – this reserved field shall be sent with a value 00H but not tested to this value when received.

• item_length – item length, in the case of this item it’s fixed to 0x0004

• max_num_ops_invoked – This field shall contain the Maximum-number-operations-invoked

• max_num_ops_performed – This field shall contain the Maximum-number-operations-performed

property total_length: int

Returns total item length, including header.

Returns:

total item length

encode() → bytes

Encodes itself into binary form

Returns:

binary representation of an item

classmethod decode(stream: BytesIO) → AsynchronousOperationsWindowSubItem

Decodes Asynchronous Operations Window sub-item from data stream

Parameters:

stream – raw data stream

Returns:

decoded Asynchronous Operations Window sub-item

class pynetdicom2.userdataitems.ScpScuRoleSelectionSubItem(sop_class_uid: UID, scu_role: int, scp_role: int, reserved: int = 0)

Represents sub-item described in PS 3.8 D.3.3.4 SCP/SCU Role Selection Negotiation

Note that item is used in both A-ASSOCIATE-RQ and A-ASSOCIATE-AC PDUs.

Variables:

• reserved – this reserved field shall be sent with a value 00H but not tested to this value when received.

• sop_class_uid – SOP Class UID or Meta SOP Class UID

• scu_role – 0 - non support of the SCU role, 1 - support of the SCU role

• scp_role – 0 - non support of the SCP role, 1 - support of the SCP role.

property item_length: int

Calculates item length

Returns:

item length

property total_length: int

Returns total item length, including header.

Returns:

total item length

encode() → bytes

Encodes itself into binary form

Returns:

binary representation of an item

classmethod decode(stream: BytesIO) → ScpScuRoleSelectionSubItem

Decodes SCP/SCU Role Selection sub-item from data stream

Parameters:

stream – raw data stream

Returns:

decoded SCP/SCU Role Selection sub-item

class pynetdicom2.userdataitems.SOPClassExtendedNegotiationSubItem(sop_class_uid: UID, app_info: bytes, reserved: int = 0)

Represents sub-item described in D.3.3.5 Service-Object Pair (SOP) Class Extended Negotiation.

Note that item is used in both A-ASSOCIATE-RQ and A-ASSOCIATE-AC PDUs.

Variables:

• sop_class_uid – service’s SOP Class UID

• app_info – application information specific to Service Class

• reserved – reserved field, defaults to 0x00. In most cases you should not change it’s value or check it

property item_length: int

Calculates item length

Returns:

item length

property total_length: int

Returns total item length, including the header.

Returns:

total item length

encode() → bytes

Encodes itself into binary form

Returns:

binary representation of an item

classmethod decode(stream: BytesIO) → SOPClassExtendedNegotiationSubItem

Factory method. Creates sub-item from binary stream.

Parameters:

stream – binary stream that should be decoded

Returns:

new sub-item

class pynetdicom2.userdataitems.UserIdentityNegotiationSubItem(primary_field: str | bytes, secondary_field: str | bytes = '', user_identity_type: int = 2, positive_response_req: int = 0, reserved: int = 0)

Represents sub-item described in D.3.3.7.1 User Identity sub-item structure(A-ASSOCIATE-RQ).

Passes user identification information based on login (and password) or kerberos service ticket

Variables:

• primary_field – user name or kerberos ticket depending on value of user_identity_type

• secondary_field – password. Used only if user_identity_type has value of 2

• user_identity_type – type of user identification. Defaults to 2 which is username/password identification

• positive_response_req – 0 - no response requested, 1 - positive response requested

• reserved – reserved field, defaults to 0x00. In most cases you should not change it’s value or check it

property primary_field: str | bytes

Sub-item primary field value.

Meaning of the value depends on the user_identity_type value

Returns:

primary field value: str when the field is valid UTF-8 (user name), otherwise raw bytes (Kerberos ticket, SAML assertion or JWT)

property secondary_field: str | bytes

Sub-item secondary field value.

Meaning of the value depends on the user_identity_type value

Returns:

secondary field value: str when the field is valid UTF-8, otherwise raw bytes

property item_length: int

Calculates item length

Returns:

item length

property total_length: int

Returns total item length, including header.

Returns:

total item length

encode() → bytes

Encodes itself into binary form

Returns:

binary representation of an item

classmethod decode(stream: BytesIO) → UserIdentityNegotiationSubItem

Factory method. Creates sub-item from binary stream.

Parameters:

stream – binary stream that should be decoded

Returns:

new sub-item

class pynetdicom2.userdataitems.UserIdentityNegotiationSubItemAc(server_response: str | bytes, reserved: int = 0)

Represents sub-item described in D.3.3.7.2 User Identity sub-item structure(A-ASSOCIATE-AC).

Server response (accept) user identification sub-item. This item is expected only if positive_response_req was set to 1 in request sub-item.

Variables:

• server_response – kerberos service ticket or SAML response, depending on requested user identification type

• reserved – reserved field, defaults to 0x00. In most cases you should not change it’s value or check it

property server_response: str | bytes

Server response value.

Returns:

server response: str when the field is valid UTF-8, otherwise raw bytes (Kerberos ticket or SAML response)

property item_length: int

Calculates item length

Returns:

item length

property total_length: int

Returns total item length, including header.

Returns:

total item length

encode() → bytes

Encodes itself into binary form

Returns:

binary representation of an item

classmethod decode(stream: BytesIO) → UserIdentityNegotiationSubItemAc

Factory method. Creates sub-item from binary stream.

Parameters:

stream – binary stream that should be decoded

Returns:

new sub-item

class pynetdicom2.userdataitems.GenericUserDataSubItem(item_type: int, user_data: bytes, reserved: int = 0)

This class is provided only to allow user data to converted to and from PDUs.

The actual data is not interpreted. This is left to the user.

property item_length: int

Calculates item length

Returns:

item length

property total_length: int

Returns total item length, including header.

Returns:

total item length

encode() → bytes

Encodes itself into binary form

Returns:

binary representation of an item

classmethod decode(stream: BytesIO) → GenericUserDataSubItem

Decodes generic data sub-item from data stream

User data value is left in raw string format. The Application Entity is responsible for dealing with it.

Parameters:

stream – raw data stream

Returns:

decoded generic data sub-item