Instance-Specific String Handles (HSZs) in DDEML

Last reviewed: November 2, 1995
Article ID: Q94953

The information in this article applies to:

Microsoft Windows Software Development Kit (SDK) versions 3.1

Microsoft Win32 Application Programming Interface (API) included with:

    - Microsoft Windows NT versions 3.5 and 3.51
    - Microsoft Windows 95 version 4.0

SUMMARY

Instance-specific string handles in DDEML may be used in DdeConnect() or DdeConnectList() in order to connect to a particular instance of a server. These string handles are received by a DDEML callback as the HSZ2 parameter to the XTYP_REGISTER/XTYP_UNREGISTER transactions whenever a server application registers or unregisters the service name it supports.

This article explains how instance-specific HSZs are internally implemented in the Windows 3.1 DDEML; however, this is for purposes of illustration only because the implementation may change in future versions of DDEML, particularly in Win32. However, the behavior will be the same.

MORE INFORMATION

Currently, instance-specific string handles contain two pieces of information: the original service name string plus the handle to a hidden window created by DDEML, which is associated with that string. These two pieces of information are then merged [that is, MAKELONG (SvcNameAtom, hWnd)] into an HSZ.

It is important to underscore what the documents on DdeCreateStringHandle() say in reference to instance-specific HSZs (see the Comments section of the Windows 3.1 Software Development Kit (SDK) "Programmer's Reference, Volume 2: Functions," page 169):

   An instance-specific string handle is not mappable from string
   handle to string to string handle again. The DdeQueryString()
   function creates a string from a string handle and then
   DdeCreateStringHandle() creates a string handle from that string,
   but the two handles are not the same.

This might be better explained as follows:

Server registers itself:

      0x0000C18F = DdeCreateStringHandle (,"SERVER",);
      DdeNameService (,0x0000C18F,,);

Callbacks receive two HSZs in XTYP_REGISTER:

      HSZ1 = 0x0000C18F  (normal HSZ)
      HSZ2 = 0x56F8C18F  (instance-specific HSZ)

Client does a DdeQueryString() on the HSZ2 returned above, and creates a string handle with the string returned.

      DdeQueryString (,0x56F8C18F, myLpstr,,,);
            // where myLpstr returned = "SERVER:(56F8)"

      0x0000C193= DdeCreateStringHandle (,myLpstr,);

   Note how instance-specific 0x56F8C18F passed in to DdeQueryString()
   is not the same as the HSZ returned (0x0000C193) from the
   DdeCreateStringHandle() on the same string; whereas regular string
   handles (that is, non-instance-specific HSZs) would have mapped to
   the same string handle.

Additional reference words: 3.10 3.50 4.00 95
KBCategory: kbui
KBSubcategory: UsrDde

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: November 2, 1995
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.