Because DDE uses global memory to pass data from one application to another, the DDEML provides a set of functions that DDE applications can use to create and manage global memory objects.
All transactions that involve the exchange of data require the application supplying the data to create a local buffer containing the data and then to call the DdeCreateDataHandle function. This function allocates a global memory object, copies the data from the buffer to the memory object, and returns a data handle of the application. A data handle is a doubleword value that the DDEML uses to provide access to data in the global memory object. To share the data in a global memory object, an application passes the data handle to the DDEML, and the DDEML passes the handle to the DDE callback function of the application that is receiving the data transaction.
The following example shows how to create a global memory object and obtain a handle of the object. During the XTYP_ADVREQ transaction, the callback function converts the current time to an ASCII string, copies the string to a local buffer, then creates a global memory object that contains the string. The callback function returns the handle of the global memory object to the DDEML, which passes the handle to the client application.
typedef struct { /* tm */
int hour;
int minute;
int second;
} TIME;
TIME tmTime;
HSZ hszTime;
HSZ hszNow;
HDDEDATA EXPENTRY DdeProc(wType, wFmt, hConv, hsz1, hsz2,
hData, dwData1, dwData2)
WORD wType;
WORD wFmt;
HCONV hConv;
HSZ hsz1;
HSZ hsz2;
HDDEDATA hData;
DWORD dwData1;
DWORD dwData2;
{
char szBuf[32];
switch (wType) {
case XTYP_ADVREQ:
if ((hsz1 == hszTime && hsz2 == hszNow)
&& (wFmt == CF_TEXT)) {
/* Copy formatted time string to buffer. */
itoa(tmTime.hour, szBuf, 10);
strcat(szBuf, ":");
if (tmTime.minute < 10)
strcat(szBuf, "0");
itoa(tmTime.minute, &szBuf[strlen(szBuf)], 10);
strcat(szBuf, ":");
if (tmTime.second < 10)
strcat(szBuf, "0");
itoa(tmTime.second, &szBuf[strlen(szBuf)], 10);
szBuf[strlen(szBuf)] = '\0';
/* Create global object, and return data handle. */
return (DdeCreateDataHandle(
idInst, /* instance identifier */
(LPBYTE) szBuf, /* source buffer */
strlen(szBuf) + 1, /* size of global object */
0L, /* offset from beginning */
hszNow, /* item-name string */
CF_TEXT, /* clipboard format */
0)); /* no creation flags */
} else
return (HDDEDATA) NULL;
.
. /* Process other transaction types. */
.
}
}The receiving application obtains a pointer to the global memory object by pass-ing the data handle to the DdeAccessData function. The pointer returned by DdeAccessData provides read-only access. The application should use the pointer to review the data and then call the DdeUnaccessData function to invalidate the pointer. The application can copy the data to a local buffer by using the DdeGetData function.
The following example obtains a pointer to the global memory object identified by the hData parameter, copies the contents to a local buffer, and then invalidates the pointer:
HDDEDATA hData;
LPBYTE lpszAdviseData;
DWORD cbDataLen;
DWORD i;
char szData[32];
case XTYP_ADVDATA:
lpszAdviseData = DdeAccessData(hData, &cbDataLen);
for (i = 0; i < cbDataLen; i++)
szData[i] = *lpszAdviseData++;
DdeUnaccessData(hData);
return (HDDEDATA) TRUE;Usually, when an application that created a data handle passes that handle to
the DDEML, the handle becomes invalid in the creating application. This is fine
if the application needs to share data with just a single application. If an application needs to share the same data with multiple applications, however, the creating application should specify the HDATA_APPOWNED flag in DdeCreateDataHandle. Doing so gives ownership of the memory object to the creating application and prevents the DDEML from invalidating the data handle. When the creating application finishes using a memory object it owns, it should free the
object by calling the DdeFreeDataHandle function.
If an application has not yet passed the handle of a global memory object to the DDEML, the application can add data to the object or overwrite data in the object by using the DdeAddData function. Typically, an application uses DdeAddData to fill an uninitialized global memory object. After an application passes a data handle to the DDEML, the global memory object identified by the handle cannot be changed; it can only be freed.
The DDEML data-management functions can handle huge memory objects. A DDEML application should check the size of a global memory object and allocate a huge buffer of the appropriate size before copying the object.