dde 0.2.2

data/lib/dde/dde_string.rb

@@ -0,0 +1,33 @@
+module DDE
+
+  # Class encapsulates DDE string. In addition to normal string behavior,
+  # it also has *handle* that can be passed to dde functions
+  class DdeString < String
+    include Win::DDE
+
+    attr_accessor :handle, # string handle passable to DDEML functions
+                  :instance_id, # instance id of DDE app that created this DdeString
+                  :code_page, # Windows code page for this string (CP_WINANSI or CP_WINUNICODE)
+                  :name # ORIGINAL string used to create this DdeString
+
+    # Given the DDE application instance_id, you cane create DdeStrings
+    # either from regular string or from known DdeString handle
+    def initialize(instance_id, string_or_handle, code_page=CP_WINANSI)
+      @instance_id = instance_id
+      @code_page = code_page
+
+      begin
+        if string_or_handle.is_a? String
+          @name = string_or_handle
+          error unless @handle = dde_create_string_handle(@instance_id, @name, @code_page)
+        else
+          @handle = string_or_handle
+          error unless @name = dde_query_string(@instance_id, @handle, @code_page)
+        end
+      rescue => e
+      end
+      raise DDE::Errors::StringError, "Failed to initialize DDE string: #{e}" unless @handle && @name && !e
+      super @name
+    end
+  end
+end

data/lib/dde/monitor.rb

@@ -0,0 +1,26 @@
+module DDE
+
+  # Class encapsulates DDE Monitor that prints all DDE transactions to console
+  class Monitor < App
+
+    # Creates new DDE monitor instance
+    def initialize(init_flags=nil, &callback)
+      init_flags ||=
+              APPCLASS_MONITOR |  # this is monitor
+              MF_CALLBACKS     |  # monitor callback functions
+              MF_CONV          |  # monitor conversation data
+              MF_ERRORS        |  # monitor DDEML errors
+              MF_HSZ_INFO      |  # monitor data handle activity
+              MF_LINKS         |  # monitor advise loops
+              MF_POSTMSGS      |  # monitor posted DDE messages
+              MF_SENDMSGS         # monitor sent DDE messages
+
+      callback ||= lambda do |*args|
+        p args.unshift(Win::DDE::TYPES[args.shift]).push(Win::DDE::FLAGS[args.pop])
+        1
+      end
+      
+      super init_flags, &callback
+    end
+  end
+end

data/lib/dde/server.rb

@@ -0,0 +1,41 @@
+module DDE
+
+  # Class encapsulates DDE Server with basic functionality (starting/stopping named service)
+  class Server < App
+
+    attr_reader :service # service(s) that this Server supports
+
+    def start_service( name, init_flags=nil, &dde_callback )
+      try "Starting service #{name}", DDE::Errors::ServiceError do
+        # Trying to start DDE if it was inactive
+        error unless dde_active? || start_dde( init_flags, &dde_callback )
+
+        # Create DDE string for name (this creates handle that can be passed to DDEML functions)
+        @service = DDE::DdeString.new(@id, name)
+
+        # Register new DDE service, returns true/false success code
+        error unless dde_name_service(@id, @service.handle, DNS_REGISTER)
+      end
+    end
+
+    def stop_service
+      try "Stopping active service", DDE::Errors::ServiceError do
+        error "Either DDE or service not initialized" unless dde_active? && service_active?
+
+        # Unregister DDE service, returns true/false success code
+        error unless dde_name_service(@id, @service.handle, DNS_UNREGISTER);
+
+        # Free string handle for service name
+        error unless dde_free_string_handle(@id, @service.handle)
+
+        # Clear handle if service successfuly stopped
+        @service = nil
+      end
+    end
+
+    def service_active?
+      !!@service
+    end
+
+  end
+end

data/lib/dde/xl_server.rb

