Dynamic Data Exchange Dynamic Link Library Horizon Technologies Inc. Introduction: The Dynamic Data Exchange (DDE) Dynamic Link Library (DLL) offers Microsoft Windows programmers a tool that reduces the effort required to add DDE support to their applications. DDE is a protocol for sending data and commands between two applications in real time. This link makes it possible to build an integrated system from specialized component programs. For example, a DDE session allows the transfer of a pie chart between a spreadsheet and a word processor. The spreadsheet advises the word processor whenever the pie chart changes. So moments after the user changes data in the spreadsheet, the pie chart in the word processor reflects the user's modifications. Then why doesn't every Windows application support the DDE protocol? Because, it is very difficult to implement. The application must deal with both the DDE protocol and the data transferred. The processing of data is application dependent and is inherent in the structure of every program. The DDE protocol, however, is the same for all applications. This lends itself to creating a set of functions, the DDE Library, that provide a simple means of implementing the DDE protocol. Overview: This overview summarizes the function calls available in the DDE Library. A general knowledge of the DDE protocol can be obtained from Microsoft documents. Chapters 8, 9 and 10 of the Microsoft Windows Software Development Kit - Windows Extensions - Version 2.0 will provide the needed background. The DDE Library tracks all DDE messages. The application does not have to respond to any DDE messages in its window procedure. The DDE Library will create special child windows to handle all of the DDE message traffic. The application only needs to interact with the functions provided. The DDE Library handles all message flow control and acknowledgements. It tracks the current state of the DDE conversation and sends messages only when permitted by the DDE protocol. The application does not have to check flags to determine whether or not to acknowledge a received message. The DDE Library handles all atom creation and deletion. It will convert a string to an atom and back again. The DDE Library will allocate, lock, unlock, and free global memory objects by the DDE protocol. The DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 1 application does not have to check flags to determine whether or not to free a memory object. Client applications use DDEInitiate and DDETerminate for session management. DDEAdvise and DDEUnadvise are used to establish and close advise circuits. DDERequest and DDEPoke are used for one time data transfers from and to the server respectively. DDEExecute is used to send a command to the server. Server applications use DDERegisterTopic to provide a service to other potential client applications. DDESendData is used to transmit data to client applications. DDEUnregisterTopic is used to remove a particular service. Each of the functions of the DDE Library are described in detail on the following pages. The information provided includes the function description, syntax, parameter list, return value, and helpful comments. These descriptions also document the format of any callback functions that may be required. An appendix is supplied that describes the different structures used. DDE Library can communicate with a variety of DDE based applications including Microsoft's Excel and Word for Windows. DDE Library also comes with three sample programs that demonstrate the use of the library. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 2 DDEInitiate Syntax: HWND DDEInitiate (hOwner, lpszApp, lpszTopic) Client applications use this function to initiate a DDE session with the first server that responds. This DDE function must be called before any of the other client DDE functions. Parameter Type/Description hOwner HWND Handle to the top level window of the application. lpszApp LPSTR Points to a character string that names the requested application. The string must be a null terminated character string. lpszTopic LPSTR Points to a character string that names the requested topic. The string must be a null terminated character string. Return Value: A handle to the initiated DDE session which is used in subsequent client DDE function calls. It is NULL if the function is unsuccessful. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 3 DDEAdvise Syntax: WORD DDEAdvise (hClient, lpszItem, lpAdvise, lpfnAdviseCallBack) Client applications use this function to request the establishment of an advise circuit for a particular data item. Whenever the server determines that the value of the data item has changed, it will notify the client by calling the lpfnAdviseCallBack function. This function returns after the server has acknowledged the advise. Parameter Type/Description hClient HWND Handle to a DDE session returned by DDEInitiate. lpszItem LPSTR Points to a character string that names the requested item. The string must be a null terminated character string. lpAdvise DDEADVISE FAR * Points to a DDEADVISE structure that specifies the particular options for this advise circuit. See Advise Structure below. lpfnAdviseCallBack DDECALLBACK Is the procedure instance of the callback function that will be invoked each time the server issues an advise. See Callback Function below. Return Value: A word in the format of the DDEACK structure. See Appendix. Advise Structure: Set fDeferUpd to TRUE to cause the server to send only a notification when the value changes. Set fAckReq to TRUE to cause the server to wait for an acknowledgement before sending another advise message. Set cfFormat to a valid clipboard format, such as CF_TEXT, identifying the format of the data requested. Comments: Setting fDeferUpd to TRUE provides a mechanism to avoid frequent data transfers if only a notification is required. Note that when setting fAckReq to TRUE the server will not receive an acknowledgement until the callback function returns. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 4 Callback Function: WORD FAR PASCAL Advise (hClient, iMessage, lpszItem, hData) Advise is a placeholder for the application-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the application's module definition file. Parameter Type/Description hClient HWND Handle to a DDE session returned by DDEInitiate. iMessage unsigned A value indicating why the callback function was invoked. See messages below. lpszItem LPSTR Points to a character string that names the item whose value is currently being advised. The string is a null terminated character string. hData HANDLE A handle to a global memory object in the form of a DDEDATA structure for DDE_DATA messages. Otherwise, it is NULL. See Data Structure below. Do not free this memory object. Messages: The messages sent to the callback function contained in iMessage are as follows: Value Description DDE_ACK First message sent when the circuit opens successfully. hData is NULL. DDE_DATA One message sent each time the server advises the client of the new data. DDE_TERMINATE Sent when the circuit is closing or if the circuit could not be established. Return Value: The return value, defined as a WORD, is unused. Data Structure: If the fDeferUpd flag in the DDEADVISE structure passed to the DDEAdvise function was TRUE then fNoData will be TRUE and Value will not contain any data. cfFormat is the format set in the DDEADVISE structure passed to the DDEAdvise function. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 5 DDEUnadvise Syntax: WORD FAR PASCAL DDEUnadvise (hClient, lpszItem) Client applications use this function to request the termination of an advise circuit for a particular data item previously established by a call to the DDEAdvise function. This function returns after the server has acknowledged the unadvise. Parameter Type/Description hClient HWND Handle to a DDE session returned by DDEInitiate. lpszItem LPSTR Points to a character string that names the requested item. The string must be a null terminated character string. Return Value: A word in the format of the DDEACK structure. See Appendix. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 6 DDERequest Syntax: WORD DDERequest (hClient, lpszItem, cfFormat, lpfnRequestCallBack) Client applications use this function to request a particular data item. The server will respond to the client by calling the lpfnRequestCallBack function. This function returns after the server has acknowledged the request. Parameter Type/Description hClient HWND Handle to a DDE session returned by DDEInitiate. lpszItem LPSTR Points to a character string that names the requested item. The string must be a null terminated character string. cfFormat WORD should be set to a valid clipboard format, such as CF_TEXT, identifying the format of the data requested. lpfnRequestCallBack DDECALLBACK Is the procedure instance of the callback function that is invoked when the server responds with the data. See Callback Function below. Return Value: A word in the format of the DDEACK structure. See Appendix. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 7 Callback Function: WORD FAR PASCAL Request (hClient, iMessage, lpszItem, hData) Request is a placeholder for the application-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the application's module definition file. Parameter Type/Description hClient HWND Handle to a DDE session returned by DDEInitiate. iMessage unsigned A value indicating why the callback function was invoked. See messages below. lpszItem LPSTR Points to a character string that names the item whose value is currently being requested. The string is a null terminated character string. hData HANDLE A handle to a global memory object in the form of a DDEDATA structure for DDE_DATA messages. Otherwise, it is NULL. See Data Structure below. Do not free this memory object. Messages: The messages sent to the callback function contained in iMessage are as follows: Value Description DDE_DATA Sent if the server fulfilled the request and is providing the data. DDE_TERMINATE Sent if the server could not fulfill the request and hence no data is available. hData is NULL. Return Value: The return value, defined as a WORD, is unused. Data Structure: cfFormat is the format requested in the DDERequest function. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 8 DDEPoke Syntax: WORD FAR PASCAL DDEPoke (hClient, lpszItem, hPoke) Client applications use this function to send, unsolicited, a particular data item to the server. This function returns after the server has acknowledged the poke. Parameter Type/Description hClient HWND Handle to a DDE session returned by DDEInitiate. lpszItem LPSTR Points to a character string that names the item whose data is being sent. The string must be a null terminated character string. hPoke HANDLE A handle to a global memory object in the form of a DDEPOKE structure. See Poke Structure below. Return Value: A word in the format of the DDEACK structure. See Appendix. Poke Structure: Set fRelease to TRUE to cause the server to free the memory object. Otherwise, it is the client application's reponsibility to free the memory object. Set cfFormat to a valid clipboard format, such as CF_TEXT, identifying the format of the data being sent. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 9 DDEExecute Syntax: WORD FAR PASCAL DDEExecute (hClient, hCommand) Client applications use this function to send, unsolicited, a particular command to the server. This function returns after the server has acknowledged the command. Parameter Type/Description hClient HWND Handle to a DDE session returned by DDEInitiate. hCommand HANDLE A handle to a global memory object which contains a null terminated ASCII string of commands that the server should execute. Example: [open ("foo.xlm")] [run ("r1c1")]. This memory object will be freed by the DDE Library. Return Value: A word in the format of the DDEACK structure. See Appendix. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 10 DDETerminate Syntax: WORD FAR PASCAL DDETerminate (hClient) Client applications use this function to terminate a session previously established DDEInitiate. This function invalidates the hClient handle which can no longer be used. This function returns after the server has acknowledged the command. Parameter Type/Description hClient HWND Handle to a DDE session returned by DDEInitiate. Return Value: A word in the format of the DDEACK structure. See Appendix. Commands: Advise circuits established with DDEAdvise do not need to be explicitly closed with a call to DDEUnadvise before terminating a session. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 11 DDERegisterTopic Syntax: HWND DDERegisterTopic (hOwner, lpszApp, lpszTopic, lpfnTopicCallBack) Server applications use this function to register its services for a particular topic. Any potential client application can establish a session with this server by issuing a DDEInitiate for this particular application and topic. Parameter Type/Description hOwner HWND Handle to the top level window of the application. lpszApp LPSTR Points to a character string that names the name of the application providing the service. The string must be a null terminated character string. lpszTopic LPSTR Points to a character string that names the name of the topic that the application is servicing. The string must be a null terminated character string. lpfnTopicCallBackDDECALLBACK Is the procedure instance of the callback function that is invoked each time a client requests a service. See Callback Function below. Return Value: A handle to the created DDE topic server which is used in subsequent server DDE function calls. It is NULL if the function is unsuccessful. Comments: A server may register more than one topic by repeatedly calling DDERegisterTopic. Each invocation should use the same lpszApp string. Since the callback function will not provide the handle returned by this function, the application should not use the same callback function for more than one topic. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 12 Callback Function: WORD FAR PASCAL Topic (hSession, iMessage, lpszItem, hData) Topic is a placeholder for the application-supplied function name. The actual name must be exported by including it in an EXPORTS statement in the application's module definition file. Parameter Type/Description hSession HWND Handle that identifies a particular DDE session with a client. This is not the return value from DDERegisterTopic. iMessage unsigned A value indicating why the callback function was invoked. See messages below. lpszItem LPSTR Points to a character string that names the item of interest. This may be NULL for some messages. The string is a null terminated character string. hData HANDLE A handle to a global memory object in a form dependant on the message. Do not free this memory object. Return Value: The return value is defined as a WORD. For messages that require a return value, fill this word using the format of the DDEACK structure. The DDEACK structure is defined in the Appendix. Each message value documented below defines whether or not it requires a return value. Messages: The messages sent to the callback function contained in iMessage are as follows: Value Description DDE_INITIATE Message sent when a new client establishes a session. lpszItem and hData are NULL. The return value is not used. DDE_TERMINATE Message sent when a session with a client is being terminated. lpszItem and hData are NULL. The return value is not used. DDE_POKE Message sent when the client is offering data for a particular item. lpszItem contains the name of the item. hData is in the form of a DDEPOKE structure. Make sure to set DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 13 fAck and fBusy in the return value since it is used. DDE_REQUEST Message sent when the client is requesting a one time data transfer for a particular item. lpszItem contains the name of the item. hData is in the form of a DDEADVISE structure. Check cfFormat. No need to check fRelease or fAckReq. Do not free this memory object. Make sure to set fAck and fBusy in the return value since it is used. If fAck is TRUE the server is required to send the data using DDESendData. DDE_EXECUTE Message sent when the client is requesting the execution of a command string. lpszItem is NULL. hData is simply a null terminated ASCII string. Make sure to set fAck and fBusy in the return value since it is used. DDE_ADVISE Message sent when the client is requesting a continuous data transfer for a particular item whenever its value changes. lpszItem contains the name of the item. hData is in the form of a DDEADVISE structure. Check fDeferUpd and cfFormat. No need to check fRelease or fAckReq. Do not free this memory object. Make sure to set fAck and fBusy in the return value since it is used. If fAck is TRUE the server should send advise data using DDESendData. DDE_UNADVISE Message sent when the client is requesting a continuous data transfer to be terminated for a particular item. lpszItem contains the name of the item. hData is NULL. Make sure to set fAck and fBusy in the return value since it is used. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 14 DDESendData Syntax: HWND DDESendData (hSession, iMessage, lpszItem, hData) Server applications use this function to send data to a client application in direct response to a request message or as a result of an advise circuit having been established. This function returns after the client has acknowledged the data message if the bAckReq field in the DDEDATA structure is TRUE. Otherwise it will return immediately after the message is sent. Parameter Type/Description hSession HWND Handle that identifies a particular DDE session with a client identified as the first parameter of the callback function registered by DDERegisterTopic. This is not the return value from DDERegisterTopic. iMessage unsigned A value indicating the reason the data is being sent to the client. Set this value to DDE_REQUEST if the data is in response to a request message, otherwise set it to DDE_ADVISE. lpszItem LPSTR Points to a character string that names the item whose data is being sent. The string must be a null terminated character string. hData HANDLE A handle to a global memory object in the form of a DDEDATA structure. See Data Structure below. Return Value: A word in the format of the DDEACK structure. See Appendix. Data Structure: If this data is sent in response to an advise message set fAckReq to the same value as the fAckReq field of the DDEADVISE structure sent previously by the client. If this data is sent in response to a request message fAckReq may be set to either TRUE or FALSE. See the appendix for more information. Set fRelease to TRUE if the client should free the memory object. Otherwise, it is the server application's responsibility to free the memory object. Set cfFormat to a valid clipboard format such as CF_TEXT. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 15 DDEUnregisterTopic Syntax: HWND DDEUnregisterTopic (hServer) Server applications use this function to unregister its services for a particular topic. This function will first terminate all currently active sessions with clients before returning Parameter Type/Description hServer HWND Handle to a DDE topic server established with DDERegisterTopic. Return Value: A word in the format of the DDEACK structure. See Appendix. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 16 Appendix The DDEACK structure: A word in the format of the DDEACK structure is returned by all of the DDE library functions except DDEInitiate and DDERegisterTopic. The fields that are packed into this word are described in the table below. Field Type/Description fAck unsigned:1 Boolean flag that is TRUE for a positive acknowledgement and FALSE for a negative (nack) acknowledgement. fBusy unsigned:1 Boolean flag that indicates the server could not process the request because it is currently busy. This field only has meaning only if fAck is FALSE. bAppReturnCode unsigned:8 Can be set to any value desired for further interprocess status communications. However, the DDE library functions also set this return code to indicated failures on their part as well. See the table below. The following table represents the values that the DDE library functions may supply in the bAppReturnCode of the DDEACK structure. Value Meaning DDE_OK Function completed ok. DDE_NACK A nack was received. DDE_BADHANDLE The session handle passed to the function is invalid. DDE_BADSTATE The current state of communications can not perform the action requested by this function. DDE_MEMORY A memory allocation error occurred during the processing of this function. DDE_BADITEM The item passed to the function is invalid. DDE_BADTOPIC The topic passed to the function is invalid. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 17 The DDEADVISE Structure: The DDEAdvise structure, sent to the server from the client, contains the following fields. Field Type/Description fAckReq unsigned:1 Boolean flag that is TRUE if the server is required to wait for an acknowledgement to be returned before sending another advise message. The fAckReq field in the DDEDATA structure sent as part of the data message to the client must be set equal to this field by the server. fDeferUpd unsigned:1 Boolean flag that indicates the server should not send data in the Value field of the DDEDATA structure when sending a data message. It is assumed that the client will send a request message to the server when it requires the actual data. cfFormat int A valid clipboard format, such as CF_TEXT, identifying the format of data requested. The DDEDATA Structure: The DDEData structure, sent to the client from the server, contains the following fields. Field Type/Description fAckReq unsigned:1 Boolean flag that is TRUE if the client is required to send an acknowledgement back to the server. fRelease unsigned:1 Boolean flag that is TRUE if the client is expected to free the global memory object. fResponse unsigned:1 Boolean flag that is TRUE if the data message is in response to a request. FALSE if the server initiated the transfer as a result of an established advise circuit. cfFormat int A valid clipboard format, such as CF_TEXT, identifying the format of data sent. Value BYTE[n] The data. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 18 The DDEPOKE Structure: The DDEPoke structure, sent to the server from the client, contains the following fields. Field Type/Description fRelease unsigned:1 Boolean flag that is TRUE if the server is expected to free the global memory object. cfFormat int A valid clipboard format, such as CF_TEXT, identifying the format of data sent. Value BYTE[n] The data. DDELIB - Copyright (C) May 17, 1990 Horizon Technologies Inc. All rights reserved. (517) 347-0800 19