win 0.1.2 → 0.1.9

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.9

data/lib/win/dde.rb

@@ -10,15 +10,53 @@ module Win
     # Windows ANSI codepage:
     CP_WINANSI = 1004
 
-    #
+    # DDE name service afCmd commands used by DdeNameService function:
+
+    # Registers the service name.
+
     DNS_REGISTER = 1
+    # Unregisters the service name. If the hsz1 parameter is 0L, ALL service names registered by the server will be
+    # unregistered.
     DNS_UNREGISTER = 2
+    # Turns on service name initiation filtering. The filter prevents a server from receiving
+    # XTYP_CONNECT transactions for service names it has not registered. This is the default
+    # setting for this filter. If a server application does not register any service names,
+    # the application cannot receive XTYP_WILDCONNECT transactions.
+    DNS_FILTERON   = 4
+    # Turns off service name initiation filtering. If this flag is specified, the server
+    # receives an XTYP_CONNECT transaction whenever another DDE application calls the
+    # DdeConnect function, regardless of the service name.
+    DNS_FILTEROFF  = 8
 
+    # Transaction types:
+
+    # A client uses the XTYP_CONNECT transaction to establish a conversation. A DDE server callback function,
+    # DdeCallback, receives this transaction when a client specifies a service name that the server supports
+    # (and a topic name that is not NULL) in a call to the DdeConnect function.
     XTYP_CONNECT = 0x60
     XTYP_DISCONNECT = 0xC0
+
+    # A client uses the XTYP_POKE transaction to send unsolicited data to the server. DDE server callback function, 
+    # DdeCallback, receives this transaction when a client specifies XTYP_POKE in the DdeClientTransaction function.
     XTYP_POKE = 0x90
     XTYP_ERROR = 0x00
 
+    # 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:
+
     # Registers the application as a standard (nonmonitoring) DDEML application.
     APPCLASS_STANDARD         = 0
     # Makes it possible for the application to monitor DDE activity in the system.
@@ -87,14 +125,41 @@ module Win
     MF_CONV                   = 0x40000000
     # ?
     MF_MASK                   = 0xFF000000
+
+    # Error codes:
+
     # Returned if DDE Init successful
     DMLERR_NO_ERROR           = 0x00
-    # Returned if DDE Init failed due to wrong DLL usage
+    # An application initialized as APPCLASS_MONITOR has attempted to perform a Dynamic Data Exchange (DDE) transaction,
+    # or an application initialized as APPCMD_CLIENTONLY has attempted to perform server transactions. 
     DMLERR_DLL_USAGE          = 0x4004
-    # Returned if DDE Init failed due to invalid params
+    # DMLERR_INVALIDPARAMETER A parameter failed to be validated by the DDEML. Some of the possible causes follow:
+    # - The application used a data handle initialized with a different item name handle than was required by the
+    #   transaction.
+    # - The application used a data handle that was initialized with a different clipboard data format than was
+    #   required by the transaction.
+    # - The application used a client-side conversation handle with a server-side function or vice versa.
+    # - The application used a freed data handle or string handle.
+    # - More than one instance of the application used the same object.
     DMLERR_INVALIDPARAMETER   = 0x4006
-    # Returned if DDE Init failed due to system error
+    # DMLERR_SYS_ERROR An internal error has occurred in the DDEML.
     DMLERR_SYS_ERROR          = 0x400f
+    #  DMLERR_ADVACKTIMEOUT A request for a synchronous advise transaction has timed out.
+    #  DMLERR_BUSY The response to the transaction caused the DDE_FBUSY flag to be set.
+    #  DMLERR_DATAACKTIMEOUT A request for a synchronous data transaction has timed out.
+    #  DMLERR_DLL_NOT_INITIALIZED A DDEML function was called without first calling the DdeInitialize function, or an invalid instance identifier was passed to a DDEML function.
+    #  DMLERR_DLL_USAGE
+    #  DMLERR_EXECACKTIMEOUT A request for a synchronous execute transaction has timed out.
+    #  DMLERR_LOW_MEMORY A DDEML application has created a prolonged race condition (in which the server application outruns the client), causing large amounts of memory to be consumed.
+    #  DMLERR_MEMORY_ERROR A memory allocation has failed.
+    #  DMLERR_NO_CONV_ESTABLISHED A client's attempt to establish a conversation has failed.
+    #  DMLERR_NOTPROCESSED A transaction has failed.
+    #  DMLERR_POKEACKTIMEOUT A request for a synchronous poke transaction has timed out.
+    #  DMLERR_POSTMSG_FAILED An internal call to the PostMessage function has failed.
+    #  DMLERR_REENTRANCY An application instance with a synchronous transaction already in progress attempted to initiate another synchronous transaction, or the DdeEnableCallback function was called from within a DDEML callback function.
+    #  DMLERR_SERVER_DIED A server-side transaction was attempted on a conversation terminated by the client, or the server terminated before completing a transaction.
+    #  DMLERR_UNADVACKTIMEOUT A request to end an advise transaction has timed out.
+    #  DMLERR_UNFOUND_QUEUE_ID An invalid transaction identifier was passed to a DDEML function. Once the application has returned from an XTYP_XACT_COMPLETE callback, the transaction identifier for that callback function is no longer valid.
 
     ##
     # The RegisterClipboardFormat function registers a new clipboard format.
