ConnectToDDEServer
int ConnectToDDEServer (unsigned int *conversationHandle, char serverName[], char topicName[], ddeFuncPtr callbackFunction, void *callbackData);
Purpose
Establishes a connection, or conversation, between your program and a named server on a topic name you specify. Your program becomes a DDE client. Thereafter, all messages from the server are routed through the specified client callback function.
ConnectToDDEServer returns zero for success or a negative error code for failure.
Parameters
| Input | ||||||
| Name | Type | Description | ||||
| serverName | char [] | Name of the server application. The name must be a string of length from 1 to 255. serverName is case insensitive. |
||||
| topicName | char [] | Specifies the type of conversation to be established between the client and the server. Each server application defines its own set of valid topic names. Refer to the server application documentation for information about valid topic names. A client and a server can have multiple connections as long as each connection has a different topic name. The name must be a string of length from 1 to 255. topicName is case insensitive. |
||||
| callbackFunction | ddeFuncPtr | The name of the callback function that processes messages for the client. A NULL pointer is not allowed. The callback function must have the following form: int (*ddeFuncPtr) (unsigned handle, char *topicName, char *itemName, int xType, int dataFmt, int dataSize, void *dataPtr, void *callbackData); handle contains a value that is unique to each client–server connection. callbackData contains the value passed as the callbackData parameter in the call to ConnectToDDEServer. In the case of a DDE_DISCONNECT message, the value is undefined.xType contains the DDE message. clientCallbackFunction can receive only two messages: DDE_DISCONNECT and DDE_DATAREADY. The other parameters to the function may or may not be used depending on the message. The following help describes each message and the data that accompanies the message: DDE_DISCONNECT—Received when a server requests the termination of a connection or when Microsoft Windows terminates the connection because of an internal error. The value of the callbackData parameter is undefined. DDE_DATAREADY—Received when you have already set up a hot or warm link by calling SetUpDDEHotLink or SetUpDDEWarmLink and the server notifies you that new data is available. If the server program uses the LabWindows/CVI DDE Support Library, it notifies you by calling AdviseDDEDataReady or BroadcastDDEDataReady. The callback receives the data in dataPtr. topicName, itemName, dataFmt, dataSize, and dataPtr contain significant data. The server to which you are connecting assigns its own meaning to topicName. itemName can specify an object to which the data refers. For example, in Excel, the item name specifies a cell. dataFmt is one of the Windows–defined data types, for example, CF_TEXT. dataSize specifies the number of bytes in the data dataPtr points to.
|
||||
| callbackData | void * | A pointer-width value the DDE Support Library passes to the callback function each time the DDE Support Library invokes the callback for the same client. You must define the meaning of the callback data. For example, you can use the callback data as a pointer to a data object that you need to access in the callback function. In this way, you do not need to declare the data object as a global variable. If you do not want to use the callback data, you can pass zero.
|
||||
| Output | ||||||
| Name | Type | Description | ||||
| conversationHandle | unsigned int | Returns a conversation handle that uniquely represents a connection between a server and a client. | ||||
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