Previous Contents Index Next |
Sun ONE Messaging and Collaboration Event Notification Service Manual |
Chapter 2 Event Notification Service C API Reference
This chapter details the ENS C API; it is divided into three main sections:
Publisher API
Publisher API Functions List
This chapter includes a description of the following Publisher functions, listed in Table 2-1:
Subscriber API Functions List
This chapter includes a description of following Subscriber functions, listed in Table 2-2:
Publish and Subscribe Dispatcher Functions List
This chapter includes a description of the following Publish and Subscribe Dispatcher functions, listed in Table 2-3:
The Publisher API consists of one definition and nine functions:
publisher_t
Syntax
typedef struct enc_struct publisher_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);
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);
Returns
Nothing. It passes the new active publisher as third argument of cbdone callback.
Purpose
Creates a new synchronous publisher.
Syntax
publisher_t *publisher_new_s (pas_dispatcher_t *disp,
void *worker,
const char *host,
unsigned short port);
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.
Returns
A new active publisher (publisher_t).
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);
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);
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.
Purpose
Terminates a publish session.
Syntax
void publisher_delete (publisher_t *publisher);
Purpose
Creates a subscriber using the credentials of the publisher.
Syntax
struct subscriber_struct * publisher_get_subscriber(publisher_t *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.
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);
The unique RENL identifier. This allows two peers to be able to set up multiple RENLs between them.
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);
The Subscriber API includes two definitions and ten functions:
subscriber_t
Syntax
typedef struct enc_struct subscriber_t;
Syntax
typedef struct subscription_struct subscription_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);
Purpose
Subscriber callback; called upon receipt of a notification.
Syntax
typedef void (*subscriber_notify_cb_t) (void *arg,
char *event,
char *data,
int datalen);
The event reference (URI). The notification event reference matches the subscription, but may contain additional information called event attributes, such as a uid.
Returns
Zero if successful, non-zero otherwise.
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);
Returns
Nothing. It passes the new active subscriber as third argument of cbdone callback.
Purpose
Creates a new synchronous subscriber.
Syntax
subscriber_t *subscriber_new_s (pas_dispatcher_t *disp,
const char *host,
unsigned short port);
Returns
A new active subscriber (subscriber_t).
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):
Cancels an asynchronous subscription.
Syntax
void unsubscribe_a (subscriber_t *subscriber,
subscription_t *subscription,
subscriber_cb_t cbdone,
void *cbarg);
Called when an unsubscribe completes. It has three parameters:
Purpose
Terminates a subscriber.
Syntax
void subscriber_delete (subscriber_t *subscriber);
Purpose
Creates a publisher, using the credentials of the subscriber.
Syntax
struct publisher_struct *subscriber_get_publisher (subscriber_t *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.
Purpose
Creates the subscription part of an RENL.
Syntax
renl_t *renl_create_subscriber (subscription_t *subscription,
const char *renl_id,
const char *publisher);
The unique RENL identifier. This allows two peers to be able to set up multiple RENLs between them.
Returns
The opaque RENL object.
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);
Publish and Subscribe Dispatcher API
The Publish and Subscribe Dispatcher API includes one definition and four functions:
Purpose
A publish and subscribe dispatcher.
Syntax
typedef struct pas_dispatcher_struct pas_dispatcher_t;
Purpose
Creates or advertises a dispatcher.
Syntax
pas_dispatcher_t *pas_dispatcher_new (void *disp);
The dispatcher context. If NULL,to start dispatching notifications, the application must call pas_dispatch.
Returns
The dispatcher to use when creating publishers or subscribers (pas_dispatcher_t).
Purpose
Destroys a dispatcher created with pas_dispatcher_new.
Syntax
void pas_dispatcher_delete (pas_dispatcher_t *disp);
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);
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);
Previous Contents Index Next
Copyright 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated August 30, 2002