dicom 0.7 → 0.8

data/lib/dicom/elements.rb

@@ -0,0 +1,82 @@
+#    Copyright 2010 Christoffer Lervag
+
+module DICOM
+
+  # The Elements mix-in module contains methods that are common among the different element classes:
+  # * DataElement
+  # * Item
+  # * Sequence
+  #
+  module Elements
+
+      # The encoded, binary value of the element (String).
+      attr_reader :bin
+      # The element's length (Fixnum).
+      attr_reader :length
+      # The element's name (String).
+      attr_reader :name
+      # The parent of this element (which may be an Item, Sequence or DObject).
+      attr_reader :parent
+      # The elementss tag (String).
+      attr_reader :tag
+      # The element's value representation (String).
+      attr_reader :vr
+
+      # Retrieves the entire chain of parents connected to this element.
+      # The parents are returned in an array, where the first element is the
+      # immediate parent and the last element is the top parent.
+      # Returns an empty array if no parent is defined.
+      #
+      def parents
+        all_parents = Array.new
+        # Extract all parents and add to array recursively:
+        if parent
+          all_parents = parent.parents if parent.parent
+          all_parents.insert(0, parent)
+        end
+        return all_parents
+      end
+
+      # Sets a specified element as this element's parent.
+      #
+      # === Parameters
+      #
+      # * <tt>new_parent</tt> -- A parent object (which can be either a DObject, Item or Sequence instance).
+      #
+      # === Examples
+      #
+      #   # Create a new Sequence and connect it to a DObject instance:
+      #   structure_set_roi = Sequence.new("3006,0020")
+      #   structure_set_roi.parent = obj
+      #
+      def parent=(new_parent)
+        # Remove ourselves from the previous parent (if any) first:
+        # Don't do this if parent is set as nil (by the remove method), or we'll get an endless loop!
+        if self.parent
+          self.parent.remove(self.tag) if new_parent and self.parent != new_parent
+        end
+        # Set the new parent (should we bother to test for parent validity here?):
+        @parent = new_parent
+      end
+
+      # Returns the top parent of a particular element.
+      #
+      # === Notes
+      #
+      # Unless an element, or one of its parent elements, are independent, the top parent will be a DObject instance.
+      #
+      def top_parent
+        # The top parent is determined recursively:
+        if parent
+          if parent.is_a?(DObject)
+            return parent
+          else
+            return parent.top_parent
+          end
+        else
+          return self
+        end
+      end
+
+  end
+end

data/lib/dicom/file_handler.rb

@@ -0,0 +1,116 @@
+#    Copyright 2010 Christoffer Lervag
+#
+# The purpose of this file is to make it as easy as possible for users to customize the way
+# DICOM files are handled when they are received through the network.
+#
+# The default behaviour is to save the files to disk using a folder structure determined by a  few select tags of the DICOM file.
+#
+# Some suggested alternatives for user customization:
+# * Analyzing tags and/or image data to determine further actions.
+# * Modify the DICOM object before it is saved to disk.
+# * Modify the folder structure in which DICOM files are saved to disk.
+# * Store DICOM contents in a database (highly relevant if you are building a Ruby on Rails DICOM application).
+# * Retransmit the DICOM object to another network destination using the DClient class.
+# * Write information to a log file.
+
+module DICOM
+
+  # This class handles DICOM files that have been received through network communication.
+  #
+  class FileHandler
+
+    # Saves a single DICOM object to file.
+    # Returns a status message stating where the file has been saved.
+    #
+    # Modify this method if you want to change the way your server saves incoming files.
+    #
+    # === Notes
+    #
+    # As default, files will be saved with the following path:
+    # <tt> path_prefix/<PatientID>/<StudyDate>/<Modality>/ </tt>
+    #
+    # === Parameters
+    #
+    # * <tt>path_prefix</tt> -- String. Specifies the root path of the DICOM storage.
+    # * <tt>obj</tt> -- A DObject instance which will be written to file.
+    # * <tt>transfer_syntax</tt> -- String. Specifies the transfer syntax that will be used to write the DICOM file.
+    #
+    def self.save_file(path_prefix, obj, transfer_syntax)
+      # File name is set using the SOP Instance UID:
+      file_name = obj.value("0008,0018") || "missing_SOP_UID.dcm"
+      folders = Array.new(3)
+      folders[0] = obj.value("0010,0020") || "PatientID"
+      folders[1] = obj.value("0008,0020") || "StudyDate"
+      folders[2] = obj.value("0008,0060") || "Modality"
+      local_path = folders.join(File::SEPARATOR) + File::SEPARATOR + file_name
+      full_path = path_prefix + local_path
+      # Save the DICOM object to disk:
+      obj.write(full_path, :transfer_syntax => transfer_syntax)
+      message = "DICOM file saved to: #{full_path}"
+      return message
+    end
+
+    # Handles the reception of a series of DICOM objects which are received in a single association.
+    #
+    # Modify this method if you want to change the way your server handles incoming file series.
+    #
+    # === Notes
+    #
+    # Default action: Pass each file to the class method which saves files to disk.
+    #
+    # === Parameters
+    #
+    # * <tt>path</tt> -- String. Specifies the root path of the DICOM storage.
+    # * <tt>objects</tt> -- An array containing the DObject instances which were received.
+    # * <tt>transfer_syntaxes</tt> -- An array containing the transfer syntaxes belonging to the received objects.
+    #
+    def self.receive_files(path, objects, transfer_syntaxes)
+      all_success = true
+      successful, too_short, parse_fail, handle_fail = 0, 0, 0, 0
+      total = objects.length
+      message = nil
+      messages = Array.new
+      # Process each DICOM object:
+      objects.each_index do |i|
+        if objects[i].length > 8
+          # Parse the received data stream and load it as a DICOM object:
+          obj = DObject.new(objects[i], :bin => true, :syntax => transfer_syntaxes[i])
+          if obj.read_success
+            begin
+              message = self.save_file(path, obj, transfer_syntaxes[i])
+              successful += 1
+            rescue
+              handle_fail += 1
+              all_success = false
+              messages << "Error: Saving file failed!"
+            end
+          else
+            parse_fail += 1
+            all_success = false
+            messages << "Error: Invalid DICOM data encountered: The DICOM data string could not be parsed successfully."
+          end
+        else
+          too_short += 1
+          all_success = false
+          messages << "Error: Invalid data encountered: The data was too small to be a valid DICOM file."
+        end
+      end
+      # Create a summary status message, when multiple files have been received:
+      if total > 1
+        if successful == total
+          messages << "All #{total} DICOM files received successfully."
+        else
+          if successful == 0
+            messages << "All #{total} received DICOM files failed!"
+          else
+            messages << "Only #{successful} of #{total} DICOM files received successfully!"
+          end
+        end
+      else
+        messages = [message] if all_success
+      end
+      return all_success, messages
+    end
+
+  end
+end

data/lib/dicom/item.rb

@@ -0,0 +1,87 @@
+#    Copyright 2010 Christoffer Lervag
+
+module DICOM
+
+  # The Item class handles information related to items - the elements contained in sequences.
+  #
+  class Item < SuperItem
+
+    # Include the Elements mix-in module:
+    include Elements
+
+    # The index of this Item in the group of items belonging to its parent. If the Item is without parent, index is nil.
+    attr_accessor :index
+
+    # Creates an Item instance.
+    #
+    # === Notes
+    #
+    # Normally, an Item contains data elements and/or sequences. However, in some cases, an Item will instead/also
+    # carry binary string data, like the pixel data of an encapsulated image fragment.
+    #
+    # === Parameters
+    #
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:bin</tt> -- A binary string to be carried by the Item.
+    # * <tt>:index</tt> -- Fixnum. If the Item is to be inserted at a specific index (Item number), this option parameter needs to set.
+    # * <tt>:length</tt> -- Fixnum. The Item length (which either refers to the length of the encoded string of children of this Item, or the length of its binary data).
+    # * <tt>:name</tt> - String. The name of the Item may be specified upon creation. If it is not, a default name is chosen.
+    # * <tt>:parent</tt> - Sequence or DObject instance which the Item instance shall belong to.
+    # * <tt>:vr</tt> -- String. The value representation of the Item may be specified upon creation. If it is not, a default vr is chosen.
+    #
+    # === Examples
+    #
+    #   # Create an empty Item and connect it to the "Structure Set ROI Sequence":
+    #   item = Item.new(:parent => obj["3006,0020"])
+    #   # Create a "Pixel Data Item" which carries an encapsulated image frame (a pre-encoded binary):
+    #   pixel_item = Item.new(:bin => processed_pixel_data, :parent => obj["7FE0,0010"][1])
+    #
+    def initialize(options={})
+      # Set common parent variables:
+      initialize_parent
+      # Set instance variables:
+      @tag = ITEM_TAG
+      @value = nil
+      @name = options[:name] || "Item"
+      @vr = options[:vr] || ITEM_VR
+      @bin = options[:bin]
+      @length = options[:length]
+      @length = -1 unless options[:length] or options[:bin]
+      if options[:parent]
+        @parent = options[:parent]
+        @index = options[:index] if options[:index]
+        @parent.add_item(self, :index => options[:index])
+      end
+    end
+
+    # Sets the binary string that the Item will contain.
+    #
+    # === Parameters
+    #
+    # * <tt>new_bin</tt> -- A binary string of encoded data.
+    #
+    # === Examples
+    #
+    #   # Insert a custom jpeg in the (encapsulated) pixel data element, in it's first pixel data item:
+    #   obj["7FE0,0010"][1].children.first.bin = jpeg_binary_string
+    #
+    def bin=(new_bin)
+      if new_bin.is_a?(String)
+        # Add an empty byte at the end if the length of the binary is odd:
+        if new_bin.length[0] == 1
+          @bin = new_bin + "\x00"
+        else
+          @bin = new_bin
+        end
+        @value = nil
+        @length = @bin.length
+      else
+        raise "Invalid parameter type. String was expected, got #{new_bin.class}."
+      end
+    end
+
+  end
+end

