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

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.