Mac Developer Library

Developer

Core Foundation Framework Reference CFNotificationCenter Reference

Options
Deployment Target:

On This Page
Language:

CFNotificationCenter Reference

Inherits From

Not Applicable

Conforms To

Not Applicable

Import Statement

Objective-C

@import CoreFoundation;

Swift

import CoreFoundation

Availability

Not Applicable

A CFNotificationCenter object provides the means by which you can send a message, or notification, to any number of recipients, or observers, without having to know anything about the recipients. A notification message consists of a notification name (a CFString), a pointer value that identifies the object posting the notification, and an optional dictionary that contains additional information about the particular notification.

To register as an observer of a notification, you call CFNotificationCenterAddObserver, providing an identifier for your observer, the callback function that should be called when the notification is posted, and the name of the notification and the object in which you are interested. The observer identifier is passed back to the callback function, along with the notification information. You can use the identifier to distinguish multiple observers using the same callback function. The identifier is also used to unregister the observer with CFNotificationCenterRemoveObserver and CFNotificationCenterRemoveEveryObserver.

To send a notification, you call CFNotificationCenterPostNotification, passing in the notification information. The notification center then looks up all the observers that registered for this notification and sends the notification information to their callback functions.

There are three types of CFNotificationCenter—a distributed notification center, a local notification center, and a Darwin notification center—an application may have at most one of each type. The distributed notification is obtained with CFNotificationCenterGetDistributedCenter. A distributed notification center delivers notifications between applications. In this case, the notification object must always be a CFString object and the notification dictionary must contain only property list values. The local and Darwin notification centers are available in OS X version 10.4 and later, and obtained using CFNotificationCenterGetLocalCenter and CFNotificationCenterGetDarwinNotifyCenter respectively.

Unlike some other Core Foundation opaque types with names similar to a Cocoa Foundation class (such as CFString and NSString), CFNotificationCenter objects cannot be cast (“toll-free bridged”) to NSNotificationCenter objects or vice-versa.

Functions

Accessing a Notification Center
  • CFNotificationCenterGetDarwinNotifyCenter() CFNotificationCenterGetDarwinNotifyCenter

    Returns the application’s Darwin notification center.

    Declaration

    Swift

    func CFNotificationCenterGetDarwinNotifyCenter() -> CFNotificationCenter!

    Objective-C

    CFNotificationCenterRef CFNotificationCenterGetDarwinNotifyCenter ( void );

    Return Value

    The application’s Darwin notification center.

    Discussion

    This notification center is used to cover the <notify.h> Core OS notification mechanism (see /usr/include/notify.h). An application has only one Darwin notification center, so this function returns the same value each time it is called.

    The Darwin Notify Center has no notion of per-user sessions, all notifications are system-wide. As with distributed notifications, the main thread's run loop must be running in one of the common modes (usually kCFRunLoopDefaultMode) for Darwin-style notifications to be delivered.

    Availability

    Available in OS X v10.4 and later.

  • CFNotificationCenterGetDistributedCenter() CFNotificationCenterGetDistributedCenter

    Returns the application’s distributed notification center.

    Declaration

    Swift

    func CFNotificationCenterGetDistributedCenter() -> CFNotificationCenter!

    Objective-C

    CFNotificationCenterRef CFNotificationCenterGetDistributedCenter ( void );

    Return Value

    The application’s distributed notification center. An application has only one distributed notification center, so this function returns the same value each time it is called.

    Discussion

    A distributed notification center delivers notifications between applications. A notification object used with a distributed notification center must always be a CFString object and the notification dictionary must contain only property list values.

    Availability

    Available in OS X v10.0 and later.

  • CFNotificationCenterGetLocalCenter() CFNotificationCenterGetLocalCenter

    Returns the application’s local notification center.

    Declaration

    Swift

    func CFNotificationCenterGetLocalCenter() -> CFNotificationCenter!

    Objective-C

    CFNotificationCenterRef CFNotificationCenterGetLocalCenter ( void );

    Return Value

    The application’s local notification center. An application has only one local notification center, so this function returns the same value each time it is called.

    Availability

    Available in OS X v10.4 and later.

