Current Event Notification Service C API Reference

Skip to end of metadata
Go to start of metadata

Current Event Notification Service C API Reference

This information details the new ENS C API in Messaging Server 7 Update 4.

Topics:

API Overview

The ENS C API, ens.h, is located in the msg-server-base/examples/enssdk/ directory. The ens_pub.c sample publisher and ens_sub.c sample subscriber demonstrate use of the ENS C API.

Here is the API header (ens.h):

====
// ens.h -- ENS C client API
//
// Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.

# ifndef ENS_HEADER_INCLUDED
# define ENS_HEADER_INCLUDED 1

# ifdef __cplusplus
extern "C" {
# endif

//
// Connecting
//

// an ENS client
struct ensclient_t;
typedef struct ensclient_t ensclient_t;

// callback invoked if the ENS connection dies
// subscriptions are no longer valid but must not be unsubscribed
typedef void (*lost_cnx_cb_t)(void*);

ensclient_t* ens_open(const char* host, int port, lost_cnx_cb_t
lost_cnx_cb, void* lost_cnx_arg);

// automatically cleans up all existing subscription handles
void ens_close(ensclient_t*);


//
// Publishing events
//

typedef void (*destructor_t)(void*);            // cleanup function

void ens_publish(ensclient_t*, const char* evt, char* body, size_t
bodysz, destructor_t body_delete);


//
// Receiving events
//

// a subscription handle
struct sub_t;
typedef struct sub_t subscription_t;

// handler called when a subscribed event is received
typedef void (*notify_cb_t)(void *rock, char *event, char *body, size_t
body_len);

subscription_t* ens_subscribe(ensclient_t*, const char* evt, notify_cb_t
cb, void* rock);
void ens_unsubscribe(ensclient_t*, subscription_t*);

# ifdef __cplusplus
}
# endif

# endif // ENS_HEADER_INCLUDED
====

API Basic Usage

The client calls ens_open() to start a connection. If reliability across ENS connection outages is important, the client should provide a lost connection handler callback. The lost connection handler normally marks any client-specific subscription information as invalid, calls ens_close, and triggers a task to attempt a reconnect by using ens_open (possibly after a delay).

The client calls ens_close() on shut down.

The client calls ens_subscribe() to subscribe to events and gets a callback when a matching event is received. The client calls ens_unsubscribe() to unsubscribe from an event (usually not necessary as a client can just call ens_close).

To publish an event, use ens_publish. (In general, you do not need to do so and the sample code should be sufficient.)

To build the sample programs, link against the libens library, which is normally installed in /opt/sun/comms/messaging64/lib/libens.so.

The ens_sub.c sample program is helpful to see what events are generated and how the event strings and message payloads are formatted.

Both Messaging Server publishers (that is, imapd) and the ENS server (enpd) are designed to drop events if an overload situation occurs.

API Usage Notes

Clients written against the old ENS C API (the headers and libens.so file included with Messaging Server 7 Update 3 and prior releases) should work against the new ENS daemon as long as they link against the libens.so library from Messaging Server 7 Update 3 and prior releases. However, the new API is simpler so a rewrite to the new API is recommended.

The ENS C API is presently the recommended API for C-based software that needs to subscribe to Messaging Server events. Use of the Glassfish Message Queue, OpenMQ, or Java Enterprise System Message Queue C API is not recommended.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.