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.