---

NSDistributedNotificationCenter

Class at a Glance

NSDistributedNotificationCenter provides a way to send notifications to objects in other tasks. It takes NSNotification objects and broadcasts them to any objects in other tasks that have registered for the notification with their task’s default NSDistributedNotificationCenter.

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 task has a default distributed notification center. You typically don’t create your own.

Commonly Used Methods

defaultCenter

Accesses the default notification center.

addObserver

Registers an object to receive a notification with a specified behavior when notification delivery is suspended.

postNotification

Creates and posts a notification.

Overview

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

Each task has a default distributed notification center that you access with the defaultCenter static method. There may be different types of distributed notification centers. Right now there is a single type—LocalNotificationCenterType. 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”.

Posting a distributed notification is an expensive operation. The notification gets sent to a system-wide server that then distributes it to all the tasks that have objects registered for distributed notifications. The latency between posting the notification and the notification’s arrival in another task is unbounded. In fact, if too many notifications are being posted and the server’s queue fills up, notifications can be dropped.

Distributed notifications are delivered via a task’s run loop. A task must be running a run loop in one of the “common” modes, such as NSRunLoop.DefaultRunLoopMode, to receive a distributed notification. For multithreaded applications running in Mac OS X v10.3 and later, distributed notifications are always delivered to the main thread. For multithreaded applications running in Mac OS X v10.2.8 and earlier, notifications are delivered to the thread that first used the distributed notifications API, which in most cases is the main thread.

Tasks

Constructors

• NSDistributedNotificationCenter

Accessing Distributed Notification Centers

• defaultCenter
• notificationCenterForType

Adding and Removing Observers

• addObserver

Posting Notifications

• postNotification

Suspending and Enabling Notification Delivery

• setSuspended
• suspended

Static Methods

defaultCenter

Returns the default distributed notification center, representing the local notification center for the machine by calling notificationCenterForType with an argument of LocalNotificationCenterType.

public static NSNotificationCenter defaultCenter()

notificationCenterForType

Returns the distributed notification center for the specified type.

public static NSDistributedNotificationCenter notificationCenterForType(String type)

Discussion

Currently only one type, LocalNotificationCenterType, is supported.

Instance Methods

addObserver

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

public void addObserver(Object anObserver, NSSelector aSelector, String notificationName, String anObject, int suspensionBehavior)

Discussion

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 null, the notification center notifies the observer of all notifications with an identifying string matching anObject. If anObject is null, 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. The possible values are described in “Constants.”

See Also

• postNotification

postNotification

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.

public void postNotification(String notificationName, String anObject, NSDictionary userInfo, boolean deliverImmediately)

Discussion

This method is the preferred method for posting notifications.

The userInfo dictionary is serialized as a property list, so it can be passed to another task. In the receiving task, it is deserialized back into a dictionary. This serialization imposes some restrictions on the objects that can be placed in the userInfo dictionary. See “XML Property Lists” for details.

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

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

public void postNotification(String name, String anObject, NSDictionary userInfo, int options)

Discussion

Possible values for options are described in the “Constants” section. Pass in 0 for no options.

The userInfo dictionary is serialized as a property list, so it can be passed to another task. In the receiving task, it is deserialized back into a dictionary. This serialization imposes some restrictions on the objects that can be placed in the userInfo dictionary. See “XML Property Lists” for details.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• encodeRootObject (NSArchiver)
• unarchiveObjectWithData (NSUnarchiver)

setSuspended

Suspends notification delivery when set to true and resumes immediate notification delivery when set to false.

public void setSuspended(boolean suspended)

Discussion

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 “Constants” for the available types of suspension behaviors.

NSApplication automatically suspends delivery when the application is not active. Applications based on the Application Kit should let the Application Kit manage the suspension of distributed notification delivery. Foundation-only programs may have occasional need to use this method.

See Also

• addObserver
• postNotification
• suspended

suspended

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

public boolean suspended()

Discussion

Applications based on the Application Kit should let the Application Kit manage the suspension of distributed notification delivery. Foundation-only programs may have occasional need to use this method.

See Also

• setSuspended

Constants

NSDistributedNotificationCenter defines the following notification center type:

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

NSDistributedNotificationCenter defines these constants to specify the behavior of notifications posted using postNotification:

---