PSFeed

Framework:
/System/Library/Frameworks/PubSub.framework
Inherits from:
Declared In:
See Also:

Overview

A PSFeed object is used for managing RSS and Atom feeds. Each feed object represents a single feed. Feed objects can either be created for subscription or parsing. To subscribe to a feed, use initWithURL: and then add the newly returned feed object to a client. To use Publication Subscription to simply parse a feed, download the feed with NSURL and then use initWithData:URL:.

Many of the feed's attributes are defined by the RSS 2.0 and Atom 1.0 specs. Any attributes defined by the specifications (or nonstandard extensions) that do not appear in this API can be retrieved using the XMLRepresentation method.

Since the values of the RSS and Atom attributes are derived from data received from the server, they may be missing or incorrect. If you have the opportunity, use attributes generated by the Publication Subscription framework, as it is more reliable. For example, using updatedDate to find entries that have been modified since a certain time would be unreliable. Use receivedDate instead. It is not recommended that you subclass PSFeed.


Methods

-entryEnumeratorSortedBy:

Returns an enumerator that contains the feed's entries sorted by the specified sort descriptors.

-extensionXMLElementsUsingNamespace:

Returns an array of the extension XML elements outside of the RSS and/or Atom standards.

-initWithData:URL:

Returns a temporary feed object initialized to the specified XML data located at the specified URL.

-initWithURL:

Returns a temporary feed object initialized from the specified URL.

-refresh:

Forces a refresh of the feed.

-setPassword:

Sets the password to use for a feed whose server requires authentication.

-XMLRepresentation

Returns the raw feed, including entries.

-XMLRepresentationWithEntries:

Returns the raw feed, with or without the entry and article elements.

entryEnumeratorSortedBy:

Returns an enumerator that contains the feed's entries sorted by the specified sort descriptors. 

- (NSEnumerator*) entryEnumeratorSortedBy: (NSArray*)sortDescriptors;
Parameters
sortDescriptors

An array containing a sort descriptor for sorting the feed's entries.

Return Value

An enumerator containing each of the feed's entries, sorted by the given sort descriptors.

Discussion

This method allows the entries to be loaded into memory one at a time, which can make it more efficient than the regular entries method. (However, you also need to wrap your enumeration loop in an autorelease pool and drain the pool at the end of the loop. Otherwise, prior entries will not be deallocated until sometime after the loop finishes.)

If sortDescriptors is empty or nil, the entries will not be sorted.

Availability
Introduced in Mac OS X v10.5.

extensionXMLElementsUsingNamespace:

Returns an array of the extension XML elements outside of the RSS and/or Atom standards. 

- (NSArray *) extensionXMLElementsUsingNamespace:(NSString *)nameSpace;
Parameters
nameSpace

The namespace of the extension XML elements; pass nil to receive all extension XML elements.

Return Value

An array of NSXMLElement objects containing the appropriate extension XML elements.

Discussion

Pass nil for nameSpace to get all extension XML elements, regardless of their namespace. This works at the feed-level only. You can use the same method on an entry to retrieve extension XML elements at that level. When using the nameSpace parameter, make sure to pass a full namespace, such as http://www.itunes.com/dtds/podcast-1.0.dtd, instead of the namespace prefix.

Availability
Introduced in Mac OS X v10.5.

initWithData:URL:

Returns a temporary feed object initialized to the specified XML data located at the specified URL. 

- (id) initWithData:(NSData *)data URL:(NSURL *)aURL;
Parameters
data

A data object containing the feed. This object can be obtained by using NSURL or NSURLConnection to download the feed in its entirety.

aURL

The URL of the feed.

Return Value

A feed parsed from the specified data.

Discussion

This method does not cause any network activity. The feed is parsed directly from the provided XML data. The URL parameter is required only to resolve relative URLs, and for future reference if this object is later subscribed to.

See the discussion under the initWithURL: method for more information about temporary feeds.

Availability
Introduced in Mac OS X v10.5.

initWithURL:

Returns a temporary feed object initialized from the specified URL. 

- (id) initWithURL: (NSURL*)url;
Parameters
aURL

The URL of the feed.

Return Value

