- Inherits from:
- NSNotificationCenter : NSObject
- Conforms to:
- NSObject
- (NSObject)
Declared in:
- Foundation/NSDistributedNotificationCenter.h
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.
Each machine has a default distributed notification center. You typically don't create your own.
+ 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. |
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.
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, further described in the "Constants" section, each useful in different circumstances:
NSNotificationSuspensionBehaviorDrop
NSNotificationSuspensionBehaviorCoalesce
NSNotificationSuspensionBehaviorHold
NSNotificationSuspensionBehaviorDeliverImmediately
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. When the task unsuspends
notification delivery, all queued notifications are delivered immediately.
Note that a notification destined for an observer that registered
with NSNotificationSuspensionBehaviorDeliverImmediately
(described
in "Constants" ), will
automatically flush the queue as it is delivered, causing all queued
notifications to be delivered at that time as well.
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
(further
described below, in "Constants" ).
There are four different types of suspension behavior, each useful in different circumstances.
Suspension Behavior | Description |
NSNotificationSuspensionBehaviorDrop |
The server does not queue any notifications with this name and object until setSuspended: with an argument of NO is called. |
NSNotificationSuspensionBehaviorCoalesce |
The server only queues the last notification of the specified
name and object; earlier notifications are dropped. In cover methods
for which suspension behavior is not an explicit argument, NSNotificationSuspensionBehaviorCoalesce is
the default. |
NSNotificationSuspensionBehaviorHold |
The server holds all matching notifications until the queue has been filled (queue size determined by the server) at which point the server may flush queued notifications. |
NSNotificationSuspensionBehaviorDeliverImmediately |
The server delivers notifications matching this registration irrespective of whether setSuspended: with an argument of YES has been called. When a notification with this suspension behavior is matched, it has the effect of first flushing any queued notifications. The effect is as if setSuspended: with an argument of NO were first called if the app is suspended, followed by the notification in question being delivered, followed by a transition back to the previous suspended or unsuspended state. |
- Accessing distributed notification centers
- + defaultCenter
- + notificationCenterForType:
- Adding and removing observers
- - addObserver:selector:name:object:
- - addObserver:selector:name:object:suspensionBehavior:
- - removeObserver:name:object:
- Posting notifications
- - postNotificationName:object:
- - postNotificationName:object:userInfo:
- - postNotificationName:object:userInfo:deliverImmediately:
- Suspending and enabling notification delivery
- - setSuspended:
- - suspended
+ (NSNotificationCenter *)defaultCenter
NSLocalNotificationCenterType
.+ (NSDistributedNotificationCenter
*)notificationCenterForType:(NSString
*)type
NSLocalNotificationCenterType
,
is supported.- (void)addObserver:(id)anObserver
selector:(SEL)aSelector
name:(NSString *)notificationName
object:(NSString *)anObject
This
method calls addObserver:selector:name:object:suspensionBehavior: with
a suspensionBehavior: argument of NSNotificationSuspensionBehaviorCoalesce
(described
in "Constants" ).
- (void)addObserver:(id)anObserver
selector:(SEL)aSelector
name:(NSString *)notificationName
object:(NSString *)anObject
suspensionBehavior:(NSNotificationSuspensionBehavior)suspensionBehavior
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 (further described
in "Constants" ):
NSNotificationSuspensionBehaviorDrop
NSNotificationSuspensionBehaviorCoalesce
NSNotificationSuspensionBehaviorHold
NSNotificationSuspensionBehaviorDeliverImmediately
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:
- (void)postNotificationName:(NSString
*)notificationName
object:(NSString *)anObject
This method invokes postNotificationName:object:userInfo:deliverImmediately: with
a userInfo:
argument
of nil
and a deliverImmediately:
argument
of NO
.
See Also: - postNotificationName:object:userInfo:
- (void)postNotificationName:(NSString
*)notificationName
object:(NSString *)anObject
userInfo:(NSDictionary *)userInfo
nil
.This method
invokes postNotificationName:object:userInfo:deliverImmediately: with
a deliverImmediately:
argument
of NO
.
See Also: - postNotificationName:object:
- (void)postNotificationName:(NSString
*)notificationName
object:(NSString *)anObject
userInfo:(NSDictionary *)userInfo
deliverImmediately:(BOOL)deliverImmediately
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)
- (void)removeObserver:(id)anObserver
name:(NSString *)notificationName
object:(NSString *)anObject
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.
- (void)setSuspended:(BOOL)suspended
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. NSApplication automatically suspends delivery
when the application is not active.See Also: - addObserver:selector:name:object:suspensionBehavior:, - postNotificationName:object:userInfo:deliverImmediately:, - suspended
- (BOOL)suspended
YES
if
the notification center is delivering notifications for this application
according to their suspension behavior, NO
if
it is delivering them immediately.See Also: - setSuspended: