Mac Developer Library

Developer

PSFeed Class Reference

Options
Deployment Target:

On This Page
Language:

PSFeed

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.

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

    Declaration

    - (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.

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

    Declaration

    - (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.

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

    Declaration

    - (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.

  • Returns a temporary feed object initialized from the specified URL.

    Declaration

    - (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.

  • Forces a refresh of the feed.

    Declaration

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

    Discussion

    If any immediate problem is encountered, this method returns NOfalse 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.

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

    Declaration

    - (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.

  • Returns the raw feed, including entries.

    Declaration

    - (NSXMLElement *) XMLRepresentation;

    Return Value

    The raw feed including entry and article elements.

    Discussion

    Equivalent to calling XMLRepresentationWithEntries:YES.

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

    Declaration

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

    Parameters

    withEntries

    A boolean value to determine whether or not the resulting NSXMLElement

    Return Value

    The raw feed.

    Discussion

    The raw feed data is parsed into a DOM tree, and the root element (<feed> or <rss>) is returned. No other processing is performed. Setting the withEntries flag to NOfalse causes the <entry> or <article> elements to be stripped out; other nonstandard child elements are kept, however.

  • URL Property

    A URL to the feed's original location.

    Declaration

    @property (readonly, retain) NSURL * URL;

  • unreadCount Property

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

    Declaration

    @property (readonly) int unreadCount;

    Discussion

    To track this value (by displaying it in your UI, for example), call this method when this PSFeed sends a PSFeedEntriesChangedNotification.

  • title Property

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

    Declaration

    @property (readonly, retain) NSString * title;

    Discussion

    The returned title corresponds to the element in both Atom and RSS.

  • subtitle Property

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

    Declaration

    @property (readonly, retain) NSString * subtitle;

    Discussion

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

  • settings Property

    The current feed settings.

    Declaration

    @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.

  • rights Property

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

    Declaration

    @property (readonly, retain) NSString * rights;

    Discussion

    The returned string corresponds to the <rights> elements in Atom and <copyright> in RSS.

  • refreshing Property

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

    Declaration

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

    Discussion

    If this property returns a value of NOfalse, 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.

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

    Declaration

    @property (readonly, retain) NSURL * redirectedURL;

    Discussion

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

  • logoURL Property

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

    Declaration

    @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 <logo> element in Atom and the <image> element in RSS.

  • login Property

    The user name used if the feed requires authentication.

    Declaration

    @property (retain) NSString * login;

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

    Declaration

    @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.

  • links Property

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

    Declaration

    @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.

  • lastError Property

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

    Declaration

    @property (readonly) NSError * lastError;

    Discussion

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

  • identifier Property

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

    Declaration

    @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 <id> element, it cannot be used for this purpose since the RSS equivalent (<guid>) is optional. Thus, Publication Subscription uses its own mechanism for uniquely identifying feeds. Clients can manually parse the XMLRepresentation if they need the Atom <id> element or RSS <guid> element.

  • iconURL Property

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

    Declaration

    @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 <icon> element in Atom. There is no RSS equivalent.

  • feedFormat Property

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

    Declaration

    @property (readonly) int feedFormat;

  • entries Property

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

    Declaration

    @property (readonly) NSArray * entries;

    Discussion

    Corresponds to <entry> in Atom and <item> in RSS.

  • dateUpdated Property

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

    Declaration

    @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 <updated> element in Atom and the <lastBuildDate> element in RSS.

  • client Property

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

    Declaration

    @property (readonly) PSClient * client;

    Return Value

    The client associated with the receiver.

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

    Declaration

    @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 <hd_link posstarget="element in RSS."> element in RSS. }