win 0.1.22 → 0.1.26

data/VERSION

@@ -1 +1 @@
-0.1.22
+0.1.26

data/lib/win/dde.rb

@@ -26,6 +26,20 @@ module Win
     # DdeConnect function, regardless of the service name.
     DNS_FILTEROFF  = 8
 
+    # Transaction confirmations:
+
+    # Transaction confirmation
+    DDE_FACK        = 0x8000
+    # Server is too busy to process transaction
+    DDE_FBUSY       = 0x4000
+    DDE_FDEFERUPD   = 0x4000
+    DDE_FACKREQ     = 0x8000
+    DDE_FRELEASE    = 0x2000
+    DDE_FREQUESTED  = 0x1000
+    DDE_FAPPSTATUS  = 0x00ff
+    # Transaction rejected
+    DDE_FNOTPROCESSED    = 0
+
     # Transaction types:
 
     XTYPF_NOBLOCK       = 0x0002
@@ -92,19 +106,6 @@ module Win
             XTYP_SHIFT          => 'XTYP_SHIFT'
     }
 
-    # Transaction confirmations:
-
-    # Transaction confirmation
-    DDE_FACK        = 0x8000
-    # Server is too busy to process transaction
-    DDE_FBUSY       = 0x4000
-    DDE_FDEFERUPD   = 0x4000
-    DDE_FACKREQ     = 0x8000
-    DDE_FRELEASE    = 0x2000
-    DDE_FREQUESTED  = 0x1000
-    DDE_FAPPSTATUS  = 0x00ff
-    # Transaction rejected
-    DDE_FNOTPROCESSED    = 0
 
     # DdeInitialize afCmd flaggs:
 
@@ -336,6 +337,254 @@ module Win
     # DdeClientTransaction timeout value indicating async transaction
     TIMEOUT_ASYNC = 0xFFFFFFFF
 
