@spec abort(pid()) :: :ok

Sends an A-ABORT to forcefully terminate the association.

@spec cancel(pid(), integer()) :: :ok

Sends a C-CANCEL-RQ to cancel a pending C-FIND operation.

The message_id should be the MessageID of the original C-FIND-RQ.

@spec connect(String.t(), pos_integer(), keyword()) :: {:ok, pid()} | {:error, term()}

Opens an association to a remote DICOM AE (SCU client).

Options

• :calling_ae — local AE title (default: "DIMSE")
• :called_ae — remote AE title (default: "ANY-SCP")
• :abstract_syntaxes — list of SOP Class UIDs to propose
• :transfer_syntaxes — list of Transfer Syntax UIDs to propose
• :max_pdu_length — max PDU length (default: 16_384)
• :timeout — total association establishment timeout in ms (default: 30_000)
• :tls — TLS options (keyword list). When present, the SCU connects via TLS instead of plain TCP. Accepts standard :ssl options such as :cacertfile, :verify, :certfile, and :keyfile.
• :role_selections — list of Dimse.Pdu.RoleSelection structs proposing SCU/SCP roles per SOP class (PS3.7 Annex D.3.3.4)
• :user_identity — Dimse.Pdu.UserIdentity struct for SCU authentication (PS3.7 Annex D.3.3.7)

Returns {:ok, association_pid} or {:error, reason}.

@spec echo(
  pid(),
  keyword()
) :: :ok | {:error, term()}

Sends a C-ECHO request on an established association.

@spec find(pid(), String.t() | atom(), binary(), keyword()) ::
  {:ok, [binary()]} | {:error, {:cancelled, [binary()]} | term()}

Sends a C-FIND request and returns matching data sets.

Parameters

• assoc — association pid from Dimse.connect/3
• sop_class_or_level — SOP Class UID string, or query level atom (:patient, :study, :worklist)
• query_data — encoded query identifier data set

Options

• :priority — request priority (default: 0x0000 medium)
• :timeout — response timeout in ms (default: 30_000)

@spec get(pid(), String.t() | atom(), binary(), keyword()) ::
  {:ok, [binary()]} | {:error, term()}

Sends a C-GET request to retrieve instances on the same association.

The SCP sends matching instances back as C-STORE sub-operations on the same association. The SCU auto-accepts and returns the data sets.

Parameters

• assoc — association pid from Dimse.connect/3
• sop_class_or_level — SOP Class UID string, or query level atom (:patient, :study)
• query_data — encoded query identifier data set

Options

• :priority — request priority (default: 0x0000 medium)
• :timeout — response timeout in ms (default: 30_000)

Returns {:ok, [binary()]} with the received data sets.

@spec move(pid(), String.t() | atom(), binary(), keyword()) ::
  {:ok, map()} | {:error, term()}

Sends a C-MOVE request to retrieve instances to a destination AE.

The SCP pushes matching instances to the destination AE via C-STORE sub-operations and reports sub-operation counts in the response.

Parameters

• assoc — association pid from Dimse.connect/3
• sop_class_or_level — SOP Class UID string, or query level atom (:patient, :study)
• query_data — encoded query identifier data set

Options

• :dest_ae — destination AE title (required)
• :priority — request priority (default: 0x0000 medium)
• :timeout — response timeout in ms (default: 30_000)

Returns {:ok, %{completed: n, failed: n, warning: n}} on success.

@spec n_action(pid(), String.t(), String.t(), integer(), binary() | nil, keyword()) ::
  {:ok, integer(), binary() | nil}
  | {:error, {:status, integer(), binary() | nil} | term()}

Sends an N-ACTION-RQ to request an action on a managed SOP Instance.

Returns {:ok, status, data} or {:error, reason}.

@spec n_create(pid(), String.t(), binary() | nil, keyword()) ::
  {:ok, integer(), String.t() | nil, binary() | nil}
  | {:error, {:status, integer(), binary() | nil} | term()}

Sends an N-CREATE-RQ to create a new managed SOP Instance.

Options