data/lib/dicom/{Link.rb → link.rb}

@@ -2,14 +2,40 @@
 
 module DICOM
 
-  # This class handles the construction and interpretation of network packages
-  # as well as network communication.
+  # This class handles the construction and interpretation of network packages as well as network communication.
+  #
   class Link
 
-    attr_accessor :max_package_size, :verbose, :file_handler
-    attr_reader :errors, :notices
-
-    # Initialize the instance with a host adress and a port number.
+    # A customized FileHandler class to use instead of the default FileHandler included with Ruby DICOM.
+    attr_accessor :file_handler
+    # The maximum allowed size of network packages (in bytes). 
+    attr_accessor :max_package_size
+    # A hash which keeps track of the relationship between context ID and chosen transfer syntax.
+    attr_accessor :presentation_contexts
+    # A boolean which defines if notices/warnings/errors will be printed to the screen (true) or not (false).
+    attr_accessor :verbose
+    # An array containing any error messages recorded.
+    attr_reader :errors
+    # An array containing any status messages recorded.
+    attr_reader :notices
+    # A TCP network session where the DICOM communication is done with a remote host or client.
+    attr_reader :session
+
+    # Creates a Link instance, which is used by both DClient and DServer to handle network communication.
+    #
+    # === Parameters
+    #
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:ae</tt> -- String. The name of the client (application entity).
+    # * <tt>:file_handler</tt> -- A customized FileHandler class to use instead of the default FileHandler.
+    # * <tt>:host_ae</tt> -- String. The name of the server (application entity).
+    # * <tt>:max_package_size</tt> -- Fixnum. The maximum allowed size of network packages (in bytes). 
+    # * <tt>:timeout</tt> -- Fixnum. The maximum period to wait for an answer before aborting the communication.
+    # * <tt>:verbose</tt> -- Boolean. If set to false, the DLink instance will run silently and not output warnings and error messages to the screen. Defaults to true.
+    #
     def initialize(options={})
       require 'socket'
       # Optional parameters (and default values):
@@ -19,31 +45,56 @@ module DICOM
       @max_package_size = options[:max_package_size] || 32768 # 16384
       @max_receive_size = @max_package_size
       @timeout = options[:timeout] || 10 # seconds
-      @min_length = 12 # minimum number of bytes to expect in an incoming transmission
+      @min_length = 10 # minimum number of bytes to expect in an incoming transmission
       @verbose = options[:verbose]
       @verbose = true if @verbose == nil # Default verbosity is 'on'.
       # Other instance variables:
       @errors = Array.new # errors and warnings are put in this array
       @notices = Array.new # information on successful transmissions are put in this array
       # Variables used for monitoring state of transmission:
-      @connection = nil # TCP connection status
+      @session = nil # TCP connection
       @association = nil # DICOM Association status
       @request_approved = nil # Status of our DICOM request
       @release = nil # Status of received, valid release response
+      @command_request = Hash.new
+      @presentation_contexts = Hash.new # Keeps track of the relationship between pc id and it's transfer syntax
       set_default_values
       set_user_information_array
-      @outgoing = Stream.new(nil, true, true)
+      @outgoing = Stream.new(string=nil, endian=true)
     end
 
+    # Waits for an SCU to issue a release request, and answers it by launching the handle_release method.
+    # If invalid or no message is received, the connection is closed.
+    #
+    def await_release
+      segments = receive_single_transmission
+      info = segments.first
+      if info[:pdu] != PDU_RELEASE_REQUEST
+        # For some reason we didnt get our expected release request. Determine why:
+        if info[:valid]
+          add_error("Unexpected message type received (PDU: #{info[:pdu]}). Expected a release request. Closing the connection.")
+          handle_abort(false)
+        else
+          add_error("Timed out while waiting for a release request. Closing the connection.")
+        end
+        stop_session
+      else
+        # Properly release the association:
+        handle_release
+      end
+    end
 
-    # Build the abort message which is transmitted when the server wishes to (abruptly) abort the connection.
-    # For the moment: NO REASONS WILL BE PROVIDED. (and source of problems will always be set as client side)
+    # Builds the abort message which is transmitted when the server wishes to (abruptly) abort the connection.
+    #
+    # === Restrictions
+    #
+    # For now, no reasons for the abortion are provided (and source of problems will always be set as client side).
+    #
     def build_association_abort
       # Big endian encoding:
-      @outgoing.set_endian(@net_endian)
+      @outgoing.endian = @net_endian
       # Clear the outgoing binary string:
       @outgoing.reset
-      pdu = "07"
       # Reserved (2 bytes)
       @outgoing.encode_last("00"*2, "HEX")
       # Source (1 byte)
@@ -52,48 +103,56 @@ module DICOM
       # Reason/Diag. (1 byte)
       reason = "00" # (Reason not specified)
       @outgoing.encode_last(reason, "HEX")
-      append_header(pdu)
+      append_header(PDU_ABORT)
     end
 
-
-    # Build the binary string that will be sent as TCP data in the Association accept response.
-    def build_association_accept(info, ac_uid, ui, result)
+    # Builds the binary string which is sent as the association accept (in response to an association request).
+    #
+    # === Parameters
+    #
+    # * <tt>info</tt> -- The association information hash.
+    #
+    def build_association_accept(info)
       # Big endian encoding:
-      @outgoing.set_endian(@net_endian)
+      @outgoing.endian = @net_endian
       # Clear the outgoing binary string:
       @outgoing.reset
-      # Set item types (pdu and presentation context):
-      pdu = "02"
-      pc_type = "21"
-      # No abstract syntax in association response:
-      abstract_syntax = nil
+      # No abstract syntax in association response. To make this work with the method that
+      # encodes the presentation context, we pass on a one-element array containing nil).
+      abstract_syntaxes = Array.new(1, nil)
       # Note: The order of which these components are built is not arbitrary.
-      append_application_context(ac_uid)
-      # Return one presentation context for each of the proposed abstract syntaxes:
-      abstract_syntaxes = Array.new
+      append_application_context(info[:application_context])
+      # Reset the presentation context instance variable:
+      @presentation_contexts = Hash.new
+      # Build the presentation context strings, one by one:
       info[:pc].each do |pc|
-        unless abstract_syntaxes.include?(pc[:abstract_syntax])
-          abstract_syntaxes << pc[:abstract_syntax]
-          context_id = pc[:presentation_context_id]
-          transfer_syntax = pc[:ts].first[:transfer_syntax]
-          append_presentation_context(abstract_syntax, pc_type, transfer_syntax, context_id, result)
-        end
+        context_id = pc[:presentation_context_id]
+        result = pc[:result]
+        transfer_syntax = pc[:selected_transfer_syntax]
+        @presentation_contexts[context_id] = transfer_syntax
+        append_presentation_contexts(abstract_syntaxes, ITEM_PRESENTATION_CONTEXT_RESPONSE, transfer_syntax, context_id, result)
       end
-      append_user_information(ui)
+      append_user_information(@user_information)
       # Header must be built last, because we need to know the length of the other components.
-      append_association_header(pdu)
+      append_association_header(PDU_ASSOCIATION_ACCEPT, info[:called_ae])
     end
 
-
-    # Build the binary string that will be sent as TCP data in the association rejection.
-    # NB: For the moment, this method will only customize the "reason" value.
-    # For a list of error codes, see the official dicom PS3.8 document, page 41.
+    # Builds the binary string which is sent as the association reject (in response to an association request).
+    #
+    # === Parameters
+    #
+    # * <tt>info</tt> -- The association information hash.
+    #
+    # === Restrictions
+    #
+    # * For now, this method will only customize the "reason" value.
+    # * For a list of error codes, see the DICOM standard, PS3.8 Chapter 9.3.4, Table 9-21.
+    #
     def build_association_reject(info)
       # Big endian encoding:
-      @outgoing.set_endian(@net_endian)
+      @outgoing.endian = @net_endian
       # Clear the outgoing binary string:
       @outgoing.reset
-      pdu = "03"
       # Reserved (1 byte)
       @outgoing.encode_last("00", "HEX")
       # Result (1 byte)
@@ -104,35 +163,44 @@ module DICOM
       # Reason (1 byte)
       reason = info[:reason]
       @outgoing.encode_last(reason, "HEX")
-      append_header(pdu)
+      append_header(PDU_ASSOCIATION_REJECT)
     end
 
-
-    # Build the binary string that will be sent as TCP data in the Association request.
-    def build_association_request(ac_uid, as, ts, ui)
+    # Builds the binary string which is sent as the association request.
+    #
+    # === Parameters
+    #
+    # * <tt>ac_uid</tt> -- The application context UID string.
+    # * <tt>as</tt> -- An array of abstract syntax strings.
+    # * <tt>ts</tt> -- An array of transfer syntax strings.
+    # * <tt>user_info</tt> -- A user information items array.
+    #
+    def build_association_request(ac_uid, as, ts, user_info)
       # Big endian encoding:
