To free a global memory object that the application allocated by calling the DdeCreateDataHandle function if the object's data handle was never passed by the application to another Dynamic Data Exchange Management Library (DDEML) function| #include <ddeml.h> |
| BOOL DdeFreeDataHandle(hData) | |||||
| HDDEDATA hData; | /* handle of global memory object | */ | |||
The DdeFreeDataHandle function frees a global memory object and deletes the data handle associated with the object.
hData
Identifies the global memory object to be freed. This handle must have been created by a previous call to the DdeCreateDataHandle function or returned by the DdeClientTransaction function.
The return value is nonzero if the function is successful. Otherwise, it is zero.
Use the DdeGetLastError function to retrieve the error value, which may be one of the following:
DMLERR_INVALIDPARAMETER DMLERR_NO_ERROR
An application must call DdeFreeDataHandle under the following circumstances:
To free a global memory object that the application allocated by calling the DdeCreateDataHandle function if the object's data handle was never passed by the application to another Dynamic Data Exchange Management Library (DDEML) function
To free a global memory object that the application allocated by specifying the HDATA_APPOWNED flag in a call to the DdeCreateDataHandle function
To free a global memory object whose handle the application received from the DdeClientTransaction function
The system automatically frees an unowned object when its handle is returned by a dynamic data exchange (DDE) callback function or used as a parameter in a DDEML function.
The following example creates a global memory object containing help information, then frees the object after passing the object's handle to the client application:
DWORD idInst;
HSZ hszItem;
HDDEDATA hDataHelp;
char szDdeHelp[] = "DDEML test server help:\r\n"\
"\tThe 'Server' (service) and 'Test' (topic) names may change.\r\n"\
"Items supported under the 'Test' topic are:\r\n"\
"\tCount:\tThis value increments on each data change.\r\n"\
"\tRand:\tThis value is changed after each data change. \r\n"\
"\t\tIn Runaway mode, the above items change after a request.\r\n"\
"\tHuge:\tThis is randomly generated text data >64k that the\r\n"\
"\t\ttest client can verify. It is recalculated on each\r\n"\
"\t\trequest. This also verifies huge data poked or executed\r\n"\
"\t\tfrom the test client.\r\n"\
"\tHelp:\tThis help information. This data is APPOWNED.\r\n";
/* Create global memory object containing help information. */
if (!hDataHelp) {
hDataHelp = DdeCreateDataHandle(idInst, szDdeHelp,
strlen(szDdeHelp) + 1, 0, hszItem, CF_TEXT, HDATA_APPOWNED);
}
.
. /* Pass help information to client application. */
.
/* Free the global memory object. */
if (hDataHelp)
DdeFreeDataHandle(hDataHelp);