@@ -116,7 +181,7 @@ module Win
     # form of an HGLOBAL value.
     #
     # :call-seq:
-    #   register_clipboard_format( format_name )
+    #   format_id = register_clipboard_format( format_name )
     #
     function :RegisterClipboardFormat, [:pointer], :uint, zeronil: true
 
@@ -135,7 +200,22 @@ module Win
     #         - XCLASS_BOOL - A DDE callback function should return TRUE or FALSE when it finishes processing a
     #           transaction that belongs to this class. The XCLASS_BOOL class consists of the following types:
     #           - XTYP_ADVSTART
-    #           - XTYP_CONNECT
+    #           - *XTYP_CONNECT*: A client uses the XTYP_CONNECT transaction to establish a conversation.
+    #             hsz1:: Handle to the topic name.
+    #             hsz2:: Handle to the service name.
+    #             dwData1:: Pointer to a CONVCONTEXT structure that contains context information for the conversation.
+    #                       If the client is not a Dynamic Data Exchange Management Library (DDEML) application,
+    #                       this parameter is 0.
+    #             dwData2:: Specifies whether the client is the same application instance as the server. If the
+    #                       parameter is 1, the client is the same instance. If the parameter is 0, the client
+    #                       is a different instance.
+    #             *Returns*:: A server callback function should return TRUE to allow the client to establish a
+    #                         conversation on the specified service name and topic name pair, or the function
+    #                         should return FALSE to deny the conversation. If the callback function returns TRUE
+    #                         and a conversation is successfully established, the system passes the conversation
+    #                         handle to the server by issuing an XTYP_CONNECT_CONFIRM transaction to the server's
+    #                         callback function (unless the server specified the CBF_SKIP_CONNECT_CONFIRMS flag
+    #                         in the DdeInitialize function).
     #         - XCLASS_DATA - A DDE callback function should return a DDE handle, the CBR_BLOCK return code, or
     #           NULL when it finishes processing a transaction that belongs to this class. The XCLASS_DATA
     #           transaction class consists of the following types:
@@ -147,7 +227,15 @@ module Win
     #           class consists of the following types:
     #           - XTYP_ADVDATA
     #           - XTYP_EXECUTE
-    #           - XTYP_POKE
+    #           - *XTYP_POKE*: A client uses the XTYP_POKE transaction to send unsolicited data to the server.
+    #             uFmt:: Specifies the format of the data sent from the server.
+    #             hconv:: Handle to the conversation.
+    #             hsz1:: Handle to the topic name.
+    #             hsz2:: Handle to the item name.
+    #             hdata:: Handle to the data that the client is sending to the server.
+    #             *Returns*:: A server callback function should return the DDE_FACK flag if it processes this
+    #                         transaction, the DDE_FBUSY flag if it is too busy to process this transaction,
+    #                         or the DDE_FNOTPROCESSED flag if it rejects this transaction.
     #         - XCLASS_NOTIFICATION - The transaction types that belong to this class are for notification purposes
     #           only. The return value from the callback function is ignored. The XCLASS_NOTIFICATION transaction
     #           class consists of the following types:
@@ -217,6 +305,11 @@ module Win
     #             - DMLERR_INVALIDPARAMETER
     #             - DMLERR_SYS_ERROR
     # ---
+    # <b> Enhanced API accepts only 2 parameters (get rid of reserved hsz2):
+    # instance_id:: (optional) Application instance identifier. At initialization, this parameter should be 0, nil
+    #               or omitted altogether. If it is nonzero/non-nil, reinitialization of the DDEML is implied.
+    # cmd(afCmd):: obligatory set of flags
+    # ---
     # *Remarks*:
     # - An application that uses multiple instances of the DDEML must not pass DDEML objects between instances.
     # - A DDE monitoring application should not attempt to perform DDE operations (establish conversations,
@@ -231,19 +324,38 @@ module Win
     #   value for the iCodePage member of the CONVCONTEXT structure (CP_WINANSI or CP_WINUNICODE).
     #
     # :call-seq:
-    #  instance_id, status = dde_initialize( instance_id = 0, cmd )
+    #  instance_id, status = dde_initialize( [instance_id = 0], cmd )
     #  {|type, format, hconv, hsz1, hsz2, hdata, data1, data2| your dde_callback block}
     #
-    function :DdeInitialize, [:pointer, :DdeCallback, :DWORD, :DWORD], :uint,
+    function :DdeInitialize, [:pointer, :DdeCallback, :uint32, :uint32], :uint,
              &->(api, old_id=0, cmd, &block){
              raise ArgumentError, 'No callback block' unless block
-             id = FFI::MemoryPointer.new(:long)
-             id.write_long(old_id)
+             old_id = 0 unless old_id
+             id = FFI::MemoryPointer.new(:long).write_long(old_id)
              status = api.call(id, block, cmd, 0)
              id = status == 0 ? id.read_long() : nil
              [id, status] }
     # weird lambda literal instead of block is needed because RDoc goes crazy if block is attached to meta-definition
 