-      @outgoing.set_endian(@net_endian)
+      @outgoing.endian = @net_endian
       # Clear the outgoing binary string:
       @outgoing.reset
-      # Set item types (pdu and presentation context):
-      pdu = "01"
-      pc = "20"
       # Note: The order of which these components are built is not arbitrary.
       # (The first three are built 'in order of appearance', the header is built last, but is put first in the message)
       append_application_context(ac_uid)
-      append_presentation_context(as, pc, ts)
-      append_user_information(ui)
+      append_presentation_contexts(as, ITEM_PRESENTATION_CONTEXT_REQUEST, ts)
+      append_user_information(user_info)
       # Header must be built last, because we need to know the length of the other components.
-      append_association_header(pdu)
+      append_association_header(PDU_ASSOCIATION_REQUEST, @host_ae)
     end
 
-
-    # Build the binary string that will be sent as TCP data in the query command fragment.
-    # Typical values:
-    # pdu = "04" (data), context = "01", flags = "03"
+    # Builds the binary string which is sent as a command fragment.
+    #
+    # === Parameters
+    #
+    # * <tt>pdu</tt> -- The command fragment's PDU string.
+    # * <tt>context</tt> -- Presentation context ID byte (references a presentation context from the association).
+    # * <tt>flags</tt> -- The flag string, which identifies if this is the last command fragment or not.
+    # * <tt>command_elements</tt> -- An array of command elements.
+    #
     def build_command_fragment(pdu, context, flags, command_elements)
       # Little endian encoding:
-      @outgoing.set_endian(@data_endian)
+      @outgoing.endian = @data_endian
       # Clear the outgoing binary string:
       @outgoing.reset
       # Build the last part first, the Command items:
@@ -160,26 +228,35 @@ module DICOM
       # Tag (4 bytes)
       @outgoing.add_first(@outgoing.encode_tag("0000,0000"))
       # Big endian encoding from now on:
-      @outgoing.set_endian(@net_endian)
+      @outgoing.endian = @net_endian
       # Flags (1 byte)
-      @outgoing.encode_first(flags, "HEX") # Command, last fragment (identifier)
+      @outgoing.encode_first(flags, "HEX")
       # Presentation context ID (1 byte)
-      @outgoing.encode_first(context, "HEX") # Explicit VR Little Endian, Study Root Query/Retrieve.... (what does this reference, the earlier abstract syntax? transfer syntax?)
+      @outgoing.encode_first(context, "BY")
       # Length (of remaining data) (4 bytes)
       @outgoing.encode_first(@outgoing.string.length, "UL")
       # PRESENTATION DATA VALUE (the above)
       append_header(pdu)
     end
 
-
-    # Build the binary string that will be sent as TCP data in the query data fragment.
-    # The style of encoding will depend on whether we have an implicit or explicit transfer syntax.
-    def build_data_fragment(data_elements)
+    # Builds the binary string which is sent as a data fragment.
+    #
+    # === Notes
+    #
+    # * The style of encoding will depend on whether we have an implicit or explicit transfer syntax.
+    #
+    # === Parameters
+    #
+    # * <tt>data_elements</tt> -- An array of data elements.
+    # * <tt>presentation_context_id</tt> -- Presentation context ID byte (references a presentation context from the association).
+    #
+    def build_data_fragment(data_elements, presentation_context_id)
+      # Set the transfer syntax to be used for encoding the data fragment:
+      set_transfer_syntax(@presentation_contexts[presentation_context_id])
       # Endianness of data fragment:
-      @outgoing.set_endian(@data_endian)
+      @outgoing.endian = @data_endian
       # Clear the outgoing binary string:
       @outgoing.reset
-      pdu = "04"
       # Build the last part first, the Data items:
       data_elements.each do |element|
         # Encode all tags (even tags which are empty):
@@ -204,50 +281,53 @@ module DICOM
       # The rest of the data fragment will be built in reverse, all the time
       # putting the elements first in the outgoing binary string.
       # Big endian encoding from now on:
-      @outgoing.set_endian(@net_endian)
+      @outgoing.endian = @net_endian
       # Flags (1 byte)
       @outgoing.encode_first("02", "HEX") # Data, last fragment (identifier)
       # Presentation context ID (1 byte)
-      @outgoing.encode_first("01", "HEX") # Explicit VR Little Endian, Study Root Query/Retrieve.... (what does this reference, the earlier abstract syntax? transfer syntax?)
+      @outgoing.encode_first(presentation_context_id, "BY")
       # Length (of remaining data) (4 bytes)
       @outgoing.encode_first(@outgoing.string.length, "UL")
       # PRESENTATION DATA VALUE (the above)
-      append_header(pdu)
+      append_header(PDU_DATA)
     end
 
-
-    # Build the binary string that will be sent as TCP data in the association release request:
+    # Builds the binary string which is sent as the release request.
+    #
     def build_release_request
       # Big endian encoding:
-      @outgoing.set_endian(@net_endian)
+      @outgoing.endian = @net_endian
       # Clear the outgoing binary string:
       @outgoing.reset
-      pdu = "05"
       # Reserved (4 bytes)
       @outgoing.encode_last("00"*4, "HEX")
-      append_header(pdu)
+      append_header(PDU_RELEASE_REQUEST)
     end
 
-
-    # Build the binary string that will be sent as TCP data in the association release response.
+    # Builds the binary string which is sent as the release response (which follows a release request).
+    #
     def build_release_response
       # Big endian encoding:
-      @outgoing.set_endian(@net_endian)
+      @outgoing.endian = @net_endian
       # Clear the outgoing binary string:
       @outgoing.reset
-      pdu = "06"
       # Reserved (4 bytes)
       @outgoing.encode_last("00000000", "HEX")
-      append_header(pdu)
+      append_header(PDU_RELEASE_RESPONSE)
     end
 
-
-    # Build the binary string that makes up a storage data fragment.
-    # Typical value: flags = "00" (more fragments following), flags = "02" (last fragment)
-    # pdu = "04", context = "01"
+    # Builds the binary string which makes up a C-STORE data fragment.
+    #
+    # === Parameters
+    #
+    # * <tt>pdu</tt> -- The data fragment's PDU string.
+    # * <tt>context</tt> -- Presentation context ID byte (references a presentation context from the association).
+    # * <tt>flags</tt> -- The flag string, which identifies if this is the last data fragment or not.
+    # * <tt>body</tt> -- A pre-encoded binary string (typicall a segment of a DICOM file to be transmitted).
+    #
     def build_storage_fragment(pdu, context, flags, body)
       # Big endian encoding:
-      @outgoing.set_endian(@net_endian)
+      @outgoing.endian = @net_endian
       # Clear the outgoing binary string:
       @outgoing.reset
       # Build in reverse, putting elements in front of the binary string:
@@ -256,161 +336,182 @@ module DICOM
       # Flags (1 byte)
       @outgoing.encode_first(flags, "HEX")
       # Context ID (1 byte)
-      @outgoing.encode_first(context, "HEX")
+      @outgoing.encode_first(context, "BY")
       # PDV Length (of remaining data) (4 bytes)
       @outgoing.encode_first(@outgoing.string.length, "UL")
       # PRESENTATION DATA VALUE (the above)
       append_header(pdu)
     end
 
-
-    # Extracts the abstrax syntax from the first presentation context in the info hash object:
-    def extract_abstract_syntax(info)
-      return info[:pc].first[:abstract_syntax]
-    end
-
-
-    # Extracts the (first) transfer syntax from the first presentation context in the info hash object:
-    def extract_transfer_syntax(info)
-      return info[:pc].first[:ts].first[:transfer_syntax]
-    end
-
-
-    # Delegates an incoming message to its correct interpreter method, based on pdu type.
-    def forward_to_interpret(message, pdu, file = nil)
+    # Delegates an incoming message to its appropriate interpreter method, based on its pdu type.
+    # Returns the interpreted information hash.
+    #
+    # === Parameters
+    #
+    # * <tt>message</tt> -- The binary message string.
+    # * <tt>pdu</tt> -- The PDU string of the message.
+    # * <tt>file</tt> -- A boolean used to inform whether an incoming data fragment is part of a DICOM file reception or not.
+    #
+    def forward_to_interpret(message, pdu, file=nil)
       case pdu
-        when "01" # Associatin request
+        when PDU_ASSOCIATION_REQUEST
           info = interpret_association_request(message)
-        when "02" # Accepted association
+        when PDU_ASSOCIATION_ACCEPT
           info = interpret_association_accept(message)
-        when "03" # Rejected association
+        when PDU_ASSOCIATION_REJECT
           info = interpret_association_reject(message)
-        when "04" # Data
+        when PDU_DATA
           info = interpret_command_and_data(message, file)
-        when "05"
+        when PDU_RELEASE_REQUEST
           info = interpret_release_request(message)
-        when "06" # Release response
+        when PDU_RELEASE_RESPONSE
           info = interpret_release_response(message)
-        when "07" # Abort connection
+        when PDU_ABORT
           info = interpret_abort(message)
         else
           info = {:valid => false}
-          add_error("An unknown pdu type was received in the incoming transmission. Can not decode this message. (pdu: #{pdu})")
+          add_error("An unknown PDU type was received in the incoming transmission. Can not decode this message. (PDU: #{pdu})")
       end
       return info
     end
 