A feed from the specified URL.

Discussion

This method does not cause any network activity. The feed's entries and metadata will not be available until the feed is added to a client (via the addFeedWithURL: method of PSClient) or its update method is called, and the feed has been downloaded and parsed.

Temporary feeds are not associated with any PSClient, and their contents will not be stored persistently. If desired, this feed can later be made persistent and 'subscribed to' by calling addFeed: on a PSClient object.

Temporary feeds are not automatically updated on a schedule. Instead, you must call "update" whenever you want to check for updates.

Availability
Introduced in Mac OS X v10.5.

refresh:

Forces a refresh of the feed. 

- (BOOL) refresh: (NSError**)error;
Discussion

If any immediate problem is encountered, this method returns NO and sets the error parameter. However, refreshing is an asynchronous operation, and errors are more likely to show up later. These can be accessed via the feed's latestError property after it sends a notification that it's ended refreshing.

To check on the status of the refresh, register for the PSFeedRefreshingNotification notification and then check the isRefreshing property.

Availability
Introduced in Mac OS X v10.5.

setPassword:

Sets the password to use for a feed whose server requires authentication. 

- (void) setPassword: (NSString*)password;
Discussion

The password is stored in the user's default keychain, associated with this feed's URL.

There is intentionally no corresponding getPassword method, because only PubSub itself needs to access the password.

This method is optional. If no password is found in the keychain when the feed is being updated, Publication Subscription will prompt the user for one, and add it to the keychain. However, your application's UI may want to let the user enter the password at the same time as he enters the user name.

This method attempts to communicate with the PubSubAgent process and causes the agent to launch if it is not already running. If PubSubAgent cannot be contacted, an exception will be thrown with the name PSException. To avoid problems, you should always be prepared to catch an exception thrown by this method.

Availability
Introduced in Mac OS X v10.5.

XMLRepresentation

Returns the raw feed, including entries. 

- (NSXMLElement *) XMLRepresentation;
Return Value

The raw feed including entry and article elements.

Discussion

Equivalent to calling XMLRepresentationWithEntries:YES.

Availability
Introduced in Mac OS X v10.5.

XMLRepresentationWithEntries:

Returns the raw feed, with or without the entry and article elements. 

- (NSXMLElement *) XMLRepresentationWithEntries:(BOOL)withEntries;
Parameters
withEntries

A boolean value to determine whether or not the resulting NSXMLElement object will contain the entry and article elements.

Return Value

The raw feed.

Discussion

The raw feed data is parsed into a DOM tree, and the root element ( or ) is returned. No other processing is performed. Setting the withEntries flag to NO causes the or

elements to be stripped out; other nonstandard child elements are kept, however.

Availability
Introduced in Mac OS X v10.5.

Properties

alternateURL

A URL to an alternate version of the feed resource. (read-only)

client

Returns the client that the receiver belongs to, or nil if the receiver has not been added to any client.

dateUpdated

A date that represents the most recent time the feed was modified. (read-only)

entries

An array of entry objects that contains the entries of a feed. (read-only)

feedFormat

The data format of the feed (RSS or Atom). (read-only)

iconURL

A URL to the feed's icon. (read-only)

identifier

A string that uniquely identifies the feed. (read-only)

lastError

The most recent error that occurred during the feed update, or nil if it was successful. (read-only)

links

An array of link objects that provide links to other URLs that are declared in this feed. (read-only)

localDateUpdated

The date when the feed and/or its entries were updated in the local Publication Subscription database. (read-only)

login

The user name used if the feed requires authentication.

logoURL

A URL to a feed's logo. (read-only)

redirectedURL

A URL to the current location of a given feed. (read-only)

refreshing

A Boolean value that indicates whether the feed is currently being refreshed. (read-only)

rights

The legal information of a given feed. (read-only)

settings

The current feed settings.

subtitle

A string that contains the subtitle (or description) of a given feed. (read-only)

title

A string that contains the title of a given feed. (read-only)

unreadCount

The number of unread entries in the feed. (read-only)

URL

A URL to the feed's original location.

alternateURL

A URL to an alternate version of the feed resource. (read-only) 

