Freeing Memory for Transactions in a DDEML Client App (83912)

SUMMARY

A Dynamic Data Exchange Management Library (DDEML) client application can request data from a server both synchronously and asynchronously by calling the DdeClientTransaction function.

To make a synchronous request, the client application specifies XTYP_REQUEST as the value for the uType parameter to DdeClientTransaction, and any reasonable value for the uTimeout parameter.

To make an asynchronous request, the client application specifies XTYP_REQUEST as the value for the uType parameter to DdeClientTransaction, and TIMEOUT_ASYNC as the value for the uTimeout parameter.

The client can also establish an advise loop with a server application by specifying XTYP_ADVSTART as the value for the uType parameter. In an advise loop, the client application's callback function receives an XTYP_ADVDATA transaction each time the specified data item changes in the server application. (NOTE: This article discusses only hot advise loops in which changed data is communicated to the application. No data is transferred for a warm advise loop, only a notification that the data changed.)

The client application must free the data handle it receives from a synchronous transaction; however, the client application should not free the data handle it receives from an asynchronous transaction or from an advise loop.

MORE INFORMATION

If the client application initiates a synchronous transaction, the DdeClientTransaction function returns a handle to the requested data. If the client application initiates an asynchronous transaction, the DdeClientTransaction function returns either TRUE or FALSE. When the data becomes available, the DDEML sends the client application an XTYP_XACT_COMPLETE notification accompanied by a handle to the requested data. In an active advise loop, the DDEML sends the client application an XTYP_ADVDATA notification accompanied by a handle to the updated data.

In the synchronous case, the client application must call DdeFreeDataHandle before it terminates to free a data handle (and the associated memory) that it received as the return value from DdeClientTransaction. If the DDEML server specified HDATA_APPOWNED when it created the data handle, then the data is invalidated when the client calls DdeFreeDataHandle; the server must call DdeFreeDataHandle before terminating to free the associated memory.

In the asynchronous case, the DDEML sends the client application's callback function an XTYP_XACT_COMPLETE notification when the server has completed the transaction. A handle to the requested data accompanies the notification as the hData parameter to the callback function. This handle is valid until control returns from the client application's callback function. Once the client application's callback function returns control, the DDEML may free the data handle and the client application must not assume that the data handle received in the callback function remains valid. This fact has two implications, as follows:

The client application cannot call DdeFreeDataHandle on the data handle it receives with an XTYP_XACT_COMPLETE transaction. If the client invalidates the data handle by freeing it in the client's callback function, and the DDEML later attempts to free the handle, a Fatal Exit will result.
The client application must make a local copy of the data it receives with the XTYP_XACT_COMPLETE transaction to use that data after the callback function returns.

In an advise loop, the client application should not free the data handle that it receives as the hData parameter to the callback function. The DDEML frees the data handle when the client application returns from its callback function. If the client calls DdeFreeDataHandle on the data handle, the DDEML will cause a Fatal Exit when it attempts to free the same data handle.

These rules apply to all data handles, whether or not the server application specified the HDATA_APPOWNED flag when it created the handle.