+    ##
+    # The DdeUninitialize function frees all Dynamic Data Exchange Management Library (DDEML) resources associated
+    # with the calling application.
+    #
+    # [*Syntax*] BOOL DdeUninitialize( DWORD idInst);
+    #
+    # idInst:: [in] Specifies the application instance identifier obtained by a previous call to the DdeInitialize.
+    # *Returns*:: If the function succeeds, the return value is nonzero.
+    #             If the function fails, the return value is zero.
+    # ---
+    # *Remarks*
+    # DdeUninitialize terminates any conversations currently open for the application.
+    #
+    # :call-seq:
+    #  success = dde_uninitialize( instance_id )
+    #
+    function :DdeUninitialize, [:uint32], :int, boolean: true
+
+
     ##
     # The DdeCreateStringHandle function creates a handle that identifies the specified string.
     # A Dynamic Data Exchange (DDE) client or server application can pass the string handle as a
@@ -265,6 +377,8 @@ module Win
     #             The DdeGetLastError function can be used to get the error code, which can be one of the
     #             following values: DMLERR_NO_ERROR, DMLERR_INVALIDPARAMETER, DMLERR_SYS_ERROR
     # ---
+    # <b> Enhanced (snake_case) API makes code_page param optional and returns *nil* if handle creation fails. </b>
+    # ---
     # *Remarks*: The value of a string handle is not related to the case of the string it identifies.
     # When an application either creates a string handle or receives one in the callback function
     # and then uses the DdeKeepStringHandle function to keep it, the application must free that string
@@ -274,7 +388,219 @@ module Win
     # :call-seq:
     #  string_handle = dde_create_string_handle( instance_id, string, code_page_id )
     #
