DdeClientTransaction

HDDEDATA DdeClientTransaction(lpbData, cbData, hConv, hszItem, uFmt, uType, uTimeout, lpdwResult)
LPBYTE lpbData;	/* address of data to pass to server	*/
DWORD cbData;	/* length of data	*/
HCONV hConv;	/* handle of conversation	*/
HSZ hszItem;	/* handle of item-name string	*/
UINT uFmt;	/* clipboard data format	*/
UINT uType;	/* transaction type	*/
DWORD uTimeout;	/* timeout duration	*/
LPDWORD lpdwResult;	/* points to transaction result	*/

The DdeClientTransaction function begins a data transaction between a client and a server. Only a dynamic data exchange (DDE) client application can call this function, and only after establishing a conversation with the server.

Parameters

lpbData

Points to the beginning of the data that the client needs to pass to the server.

Optionally, an application can specify the data handle (HDDEDATA) to pass to the server, in which case the cbData parameter should be set to -1. This parameter is required only if the uType parameter is XTYP_EXECUTE or XTYP_POKE. Otherwise, this parameter should be NULL.

cbData

Specifies the length, in bytes, of the data pointed to by the lpbData parameter. A value of -1 indicates that lpbData is a data handle that identifies the data being sent.

hConv

Identifies the conversation in which the transaction is to take place.

hszItem

Identifies the data item for which data is being exchanged during the transaction. This handle must have been created by a previous call to the DdeCreateStringHandle function. This parameter is ignored (and should be set to NULL) if the uType parameter is XTYP_EXECUTE.

uFmt

Specifies the standard clipboard format in which the data item is being submitted or requested. For more information about standard clipboard formats, see the Microsoft Windows Guide to Programming.

uType

Specifies the transaction type. This parameter can be one of the following values:

Value

Meaning

XTYP_ADVSTART
	Begins an advise loop. Any number of distinct advise loops can exist within a conversation. An application can alter the advise loop type by combining the XTYP_ADVSTART transaction type with one or more of the following flags:

Value

Meaning

XTYPF_NODATA	Instructs the server to notify the client of any data changes without actually sending the data. This flag gives the client the option of ignoring the notification or requesting the changed data from the server.
XTYPF_ACKREQ	Instructs the server to wait until the client acknowledges that it received the previous data item before sending the next data item. This flag prevents a fast server from sending data faster than the client can process it.

XTYP_ADVSTOP
	Ends an advise loop.
XTYP_EXECUTE
	Begins an execute transaction.
XTYP_POKE
	Begins a poke transaction.
XTYP_REQUEST
	Begins a request transaction.

uTimeout

Specifies the maximum length of time, in milliseconds, that the client will wait for a response from the server application in a synchronous transaction. This parameter should be set to TIMEOUT_ASYNC for asynchronous transactions.

lpdwResult

Points to a variable that receives the result of the transaction. An application that does not check the result can set this value to NULL. For synchronous transactions, the low-order word of this variable will contain any applicable DDE_ flags resulting from the transaction. This provides support for applications dependent on DDE_APPSTATUS bits. (It is recommended that applications no longer use these bits because they may not be supported in future versions of the DDE Management Library.) For asynchronous transactions, this variable is filled with a unique transaction identifier for use with the DdeAbandonTransaction function and the XTYP_XACT_COMPLETE transaction.

Return Value

The return value is a data handle that identifies the data for successful synchronous transactions in which the client expects data from the server. The return value is TRUE for successful asynchronous transactions and for synchronous transactions in which the client does not expect data. The return value is FALSE for all unsuccessful transactions.

Errors

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

DMLERR_ADVACKTIMEOUT
DMLERR_BUSY
DMLERR_DATAACKTIMEOUT
DMLERR_DLL_NOT_INITIALIZED
DMLERR_EXECACKTIMEOUT
DMLERR_INVALIDPARAMETER
DMLERR_MEMORY_ERROR
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR
DMLERR_NOTPROCESSED
DMLERR_POKEACKTIMEOUT
DMLERR_POSTMSG_FAILED
DMLERR_REENTRANCY
DMLERR_SERVER_DIED
DMLERR_UNADVACKTIMEOUT

Comments

When the application is finished using the data handle returned by the DdeClientTransaction function, the application should free the handle by calling the DdeFreeDataHandle function.

Transactions can be synchronous or asynchronous. During a synchronous transaction, the DdeClientTransaction function does not return until the transaction completes successfully or fails. Synchronous transactions cause the client to enter a modal loop while waiting for various asynchronous events. Because of this, the client application can still respond to user input while waiting on a synchronous transaction but cannot begin a second synchronous transaction because of the activity associated with the first. The DdeClientTransaction function fails if any instance of the same task has a synchronous transaction already in progress.

During an asynchronous transaction, the DdeClientTransaction function returns after the transaction is begun, passing a transaction identifier for reference. When the server's DDE callback function finishes processing an asynchronous transaction, the system sends an XTYP_XACT_COMPLETE transaction to the client. This transaction provides the client with the results of the asynchronous transaction that it initiated by calling the DdeClientTransaction function. A client application can choose to abandon an asynchronous transaction by calling the DdeAbandonTransaction function.