DdeCreateStringHandle

3.1

#include <ddeml.h>

HSZ DdeCreateStringHandle(idInst, lpszString, codepage)
DWORD idInst;	/* instance identifier, */
LPCSTR lpszString;	/* address of null-terminated string	*/
int codepage;	/* code page	*/

The DdeCreateStringHandle function creates a handle that identifies the string pointed to by the lpszString parameter. A dynamic data exchange (DDE) client or server application can pass the string handle as a parameter to other DDE Management Library functions.

Parameters

idInst

Specifies the application-instance identifier obtained by a previous call to the DdeInitialize function.

lpszString

Points to a buffer that contains the null-terminated string for which a handle is to be created. This string may be any length.

codepage

Specifies the code page used to render the string. This value should be either CP_WINANSI or the value returned by the GetKBCodePage function. A value of zero implies CP_WINANSI.

Return Value

The return value is a string handle if the function is successful. Otherwise, it is NULL.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR
DMLERR_SYS_ERROR

Comments

Two identical strings always correspond to the same string handle. String handles are unique across all tasks that use the DDEML. That is, when an application creates a handle for a string and another application creates a handle for an identical string, the string handles returned to both applications are identical—regardless of case.

The value of a string handle is not related to the case of the string it identifies.

When an application has either created a string handle or received one in the callback function and has used the DdeKeepStringHandle function to keep it, the application must free that string handle when it is no longer needed.

An instance-specific string handle is not mappable from string handle to string to string handle again. This is shown in the following example, in which 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:

DWORD idInst;
DWORD cb;
HSZ hszInst, hszNew;
PSZ pszInst;

DdeQueryString(idInst, hszInst, pszInst, cb, CP_WINANSI);
hszNew = DdeCreateStringHandle(idInst, pszInst, CP_WINANSI);
/* hszNew != hszInst ! */

Example

The following example creates a service-name string handle and a topic-name string handle and then attempts to establish a conversation with a server that supports the service name and topic name. If the attempt fails, the example obtains an error value identifying the reason for the failure.

DWORD idInst = 0L;
HSZ hszClock;
HSZ hszTime;
HCONV hconv;
UINT uError;

hszClock = DdeCreateStringHandle(idInst, "Clock", CP_WINANSI);
hszTime = DdeCreateStringHandle(idInst, "Time", CP_WINANSI);

if ((hconv = DdeConnect(
    idInst,                  /* instance identifier                */
    hszClock,                /* server's service name              */
    hszTime,                 /* topic name                         */
    NULL)) == NULL) {        /* use default CONVCONTEXT            */

    uError = DdeGetLastError(idInst);
}