-    function :DdeCreateStringHandle, [:DWORD, :pointer, :int], :HSZ, zeronil: true
+    function :DdeCreateStringHandle, [:uint32, :pointer, :int], :ulong, zeronil: true,
+             &->(api, instance_id, string, code_page=CP_WINANSI){ api.call(instance_id, string, code_page) }
+
+    ##
+    # The DdeFreeStringHandle function frees a string handle in the calling application.
+    #
+    # [*Syntax*] BOOL DdeFreeStringHandle( DWORD idInst, HSZ hsz );
+    #
+    # idInst:: [in] Specifies the application instance identifier obtained by a previous call to the DdeInitialize.
+    # hsz:: [in, out] Handle to the string handle to be freed. This handle must have been created by a previous call
+    #       to the DdeCreateStringHandle function.
+    # *Returns*:: If the function succeeds, the return value is nonzero. If the function fails, it is zero.
+    # ---
+    # <b> Enhanced snake_case API returns boolean true/false as a success indicator. </b>
+    # ---
+    # *Remarks*:
+    # An application can free string handles it creates with DdeCreateStringHandle but should not free those that
+    # the system passed to the application's Dynamic Data Exchange (DDE) callback function or those returned in the
+    # CONVINFO structure by the DdeQueryConvInfo function.
+    #
+    # :call-seq:
+    #  success = dde_free_string_handle( instance_id, string_handle )
+    #
+    function :DdeFreeStringHandle, [:uint32, :ulong], :int, boolean: true
+
+    ##
+    # The DdeQueryString function copies text associated with a string handle into a buffer.
+    #
+    # [*Syntax*] DWORD DdeQueryString( DWORD idInst, HSZ hsz, LPTSTR psz, DWORD cchMax, int iCodePage);
+    #
+    # idInst:: [in] Specifies the application instance identifier obtained by a previous call to the DdeInitialize.
+    # hsz:: [in] Handle to the string to copy. This handle must have been created by a previous call to the
+    #            DdeCreateStringHandle function.
+    # psz:: [in, out] Pointer to a buffer that receives the string. To obtain the length of the string, this parameter
+    #       should be set to NULL.
+    # cchMax::  [in] Specifies the length, in TCHARs, of the buffer pointed to by the psz parameter. For the ANSI
+    #           version of the function, this is the number of bytes; for the Unicode version, this is the number of
+    #           characters. If the string is longer than ( cchMax– 1), it will be truncated. If the psz parameter is
+    #           set to NULL, this parameter is ignored.
+    # iCodePage:: [in] Code page used to render the string. This value should be either CP_WINANSI or CP_WINUNICODE.
+    #
+    # *Returns*:: If the psz parameter specified a valid pointer, the return value is the length, in TCHARs, of the
+    #             returned text (not including the terminating null character). If the psz parameter specified a NULL
+    #             pointer, the return value is the length of the text associated with the hsz parameter (not including
+    #             the terminating null character). If an error occurs, the return value is 0L.
+    # ---
+    # <b> Enhanced (snake_case) API makes all args optional except for first (dde instance id), and returns nil if
+    # the function was unsuccessful.</b>
+    # ---
+    # *Remarks*
+    # - The string returned in the buffer is always null-terminated. If the string is longer than ( cchMax– 1),
+    #   only the first ( cchMax– 1) characters of the string are copied.
+    # - If the psz parameter is NULL, the DdeQueryString function obtains the length, in bytes, of the string
+    #   associated with the string handle. The length does not include the terminating null character.
+    #
+    # :call-seq:
+    #  string = dde_query_string( instance_id, handle, [code_page = CP_WINANSI ] )
+    #
+    function :DdeQueryString, [:uint32, :ulong, :pointer, :uint32, :int], :uint32,
+             &->(api, instance_id, handle, code_page = CP_WINANSI){
+             buffer = FFI::MemoryPointer.new :char, 1024
+             num_chars = api.call(instance_id, handle, buffer, buffer.size, code_page)
+             num_chars == 0 ? nil : buffer.get_bytes(0, num_chars) }
+
+    ##
+    # The DdeNameService function registers or unregisters the service names a Dynamic Data Exchange (DDE) server
+    # supports. This function causes the system to send XTYP_REGISTER or XTYP_UNREGISTER transactions to other running
+    # Dynamic Data Exchange Management Library (DDEML) client applications.
+    #
+    # [*Syntax*] HDDEDATA DdeNameService( DWORD idInst, UINT hsz1, UINT hsz2, UINT afCmd );
+    #
+    # idInst:: [in] Specifies the application instance identifier obtained by a previous call to the DdeInitialize.
+    # hsz1:: [in] Handle to the string that specifies the service name the server is registering or unregistering.
+    #        An application that is unregistering all of its service names should set this parameter to 0L.
+    # hsz2:: Reserved; should be set to 0L.
+    # afCmd:: [in] Specifies the service name options. This parameter can be one of the following values.
+    #         DNS_REGISTER::  Registers the service name.
+    #         DNS_UNREGISTER:: Unregisters the service name. If the hsz1 parameter is 0L,
+    #                          all service names registered by the server will be unregistered.
+    #         DNS_FILTERON:: Turns on service name initiation filtering. The filter prevents a server from receiving
+    #                        XTYP_CONNECT transactions for service names it has not registered. This is the default
+    #                        setting for this filter. If a server application does not register any service names,
+    #                        the application cannot receive XTYP_WILDCONNECT transactions.
+    #         DNS_FILTEROFF:: Turns off service name initiation filtering. If this flag is specified, the server
+    #                         receives an XTYP_CONNECT transaction whenever another DDE application calls the
+    #                         DdeConnect function, regardless of the service name.
+    # *Returns*:: If the function succeeds, it returns nonzero (*true* in snake_case method). For CamelCase, that
+    #             value is not really HDDEDATA value, but merely a Boolean indicator of success. The function is
+    #             typed HDDEDATA to allow for future expansion of the function and more sophisticated returns.
+    #             If the function fails, the return value is 0L (*false* in snake_case method). The DdeGetLastError
+    #             function can be used to get the error code, which can be one of the following:
+    #             - DMLERR_DLL_NOT_INITIALIZED
+    #             - DMLERR_DLL_USAGE
+    #             - DMLERR_INVALIDPARAMETER
+    #             - DMLERR_NO_ERROR
+    # ---
+    # <b> Enhanced API accepts only 3 parameters (get rid of reserved hsz2) and returns boolean true/false. </b>
+    # ---
+    # *Remarks*:
+    # The service name identified by the hsz1 parameter should be a base name (that is, the name should contain no
+    # instance-specific information). The system generates an instance-specific name and sends it along with the
+    # base name during the XTYP_REGISTER and XTYP_UNREGISTER transactions. The receiving applications can then
+    # connect to the specific application instance.
+    #
+    # :call-seq:
+    #  success = dde_name_service( instance_id, string_handle, cmd )
+    #
+    function :DdeNameService, [:uint32, :ulong, :ulong, :uint], :ulong,
+             &->(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.
+    #
+    # [*Syntax*] HCONV DdeConnect( DWORD idInst, HSZ hszService, HSZ hszTopic, PCONVCONTEXT pCC );
+    #
+    # idInst::  [in] Specifies the application instance identifier obtained by a previous call to the DdeInitialize.
+    # hszService:: [in] Handle to the string that specifies the service name of the server application with which
+    #              a conversation is to be established. This handle must have been created by a previous call to
+    #              the DdeCreateStringHandle function. If this parameter is 0L, a conversation is established with
+    #              any available server.
+    # hszTopic:: [in] Handle to the string that specifies the name of the topic on which a conversation is to be
+    #            established. This handle must have been created by a previous call to DdeCreateStringHandle.
+    #            If this parameter is 0L, a conversation on any topic supported by the selected server is established.
+    # pCC:: [in] Pointer to the CONVCONTEXT structure that contains conversation context information. If this
+    #            parameter is NULL, the server receives the default CONVCONTEXT structure during the XTYP_CONNECT
+    #            or XTYP_WILDCONNECT transaction.
+    # *Returns*:: If the function succeeds, the return value is the handle to the established conversation.
+    #              If the function fails, the return value is 0L. 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_CONV_ESTABLISHED
+    #              - DMLERR_NO_ERROR
+    # ---
+    # <b> Enhanced (snake_case) API makes all args optional except for first (dde instance id), and returns nil if
+    # the function was unsuccessful.</b>
+    # ---
+    # *Remarks*
+    # - The client application cannot make assumptions regarding the server selected. If an instance-specific name
+    #   is specified in the hszService parameter, a conversation is established with only the specified instance.
+    #   Instance-specific service names are passed to an application's Dynamic Data Exchange (DDE) callback function
+    #   during the XTYP_REGISTER and XTYP_UNREGISTER transactions.
+    # - All members of the default CONVCONTEXT structure are set to zero except cb, which specifies the size of the
+    #   structure, and iCodePage, which specifies CP_WINANSI (the default code page) or CP_WINUNICODE, depending on
+    #   whether the ANSI or Unicode version of the DdeInitialize function was called by the client application. 
+    #
+    # :call-seq:
+    #  conversation_handle = dde_connect( instance_id, [service = nil, topic = nil, context = nil] )
+    #
+    function :DdeConnect, [:uint32, :ulong, :ulong, :pointer], :ulong, zeronil: true,
+             &->(api, instance_id, service = nil, topic = nil, context = nil){
+             api.call(instance_id, service, topic, context) }
+
+    ##
+    # The DdeGetLastError function retrieves the most recent error code set by the failure of a Dynamic Data Exchange
+    # Management Library (DDEML) function and resets the error code to DMLERR_NO_ERROR.
+    #
+    # [*Syntax*] UINT DdeGetLastError( DWORD idInst );
+    #
+    # idInst::  [in] Specifies the application instance identifier obtained by a previous call to the DdeInitialize.
+    #
+    # *Returns*:: If the function succeeds, the return value is the last error code, which can be one of the following:
+    # DMLERR_ADVACKTIMEOUT, DMLERR_EXECACKTIMEOUT, DMLERR_INVALIDPARAMETER, DMLERR_LOW_MEMORY, DMLERR_MEMORY_ERROR,
+    # DMLERR_NO_CONV_ESTABLISHED, DMLERR_NOTPROCESSED, DMLERR_POKEACKTIMEOUT, DMLERR_POSTMSG_FAILED, DMLERR_REENTRANCY,
+    # DMLERR_SERVER_DIED, DMLERR_SYS_ERROR, DMLERR_UNADVACKTIMEOUT, DMLERR_UNFOUND_QUEUE_ID
+    #
+    # :call-seq:
+    #  string = dde_get_last_error( instance_id )
+    #
+    function :DdeGetLastError, [:uint32], :int, zeronil: true
 
   end
 end

data/lib/win/gui/input.rb

@@ -251,7 +251,7 @@ module Win
       # Y:: [in] Specifies the new y-coordinate of the cursor, in screen coordinates.
       #
       # *Returns*:: Nonzero(*true*) if successful or zero(*false*) otherwise. To get extended error information,
-      #           call GetLastError. Enhanced to return true/false instead of nonzero/zero
+      #             call GetLastError. Enhanced to return true/false instead of nonzero/zero
       # ---
       # *Remarks*: The cursor is a shared resource. A window should move the cursor only when the cursor is in the
       # window's client area. The calling process must have WINSTA_WRITEATTRIBUTES access to the window station.

data/lib/win/gui/message.rb

@@ -235,7 +235,7 @@ module Win
       # App-specific (non-reserved) messages above this one (WM_App+1, etc...)
       WM_APP                        = 0x8000
 
-      # Sys Commands: 
+      # Sys Commands:
 
       #
       SC_SIZE         = 0xF000
@@ -259,26 +259,67 @@ module Win
       SC_MONITORPOWER = 0xF170
       SC_CONTEXTHELP  = 0xF180
 
+      ##
       function :BroadcastSystemMessage, 'LPIIL', 'L'
+
+      ##
       function :DefWindowProc, 'LLLL', 'L'
+
+      ##
       function :DispatchMessage, 'P', 'L'
+
+      ##
       function :GetInputState, 'V', 'B'
+
+      ##
       function :GetMessage, 'PLII', 'B'
+
+      ##
       function :GetMessageExtraInfo, 'V', 'L'
+
+      ##
       function :GetMessagePos, 'V', 'L'
+
+      ##
       function :GetMessageTime, 'V', 'L'
+
+      ##
       function :GetQueueStatus, 'I', 'L'
+
+      ##
       function :InSendMessage, 'V', 'B'
+
+      ##
       function :InSendMessageEx, 'L', 'L'
+
+      ##
       function :PeekMessage, 'PLIII', 'B'
+
+      ##
       function :PostQuitMessage, 'I', 'V'
+
+      ##
       function :PostThreadMessage, 'LILL', 'B'
+
+      ##
       function :RegisterWindowMessage, 'P', 'I'
+
+      ##
       function :ReplyMessage, 'L', 'B'
+
+      ##
       function :SendMessageTimeout, 'LILLIIP', 'L'
+
+      ##
       function :SendNotifyMessage, 'LILLIIP', 'L'
+
+      ##
       function :SetMessageExtraInfo, 'L', 'L'
+
+      ##
       function :TranslateMessage, 'P', 'B'
+
+      ##
       function :WaitMessage, 'V', 'B'
 
       ##
@@ -296,7 +337,7 @@ module Win
       # lResult:: [in] Specifies the result of the message processing. This value depends on the message.
       #
       # :call-seq:
-      #  SendAsyncProc callback block: {|handle, msg, w_param, l_param| your code }
+      #  SendAsyncProc callback block: {|handle, msg, data, l_result| your callbackcode }
       #
       callback :SendAsyncProc, [:long, :uint, :ulong, :ulong, :long], :void
 
@@ -334,7 +375,11 @@ module Win
       #  - The callback function is called only when the thread that called SendMessageCallback also calls GetMessage,
       #    PeekMessage, or WaitMessage.
       #
-      function :SendMessageCallback, [:long, :uint, :uint, :long, :SendAsyncProc, :ulong], :bool
+      # :call-seq:
+      #  success = send_message_callback(handle, msg, w_param, l_param, data)
+      #            {|handle, msg, data, l_result| callback code }
+      #
+      function :SendMessageCallback, [:long, :uint, :uint, :long, :SendAsyncProc, :ulong], :int, boolean: true
 
       ##
       # The PostMessage function places (posts) a message in the message queue associated with the thread that
@@ -343,14 +388,14 @@ module Win
       #
       # [*Syntax*] BOOL PostMessage( HWND hWnd, UINT Msg, WPARAM wParam, LPARAM lParam);
       #
-      # handle:: [in] Handle to the window whose window procedure will receive the message. If this parameter is
+      # hWnd::   [in] Handle to the window whose window procedure will receive the message. If this parameter is
       #          HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or
       #          invisible unowned windows, overlapped windows, and pop-up windows; but the message is not posted to
       #          child windows. If it is NULL, the function behaves like a call to PostThreadMessage()
       #          with the dwThreadId parameter set to the identifier of the current thread.
-      # msg:: [in] Specifies the message to be posted.
-      # w_param:: [in] Specifies additional message-specific information.
-      # l_param:: [in] Specifies additional message-specific information.
+      # Msg:: [in] Specifies the message to be posted.
+      # wParam:: [in] Specifies additional message-specific information.
+      # lParam:: [in] Specifies additional message-specific information.
       #
       # *Returns*:: Nonzero if the function succeeds, zero if it fails. For extended error info, call GetLastError.
       # ---
@@ -371,10 +416,50 @@ module Win
       #:call-seq:
       # success = post_message(handle, msg, w_param, l_param)
       #
-      function :PostMessage, [:ulong, :uint, :long, :uint], :bool
-
-      function :SendMessage, 'LLLP', 'L'
+      function :PostMessage, [:ulong, :uint, :long, :uint], :int, boolean: true
 
+      ##
+      # The SendMessage function sends the specified message to a window or windows. It calls the window procedure for
+      # the specified window and does not return until the window procedure has processed the message.
+      #
+      # To send a message and return immediately, use the SendMessageCallback or SendNotifyMessage function. To post a
+      # message to a thread's message queue and return immediately, use the PostMessage or PostThreadMessage function.
+      #
+      #
+      # [*Syntax*] LRESULT SendMessage( HWND hWnd, UINT Msg, WPARAM wParam, LPARAM lParam );
+      #
+      # hWnd:: [in] Handle to the window whose window procedure will receive the message. If this parameter is
+      #        HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or
+      #        invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to
+      #        child windows.
+      #        Microsoft Windows Vista and later. Message sending is subject to User Interface Privilege Isolation
+      #        (UIPI). The thread of a process can send messages only to message queues of threads in processes of
+      #        lesser or equal integrity level.
+      # Msg:: [in] Specifies the message to be sent.
+      # wParam:: [in] Specifies additional message-specific information.
+      # lParam:: [in/out?] Specifies additional message-specific information.
+      #
+      # *Return*:: The return value specifies the result of the message processing; it depends on the message sent.
+      # ---
+      # *Remarks*:
+      # - Microsoft Windows Vista and later. When a message is blocked by UIPI the last error, retrieved with
+      #   GetLastError, is set to 5 (access denied).
+      # - Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function
+      #   to obtain a unique message for inter-application communication.
+      # - The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
+      #   messages (those >= WM_USER) to another process, you must do custom marshalling.
+      # - If the specified window was created by the calling thread, the window procedure is called immediately as
+      #   a subroutine. If the specified window was created by a different thread, the system switches to that thread
+      #   and calls the appropriate window procedure. Messages sent between threads are processed only when the
+      #   receiving thread executes message retrieval code. The sending thread is blocked until the receiving thread
+      #   processes the message. However, the sending thread will process incoming nonqueued messages while waiting
+      #   for its message to be processed. To prevent this, use SendMessageTimeout with SMTO_BLOCK set. For more
+      #   information on nonqueued messages, see Nonqueued Messages.
+      #
+      #:call-seq:
+      # send_message(handle, msg, w_param, l_param)
+      #
+      function :SendMessage, [:ulong, :uint, :long, :pointer], :int   # LPARAM different from PostMessage!
 
     end
   end

data/lib/win/gui/window.rb

@@ -394,8 +394,7 @@ module Win
       function :GetWindowThreadProcessId, [:ulong, :pointer], :long,
                &->(api, *args) {
                namespace.enforce_count( args, api.prototype, -1)
-               process = FFI::MemoryPointer.new(:long)
-               process.write_long(1)
+               process = FFI::MemoryPointer.new(:long).write_long(1)
                thread = api.call(args.first, process)
                thread == 0 ? [nil, nil] : [thread, process.read_long()] }
       # weird lambda literal instead of normal block is needed because current version of RDoc
@@ -429,7 +428,7 @@ module Win
                &->(api, *args) {
                namespace.enforce_count( args, api.prototype, -1)
                rect = FFI::MemoryPointer.new(:long, 4)
-               rect.write_array_of_long([0, 0, 0, 0])
+               #rect.write_array_of_long([0, 0, 0, 0])
                res = api.call args.first, rect
                res == 0 ? [nil, nil, nil, nil] :  rect.read_array_of_long(4) }
       # weird lambda literal instead of normal block is needed because current version of RDoc

data/lib/win/library.rb

@@ -75,7 +75,7 @@ module Win
               c:  :char, # 8-bit character (byte)
               #   :int8       – 8-bit signed integer
               #   :uint8      – 8-bit unsigned integer
-              S:  :ushort, # – 16-bit unsigned integer (Win32API: used for string)
+              S:  :ushort, # – 16-bit unsigned integer (Win32/API: S used for string params)
               s:  :short, # – 16-bit signed integer
               #   :uint16     – 16-bit unsigned integer
               #   :int16      – 16-bit signed integer

data/spec/spec_helper.rb

@@ -12,17 +12,21 @@ module ClassMacros
   # wrapper for it method that extracts description from example source code, such as:
   # spec { use{    function(arg1 = 4, arg2 = 'string')  }}
   def spec &block
-    if RUBY_PLATFORM =~ /java/
-      it 'not able to extract description', &block
-    else
-      it description_from(*block.source_location), &block
-    end
+    it description_from(caller[0]), &block # it description_from(*block.source_location), &block
+    #do lambda(&block).should_not raise_error end
   end
 
-  # reads description line from source file and drops external brackets (like its{}, use{}
-  def description_from(file, line)
+  # reads description line from source file and drops external brackets like its{}, use{}
+  # accepts as arguments either file name and line or call stack member (caller[0])
+  def description_from(*args)
+    case args.size
+      when 1
+        file, line = args.first.scan(/\A(.*?):(\d+)/).first
+      when 2
+        file, line = args
+    end
     File.open(file) do |f|
-      f.lines.to_a[line-1].gsub( /(spec.*?{)|(use.*?{)|}/, '' ).strip
+      f.lines.to_a[line.to_i-1].gsub( /(spec.*?{)|(use.*?{)|}/, '' ).strip
     end
   end
 end
@@ -32,6 +36,7 @@ module InstanceMacros
   def use
     lambda{yield}.should_not raise_error
   end
+
   def any_block
     lambda{|*args| args}
   end
@@ -40,6 +45,12 @@ end
 Spec::Runner.configure do |config|
   config.extend(ClassMacros)
   config.include(InstanceMacros)
+
+  class << Spec::ExampleGroup
+#    def spoc &block
+#      it description_from(caller[0]), &block
+#    end
+  end
 end
 
 module WinTest

data/spec/win/dde_spec.rb

@@ -13,6 +13,14 @@ module WinDDETest
     ->{}
   end
 
+  def zero_id
+    FFI::MemoryPointer.new(:long).write_long(0)
+  end
+
+  def buffer
+    FFI::MemoryPointer.new(:char, 1024)
+  end
+
   describe Win::DDE, ' contains a set of pre-defined Windows API functions' do
     describe 'register_clipboard_format' do
       spec{ use{ RegisterClipboardFormat(format_name = "XlTable") }}
@@ -36,10 +44,25 @@ module WinDDETest
     end
 
     describe 'dde_initialize' do
-      spec{ use{ status = DdeInitialize( id = [0].pack('L'), dde_callback, dde_cmd, unused = 0)}}
-      spec{ use{ id, status = dde_initialize( id = 0, dde_cmd) do|*args| end }}
+      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 }}
+
+      it 'with zero instance_id, returns integer id and DMLERR_NO_ERROR if initialization successful' do
+        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
+        id, status = dde_initialize(nil, APPCLASS_STANDARD) {|*args| }
+        id.should be_an Integer
+        id.should_not == 0
+        status.should == DMLERR_NO_ERROR
+      end
 
-      it 'returns integer id and 0 if initialization successful' do
+      it 'with omitted instance_id, returns integer id and DMLERR_NO_ERROR if initialization successful' do
         id, status = dde_initialize(APPCLASS_STANDARD) {|*args| }
         id.should be_an Integer
         id.should_not == 0
@@ -58,12 +81,153 @@ module WinDDETest
         status.should == DMLERR_NO_ERROR
         new_id.should == id
       end
+    end
+
+    context 'after initialization:' do
+      before(:each) {@instance_id, status = dde_initialize(APPCLASS_STANDARD) {|*args| }}
+      after(:each) {dde_uninitialize(@instance_id)}
+
+      describe '#dde_uninitialize' do
+
+        spec{ use{ status = DdeUninitialize( @instance_id ) }}
+        spec{ use{ id, status = dde_uninitialize( @instance_id) }}
+
+        it 'returns true if uninitialization successful' do
+          res = dde_uninitialize(@instance_id)
+          res.should == true
+        end
+
+        it 'returns false if initialization unsuccessful' do
+          res = dde_uninitialize(12345)
+          res.should == false
+        end
+      end
+
+      describe '#dde_create_string_handle' do
+        spec{ use{ string_handle = DdeCreateStringHandle(instance_id=0, string='Any String', code_page_id=CP_WINANSI) }}
+        spec{ use{ string_handle = dde_create_string_handle(instance_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.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.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_handle1 = dde_create_string_handle(@instance_id, 'My String')
+          10.times do
+            string_handle2 = dde_create_string_handle(@instance_id, 'My String')
+            string_handle1.should == string_handle2
+          end
+        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.should == nil
+        end
+
+      end
+
+      context "with dde string handle to 'My String':" do
+        before(:each) {@string_handle = dde_create_string_handle(@instance_id, 'My String', CP_WINANSI)}
+        after(:each) {dde_free_string_handle(@instance_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 )}}
+
+          it 'retrieves string that given string handle refers to' do
+            string = dde_query_string(@instance_id, @string_handle)
+            string.should == 'My String'
+          end
+
+          it 'retrieves string even if code_page is omitted' do
+            string = dde_query_string(@instance_id, @string_handle)
+            string.should == 'My String'
+          end
+
+          it 'returns nil attempting to retrieve invalid handle' do
+            string = dde_query_string(@instance_id, 12345)
+            string.should == nil
+          end
+        end
+
+        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 )}}
+
+          it 'returns true when freeing string handle registered with DDEML' do
+            res = dde_free_string_handle(@instance_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.should == false
+          end
+        end
+
+        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_get_last_error' do
+          spec{ use{ error_code = DdeGetLastError( @instance_id) }}
+          spec{ use{ error_code = dde_get_last_error( @instance_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
+          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
+          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
+          end
+        end
+
+      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 '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 if trying to address invalid dde data handle' do
+          dde_get_data( data_handle = 123, 3741823, 0).should == nil
+        end
 
-      it 'returns nil if not able to initialize' do
-        pending
-        register_clipboard_format("").should == nil
       end
+
+      describe '#dde_connect' do
+        it 'connects to existing DDE server'
+      end
+
     end
   end
 end
-

data/spec/win/gui/message_spec.rb

@@ -10,6 +10,7 @@ module WinGuiMessageTest
   describe Win::Gui::Message do
 
     describe '#post_message' do
+      spec{ use{ success = PostMessage(handle = 0, msg = 0, w_param = 0, l_param = 0) }}
       spec{ use{ success = post_message(handle = 0, msg = 0, w_param = 0, l_param = 0) }}
 
       it 'places (posts) a message in the message queue associated with the thread that created the specified window'
@@ -17,6 +18,7 @@ module WinGuiMessageTest
     end
 
     describe '#send_message' do
+      spec{ use{ success = SendMessage(handle = 0, msg = 0, w_param = 1024, l_param = "\x0"*1024) }}
       spec{ use{ success = send_message(handle = 0, msg = 0, w_param = 1024, l_param = "\x0"*1024) }}
       # handle (L) - Handle to the window whose window procedure is to receive the message. The following values have special meanings.
       #   HWND_BROADCAST - The message is posted to all top-level windows in the system, including disabled or invisible unowned windows,

data/win.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{win}
-  s.version = "0.1.2"
+  s.version = "0.1.9"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["arvicco"]
-  s.date = %q{2010-02-16}
+  s.date = %q{2010-02-19}
   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.2
+  version: 0.1.9
 platform: ruby
 authors: 
 - arvicco
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-16 00:00:00 +03:00
+date: 2010-02-19 00:00:00 +03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency