Introducing the Windows RSS Platform
Introducing the Windows RSS Platform
This topic introduces the Windows RSS Platform, an API that developers can use to manipulate the Common Feed List, the set of feeds to which the user is subscribed. The properties and methods are categorized to provide a technical overview of the platform and its functionality.
This topic contains the following sections.
- Introduction
- Object Model
- Common Feed List
- Working with Feeds
- RSS 2.0 Elements
- IFeed
- IFeedItem
- IFeedEnclosure
- Feed Synchronization
- Related Topics
Introduction
Really Simple Syndication (RSS) is an XML document format used by Web sites to publish frequently updated content, such as news headlines and blog posts. The distribution is called an RSS feed. In most cases, the RSS feed is retrieved directly from a Web server via HTTP. The RSS specification includes conventions that dictate how often feeds should be checked for updates.
As part of the RSS support in Windows Internet Explorer 7, users can discover and subscribe to RSS feeds within the browser. When the user subscribes to a feed, it is added to the Common Feed List, which is available for clients to use in addition to or instead of their own list. For example, in Microsoft Office Outlook® 2007, the user's subscription list can import feeds from the Common Feed List. This enables the discovery of feeds within Internet Explorer, and then for those discovered feeds to appear in other applications.
The Feed Download Engine downloads feeds and merges the new items with the existing data in the feed store. Using the Windows RSS Platform, applications can then expose the feed data to the user. The RSS Explorer of Windows Vista, for example, provides an excellent text reading experience for news and blog feeds, and Microsoft Windows Media Player enables users to listen to audio feeds. The consumption of feed data varies by application; the Windows RSS Platform makes a variety of scenarios possible by providing easy access to the feed data.
Object Model
The top-level object in the Windows RSS Platform is the FeedsManager object. To create the object for scripting, use the ProgID Microsoft.FeedsManager. To create the object for use with C/C++, call CoCreateInstance with CLSID_FeedsManager (defined in the msfeeds.h header file).
The Windows RSS Platform object model hierarchy is as follows:
.gif "Windows RSS Platform Object Model")
The Windows RSS Platform supports both styles of Component Object Model (COM) interfaces:
- Early-bound (vtable) interface—the interface that is better for C/C++ developers. These objects are in the IXFeedsManager hierarchy.
- Late-bound IDispatch interface—COM Automation interface that is ideal for scripting and managed code (Microsoft Visual Basic .NET and C#). These are the IFeedsManager objects.
To avoid unnecessary repetition, the names of the COM Automation interfaces are used throughout this topic.
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. From there, each IFeedFolder object contains its own collection of subfolders and feeds. (Refer to the example in Subfolders for a demonstration of a recursive folder search that returns an aggregated total count of feeds.)
The following table lists the methods and properties that are used to traverse and manipulate the Common Feed List hierarchy.
| Folder Method | Returns | Description |
|---|---|---|
| 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. |
| Testing for Folders | ||
| FeedsManager.ExistsFolder(path) | Boolean | Returns true if folder exists. |
| FeedFolder.ExistsSubfolder(name) | Boolean | Returns true if subfolder exists. |
| Managing 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, assign it to a folder. The following table lists the methods and properties that are used to manage the feeds.
| Feed Method | Returns | Description |
|---|---|---|
| FeedsManager.GetFeed(path) | IFeed | Returns specific feed, by feed list path. |
| FeedsManager.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. |
| Testing for Feeds | ||
| 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. |
| Managing 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. | |
RSS 2.0 Elements
Most of the 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.
IFeed
The IFeed interface exposes the properties that are present on the RSS channel element.
| Feed Elements | Type | Description |
|---|---|---|
| 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.IsList | Boolean | Returns true if the feed contains list extensions. |
| Feed.ItemCount | Integer | Returns count of items. |
| Feed.Items | IFeedsEnum | Returns collection of items. |
| Feed.LastWriteTime | String | Returns the date and time of creation or last modification. |
| Feed.LocalEnclosurePath | String | Returns the system folder where downloaded enclosures are saved. |
| Feed.LocalId | String | Returns the GUID assigned to the feed. |
| 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. |
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 | Type | Description |
|---|---|---|
| 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.Guid | String | Optional. Returns the GUID of the item. |
| FeedItem.Link | String | Required. Returns the source URL of the item. |
| FeedItem.Modified | Floating-point number | Optional. Returns the date and time of last modification. |
| FeedItem.PubDate | Floating-point number | Optional. Indicates the date of the item publication. |
| 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 the URL used for security zone mapping. |
| FeedItem.Enclosure | IFeedEnclosure | Returns the enclosure (media object) associated with the item. |
| FeedItem.IsRead | Boolean | Returns true if the item has been viewed. |
| FeedItem.LocalId | Integer | Returns the ID assigned by the Feed Download Engine. |
| 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 | Type | Description |
|---|---|---|
| FeedEnclosure.Length | Integer | Required. Returns the length in bytes of the enclosure. |
| FeedEnclosure.Type | String | Required. Returns the MIME type. |
| FeedEnclosure.Url | String | Required. Returns the source URL of the file. |
| Common Feed List Properties | ||
| FeedEnclosure.DownloadMimeType | String | Returns the final MIME type. |
| FeedEnclosure.DownloadUrl | String | Returns the URL used for security zone mapping. |
| FeedEnclosure.LocalPath | String | Returns the local system path of the downloaded file. |
| FeedEnclosure.Parent | IFeedItem | Returns the parent feed item. |
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 following table lists the methods and properties that control the download and synchronization behavior of feeds:
| Synchronization Properties | Type | Description |
|---|---|---|
| FeedsManager.BackgroundSync(action) | Possible actions are: Enable, Disable, or RunNow. | |
| FeedsManager.BackgroundSyncStatus | FEEDS_BACKGROUNDSYNC_STATUS | 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. |
| Synchronization Methods | ||
| FeedsManager.AsyncSyncAll | Forces update of all feeds, regardless of LastDownloadTime or Ttl. | |
| 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. |