-
-    # Handles the abortion of a session, when a non-valid message has been received.
-    def handle_abort(session)
-      add_notice("An unregonizable (non-DICOM) message was received.")
+    # Handles the abortion of a session, when a non-valid or unexpected message has been received.
+    #
+    # === Parameters
+    #
+    # * <tt>default_message</tt> -- A boolean which unless set as nil/false will make the method print the default status message.
+    #
+    def handle_abort(default_message=true)
+      add_notice("An unregonizable (non-DICOM) message was received.") if default_message
       build_association_abort
-      transmit(session)
+      transmit
     end
 
-
-    # Handles the association accept.
-    def handle_association_accept(session, info, syntax_result)
+    # Handles the outgoing association accept message.
+    #
+    # === Parameters
+    #
+    # * <tt>info</tt> -- The association information hash.
+    #
+    def handle_association_accept(info)
       # Update the variable for calling ae (information gathered in the association request):
       @ae = info[:calling_ae]
-      application_context = info[:application_context]
+      # Build message string and send it:
       set_user_information_array(info)
-      build_association_accept(info, application_context, @user_information, syntax_result)
-      transmit(session)
+      build_association_accept(info)
+      transmit
     end
 
-
-    # Process the data that was received from the user.
-    # We expect this to be an initial C-STORE-RQ followed by a bunch of data fragments.
-    def handle_incoming_data(session, path)
+    # Processes incoming command & data fragments for the DServer.
+    # Returns a success boolean and an array of status messages.
+    #
+    # === Notes
+    #
+    # The incoming traffic will in most cases be: A C-STORE-RQ (command fragment) followed by a bunch of data fragments.
+    # However, it may also be a C-ECHO-RQ command fragment, which is used to test connections.
+    #
+    # === Parameters
+    #
+    # * <tt>path</tt> -- The path used to save incoming DICOM files.
+    #
+    #--
+    # FIXME: The code which handles incoming data isnt quite satisfactory. It would probably be wise to rewrite it at some stage to clean up
+    # the code somewhat. Probably a better handling of command requests (and their corresponding data fragments) would be a good idea.
+    #
+    def handle_incoming_data(path)
       # Wait for incoming data:
-      segments = receive_multiple_transmissions(session, file = true)
+      segments = receive_multiple_transmissions(file=true)
       # Reset command results arrays:
       @command_results = Array.new
       @data_results = Array.new
-      # Try to extract data:
-      file_data = Array.new
+      file_transfer_syntaxes = Array.new
+      files = Array.new
+      single_file_data = Array.new
+      # Proceed to extract data from the captured segments:
       segments.each do |info|
         if info[:valid]
           # Determine if it is command or data:
-          if info[:presentation_context_flag] == "00" or info[:presentation_context_flag] == "02"
-            # Data (last fragment)
+          if info[:presentation_context_flag] == DATA_MORE_FRAGMENTS
             @data_results << info[:results]
-            file_data  << info[:bin]
-          elsif info[:presentation_context_flag] == "03"
-            # Command (last fragment):
+            single_file_data  << info[:bin]
+          elsif info[:presentation_context_flag] == DATA_LAST_FRAGMENT
+            @data_results << info[:results]
+            single_file_data  << info[:bin]
+            # Join the recorded data binary strings together to make a DICOM file binary string and put it in our files Array:
+            files << single_file_data.join
+            single_file_data = Array.new
+          elsif info[:presentation_context_flag] == COMMAND_LAST_FRAGMENT
             @command_results << info[:results]
-            @presentation_context_id = info[:presentation_context_id]
+            @presentation_context_id = info[:presentation_context_id] # Does this actually do anything useful?
+            file_transfer_syntaxes << @presentation_contexts[info[:presentation_context_id]]
           end
         end
       end
-      data = file_data.join
-      if data.length > 8
-        # Read the received data stream and load it as a DICOM object:
-        obj = DObject.new(data, :bin => true, :syntax => @transfer_syntax)
-        # The actual handling of the DICOM object and (processing, saving, database storage, retransmission, etc)
-        # is handled by the external FileHandler class, in order to make it as easy as possible for users to write
-        # their own customised solutions for handling the incoming DICOM files:
-        success, message = @file_handler.receive_file(obj, path, @transfer_syntax)
-      else
-        # Valid DICOM data not received:
-        success = false
-        message = "Error: Invalid data received (the data was too small to be a valid DICOM file)."
-      end
-      return success, message
+      # Process the received files using the customizable FileHandler class:
+      success, messages = @file_handler.receive_files(path, files, file_transfer_syntaxes)
+      return success, messages
     end
 
-
-    # Handles the rejection of an association, when the formalities of the association is not correct.
-    def handle_rejection(session)
+    # Handles the rejection message (The response used to an association request when its formalities are not correct).
+    #
+    def handle_rejection
       add_notice("An incoming association request was rejected. Error code: #{association_error}")
       # Insert the error code in the info hash:
       info[:reason] = association_error
       # Send an association rejection:
       build_association_reject(info)
-      transmit(session)
+      transmit
     end
 
-
-    # Handles the release of an association.
-    def handle_release(session)
-      segments = receive_single_transmission(session)
-      info = segments.first
-      if info[:pdu] == "05"
-        add_notice("Received a release request. Releasing association.")
-        build_release_response
-        transmit(session)
-      end
+    # Handles the release message (which is the response to a release request).
+    #
+    def handle_release
+      stop_receiving
+      add_notice("Received a release request. Releasing association.")
+      build_release_response
+      transmit
+      stop_session
     end
 
-
-    # Handles the response (C-STORE-RSP) when a DICOM object has been (successfully) received.
-    def handle_response(session)
-      tags = @command_results.first
+    # Handles the command fragment response.
+    #
+    # === Notes
+    #
+    # This is usually a C-STORE-RSP which follows the (successful) reception of a DICOM file, but may also
+    # be a C-ECHO-RSP in response to an echo request.
+    #
+    def handle_response
       # Need to construct the command elements array:
       command_elements = Array.new
       # SOP Class UID:
-      command_elements << ["0000,0002", "UI", tags["0000,0002"]]
+      command_elements << ["0000,0002", "UI", @command_request["0000,0002"]]
       # Command Field:
-      command_elements << ["0000,0100", "US", 32769] # C-STORE-RSP
+      command_elements << ["0000,0100", "US", command_field_response(@command_request["0000,0100"])]
       # Message ID Being Responded To:
-      command_elements << ["0000,0120", "US", tags["0000,0110"]] # (Message ID)
+      command_elements << ["0000,0120", "US", @command_request["0000,0110"]]
       # Data Set Type:
-      command_elements << ["0000,0800", "US", 257]
+      command_elements << ["0000,0800", "US", NO_DATA_SET_PRESENT]
       # Status:
-      command_elements << ["0000,0900", "US", 0] # (Success)
+      command_elements << ["0000,0900", "US", SUCCESS]
       # Affected SOP Instance UID:
-      command_elements << ["0000,1000", "UI", tags["0000,1000"]]
-      pdu = "04"
-      context = @presentation_context_id
-      flag = "03" # (Command, last fragment)
-      build_command_fragment(pdu, context, flag, command_elements)
-      transmit(session)
+      command_elements << ["0000,1000", "UI", @command_request["0000,1000"]] if @command_request["0000,1000"]
+      build_command_fragment(PDU_DATA, @presentation_context_id, COMMAND_LAST_FRAGMENT, command_elements)
+      transmit
     end
 
-
-    # Decode an incoming transmission., decide its type, and forward its content to the various methods that process these.
-    def interpret(message, file = nil)
+    # Decodes the header of an incoming message, analyzes its real length versus expected length, and handles any
+    # deviations to make sure that message strings are split up appropriately before they are being forwarded to interpretation.
+    # Returns an array of information hashes.
+    #
+    # === Parameters
+    #
+    # * <tt>message</tt> -- The binary message string.
+    # * <tt>file</tt> -- A boolean used to inform whether an incoming data fragment is part of a DICOM file reception or not.
+    #
+    #--
+    # FIXME: This method is rather complex and doesnt feature the best readability. A rewrite that is able to simplify it would be lovely.
+    #
+    def interpret(message, file=nil)
       if @first_part
         message = @first_part + message
         @first_part = nil
@@ -419,7 +520,7 @@ module DICOM
       # If the message is at least 8 bytes we can start decoding it:
       if message.length > 8
         # Create a new Stream instance to handle this response.
-        msg = Stream.new(message, @net_endian, @explicit)
+        msg = Stream.new(message, @net_endian)
         # PDU type ( 1 byte)
         pdu = msg.decode(1, "HEX")
         # Reserved (1 byte)
@@ -468,11 +569,16 @@ module DICOM
       return segments
     end
 
-
-    # Decode the binary string received when the provider wishes to abort the connection, for some reason.
+    # Decodes the message received when the remote node wishes to abort the session.
+    # Returns the processed information hash.
+    #
+    # === Parameters
+    #
+    # * <tt>message</tt> -- The binary message string.
+    #
     def interpret_abort(message)
       info = Hash.new
-      msg = Stream.new(message, @net_endian, @explicit)
+      msg = Stream.new(message, @net_endian)
       # Reserved (2 bytes)
       reserved_bytes = msg.skip(2)
       # Source (1 byte)
@@ -488,11 +594,16 @@ module DICOM
       return info
     end
 
