Developer Documentation
PATH  Mac OS X Documentation > Foundation Reference: Objective-C


[Previous] [Class List] [Next]

NSDistributedNotificationCenter


Inherits from: NSNotificationCenter : NSObject
Conforms to: NSObject
(NSObject)
Declared in: Foundation/NSDistributedNotificationCenter.h



Class at a Glance


NSDistributedNotificationCenter provides a way for objects that don't know about each other to communicate between tasks. It receives NSNotification objects and broadcasts them to all interested objects.

Principal Attributes


A table of objects that want to receive notifications, the notifications they want to receive, and identifying strings they are interested in.

Creation


Each machine has a default distributed notification center. You typically don't create your own.

Commonly Used Methods



+ defaultCenter Accesses the default notification center.
- addObserver:selector:name:object:suspensionBehavior: Registers an object to receive a notification with a specified behavior when notification delivery is suspended.
- postNotificationName:object:userInfo:deliverImmediately: Creates and posts a notification.
- removeObserver:name:object: Specifies that an object no longer wants to receive certain notifications.


Class Description


An NSDistributedNotificationCenter object (or simply, distributed notification center) is a notification center that can distributed notifications to tasks other than the one in which the notification was posted.

The distributed notification center notifies all observers of notifications meeting specific criteria. This information is encapsulated in NSNotification objects, also known as notifications. Client objects register themselves as observers of specific notifications posted by other objects. When an event occurs, an object posts an appropriate notification to the distributed notification center. (See the NSNotification class specification for more on notifications.) The distributed notification center dispatches a message to each registered observer, passing the notification as the sole argument. It is possible for the posting object and the observing object to be the same.

Each task has a default distributed notification center that you access with the defaultCenter class method. There may be different types of distributed notification centers. Right now there is a single type-NSLocalNotificationCenterType. This type of distributed notification center handles notifications that can be sent between tasks on a single machine. For communication between tasks on different machines, use Distributed Objects.

Registering to Receive Notifications

An object registers itself to receive a notification by sending the addObserver:selector:name:object:suspensionBehavior: method, specifying the message the notification should send, the name of the notification it wants to receive, the identifying string to match (the anObject argument), and the behavior to follow if notification delivery is suspended. Because the posting object and the observer may be in different tasks, notifications can't contain pointers to arbitrary objects. Therefore, NSDistributedNotificationCenter requires notifications to use an NSString as the anObject argument. Notification matching is done based on this string, rather than an object pointer. You should check the documentation of the object posting the notification to see what it uses as its identifying string.

There are four different types of suspension behavior, each useful in different circumstances:

Suspending Notification Delivery

When a task is no longer interested in receiving notifications immediately, it may suspend notification delivery. This is often done when the application is hidden, or is put into the background. You suspend notifications by invoking setSuspended: with an argument of YES on the distributed notification center.

While notifications are suspended, the notification server handles notifications destined for the task that suspended notification delivery according to the suspension behavior specified by the observers when they registered to receive notifications. (See the table above.) When the task unsuspends notification delivery, all queued notifications are delivered immediately. Note that a notification destined for an observer that registered with NSNotificationSuspensionBehaviorDeliverImmediately will automatically flush the queue as it is delivered, causing all queued notifications to be delivered at that time as well.

Posting Notifications for Immediate Delivery

If an object posting a notification wants to ensure that all observers receive the notification immediately (for example, if the notification is a warning that a server is about to shut down), it can invoke postNotificationName:object:userInfo:deliverImmediately: with a deliverImmediately argument of YES. The notification center will deliver the notification as if the observers had registered with NSNotificationSuspensionBehaviorDeliverImmediately .


Constants

There are four different types of suspension behavior, each useful in different circumstances.
Suspension Behavior Description
NSNotificationSuspensionBehaviorDrop Drops notifications observed with this behavior when the observer suspends notifications.
NSNotificationSuspensionBehaviorCoalesce Coalesces notifications observed with this behavior, such that only the most recent notification is delivered when notification delivery is resumed.
NSNotificationSuspensionBehaviorHold Holds all notifications on the notification server for later delivery when notification delivery is resumed.
NSNotificationSuspensionBehaviorDeliverImmediately Delivers matching notifications immediately. This also flushes the queue of undelivered notifications-the behavior is as if the receiving application had momentarily called setSuspended: with an argument of NO, then immediately after all notifications are delivered, called setSuspended: again with an argument of YES.

Method Types


Accessing distributed notification centers
+ defaultCenter
+ notificationCenterForType:
Adding and removing observers
- addObserver:selector:name:object:
- addObserver:selector:name:object:suspensionBehavior:
- removeObserver:name:object:
Posting notifications
- postNotification:
- postNotificationName:object:
- postNotificationName:object:userInfo:
- postNotificationName:object:userInfo:deliverImmediately:
Suspending and enabling notification delivery
- setSuspended:
- suspended

Class Methods



defaultCenter

+ (NSNotificationCenter *)defaultCenter

Returns the default distributed notification center, the local notification center for the machine. Calls notificationCenterForType: with an argument of NSLocalNotificationCenterType.

notificationCenterForType:

+ (NSDistributedNotificationCenter *)notificationCenterForType:(NSString *)type