+    # The MONCBSTRUCT structure contains information about the current Dynamic Data Exchange (DDE)
+    # transaction. A DDE debugging application can use this structure when monitoring transactions that the
+    # system passes to the DDE callback functions of other applications.
+    #
+    # [*Typedef*] struct { UINT cb; DWORD dwTime; HANDLE hTask; DWORD dwRet; UINT wType; UINT wFmt; HCONV
+    #             hConv; HSZ hsz1; HSZ hsz2; HDDEDATA hData; ULONG_PTR dwData1; ULONG_PTR dwData2;
+    #             CONVCONTEXT cc; DWORD cbData; DWORD Data[8] } MONCBSTRUCT;
+    #
+    # cb:: Specifies the structure's size, in bytes.
+    # dwTime:: Specifies the Windows time at which the transaction occurred. Windows time is the number of
+    #          milliseconds that have elapsed since the system was booted.
+    # hTask:: Handle to the task (app instance) containing the DDE callback function that received the transaction.
+    # dwRet:: Specifies the value returned by the DDE callback function that processed the transaction.
+    # wType:: Specifies the transaction type.
+    # wFmt:: Specifies the format of the data exchanged (if any) during the transaction.
+    # hConv:: Handle to the conversation in which the transaction took place.
+    # hsz1:: Handle to a string.
+    # hsz2:: Handle to a string.
+    # hData:: Handle to the data exchanged (if any) during the transaction.
+    # dwData1:: Specifies additional data.
+    # dwData2:: Specifies additional data.
+    # cc:: Specifies a CONVCONTEXT structure containing language information used to share data in different languages.
+    # cbData:: Specifies the amount, in bytes, of data being passed with the transaction. This value can be
+    #          more than 32 bytes.
+    # Data:: Contains the first 32 bytes of data being passed with the transaction (8 * sizeof(DWORD)).
+    # ---
+    # *Information*:
+    # Header Declared in Ddeml.h, include Windows.h
+
+    class MonCbStruct < FFI::Struct # :nodoc:
+      layout :cb, :uint,
+             :dw_time, :uint32,
+             :h_task, :ulong,
+             :dw_ret, :uint32,
+             :w_type, :uint,
+             :w_fmt, :uint,
+             :h_conv, :ulong,
+             :hsz1, :ulong,
+             :hsz2, :ulong,
+             :h_data, :pointer,
+             :dw_data1, :pointer,
+             :dw_data2, :pointer,
+             :cc, :pointer,
+             :cb_data, :uint32,
+             :data, [:uint32, 8]
+    end
+
+    # The MONCONVSTRUCT structure contains information about a Dynamic Data Exchange (DDE) conversation. A
+    # DDE monitoring application can use this structure to obtain information about a conversation that has
+    # been established or has terminated.
+    #
+    # [*Typedef*] struct { UINT cb; BOOL fConnect; DWORD dwTime; HANDLE hTask; HSZ hszSvc; HSZ hszTopic;
+    #             HCONV hConvClient; HCONV hConvServer } MONCONVSTRUCT;
+    #
+    # cb:: Specifies the structure's size, in bytes.
+    # fConnect:: Indicates whether the conversation is currently established. A value of TRUE indicates the
+    #            conversation is established; FALSE indicates it is not.
+    # dwTime:: Specifies the Windows time at which the conversation was established or terminated. Windows
+    #          time is the number of milliseconds that have elapsed since the system was booted.
+    # hTask:: Handle to a task (application instance) that is a partner in the conversation.
+    # hszSvc:: Handle to the service name on which the conversation is established.
+    # hszTopic:: Handle to the topic name on which the conversation is established.
+    # hConvClient:: Handle to the client conversation.
+    # hConvServer:: Handle to the server conversation.
+    # ---
+    # *Remarks*:
+    #
+    # Because string handles are local to the process, the hszSvc and hszTopic members are global atoms.
+    # Similarly, conversation handles are local to the instance; therefore, the hConvClient and hConvServer
+    # members are window handles.
+    # The hConvClient and hConvServer members of the MONCONVSTRUCT structure do not hold the same value as
+    # would be seen by the applications engaged in the conversation. Instead, they hold a globally unique
+    # pair of values that identify the conversation.
+    # ---
+    # Structure Information:
+    # Header Declared in Ddeml.h, include Windows.h
+    #
+    class MonConvStruct < FFI::Struct  # :nodoc:
+      layout :cb, :uint,
+             :f_connect, :uchar,
+             :dw_time, :uint32,
+             :h_task, :ulong,
+             :hsz_svc, :ulong,
+             :hsz_topic, :ulong,
+             :h_conv_client, :ulong,
+             :h_conv_server, :ulong
+    end
+
+    # The MONERRSTRUCT structure contains information about the current Dynamic Data Exchange (DDE) error. A
+    # DDE monitoring application can use this structure to monitor errors returned by DDE Management Library
+    # functions.
+    #
+    # [*Typedef*] struct { UINT cb; UINT wLastError; DWORD dwTime; HANDLE hTask } MONERRSTRUCT;
+    #
+    # cb:: Specifies the structure's size, in bytes.
+    # wLastError:: Specifies the current error.
+    # dwTime:: Specifies the Windows time at which the error occurred. Windows time is the number of
+    #          milliseconds that have elapsed since the system was booted.
+    # hTask:: Handle to the task (application instance) that called the DDE function that caused the error.
+    # ---
+    # Structure Information:
+    # Header Declared in Ddeml.h, include Windows.h
+    #
+    class MonErrStruct < FFI::Struct # :nodoc:
+      layout :cb, :uint,
+             :w_last_error, :uint,
+             :dw_time, :uint32,
+             :h_task, :ulong
+    end
+
+    MH_CREATE  = 1
+    MH_KEEP    = 2
+    MH_DELETE  = 3
+    MH_CLEANUP = 4
+
+    # The MONHSZSTRUCT structure contains information about a Dynamic Data Exchange (DDE) string handle. A
+    # DDE monitoring application can use this structure when monitoring the activity of the string manager
+    # component of the DDE Management Library.
+    #
+    # [*Typedef*] struct { UINT cb; BOOL fsAction; DWORD dwTime; HSZ hsz; HANDLE hTask; TCHAR str[1] } MONHSZSTRUCT;
+    #
+    # cb:: Specifies the structure's size, in bytes.
+    # fsAction:: Specifies the action being performed on the string identified by the hsz member.
+    #            MH_CLEANUP:: An application is freeing its DDE resources, causing the system to delete string handles
+    #                         the application had created. (The application called the DdeUninitialize function.)
+    #            MH_CREATE:: An application is creating a string handle. (The app called the DdeCreateStringHandle)
+    #            MH_DELETE:: An application is deleting a string handle. (The app called the DdeFreeStringHandle)
+    #            MH_KEEP:: An application is increasing the usage count of a string handle. (The application called the
+    #                      DdeKeepStringHandle function.)
+    # dwTime:: Specifies the Windows time at which the action specified by the fsAction member takes place.
+    #          Windows time is the number of milliseconds that have elapsed since the system was booted.
+    # hsz:: Handle to the string. Because string handles are local to the process, this member is a global atom.
+    # hTask:: Handle to the task (application instance) performing the action on the string handle.
+    # str:: Pointer to the string identified by the hsz member.
+    # ---
+    # Structure Information
+    # Header Declared in Ddeml.h, include Windows.h
+    #
+    class MonHszStruct < FFI::Struct # :nodoc:
+      layout :cb, :uint,
+             :fs_action, :uchar,
+             :dw_time, :uint32,
+             :hsz, :ulong,
+             :h_task, :ulong,
+             :str, :pointer
+    end
+
+    # The MONLINKSTRUCT structure contains information about a Dynamic Data Exchange (DDE) advise loop. A
+    # DDE monitoring application can use this structure to obtain information about an advise loop that has
+    # started or ended.
+    #
+    # [*Typedef*] struct { UINT cb; DWORD dwTime; HANDLE hTask; BOOL fEstablished; BOOL fNoData; HSZ hszSvc;
+    #             HSZ hszTopic; HSZ hszItem; UINT wFmt; BOOL fServer; HCONV hConvServer; HCONV hConvClient }
+    #             MONLINKSTRUCT;
+    #
+    # cb:: Specifies the structure's size, in bytes.
+    # dwTime:: Specifies the Windows time at which the advise loop was started or ended. Windows time is the
+    #          number of milliseconds that have elapsed since the system was booted.
+    # hTask:: Handle to a task (application instance) that is a partner in the advise loop.
+    # fEstablished:: Indicates whether an advise loop was successfully established. A value of TRUE
+    #                indicates an advise loop was established; FALSE indicates it was not.
+    # fNoData:: Indicates whether the XTYPF_NODATA flag is set for the advise loop. A value of TRUE
+    #           indicates the flag is set; FALSE indicates it is not.
+    # hszSvc:: Handle to the service name of the server in the advise loop.
+    # hszTopic:: Handle to the topic name on which the advise loop is established.
+    # hszItem:: Handle to the item name that is the subject of the advise loop.
+    # wFmt:: Specifies the format of the data exchanged (if any) during the advise loop.
+    # fServer:: Indicates whether the link notification came from the server. A value of TRUE indicates the
+    #           notification came from the server; FALSE indicates otherwise.
+    # hConvServer:: Handle to the server conversation.
+    # hConvClient:: Handle to the client conversation.
+    # ---
+    # *Remarks*:
+    # Because string handles are local to the process, the hszSvc, hszTopic, and hszItem members are global atoms.
+    # The hConvClient and hConvServer members of the MONLINKSTRUCT structure do not hold the same value as
+    # would be seen by the applications engaged in the conversation. Instead, they hold a globally unique
+    # pair of values that identify the conversation.
+    # ---
+    # Structure Information
+    # Header Declared in Ddeml.h, include Windows.h
+    #
+    class MonLinkStruct < FFI::Struct # :nodoc:
+      layout :cb, :uint,
+             :dw_time, :uint32,
+             :h_task, :ulong,
+             :f_established, :uchar,
+             :f_no_data, :uchar,
+             :hsz_svc, :ulong,
+             :hsz_topic, :ulong,
+             :hsz_item, :ulong,
+             :w_fmt, :uint,
+             :f_server, :uchar,
+             :h_conv_server, :ulong,
+             :h_conv_client, :ulong
+    end
+
+    # The MONMSGSTRUCT structure contains information about a Dynamic Data Exchange (DDE) message. A DDE
+    # monitoring application can use this structure to obtain information about a DDE message that was sent
+    # or posted.
+    #
+    # [*Typedef*] struct { UINT cb; HWND hwndTo; DWORD dwTime; HANDLE hTask; UINT wMsg; WPARAM wParam;
+    #             LPARAM lParam; DDEML_MSG_HOOK_DATA dmhd } MONMSGSTRUCT;
+    #
+    # cb:: Specifies the structure's size, in bytes.
+    # hwndTo:: Handle to the window that receives the DDE message.
+    # dwTime:: Specifies the Windows time at which the message was sent or posted. Windows time is the
+    #          number of milliseconds that have elapsed since the system was booted.
+    # hTask:: Handle to the task (application instance) containing the window that receives the DDE message.
+    # wMsg:: Specifies the identifier of the DDE message.
+    # wParam:: Specifies the wParam parameter of the DDE message.
+    # lParam:: Specifies the lParam parameter of the DDE message.
+    # dmhd:: Specifies a DDEML_MSG_HOOK_DATA structure that contains additional information about the DDE message.
+    # ---
+    # Structure Information
+    # Header Declared in Ddeml.h, include Windows.h
+    #
+    class MonMsgStruct < FFI::Struct # :nodoc:
+      layout :cb, :uint,
+             :hwnd_to, :ulong,
+             :dw_time, :uint32,
+             :h_task, :ulong,
+             :w_msg, :uint,
+             :w_param, :uint,
+             :l_param, :long,
+             :dmhd, :pointer
+    end
+
+    # The DDEML_MSG_HOOK_DATA structure contains information about a Dynamic Data Exchange (DDE) message,
+    # and provides read access to the data referenced by the message. This structure is intended to be used
+    # by a Dynamic Data Exchange Management Library (DDEML) monitoring application.
+    #
+    # [*Typedef*] struct { UINT_PTR uiLo; UINT_PTR uiHi; DWORD cbData; DWORD Data } DDEML_MSG_HOOK_DATA;
+    #
+    # uiLo:: Specifies the unpacked low-order word of the lParam parameter associated with the DDE message.
+    # uiHi:: Specifies the unpacked high-order word of the lParam parameter associated with the DDE message.
+    # cbData:: Specifies the amount, in bytes, of data being passed with the message. This value can be > 32.
+    # Data:: Contains the first 32 bytes of data being passed with the message (8 * sizeof(DWORD)).
+    # ---
+    # Structure Information
+    # Header Declared in Ddeml.h, include Windows.h
+    #
+    class DdemlMsgHookData < FFI::Struct # :nodoc:
+      layout :ui_lo, :uint,
+             :ui_hi, :uint,
+             :cb_data, :uint32,
+             :data, :uint32
+    end
+
     ##
     # The RegisterClipboardFormat function registers a new clipboard format.
     # This format can then be used as a valid clipboard format.
