Mac Developer Library

Developer

Foundation Framework Reference NSDistributedNotificationCenter Class Reference

Options
Deployment Target:

On This Page
Language:

NSDistributedNotificationCenter

Class at a Glance

The NSDistributedNotificationCenter class 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 distributed notification center.

The NSDistributedNotificationCenter class implements a notification center that can distribute notifications asynchronously to tasks other than the one in which the notification was posted. An instance of this class are known as a distributed notification center.

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. Currently there is a single type—NSLocalNotificationCenterType. This type of distributed notification center handles notifications that can be sent between tasks on a single computer. For communication between tasks on different computers, use Distributed Objects Programming Topics.

Posting a distributed notification is an expensive operation. The notification gets sent to a system-wide server that 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, when too many notifications are posted and the server’s queue fills up, notifications may 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 NSDefaultRunLoopMode, to receive a distributed notification. For multithreaded applications running in OS X v10.3 and later, distributed notifications are always delivered to the main thread. For multithreaded applications running in 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.

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.0 and later.
  • Returns the default distributed notification center, representing the local notification center for the computer.

    Declaration

    Swift

    class func defaultCenter() -> NSDistributedNotificationCenter

    Objective-C

    + (NSDistributedNotificationCenter *)defaultCenter

    Return Value

    Default distributed notification center for the computer.

    Discussion

    This method calls notificationCenterForType: with an argument of NSLocalNotificationCenterType.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the distributed notification center for a particular notification center type.

    Declaration

    Swift

    class func notificationCenterForType(_ notificationCenterType: String) -> NSDistributedNotificationCenter

    Objective-C

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

    Parameters

    notificationCenterType

    Notification center type being inquired about.

    Return Value

    Distributed notification center for notificationCenterType.

    Discussion

    Currently only one type, NSLocalNotificationCenterType, is supported.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Adds an entry to the receiver’s dispatch table with an observer, a notification selector and optional criteria: notification name and sender.

    Declaration

    Swift

    func addObserver(_ notificationObserver: AnyObject, selector notificationSelector: Selector, name notificationName: String?, object notificationSender: String?)

    Objective-C

    - (void)addObserver:(id)notificationObserver selector:(SEL)notificationSelector name:(NSString *)notificationName object:(NSString *)notificationSender

    Parameters

    notificationObserver

    Object registering as an observer. Must not be nil.

    notificationSelector

    Selector that specifies the message the receiver sends notificationObserver to notify it of the notification posting. Must not be 0.

    notificationName

    The name of the notification for which to register the observer; that is, only notifications with this name are delivered to the observer. When nil, the notification center doesn’t use a notification’s name to decide whether to deliver it to the observer.

    notificationSender

    The object whose notifications the observer wants to receive; that is, only notifications sent by this sender are delivered to the observer. When nil, the notification center doesn’t use a notification’s sender to decide whether to deliver it to the observer.

    Discussion

    This method calls addObserver:selector:name:object:suspensionBehavior: with suspensionBehavior:NSNotificationSuspensionBehaviorCoalesce (described in Constants).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Adds an entry to the receiver’s dispatch table with a specific observer and suspended-notifications behavior, and optional notification name and sender.

    Declaration

    Swift

    func addObserver(_ notificationObserver: AnyObject, selector notificationSelector: Selector, name notificationName: String?, object notificationSender: String?, suspensionBehavior suspendedDeliveryBehavior: NSNotificationSuspensionBehavior)

    Objective-C

    - (void)addObserver:(id)notificationObserver selector:(SEL)notificationSelector name:(NSString *)notificationName object:(NSString *)notificationSender suspensionBehavior:(NSNotificationSuspensionBehavior)suspendedDeliveryBehavior

    Parameters

    notificationObserver

    Object registering as an observer. Must not be nil.

    notificationSelector

    Selector that specifies the message the receiver sends notificationObserver to notify it of the notification posting. Must not be 0.

    notificationName

    The name of the notification for which to register the observer; that is, only notifications with this name are delivered to the observer. When nil, the notification center doesn’t use a notification’s name to decide whether to deliver it to the observer.

    notificationSender

    The object whose notifications the observer wants to receive; that is, only notifications sent by this sender are delivered to the observer. When nil, the notification center doesn’t use a notification’s sender to decide whether to deliver it to the observer.

    suspendedDeliveryBehavior

    Notification posting behavior when notification delivery is suspended.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Removes matching entries from the receiver’s dispatch table.

    Declaration

    Swift

    func removeObserver(_ notificationObserver: AnyObject?, name notificationName: String?, object notificationSender: String?)

    Objective-C

    - (void)removeObserver:(id)notificationObserver name:(NSString *)notificationName object:(NSString *)notificationSender

    Parameters

    notificationObserver

    Observer to remove from the dispatch table. Specify an observer to remove only entries for this observer. When nil, the receiver does not use notification observers as criteria for removal.

    notificationName

    Name of the notification to remove from dispatch table. Specify a notification name to remove only entries that specify this notification name. When nil, the receiver does not use notification names as criteria for removal.

    notificationSender

    Sender to remove from the dispatch table. Specify a notification sender to remove only entries that specify this sender. When nil, the receiver does not use notification senders as criteria for removal.

    Discussion

    Be sure to invoke this method with notificationName:nil notificationSender:nil (or removeObserver:) before deallocating the observer object.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether notification delivery is suspended.

    Declaration

    Swift

    var suspended: Bool

    Objective-C

    @property BOOL suspended

    Return Value

    YEStrue when notification delivery is suspended, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Suspends or resumes notification delivery.

    Declaration

    Swift

    var suspended: Bool

    Objective-C

    @property BOOL suspended

    Parameters

    suspended

    YEStrue suspends notification delivery, NOfalse resumes it.

    Discussion

    See NSNotificationSuspensionBehavior for details on how the receiver delivers notifications to their observers when normal notification delivery is suspended.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

