Events in the Windows RSS Platform
Events in the Windows RSS Platform
The Windows RSS Platform includes a rich eventing subsystem that developers can use to listen for and respond to feed and folder events. This topic provides design and implementation details of the Windows RSS Platform. Although the emphasis is on the early-bound interfaces (IXFeed*), the event methods apply equally to the Component Object Model (COM) automation interfaces (IFeed*).
This topic contains the following sections:
- Folder and Feed Events
- Folder Events
- Feed Events
- Registering for Events
- Scope and Mask
Folder and Feed Events
The folder and feed events are detailed below.
An application need not implement all events (event sink methods); however, it must return E_NOTIMPL from each method that is not implemented. If an application returns anything but S_OK or E_NOTIMPL, the eventing system will raise the Error event to report the problem. When this happens, the application must assume that some events have not been raised, and should recover by rereading the feed subscription list as if running for the first time. The Error event can always be raised independent of any specified mask .
Folder Events
The table below lists the events that apply to both IXFeedFolderEvents and IFeedFolderEvents:
| Event | Description | Mask |
|---|---|---|
| FolderAdded(path) | A subfolder was added. | FEM_FOLDEREVENTS |
| FolderDeleted(path) | A subfolder was deleted. | FEM_FOLDEREVENTS |
| FolderRenamed(new,old) | A subfolder was renamed. | FEM_FOLDEREVENTS |
| FolderMovedFrom(new,old) | A subfolder was moved from this folder to another folder. | FEM_FOLDEREVENTS |
| FolderMovedTo(new,old) | A subfolder was moved into this folder. | FEM_FOLDEREVENTS |
| FolderItemCountChanged(path,type,count) | The aggregated total of items or unread items changed. | FEM_FOLDEREVENTS |
| FeedAdded(path) | A feed was added. | FEM_FEEDEVENTS |
| FeedDeleted(path) | A feed was deleted. | FEM_FEEDEVENTS |
| FeedRenamed(new,old) | A feed was renamed. | FEM_FEEDEVENTS |
| FeedUrlChanged(path) | The URL of a feed changed. | FEM_FEEDEVENTS |
| FeedMovedFrom(new,old) | A feed was moved from this folder. | FEM_FEEDEVENTS |
| FeedMovedTo(new,old) | A feed was moved to this folder. | FEM_FEEDEVENTS |
| FeedDownloading(path) | A feed started downloading. | FEM_FEEDEVENTS |
| FeedDownloadCompleted(path,error) | A feed completed downloading (success or error). | FEM_FEEDEVENTS |
| FeedItemCountChanged(path,type,count) | The number of items or unread items in a feed changed. | FEM_FEEDEVENTS |
| Error | An error occurred in the eventing subsystem. | N/A |
Feed Events
The following events apply to both IXFeedEvents and IFeedEvents.
| Event | Description | Mask |
|---|---|---|
| FeedDeleted(path) | The feed was deleted. | FEM_FEEDEVENTS |
| FeedRenamed(new,old) | The feed was renamed. | FEM_FEEDEVENTS |
| FeedUrlChanged(path) | The URL of the feed changed. | FEM_FEEDEVENTS |
| FeedMoved(new,old) | The feed was moved. | FEM_FEEDEVENTS |
| FeedDownloading(path) | The feed started downloading. | FEM_FEEDEVENTS |
| FeedDownloadCompleted(path,error) | The feed completed downloading (success or error). | FEM_FEEDEVENTS |
| FeedItemCountChanged(path,type,count) | The number of items or unread items in the feed changed. | FEM_FEEDEVENTS |
| Error | An error occurred in the eventing subsystem. | N/A |
Enclosures
The Windows RSS Platform does not raise events when enclosures are downloaded. The DownloadStatus property of the FeedEnclosure object indicates whether the download is in progress, failed, or completed.
Because LocalPath is set when the item is created in the Common Feed List, the property may be used to poll the file system until the file arrives. The Background Intelligent Transfer Service (BITS) downloads the enclosure to a temporary location before copying it to the location specified in LocalPath upon completion.
Registering for Events
Applications can register for events on folders and feeds. The event sink interfaces are IXFeedFolderEvents (or IFeedFolderEvents) and IXFeedEvents (or IFeedEvents). The application must implement these interfaces.
- IXFeedFolderEvents defines event methods—such as add, delete, rename, and move—for folders and subfolders,as well as event methods for feeds that belong to the folders and subfolders.
- IXFeedEvents contains only the event methods for a particular feed.
To register for events, an application calls the IXFeedFolder.GetWatcher method on a folder or feed, specifying the scope and mask. The interface returned by GetWatcher is an IConnectionPointContainer which is the standard COM interface used to register for events. In short, an application uses the IConnectionPointContainer to register its implementation of the event sink interface (IConnectionPoint). The eventing subsystem will then call back on the connection point. For more information, see Architecture of Connectable Objects.
The next section describes how to limit which events are raised.
Scope and Mask
Only event sink methods that fall within the specified scope will be called. When registering for events on a folder, the application can specify a value from the FEEDS_EVENTS_SCOPE enumeration that indicates which of the events will be fired. It is possible to raise events for a single folder and its feeds, or for the entire Common Feed List hierarchy recursively.
| Value | Description |
|---|---|
| FES_SELF_ONLY | Raise events for this folder and its feeds. |
| FES_SELF_AND_CHILDREN_ONLY | Raise events for this folder and its feeds, and for its direct subfolders and their feeds. |
| FES_ALL | Raise events for this folder and its feeds, and all subfolders recursively and their feeds. |
To limit which events are raised, applications can specify the FEEDS_EVENTS_MASK. This mask determines which events will be raised by the Windows RSS Platform.
| Value | Description |
|---|---|
| FEM_FOLDEREVENTS | Raise folder events only (added, deleted, renamed, moved). |
| FEM_FEEDEVENTS | Raise feed events only (added, deleted, renamed, moved). |
The following conceptual example, written in C++, demonstrates how to subscribe to the folder events for the entire Common Feed List hierarchy.
Note To receive the events for a single feed only, use the IConnectionPointContainer returned by IXFeed.GetWatcher, and register your IXFeedEvents interface instead of the IXFeedFolderEvents interface, as shown in the example.
IXFeedsManager* pfm;
HRESULT hr = CoCreateInstance(CLSID_XFeedsManager,
NULL, CLSCTX_INPROC_SERVER,
IID_PPV_ARGS(&pfm));
if (SUCCEEDED(hr))
{
// Get the root folder
IXFeedFolder* pff;
hr = pfm->RootFolder(IID_PPV_ARGS(&pff));
if (SUCCEEDED(hr))
{
// Get the ConnectionPointContainer
IConnectionPointContainer* pcpc;
hr = pff->GetWatcher(FES_ALL,
FEM_FOLDEREVENTS | FEM_FEEDEVENTS,
IID_PPV_ARGS(&pcpc));
if (SUCCEEDED(hr))
{
// Get the ConnectionPoint
IConnectionPoint* pcp;
hr = pcpc->FindConnectionPoint(
__uuidof(IXFeedFolderEvents), &pcp);
if (SUCCEEDED(hr))
{
// Get COM class that implements the event callbacks
IXFeedFolderEvents* pffe;
pffe = static_cast<IXFeedFolderEvents*>(this);
// Register the callback event sink implementation
DWORD dwAdviseCookie = 0;
hr = pcp->Advise(pffe, &dwAdviseCookie);
// Release interfaces
pcp->Release();
}
pcpc->Release();
}
pff->Release();
}
pfm->Release();
}
For users of C#, the process of subscribing to the event sink is greatly simplified. The following example subscribes to the FeedItemCountChanged event with two lines of code: one to retrieve the event sink and the other to register the event handler.
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
// Declaration of FeedList objects
FeedsManager fm = new FeedsManager();
IFeedFolder rootFolder = (IFeedFolder)fm.RootFolder;
IFeedFolderEvents_Event fw;
fw = (IFeedFolderEvents_Event)rootFolder.GetWatcher(
FEEDS_EVENTS_SCOPE.FES_ALL,
FEEDS_EVENTS_MASK.FEM_FEEDEVENTS);
fw.FeedItemCountChanged += new
IFeedFolderEvents_FeedItemCountChangedEventHandler(fw_FeedItemCountChanged);
// Enumerate the feed list
DisplayFeeds();
}
void fw_FeedItemCountChanged(string path, int itemCountType, int count)
{
MessageBox.Show("Hmmm... Looks like a Refresh is needed...");
// Refresh the feed list
DisplayFeeds();
}
...