@@ -0,0 +1,32 @@
+require 'dde/xl_table'
+
+module DDE
+
+  # Class encapsulates DDE Server mimicking Excel. It is used to create DDE server with specific service name
+  # (default name 'excel') and store data received by the server via DDE
+  class XlServer < Server
+
+    attr_reader :format, # data format(s) (registered clipboard formats) that server supports
+                :table # data table for data storage
+
+    # Creates new Xl Server instance
+    def initialize(init_flags = nil, &dde_callback )
+
+      @table = DDE::XlTable.new
+
+      # Trying to register or retrieve existing format XlTable
+      try 'Registering format XlTable', DDE::Errors::FormatError do
+        @format = register_clipboard_format("XlTable")
+      end
+
+      super init_flags, &dde_callback
+    end
+
+    # Make 'excel' the default name for named service
+    alias_method :__start_service, :start_service
+    def start_service( name='excel', init_flags=nil, &dde_callback )
+      __start_service( name, init_flags, &dde_callback )
+    end
+
+  end
+end

data/lib/dde/xl_table.rb

@@ -0,0 +1,172 @@
+module DDE
+  extend FFI::Library  # todo: < Array ?
+  class Conv < FFI::Union
+    layout( :w, :ushort, # word should be 2 bytes, not 8
+            :d, :double, # it is 8 bytes
+            :b, [:char, 8]) # it is 8 bytes
+  end
+
+
+  # XLTable class represents a single chunk of DDE data formatted as an Excel table
+  class XlTable
+    include Win::DDE
+
+    # Received data types
+    TDT_FLOAT = 1
+    TDT_STRING = 2
+    TDT_BOOL = 3
+    TDT_ERROR = 4
+    TDT_BLANK = 5
+    TDT_INT = 6
+    TDT_SKIP = 7
+    TDT_TABLE = 16
+
+    TDT_TYPES = {
+            TDT_FLOAT => 'TDT_FLOAT',
+            TDT_STRING =>'TDT_STRING',
+            TDT_BOOL => 'TDT_BOOL',
+            TDT_ERROR => 'TDT_ERROR',
+            TDT_BLANK => 'TDT_BLANK',
+            TDT_INT => 'TDT_INT',
+            TDT_SKIP => 'TDT_SKIP',
+            TDT_TABLE => 'TDT_TABLE'
+    }
+
+    attr_accessor :topic_item # topic_item
+
+    def initialize
+      @table_data = []    # Array contains Arrays of Strings
+      @col = 0
+      @row = 0
+      # omitting separators for now
+    end
+
+    # tests if table data is empty or contains data in inconsistent state
+    def empty?
+      @table_data.empty? ||
+              @row == 0 || @col == 0 ||
+              @row != @table_data.size ||
+              @col != @table_data.first.size  # assumes first element is also an Array
+    end
+
+    def data?;
+      !empty?
+    end
+
+    def draw
+      return false if empty?
+
+      # omitting separator gymnastics for now
+      cout "-----\n"
+      @table_data.each{|row| row.each {|col| cout col, " "}; cout "\n"}
+    end
+
+    def get_data(dde_handle)
+#      conv = DDE::Conv.new  # Union for data conversion
+
+      # Copy DDE data from dde_handle (FFI::MemoryPointer is returned)
+      return nil unless data = dde_get_data(dde_handle) # raise 'DDE data not extracted'
+      offset = 0
+
+      # Make sure that the first block is tdtTable
+      return nil unless data.get_int16(offset) == TDT_TABLE # raise 'DDE data not TDT_TABLE'
+      offset += 2
+
+      # Make sure cb == 4
+      return nil unless data.get_int16(offset) == 4 # raise 'TDT_TABLE data length wrong'
+      offset += 2
+
+      @row = data.get_int16(offset)
+      @col = data.get_int16(offset+2)
+      offset += 4
+#p "row, col", @row, @col
+
+      # Make sure nonzero row and col
+      return nil if @row == 0 || @col == 0   # raise 'col or row zero in TDT_TABLE'
+
+      @table_data = Array.new(@row){||Array.new}
+
+      r = 0
+      c = 0
+      while offset < data.size
+        type = data.get_int16(offset)   # Next data field(s) type
+        cb = data.get_int16(offset+2)   # Next data field(s) length in bytes
+        offset += 4
+
+#p "type #{TDT_TYPES[type]}, cb #{cb}, row #{r}, col #{c}"
+        case type
+          when TDT_FLOAT       # Float, 8 bytes per field
+            (cb/8).times do
+              @table_data[r][c] = data.get_float64(offset)
+              offset += 8
+              c += 1
+              if c == @col # end of row
+                c = 0
+                r += 1
+              end
+            end
+          when TDT_STRING
+            end_field = offset + cb
+            while offset < end_field do
+              length = data.get_int8(offset)
+              offset += 1
+               @table_data[r][c] = data.get_bytes(offset, length)
+              offset += length
+              c += 1
+              if c == @col # end of row
+                c = 0
+                r += 1
+              end
+            end
+          when TDT_BOOL        # Bool, 2 bytes per field
+            (cb/2).times do
+              @table_data[r][c] = data.get_int16(offset) == 0
+              offset += 2
+              c += 1
+              if c == @col # end of row
+                c = 0
+                r += 1
+              end
+            end
+          when TDT_ERROR        # Error enum, 2 bytes per field
+            (cb/2).times do
+              @table_data[r][c] = "Error:#{data.get_int16(offset)}"
+              offset += 2
+              c += 1
+              if c == @col # end of row
+                c = 0
+                r += 1
+              end
+            end
+          when TDT_BLANK        # Number of blank cells, 2 bytes per field
+            (cb/2).times do
+              blanks = data.get_int16(offset)
+              offset += 2
+              blanks.times do
+                @table_data[r][c] = ""
+                c += 1
+                if c == @col # end of row
+                  c = 0
+                  r += 1
+                end
+              end
+            end
+          when TDT_INT        # Int, 2 bytes per field
+            (cb/2).times do
+              @table_data[r][c] = data.get_int16(offset) == 0
+              offset += 2
+              c += 1
+              if c == @col # end of row
+                c = 0
+                r += 1
+              end
+            end
+          else
+            return nil
+        end
+      end
+#TODO:	free FFI::Pointer ?  delete []data;                          // Free memory
+      true      # Data acquisition successful
+    end
+  end
+end