Posting a Notification
  • CFNotificationCenterPostNotification(_:_:_:_:_:) CFNotificationCenterPostNotification

    Posts a notification for an object.

    Declaration

    Swift

    func CFNotificationCenterPostNotification(_ center: CFNotificationCenter!, _ name: CFString!, _ object: UnsafePointer<Void>, _ userInfo: CFDictionary!, _ deliverImmediately: Bool)

    Objective-C

    void CFNotificationCenterPostNotification ( CFNotificationCenterRef center, CFStringRef name, const void *object, CFDictionaryRef userInfo, Boolean deliverImmediately );

    Parameters

    center

    The notification center to post the notification.

    name

    The name of the notification to post. This value must not be NULL.

    object

    The object posting the notification. If NULL, the notification is sent only to observers that are observing all objects. In other words, only observers that registered for the notification with a NULL value for object will receive the notification.

    If you want to allow your clients to register for notifications using Cocoa APIs (see NSNotificationCenter Class Reference), then object must be a Core Foundation or Cocoa object.

    For distributed notifications, object must be a CFString object.

    If center is a Darwin notification center, this value is ignored.

    userInfo

    A dictionary passed to observers. You populate this dictionary with additional information describing the notification. For distributed notifications, the dictionary must contain only property list objects. This value may be NULL.

    If center is a Darwin notification center, this value is ignored.

    deliverImmediately

    If true, the notification is delivered to all observers immediately, even if some observers are in suspended (background) applications and they requested different suspension behavior when registering for the notification. If false, each observer’s requested suspension behavior is respected.

    If center is a Darwin notification center, this value is ignored.

    Availability

    Available in OS X v10.0 and later.

  • CFNotificationCenterPostNotificationWithOptions(_:_:_:_:_:) CFNotificationCenterPostNotificationWithOptions

    Posts a notification for an object using specified options.

    Declaration

    Swift

    func CFNotificationCenterPostNotificationWithOptions(_ center: CFNotificationCenter!, _ name: CFString!, _ object: UnsafePointer<Void>, _ userInfo: CFDictionary!, _ options: CFOptionFlags)

    Objective-C

    void CFNotificationCenterPostNotificationWithOptions ( CFNotificationCenterRef center, CFStringRef name, const void *object, CFDictionaryRef userInfo, CFOptionFlags options );

    Parameters

    center

    The notification center to post the notification.

    name

    The name of the notification to post. This value must not be NULL.

    object

    The object posting the notification. If NULL, the notification is sent only to observers that are observing all objects. In other words, only observers that registered for the notification with a NULL value for object will receive the notification.

    If you want to allow your clients to register for notifications using Cocoa APIs (see NSNotificationCenter Class Reference), then object must be a Core Foundation or Cocoa object.

    For distributed notifications, object must be a CFString object.

    If center is a Darwin notification center, this value is ignored.

    userInfo

    A dictionary to pass to observers. You populate this dictionary with additional information describing the notification. For distributed notifications, the dictionary must contain only property list objects. Can be NULL.

    If center is a Darwin notification center, this value is ignored.

    options

    Specifies if the notification should be posted immediately, or to all sessions. See Notification Posting Options for possible values.

    If center is a Darwin notification center, this value is ignored.

    Availability

    Available in OS X v10.3 and later.

Adding and Removing Observers
  • CFNotificationCenterAddObserver(_:_:_:_:_:_:) CFNotificationCenterAddObserver

    Registers an observer to receive notifications.

    Declaration

    Swift

    func CFNotificationCenterAddObserver(_ center: CFNotificationCenter!, _ observer: UnsafePointer<Void>, _ callBack: CFNotificationCallback!, _ name: CFString!, _ object: UnsafePointer<Void>, _ suspensionBehavior: CFNotificationSuspensionBehavior)

    Objective-C

    void CFNotificationCenterAddObserver ( CFNotificationCenterRef center, const void *observer, CFNotificationCallback callBack, CFStringRef name, const void *object, CFNotificationSuspensionBehavior suspensionBehavior );

    Parameters

    center

    The notification center to which to add the observer.

    observer

    The observer. In OS X v10.3 and later, this parameter may be NULL.

    callBack

    The callback function to call when object posts the notification named name.

    name

    The name of the notification to observe. If NULL, callback is called for any notification posted by object.

    If center is a Darwin notification center, this value must not be NULL.

    object

    The object to observe. For distributed notifications, object must be a CFString object. If NULL, callback is called when a notification named name is posted by any object.

    If center is a Darwin notification center, this value is ignored.

    suspensionBehavior

    Flag indicating how notifications should be handled when the application is in the background. See Notification Delivery Suspension Behavior for the list of available values.

    If center is a Darwin notification center, this value is ignored.

    Discussion

    Notification delivery is registered for the main thread.

    If you need to control which thread processes a notification, your callback function must be able to forward the notification to the proper thread. You can use a CFMessagePort object or a custom CFRunLoopSource object to send notifications to the correct thread’s run loop.

    Availability

    Available in OS X v10.0 and later.

    See Also

    CFMessagePortRef
    CFRunLoopSourceRef

  • CFNotificationCenterRemoveEveryObserver(_:_:) CFNotificationCenterRemoveEveryObserver

    Stops an observer from receiving any notifications from any object.

    Declaration

    Swift

    func CFNotificationCenterRemoveEveryObserver(_ center: CFNotificationCenter!, _ observer: UnsafePointer<Void>)

    Objective-C

    void CFNotificationCenterRemoveEveryObserver ( CFNotificationCenterRef center, const void *observer );

    Parameters

    center

    The notification center from which to remove observers.

    observer

    The observer. This value must not be NULL.

    Discussion

    If you no longer want an observer to receive any notifications, perhaps because the observer is being deallocated, you can call this function to unregister the observer from all the notifications for which it had previously registered.

    Availability

    Available in OS X v10.0 and later.

  • CFNotificationCenterRemoveObserver(_:_:_:_:) CFNotificationCenterRemoveObserver

    Stops an observer from receiving certain notifications.

    Declaration

    Swift

    func CFNotificationCenterRemoveObserver(_ center: CFNotificationCenter!, _ observer: UnsafePointer<Void>, _ name: CFString!, _ object: UnsafePointer<Void>)

    Objective-C

    void CFNotificationCenterRemoveObserver ( CFNotificationCenterRef center, const void *observer, CFStringRef name, const void *object );

    Parameters

    center

    The notification center to modify.

    observer

    The observer. This value must not be NULL.

    name

    The name of the notification to stop observing. If NULL, observer stops receiving callbacks for all notifications posted by object.

    object

    The object to stop observing. For distributed notifications, object must be a CFString object. If NULL, observer stops receiving callbacks for all objects posting notifications named name.

    If center is a Darwin notification center, this value is ignored.

    Discussion

    If both name and object are NULL, this function unregisters observer from all the notifications for which it had previously registered with center.

    Availability

    Available in OS X v10.0 and later.

