dicom 0.7 → 0.8

data/lib/dicom/d_read.rb

@@ -0,0 +1,433 @@
+#    Copyright 2008-2010 Christoffer Lervag
+#
+# === Notes
+#
+# In addition to reading files that are compliant to DICOM 3 Part 10, the philosophy of the Ruby DICOM library is to feature maximum
+# compatibility, and as such it will also successfully read many types of 'DICOM' files that deviate in some way from the standard.
+
+module DICOM
+
+  # The DRead class parses the DICOM data from a binary string.
+  #
+  # The source of this binary string is typically either a DICOM file or a DICOM network transmission.
+  #
+  class DRead
+
+    # A boolean which reports the explicitness of the DICOM string, true if explicit and false if implicit.
+    attr_reader :explicit
+    # A boolean which reports the endianness of the post-meta group part of the DICOM string (true for big endian, false for little endian).
+    attr_reader :file_endian
+    # An array which records any status messages that are generated while parsing the DICOM string.
+    attr_reader :msg    
+    # A DObject instance which the parsed data elements will be connected to.
+    attr_reader :obj
+    # A boolean which records whether the DICOM string contained the proper DICOM header signature of 128 bytes + 'DICM'.
+    attr_reader :signature
+    # A boolean which reports whether the DICOM string was parsed successfully (true) or not (false).
+    attr_reader :success
+
+    # Creates a DRead instance.
+    # Parses the DICOM string, builds data element objects and connects these with the DObject instance.
+    #
+    # === Parameters
+    #
+    # * <tt>obj</tt> -- A DObject instance which the parsed data elements will be connected to.
+    # * <tt>string</tt> -- A string which specifies either the path of a DICOM file to be loaded, or a binary DICOM string to be parsed.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:syntax</tt> -- String. If specified, the decoding of the DICOM string will be forced to use this transfer syntax.
+    # * <tt>:bin</tt> -- Boolean. If set to true, string parameter will be interpreted as a binary DICOM string, and not a path string, which is the default behaviour.
+    # 
+    def initialize(obj, string=nil, options={})
+      # Set the DICOM object as an instance variable:
+      @obj = obj
+      # Some of the options need to be transferred to instance variables:
+      @transfer_syntax = options[:syntax]
+      # Initiate the variables that are used during file reading:
+      init_variables
+      # Are we going to read from a file, or read from a binary string?
+      if options[:bin]
+        # Read from the provided binary string:
+        @str = string
+      else
+        # Read from file:
+        open_file(string)
+        # Read the initial header of the file:
+        if @file == nil
+          # File is not readable, so we return:
+          @success = false
+          return
+        else
+          # Extract the content of the file to a binary string:
+          @str = @file.read
+          @file.close
+        end
+      end
+      # Create a Stream instance to handle the decoding of content from this binary string:
+      @stream = Stream.new(@str, @file_endian)
+      # Do not check for header information when supplied a (network) binary string:
+      unless options[:bin]
+        # Read and verify the DICOM header:
+        header = check_header
+        # If the file didnt have the expected header, we will attempt to read
+        # data elements from the very start file:
+        if header == false
+          @stream.skip(-132)
+        elsif header == nil
+          # Not a valid DICOM file, return:
+          @success = false
+          return
+        end
+      end
+      # Run a loop which parses Data Elements, one by one, until the end of the data string is reached:
+      data_element = true
+      while data_element do
+        # Using a rescue clause since processing Data Elements can cause errors when parsing an invalid DICOM string.
+        begin
+          # Extracting Data element information (nil is returned if end of file is encountered in a normal way).
+          data_element = process_data_element
+        rescue
+          # The parse algorithm crashed. Set data_element to false to break the loop and toggle the success boolean to indicate failure.
+          @msg << "Error! Failed to process a Data Element. This is probably the result of invalid or corrupt DICOM data."
+          @success = false
+          data_element = false
+        end
+      end
+    end
+
+
+    # Following methods are private:
+    private
+
+
+    # Checks for the official DICOM header signature.
+    # Returns true if the proper signature is present, false if it is not present,
+    # and nil if thestring was shorter then the length of the DICOM signature.
+    #
+    def check_header
+      # According to the official DICOM standard, a DICOM file shall contain 128 consequtive (zero) bytes,
+      # followed by 4 bytes that spell the string 'DICM'. Apparently, some providers seems to skip this in their DICOM files.
+      # Check that the file is long enough to contain a valid header:
+      if @str.length < 132
+        # This does not seem to be a valid DICOM file and so we return.
+        return nil
+      else
+        @stream.skip(128)
+        # Next 4 bytes should spell "DICM":
+        identifier = @stream.decode(4, "STR")
+        @header_length += 132
+        if identifier != "DICM" then
+          # Header signature is not valid (we will still try to read it is a DICOM file though):
+          @msg << "Warning: The specified file does not contain the official DICOM header. Will try to read the file anyway, as some sources are known to skip this header."
+          # As the file is not conforming to the DICOM standard, it is possible that it does not contain a
+          # transfer syntax element, and as such, we attempt to choose the most probable encoding values here:
+          @explicit = false
+          return false
+        else
+          # Header signature is valid:
+          @signature = true
+          return true
+        end
+      end
+    end
+
+    # Handles the process of reading a data element from the DICOM string, and creating an element object from the parsed data.
+    # Returns nil if end of file has been reached (in an expected way), false if the element parse failed, and true if an element was parsed successfully.
+    #
+    #--
+    # FIXME: This method has grown a bit messy and isn't very easy to follow. It would be nice if it could be cleaned up somewhat.
+    #
+    def process_data_element
+      # STEP 1:
+      # Attempt to read data element tag:
+      tag = read_tag
+      # Return nil if we have (naturally) reached the end of the data string.
+      return nil unless tag
+      # STEP 2:
+      # Access library to retrieve the data element name and VR from the tag we just read:
+      # (Note: VR will be overwritten in the next step if the DICOM file contains VR (explicit encoding))
+      name, vr = LIBRARY.get_name_vr(tag)
+      # STEP 3:
+      # Read VR (if it exists) and the length value:
+      vr, length = read_vr_length(vr,tag)
+      level_vr = vr
+      # STEP 4:
+      # Reading value of data element.
+      # Special handling needed for items in encapsulated image data:
+      if @enc_image and tag == ITEM_TAG
+        # The first item appearing after the image element is a 'normal' item, the rest hold image data.
+        # Note that the first item will contain data if there are multiple images, and so must be read.
+        vr = "OW" # how about alternatives like OB?
+        # Modify name of item if this is an item that holds pixel data:
+        if @current_element.tag != PIXEL_TAG
+          name = PIXEL_ITEM_NAME
+        end
+      end
+      # Read the binary string of the element:
+      bin = read_bin(length) if length > 0
+      # Read the value of the element (if it contains data, and it is not a sequence or ordinary item):
+      if length > 0 and vr != "SQ" and tag != ITEM_TAG
+        # Read the element's processed value:
+        value = read_value(vr, length)
+      else
+        # Data element has no value (data).
+        value = nil
+        # Special case: Check if pixel data element is sequenced:
+        if tag == PIXEL_TAG
+          # Change name and vr of pixel data element if it does not contain data itself:
+          name = ENCAPSULATED_PIXEL_NAME
+          level_vr = "SQ"
+          @enc_image = true
+        end
+      end
+      # Create an Element from the gathered data:
+      if level_vr == "SQ" or tag == ITEM_TAG
+        if level_vr == "SQ"
+          # Create a Sequence:
+          @current_element = Sequence.new(tag, :length => length, :name => name, :parent => @current_parent, :vr => vr)
+        elsif tag == ITEM_TAG
+          # Create an Item:
+          if @enc_image
+            @current_element = Item.new(:bin => bin, :length => length, :name => name, :parent => @current_parent, :vr => vr)
+          else
+            @current_element = Item.new(:length => length, :name => name, :parent => @current_parent, :vr => vr)
+          end
+        end
+        # Common operations on the two types of parent elements:
+        if length == 0 and @enc_image
+          # Set as parent. Exceptions when parent will not be set:
+          # Item/Sequence has zero length & Item is a pixel item (which contains pixels, not child elements).
+          @current_parent = @current_element
+        elsif length != 0
+          @current_parent = @current_element unless name == PIXEL_ITEM_NAME
+        end
+        # If length is specified (no delimitation items), load a new DRead instance to read these child elements
+        # and load them into the current sequence. The exception is when we have a pixel data item.
+        if length > 0 and not @enc_image
+          child_reader = DRead.new(@current_element, bin, :bin => true, :syntax => @transfer_syntax)
+          @current_parent = @current_parent.parent
+          @msg << child_reader.msg
+          @success = child_reader.success
+          return false unless @success
+        end
+      elsif DELIMITER_TAGS.include?(tag)
+        # We do not create an element for the delimiter items.
+        # The occurance of such a tag indicates that a sequence or item has ended, and the parent must be changed:
+        @current_parent = @current_parent.parent
+      else
+        # Create an ordinary Data Element:
+        @current_element = DataElement.new(tag, value, :bin => bin, :name => name, :parent => @current_parent, :vr => vr)
+        # Check that the data stream didnt end abruptly:
+        if length != @current_element.bin.length
+          set_abrupt_error
+          return false # (Failed)
+        end
+      end
+      # Return true to indicate success:
+      return true
+    end
+
+    # Reads and returns the data element's tag (the 4 first bytes of a data element).
+    # Returns nil if no tag could be read (end of string).
+    #
+    def read_tag
+      tag = @stream.decode_tag
+      if tag
+        # When we shift from group 0002 to another group we need to update our endian/explicitness variables:
+        if tag.group != META_GROUP and @switched == false
+          switch_syntax
+          # We may need to read our tag again if endian has switched (in which case it has been misread):
+          if @switched_endian
+            @stream.skip(-4)
+            tag = @stream.decode_tag
+          end
+        end
+      end
+      return tag
+    end
+
+    # Reads the data element's value representation (2 bytes), as well as the data element's length (varying length: 2-6 bytes).
+    # The decoding scheme to be applied depends on explicitness, data element type and vr.
+    # Returns vr and length.
+    #
+    # === Parameters
+    #
+    # * <tt>vr</tt> -- String. The value representation that was retrieved from the dictionary for the tag of this data element.
+    # * <tt>tag</tt> -- String. The tag of this data element.
+    #
+    def read_vr_length(vr, tag)
+      # Structure will differ, dependent on whether we have explicit or implicit encoding:
+      reserved = 0
+      bytes = 0
+      # *****EXPLICIT*****:
+      if @explicit == true
+        # Step 1: Read VR, 2 bytes (if it exists - which are all cases except for the item related elements)
+        vr = @stream.decode(2, "STR") unless ITEM_TAGS.include?(tag)
+        # Step 2: Read length
+        # Three possible structures for value length here, dependent on element vr:
+        case vr
+          when "OB","OW","OF","SQ","UN","UT"
+            # 6 bytes total (2 reserved bytes preceeding the 4 byte value length)
+            reserved = 2
+            bytes = 4
+          when ITEM_VR
+            # For the item elements: "FFFE,E000", "FFFE,E00D" and "FFFE,E0DD":
+            bytes = 4
+          else
+            # For all the other element vr, value length is 2 bytes:
+            bytes = 2
+        end
+      else
+        # *****IMPLICIT*****:
+        bytes = 4
+      end
+      # Handle skips and read out length value:
+      @stream.skip(reserved)
+      if bytes == 2
+        length = @stream.decode(bytes, "US") # (2)
+      else
+        length = @stream.decode(bytes, "SL") # (4)
+      end
+      if length%2 > 0 and length > 0
+        # According to the DICOM standard, all data element lengths should be an even number.
+        # If it is not, it may indicate a file that is not standards compliant or it might even not be a DICOM file.
+        @msg << "Warning: Odd number of bytes in data element's length occured. This is a violation of the DICOM standard, but program will attempt to read the rest of the file anyway."
+      end
+      return vr, length
+    end
+
+    # Reads and returns the data element's binary value string (varying length).
+    #
+    # === Parameters
+    #
+    # * <tt>length</tt> -- Fixnum. The length of the binary string that will be extracted.
+    #
+    def read_bin(length)
+      return @stream.extract(length)
+    end
+
+    # Decodes and returns the data element's value (varying length).
+    #
+    # === Notes
+    #
+    # * Data elements which have multiple numbers as value, will have these numbers joined to a string, separated by the \ character.
+    # * For some value representations (OW, OB, OF, UN), a value is not processed, and nil is returned.
+    # This means that for data like pixel data, compressed data, unknown data, a value is not available in the data element,
+    # and must be processed from the data element's binary variable.
+    #
+    # === Parameters
+    #
+    # * <tt>vr</tt> -- String. The value representation of the data element which the value to be decoded belongs to.
+    # * <tt>length</tt> -- Fixnum. The length of the binary string that will be extracted.
+    #
+    def read_value(vr, length)
+      unless vr == "OW" or vr == "OB" or vr == "OF" or vr == "UN"
+        # Since the binary string has already been extracted for this data element, we must first "rewind":
+        @stream.skip(-length)
+        # Decode data:
+        value = @stream.decode(length, vr)
+        # If the returned value is an array of multiple values, we will join these values to a string with the separator "\":
+        value = value.join("\\") if value.is_a?(Array)
+      else
+        # No decoded value:
+        value = nil
+      end
+      return value
+    end
+
+    # Tests if a file is readable, and if so, opens it.
+    #
+    # === Parameters
+    #
+    # * <tt>file</tt> -- A path/file string.
+    #
+    def open_file(file)
+      if File.exist?(file)
+        if File.readable?(file)
+          if not File.directory?(file)
+            if File.size(file) > 8
+              @file = File.new(file, "rb")
+            else
+              @msg << "Error! File is too small to contain DICOM information (#{file})."
+            end
+          else
+            @msg << "Error! File is a directory (#{file})."
+          end
+        else
+          @msg << "Error! File exists but I don't have permission to read it (#{file})."
+        end
+      else
+        @msg << "Error! The file you have supplied does not exist (#{file})."
+      end
+    end
+
+    # Registers an unexpected error by toggling a success boolean and recording an error message.
+    # The DICOM string ended abruptly because the data element's value was shorter than expected.
+    #
+    def set_abrupt_error
+      @msg << "Error! The parsed data of the last data element #{@current_element.tag} does not match its specified length value. This is probably the result of invalid or corrupt DICOM data."
+      @success = false
+    end
+
+    # Changes encoding variables as the file reading proceeds past the initial meta group part (0002,xxxx) of the DICOM file.
+    #
+    def switch_syntax
+      # Get the transfer syntax string, unless it has already been provided by keyword:
+      unless @transfer_syntax
+        ts_element = @obj["0002,0010"]
+        if ts_element
+          @transfer_syntax = ts_element.value
+        else
+          @transfer_syntax = IMPLICIT_LITTLE_ENDIAN
+        end
+      end
+      # Query the library with our particular transfer syntax string:
+      valid_syntax, @rest_explicit, @rest_endian = LIBRARY.process_transfer_syntax(@transfer_syntax)
+      unless valid_syntax
+        @msg << "Warning: Invalid/unknown transfer syntax! Will try reading the file, but errors may occur."
+      end
+      # We only plan to run this method once:
+      @switched = true
+      # Update endian, explicitness and unpack variables:
+      @switched_endian = true if @rest_endian != @file_endian
+      @file_endian = @rest_endian
+      @stream.endian = @rest_endian
+      @explicit = @rest_explicit
+    end
+
+
+    # Creates various instance variables that are used when parsing the DICOM string.
+    #
+    def init_variables
+      # Array that will holde any messages generated while reading the DICOM file:
+      @msg = Array.new
+      # Presence of the official DICOM signature:
+      @signature = false
+      # Default explicitness of start of DICOM file:
+      @explicit = true
+      # Default endianness of start of DICOM files is little endian:
+      @file_endian = false
+      # A switch of endianness may occur after the initial meta group, an this needs to be monitored:
+      @switched_endian = false
+      # Explicitness of the remaining groups after the initial 0002 group:
+      @rest_explicit = false
+      # Endianness of the remaining groups after the first group:
+      @rest_endian = false
+      # When the file switch from group 0002 to a later group we will update encoding values, and this switch will keep track of that:
+      @switched = false
+      # Keeping track of the data element parent status while parsing the DICOM string:
+      @current_parent = @obj
+      # Keeping track of what is the current data element:
+      @current_element = @obj
+      # Items contained under the pixel data element may contain data directly, so we need a variable to keep track of this:
+      @enc_image = false
+      # Assume header size is zero bytes until otherwise is determined:
+      @header_length = 0
+      # Assume file will be read successfully and toggle it later if we experience otherwise:
+      @success = true
+    end
+
+  end
+end