-
-    # Decode the binary string received in the association response, and interpret its content.
+    # Decodes the message received in the association response, and interprets its content.
+    # Returns the processed information hash.
+    #
+    # === Parameters
+    #
+    # * <tt>message</tt> -- The binary message string.
+    #
     def interpret_association_accept(message)
       info = Hash.new
-      msg = Stream.new(message, @net_endian, @explicit)
+      msg = Stream.new(message, @net_endian)
       # Protocol version (2 bytes)
       info[:protocol_version] = msg.decode(2, "HEX")
       # Reserved (2 bytes)
@@ -513,32 +624,48 @@ module DICOM
       # Application context (variable length)
       info[:application_context] = msg.decode(info[:application_item_length], "STR")
       # PRESENTATION CONTEXT:
-      # Item type (1 byte)
-      info[:presentation_item_type] = msg.decode(1, "HEX")
-      # Reserved (1 byte)
-      msg.skip(1)
-      # Presentation item length (2 bytes)
-      info[:presentation_item_length] = msg.decode(2, "US")
-      # Presentation context ID (1 byte)
-      info[:presentation_context_id] = msg.decode(1, "HEX")
-      # Reserved (1 byte)
-      msg.skip(1)
-      # Result (& Reason) (1 byte)
-      info[:result] = msg.decode(1, "BY")
-      process_result(info[:result])
-      # Reserved (1 byte)
-      msg.skip(1)
-      # Transfer syntax sub-item:
-      # Item type (1 byte)
-      info[:transfer_syntax_item_type] = msg.decode(1, "HEX")
-      # Reserved (1 byte)
-      msg.skip(1)
-      # Transfer syntax item length (2 bytes)
-      info[:transfer_syntax_item_length] = msg.decode(2, "US")
-      # Transfer syntax name (variable length)
-      info[:transfer_syntax] = msg.decode(info[:transfer_syntax_item_length], "STR")
+      # As multiple presentation contexts may occur, we need a loop to catch them all:
+      # Each presentation context hash will be put in an array, which will be put in the info hash.
+      presentation_contexts = Array.new
+      pc_loop = true
+      while pc_loop do
+        # Item type (1 byte)
+        item_type = msg.decode(1, "HEX")
+        if item_type == ITEM_PRESENTATION_CONTEXT_RESPONSE
+          pc = Hash.new
+          pc[:presentation_item_type] = item_type
+          # Reserved (1 byte)
+          msg.skip(1)
+          # Presentation item length (2 bytes)
+          pc[:presentation_item_length] = msg.decode(2, "US")
+          # Presentation context ID (1 byte)
+          pc[:presentation_context_id] = msg.decode(1, "BY")
+          # Reserved (1 byte)
+          msg.skip(1)
+          # Result (& Reason) (1 byte)
+          pc[:result] = msg.decode(1, "BY")
+          process_result(pc[:result])
+          # Reserved (1 byte)
+          msg.skip(1)
+          # Transfer syntax sub-item:
+          # Item type (1 byte)
+          pc[:transfer_syntax_item_type] = msg.decode(1, "HEX")
+          # Reserved (1 byte)
+          msg.skip(1)
+          # Transfer syntax item length (2 bytes)
+          pc[:transfer_syntax_item_length] = msg.decode(2, "US")
+          # Transfer syntax name (variable length)
+          pc[:transfer_syntax] = msg.decode(pc[:transfer_syntax_item_length], "STR")
+          presentation_contexts << pc
+        else
+          # Break the presentation context loop, as we have probably reached the next stage, which is user info. Rewind:
+          msg.skip(-1)
+          pc_loop = false
+        end
+      end
+      info[:pc] = presentation_contexts
       # USER INFORMATION:
-      # Item type (1 byte) ("50")
+      # Item type (1 byte)
       info[:user_info_item_type] = msg.decode(1, "HEX")
       # Reserved (1 byte)
       msg.skip(1)
@@ -552,35 +679,54 @@ module DICOM
         # Item length (2 bytes)
         item_length = msg.decode(2, "US")
         case item_type
-          when "51"
+          when ITEM_MAX_LENGTH
             info[:max_pdu_length] = msg.decode(item_length, "UL")
             @max_receive_size = info[:max_pdu_length]
-          when "52"
+          when ITEM_IMPLEMENTATION_UID
             info[:implementation_class_uid] = msg.decode(item_length, "STR")
-          when "53"
+          when ITEM_MAX_OPERATIONS_INVOKED
             # Asynchronous operations window negotiation (PS 3.7: D.3.3.3) (2*2 bytes)
             info[:maxnum_operations_invoked] = msg.decode(2, "US")
             info[:maxnum_operations_performed] = msg.decode(2, "US")
-          when "55"
+          when ITEM_ROLE_NEGOTIATION
+            # SCP/SCU Role Selection Negotiation (PS 3.7 D.3.3.4)
+            # Note: An association response may contain several instances of this item type (each with a different abstract syntax).
+            uid_length = msg.decode(2, "US")
+            role = Hash.new
+            # SOP Class UID (Abstract syntax):
+            role[:sop_uid] = msg.decode(uid_length, "STR")
+            # SCU Role (1 byte):
+            role[:scu] = msg.decode(1, "BY")
+            # SCP Role (1 byte):
+            role[:scp] = msg.decode(1, "BY")
+            if info[:role_negotiation]
+              info[:role_negotiation] << role
+            else
+              info[:role_negotiation] = [role]
+            end
+          when ITEM_IMPLEMENTATION_VERSION
             info[:implementation_version] = msg.decode(item_length, "STR")
           else
             # Value (variable length)
             value = msg.decode(item_length, "STR")
-            add_error("Unknown user info item type received. Please update source code or contact author. (item type: " + item_type + ")")
+            add_error("Unknown user info item type received. Please update source code or contact author. (item type: #{item_type})")
         end
       end
       stop_receiving
       info[:valid] = true
-      # Update transfer syntax settings for this instance:
-      set_transfer_syntax(info[:transfer_syntax])
       return info
-    end # of interpret_association_accept
-
+    end
 
-    # Decode the association reject message and extract the error reasons given.
+    # Decodes the association reject message and extracts the error reasons given.
+    # Returns the processed information hash.
+    #
+    # === Parameters
+    #
+    # * <tt>message</tt> -- The binary message string.
+    #
     def interpret_association_reject(message)
       info = Hash.new
-      msg = Stream.new(message, @net_endian, @explicit)
+      msg = Stream.new(message, @net_endian)
       # Reserved (1 byte)
       msg.skip(1)
       # Result (1 byte)
@@ -595,11 +741,16 @@ module DICOM
       return info
     end
 
-
-    # Decode the binary string received in the association request, and interpret its content.
+    # Decodes the binary string received in the association request, and interprets its content.
+    # Returns the processed information hash.
+    #
+    # === Parameters
+    #
+    # * <tt>message</tt> -- The binary message string.
+    #
     def interpret_association_request(message)
       info = Hash.new
-      msg = Stream.new(message, @net_endian, @explicit)
+      msg = Stream.new(message, @net_endian)
       # Protocol version (2 bytes)
       info[:protocol_version] = msg.decode(2, "HEX")
       # Reserved (2 bytes)
@@ -612,7 +763,7 @@ module DICOM
       msg.skip(32)
       # APPLICATION CONTEXT:
       # Item type (1 byte)
-      info[:application_item_type] = msg.decode(1, "HEX") # "10"
+      info[:application_item_type] = msg.decode(1, "HEX") # 10H
       # Reserved (1 byte)
       msg.skip(1)
       # Application item length (2 bytes)
@@ -627,7 +778,7 @@ module DICOM
       while pc_loop do
         # Item type (1 byte)
         item_type = msg.decode(1, "HEX")
-        if item_type == "20"
+        if item_type == ITEM_PRESENTATION_CONTEXT_REQUEST
           pc = Hash.new
           pc[:presentation_item_type] = item_type
           # Reserved (1 byte)
@@ -635,14 +786,14 @@ module DICOM
           # Presentation context item length (2 bytes)
           pc[:presentation_item_length] = msg.decode(2, "US")
           # Presentation context id (1 byte)
-          pc[:presentation_context_id] = msg.decode(1, "HEX")
+          pc[:presentation_context_id] = msg.decode(1, "BY")
           # Reserved (3 bytes)
           msg.skip(3)
           presentation_contexts << pc
           # A presentation context contains an abstract syntax and one or more transfer syntaxes.
           # ABSTRACT SYNTAX SUB-ITEM:
           # Abstract syntax item type (1 byte)
-          pc[:abstract_syntax_item_type] = msg.decode(1, "HEX") # "30"
+          pc[:abstract_syntax_item_type] = msg.decode(1, "HEX")
           # Reserved (1 byte)
           msg.skip(1)
           # Abstract syntax item length (2 bytes)
@@ -657,7 +808,7 @@ module DICOM
           while ts_loop do
             # Item type (1 byte)
             item_type = msg.decode(1, "HEX")
-            if item_type == "40"
+            if item_type == ITEM_TRANSFER_SYNTAX
               ts = Hash.new
               ts[:transfer_syntax_item_type] = item_type
               # Reserved (1 byte)
@@ -698,15 +849,31 @@ module DICOM
         # Item length (2 bytes)
         item_length = msg.decode(2, "US")
         case item_type
-          when "51"
+          when ITEM_MAX_LENGTH
             info[:max_pdu_length] = msg.decode(item_length, "UL")
-          when "52"
+          when ITEM_IMPLEMENTATION_UID
             info[:implementation_class_uid] = msg.decode(item_length, "STR")
