Struct ClientAssociationOptions 

pub struct ClientAssociationOptions<'a> { /* private fields */ }

A DICOM association builder for a client node. The final outcome is a ClientAssociation.

This is the standard way of requesting and establishing an association with another DICOM node, that one usually taking the role of a service class provider (SCP).

You can create either a blocking or non-blocking client by calling either establish or establish_async respectively.

⚠️ Warning: It is highly recommended to set read_timeout and write_timeout to a reasonable value for the async client since there is no default timeout on TcpStream

Basic usage

Synchronous API

let association = ClientAssociationOptions::new()
   .with_presentation_context("1.2.840.10008.1.1", vec!["1.2.840.10008.1.2.1", "1.2.840.10008.1.2"])
   .read_timeout(Duration::from_secs(60))
   .write_timeout(Duration::from_secs(60))
   .establish("129.168.0.5:104")?;

Asynchronous API

Include the async feature in your Cargo.toml

let association = ClientAssociationOptions::new()
   .with_presentation_context("1.2.840.10008.1.1", vec!["1.2.840.10008.1.2.1", "1.2.840.10008.1.2"])
   .read_timeout(Duration::from_secs(60))
   .write_timeout(Duration::from_secs(60))
   .establish_async("129.168.0.5:104")
   .await?;

TLS Support

Enabling one of the Cargo features sync-tls or async-tls unlocks the methods for configuring TLS. Call tls_config and server_name to establish the association over a secure transport connection.

TLS in synchronous API

Include the sync-tls feature in your Cargo.toml.

TLS in asynchronous API

Include the async-tls feature in your Cargo.toml.

Example

use dicom_dictionary_std::uids;
use dicom_ul::{ClientAssociation, ClientAssociationOptions};
use rustls::{
    ClientConfig, RootCertStore,
    pki_types::{CertificateDer, PrivateKeyDer, pem::PemObject},
};
// Loading certificates and keys for demonstration purposes
let ca_cert = CertificateDer::from_pem_slice(std::fs::read("ssl/ca.crt")?.as_ref())
    .expect("Failed to load client cert");

// Server certificate -- signed by CA
let server_cert = CertificateDer::from_pem_slice(std::fs::read("ssl/server.crt")?.as_ref())
    .expect("Failed to load server cert");

// Client cert and private key -- signed by CA
let client_cert = CertificateDer::from_pem_slice(std::fs::read("ssl/client.crt")?.as_ref())
    .expect("Failed to load client cert");
let client_private_key = PrivateKeyDer::from_pem_slice(std::fs::read("ssl/client.key")?.as_ref())
    .expect("Failed to load client private key");

// Create a root cert store for the client which includes the server certificate
let mut certs = RootCertStore::empty();
certs.add_parsable_certificates(vec![ca_cert.clone()]);

let config = ClientConfig::builder()
    .with_root_certificates(certs)
    .with_client_auth_cert(vec![client_cert, ca_cert], client_private_key)
    .expect("Failed to create client TLS config");

let association: ClientAssociation<_> = ClientAssociationOptions::new()
   .with_presentation_context(
        uids::VERIFICATION,
        vec![uids::EXPLICIT_VR_LITTLE_ENDIAN, uids::IMPLICIT_VR_LITTLE_ENDIAN]
   )
   .tls_config(config)
   .read_timeout(Duration::from_secs(60))
   .write_timeout(Duration::from_secs(60))
   .establish_with_tls("REMOTE_DCM@129.168.0.5:104")?;

For an association with the async API, call establish_tls_async or establish_with_async_tls instead of establish_tls or establish_with_tls.

Presentation contexts

At least one presentation context must be specified, using the method with_presentation_context and supplying both an abstract syntax and list of transfer syntaxes.

A helper method with_abstract_syntax will include by default the transfer syntaxes Implicit VR Little Endian and Explicit VR Little Endian in the resulting presentation context.

let association = ClientAssociationOptions::new()
    .with_abstract_syntax("1.2.840.10008.1.1")
    .establish("129.168.0.5:104")?;

Implementations

impl<'a> ClientAssociationOptions<'a>

pub fn new() -> Self

Create a new set of options for establishing an association.

pub fn calling_ae_title<T>(self, calling_ae_title: T) -> Self

where T: Into<Cow<'a, str>>,

Define the calling application entity title for the association, which refers to this DICOM node.

The default is THIS-SCU.

pub fn called_ae_title<T>(self, called_ae_title: T) -> Self

where T: Into<Cow<'a, str>>,

Define the called application entity title for the association, which refers to the target DICOM node.

The default is ANY-SCP. Passing an empty string resets the AE title to the default (or to the one passed via establish_with).

pub fn with_presentation_context<T>( self, abstract_syntax_uid: T, transfer_syntax_uids: Vec<T>, ) -> Self

where T: Into<Cow<'a, str>>,

Include this presentation context in the list of proposed presentation contexts.

pub fn with_abstract_syntax<T>(self, abstract_syntax_uid: T) -> Self

where T: Into<Cow<'a, str>>,

Helper to add this abstract syntax with the default transfer syntaxes to the list of proposed presentation contexts.

pub fn max_pdu_length(self, value: u32) -> Self

Override the maximum PDU length that this application entity will admit.

pub fn strict(self, strict: bool) -> Self

Override strict mode: whether receiving PDUs must not surpass the negotiated maximum PDU length.

pub fn username<T>(self, username: T) -> Self

where T: Into<Cow<'a, str>>,

Sets the user identity username

pub fn password<T>(self, password: T) -> Self

where T: Into<Cow<'a, str>>,

Sets the user identity password

pub fn username_password<T, U>(self, username: T, password: U) -> Self

where T: Into<Cow<'a, str>>, U: Into<Cow<'a, str>>,

Sets the user identity username and password

pub fn kerberos_service_ticket<T>(self, kerberos_service_ticket: T) -> Self

where T: Into<Cow<'a, str>>,

Sets the user identity Kerberos service ticket

pub fn saml_assertion<T>(self, saml_assertion: T) -> Self

where T: Into<Cow<'a, str>>,

Sets the user identity SAML assertion

pub fn jwt<T>(self, jwt: T) -> Self

where T: Into<Cow<'a, str>>,

Sets the user identity JWT

pub fn establish<A: ToSocketAddrs>( self, address: A, ) -> Result<ClientAssociation<TcpStream>, Error>

Initiate simple TCP connection to the given address and request a new DICOM association, negotiating the presentation contexts in the process.

pub fn establish_with( self, ae_address: &str, ) -> Result<ClientAssociation<TcpStream>, Error>

Initiate the TCP connection to the given address and request a new DICOM association, negotiating the presentation contexts in the process.

This method allows you to specify the called AE title alongside with the socket address. See AeAddr for more details. However, the AE title in this parameter is overridden by any called_ae_title option previously received.

Example

let association = ClientAssociationOptions::new()
    .with_abstract_syntax("1.2.840.10008.1.1")
    // called AE title in address
    .establish_with("MY-STORAGE@10.0.0.100:104")?;

pub fn read_timeout(self, timeout: Duration) -> Self

Set the read timeout for the underlying TCP socket

This is used to set both the read and write timeout.

pub fn write_timeout(self, timeout: Duration) -> Self

Set the write timeout for the underlying TCP socket

pub fn connection_timeout(self, timeout: Duration) -> Self

Set the connection timeout for the underlying TCP socket

Trait Implementations

impl<'a> Clone for ClientAssociationOptions<'a>

fn clone(&self) -> ClientAssociationOptions<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for ClientAssociationOptions<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ClientAssociationOptions<'_>

fn default() -> Self

Returns the “default value” for a type.