data/lib/dicom/d_server.rb

@@ -0,0 +1,397 @@
+#    Copyright 2009-2010 Christoffer Lervag
+
+module DICOM
+
+  # This class contains code for setting up a Service Class Provider (SCP),
+  # which will act as a simple storage node (a DICOM server that receives images).
+  #
+  class DServer
+
+    # Runs the server and takes a block for initializing.
+    #
+    # === Parameters
+    #
+    # * <tt>port</tt> -- Fixnum. The network port to be used. Defaults to 104.
+    # * <tt>path</tt> -- String. The path where incoming DICOM files will be stored. Defaults to "./received/".
+    # * <tt>&block</tt> -- A block of code that will be run on the DServer instance, between creation and the launch of the SCP itself.
+    #
+    # === Examples
+    #
+    #   require 'dicom'
+    #   require 'my_file_handler'
+    #   include DICOM
+    #   DServer.run(104, 'c:/temp/') do
+    #     timeout = 100
+    #     file_handler = MyFileHandler
+    #   end
+    #
+    def self.run(port=104, path='./received/', &block)
+      server = DServer.new(port)
+      server.instance_eval(&block)
+      server.start_scp(path)
+    end
+
+    # A customized FileHandler class to use instead of the default FileHandler included with Ruby DICOM.
+    attr_accessor :file_handler
+    # The name of the server (application entity).
+    attr_accessor :host_ae
+    # The maximum allowed size of network packages (in bytes). 
+    attr_accessor :max_package_size
+    # The network port to be used.
+    attr_accessor :port
+    # The maximum period the server will wait on an answer from a client before aborting the communication.
+    attr_accessor :timeout
+    # A boolean which defines if notices/warnings/errors will be printed to the screen (true) or not (false).
+    attr_accessor :verbose
+    
+    # A hash containing the abstract syntaxes that will be accepted.
+    attr_reader :accepted_abstract_syntaxes
+    # A hash containing the transfer syntaxes that will be accepted.
+    attr_reader :accepted_transfer_syntaxes
+    # An array containing any error messages recorded.
+    attr_reader :errors
+    # An array containing any status messages recorded.
+    attr_reader :notices
+
+    # Creates a DServer instance.
+    #
+    # === Parameters
+    #
+    # * <tt>port</tt> -- Fixnum. The network port to be used. Defaults to 104.
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <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 the server will wait on an answer from a client before aborting the communication.
+    # * <tt>:verbose</tt> -- Boolean. If set to false, the DServer instance will run silently and not output warnings and error messages to the screen. Defaults to true.
+    #
+    # === Examples
+    #
+    #   # Create a server using default settings:
+    #   s = DICOM::DServer.new
+    #   # Create a server and specify a host name as well as a custom buildt file handler:
+    #   require 'MyFileHandler'
+    #   server = DICOM::DServer.new(104, :host_ae => "RUBY_SERVER", :file_handler => DICOM::MyFileHandler)
+    #
+    def initialize(port=104, options={})
+      require 'socket'
+      # Required parameters:
+      @port = port
+      # Optional parameters (and default values):
+      @file_handler = options[:file_handler] || FileHandler
+      @host_ae =  options[:host_ae]  || "RUBY_DICOM"
+      @max_package_size = options[:max_package_size] || 32768 # 16384
+      @timeout = options[:timeout] || 10 # seconds
+      @min_length = 12 # 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
+      @association = nil # DICOM Association status
+      @request_approved = nil # Status of our DICOM request
+      @release = nil # Status of received, valid release response
+      set_default_accepted_syntaxes
+    end
+
+    # Adds an abstract syntax to the list of abstract syntaxes that the server will accept.
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- An abstract syntax UID string.
+    #
+    def add_abstract_syntax(uid)
+      if uid.is_a?(String)
+        name = LIBRARY.get_syntax_description(uid) || "Unknown UID" 
+        @accepted_abstract_syntaxes[uid] = name
+      else
+        raise "Invalid type of UID. Expected String, got #{uid.class}!"
+      end
+    end
+
+    # Adds a transfer syntax to the list of transfer syntaxes that the server will accept.
+    #
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- A transfer syntax UID string.
+    #
+    def add_transfer_syntax(uid)
+      if uid.is_a?(String)
+        name = LIBRARY.get_syntax_description(uid) || "Unknown UID" 
+        @accepted_transfer_syntaxes[uid] = name
+      else
+        raise "Invalid type of UID. Expected String, got #{uid.class}!"
+      end
+    end
+
+    # Prints the list of accepted abstract syntaxes to the screen.
+    #
+    def print_abstract_syntaxes
+      # Determine length of longest key to ensure pretty print:
+      max_uid = @accepted_abstract_syntaxes.keys.collect{|k| k.length}.max
+      puts "Abstract syntaxes which are accepted by this SCP:"
+      @accepted_abstract_syntaxes.sort.each do |pair|
+        puts "#{pair[0]}#{' '*(max_uid-pair[0].length)} #{pair[1]}"
+      end
+    end
+
+    # Prints the list of accepted transfer syntaxes to the screen.
+    #
+    def print_transfer_syntaxes
+      # Determine length of longest key to ensure pretty print:
+      max_uid = @accepted_transfer_syntaxes.keys.collect{|k| k.length}.max
+      puts "Transfer syntaxes which are accepted by this SCP:"
+      @accepted_transfer_syntaxes.sort.each do |pair|
+        puts "#{pair[0]}#{' '*(max_uid-pair[0].length)} #{pair[1]}"
+      end
+    end
+
+    # Removes a specific abstract syntax from the list of abstract syntaxes that the server will accept.
+    #
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- An abstract syntax UID string.
+    #
+    def remove_abstract_syntax(uid)
+      if uid.is_a?(String)
+        @accepted_abstract_syntaxes.delete(uid)
+      else
+        raise "Invalid type of UID. Expected String, got #{uid.class}!"
+      end
+    end
+
+    # Removes a specific transfer syntax from the list of transfer syntaxes that the server will accept.
+    #
+    # === Parameters
+    #
+    # * <tt>uid</tt> -- A transfer syntax UID string.
+    #
+    def remove_transfer_syntax(uid)
+      if uid.is_a?(String)
+        @accepted_transfer_syntaxes.delete(uid)
+      else
+        raise "Invalid type of UID. Expected String, got #{uid.class}!"
+      end
+    end
+
+    # Completely clears the list of abstract syntaxes that the server will accept.
+    #
+    # === Notes
+    #
+    # * Following such a removal, the user must ensure to add the specific abstract syntaxes that are to be accepted by the server.
+    #
+    def remove_all_abstract_syntaxes
+      @accepted_abstract_syntaxes = Hash.new
+    end
+
+    # Completely clears the list of transfer syntaxes that the server will accept.
+    #
+    # === Notes
+    #
+    # * Following such a removal, the user must ensure to add the specific transfer syntaxes that are to be accepted by the server.
+    #
+    def remove_all_transfer_syntaxes
+      @accepted_transfer_syntaxes = Hash.new
+    end
+
+    # Starts the Service Class Provider (SCP).
+    #
+    # === Notes
+    #
+    # * This service acts as a simple storage node, which receives DICOM files and stores them in a specified folder.
+    # * Customized storage actions can be set my modifying or replacing the FileHandler class.
+    #
+    # === Parameters
+    #
+    # * <tt>path</tt> -- The path where incoming files are to be saved.
+    #
+    def start_scp(path='./received/')
+      if @accepted_abstract_syntaxes.size > 0 and @accepted_transfer_syntaxes.size > 0
+        add_notice("Starting DICOM SCP server...")
+        add_notice("*********************************")
+        # Initiate server:
+        @scp = TCPServer.new(@port)
+        # Use a loop to listen for incoming messages:
+        loop do
+          Thread.start(@scp.accept) do |session|
+            # Initialize the network package handler for this session:
+            link = Link.new(:host_ae => @host_ae, :max_package_size => @max_package_size, :timeout => @timeout, :verbose => @verbose, :file_handler => @file_handler)
+            link.set_session(session)
+            # Note the time of reception as well as who has contacted us:
+            add_notice(Time.now.strftime("%Y-%m-%d  %H:%M:%S"))
+            add_notice("Connection established with:  #{session.peeraddr[2]}  (IP: #{session.peeraddr[3]})")
+            # Receive an incoming message:
+            segments = link.receive_multiple_transmissions
+            info = segments.first
+            # Interpret the received message:
+            if info[:valid]
+              association_error = check_association_request(info)
+              unless association_error
+                info, approved, rejected = process_syntax_requests(info)
+                link.handle_association_accept(info)
+                if approved > 0
+                  if approved == 1
+                    add_notice("Accepted the association request with context: #{LIBRARY.get_syntax_description(info[:pc].first[:abstract_syntax])}")
+                  else
+                    if rejected == 0
+                      add_notice("Accepted all #{approved} proposed contexts in the association request.")
+                    else
+                      add_notice("Accepted only #{approved} of #{approved+rejected} of the proposed contexts in the association request.")
+                    end
+                  end
+                  # Process the incoming data. This method will also take care of releasing the association:
+                  success, messages = link.handle_incoming_data(path)
+                  if success
+                    add_notice(messages) if messages.first
+                  else
+                    # Something has gone wrong:
+                    add_error(messages) if messages.first
+                  end
+                else
+                  # No abstract syntaxes in the incoming request were accepted:
+                  if rejected == 1
+                    add_notice("Rejected the association request with proposed context: #{LIBRARY.get_syntax_description(info[:pc].first[:abstract_syntax])}")
+                  else
+                    add_notice("Rejected all #{rejected} proposed contexts in the association request.")
+                  end
+                  # Since the requested abstract syntax was not accepted, the association must be released.
+                  link.await_release
+                end
+              else
+                # The incoming association was not formally correct.
+                link.handle_rejection
+              end
+            else
+              # The incoming message was not recognised as a valid DICOM message. Abort:
+              link.handle_abort
+            end
+            # Terminate the connection:
+            link.stop_session
+            add_notice("*********************************")
+          end
+        end
+      else
+        raise "Unable to start SCP server as no accepted abstract syntaxes have been set!" if @accepted_abstract_syntaxes.length == 0
+        raise "Unable to start SCP server as no accepted transfer syntaxes have been set!" if @accepted_transfer_syntaxes.length == 0
+      end
+    end
+
+
+    # Following methods are private:
+    private
+
+
+    # Adds a warning or error message to the instance array holding messages,
+    # 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)
+      if @verbose
+        puts error
+      end
+      @errors << error
+    end
+
+    # Adds a notice (information regarding progress or successful communications) to the instance array,
+    # 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)
+      if @verbose
+        puts notice
+      end
+      @notices << notice
+    end
+
+    # Checks if the association request is formally correct, by matching against an exact application context UID.
+    # Returns nil if valid, and an error code if it is not approved.
+    #
+    # === Notes
+    #
+    # Other things can potentionally be checked here too, if we want to make the server more strict with regards to what information is received:
+    # * Application context name, calling AE title, called AE title
+    # * Description of error codes are given in the DICOM Standard, PS 3.8, Chapter 9.3.4 (Table 9-21).
+    #
+    # === Parameters
+    #
+    # * <tt>info</tt> -- An information hash from the received association request.
+    #
+    def check_association_request(info)
+      unless info[:application_context] == APPLICATION_CONTEXT
+        error = 2 # (application context name not supported)
+        add_error("Error: The application context in the incoming association request was not recognized: (#{info[:application_context]})")
+      else
+        error = nil
+      end
+      return error
+    end
+
+    # Checks if the requested abstract syntax & its transfer syntax(es) are supported by this server instance,
+    # and inserts a corresponding result code for each presentation context.
+    # Returns the modified association information hash, as well as the number of abstract syntaxes that were accepted and rejected.
+    #
+    # === Notes
+    #
+    # * Description of error codes are given in the DICOM Standard, PS 3.8, Chapter 9.3.3.2 (Table 9-18).
+    #
+    # === Parameters
+    #
+    # * <tt>info</tt> -- An information hash from the received association request.
+    #
+    def process_syntax_requests(info)
+      # A couple of variables used to analyse the properties of the association:
+      approved = 0
+      rejected = 0
+      # Loop through the presentation contexts:
+      info[:pc].each do |pc|
+        if @accepted_abstract_syntaxes[pc[:abstract_syntax]]
+          # Abstract syntax accepted. Proceed to check its transfer syntax(es):
+          proposed_transfer_syntaxes = pc[:ts].collect{|t| t[:transfer_syntax]}.sort
+          # Choose the first proposed transfer syntax that exists in our list of accepted transfer syntaxes:
+          accepted_transfer_syntax = nil
+          proposed_transfer_syntaxes.each do |proposed_ts|
+            if @accepted_transfer_syntaxes.include?(proposed_ts)
+              accepted_transfer_syntax = proposed_ts
+              break
+            end
+          end
+          if accepted_transfer_syntax
+            # Both abstract and transfer syntax has been approved:
+            pc[:result] = ACCEPTANCE
+            pc[:selected_transfer_syntax] = accepted_transfer_syntax
+            # Update our status variables:
+            approved += 1
+          else
+            # No transfer syntax was accepted for this particular presentation context:
+            pc[:result] = TRANSFER_SYNTAX_REJECTED
+            rejected += 1
+          end
+        else
+          # Abstract syntax rejected:
+          pc[:result] = ABSTRACT_SYNTAX_REJECTED
+        end
+      end
+      return info, approved, rejected
+    end
+
+    # Sets the default accepted abstract syntaxes and transfer syntaxes for this SCP.
+    #
+    def set_default_accepted_syntaxes
+      @accepted_transfer_syntaxes, @accepted_abstract_syntaxes = LIBRARY.extract_transfer_syntaxes_and_sop_classes
+    end
+
+  end
+end