data/lib/dde.rb

@@ -0,0 +1,8 @@
+# console output redirection (may need to wrap it in synchronization code, etc)
+require 'win/dde'
+require 'dde/dde_string'
+require 'dde/app'
+require 'dde/server'
+require 'dde/client'
+require 'dde/monitor'
+require 'dde/xl_server'

data/spec/dde/app_spec.rb

@@ -0,0 +1,85 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+module DDETest
+  describe DDE::App do
+    before(:each ){ @app = DDE::App.new }
+
+    it 'starts with nil id and flags if no arguments given' do
+      @app.id.should == nil
+      @app.init_flags.should == nil
+      @app.dde_active?.should == false
+    end
+
+    it 'starts DDE (initializes as STANDARD DDE app) with given callback block' do
+      app = DDE::App.new {|*args|}
+      app.id.should be_an Integer
+      app.id.should_not == 0
+      app.init_flags.should == APPCLASS_STANDARD
+      app.dde_active?.should == true
+    end
+
+    describe '#start_dde' do
+      it 'starts DDE with callback and default init_flags' do
+        res = @app.start_dde {|*args|}
+        res.should be_true
+        @app.id.should be_an Integer
+        @app.id.should_not == 0
+        @app.init_flags.should == APPCLASS_STANDARD
+        @app.dde_active?.should == true
+      end
+
+      it 'returns self if success (allows method chain)' do
+        @app.start_dde {|*args|}.should == @app
+      end
+
+      it 'starts DDE with callback and given init_flags' do
+        res = @app.start_dde( APPCLASS_STANDARD | CBF_FAIL_CONNECTIONS ){|*args|}
+        res.should be_true
+        @app.id.should be_an Integer
+        @app.id.should_not == 0
+        @app.init_flags.should == APPCLASS_STANDARD | CBF_FAIL_CONNECTIONS
+        @app.dde_active?.should == true
+      end
+
+      it 'raises InitError if no callback was given' do
+        lambda{ @app.start_dde}.should raise_error DDE::Errors::InitError
+      end
+
+      it 'reinitializes with new flags and callback if it was already initialized' do
+        @app.start_dde {|*args| 1}
+        old_id = @app.id
+        res = @app.start_dde( APPCLASS_STANDARD | CBF_FAIL_CONNECTIONS ){|*args| 2}
+        res.should be_true
+        @app.id.should == old_id
+        @app.init_flags.should == APPCLASS_STANDARD | CBF_FAIL_CONNECTIONS
+        @app.dde_active?.should == true
+      end
+    end
+
+    describe '#stop_dde' do
+      it 'stops DDE that was active' do
+        @app.start_dde {|*args| 1}
+
+        @app.stop_dde
+        @app.id.should == nil
+        @app.dde_active?.should == false
+      end
+
+      it 'preserves init_flags after DDE is stopped (for reinitialization)' do
+        @app.start_dde(APPCLASS_STANDARD | CBF_FAIL_CONNECTIONS) {|*args| 1}
+
+        @app.stop_dde
+        @app.init_flags.should == APPCLASS_STANDARD | CBF_FAIL_CONNECTIONS
+      end
+
+      it 'returns self if success (allows method chain)' do
+        @app.start_dde{|*args|}.stop_dde.should == @app
+      end
+
+      it 'raises InitError if dde was not active first' do
+        lambda{ @app.stop_dde}.should raise_error DDE::Errors::InitError
+      end
+    end
+
+  end
+end