Returns the distributed notification center for the specified type. Currently only one type, NSLocalNotificationCenterType, is supported.


Instance Methods



addObserver:selector:name:object:

- (void)addObserver:(id)anObserver selector:(SEL)aSelector name:(NSString *)notificationName object:(NSString *)anObject

Registers anObserver to receive notifications with the name notificationName and/or the identifying string anObject.

This method calls addObserver:selector:name:object:suspensionBehavior: with a suspensionBehavior: argument of NSNotificationSuspensionBehaviorCoalesce <<XRef to Constants>>.



addObserver:selector:name:object:suspensionBehavior:

- (void)addObserver:(id)anObserver selector:(SEL)aSelector name:(NSString *)notificationName object:(NSString *)anObject suspensionBehavior:(NSNotificationSuspensionBehavior)suspensionBehavior

Registers anObserver to receive notifications with the name notificationName and/or the identifying string anObject.

When a notification of name notificationName with the identifying string anObject is posted, anObserver receives an aSelector message with this notification as the argument. The method for the selector specified in aSelector must have one and only one argument. If notificationName is nil, the notification center notifies the observer of all notifications with an identifying string matching anObject. If anObject is nil, the notification center notifies the observer of all notifications with the name notificationName. The suspensionBehavior determines how the notification center handles notifications when notification delivery has been suspended. Here are the possible values:

The notification center does not retain anObserver. Therefore, you should always send removeObserver: or removeObserver:name:object: to the notification center before releasing anObserver.

See Also: - postNotificationName:object:userInfo:deliverImmediately:



postNotification:

- (void)postNotification:(NSNotification *)notification

Posts notification to the notification center. notification should have an NSString as its object instance variable, so the notification can be delivered in another task. This method invokes postNotificationName:object:userInfo:deliverImmediately: with the information contained in notification and a deliverImmediately: argument of NO.

See Also: - postNotificationName:object:, - postNotificationName:object:userInfo:, - postNotificationName:object:userInfo:deliverImmediately:



postNotificationName:object:

- (void)postNotificationName:(NSString *)notificationName object:(NSString *)anObject

Creates a notification with the name notificationName, associates it with the string anObject, and posts it to the notification center. anObject may be nil.

This method invokes postNotificationName:object:userInfo:deliverImmediately: with a userInfo: argument of nil and a deliverImmediately: argument of NO.

See Also: - postNotification:



postNotificationName:object:userInfo:

- (void)postNotificationName:(NSString *)notificationName object:(NSString *)anObject userInfo:(NSDictionary *)userInfo

Creates a notification with the name notificationName, associates it with the string anObject and dictionary userInfo, and posts it to the notification center. anObject and userInfo may be nil.

This method invokes postNotificationName:object:userInfo:deliverImmediately: with a deliverImmediately: argument of NO.

See Also: - postNotificationName:object:



postNotificationName:object:userInfo:deliverImmediately:

- (void)postNotificationName:(NSString *)notificationName object:(NSString *)anObject userInfo:(NSDictionary *)userInfo deliverImmediately:(BOOL)deliverImmediately

Creates a notification with the name notificationName, associates it with the string anObject and dictionary userInfo, and posts it to the notification center with delivery scheduled for deliverImmediately, as supplied by the invoker. This method is the preferred method for posting notifications.

The userInfo dictionary is serialized using the NSArchiver class, so it can be passed to another task. In the receiving task, it is deserialized using NSUnarchiver. This imposes some restrictions on the objects that can be placed in the userInfo dictionary. See the NSArchiver and NSUnarchiver documentation for details.

Posting with deliverImmediately set to NO allows the normal suspension behavior of the observers to take place. If deliverImmediately is set to YES, the notification is delivered immediately to all observers, regardless of their suspension behavior or suspension state.

See Also: - postNotificationName:object:userInfo:, - encodeRootObject: (NSArchiver) + unarchiveObjectWithData: (NSUnarchiver)



removeObserver:name:object:

- (void)removeObserver:(id)anObserver name:(NSString *)notificationName object:(NSString *)anObject

Removes anObserver from the notification center as the observer of notifications with the name notificationName and identifying string anObject . Be sure to invoke this method (or removeObserver:) before deallocating the observer object. <<Why isn't there a Java version of this method?>>

If anObserver is nil, all objects are removed as observers of notificationName with identifying string anObject. If notificationName is nil, anObserver is removed as an observer of all notifications with identifying string anObject. If anObject is nil, anObserver is removed as an observer of notificationName with any identifying string. <<Perhaps better would be to say that an argument of nil is interpreted as a wildcard, matching any value...>>



setSuspended:

- (void)setSuspended:(BOOL)suspended

Suspends notification delivery when set to YES, and resumes immediate notification delivery when set to NO. Distributed notification centers enable or suspend notification delivery on a per-task basis. When a task suspends notification delivery, notifications are delivered according to the suspension behavior of the observer. When delivery is not suspended, notifications are always delivered immediately. See "Suspending Notification Delivery" in the class introduction for more information.

See Also: - addObserver:selector:name:object:suspensionBehavior:, - postNotificationName:object:userInfo:deliverImmediately:



suspended

- (BOOL)suspended

Returns YES if the notification center is delivering notifications for this application according to their suspension behavior, NO if it is delivering them immediately.


[Previous] [Next]