@property (
    readonly,
    retain) NSURL * alternateURL;
Discussion

Traditionally, the alternate URL corresponds to the homepage associated with the feed. The URL is parsed from the element in Atom and the element in RSS.

Availability
Introduced in Mac OS X v10.5.

client

Returns the client that the receiver belongs to, or nil if the receiver has not been added to any client. 

@property (
    readonly) PSClient * client;
Return Value

The client associated with the receiver.

Availability
Introduced in Mac OS X v10.5.

dateUpdated

A date that represents the most recent time the feed was modified. (read-only) 

@property (
    readonly,
    retain) NSDate * dateUpdated;
Discussion

The date is stored in the feed and set by the software that creates it. Therefore, it is associated with the feed's server, not the machine your application is running on. The returned date corresponds to the element in Atom and the element in RSS.

Availability
Introduced in Mac OS X v10.5.

entries

An array of entry objects that contains the entries of a feed. (read-only) 

@property (
    readonly) NSArray * entries;
Discussion

Corresponds to in Atom and in RSS.

Availability
Introduced in Mac OS X v10.5.

feedFormat

The data format of the feed (RSS or Atom). (read-only) 

@property (
    readonly) int feedFormat;

Availability
Introduced in Mac OS X v10.5.

iconURL

A URL to the feed's icon. (read-only) 

@property (
    readonly,
    retain) NSURL * iconURL;
Discussion

Icons should have an aspect ratio of 1:1 and be suitable for presentation at a small size. The URL corresponds to the element in Atom. There is no RSS equivalent.

Availability
Introduced in Mac OS X v10.5.

identifier

A string that uniquely identifies the feed. (read-only) 

@property (
    readonly,
    retain) NSString * identifier;
Discussion

This identifier can be used as a key to map between PSFeed objects and your application's own data model objects. This identifier is generated internally by the Publication Subscription framework. You should not make any assumptions about its format or size, as they may change. Although Atom defines a mandatory element, it cannot be used for this purpose since the RSS equivalent () is optional. Thus, Publication Subscription uses its own mechanism for uniquely identifying feeds. Clients can manually parse the XMLRepresentation if they need the Atom element or RSS element.

Availability
Introduced in Mac OS X v10.5.

lastError

The most recent error that occurred during the feed update, or nil if it was successful. (read-only) 

@property (
    readonly) NSError * lastError;
Discussion

Can be used to obtain failure status such as "Feed is 404", "Server is not responding", etc.

Availability
Introduced in Mac OS X v10.5.

links

An array of link objects that provide links to other URLs that are declared in this feed. (read-only) 

@property (
    readonly) NSArray * links;
Discussion

Feeds and HTML pages can contain both "link" tags (that define explicit links to other URLs) and the purposes of those links. This is often used for "autodiscovery", where a web page contains a link to its feed.

Availability
Introduced in Mac OS X v10.5.

localDateUpdated

The date when the feed and/or its entries were updated in the local Publication Subscription database. (read-only) 

@property (
    readonly,
    retain) NSDate * localDateUpdated;
Discussion

This is the date/time that changes in the feed were received, whereas the dateUpdated is the time that changes were published by the server.

Availability
Introduced in Mac OS X v10.5.

login

The user name used if the feed requires authentication. 

@property (
    retain) NSString * login;

Availability
Introduced in Mac OS X v10.5.

logoURL

A URL to a feed's logo. (read-only) 

@property (
    readonly,
    retain) NSURL * logoURL;
Discussion

Even though Atom states that logos should have an aspect ratio of 2:1, RSS prefers a default size of 88 x 31 pixels. The returned URL corresponds to the element in Atom and the element in RSS.

Availability
Introduced in Mac OS X v10.5.

redirectedURL

A URL to the current location of a given feed. (read-only) 

@property (
    readonly,
    retain) NSURL * redirectedURL;
Discussion

The URL is to the feed's current location following any redirects.

Availability
Introduced in Mac OS X v10.5.

refreshing

A Boolean value that indicates whether the feed is currently being refreshed. (read-only) 

@property (
    readonly,
    getter=isRefreshing) BOOL refreshing;
Discussion

