ID Number: Q83912
3.10
WINDOWS
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.
Additional reference words: 3.10