|
Really Simple Syndication (RSS) is a collection of standardized
formats that are used to publish information about content that is
frequently changed. A news feed is published in XML format, which
contains one or more items that includes summary text, hyperlinks
to source content and additional metadata that is used to describe
the item. News feeds can be used for a variety of purposes,
including providing updates for weblogs, news headlines, video and
audio content. RSS can also be used for other purposes, such as a
software updates, where new updates are listed as items in the
feed.
News feeds can be accessed remotely from a web server, or
locally as an XML formatted text file. The source of the feed is
determined by the URI scheme that is specified. If the http or
https scheme is specified, then the feed is retrieved from a web
server. If the file scheme is used, the feed is considered to be
local and is accessed from the disk or local network. The News Feed
library provides an API that enables you to open a feed by URL and
iterate through each of the items in the feed or search for a
specific feed item. The API also provides a function that can be
used to parse a string that contains XML data in RSS format, where
the feed may have been retrieved from other sources such as a
database.
The first step your application must take is to initialize the
library, which will load the required system libraries and
initialize the internal data structures that are used. You must
call the initialization function before attempting to call any
other function in the library.
RssInitialize
Initialize the library and load the Windows Sockets library for the
current process. This must be the first function call that the
application makes before calling the other SMS API functions.
RssUninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
function call the application should make prior to terminating.
News Channels
A news feed consists of a channel that contains each of the news
feed items. The news channel is represented in the library by an
HCHANNEL handle. This handle is used with the other
functions to reference the specific news feed channel. Information
about the news feed, such as the title of the channel and the date
it was last modified, is returned in an RSSCHANNEL structure.
RssOpenFeed
Open the channel by specifying a URL to the resource that contains
the news. The URL can identify a remote feed that is downloaded
using the HTTP or HTTPS protocols, or it can be a file on the local
system or network.
RssParseFeed
Parse a string buffer that contains a news feed. This function is
similar to the RssOpenFeed function, however it used to
parse a string that contains the news feed. This function would
typically be used when the feed content is obtained from a
different source, such as a database or by using a different
protocol. For example, the news feed could be downloaded using the
FTP API and then passed to this function.
RssCloseFeed
This function closes the handle that was allocated by a previous
call to the RssOpenFeed or RssParseFeed function.
When the information in a news feed is no longer needed, this
function must be called to release the resources allocated to
process the feed. After this function is called, the handle is no
longer valid.
RssValidateFeed
This function is used to validate the contents of a news feed,
ensuring that it is structured correctly. The function will return
information about the feed, including the number of news items in
the feed and the date that it was last modified. The news feed can
be specified either as a URL to a remote resource or as a file on
the local system or network.
RssStoreFeed
This function is used to store a news feed as a file on the local
system. This is typically used to cache the contents of a news feed
or to track the changes made to the feed over time. It is
recommended that the application periodically check the publication
date of the feed to ensure that they have current version.
News Items
News feed items are identified by a numeric value called the
item ID. This is used with other functions to return information
about a specific news item. The first item in a news feed has an ID
of one and it increments for each additional item in the feed,
although it is recommended that applications treat this an opaque
value. Functions are provided which will return the number of items
in a news feed, information about each item and enable you to
easily enumerate each of the items in the feed. Information about a
particular news item is returned in an RSSCHANNELITEM
structure.
RssGetItemCount
This function will return the number of news items in the feed.
RssGetFirstItem /
RssGetNextItem
These functions are used to enumerate the items in the news feed.
Details about each news item is returned in an
RSSCHANNELITEM structure which contains information such as
the title, description and author of the news item.
RssGetItem
This function is used to return information about a specific news
item based on the item ID. When the function returns, it will
populate an RSSCHANNELITEM structure. Although this function
can be used to effectively enumerate all of the news feed items by
starting with an item ID value of one, it's recommended that you
use the RssGetFirstItem and RssGetNextItem functions
instead. Your application should never make an assumption about the
actual value of the item ID because there's no guarantee that
future versions of the library will assign item IDs sequentially.
Best practices dictate that the RssGetItem function should
only be called using an item ID that was previously obtained by a
call to either the RssGetFirstItem, RssGetNextItem or
RssFindItem functions.
RssFindItem
This function is used to search the feed channel for a specific
item, based either on its GUID, title, link or publication date.
When searching for a specific item, only searches by GUID are
guaranteed to return a unique news item. However, since not all
news feeds may provide GUIDs for their news items, additional
search criteria can be used when necessary. If the function is
successful, it will populate an RSSCHANNELITEM structure
with information about the news feed item.
RssGetItemText
This function is used to return a copy of the news item description
based on the item ID. Internally, this function calls
RssGetItem and then copies the item description to the
string buffer that is provided by the caller. Note that it is the
responsibility of the application to display the text in the
appropriate format. Most news feeds will either use plain text or
HTML formatted text for the item description.
|