@@ -675,47 +924,6 @@ module Win
              &->(api, id, string_handle, cmd){ api.call(id, string_handle, 0, cmd) != 0 }
     # weird lambda literal instead of block is needed because RDoc goes crazy if block is attached to meta-definition
 
-    ##
-    # The DdeGetData function copies data from the specified Dynamic Data Exchange (DDE) object to the specified
-    # local buffer.
-    #
-    # [*Syntax*] DWORD DdeGetData( HDDEDATA hData, LPBYTE pDst, DWORD cbMax, DWORD cbOff );
-    #
-    # hData:: [in] Handle to the DDE object that contains the data to copy.
-    # pDst:: [out] Pointer to the buffer that receives the data. If this parameter is NULL, the DdeGetData
-    #        function returns the amount of data, in bytes, that would be copied to the buffer.
-    # cbMax:: [in] Specifies the maximum amount of data, in bytes, to copy to the buffer pointed to by the pDst
-    #         parameter. Typically, this parameter specifies the length of the buffer pointed to by pDst.
-    # cbOff:: [in] Specifies an offset within the DDE object. Data is copied from the object beginning at this offset.
-    #
-    # *Returns*:: If the pDst parameter points to a buffer, return value is the size, in bytes, of the memory object
-    #             associated with the data handle or the size specified in the cbMax parameter, whichever is lower.
-    #             If the pDst parameter is NULL, the return value is the size, in bytes, of the memory object
-    #             associated with the data handle.
-    #             The DdeGetLastError function can be used to get the error code, which can be one of the following:
-    #             - DMLERR_DLL_NOT_INITIALIZED
-    #             - DMLERR_INVALIDPARAMETER
-    #             - DMLERR_NO_ERROR
-    # ---
-    # <b> Enhanced (snake_case) API accepts only data handle, and optionally max and offset (no need to pre-allocate
-    # buffer). It returns buffer with copied DDE data (FFI::MemoryPointer) or nil for failure. DDE data length is
-    # determined internally, no need to call function twice (first time with nil buffer just to determine length).</b>
-    # ---
-    #
-    # :call-seq:
-    #  buffer, success = dde_get_data( data_handle, [max = infinite, offset = 0] )
-    #
-    function :DdeGetData, [:ulong, :pointer, :uint32, :uint32], :uint,
-             &->(api, data_handle, max=1073741823, offset=0){     # max is maximum DWORD Fixnum
-             length = api.call(data_handle, nil, 0, 0)   # determining data set length
-             if length != 0
-               copy_length = length < max ? length : max
-               buffer = FFI::MemoryPointer.new(:char, offset + copy_length)
-               length = api.call(data_handle, buffer, copy_length, offset)
-             end
-             length != 0 ? buffer: nil }
-    # weird lambda literal instead of block is needed because RDoc goes crazy if block is attached to meta-definition
-
     ##
     # DdeConnect function establishes a conversation with a server application that supports the specified service
     # name and topic name pair. If more than one such server exists, the system selects only one.
@@ -908,7 +1116,119 @@ module Win
     # :call-seq:
     #  data_handle = dde_client_transaction(data_pointer, size, conv, item, format, type, timeout, result)
     #