-          when "53"
+          when ITEM_MAX_OPERATIONS_INVOKED
             # Asynchronous operations window negotiation (PS 3.7: D.3.3.3) (2*2 bytes)
             info[:maxnum_operations_invoked] = msg.decode(2, "US")
             info[:maxnum_operations_performed] = msg.decode(2, "US")
-          when "55"
+          when ITEM_ROLE_NEGOTIATION
+            # SCP/SCU Role Selection Negotiation (PS 3.7 D.3.3.4)
+            # Note: An association request may contain several instances of this item type (each with a different abstract syntax).
+            uid_length = msg.decode(2, "US")
+            role = Hash.new
+            # SOP Class UID (Abstract syntax):
+            role[:sop_uid] = msg.decode(uid_length, "STR")
+            # SCU Role (1 byte):
+            role[:scu] = msg.decode(1, "BY")
+            # SCP Role (1 byte):
+            role[:scp] = msg.decode(1, "BY")
+            if info[:role_negotiation]
+              info[:role_negotiation] << role
+            else
+              info[:role_negotiation] = [role]
+            end
+          when ITEM_IMPLEMENTATION_VERSION
             info[:implementation_version] = msg.decode(item_length, "STR")
           else
             # Unknown item type:
@@ -718,27 +885,39 @@ module DICOM
       stop_receiving
       info[:valid] = true
       return info
-    end # of interpret_association_request
-
+    end
 
-    # Decode the received command/data binary string, and interpret its content.
-    # Decoding of data fragment will depend on the explicitness of the transmission.
-    def interpret_command_and_data(message, file = nil)
+    # Decodes the received command/data fragment message, and interprets its content.
+    # Returns the processed information hash.
+    #
+    # === Notes
+    #
+    # * Decoding of a data fragment depends on the explicitness of the transmission.
+    #
+    # === Parameters
+    #
+    # * <tt>message</tt> -- The binary message string.
+    # * <tt>file</tt> -- A boolean used to inform whether an incoming data fragment is part of a DICOM file reception or not.
+    #
+    def interpret_command_and_data(message, file=nil)
       info = Hash.new
-      msg = Stream.new(message, @net_endian, @explicit)
+      msg = Stream.new(message, @net_endian)
       # Length (of remaining PDV data) (4 bytes)
       info[:presentation_data_value_length] = msg.decode(4, "UL")
       # Calculate the last index position of this message element:
       last_index = info[:presentation_data_value_length] + msg.index
       # Presentation context ID (1 byte)
-      info[:presentation_context_id] = msg.decode(1, "HEX") # "01" expected
+      info[:presentation_context_id] = msg.decode(1, "BY")
+      @presentation_context_id = info[:presentation_context_id]
       # Flags (1 byte)
       info[:presentation_context_flag] = msg.decode(1, "HEX") # "03" for command (last fragment), "02" for data
-      # Little endian encoding from now on:
-      msg.set_endian(@data_endian)
+      # Apply the proper transfer syntax for this presentation context:
+      set_transfer_syntax(@presentation_contexts[info[:presentation_context_id]])
+      # "Data endian" encoding from now on:
+      msg.endian = @data_endian
       # We will put the results in a hash:
       results = Hash.new
-      if info[:presentation_context_flag] == "03"
+      if info[:presentation_context_flag] == COMMAND_LAST_FRAGMENT
         # COMMAND, LAST FRAGMENT:
         while msg.index < last_index do
           # Tag (4 bytes)
@@ -761,22 +940,28 @@ module DICOM
         end
         # The results hash is put in an array along with (possibly) other results:
         info[:results] = results
+        # Store the results in an instance variable (to be used later when sending a receipt for received data):
+        @command_request = results
         # Check if the command fragment indicates that this was the last of the response fragments for this query:
         status = results["0000,0900"]
         if status
           # Note: This method will also stop the packet receiver if indicated by the status mesasge.
           process_status(status)
         end
-      elsif info[:presentation_context_flag] == "00" or info[:presentation_context_flag] == "02"
+        # Special case: Handle a possible C-ECHO-RQ:
+        if info[:results]["0000,0100"] == C_ECHO_RQ
+          add_notice("Received an Echo request. Returning an Echo response.")
+          handle_response
+        end
+      elsif info[:presentation_context_flag] == DATA_MORE_FRAGMENTS or info[:presentation_context_flag] == DATA_LAST_FRAGMENT
         # DATA FRAGMENT:
         # If this is a file transmission, we will delay the decoding for later:
         if file
           # Just store the binary string:
           info[:bin] = msg.rest_string
-          # Abort the listening if this is last data fragment:
-          if info[:presentation_context_flag] == "02"
-            stop_receiving
-          end
+          # If this was the last data fragment of a C-STORE, we need to send a receipt:
+          # (However, for, say a C-FIND-RSP, which indicates the end of the query results, this method shall not be called) (Command Field (0000,0100) holds information on this)
+          handle_response if info[:presentation_context_flag] == DATA_LAST_FRAGMENT
         else
           # Decode data elements:
           while msg.index < last_index do
@@ -819,23 +1004,33 @@ module DICOM
       return info
     end
 
-
-    # Decode the binary string received in the release request, and interpret its content.
+    # Decodes the message received in the release request and calls the handle_release method.
+    # Returns the processed information hash.
+    #
+    # === Parameters
+    #
+    # * <tt>message</tt> -- The binary message string.
+    #
     def interpret_release_request(message)
       info = Hash.new
-      msg = Stream.new(message, @net_endian, @explicit)
+      msg = Stream.new(message, @net_endian)
       # Reserved (4 bytes)
       reserved_bytes = msg.decode(4, "HEX")
-      stop_receiving
+      handle_release
       info[:valid] = true
       return info
     end
 
-
-    # Decode the binary string received in the release response, and interpret its content.
+    # Decodes the message received in the release response and closes the connection.
+    # Returns the processed information hash.
+    #
+    # === Parameters
+    #
+    # * <tt>message</tt> -- The binary message string.
+    #
     def interpret_release_response(message)
       info = Hash.new
-      msg = Stream.new(message, @net_endian, @explicit)
+      msg = Stream.new(message, @net_endian)
       # Reserved (4 bytes)
       reserved_bytes = msg.decode(4, "HEX")
       stop_receiving
@@ -843,14 +1038,19 @@ module DICOM
       return info
     end
 
-
-    # Handle multiple incoming transmissions and return the interpreted, received data.
-    def receive_multiple_transmissions(session, file = nil)
+    # Handles the reception of multiple incoming transmissions.
+    # Returns an array of interpreted message information hashes.
+    #
+    # === Parameters
+    #
+    # * <tt>file</tt> -- A boolean used to inform whether an incoming data fragment is part of a DICOM file reception or not.
+    #
+    def receive_multiple_transmissions(file=nil)
       @listen = true
       segments = Array.new
       while @listen
         # Receive data and append the current data to our segments array, which will be returned.
-        data = receive_transmission(session, @min_length)
+        data = receive_transmission(@min_length)
         current_segments = interpret(data, file)
         if current_segments
           current_segments.each do |cs|
@@ -862,20 +1062,47 @@ module DICOM
       return segments
     end
 
-
-    # Handle an expected single incoming transmission and return the interpreted, received data.
-    def receive_single_transmission(session)
+    # Handles the reception of a single, expected incoming transmission and returns the interpreted, received data.
+    #
+    def receive_single_transmission
       min_length = 8
-      data = receive_transmission(session, min_length)
+      data = receive_transmission(min_length)
       segments = interpret(data)
       segments << {:valid => false} unless segments.length > 0
       return segments
     end
 
+    # Sets the session of this Link instance (used when this session is already established externally).
+    #
+    # === Parameters
+    #
+    # * <tt>session</tt> -- A TCP network connection that has been established with a remote node.
+    #
+    def set_session(session)
+      @session = session
+    end
+
+    # Establishes a new session with a remote network node.
+    #
+    # === Parameters
+    #
+    # * <tt>adress</tt> -- String. The adress (IP) of the remote node.
+    # * <tt>port</tt> -- Fixnum. The network port to be used in the network communication.
+    #
+    def start_session(adress, port)
+      @session = TCPSocket.new(adress, port)
+    end
+
+    # Ends the current session by closing the connection.
+    #
+    def stop_session
+      @session.close unless @session.closed?
+    end
 
-    # Send the encoded binary string (package) to its destination.
-    def transmit(session)
-      session.send(@outgoing.string, 0)
+    # Sends the outgoing message (encoded binary string) to the remote node.
+    #
+    def transmit
+      @session.send(@outgoing.string, 0)
     end
 
 
@@ -884,25 +1111,38 @@ module DICOM
 
 
     # Adds a warning or error message to the instance array holding messages,
-    # and if verbose variable is true, prints the message as well.
+    # and prints the information to the screen if verbose is set.
+    #
+    # === Parameters
+    #
+    # * <tt>error</tt> -- A single error message or an array of error messages.
+    #
     def add_error(error)
       puts error if @verbose
       @errors << error
     end
 
-
     # Adds a notice (information regarding progress or successful communications) to the instance array,
-    # and if verbosity is set for these kinds of messages, prints it to the screen as well.
+    # and prints the information to the screen if verbose is set.
+    #
+    # === Parameters
+    #
+    # * <tt>notice</tt> -- A single status message or an array of status messages.
+    #
     def add_notice(notice)
       puts notice if @verbose
       @notices << notice
     end
 
