XLLRTDFEED.DLL is a general-purpose RTD feed server component. It is supplied as a component of the XLL+ tool-kit (version 6.3 and above).
This RTD server routes all necessary RTD messages back to an XLL that uses it. Thus all the significant application code can be in one place - the XLL add-in.
The server must be registered as a COM module before it can be used with Excel. See Deploying a feed server add-in for details.
XllRtdFeed API
All the communication between the RTD server and an XLL is through a C++ API. To use the API, add the header file to your application code:
CopyC++#include <XllRtdFeedServerProxy.h>
XLL add-ins make calls to the RTD server via the CXllRtdFeedServerProxy class. The XLL must also provide a callback object, derived from IXllRtdFeedCallback, which will handle events raised by the RTD server.
CXllRtdFeedServerProxy class
This class has four public methods.
| Method | Description |
|---|---|
| RegisterClient | Registers this XLL as a client of the RTD server, and initializes the RTD server if necessary. |
| UnregisterClient | Unregisters this XLL as a client of the RTD server. No further call-backs will be routed to the XLL. |
| CallRtd | Makes a call to the RTD server, via Excel. If called from an add-in function, has the effect of linking the caller cell to the specified topic. The cell will automatically be recalculated whenever the topic is updated. |
| UpdateTopic | Informs the RTD server that the specified topic has been updated. Any cells depending on the topic will automatically be recalculated. This method may be called from any thread. |
IXllRtdFeedCallback interface
An XLL must create an instance of a class derived from IXllRtdFeedCallback, and pass a pointer to the instance during CXllRtdFeedServerProxy::RegisterClient(). The class must implement two virtual functions.
| Method | Description |
|---|---|
| OnGetDataState | Called whenever Excel needs to know whether a data item is available, and whether its value has changed. |
| OnTopicRemoved | Called whenever Excel is no longer interested in a particular topic. This will occur when the last cell range that refers to the topic is removed, changed or closed. |
Client usage
Normally, an XLL will interact with XllRtdFeed as follows.
- Call CXllRtdFeedServerProxy::RegisterClient() during initialization, usually during OnXllOpenEx().
- Invoke CXllRtdFeedServerProxy::CallRtd() during any add-in function that returns live data.
- Call CXllRtdFeedServerProxy::UpdateTopic() asynchronously, whenever the feed server sends an update for a topic of interest.
- Call CXllRtdFeedServerProxy::UnregisterClient() during close-down, usually during OnXllClose() .
In addition, the implementation of IXllRtdFeedCallback should handle the following callbacks.
CopyC++virtual bool OnGetDataState(LPCWSTR lpszClient, LPCWSTR lpszTopic, LPVARIANT lpvntState);
This virtual function is called whenever Excel needs to know the current value or availability of the specified topic.
- The XLL should examine its cache for the requested data.
- If the data is found, then it should set *lpvntState to a value which describes the state of the data and return true. (See State values below.)
- If the data is not found, the XLL should request it from the feed.
- If the data item will never be found, OnGetDataState() should return false.
CopyC++virtual void OnTopicRemoved(LPCWSTR lpszClient, LPCWSTR lpszTopic, long lTopicID);
This virtual function is called when Excel is no longer interested in a topic.
- The XLL should inform the feed that it is no longer interested in the topic.
- The XLL should remove the specified data from its cache.
State Values
It is not necessary to inform RTD of the actual value of the data that has changed; you merely need to pass a value that changes whenever the value itself changes. This distinction is important, because RTD cannot accept array values, only scalars, so it is not possible to pass an array value to RTD.
The state value is any associated value that changes at the same time as the data value itself. Possible state values are:
- Timestamp of new data value.
- A numeric hash of the full data value.
- For a scalar value, the data value itself.
- A sequence id which is incremented whenever the value is changed.
For most purposes, a timestamp is the simplest option. The demo add-in uses as timestamp as the state value.