-    function :DdeClientTransaction, [:pointer, :uint32, :ulong, :ulong, :uint, :uint, :uint32, :pointer], :HDDEDATA
+    function :DdeClientTransaction, [:pointer, :uint32, :ulong, :ulong, :uint, :uint, :uint32, :pointer],
+             :HDDEDATA, boolean: true
+
+    ##
+    # The DdeGetData function copies data from the specified Dynamic Data Exchange (DDE) object to the specified
+    # local buffer.
+    #
+    # [*Syntax*] DWORD DdeGetData( HDDEDATA hData, LPBYTE pDst, DWORD cbMax, DWORD cbOff );
+    #
+    # hData:: [in] Handle to the DDE object that contains the data to copy.
+    # pDst:: [out] Pointer to the buffer that receives the data. If this parameter is NULL, the DdeGetData
+    #        function returns the amount of data, in bytes, that would be copied to the buffer.
+    # cbMax:: [in] Specifies the maximum amount of data, in bytes, to copy to the buffer pointed to by the pDst
+    #         parameter. Typically, this parameter specifies the length of the buffer pointed to by pDst.
+    # cbOff:: [in] Specifies an offset within the DDE object. Data is copied from the object beginning at this offset.
+    #
+    # *Returns*:: If the pDst parameter points to a buffer, return value is the size, in bytes, of the memory object
+    #             associated with the data handle or the size specified in the cbMax parameter, whichever is lower.
+    #             If the pDst parameter is NULL, the return value is the size, in bytes, of the memory object
+    #             associated with the data handle.
+    #             The DdeGetLastError function can be used to get the error code, which can be one of the following:
+    #             - DMLERR_DLL_NOT_INITIALIZED
+    #             - DMLERR_INVALIDPARAMETER
+    #             - DMLERR_NO_ERROR
+    # ---
+    # <b> Enhanced (snake_case) API accepts data handle, and optionally max and offset (no need to pre-allocate
+    # buffer). It returns pointer to copied DDE data (FFI::MemoryPointer) and size of copied data in bytes.
+    # In case of failure, it returns [nil, 0]. This API is the same as for enhanced dde_access_data.
+    # No need to call function twice (first time with nil buffer just to determine length).</b>
+    # ---
+    #
+    # :call-seq:
+    #  buffer, size = dde_get_data( data_handle, [max = infinite, offset = 0] )
+    #
+    function :DdeGetData, [:ulong, :pointer, :uint32, :uint32], :uint,
+             &->(api, data_handle, max=1073741823, offset=0){     # max is maximum DWORD Fixnum
+             size = api.call(data_handle, nil, 0, 0)   # determining data set length
+             if size == 0
+               [nil, 0]
+             else
+               copy_size = size < max ? size : max
+               buffer = FFI::MemoryPointer.new(:char, offset + copy_size)
+               size = api.call(data_handle, buffer, copy_size, offset)
+               [buffer, size]
+             end }
+    # weird lambda literal instead of block is needed because RDoc goes crazy if block is attached to meta-definition
+
+
+    ##
+    # The DdeAccessData function provides access to the data in the specified Dynamic Data Exchange (DDE)
+    # object. An application must call the DdeUnaccessData function when it has finished accessing the data
+    # in the object.
+    #
+    # [*Syntax*] LPBYTE DdeAccessData( HDDEDATA hData, LPDWORD pcbDataSize );
+    #
+    # hData:: [in] Handle to the DDE object to access.
+    # pcbDataSize:: [out] Pointer to a variable that receives the size, in bytes, of the DDE object
+    #               identified by the hData parameter. If this parameter is NULL, no size information is
+    #               returned.
+    #
+    # *Returns*:: If the function succeeds, the return value is a pointer to the first byte of data in the
+    #             DDE object.
+    # If the function fails, the return value is NULL.
+    # The DdeGetLastError function can be used to get the error code, which can be one of the following
+    # values:
+    # DMLERR_DLL_NOT_INITIALIZED
+    # DMLERR_INVALIDPARAMETER
+    # DMLERR_NO_ERROR
+    # ---
+    # *Remarks*:
+    # If the hData parameter has not been passed to a Dynamic Data Exchange Management Library (DDEML)
+    # function, an application can use the pointer returned by DdeAccessData for read-write access to the
+    # DDE object. If hData has already been passed to a DDEML function, the pointer should be used only for
+    # read access to the memory object.
+    #
+    # ---
+    # <b>Enhanced (snake_case) API accepts DDE data handle and returns FFI::MemoryPointer to raw data and
+    # size of data set in bytes (same API as enhanced dde_get_data). Returns [nil, 0] in case of failure. </b>
+    #
+    # :call-seq:
+    #  data_pointer, size = dde_access_data( data_handle )
+    #
+    function :DdeAccessData, [:HDDEDATA, :pointer], :pointer,
+             &->(api, data_handle){
+             size_buffer = FFI::MemoryPointer.new(:int16)
+             buffer = api.call(data_handle, size_buffer)
+             size = size_buffer.get_int16(0)
+             size == 0 ? [nil, 0] : [buffer, size] }
+    # weird lambda literal instead of block is needed because RDoc goes crazy if block is attached to meta-definition
+
+      ##
+      # The DdeUnaccessData function unaccesses a Dynamic Data Exchange (DDE) object. An application must call
+      # this function after it has finished accessing the object.
+      #
+      # [*Syntax*] BOOL DdeUnaccessData( HDDEDATA hData );
+      #
+      # hData:: [in] Handle to the DDE object.
+      #
+      # *Returns*:: If the function succeeds, the return value is nonzero.
+      # If the function fails, the return value is zero.
+      # The DdeGetLastError function can be used to get the error code, which can be one of the following
+      # values:
+      # DMLERR_DLL_NOT_INITIALIZED
+      # DMLERR_INVALIDPARAMETER
+      # DMLERR_NO_ERROR
+      #
+      # ---
+      # <b>Enhanced (snake_case) API returns true/false instead of nonzero/zero: </b>
+      #
+      # :call-seq:
+      #  success = dde_unaccess_data(data_handle)
+      #
+      function :DdeUnaccessData, [:HDDEDATA], :int8, boolean: true
 
   end
 end

data/lib/win/library.rb

@@ -328,10 +328,11 @@ module Win
         boolean = options[:boolean]
         zeronil = options[:zeronil]
 
-        effective_name = effective_names.inject(nil) do |func, ename|
+        effective_name = effective_names.inject(nil) do |func, effective_name|
           func || begin
-            attach_function(name, ename, params.dup, returns) # creates basic CamelCase method via FFI
-            ename
+            # tries to attach basic CamelCase method via FFI
+            attach_function(name, effective_name, params.dup, returns)
+            effective_name
           rescue FFI::NotFoundError
             nil
           end

data/spec/win/dde_spec.rb

@@ -6,12 +6,14 @@ module WinDDETest
   include Win::DDE
   include Win::GUI::Message
 
+  POKE_STRING = "Poke_string\x00\x00"
+
   def dde_cmd
     APPCLASS_STANDARD
   end
 
   def dde_callback
-    ->{}
+    ->(*args){}
   end
 
   def zero_id
@@ -35,8 +37,40 @@ module WinDDETest
      data, data1, data2]
   end
 
+  def setup_server(&server_block)
+    @client_calls = []
+    @server_calls = []
+    @client_id, st = dde_initialize(APPCLASS_STANDARD) {|*args| @client_calls << extract_values(*args); DDE_FACK}
+    @server_id, st = dde_initialize(APPCLASS_STANDARD,
+                                    &server_block || proc {|*args| @server_calls << extract_values(*args); DDE_FACK} )
+    @service_handle = dde_create_string_handle(@server_id, 'service 2', CP_WINANSI)
+    @topic_handle = dde_create_string_handle(@server_id, 'topic 2', CP_WINANSI)
+    dde_name_service(@server_id, @service_handle, DNS_REGISTER)
+  end
+
+  def teardown_server
+    if @print
+      p @server_calls, @client_calls
+      p @server_conv
+      p ERRORS[dde_get_last_error(@server_id)]
+      p ERRORS[dde_get_last_error(@client_id)]
+      @print = nil
+    end
+    dde_name_service(@server_id, @service_handle, DNS_UNREGISTER) if @server_id && @service_handle
+    dde_free_string_handle(@server_id, @service_handle) if @server_id && @service_handle
+    dde_free_string_handle(@server_id, @topic_handle) if @server_id && @topic_handle
+    dde_uninitialize(@server_id) if @server_id
+    dde_uninitialize(@client_id) if @client_id
+    if @conv_handle
+      dde_disconnect(@conv_handle)
+      @conv_handle = nil
+    end
+    @data = nil
+  end
+
   describe Win::DDE, ' contains a set of pre-defined Windows API functions' do
-    describe 'register_clipboard_format' do
+
+    describe '#register_clipboard_format' do
       spec{ use{ RegisterClipboardFormat(format_name = "XlTable") }}
       spec{ use{ register_clipboard_format(format_name = "XlTable") }}
 
@@ -57,59 +91,58 @@ module WinDDETest
       end
     end
 
-    describe 'dde_initialize' do
-      after(:each) {dde_uninitialize(@instance_id) if @instance_id}
+    describe '#dde_initialize' do
+      after(:each) {dde_uninitialize(@id) if @id}
 
-      spec{ use{ status = DdeInitialize( zero_id, dde_callback, dde_cmd, unused = 0)}}
-      spec{ use{ id, status = dde_initialize( instance_id = 0, dde_cmd) do|*args|
-      end }}
+      spec{ use{ status = DdeInitialize( id = zero_id, dde_callback, dde_cmd, unused=0); @id = id.read_long}}
+      spec{ use{ @id, status = dde_initialize(@id=0, dde_cmd, &dde_callback) }}
 
       it 'with zero instance_id, returns integer id and DMLERR_NO_ERROR if initialization successful' do