data/spec/dde/client_spec.rb

@@ -0,0 +1,176 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+module DDETest
+
+  describe DDE::Client do
+#    before(:all){@monitor = DDE::Monitor.new}
+#    after(:all){@monitor.stop_dde}
+
+    before(:each ){ @client = DDE::Client.new }
+#    after(:each ){ @client.stop_dde}
+
+    it 'new without parameters creates Client but does not activate DDEML' do
+      @client.id.should == nil
+      @client.conversation.should == nil
+      @client.service.should == nil
+      @client.topic.should == nil
+      @client.dde_active?.should == false
+      @client.conversation_active?.should == false
+    end
+
+    it 'new with attached callback block creates Client and activates DDEML' do
+      client = DDE::Client.new {|*args|}
+      client.id.should be_an Integer
+      client.id.should_not == 0
+      client.dde_active?.should == true
+      client.conversation.should == nil
+      client.conversation_active?.should == false
+      client.service.should == nil
+      client.topic.should == nil
+    end
+
+    describe '#start_conversation' do
+
+      context 'with inactive (uninitialized) DDE:' do
+        it 'fails to starts new conversation' do
+          lambda{@client.start_conversation('service', 'topic')}.
+                  should raise_error /DDE is not initialized/
+          @client.conversation_active?.should == false
+          lambda{@client.start_conversation(nil, nil)}.
+                  should raise_error /DDE is not initialized/
+          @client.conversation_active?.should == false
+          lambda{@client.start_conversation}.
+                  should raise_error /DDE is not initialized/
+          @client.conversation_active?.should == false
+        end
+      end
+
+      context 'with active (initialized) DDE AND existing DDE server supporting "service" topic' do
+        before(:each )do
+          @client_calls = []
+          @server_calls = []
+          @client = DDE::Client.new {|*args| @client_calls << args; 1}
+          @server = DDE::Server.new {|*args| @server_calls << args; 1}.start_service('service')
+        end
+
+        it 'starts new conversation if DDE is already activated' do
+          res = @client.start_conversation 'service', 'topic'
+          res.should be_true
+          @client.conversation_active?.should == true
+        end
+
+        it 'returns self if success (allows method chain)' do
+          @client.start_conversation('service', 'topic').should == @client
+        end
+
+        it 'sets @conversation, @service and @topic attributes' do
+          @client.start_conversation 'service', 'topic'
+
+          @client.conversation.should be_an Integer
+          @client.conversation.should_not == 0
+          @client.service.should be_a DDE::DdeString
+          @client.service.should == 'service'
+          @client.service.name.should == 'service'
+          @client.conversation.should be_an Integer
+          @client.conversation.should_not == 0
+        end
+
+        it 'initiates XTYP_CONNECT transaction to service`s callback' do
+          @client.start_conversation 'service', 'topic'
+
+          @server_calls.first[0].should == XTYP_CONNECT
+          @server_calls.first[3].should == @client.topic.handle
+          @server_calls.first[4].should == @client.service.handle
+        end
+
+        it 'if server confirms connect, XTYP_CONNECT_CONFIRM transaction to service`s callback follows' do
+          @client.start_conversation 'service', 'topic'
+
+          @server_calls[1][0].should == XTYP_CONNECT_CONFIRM
+          @server_calls[1][3].should == @client.topic.handle
+          @server_calls[1][4].should == @client.service.handle
+        end
+
+        it 'client`s callback receives no transactions' do
+          @client.start_conversation 'service', 'topic'
+
+          p @server_calls, @client.service.handle, @client.topic.handle, @client.conversation
+          @client_calls.should == []
+        end
+
+        it 'fails if another conversation is already in progress' do
+          @client.start_conversation 'service', 'topic'
+
+          lambda{@client.start_conversation 'service1', 'topic1'}.
+                  should raise_error /Another conversation already established/
+        end
+
+        it 'fails to start conversation on unsupported service' do
+          lambda{@client.start_conversation('not_a_service', 'topic')}.
+                  should raise_error /A client`s attempt to establish a conversation has failed/
+          @client.conversation_active?.should == false
+        end
+
+      end
+    end
+
+    describe '#stop_conversation' do
+
+      context 'with inactive (uninitialized) DDE:' do
+        it 'fails to stop conversation' do
+          lambda{@client.stop_conversation}.
+                  should raise_error /DDE not started/
+          @client.conversation_active?.should == false
+        end
+
+      end
+
+      context 'with active (initialized) DDE AND existing DDE server supporting "service" topic' do
+        before(:each )do
+          @client_calls = []
+          @server_calls = []
+          @client = DDE::Client.new {|*args| @client_calls << args; 1}
+          @server = DDE::Server.new {|*args| @server_calls << args; 1}
+          @server.start_service('service')
+        end
+
+        it 'fails to stop conversation' do
+          lambda{@client.stop_conversation}.
+                  should raise_error /Conversation not started/
+          @client.conversation_active?.should == false
+        end
+
+        context 'conversation already started' do
+          before(:each ){@client.start_conversation 'service', 'topic'}
+
+          it 'stops conversation' do
+            res = @client.stop_conversation
+            res.should be_true
+            @client.conversation_active?.should == false
+          end
+
+          it 'unsets @conversation, @service and @topic attributes' do
+            @client.stop_conversation
+            @client.conversation.should == nil
+            @client.service.should == nil
+            @client.topic.should == nil
+          end
+
+          it 'does not stop DDE' do
+            @client.stop_conversation
+            @client.dde_active?.should == true
+          end
+
+          it 'initiates XTYP_DISCONNECT transaction to service`s callback' do
+            pending
+            @client.stop_conversation
+            p @server_calls, @client_calls    # ?????????? No XTYP_DISCONNECT ? Why ?
+            @server_calls.last[0].should == XTYP_DISCONNECT
+          end
+
+        end
+
+      end
+    end
+  end
+end

