ENS C API Overview

ENS implements the following three APIs:

• Publisher API

  A publisher sends notification of a subscribed-to event to ENS, which then distributes it to the subscribers. Optionally, in Calendar Server, the application can request acknowledgment of receipt of the notification. To do this, a Reliable Event Notification Link (RENL) is necessary. An RENL has a publisher, a subscriber, and a unique ID, which identify notifications that are subject to acknowledgment. The publisher informs the application of the receipt of an acknowledgment by invoking the end2end_ack callback passed to publish_a. Currently, only Calendar Server supports RENL.

• Unreliable Publisher API

  A publisher sends notification of an event to ENS, which distributes it to the subscribers. The term “unreliable” means that the API does not indicate whether a published event was successfully sent or received by a subscriber.

  This communication model is suitable for some applications, but not for others. If you are concerned about transfer reliability, use the full-blown publisher API (publisher.h) instead. However, the Unreliable Publisher API has the merit of being easier to use if transfer reliability is not a concern.

• Subscriber API

  A subscriber is a client to the notification service which expresses interest in particular events. When the notification service receives a notification about one of these events from a publisher, it relays the notification to the subscriber.

  A subscriber may also unsubscribe, which cancels an active subscription.

  In Calendar Server, to enable an RENL, the subscriber declares its existence to ENS, which then transparently generates notification acknowledgment on behalf of the subscriber application. The subscriber can revoke the RENL at any time.

• Publish and Subscribe Dispatcher API

  When an asynchronous publisher is used, ENS needs to borrow threads from a thread pool in order to invoke callbacks. The application can either choose to create its own thread pool and pass it to ENS, or it can let ENS create and manage its own thread pool. In either case, ENS creates and uses a dispatcher object to instantiate the dispatcher used (pas_dispatcher_t).

  GDisp (libasync) is the dispatcher supported.