Mac Dev Center Mac OS X Reference Library Core Services Layer Publication Subscription Publication Subscription Framework Reference

Overview

A PSClient object represents a client of the API that has its own set of feeds. PSClient is the backbone of the Publication Subscription framework. To subscribe to feeds, your application must use a client object. You can then add feeds to the PubSub Database with the addFeed: and addFeedWithURL: methods. Similarly, you can unsubscribe from a feed with the removeFeed: method. It is not recommended that you subclass PSClient.

Methods

-addFeed:

Subscribes the client to the given feed.

-addFeedWithURL:

Subscribes the client to the feed at the given URL.

+allClientBundleIdentifiers

Returns a list of the bundle identifiers for the clients that have registered with the PubSub Agent.

+applicationClient

Creates the default instance for the current application.

+clientForBundleIdentifier:

Creates a client for the specified bundle identifier.

-entryWithIdentifier:

Returns the entry with the given identifier.

-feedWithIdentifier:

Returns the feed with the specified identifier.

-feedWithURL:

Returns the subscribed feed with the given URL.

-removeFeed:

Unsubscribes the client from a feed.

-sendChangesSinceDate:

Calls the delegate methods and sends the corresponding notifications that would have been called if the client had been running since the specified date.

Subscribes the client to the given feed.

- (BOOL) addFeed: (PSFeed*)feed; 

Parameters

Return Value

YES on success; NO if an immediate error occurred.

Discussion

A feed object may only belong to one client, so if the given feed has already been added to any other client, this method will fail. Instead, create a new feed object with the same URL as the existing one or use addFeedWithURL:.

Availability

Introduced in Mac OS X v10.5.

Subscribes the client to the feed at the given URL.

- (PSFeed *) addFeedWithURL: (NSURL*)url; 

Parameters

Return Value

The subscribed feed, or nil if an error occurred.

Discussion

This method creates a subscribed feed from the given URL. If a feed with this URL is already subscribed, this method returns a feed object from the existing data in the PubSub Database.

Availability

Introduced in Mac OS X v10.5.

Returns a list of the bundle identifiers for the clients that have registered with the PubSub Agent.

+ (NSArray*) allClientBundleIdentifiers; 

Return Value

An array of string objects containing the bundle identifiers of the clients registered with the PubSub Agent.

Discussion

This method should be used by applications that want to inspect the subscriptions of another application or construct a set of all subscribed feeds. However, the results may not be complete, because this method does not return the bundle identifiers of private clients.

Availability

Introduced in Mac OS X v10.5.

Creates the default instance for the current application.

+ (PSClient*) applicationClient; 

Return Value

A client object for the current application.

Availability

Introduced in Mac OS X v10.5.

Creates a client for the specified bundle identifier.

+ (PSClient*) clientForBundleIdentifier:(NSString *)bundleIdentifier; 

Parameters

Return Value

A client object for the specified bundle identifier.

Discussion

This method should be used by applications that want to inspect the subscriptions of other applications or by a suite of applications that want to use a shared subscription client. If you need to create a client for the current application, use applicationClient instead.

Availability

Introduced in Mac OS X v10.5.

Returns the entry with the given identifier.

- (PSEntry *) entryWithIdentifier: (NSString*)identifier; 

Parameters

Return Value

The entry associated with the specified identifier, or nil if the identifier is not in a subscribed feed.

Discussion

Entry identifiers are persistent, unique, and unchangeable, so they provide a way for your application to establish a persistent reference to an entry. This method considers only entries in feeds subscribed to by this client.

Availability

Introduced in Mac OS X v10.5.

Returns the feed with the specified identifier.

- (PSFeed *) feedWithIdentifier: (NSString*)identifier; 

Parameters

Return Value

The feed associated with the specified identifier, or nil if the client isn't subscribed to the feed associated with this identifier.

Discussion

Feed identifiers are persistent, unique, and unchangeable, so they provide a way for your application to establish a persistent reference to an feed. This method considers only feeds subscribed to by this client.

Availability

Introduced in Mac OS X v10.5.

Returns the subscribed feed with the given URL.

- (PSFeed *) feedWithURL: (NSURL*)url; 

Parameters

Return Value

The feed from the given URL.

Availability

Introduced in Mac OS X v10.5.

Unsubscribes the client from a feed.

- (BOOL) removeFeed:(PSFeed *)feed; 

Parameters

Return Value

YES if the client is unsubscribed; NO if an error occurred.

Availability

Introduced in Mac OS X v10.5.

Calls the delegate methods and sends the corresponding notifications that would have been called if the client had been running since the specified date.

- (void) sendChangesSinceDate:(NSDate *)dateLastUpdated; 

Parameters

Discussion

Some clients may choose to associate their data with various Publication Subscription instances. Since feeds and articles can change when a client isn't running, dateLastUpdated and sendChangesSinceDate: are needed to maintain a synchronized state. The typical date passed to this method is the value that was returned by the dateLastUpdated method just before the application quit.

Availability

Introduced in Mac OS X v10.5.

Properties

dateLastUpdated

The date and time associated with the most recent feed-change notification delivered to the receiver's delegate.

delegate

The delegate of the client.

feeds

An array of all the feeds subscribed to by the client.

isPrivate

A Boolean value that indicates whether the client instance is private.

settings

The feed settings of the client.

signature

The application bundle identifier associated with the PSClient instance.

The date and time associated with the most recent feed-change notification delivered to the receiver's delegate.

@property (
    readonly) NSDate * dateLastUpdated; 

Discussion

If no notifications have been sent at the time this method was called, it returns the date and time that the receiver was created. Because feeds and entries can change when a client isn't running, store the value from dateLastUpdated when your application quits, and pass that value to sendChangesSinceDate: to retrieve any notifications that would have been called while your application was not running.

Availability

Introduced in Mac OS X v10.5.

The delegate of the client.

@property (
    assign) id delegate; 

Discussion

The delegate should implement the PSClientDelegate informal protocol.

Availability

Introduced in Mac OS X v10.5.

An array of all the feeds subscribed to by the client.

@property (
    readonly) NSArray * feeds; 

Discussion

The ordering of the feeds in the array is undefined.

Availability

Introduced in Mac OS X v10.5.

A Boolean value that indicates whether the client instance is private.

@property (
    getter=isPrivate,
    setter=setPrivate:) BOOL isPrivate; 

Discussion

A private PSClient instance can be accessed only by an application process whose bundle identifier matches the signature of the PSClient.

Availability

Introduced in Mac OS X v10.5.

The feed settings of the client.

@property (
    retain) PSFeedSettings * settings; 

Discussion

If the settings have not been modified, returns the default settings.

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.

The application bundle identifier associated with the PSClient instance.

@property (
    readonly,
    retain) NSString * signature; 

Availability

Introduced in Mac OS X v10.5.