If this property returns a value of NO, this may be because the feed has finished refreshing or because the feed has not started refreshing. To get more accurate output, register for the PSFeedRefreshingNotification notification and then call this method.

Availability
Introduced in Mac OS X v10.5.

rights

The legal information of a given feed. (read-only) 

@property (
    readonly,
    retain) NSString * rights;
Discussion

The returned string corresponds to the elements in Atom and in RSS.

Availability
Introduced in Mac OS X v10.5.

settings

The current feed settings. 

@property (
    retain) PSFeedSettings * settings;
Discussion

The client's settings are used whenever a feed's settings are undefined.

This property attempts to communicate with the PubSubAgent process and causes the agent to launch if it is not already running. If PubSubAgent cannot be contacted, an exception will be thrown with the name PSException. To avoid problems, you should always be prepared to catch an exception thrown by this property.

Availability
Introduced in Mac OS X v10.5.

subtitle

A string that contains the subtitle (or description) of a given feed. (read-only) 

@property (
    readonly,
    retain) NSString * subtitle;
Discussion

The returned subtitle corresponds to the element in Atom and in RSS.

Availability
Introduced in Mac OS X v10.5.

title

A string that contains the title of a given feed. (read-only) 

@property (
    readonly,
    retain) NSString * title;
Discussion

The returned title corresponds to the element in both Atom and RSS. <!-- end discussion --> <p></p><dl><dt><i>Availability</i></dt><dd>Introduced in Mac OS X v10.5.</dd> </dl> <hr><!-- headerDoc=instp; uid=//apple_ref/occ/instp/PSFeed/unreadCount; name=PSFeed::unreadCount --> <a name="//apple_ref/occ/instp/PSFeed/unreadCount"></a> <table border="0" cellpadding="2" cellspacing="2" width="300"><tr><td valign="top" height="12" colspan="5" scope="row"><h3><a name="unreadCount">unreadCount</a></h3> </td></tr></table><hr><p><!-- begin abstract --><p>The number of unread entries in the feed. (read-only) <!-- end abstract --></p> <p></p><div class='declaration_indent'> <pre>@property ( <span class="param">readonly</span>) <!-- a --><span class="type">int</span><!-- /a --> <!-- a --><span class="var">unreadCount</span><!-- /a -->; </pre> </div> <h5 class="tight"><font face="Lucida Grande,Helvetica,Arial">Discussion</font> </h5><!-- begin discussion --><p>To track this value (by displaying it in your UI, for example), call this method when this <code>PSFeed</code> sends a <code>PSFeedEntriesChangedNotification</code>. <!-- end discussion --> <p></p><dl><dt><i>Availability</i></dt><dd>Introduced in Mac OS X v10.5.</dd> </dl> <hr><!-- headerDoc=instp; uid=//apple_ref/occ/instp/PSFeed/URL; name=PSFeed::URL --> <a name="//apple_ref/occ/instp/PSFeed/URL"></a> <table border="0" cellpadding="2" cellspacing="2" width="300"><tr><td valign="top" height="12" colspan="5" scope="row"><h3><a name="URL">URL</a></h3> </td></tr></table><hr><p><!-- begin abstract --><p>A URL to the feed's original location. <!-- end abstract --></p> <p></p><div class='declaration_indent'> <pre>@property ( <span class="param">readonly</span>, <span class="param">retain</span>) <a href="../../../../../../Cocoa/Reference/Foundation/Classes/NSURL_Class/Reference/Reference.html#//apple_ref/occ/cl/NSURL" target="_top" class="type"><span class="type">NSURL</span></a> <span class="type">*</span> <!-- a --><span class="var">URL</span><!-- /a -->; </pre> </div> <p></p><dl><dt><i>Availability</i></dt><dd>Introduced in Mac OS X v10.5.</dd> </dl> <p><!-- start of footer --> <!-- start of footer --> <!--#include virtual="../../../../../../../Resources/383/includes/reflib_small_feedback"--> <p> </p> <!--#include virtual="../../../../../../../Resources/383/includes/footer"--> <!-- end of footer --> <!-- end of footer --> Last Updated: 2009-08-12 </p></body></html>