Sun Java System Communications Services 6 2005Q4 Event Notification Service Guide

Chapter 2 Event Notification Service C API Reference

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

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. 

Subscriber API Functions List

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

Table 2–2 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–3:

Table 2–3 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

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.

Subscriber API

The Subscriber API includes two definitions and ten functions:

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:


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.