• :sop_instance_uid — optional proposed SOP Instance UID
• :timeout — response timeout in ms (default: 30_000)

Returns {:ok, status, created_sop_instance_uid, data} or {:error, reason}.

@spec n_delete(pid(), String.t(), String.t(), keyword()) ::
  {:ok, integer(), nil} | {:error, {:status, integer(), nil} | term()}

Sends an N-DELETE-RQ to delete a managed SOP Instance.

Returns {:ok, status, nil} or {:error, reason}.

@spec n_event_report(
  pid(),
  String.t(),
  String.t(),
  integer(),
  binary() | nil,
  keyword()
) ::
  {:ok, integer(), binary() | nil}
  | {:error, {:status, integer(), binary() | nil} | term()}

Sends an N-EVENT-REPORT-RQ to notify the SCP of an event.

Returns {:ok, status, data} or {:error, reason}.

@spec n_get(pid(), String.t(), String.t(), keyword()) ::
  {:ok, integer(), binary() | nil}
  | {:error, {:status, integer(), binary() | nil} | term()}

Sends an N-GET-RQ to retrieve attributes from a managed SOP Instance.

Options

• :attribute_identifier_list — list of {group, element} tags to retrieve
• :timeout — response timeout in ms (default: 30_000)

Returns {:ok, status, data} or {:error, reason}.

@spec n_set(pid(), String.t(), String.t(), binary(), keyword()) ::
  {:ok, integer(), binary() | nil}
  | {:error, {:status, integer(), binary() | nil} | term()}

Sends an N-SET-RQ to modify attributes on a managed SOP Instance.

Returns {:ok, status, data} or {:error, reason}.

@spec release(pid(), timeout()) :: :ok | {:error, term()}

Sends an A-RELEASE-RQ to gracefully close the association.

@spec start_listener(keyword()) :: {:ok, term()} | {:error, term()}

Starts a DIMSE listener on the given port.

Options

• :port — TCP port to listen on (default: 11112)
• :handler — module implementing Dimse.Handler behaviour (required)
• :ae_title — local AE title (default: "DIMSE")
• :max_associations — max concurrent associations (default: 200)
• :num_acceptors — Ranch acceptor pool size (default: 10)
• :max_pdu_length — max PDU length in bytes (default: 16_384)
• :tls — TLS options (keyword list). When present, the listener uses TLS (:ranch_ssl) instead of plain TCP. Accepts standard :ssl options such as :certfile, :keyfile, :cacertfile, :verify, and :fail_if_no_peer_cert. PS3.15 Annex B recommends port 2762 for DICOM-TLS.

Returns {:ok, listener_ref} or {:error, reason}.

@spec stop_listener(term()) :: :ok | {:error, term()}

Stops a running DIMSE listener.

@spec store(pid(), String.t(), String.t(), binary(), keyword()) ::
  :ok | {:error, term()}

Sends a C-STORE request with the given data set.

Parameters

• assoc — association pid from Dimse.connect/3
• sop_class_uid — SOP Class UID of the instance
• sop_instance_uid — SOP Instance UID of the instance
• data — encoded data set binary

Options

• :priority — request priority (default: 0x0000 medium)
• :move_originator_ae — AE title of the C-MOVE originator
• :move_originator_message_id — message ID from the C-MOVE request
• :timeout — response timeout in ms (default: 30_000)

@spec with_connection(String.t(), pos_integer(), keyword(), (pid() -> term())) ::
  {:ok, term()} | {:error, term()}

Opens an association, executes a function, and releases gracefully.

Handles the full connection lifecycle: connect, execute, release. If the function raises or the association fails, the connection is aborted to ensure cleanup.

Parameters

• host — remote hostname or IP
• port — remote port
• opts — connection options (same as connect/3)
• fun — function receiving the association pid

Examples

Dimse.with_connection("192.168.1.10", 11112, [calling_ae: "SCU"], fn assoc ->
  :ok = Dimse.echo(assoc)
  {:ok, results} = Dimse.find(assoc, :study, query)
  results
end)

Returns {:ok, fun_result} or {:error, reason}.