AdviseDDEDataReady
int AdviseDDEDataReady (unsigned int conversationHandle, char itemName[], unsigned int dataFormat, void *dataPointer, size_t dataSize, unsigned int timeOut);
Purpose
Allows your program, acting as a DDE server, to send data to a client that has set up a hot or warm link. Call AdviseDDEDataReady in your server program only when the value of a data item changes and a warm or hot link has been established for the data item.
When a client sets up a hot or warm link, your server callback function receives a DDE_ADVISELOOP message for a particular data object that corresponds to itemName. When the hot or warm link is terminated, your server callback function receives a DDE_ADVISESTOP message for the data object.
During the period when the hot or warm link is in effect, your server program is responsible for notifying the client whenever the value of the data object changes. When the data object value changes, you can call AdviseDDEDataReady or BroadcastDDEDataReady.
AdviseDDEDataReady differs from BroadcastDDEDataReady in that you specify a particular conversation with a client. AdviseDDEDataReady sends the data only to the client you specify with conversationHandle, even if other clients have hot or warm links to the same item. AdviseDDEDataReady sends the data without invoking your server callback function. However, if there are other clients with warm links to the same item, AdviseDDEDataReady notifies them all that new data is available. If the clients request the new data, the DDE_REQUESTDATA message invokes your server callback function. If you do not want to send the data to those other clients, you must write your server callback function so that it does not call ServerDDEWrite in this case.
If you pass NULL (0) as dataPointer and 0 as dataSize, AdviseDDEDataReady sends no data to the client you specify with conversationHandle. Instead, AdviseDDEDataReady notifies all clients with warm links to the item. If the clients request the new data, the DDE_REQUESTDATA message invokes your server callback function, and you can use ServerDDEWrite to send the data in response.
If successful, AdviseDDEDataReady returns the number of bytes sent. Otherwise, AdviseDDEDataReady returns a negative error code.
 |
Note Your program should not call AdviseDDEDataReady in a tight loop because the iterations compete with user interface events for the CPU time. You should use AdviseDDEDataReady sparingly and only when the value of the hot– or warm–linked data object changes. In cases when the server returns large data objects, your program should call AdviseDDEDataReady only when the user interface is not busy. |
Parameters
| Input | ||
| Name | Type | Description |
| conversationHandle | unsigned int | The conversation handle that uniquely represents the connection between the server and the client. |
| itemName | char [] | The name that uniquely identifies the object to which the data refers; for example, an Excel cell name. Each server defines its own set of valid item names. The name must be a string of length from 1 to 255. itemName is case insensitive. |
| dataFormat | unsigned int | One of the data formats Microsoft Windows recognizes. Windows supports the following valid data formats: CF_TEXT CF_BITMAP CF_METAFILEPICT CF_SYLK CF_DIF CF_TIFF CF_OEMTEXT CF_DIB CF_PALETTE CF_PENDATA CF_RIFF CF_WAVE CF_OWNERDISPLAY CF_DSPTEXT CF_DSPBITMAP CF_DSPMETAFILEPICT Refer to www.msdn.com for more information about DDE programming and the meaning of each data format type. |
| dataPointer | void * | The pointer to the data to be written. NULL is allowed but should be used only if the link is a warm link. If NULL is passed, your server callback receives a DDE_REQUESTDATA message when the client asks for the data. You must call ServerDDEWrite to send the data. |
| dataSize | size_t | The number of bytes in the data to be written. An error is returned if you pass a value greater than INT_MAX. If dataPointer is NULL, then dataSize must be zero. |
| timeOut | unsigned int | The number of milliseconds to wait for a DDE read or write operation to complete. If a value of zero is passed, then a default timeout of 5000 milliseconds is used. |
Return Value
| Name | Type | Description |
| status | int | Return value indicating whether the function was successful. A negative number represents the error code. For functions that read or write data (ClientDDERead, ClientDDEWrite, ServerDDEWrite, AdviseDDEDataReady, BroadcastDDEDataReady), if the function was successful, the return value is the number of bytes transferred. For other DDE Support Library functions, zero represents successful execution. The enumerated type that specifies the absolute values of the error codes is declared in ddesupp.h. For instance, if an invalid parameter is passed, –kDDE_InvalidParameter is returned. Currently, a maximum of 255 concurrent conversations are allowed at any one time. If you exceed this limit, –kDDE_TooManyConversations will be returned. Error codes from –16 to –33 are native DDEML errors, which correspond to Windows DDE error codes starting from 0x4000. |
Additional Information
Library: DDE Support Library
Include file: ddesupp.h
LabWindows/CVI compatibility: LabWindows/CVI 3.0 and later