Chapter 2 Event Notification Service C API Reference

This chapter details the ENS C API; it is divided into three main sections:

• Publisher API

• Unreliable Publisher API

• Subscriber API

• Publish and Subscribe Dispatcher API

Publisher API Functions List

This chapter includes a description of the following Publisher functions, listed in Table 2–1:

Table 2–1 ENS Publisher API Functions List

Function	Description
publisher_t	Definition for a publisher.
publisher_cb_t	Generic callback function acknowledging an asynchronous call.
publisher_new_a	Creates a new asynchronous publisher.
publisher_new_s	Creates a new synchronous publisher.
publish_a	Sends an asynchronous notification to the notification service.
publish_s	Sends a synchronous notification to the notification service.
publisher_delete	Terminates a publish session.
publisher_get_subscriber	Creates a subscriber using the publisher’s credentials.
renl_create_publisher	Creates an RENL, which enables the invocation of end2end_ack.
renl_cancel_publisher	Cancels an RENL.

Unreliable Publisher API

This chapter includes a description of the following Unreliable Publisher functions, listed in Table 2–2:

Table 2–2 ENS Unreliable Publisher API Functions List

Function	Description
upub_t	Definition for an unreliable publisher.
upub_publish	Sends a notification.
upub_init	Creates the publisher.
upub_shutdown	Shuts down and frees the publisher.

Subscriber API Functions List

This chapter includes a description of following Subscriber functions, listed in Table 2–3:

Table 2–3 ENS Subscriber API Functions List

Function	Description
subscriber_t	Definition of a subscriber.
subscription_t	Definition of a subscription.
subscriber_cb_t	Generic callback function acknowledging an asynchronous call.
subscriber_notify_cb_t	Synchronous callback; called upon receipt of a notification.
subscriber_new_a	Creates a new asynchronous subscriber.
subscriber_new_s	Creates a new synchronous subscriber.
subscribe_a	Establishes an asynchronous subscription.
unsubscribe_a	Cancels an asynchronous subscription.
subscriber_delete	Terminates a subscriber.
subscriber_get_publisher	Creates a publisher using the subscriber’s credentials.
renl_create_subscriber	Creates the subscription part of the RENL.
renl_cancel_subscriber	Cancels an RENL.

Publish and Subscribe Dispatcher Functions List

This chapter includes a description of the following Publish and Subscribe Dispatcher functions, listed in Table 2–4:

Table 2–4 ENS Publish and Subscribe Dispatcher Functions List

Function	Description
pas_dispatcher_t	Definition of a publish and subscribe dispatcher.
pas_dispatcher_new	Creates a dispatcher.
pas_dispatcher_delete	Destroys a dispatcher created with pas_dispatcher_new.
pas_dispatch	Starts the dispatch loop of an event notification environment.
pas_shutdown	Stops the dispatch loop on an event notification environment started with pas_dispatch.

Publisher API

The Publisher API consists of one definition and nine functions:

• publisher_t

• publisher_cb_t

• publisher_new_a

• publisher_new_s

• publish_a

• publish_s

• publisher_delete

• publisher_get_subscriber

• renl_create_publisher

• renl_cancel_publisher

publisher_t

Purpose.

A publisher.

Syntax

typedef struct enc_struct publisher_t;

Parameters

None.

Returns

Nothing.

publisher_cb_t

Purpose.

Generic callback function invoked by ENS to acknowledge an asynchronous call.

Syntax

typedef void (*publisher_cb_t) (void *arg, int rc, void *data);

Parameters

arg	Context variable passed by the caller.
rc	The return code.
data	For an open, contains a newly created context.

Returns

Nothing.

publisher_new_a

Purpose

Creates a new asynchronous publisher.

Syntax

void publisher_new_a (pas_dispatcher_t *disp,
                      void *worker,
                      const char *host,
                      unsigned short port,
                      publisher_cb_t cbdone,
                      void *cbarg);

Parameters

disp	P&S thread pool context returned by pas_dispatcher_new.
worker	Application worker. If not NULL, grouped with existing workers created by ENS to service this publisher session. Used to prevent multiple threads from accessing the publisher data at the same time.
host	Notification server host name.
port	Notification server port.
cbdone	The callback invoked when the publisher has been successfully created, or could not be created. There are three Parameters to cbdone: cbarg The first argument. A status code. If non-zero, the publisher could not be created; value specifies cause of the failure. The new active publisher.
cbarg	First argument of cbdone.

Returns

Nothing. It passes the new active publisher as third argument of cbdone callback.

publisher_new_s

Purpose

Creates a new synchronous publisher.

Syntax

publisher_t *publisher_new_s (pas_dispatcher_t *disp,
                              void *worker,
                              const char *host,
                              unsigned short port);

Parameters

disp	P&S thread pool context returned by pas_dispatcher_new.
worker	Application worker. If not NULL, grouped with existing workers created by ENS to service this publisher session. Used to prevent multiple threads from accessing the publisher data at the same time.
host	Notification server host name.
port	Notification server port.

Returns

A new active publisher (publisher_t).

publish_a

Purpose

Sends an asynchronous notification to the notification service.

Syntax

void publish_a (publisher_t *publisher,
                const char *event_ref,
                const char *data,
                unsigned int datalen,
                publisher_cb_t cbdone,
                publisher_cb_t end2end_ack,
                void *cbarg,
                unsigned long timeout);

Parameters

publisher_t	The active publisher.
event_ref	The event reference. This is a URI identifying the modified resource.
data	The event data. The body of the notification message. It is opaque to the notification service, which merely relays it to the events’ subscriber.
datalen	The length in bytes of the data.
cbdone	The callback invoked when the data has been accepted or deemed unacceptable by the notification service. What makes a notification acceptable depends on the protocol used. The protocol may choose to use the transport acknowledgment (TCP) or use its own acknowledgment response mechanism.
end2end_ack	The callback function invoked after acknowledgment from the consumer peer (in an RENL) has been received. Used only in the context of an RENL.
cbarg	The first argument of cbdone or end2end_ack when invoked.
timeout	The length of time to wait for an RENL to complete.

Returns

Nothing.

publish_s

Purpose

Sends a synchronous notification to the notification service.

Syntax

int publish_s (publisher_t *publisher,
               const char *event_ref,
               const char *data,
               unsigned int datalen);

Parameters

publisher	The active publisher.
event_ref	The event reference. This is a URI identifying the modified resource.
data	The event data. The body of the notification message. It is opaque to the notification service, which relays it to the events’ subscriber.
datalen	The length in bytes of the data.

Returns

Zero if successful; a failure code if unsuccessful. If an RENL, the call does not return until the consumer has completely processed the notification and has successfully acknowledged it.

publisher_delete

Purpose

Terminates a publish session.

Syntax

void publisher_delete (publisher_t *publisher);

Parameters

publisher

The publisher to delete.

Returns

Nothing.

publisher_get_subscriber

Purpose

Creates a subscriber using the credentials of the publisher.

Syntax

struct subscriber_struct * publisher_get_subscriber(publisher_t *publisher);

Parameters

publisher

The publisher whose credentials are used to create the subscriber.

Returns

The subscriber, or NULL if the creation failed. If the creation failed, use the subscriber_new to create the subscriber.

renl_create_publisher

Purpose

Declares an RENL, which enables the end2end_ack invocation. After this call returns, the end2end_ack argument is invoked when an acknowledgment notification matching the specified publisher and subscriber is received.

Syntax

void renl_create_publisher (publisher_t *publisher,
                             const char *renl_id,
                            const char *subscriber,
                            publisher_cb_t cbdone,
                            void *cbarg);

Parameters

publisher	The active publisher.
renl_id	The unique RENL identifier. This allows two peers to be able to set up multiple RENLs between them.
subscriber	The authenticated identity of the peer.
cbdone	The callback invoked when the RENL is established.
cbarg	The first argument of cbdone, when invoked.

Returns

Nothing.

renl_cancel_publisher

Purpose

This cancels an RENL. This does not prevent more notifications being sent, but should a client acknowledgment be received, the end2end_ack argument of publish will no longer be invoked. All RENLs are automatically destroyed when the publisher is deleted. Therefore, this function does not need to be called to free RENL-related memory before deleting a publisher.

Syntax

void renl_cancel_publisher (renl_t *renl);

Parameters

renl	The RENL to cancel.

Returns

Nothing.

Unreliable Publisher API

The Unreliable Publisher (upub) API consists of the following functions:

• upub_t

• upub_publish

• upub_init

• upub_shutdown

upub_t

Purpose

Defines an unreliable publisher type.

Syntax

typedef struct upub_struct upub_t;

Parameters

None.

Returns

Nothing.

upub_publish

Purpose

Sends a notification.

Syntax

void upub_publish (upub_t *upub,
                              const char *event_ref,
                              void *payload,
                              unsigned int payload_len,
                              void (*delete_payload) (void *));

Parameters

upub	Publisher.
event_ref	Event reference. This is a URI identifying the resource that is modifed.
payload	Notification payload.
payload_len	Length in bytes of the payload.
delete_payload	Callback to free the payload when it is no longer needed.

Returns

Nothing.

upub_init

Purpose

Creates the publisher.

This function allocates the upub object and sets up the thread dispatcher. The thread dispatcher can be provided by the application if the application already has one. This will have the advantage of not creating a thread dedicated to this API.

Note: If a connection-based transport is used, the connection to the notification service is not set up here. This is deferred to the first time a notification is actually published.

Syntax

upub_t *upub_init(void *gdc,
                             const char *host, unisgned short port,
                             int num_workers);

Parameters

gdc	GDisp context (thread dispatcher).
host	Notification server host name.
port	Notification server port.
num_workers	Number of parallel sessions.

Returns

The upub ready to be used.

upub_shutdown

Purpose

Shuts down and frees the publisher.

Syntax

void upub_shutdown(upub_t *upub);

Parameters

upub

Publisher.

Returns

Nothing.

Subscriber API

The Subscriber API includes two definitions and ten functions:

• subscriber_t

• subscription_t

• subscriber_cb_t

• subscriber_notify_cb_t

• subscriber_new_a

• subscriber_new_s

• subscribe_a

• unsubscribe_a

• subscriber_delete

• subscriber_get_publisher

• renl_create_subscriber

• renl_cancel_subscriber

subscriber_t

Purpose

A subscriber.

Syntax

typedef struct enc_struct subscriber_t;

Parameters

None.

Returns

Nothing.

subscription_t

Purpose

A subscription.

Syntax

typedef struct subscription_struct subscription_t;

Parameters

None.

Returns

Nothing.

subscriber_cb_t

Purpose

Generic callback function invoked by ENS to acknowledge an asynchronous call.

Syntax

typedef void (*subscriber_cb_t) (void *arg,
                                 int rc,
                                 void *data);

Parameters

arg	Context variable passed by the caller.
rc	The return code.
data	For an open, contains a newly created context.

Returns

Nothing

subscriber_notify_cb_t

Purpose

Subscriber callback; called upon receipt of a notification.

Syntax

typedef void (*subscriber_notify_cb_t) (void *arg,
                                        char *event,
                                        char *data,
                                        int datalen);

Parameters

arg	Context pointer passed to subscribe (notify_arg).
event	The event reference (URI). The notification event reference matches the subscription, but may contain additional information called event attributes, such as a uid.
data	The body of the notification. A MIME object.
datalen	Length of the data.

Returns

Zero if successful, non-zero otherwise.

subscriber_new_a

Purpose

Creates a new asynchronous subscriber.

Syntax

void subscriber_new_a (pas_dispatcher_t *disp,
                       void *worker,
                       const char *host,
                       unsigned short port,
                       subscriber_cb_t cbdone,
                       void *cbarg);

Parameters

disp	Thread dispatcher context returned by pas_dispatcher_new.
worker	Application worker. If not NULL, grouped with existing workers created by ENS to service this subscriber session. Used to prevent multiple threads from accessing the subscriber data at the same time. Only usable if the caller creates and dispatches the GDisp context.
host	Notification server host name or IP address.
port	Subscription service port number.
cbdone	The callback invoked when the subscriber session becomes active and subscriptions can be issued. There are three parameters to cbdone: cbarg The first argument. A status code. If non-zero, the subscriber could not be created; value specifies cause of the failure. The new active subscriber (subscriber_t).
cbarg	First argument of cbdone.

Returns

Nothing. It passes the new active subscriber as third argument of cbdone callback.

subscriber_new_s

Purpose

Creates a new synchronous subscriber.

Syntax

subscriber_t *subscriber_new_s (pas_dispatcher_t *disp,
                                const char *host,
                                unsigned short port);

Parameters

disp	Publish and subscribe dispatcher returned by pas_dispatcher_new.
worker	Application worker. If not NULL, grouped with existing workers created by ENS to service this publisher session. Used to prevent multiple threads from accessing the publisher data at the same time. Only usable if the caller creates and dispatches the GDisp context.
host	Notification server host name or IP address.
port	Subscription service port number.

Returns

A new active subscriber (subscriber_t).

subscribe_a

Purpose

Establishes an asynchronous subscription.

Syntax

void subscribe_a (subscriber_t *subscriber,
                  const char *event_ref,
                  subscriber_notify_cb_t notify_cb,
                  void *notify_arg,
                  subscriber_cb_t cbdone,
                  void *cbarg):

Parameters

subscriber	The subscriber.
event_ref	The event reference. This is a URI identifying the event’s source.
notify_cb	The callback invoked upon receipt of a notification matching this subscription.
notify_arg	The first argument of notify_arg. May be called at any time, by any thread, while the subscription is still active.
cbdone	Called when an unsubscribe completes. It has three Parameters: cbarg (see below). Status code. A pointer to an opaque subscription object.
cbarg	The first argument of cbdone.

Returns

Nothing.

unsubscribe_a

Purpose

Cancels an asynchronous subscription.

Syntax

void unsubscribe_a (subscriber_t *subscriber,
                    subscription_t *subscription,
                    subscriber_cb_t cbdone,
                    void *cbarg);

Parameters

subscriber	The disappearing subscriber.
subscription	The subscription to cancel.
cbdone	Called when an unsubscribe completes. It has three parameters: cbarg (see below). Status code. A pointer to an opaque subscription object.
cbarg	The first argument of cbdone.

Returns

Nothing.

subscriber_delete

Purpose

Terminates a subscriber.

Syntax

void subscriber_delete (subscriber_t *subscriber);

Parameters

subscriber

The subscriber to delete.

Returns.

Nothing

subscriber_get_publisher

Purpose

Creates a publisher, using the credentials of the subscriber.

Syntax

struct publisher_struct *subscriber_get_publisher (subscriber_t  
*subscriber);

Parameters

subscriber

The subscriber whose credentials are used to create the publisher.

Returns

The publisher, or NULL if creation failed. In case the creation fails, use the publisher_new.

renl_create_subscriber

Purpose

Creates the subscription part of an RENL.

Syntax

renl_t *renl_create_subscriber (subscription_t *subscription,
                                const char *renl_id,
                                const char *publisher);

Parameters

subscription	The subscription.
renl_id	The unique RENL identifier. This allows two peers to be able to set up multiple RENLs between them.
publisher	The authenticated identity of the peer.

Returns

The opaque RENL object.

renl_cancel_subscriber

Purpose

This cancels an RENL. It does not cancel a subscription. It tells ENS not to acknowledge any more notifications received for this subscription. It destroys the RENL object, the application may no longer use this RENL. All RENLs are automatically destroyed when the subscription is canceled. Therefore, this function does not need to be called to free RENL-related memory before deleting a subscriber.

Syntax

void renl_cancel_subscriber (renl_t *renl);

Parameters

renl	The RENL to cancel.

Returns

Nothing.

Publish and Subscribe Dispatcher API

The Publish and Subscribe Dispatcher API includes one definition and four functions:

• pas_dispatcher_t

• pas_dispatcher_new

• pas_dispatcher_delete

• pas_dispatch

• pas_shutdown

---

Note –

The only thread dispatcher supported is GDisp (libasync).

---

pas_dispatcher_t

Purpose

A publish and subscribe dispatcher.

Syntax

typedef struct pas_dispatcher_struct pas_dispatcher_t;

Parameters

None.

Returns

Nothing.

pas_dispatcher_new

Purpose

Creates or advertises a dispatcher.

Syntax

pas_dispatcher_t *pas_dispatcher_new (void *disp);

Parameters

dispcx

The dispatcher context. If NULL,to start dispatching notifications, the application must call pas_dispatch. If not NULL, the dispatcher is a libasync dispatcher.

Returns

The dispatcher to use when creating publishers or subscribers (pas_dispatcher_t).

pas_dispatcher_delete

Purpose

Destroys a dispatcher created with pas_dispatcher_new.

Syntax

void pas_dispatcher_delete (pas_dispatcher_t *disp);

Parameters

disp	The event notification client environment.

Returns

Nothing.

pas_dispatch

Purpose

Starts the dispatch loop of an event notification environment. It has no effect if the application uses its own thread pool.

Syntax

void pas_dispatch (pas_dispatcher_t *disp);

Parameters

disp	The new dispatcher.

Returns

Nothing.

pas_shutdown

Purpose

Stops the dispatch loop of an event notification environment started with pas_dispatch. It has no effect if an application-provided dispatcher was passed to pas_dispatcher_new.

Syntax

void pas_shutdown (pas_dispatcher_t *disp);

Parameters

disp	The dispatcher context to shutdown.

Returns

Nothing.