data/spec/dde/dde_string_spec.rb

@@ -0,0 +1,40 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+module DDETest
+  describe DDE::DdeString do
+    before(:each ){ @app = DDE::App.new {|*args|}}
+
+    context ' with valid instance id of active DDE application' do
+      it 'can be created from normal string' do
+        dde_string = DDE::DdeString.new(@app.id, "My_String")
+        dde_string == "My_String"
+        dde_string.handle.should be_an Integer
+        dde_string.handle.should_not == 0
+      end
+
+      it 'can be created from valid DDE string handle' do
+        string_handle = dde_create_string_handle(@app.id, 'My String')
+        dde_string = DDE::DdeString.new(@app.id, string_handle)
+        dde_string == "My_String"
+        dde_string.handle.should be_an Integer
+        dde_string.handle.should_not == 0
+      end
+    end
+
+    context ' without instance id of active DDE application' do
+      it 'cannot be created from String' do
+        lambda{DDE::DdeString.new(nil, "My_String")}.should raise_error DDE::Errors::StringError
+        lambda{DDE::DdeString.new(12345, "My_String")}.should raise_error DDE::Errors::StringError
+        lambda{DDE::DdeString.new(0, "My_String")}.should raise_error DDE::Errors::StringError
+      end
+
+      it 'cannot be created from valid string handle' do
+        string_handle = dde_create_string_handle(@app.id, 'My String')
+        lambda{DDE::DdeString.new(nil, string_handle)}.should raise_error DDE::Errors::StringError
+        lambda{DDE::DdeString.new(12345, string_handle)}.should raise_error DDE::Errors::StringError
+        lambda{DDE::DdeString.new(0, string_handle)}.should raise_error DDE::Errors::StringError
+      end
+    end
+
+  end
+end