-
-    # Builds the application context that is part of the association request.
+    # Builds the application context (which is part of the association request/response).
+    #
+    # === Parameters
+    #
+    # * <tt>ac_uid</tt> -- Application context UID string.
+    #
     def append_application_context(ac_uid)
       # Application context item type (1 byte)
-      @outgoing.encode_last("10", "HEX")
+      @outgoing.encode_last(ITEM_APPLICATION_CONTEXT, "HEX")
       # Reserved (1 byte)
       @outgoing.encode_last("00", "HEX")
       # Application context item length (2 bytes)
@@ -911,11 +1151,16 @@ module DICOM
       @outgoing.encode_last(ac_uid, "STR")
     end
 
-
-    # Build the binary string that makes up the header part (part of the association request).
-    def append_association_header(pdu)
+    # Builds the binary string that makes up the header part the association request/response.
+    #
+    # === Parameters
+    #
+    # * <tt>pdu</tt> -- The command fragment's PDU string.
+    # * <tt>called_ae</tt> -- Application entity (name) of the SCP (host).
+    #
+    def append_association_header(pdu, called_ae)
       # Big endian encoding:
-      @outgoing.set_endian(@net_endian)
+      @outgoing.endian = @net_endian
       # Header will be encoded in opposite order, where the elements are being put first in the outgoing binary string.
       # Build last part of header first. This is necessary to be able to assess the length value.
       # Reserved (32 bytes)
@@ -923,9 +1168,9 @@ module DICOM
       # Calling AE title (16 bytes)
       calling_ae = @outgoing.encode_string_with_trailing_spaces(@ae, 16)
       @outgoing.add_first(calling_ae) # (pre-encoded value)
-      # Called AE title (16 bytes)
-      called_ae = @outgoing.encode_string_with_trailing_spaces(@host_ae, 16)
-      @outgoing.add_first(called_ae) # (pre-encoded value)
+      # Called AE title (16 bytes) (return the name that the SCU used in the association request)
+      formatted_called_ae = @outgoing.encode_string_with_trailing_spaces(called_ae, 16)
+      @outgoing.add_first(formatted_called_ae) # (pre-encoded value)
       # Reserved (2 bytes)
       @outgoing.encode_first("0000", "HEX")
       # Protocol version (2 bytes)
@@ -933,9 +1178,12 @@ module DICOM
       append_header(pdu)
     end
 
-
-    # Adds the header bytes to the outgoing, binary string (this part has the same structure for all dicom network messages)
-    # PDU: "01", "02", etc..
+    # Adds the header bytes to the outgoing message (the header structure is equal for all of the message types).
+    #
+    # === Parameters
+    #
+    # * <tt>pdu</tt> -- The command fragment's PDU string.
+    #
     def append_header(pdu)
       # Length (of remaining data) (4 bytes)
       @outgoing.encode_first(@outgoing.string.length, "UL")
@@ -945,68 +1193,94 @@ module DICOM
       @outgoing.encode_first(pdu, "HEX")
     end
 
-
-    # Build the binary string that makes up the presentation context part (part of the association request).
-    # For a list of error codes, see the official DICOM PS3.8 document, (page 39).
-    def append_presentation_context(as, pc, ts, context_id = "01", result = "00")
-      # PRESENTATION CONTEXT:
-      # Presentation context item type (1 byte)
-      @outgoing.encode_last(pc, "HEX") # "20" (request) & "21" (response)
-      # Reserved (1 byte)
-      @outgoing.encode_last("00", "HEX")
-      # Presentation context item length (2 bytes)
-      if ts.is_a?(Array)
-        ts_length = 4*ts.length + ts.join.length
-      else # (String)
-        ts_length = 4 + ts.length
-      end
-      if as
-        items_length = 4 + (4 + as.length) + ts_length
-      else
-        items_length = 4 + ts_length
-      end
-      @outgoing.encode_last(items_length, "US")
-      # Presentation context ID (1 byte)
-      @outgoing.encode_last(context_id, "HEX")
-      # Reserved (1 byte)
-      @outgoing.encode_last("00", "HEX")
-      # (1 byte) Reserved (for association request) & Result/reason (for association accept response)
-      @outgoing.encode_last(result, "HEX")
-      # Reserved (1 byte)
-      @outgoing.encode_last("00", "HEX")
-      ## ABSTRACT SYNTAX SUB-ITEM: (only for request, not response)
-      if as
-        # Abstract syntax item type (1 byte)
-        @outgoing.encode_last("30", "HEX")
+    # Builds the binary string that makes up the presentation context part of the association request/accept.
+    #
+    # === Notes
+    #
+    # * The values of the parameters will differ somewhat depending on whether this is related to a request or response.
+    # * Description of error codes are given in the DICOM Standard, PS 3.8, Chapter 9.3.3.2 (Table 9-18).
+    #
+    # === Parameters
+    #
+    # * <tt>abstract_syntaxes</tt> -- An array of abstract syntax strings.
+    # * <tt>pc</tt> -- Presentation context item (request or response).
+    # * <tt>ts</tt> -- An array of transfer syntax strings.
+    # * <tt>context_id</tt> -- The ID of the current presentation context.
+    # * <tt>result</tt> -- The result (accepted/refused) for the current presentation context.
+    #
+    def append_presentation_contexts(abstract_syntaxes, pc, ts, context_id=nil, result=ACCEPTANCE)
+      # One presentation context for each abstract syntax:
+      abstract_syntaxes.each_with_index do |as, index|
+        # PRESENTATION CONTEXT:
+        # Presentation context item type (1 byte)
+        @outgoing.encode_last(pc, "HEX")
         # Reserved (1 byte)
         @outgoing.encode_last("00", "HEX")
-        # Abstract syntax item length (2 bytes)
-        @outgoing.encode_last(as.length, "US")
-        # Abstract syntax (variable length)
-        @outgoing.encode_last(as, "STR")
-      end
-      ## TRANSFER SYNTAX SUB-ITEM:
-      ts = [ts] if ts.is_a?(String)
-      ts.each do |t|
-        # Transfer syntax item type (1 byte)
-        @outgoing.encode_last("40", "HEX")
+        # Presentation context item length (2 bytes)
+        if ts.is_a?(Array)
+          ts_length = 4*ts.length + ts.join.length
+        else # (String)
+          ts_length = 4 + ts.length
+        end
+        if as
+          items_length = 4 + (4 + as.length) + ts_length
+        else
+          items_length = 4 + ts_length
+        end
+        @outgoing.encode_last(items_length, "US")
+        # Presentation context ID (1 byte)
+        # Generate a number based on the index of the abstract syntax, unless one has been supplied to this method already.
+        # (NB! This number should be odd, and in the range 1..255)
+        if context_id
+          presentation_context_id = context_id
+        else
+          presentation_context_id = index*2 + 1
+        end
+        @outgoing.encode_last(presentation_context_id, "BY")
+        # Reserved (1 byte)
+        @outgoing.encode_last("00", "HEX")
+        # (1 byte) Reserved (for association request) & Result/reason (for association accept response)
+        @outgoing.encode_last(result, "BY")
         # Reserved (1 byte)
         @outgoing.encode_last("00", "HEX")
-        # Transfer syntax item length (2 bytes)
-        @outgoing.encode_last(t.length, "US")
-        # Transfer syntax (variable length)
-        @outgoing.encode_last(t, "STR")
+        ## ABSTRACT SYNTAX SUB-ITEM: (only for request, not response)
+        if as
+          # Abstract syntax item type (1 byte)
+          @outgoing.encode_last(ITEM_ABSTRACT_SYNTAX, "HEX")
+          # Reserved (1 byte)
+          @outgoing.encode_last("00", "HEX")
+          # Abstract syntax item length (2 bytes)
+          @outgoing.encode_last(as.length, "US")
+          # Abstract syntax (variable length)
+          @outgoing.encode_last(as, "STR")
+        end
+        ## TRANSFER SYNTAX SUB-ITEM (not included if result indicates error):
+        if result == ACCEPTANCE
+          ts = [ts] if ts.is_a?(String)
+          ts.each do |t|
+            # Transfer syntax item type (1 byte)
+            @outgoing.encode_last(ITEM_TRANSFER_SYNTAX, "HEX")
+            # Reserved (1 byte)
+            @outgoing.encode_last("00", "HEX")
+            # Transfer syntax item length (2 bytes)
+            @outgoing.encode_last(t.length, "US")
+            # Transfer syntax (variable length)
+            @outgoing.encode_last(t, "STR")
+          end
+        end
       end
-      # Update transfer syntax settings for this instance:
-      set_transfer_syntax(ts.first)
     end
 
-
-    # Adds the binary string that makes up the user information (part of the association request).
+    # Adds the binary string that makes up the user information part of the association request/response.
+    #
+    # === Parameters
+    #
+    # * <tt>ui</tt> -- User information items array.
+    #
     def append_user_information(ui)
       # USER INFORMATION:
       # User information item type (1 byte)
-      @outgoing.encode_last("50", "HEX")
+      @outgoing.encode_last(ITEM_USER_INFORMATION, "HEX")
       # Reserved (1 byte)
       @outgoing.encode_last("00", "HEX")
       # Encode the user information item values so we can determine the remaining length of this section:
@@ -1030,9 +1304,30 @@ module DICOM
       end
     end
 
+    # Returns the appropriate response value for the Command Field (0000,0100) to be used in a command fragment (response).
+    #
+    # === Parameters
+    #
+    # * <tt>request</tt> -- The Command Field value in a command fragment (request).
+    #
+    def command_field_response(request)
+      case request
+        when C_STORE_RQ
+          return C_STORE_RSP
+        when C_ECHO_RQ
+          return C_ECHO_RSP
+        else
+          add_error("Unknown or unsupported request (#{request}) encountered.")
+          return C_CANCEL_RQ
+      end
+    end
 
-    # Process the value of the reason byte (in an association abort).
-    # This will provide information on what is the reason for the error.
+    # Processes the value of the reason byte received in the association abort, and prints an explanation of the error.
+    #
+    # === Parameters
+    #
+    # * <tt>reason</tt> -- String. Reason code for an error that has occured.
+    #
     def process_reason(reason)
       case reason
         when "00"
@@ -1052,9 +1347,17 @@ module DICOM
       end
     end
 
-
-    # Process the value of the result byte (in the association response).
-    # Something is wrong if result is different from 0.
+    # Processes the value of the result byte received in the association response.
+    # Prints an explanation if an error is indicated.
+    #
+    # === Notes
+    #
+    # A value other than 0 indicates an error.
+    #
+    # === Parameters
+    #
+    # * <tt>result</tt> -- Fixnum. The result code from an association response.
+    #
     def process_result(result)
       unless result == 0
         # Analyse the result and report what is wrong:
@@ -1073,9 +1376,12 @@ module DICOM
       end
     end
 
-
-    # Process the value of the source byte (in an association abort).
-    # This will provide information on who is the source of the error.
+    # Processes the value of the source byte in the association abort, and prints an explanation of the source (of the error).
+    #
+    # === Parameters
+    #
+    # * <tt>source</tt> -- String. A code which informs which part has been the source of an error.
+    #
     def process_source(source)
       if source == "00"
         add_error("Warning: Connection has been aborted by the service provider because of an error by the service user (client side).")
@@ -1086,16 +1392,24 @@ module DICOM
       end
     end
 
-
-    # Process the value of the status tag 0000,0900 received in the command fragment.
-    # Note: The status tag has vr 'US', and the status as reported here is therefore a number.
-    # In the official DICOM documents however, the value of the various status options is given in hex format.
-    # Resources: DICOM PS3.4 Annex Q 2.1.1.4, DICOM PS3.7 Annex C 4.
+    # Processes the value of the status element (0000,0900) received in the command fragment.
+    # Prints an explanation where deemed appropriate.
+    #
+    # === Notes
+    #
+    # The status element has vr 'US', and the status as reported here is therefore a number.
+    # In the official DICOM documents however, the values of the various status options are given in hex format.
+    # Resources: The DICOM standard; PS3.4, Annex Q 2.1.1.4 & PS3.7 Annex C 4.
+    #
+    # === Parameters
+    #
+    # * <tt>status</tt> -- Fixnum. A status code from a command fragment.
+    #
     def process_status(status)
       case status
         when 0 # "0000"
           # Last fragment (Break the while loop that listens continuously for incoming packets):
-          add_notice("Receipt for successful execution of the desired request has been received. Closing communication.")
+          add_notice("Receipt for successful execution of the desired operation has been received.")
           stop_receiving
         when 42752 # "a700"
           # Failure: Out of resources. Related fields: 0000,0902
@@ -1126,19 +1440,27 @@ module DICOM
       end
     end
 
-
-    # Handles an incoming transmission.
-    # Optional: Specify a minimum length of the incoming transmission. (If a message is received
-    # which is shorter than this limit, the method will keep listening for more incoming packets to append)
-    def receive_transmission(session, min_length=0)
-      data = receive_transmission_data(session)
+    # Handles an incoming network transmission.
+    # Returns the binary string data received.
+    #
+    # === Notes
+    #
+    # If a minimum length has been specified, and a message is received which is shorter than this length,
+    # the method will keep listening for more incoming network packets to append.
+    #
+    # === Parameters
+    #
+    # * <tt>min_length</tt> -- Fixnum. The minimum possible length of a valid incoming transmission.
+    #
+    def receive_transmission(min_length=0)
+      data = receive_transmission_data
       # Check the nature of the received data variable:
       if data
         # Sometimes the incoming transmission may be broken up into smaller pieces:
         # Unless a short answer is expected, we will continue to listen if the first answer was too short:
         unless min_length == 0
-          if data.length <= min_length
-            addition = receive_transmission_data(session)
+          if data.length < min_length
+            addition = receive_transmission_data
             data = data + addition if addition
           end
         end
@@ -1150,13 +1472,14 @@ module DICOM
       return data
     end
 
-
-    # Receives the incoming transmission data.
-    def receive_transmission_data(session)
+    # Receives the data from an incoming network transmission.
+    # Returns the binary string data received.
+    #
+    def receive_transmission_data
       data = false
       t1 = Time.now.to_f
       @receive = true
-      thr = Thread.new{ data = session.recv(@max_receive_size); @receive = false }
+      thr = Thread.new{ data=@session.recv(@max_receive_size); @receive=false }
       while @receive
         if (Time.now.to_f - t1) > @timeout
           Thread.kill(thr)
@@ -1167,58 +1490,96 @@ module DICOM
       return data
     end
 
-
-    # Some default values.
+    # Sets some default values related to encoding.
+    #
     def set_default_values
       # Default endianness for network transmissions is Big Endian:
       @net_endian = true
       # Default endianness of data is little endian:
       @data_endian = false
       # It may turn out to be unncessary to define the following values at this early stage.
-      # Explicitness
-      @explicit = true
-      # Transfer syntax (Implicit, little endian):
-      set_transfer_syntax("1.2.840.10008.1.2")
+      # Explicitness:
+      @explicit = false
+      # Transfer syntax:
+      set_transfer_syntax(IMPLICIT_LITTLE_ENDIAN)
     end
 
-
-    # Set instance variables related to the transfer syntax.
-    def set_transfer_syntax(value)
+    # Set instance variables related to a transfer syntax.
+    #
+    # === Parameters
+    #
+    # * <tt>syntax</tt> -- A transfer syntax string.
+    #
+    def set_transfer_syntax(syntax)
+      @transfer_syntax = syntax
       # Query the library with our particular transfer syntax string:
-      result = LIBRARY.process_transfer_syntax(value)
-      # Result is a 3-element array: [Validity of ts, explicitness, endianness]
-      unless result[0]
+      valid_syntax, @explicit, @data_endian = LIBRARY.process_transfer_syntax(syntax)
+      unless valid_syntax
         add_error("Warning: Invalid/unknown transfer syntax encountered! Will try to continue, but errors may occur.")
       end
-      # Update encoding variables:
-      @explicit = result[1]
-      @data_endian = result[2]
-      @transfer_syntax = value
     end
 
-
-    # Set user information [item type code, vr/type, value]
-    def set_user_information_array(info = nil)
+    # Sets the @user_information items instance array.
+    #
+    # === Notes
+    #
+    # Each user information item is a three element array consisting of: item type code, VR & value.
+    #
+    # === Parameters
+    #
+    # * <tt>info</tt> -- An association information hash.
+    #
+    def set_user_information_array(info=nil)
       @user_information = [
-        ["51", "UL", @max_package_size], # Max PDU Length
-        ["52", "STR", UID],
-        ["55", "STR", NAME]
+        [ITEM_MAX_LENGTH, "UL", @max_package_size],
+        [ITEM_IMPLEMENTATION_UID, "STR", UID],
+        [ITEM_IMPLEMENTATION_VERSION, "STR", NAME]
       ]
-      # A bit of a hack to include "asynchronous operations window negotiation", if this has been included in the association request:
+      # A bit of a hack to include "asynchronous operations window negotiation" and/or "role negotiation",
+      # in cases where this has been included in the association request:
       if info
-        @user_information.insert(2, ["53", "HEX", "00010001"]) if info[:maxnum_operations_invoked]
+        if info[:maxnum_operations_invoked]
+          @user_information.insert(2, [ITEM_MAX_OPERATIONS_INVOKED, "HEX", "00010001"])
+        end
+        if info[:role_negotiation]
+          pos = 3
+          info[:role_negotiation].each do |role|
+            msg = Stream.new(message, @net_endian)
+            uid = role[:sop_uid]
+            # Length of UID (2 bytes):
+            msg.encode_first(uid.length, "US")
+            # SOP UID being negotiated (Variable length):
+            msg.encode_last(uid, "STR")
+            # SCU Role (Always accept SCU) (1 byte):
+            if role[:scu] == 1
+              msg.encode_last(1, "BY")
+            else
+              msg.encode_last(0, "BY")
+            end
+            # SCP Role (Never accept SCP) (1 byte):
+            if role[:scp] == 1
+              msg.encode_last(0, "BY")
+            else
+              msg.encode_last(1, "BY")
+            end
+            @user_information.insert(pos, [ITEM_ROLE_NEGOTIATION, "STR", msg.string])
+            pos += 1
+          end
+        end
       end
     end
 
-
-    # Breaks the loops that listen for incoming packets by changing a couple of instance variables.
+    # Toggles two instance variables that in causes the loops that listen for incoming network packets to break.
+    #
+    # === Notes
+    #
     # This method is called by the various methods that interpret incoming data when they have verified that
     # the entire message has been received, or when a timeout is reached.
+    #
     def stop_receiving
       @listen = false
       @receive = false
     end
 
-
-  end # of class
-end # of module
+  end
+end