Getting the CFNotificationCenter Type ID

Callbacks

CFNotificationCenter Miscellaneous Callbacks
  • CFNotificationCallback CFNotificationCallback

    Callback function invoked for each observer of a notification when the notification is posted.

    Declaration

    Swift

    typealias CFNotificationCallback = (CFNotificationCenter!, UnsafeMutablePointer<Void>, CFString!, UnsafePointer<Void>, CFDictionary!) -> Void

    Objective-C

    typedef void (*CFNotificationCallback) ( CFNotificationCenterRef center, void *observer, CFStringRef name, const void *object, CFDictionaryRef userInfo );

    Parameters

    center

    The notification center handling the notification.

    observer

    An arbitrary value, other than NULL, that identifies the observer.

    name

    The name of the notification being posted.

    object

    An arbitrary value that identifies the object posting the notification. For distributed notifications, object is always a CFString object. This value could be NULL.

    userInfo

    A dictionary containing additional information regarding the notification. This value could be NULL.

    If the notification center is a Darwin notification center, this value must be ignored.

    Availability

    Available in OS X v10.0 and later.

Data Types

Miscellaneous

  • CFNotificationCenterRef CFNotificationCenterRef

    The type of a reference to a CFNotificationCenter.

    Declaration

    Swift

    typealias CFNotificationCenterRef = CFNotificationCenter

    Objective-C

    typedef struct *CFNotificationCenterRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Constants

Miscellaneous

  • CFNotificationSuspensionBehavior

    Suspension flags that indicate how distributed notifications should be handled when the receiving application is in the background.

    Declaration

    Swift

    enum CFNotificationSuspensionBehavior : CFIndex { case Drop case Coalesce case Hold case DeliverImmediately }

    Objective-C

    enum CFNotificationSuspensionBehavior { CFNotificationSuspensionBehaviorDrop = 1, CFNotificationSuspensionBehaviorCoalesce = 2, CFNotificationSuspensionBehaviorHold = 3, CFNotificationSuspensionBehaviorDeliverImmediately = 4 }; typedef enum CFNotificationSuspensionBehavior CFNotificationSuspensionBehavior;

    Constants

    • Drop

      CFNotificationSuspensionBehaviorDrop

      The server will not queue any notifications of the specified name and object while the receiving application is in the background.

      Available in OS X v10.0 and later.

    • Coalesce

      CFNotificationSuspensionBehaviorCoalesce

      The server will only queue the last notification of the specified name and object; earlier notifications are dropped.

      Available in OS X v10.0 and later.

    • Hold

      CFNotificationSuspensionBehaviorHold

      The server will hold 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

      CFNotificationSuspensionBehaviorDeliverImmediately

      The server will deliver notifications of the specified name and object whether or not the application is in the background. When a notification with this suspension behavior is matched, it has the effect of first flushing any queued notifications.

      Available in OS X v10.0 and later.

    Discussion

    An application selects the suspension behavior for a given notification when it registers an observer for that notification with CFNotificationCenterAddObserver.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Notification Posting Options

    Possible options when posting notifications.

    Declaration

    Swift

    var kCFNotificationDeliverImmediately: CFOptionFlags { get } var kCFNotificationPostToAllSessions: CFOptionFlags { get }

    Objective-C

    enum { kCFNotificationDeliverImmediately = (1 << 0), kCFNotificationPostToAllSessions = (1 << 1) };

    Constants

    • kCFNotificationDeliverImmediately

      kCFNotificationDeliverImmediately

      Delivers the notification immediately.

      Available in OS X v10.3 and later.

    • kCFNotificationPostToAllSessions

      kCFNotificationPostToAllSessions

      Delivers the notification to all sessions.

      Available in OS X v10.3 and later.

    Discussion

    Use these constants when calling the CFNotificationCenterPostNotificationWithOptions function.

Copyright © 2015 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2013-08-08