Saturday, June 24, 2006

Windows RSS Platform Events

The Microsoft Windows RSS Platform includes a rich eventing subsystem that developers can use to listen for and respond to feed and folder events.
Although the below places emphasis on the early-bound interfaces (IXFeed*), the event methods apply equally to the Component Object Model (COM) automation interfaces (IFeed*).

Registering for Events
Applications can register for events on folders and on feeds. The event sink interfaces are IXFeedFolderEvents (or IFeedFolderEvents) and IXFeedEvents (or IFeedEvents). The application must implement these interfaces.
IXFeedFolderEvents defines event methods for folders and subfolders (add, delete, rename, move, and so on) as well as event methods for feeds that belong to the folder or subfolders.
IXFeedEvents contains just 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 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 details, see Architecture of Connectable Objects.
Note that not all event sink methods will be called if they do not fall within the specified scope.

Scope and Mask
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 only, or for the entire Common Feed List hierarchy recursively.

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.

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, rather than IXFeedFolderEvents interface as shown in the example.

IXFeedsManager* pfm;
HRESULT hr = CoCreateInstance(CLSID_FeedsManager,
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(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.

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 bstrPath, int lItemCount, int lUnreadItemCount)
{
MessageBox.Show("Hmmm... Looks like a Refresh is needed...");

// Refresh the feed list
DisplayFeeds();
}

...

Feed Synchronization

The Internet Explorer 7 aggregator (the Feed Download Engine) automatically downloads the feed items from the source URL specified in the feed.
These downloads can occur on a schedule, or as requested by the user. The value of the Interval property and Ttl element of the feed determine how often the feed is downloaded; the feed is updated when the current time is equal to LastDownloadTime plus the maximum of these two values.

The methods and properties that control the download and synchronization behavior of feeds are as follows:

Background Synchronization
FeedsManager.BackgroundSync(action):Possible actions are: Enable, Disable, or RunNow.
FeedsManager.BackgroundSyncStatus:FEEDSBACKGROUNDSYNCSTATUS,
Returns the status (Disabled, Enabled) of the Feed Download Engine.
FeedsManager.DefaultInterval :Integer,Returns, in minutes, the system-defined download interval.
FeedsManager.ItemCountLimit:Integer,Returns the upper limit of items that can be kept.
Feed.DownloadEnclosuresAutomatically:Boolean,Returns true if enclosures are automatically downloaded with the feed.
Feed.Interval:Integer,Returns, in minutes, how frequently the Feed Download Engine should download this feed.
Feed.MaxItemCount:Integer,Returns the number of items to keep when downloading this feed.
Feed.SyncSetting:FEEDS_SYNC_SETTING,Specifies whether to use the local or global interval setting, or disable automatic download entirely.
Feed.Ttl:String,Returns, in minutes, how long the feed should be cached according to the XML of the feed.

Download (On Demand)
Feed.Download:Downloads the feed and merges its contents into the system feed list.
FeedEnclosure.AsyncDownload:Downloads the enclosure.
FeedEnclosure.CancelAsyncDownload:Cancels a download operation in progress.

Success Indicators
Feed.LastDownloadTime:Floating-point number,Returns the date and time of the last successful download.
FeedItem.LastDownloadTime:Floating-point number,Returns the date and time of the last successful update.
Feed.LastDownloadError:FEEDS_DOWNLOAD_ERROR,Returns the download error of the feed, if any.
Feed.DownloadStatus:FEEDS_DOWNLOAD_STATUS,Returns the status of the feed.
FeedEnclosure.LastDownloadError:FEEDS_DOWNLOAD_ERROR,Returns the download error of the enclosure, if any.
FeedEnclosure.DownloadStatus:FEEDS_DOWNLOAD_STATUS,Returns the status of the enclosure.

IFeedItem

Individual items in a feed are represented by FeedItem objects.

Depending on the type of feed, these items are aggregated as news items that are merged into the feed, or as list items that replace the contents of the previous list.
Additional RSS 2.0 item elements, such as GUID and source, are available in the XML source document of the feed.

Item Elements
FeedItem.Author:String,Optional. Returns the e-mail address of the author.
FeedItem.Comments:String,Optional. Returns the page URL of related comments.
FeedItem.Description:String,Required. Returns the item synopsis.
FeedItem.Link:String,Required. Returns the source URL of the item.
FeedItem.PubDate:String,Optional. Indicates when the item was published.
FeedItem.Title:String,Required. Returns the title of the item.

XML Source
FeedItem.Xml(include):String,Returns an XML fragment for the item.

Common Feed List Properties
FeedItem.DownloadUrl:String,Returns URL used for security zone mapping.
FeedItem.Enclosure:IFeedEnclosure,Returns the enclosure (media object) associated with the item.
FeedItem.Id:Integer,Returns an identifier (ID) assigned by the Feed Download Engine. It is unique within the feed.
FeedItem.IsRead:Boolean,Returns true if the item has been viewed.
FeedItem.Parent:IFeed,Returns the parent feed.

IFeedEnclosure
The IFeedEnclosure interface provides access to the optional media file attachment that may be associated with each feed item.

Enclosure Attributes
FeedEnclosure.Length:Integer,Required. Returns the length in bytes of the enclosure.
FeedEnclosure.Type:String,Required. Returns the Multipurpose Internet Mail Extensions (MIME) type.
FeedEnclosure.Url:String,Required. Returns the source URL of the file.

Common Feed List Properties
FeedEnclosure.LocalPath:String,Returns the local system path of the downloaded file.
FeedEnclosure.Parent:IFeedItem,Returns the parent feed item.

IFeed

The IFeed interface exposes the properties that are present on the RSS channel element.

Feed Elements
Feed.Copyright:String,Optional. Returns the channel copyright.
Feed.Description:String,Required. Returns the channel description.
Feed.Image:String,Optional. Returns the URL of the feed logo.
Feed.Language:String,Optional. Returns the language code for the feed.
Feed.LastBuildDate:Floating-point number,Optional. Returns the date of last content change.
Feed.Link:String,Required. Returns the homepage URL of the feed.
Feed.PubDate:Floating-point number,Optional. Returns the publication date for feed content.
Feed.Title:String,Required. Returns the title of the feed.
Feed.Ttl:String,Optional. Returns the time to live (TTL) of the feed.

XML Source
Feed.Xml(count,sort,filter,include):String,Returns a new XML document for the feed.

Common Feed List Properties
Feed.DownloadUrl:String,Returns URL used for security zone mapping.
Feed.Id:String,Returns the globally unique identifier (GUID) assigned to the feed.
Feed.IsList:Boolean,Returns whether to treat feed as a list.
Feed.ItemCount:Integer,Returns count of items.
Feed.Items:IFeedsEnum,Returns collection of items.
Feed.LastWriteTime:String,Returns date and time of creation or last modification.
Feed.LocalEnclosurePath:String,Returns the system folder where downloaded enclosures are saved.
Feed.MarkAllItemsRead:String,Sets the read status of all items to true.
Feed.Name:String,Returns the name of the feed.
Feed.Parent:IFeedFolder,Returns the parent folder of the feed.
Feed.Path:String,Returns the feed list path of the feed.
Feed.UnreadItemCount:Integer,Returns the count of unread items.
Feed.Url:String,Returns the source URL of the feed.

Where is my xml

Most of the Extensible Markup Language (XML) elements of an RSS 2.0 feed are available as read-only properties on the associated objects.
Although some channel elements (such as cloud, rating, skipDays, and skipHours) are not available as properties on the IFeed interface, they are still in the XML source for the feed. Additional namespace extensions define properties that are used by the Windows RSS Platform to manage lists. (See Simple List Extensions.)

IFeed
The IFeed interface exposes the properties that are present on the RSS channel element.

Feed Elements
Feed.Copyright :String ,Optional. Returns the channel copyright.
Feed.Description :String ,Required. Returns the channel description.
Feed.Image :String ,Optional. Returns the URL of the feed logo.
Feed.Language :String ,Optional. Returns the language code for the feed.
Feed.LastBuildDate :Floating-point number ,Optional. Returns the date of last content change.
Feed.Link :String ,Required. Returns the homepage URL of the feed.
Feed.PubDate :Floating-point number ,Optional. Returns the publication date for feed content.
Feed.Title :String ,Required. Returns the title of the feed.
Feed.Ttl :String ,Optional. Returns the time to live (TTL) of the feed.

XML Source
Feed.Xml(count,sort,filter,include) :String ,Returns a new XML document for the feed.

Common Feed List Properties
Feed.DownloadUrl :String ,Returns URL used for security zone mapping.
Feed.Id :String ,Returns the globally unique identifier (GUID) assigned to the feed.
Feed.IsList :Boolean ,Returns whether to treat feed as a list.
Feed.ItemCount :Integer ,Returns count of items.
Feed.Items :IFeedsEnum ,Returns collection of items.
Feed.LastWriteTime :String ,Returns date and time of creation or last modification.
Feed.LocalEnclosurePath :String ,Returns the system folder where downloaded enclosures are saved.
Feed.MarkAllItemsRead :String ,Sets the read status of all items to true.
Feed.Name :String ,Returns the name of the feed.
Feed.Parent : IFeedFolder ,Returns the parent folder of the feed.
Feed.Path :String ,Returns the feed list path of the feed.
Feed.UnreadItemCount :Integer ,Returns the count of unread items.
Feed.Url :String ,Returns the source URL of the feed.

Working with Feeds

The IFeed interface exposes the required and optional elements of an RSS feed. To subscribe to a feed, merely assign it to a folder.

Below are the methods and properties that are used to manage the feeds.

Feeds
FeedsManager.GetFeed(path):IFeed,Returns specific feed, by feed list path.
FeedFolder.GetFeedByUrl(url):IFeed,Returns specific feed, if subscribed, by URL.
FeedFolder.GetFeed(name):IFeed,Returns specific feed by name.
FeedFolder.Feeds:IFeedsEnum,Returns collection of feeds.
Feed.Name:String,Returns the name of the feed.
Feed.Parent:IFeedFolder,Returns the parent folder of the feed.
Feed.Path:String,Returns the feed list path of the feed.

Feed Existence
FeedsManager.ExistsFeed(path):Boolean,Returns true if feed exists.
FeedFolder.ExistsFeed(name):Boolean,Returns true if feed exists.
FeedsManager.IsSubscribed(url):Boolean,Returns true if a feed subscription exists.

Create, Delete, Move, Rename Feeds
FeedFolder.CreateFeed(name,url):IFeed,Creates feed in folder and subscribes to it.
FeedsManager.DeleteFeed(path):Deletes the feed.
Feed.Delete:Deletes the feed.
Feed.Move(path):Moves the feed.
Feed.Rename(name):Renames the feed.

Common Feed List

The Common Feed List resembles a hierarchical file system with folders and feeds.

The IFeedFolder interface contains properties and methods for accessing feeds contained within the folder as well as properties and methods for accessing subfolders.

Because feed folders are mapped to disk directories, folder names are limited to those characters that the file system allows. (See Valid Feed and Folder Names for more information.)

The root folder of the Common Feed List is accessed through the FeedsManager.RootFolder property, which returns an object of type IFeedFolder.

Below are methods and properties that are used to traverse and manipulate the Common Feed List hierarchy.


FeedsManager.RootFolder :IFeedFolder , Returns the top-level system feed folder.
FeedFolder.IsRoot : Boolean, Returns true if top-level folder.
FeedFolder.Subfolders : IFeedsEnum, Returns collection of subfolders.
FeedsManager.GetFolder(path) :IFeedFolder, Returns specific folder by path.
FeedFolder.GetSubfolder(name) : IFeedFolder, Returns specific subfolder.
FeedFolder.Name : String, Returns the name of the folder.
FeedFolder.Parent : IFeedFolder, Returns the parent folder.
FeedFolder.Path :String, Returns the feed list path of the folder.
FeedFolder.TotalItemCount: Integer, Returns an aggregated total of items in all feeds.
FeedFolder.TotalUnreadItemCount:Integer,Returns an aggregated total of unread items in all feeds.
FeedsManager.ExistsFolder(path):Boolean,Returns true if folder exists.
FeedFolder.ExistsSubfolder(name):Boolean,Returns true if subfolder exists.
Create, Delete, Move, Rename Folders
FeedFolder.CreateSubfolder(name) :IFeedFolder,Creates and returns new subfolder.
FeedsManager.DeleteFolder(path):Deletes folder, including its subfolders and feeds.
FeedFolder.Delete:Deletes folder, including its subfolders and feeds.
FeedFolder.Move(path):Moves the folder.
FeedFolder.Rename(name):Renames the folder.
Working with Feeds
The IFeed interface exposes the required and optional elements of an RSS feed.

To subscribe to a feed, merely assign it to a folder.

Below are methods and properties that are used to manage the feeds.
Feeds
FeedsManager.GetFeed(path):IFeed,Returns specific feed, by feed list path.
FeedFolder.GetFeedByUrl(url):IFeed,Returns specific feed, if subscribed, by URL.
FeedFolder.GetFeed(name):IFeed,Returns specific feed by name.
FeedFolder.Feeds:IFeedsEnum,Returns collection of feeds.
Feed.Name:String,Returns the name of the feed.
Feed.Parent:IFeedFolder,Returns the parent folder of the feed.
Feed.Path:String,Returns the feed list path of the feed.
Feed Existence
FeedsManager.ExistsFeed(path):Boolean,Returns true if feed exists.
FeedFolder.ExistsFeed(name):Boolean,Returns true if feed exists.
FeedsManager.IsSubscribed(url):Boolean,Returns true if a feed subscription exists.
Create, Delete, Move, Rename Feeds
FeedFolder.CreateFeed(name,url):IFeed,Creates feed in folder and subscribes to it.
FeedsManager.DeleteFeed(path):Deletes the feed.
Feed.Delete:Deletes the feed.
Feed.Move(path):Moves the feed.
Feed.Rename(name):Renames the feed.

and that's the feed list story