-        @instance_id, status = dde_initialize(0, APPCLASS_STANDARD) {|*args| }
-        @instance_id.should be_an Integer
-        @instance_id.should_not == 0
+        @id, status = dde_initialize(0, APPCLASS_STANDARD) {|*args| }
+        @id.should be_an Integer
+        @id.should_not == 0
         status.should == DMLERR_NO_ERROR
       end
 
       it 'with nil instance_id, returns integer id and DMLERR_NO_ERROR if initialization successful' do
-        @instance_id, status = dde_initialize(nil, APPCLASS_STANDARD) {|*args| }
-        @instance_id.should be_an Integer
-        @instance_id.should_not == 0
+        @id, status = dde_initialize(nil, APPCLASS_STANDARD) {|*args| }
+        @id.should be_an Integer
+        @id.should_not == 0
         status.should == DMLERR_NO_ERROR
       end
 
       it 'with omitted instance_id, returns integer id and DMLERR_NO_ERROR if initialization successful' do
-        @instance_id, status = dde_initialize(APPCLASS_STANDARD) {|*args| }
-        @instance_id.should be_an Integer
-        @instance_id.should_not == 0
+        @id, status = dde_initialize(APPCLASS_STANDARD) {|*args| }
+        @id.should be_an Integer
+        @id.should_not == 0
         status.should == DMLERR_NO_ERROR
       end
 
       it 'returns error status if initialization unsuccessful' do
-        @instance_id, status = dde_initialize(12345, APPCLASS_STANDARD) {|*args| }
+        @id, status = dde_initialize(12345, APPCLASS_STANDARD) {|*args| }
         status.should == DMLERR_INVALIDPARAMETER
-        @instance_id.should == nil
+        @id.should == nil
       end
 
       it 'is able to reinitialize with correct id' do
-        @instance_id, status = dde_initialize(APPCLASS_STANDARD) {|*args| }
-        new_id, status = dde_initialize(@instance_id, APPCLASS_STANDARD) {|*args| }
+        @id, status = dde_initialize(APPCLASS_STANDARD) {|*args| }
+        new_id, status = dde_initialize(@id, APPCLASS_STANDARD) {|*args| }
         status.should == DMLERR_NO_ERROR
-        new_id.should == @instance_id
+        new_id.should == @id
       end
-    end
+    end # describe 'dde_initialize'
 
     context 'after initialization:' do
-      before(:each) {@instance_id, status = dde_initialize(APPCLASS_STANDARD) {|*args| }}
-      after(:each) {dde_uninitialize(@instance_id) if @instance_id}
+      before(:each) {@id, status = dde_initialize(APPCLASS_STANDARD) {|*args| }}
+      after(:each) {dde_uninitialize(@id) if @id}
 
       describe '#dde_uninitialize' do
 
-        spec{ use{ status = DdeUninitialize( @instance_id ) }}
-        spec{ use{ id, status = dde_uninitialize( @instance_id) }}
+        spec{ use{ status = DdeUninitialize( @id ) }}
+        spec{ use{ id, status = dde_uninitialize( @id) }}
 
         it 'returns true if uninitialization successful' do
-          res = dde_uninitialize(@instance_id)
+          res = dde_uninitialize(@id)
           res.should == true
         end
 
@@ -120,129 +153,123 @@ module WinDDETest
       end # describe '#dde_uninitialize'
 
       describe '#dde_create_string_handle' do
-        after(:each) {dde_free_string_handle(@instance_id, @string_handle) if @string_handle}
+        after(:each) {dde_free_string_handle(@id, @string_handle) if @string_handle}
 
-        spec{ use{ @string_handle = DdeCreateStringHandle(instance_id=0, string_pointer, code_page_id=CP_WINANSI) }}
-        spec{ use{ @string_handle = dde_create_string_handle(instance_id=0, string='Any String', code_page_id=CP_WINANSI)}}
+        spec{ use{ @string_handle = DdeCreateStringHandle(id=0, string_pointer, code_page_id=CP_WINANSI) }}
+        spec{ use{ @string_handle = dde_create_string_handle(id=0, string='Any String', code_page_id=CP_WINANSI)}}
 
         it 'returns nonzero Integer handle to a string (passable to other DDEML functions)' do
-          @string_handle = dde_create_string_handle(@instance_id, 'My String', CP_WINANSI)
+          @string_handle = dde_create_string_handle(@id, 'My String', CP_WINANSI)
           @string_handle.should be_an Integer
           @string_handle.should_not == 0
         end
 
         it 'creates handle even if code_page is omitted' do
-          @string_handle = dde_create_string_handle(@instance_id, 'My String')
+          @string_handle = dde_create_string_handle(@id, 'My String')
           @string_handle.should be_an Integer
           @string_handle.should_not == 0
         end
 
         it 'creating two handles for the SAME string (inside one instance) USUALLY returns same handle' do
-          @string_handle = dde_create_string_handle(@instance_id, 'My String')
+          @string_handle = dde_create_string_handle(@id, 'My String')
           10.times do
-            string_handle1 = dde_create_string_handle(@instance_id, 'My String')
+            string_handle1 = dde_create_string_handle(@id, 'My String')
             string_handle1.should == @string_handle
-            dde_free_string_handle(@instance_id, string_handle1)
+            dde_free_string_handle(@id, string_handle1)
           end
         end
 
         it 'created different handles for two different strings ' do
-          @string_handle = dde_create_string_handle(@instance_id, 'My String')
-          string_handle1 = dde_create_string_handle(@instance_id, 'My String1')
+          @string_handle = dde_create_string_handle(@id, 'My String')
+          string_handle1 = dde_create_string_handle(@id, 'My String1')
           string_handle1.should_not == @string_handle
-          dde_free_string_handle(@instance_id, string_handle1)
+          dde_free_string_handle(@id, string_handle1)
         end
 
         it 'returns nil if unable to register handle to a string' do
-          @string_handle = dde_create_string_handle(@instance_id, "", CP_WINANSI)
+          @string_handle = dde_create_string_handle(@id, "", CP_WINANSI)
           @string_handle.should == nil
         end
       end # describe '#dde_create_string_handle'
 
       context "with dde string handle to 'My String 2'" do
-        before(:each) {@string_handle = dde_create_string_handle(@instance_id, 'My String 2', CP_WINANSI)}
-        after(:each) {dde_free_string_handle(@instance_id, @string_handle)}
+        before(:each) {@string_handle = dde_create_string_handle(@id, 'My String 2', CP_WINANSI)}
+        after(:each) {dde_free_string_handle(@id, @string_handle)}
 
         describe '#dde_query_string' do
 