Data Types

  • These constants specify the types of notification delivery suspension behaviors.

    Declaration

    Swift

    enum NSNotificationSuspensionBehavior : UInt { case Drop case Coalesce case Hold case DeliverImmediately }

    Objective-C

    typedef enum { NSNotificationSuspensionBehaviorDrop = 1, NSNotificationSuspensionBehaviorCoalesce = 2, NSNotificationSuspensionBehaviorHold = 3, NSNotificationSuspensionBehaviorDeliverImmediately = 4 } NSNotificationSuspensionBehavior;

    Constants

    • Drop

      NSNotificationSuspensionBehaviorDrop

      The server does not queue any notifications with this name and object until setSuspended: with an argument of NOfalse is called.

      Available in OS X v10.0 and later.

    • Coalesce

      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.

      Available in OS X v10.0 and later.

    • Hold

      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.

      Available in OS X v10.0 and later.

    • DeliverImmediately

      NSNotificationSuspensionBehaviorDeliverImmediately

      The server delivers notifications matching this registration irrespective of whether setSuspended: with an argument of YEStrue 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 NOfalse were first called if the application is suspended, followed by the notification in question being delivered, followed by a transition back to the previous suspended or unsuspended state.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • This constant specifies the notification center type.

    Declaration

    Swift

    let NSLocalNotificationCenterType: NSString!

    Objective-C

    FOUNDATION_EXPORT NSString * const NSLocalNotificationCenterType;

    Constants

    • NSLocalNotificationCenterType

      NSLocalNotificationCenterType

      Distributes notifications to all tasks on the sender’s computer.

      Available in OS X v10.0 and later.

  • These constants specify the behavior of notifications posted using the postNotificationName:object:userInfo:options: method.

    Declaration

    Swift

    var NSNotificationDeliverImmediately: Int { get } var NSNotificationPostToAllSessions: Int { get }

    Objective-C

    enum { NSNotificationDeliverImmediately = (1 << 0), NSNotificationPostToAllSessions = (1 << 1) };

    Constants

    • NSNotificationDeliverImmediately

      NSNotificationDeliverImmediately

      When set, the notification is delivered immediately to all observers, regardless of their suspension behavior or suspension state. When not set, allows the normal suspension behavior of notification observers to take place.

      Available in OS X v10.3 and later.

    • NSNotificationPostToAllSessions

      NSNotificationPostToAllSessions

      When set, the notification is posted to all sessions. When not set, the notification is sent only to applications within the same login session as the posting task.

      Available in OS X v10.3 and later.