Sun ONE Messaging and Collaboration 6.0 Event Notification Service Manual |
Chapter 2
Event Notification Service C API ReferenceThis chapter details the ENS C API; it is divided into three main sections:
Publisher API Functions ListThis chapter includes a description of the following Publisher functions, listed in Table 2-1:
Subscriber API Functions ListThis chapter includes a description of following Subscriber functions, listed in Table 2-2:
Publish and Subscribe Dispatcher Functions ListThis chapter includes a description of the following Publish and Subscribe Dispatcher functions, listed in Table 2-3:
Publisher APIThe 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
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
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
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
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
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
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
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
Returns
Nothing.
Subscriber APIThe 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
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
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
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
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
The first argument of cbdone.
Returns
Nothing.
subscriber_delete
Purpose
Terminates a subscriber.
Syntax
void subscriber_delete (subscriber_t *subscriber);
Parameters
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
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
Returns
Nothing.
Publish and Subscribe Dispatcher APIThe Publish and Subscribe Dispatcher API includes one definition and four functions:
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
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
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
Returns
Nothing.