-          spec{ use{ string = DdeQueryString(@instance_id, @string_handle, buffer, buffer.size, code_page=CP_WINANSI)}}
-          spec{ use{ string = dde_query_string(@instance_id, @string_handle, code_page=CP_WINANSI )}}
+          spec{ use{ string = DdeQueryString(@id, @string_handle, buffer, buffer.size, code_page=CP_WINANSI)}}
+          spec{ use{ string = dde_query_string(@id, @string_handle, code_page=CP_WINANSI )}}
+
+          it 'retrieves string that given string handle refers to' do
+            num_chars = DdeQueryString(@id, @string_handle, buf = buffer, buf.size, CP_WINANSI)
+            num_chars.should == 11
+            buf.read_string.should == 'My String 2'
+          end
 
           it 'retrieves string that given string handle refers to' do
-            string = dde_query_string(@instance_id, @string_handle)
+            string = dde_query_string(@id, @string_handle, CP_WINANSI)
             string.should == 'My String 2'
           end
 
           it 'retrieves string even if code_page is omitted' do
-            string = dde_query_string(@instance_id, @string_handle)
+            string = dde_query_string(@id, @string_handle)
             string.should == 'My String 2'
           end
 
           it 'returns nil attempting to retrieve invalid handle' do
-            string = dde_query_string(@instance_id, 12345)
+            string = dde_query_string(@id, 12345)
             string.should == nil
           end
         end # describe '#dde_query_string'
 
         describe '#dde_free_string_handle' do
 
-          spec{ use{ success = DdeFreeStringHandle( @instance_id, @string_handle)}}
-          spec{ use{ success = dde_free_string_handle( @instance_id, @string_handle )}}
+          spec{ use{ success = DdeFreeStringHandle( @id, @string_handle)}}
+          spec{ use{ success = dde_free_string_handle( @id, @string_handle )}}
 
           it 'returns true when freeing string handle registered with DDEML' do
-            res = dde_free_string_handle(@instance_id, @string_handle)
+            res = dde_free_string_handle(@id, @string_handle)
             res.should == true
           end
 
           it 'returns false attempting to free unregistered handle' do
-            res = dde_free_string_handle(@instance_id, 12345)
+            res = dde_free_string_handle(@id, 12345)
             res.should == false
           end
 
-          it 'keeps string accessible if there are more handles to it around' do
-            string_handle_1 = dde_create_string_handle(@instance_id, 'My String 2', CP_WINANSI)
+          it 'keeps string accessible while references to it still exist' do
+            # creates second handle to 'My String 2'
+            string_handle_1 = dde_create_string_handle(@id, 'My String 2', CP_WINANSI)
 
-            dde_free_string_handle(@instance_id, @string_handle)
+            dde_free_string_handle(@id, @string_handle)
+            dde_query_string(@id, @string_handle).should == 'My String 2'
 
-            dde_query_string(@instance_id, @string_handle).should == 'My String 2'
-            dde_free_string_handle(@instance_id, string_handle_1)
+            dde_free_string_handle(@id, string_handle_1)
+            dde_query_string(@id, @string_handle).should == nil
           end
 
           it 'makes string inaccessible once its last handle is freed' do
-            dde_free_string_handle(@instance_id, @string_handle)
-
-            dde_query_string(@instance_id, @string_handle).should == nil
+            dde_free_string_handle(@id, @string_handle)
+            dde_query_string(@id, @string_handle).should == nil
           end
         end # describe '#dde_free_string_handle'
 
-        describe '#dde_name_service' do
-          spec{ use{ success = dde_name_service(@instance_id, @string_handle, cmd=DNS_UNREGISTER ) }}
-          spec{ use{ success = DdeNameService(@instance_id, @string_handle, reserved=0, cmd=DNS_UNREGISTER) }}
-
-          it 'registers or unregisters the service names that DDE server supports' do
-            success = dde_name_service( @instance_id, @string_handle, DNS_REGISTER )
-            success.should == true
-
-            success = dde_name_service( @instance_id, @string_handle, DNS_UNREGISTER )
-            success.should == true
-          end
-        end # describe '#dde_name_service'
-
         describe '#dde_get_last_error' do
-          spec{ use{ error_code = DdeGetLastError( @instance_id) }}
-          spec{ use{ error_code = dde_get_last_error( @instance_id) }}
+          spec{ use{ error_code = DdeGetLastError(@id) }}
+          spec{ use{ error_code = dde_get_last_error(@id) }}
 
           it 'original API returns DMLERR_NO_ERROR if there is no last DDE error for given app instance' do
-            DdeGetLastError( @instance_id).should == DMLERR_NO_ERROR
+            DdeGetLastError(@id).should == DMLERR_NO_ERROR
           end
 
           it 'snake_case API returns nil if there is no last DDE error for given app instance' do
-            dde_get_last_error( @instance_id).should == nil
+            dde_get_last_error(@id).should == nil
           end
 
           it 'returns error code of last DDE error for given app instance' do
-            dde_name_service( @instance_id, 1234, DNS_REGISTER )
-            dde_get_last_error( @instance_id).should == DMLERR_INVALIDPARAMETER
+            dde_name_service(@id, 1234, DNS_REGISTER )
+            dde_get_last_error(@id).should == DMLERR_INVALIDPARAMETER
           end
         end # describe '#dde_get_last_error'
 
@@ -250,30 +277,23 @@ module WinDDETest
     end # context 'after initialization:'
 
     context 'with synthetic DDE client/server' do
-      before(:each) do
-        @client_calls = []
-        @server_calls = []
-        @client_id, status = dde_initialize(APPCLASS_STANDARD) {|*args| @client_calls << extract_values(*args); 1}
-        @server_id, status = dde_initialize(APPCLASS_STANDARD) {|*args| @server_calls << extract_values(*args); 1}
-        @service_handle = dde_create_string_handle(@server_id, 'service 2', CP_WINANSI)
-        @topic_handle = dde_create_string_handle(@client_id, 'topic 2', CP_WINANSI)
-        dde_name_service(@server_id, @service_handle, DNS_REGISTER)
-      end
-
-      after(:each) do
-#        p @server_calls, @client_calls, @server_conv
-#        p ERRORS[dde_get_last_error(@server_id)]
-#        p ERRORS[dde_get_last_error(@client_id)]
+      before(:each){ setup_server }
+      after(:each) { teardown_server}
+
+      describe '#dde_name_service' do
+        spec{ use{ success = dde_name_service(@server_id, @service_handle, cmd=DNS_UNREGISTER ) }}
+        spec{ use{ success = DdeNameService(@server_id, @service_handle, reserved=0, cmd=DNS_UNREGISTER) }}
+
+        it 'registers or unregisters the service names that DDE server supports' do
+          pending 'Register/Unregister messages don`t show up in @server_calls :('
+          success = dde_name_service(@server_id, @service_handle, DNS_REGISTER )
+          success.should == true
+          success = dde_name_service(@server_id, @service_handle, DNS_UNREGISTER )
+          success.should == true
+        end
+      end # describe '#dde_name_service'
 
-        dde_name_service(@server_id, @service_handle, DNS_UNREGISTER)
-        dde_free_string_handle(@server_id, @service_handle)
-        dde_free_string_handle(@client_id, @topic_handle)
-        dde_uninitialize(@client_id)
-        dde_uninitialize(@server_id)
-      end
-      
       describe '#dde_connect' do
-        after(:each) { dde_disconnect(@conv_handle) if @conv_handle}
         spec{ use{ @conv_handle = DdeConnect( instance_id=0, service=0, topic=0, context=nil) }}
         spec{ use{ @conv_handle = dde_connect( instance_id=0, service=0, topic=0, context=nil) }}
 
@@ -288,19 +308,12 @@ module WinDDETest
           @server_calls[1][4].should == 'service 2'
           dde_disconnect(@server_conv).should == true
           dde_disconnect(@conv_handle).should == true
-          
-          p @server_calls, @client_calls, @conv_handle, @server_conv
-          p ERRORS[dde_get_last_error(@server_id)]
-          p ERRORS[dde_get_last_error(@client_id)]
         end
-        
-        it 'connects to existing DDE server (NOT self)' do
+
+        it 'connects to existing DDE server (from @client, NOT self)' do
           pending 'something is wrong when connecting to separate service instance, uninitialize fails'
-          conv_handle = dde_connect( @client_id, @service_handle, @topic_handle, context=nil)
-          puts conv_handle
-          p @server_calls, @client_calls, @server_conv
-          p dde_disconnect(@server_conv) #conv_handle)
-#          p @server_calls, @client_calls
+          @conv_handle = dde_connect( @client_id, @service_handle, @topic_handle, context=nil)
+          puts @conv_handle
         end
       end # describe '#dde_connect'
 
@@ -312,67 +325,196 @@ module WinDDETest
           dde_disconnect(12345).should == false
         end
 
-        it 'disconnects from existing DDE server' do
-          pending 'XTYP_DISCONNECT is not received by server callback for some reason'
+        it 'disconnects from existing (self) DDE server' do
+          conv_handle = dde_connect( @server_id, @service_handle, @topic_handle, context=nil)
+          dde_disconnect(conv_handle).should == true
         end
-      end # describe '#dde_disconnect'
 
-      describe "#dde_client_transaction" do
-        after(:each) do
+        it 'disconnects from existing (self) DDE server' do
+          pending 'XTYP_DISCONNECT is not received by server callback (since we are disconnecting from self?)'
+          conv_handle = dde_connect( @server_id, @service_handle, @topic_handle, context=nil)
+          dde_disconnect(conv_handle).should == true
+          @server_calls.last[0].should == "XTYP_DISCONNECT"
           p @server_calls, @client_calls, @server_conv
           p ERRORS[dde_get_last_error(@server_id)]
           p ERRORS[dde_get_last_error(@client_id)]
         end
+      end # describe '#dde_disconnect'
+    end # context 'with synthetic DDE server'
 
-        spec{ use{ res = DdeClientTransaction(data=nil, size=0, conv=0, item=0, format=0, type=0, timeout=0, result=nil) }}
-        spec{ use{ res = dde_client_transaction(data=nil, size=0, conv=0, item=0, format=0, type=0, timeout=0, result=nil) }}
-
-        it "original api is used by CLIENT to begins a data transaction with server" do
-#          pending 'weird error - wrong number of arguments (8 for 0)'
-          p @conv_handle = dde_connect( @server_id, @service_handle, @topic_handle, context=nil)
-          str = FFI::MemoryPointer.from_string "Poke_string\n\x00\x00"
-#          res = DdeClientTransaction(str, str.size, @conv_handle, @topic_handle, CF_TEXT, XTYP_POKE, 1000, nil)
-          begin
-          get_message() if peek_message()
-          res = DdeClientTransaction(str, str.size, @conv_handle, @topic_handle, 0, XTYP_EXECUTE, 1000, nil)
-          p res
-          rescue => e
-            puts e.backtrace
-            raise e
-          end
+    describe "#dde_client_transaction" do
+      before(:each) do
+        setup_server do |*args|
+          @server_calls << extract_values(*args)
+          @data, size = dde_get_data(args[5]) if args.first == XTYP_POKE || args.first == XTYP_EXECUTE
+          DDE_FACK
         end
+      end
+      after(:each) { teardown_server}
+
+      spec{ use{ DdeClientTransaction(data=nil, size=0, conv=0, item=0, format=0, type=0, timeout=0, result=nil) }}
+      spec{ use{ dde_client_transaction(data=nil, size=0, conv=0, item=0, format=0, type=0, timeout=0, result=nil) }}
+
+      it "original api is used by CLIENT to begins a data transaction with server" do
+        @conv_handle = dde_connect( @server_id, @service_handle, @topic_handle, context=nil)
+        str = FFI::MemoryPointer.from_string POKE_STRING
+        res = DdeClientTransaction(str, str.size, @conv_handle, @topic_handle, CF_TEXT, XTYP_POKE, 1000, nil)
+        res.should == 1
+        @server_calls.any? {|call| call[0] = 'XTYP_POKE'}.should be_true
+        @data.read_string.should == POKE_STRING.rstrip
+      end
+
+      it "snake_case api begins a data transaction between a client and a server" do
+        str = FFI::MemoryPointer.from_string POKE_STRING
+        @conv_handle = dde_connect( @server_id, @service_handle, @topic_handle, context=nil)
+        res = dde_client_transaction(str, str.size, @conv_handle, @topic_handle, 0, XTYP_EXECUTE, 1000, nil)
+        res.should == true
+        @server_calls.any? {|call| call[0] = 'XTYP_EXECUTE'}.should be_true
+        @data.read_string.should == POKE_STRING.rstrip
+      end
+    end # describe dde_client_transaction
+
+    describe '#dde_get_data' do
+      after(:each) { teardown_server}
 
-        it "snake_case api begins a data transaction between a client and a server. Only a Dynamic Data Exchange (DDE) client " do
-          pending
-          success = dde_client_transaction(p_data=0, cb_data=0, h_conv=0, hsz_item=0, w_fmt=0, w_type=0, dw_timeout=0, pdw_result=0)
+      spec{ use{ data_pointer, size = dde_get_data( data_handle = 123, max = 1073741823, offset = 0) }}
+      spec{ use{ size = DdeGetData( data_handle = 123, nil, 0, 0) }} # returns dde data set size in bytes
+      spec{ use{ size = DdeGetData( data_handle = 123, FFI::MemoryPointer.new(:char, 1024), max = 1024, offset = 0) }}
+
+      it 'original API returns 0 if trying to address invalid dde data handle' do
+        DdeGetData( data_handle = 123, nil, 0, 0).should == 0
+      end
+
+      it 'snake_case API returns [nil, 0] if trying to address invalid dde data handle' do
+        data, size = dde_get_data( data_handle = 123, 3741823, 0)
+        data.should == nil
+      end
+
+      it 'returns dde data if used inside dde callback block' do
+        setup_server do |*args|
+          @server_calls << extract_values(*args);
+          if args[0] == XTYP_POKE
+            data_handle = args[5]
+            data, size = dde_get_data(data_handle)
+            data.should be_an FFI::MemoryPointer
+            data.read_string.should == POKE_STRING.rstrip
+            size.should == 14
+            DdeGetData(data_handle, nil, 0, 0).should == 14
+            data = FFI::MemoryPointer.new(:char, 1024)
+            DdeGetData(data_handle, data, data.size, 0).should == 14
+            data.read_string.should == POKE_STRING.rstrip
+          end
+          DDE_FACK
         end
-      end # describe dde_client_transaction
+        @conv_handle = dde_connect( @server_id, @service_handle, @topic_handle, context=nil)
+        str = FFI::MemoryPointer.from_string POKE_STRING
+        dde_client_transaction(str, str.size, @conv_handle, @topic_handle, CF_TEXT, XTYP_POKE, 1000, nil)
+      end
 
-      describe '#dde_get_data' do
-        spec{ use{ buffer, success = dde_get_data( data_handle = 123, max = 1073741823, offset = 0) }}
-        spec{ use{ length = DdeGetData( data_handle = 123, nil, 0, 0) }} # returns dde data set length
-        spec{ use{ length = DdeGetData( data_handle = 123, FFI::MemoryPointer.new(:char, 1024), max = 1024, offset = 0) }}
+      it 'dde data handle expires once transaction is finished (DDE_FACK)' do
+        setup_server do |*args|
+          @server_calls << extract_values(*args);
+          DDE_FACK
+        end
+        @conv_handle = dde_connect( @server_id, @service_handle, @topic_handle, context=nil)
+        str = FFI::MemoryPointer.from_string POKE_STRING
+        dde_client_transaction(str, str.size, @conv_handle, @topic_handle, CF_TEXT, XTYP_POKE, 1000, nil)
+
+        # only inside callback block dde data handle is valid (while transaction still in progress)
+        data, size = dde_get_data(@server_calls.last[5])
+        data.should == nil
+        size.should == 0
+      end
 
-        it 'original API returns 0 if trying to address invalid dde data handle' do
-          DdeGetData( data_handle = 123, nil, 0, 0).should == 0
+    end # describe '#dde_get_data'
+
+    describe "#dde_access_data" do
+      after(:each) { teardown_server}
+
+      spec{ use{ success = DdeAccessData(data_handle = 123, data_size=zero_id) }}
+      spec{ use{ data_pointer, size = dde_access_data(data_handle = 123) }}
+
+      it "provides access to the data in the specified DDE data handle (both inside and outside of callback)" do
+        setup_server do |*args|
+          @server_calls << extract_values(*args)
+          if args[0] == XTYP_POKE
+            data_handle = args[5]
+            data, size = dde_access_data(data_handle)
+            data.should be_kind_of FFI::Pointer
+            data.read_string.should == POKE_STRING.rstrip
+            size.should == 14
+            buf = FFI::MemoryPointer.new(:int16)
+            data = DdeAccessData(data_handle, buf)
+            buf.get_int16(0).should == 14
+            data.should be_kind_of FFI::Pointer
+            data.read_string.should == POKE_STRING.rstrip
+            dde_unaccess_data(data_handle)
+          end
+          DDE_FACK
         end
+        @conv_handle = dde_connect( @server_id, @service_handle, @topic_handle, context=nil)
+        str = FFI::MemoryPointer.from_string POKE_STRING
+        dde_client_transaction(str, str.size, @conv_handle, @topic_handle, CF_TEXT, XTYP_POKE, 1000, nil)
+      end
 
-        it 'snake_case API returns nil if trying to address invalid dde data handle' do
-          dde_get_data( data_handle = 123, 3741823, 0).should == nil
+      it 'dde data handle expires once transaction is finished (DDE_FACK)' do
+        setup_server do |*args|
+          @server_calls << extract_values(*args);
+          DDE_FACK
         end
+        @conv_handle = dde_connect( @server_id, @service_handle, @topic_handle, context=nil)
+        str = FFI::MemoryPointer.from_string POKE_STRING
+        dde_client_transaction(str, str.size, @conv_handle, @topic_handle, CF_TEXT, XTYP_POKE, 1000, nil)
+
+        # only inside callback block dde data handle is valid (while transaction still in progress)
+        data, size = dde_access_data(@server_calls.last[5])
+        data.should == nil
+        size.should == 0
+      end
+    end # describe dde_access_data
+
+    describe "#dde_unaccess_data" do
+      spec{ use{ success = DdeUnaccessData(data_handle = 123) }}
+      spec{ use{ success = dde_unaccess_data(data_handle = 123) }}
+
+      it "returns 0/false if given invalid DDE data handle " do
+        DdeUnaccessData(data_handle = 123).should == 0
+        dde_unaccess_data(data_handle = 123).should == false
+      end
+
+      it "unaccesses a DDE data handle that was previously accessed" do
+        setup_server do |*args|
+          @server_calls << extract_values(*args);
+          if args[0] == XTYP_POKE
+            data_handle = args[5]
+            dde_unaccess_data(data_handle).should == true
 
-        it 'original API returns 1 if connect successful' do
-          pending
-          DdeGetData( data_handle = 123, nil, 0, 0).should == 0
+            data, size = dde_access_data(data_handle)
+            data.should be_kind_of FFI::Pointer
+            data.read_string.should == POKE_STRING.rstrip
+
+            dde_unaccess_data(data_handle).should == true
+          end
+          DDE_FACK
         end
+        @conv_handle = dde_connect( @server_id, @service_handle, @topic_handle, context=nil)
+        str = FFI::MemoryPointer.from_string POKE_STRING
+        dde_client_transaction(str, str.size, @conv_handle, @topic_handle, CF_TEXT, XTYP_POKE, 1000, nil)
+      end
 
-        it 'snake_case API returns returns true if connect successful' do
-          pending
-          dde_get_data( data_handle = 123, 3741823, 0).should == nil
+      it 'dde data handle expires once transaction is finished (DDE_FACK)' do
+        setup_server do |*args|
+          @server_calls << extract_values(*args);
+          DDE_FACK
         end
+        @conv_handle = dde_connect( @server_id, @service_handle, @topic_handle, context=nil)
+        str = FFI::MemoryPointer.from_string POKE_STRING
+        dde_client_transaction(str, str.size, @conv_handle, @topic_handle, CF_TEXT, XTYP_POKE, 1000, nil)
 
-      end # describe '#dde_get_data'
+        # only inside callback block dde data handle is valid (while transaction still in progress)
+        dde_unaccess_data(@server_calls.last[5]).should == false
+      end
 
-    end # context 'with synthetic DDE server'
+    end # describe dde_unaccess_data
   end
 end

data/win.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{win}
-  s.version = "0.1.22"
+  s.version = "0.1.26"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["arvicco"]
-  s.date = %q{2010-03-06}
+  s.date = %q{2010-03-17}
   s.description = %q{Rubyesque interfaces and wrappers for Windows API functions pre-defined using FFI }
   s.email = %q{arvitallian@gmail.com}
   s.extra_rdoc_files = [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: win
 version: !ruby/object:Gem::Version 
-  version: 0.1.22
+  version: 0.1.26
 platform: ruby
 authors: 
 - arvicco
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-06 00:00:00 +03:00
+date: 2010-03-17 00:00:00 +03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency