avis/elvin.h File Reference

---

Detailed Description

The main Avis client library definitions.

#include <avis/defs.h>
#include <avis/keys.h>
#include <avis/attributes.h>
#include <avis/stdtypes.h>
#include <avis/elvin_uri.h>
#include <avis/errors.h>
#include <avis/arrays.h>
#include <avis/net.h>

Go to the source code of this file.

Data Structures
struct	Elvin
	A client connection to an Elvin router. More...
struct	Subscription
	A subscription to notifications on an Elvin router. More...
Defines
#define	AVIS_LISTENERS_TYPE
Typedefs
typedef ArrayList *	Listeners
typedef void(*	SubscriptionListener )(Subscription *subscription, Attributes *attributes, bool secure, void *user_data)
	A listener for notifications received via a subscription.
typedef void(*	CloseListener )(Elvin *elvin, CloseReason reason, const char *message, void *user_data)
	A listener for elvin connection close events.
typedef void(*	GeneralNotificationListener )(Elvin *elvin, Attributes *attributes, bool secure, void *user_data)
	A listener for connection-wide notification events.
typedef void(*	InvokeHandler )(Elvin *elvin, void *parameter)
	A handler function schedued to be called by elvin_invoke().
Enumerations
enum	SecureMode { REQUIRE_SECURE_DELIVERY = 0, ALLOW_INSECURE_DELIVERY = 1 }
	Selects the secure delivery/receipt mode for notifications. More...
enum	CloseReason { REASON_CLIENT_SHUTDOWN, REASON_ROUTER_SHUTDOWN, REASON_PROTOCOL_VIOLATION, REASON_ROUTER_STOPPED_RESPONDING }
Functions
AVIS_PUBLIC bool	elvin_open (Elvin *elvin, const char *router_uri)
	Open a connection to an Elvin router.
AVIS_PUBLIC bool	elvin_open_uri (Elvin *elvin, ElvinURI *uri)
	Open a connection to an Elvin router.
AVIS_PUBLIC bool	elvin_open_with_keys (Elvin *elvin, ElvinURI *uri, Keys *notification_keys, Keys *subscription_keys)
	Open a connection to an Elvin router with optional security constraints.
AVIS_PUBLIC bool	elvin_set_keys (Elvin *elvin, Keys *notification_keys, Keys *subscription_keys)
	Change the connection-wide keys used to secure the receipt and delivery of notifications.
AVIS_PUBLIC bool	elvin_send (Elvin *elvin, Attributes *notification)
	Send a notification to an Elvin router.
AVIS_PUBLIC bool	elvin_send_with_keys (Elvin *elvin, Attributes *notification, Keys *notification_keys, SecureMode security)
	Send a notification to an Elvin router with security constraints.
AVIS_PUBLIC Subscription *	elvin_subscribe (Elvin *elvin, const char *subscription_expr)
	Subscribe to notifications from an Elvin router.
AVIS_PUBLIC Subscription *	elvin_subscribe_with_keys (Elvin *elvin, const char *subscription_expr, Keys *keys, SecureMode security)
	Subscribe to notifications from an Elvin router with optional security constraints.
AVIS_PUBLIC bool	elvin_unsubscribe (Elvin *elvin, Subscription *subscription)
	Unsubscribe from a subscription created on an Elvin router.
AVIS_PUBLIC bool	elvin_subscription_set_expr (Subscription *subscription, const char *subscription_expr)
	Change the subscription expression for an existing subscription.
AVIS_PUBLIC bool	elvin_subscription_set_keys (Subscription *subscription, Keys *subscription_keys, SecureMode security)
	Change the keys used for receiving secure notifications.
AVIS_PUBLIC void	elvin_subscription_add_listener (Subscription *subscription, SubscriptionListener listener, void *user_data)
	Add a listener that will be called when notifications matching a subscription are received.
AVIS_PUBLIC bool	elvin_subscription_remove_listener (Subscription *subscription, SubscriptionListener listener)
	Remove a previously added subscription listener.
AVIS_PUBLIC bool	elvin_is_open (const Elvin *elvin)
	Test if the Elvin connection is open.
AVIS_PUBLIC bool	elvin_close (Elvin *elvin)
	Close the elvin connection.
AVIS_PUBLIC void	elvin_reset (Elvin *elvin)
	Reset a new Elvin instance to safe defaults such that the instance appears to be closed (elvin_is_open(), elvin_close() and elvin_free() are safe to call).
AVIS_PUBLIC bool	elvin_invoke (Elvin *elvin, InvokeHandler handler, void *parameter)
	Invoke a function call inside the Elvin event loop thread.
AVIS_PUBLIC bool	elvin_invoke_close (Elvin *elvin)
	Shortcut to invoke elvin_close() via elvin_invoke().
AVIS_PUBLIC void	elvin_add_close_listener (Elvin *elvin, CloseListener listener, void *user_data)
	Add a listener that will be called when the connection is closed.
AVIS_PUBLIC bool	elvin_remove_close_listener (Elvin *elvin, CloseListener listener)
	Remove a listener added by elvin_add_close_listener().
AVIS_PUBLIC void	elvin_add_notification_listener (Elvin *elvin, GeneralNotificationListener listener, void *user_data)
	Add a listener that will be called when a notification is received on any subscription created by this connection.
AVIS_PUBLIC bool	elvin_remove_notification_listener (Elvin *elvin, GeneralNotificationListener listener)
	Remove a listener added by elvin_add_notification_listener().
AVIS_PUBLIC bool	elvin_event_loop (Elvin *elvin)
	Continuously poll an Elvin connection for an incoming messages from the router until the client connection is closed.
AVIS_PUBLIC bool	elvin_poll (Elvin *elvin)
	Poll an Elvin connection for a single incoming message from the router.

---

Define Documentation

#define AVIS_LISTENERS_TYPE

---

Typedef Documentation

typedef void(* CloseListener)(Elvin *elvin, CloseReason reason, const char *message, void *user_data)

A listener for elvin connection close events.

Parameters:

	elvin	The elvin connection.
	reason	The reason for the shutdown.
	message	The router's shutdown message (when REASON_ROUTER_SHUTDOWN), or the client's description of the reason otherwise.
	user_data	The user data passed in when adding the listener.

See also:

elvin_add_close_listener()

typedef void(* GeneralNotificationListener)(Elvin *elvin, Attributes *attributes, bool secure, void *user_data)

A listener for connection-wide notification events.

Parameters:

	elvin	The elvin connection.
	attributes	The notification from the router. Note that these attributes are only valid for the duration of the callback -- they will be freed by the connection after the callback returns. If you want to refer to any part of the notification outside callback scope, you will need to copy the relevant parts before returning.
	secure	True if the notification was received securely from a client with a matching set of security keys (see elvin_subscribe_with_keys() and elvin_open_with_keys()). This will be true if at least one subscription securely matched the notification.
	user_data	The user data passed in when adding the listener.

See also:

elvin_add_notification_listener()

typedef void(* InvokeHandler)(Elvin *elvin, void *parameter)

A handler function schedued to be called by elvin_invoke().

Parameters:

	elvin	The Elvin connection that is calling the function.
	parameter	The parameter passed into elvin_invoke ().

typedef ArrayList* Listeners

typedef void(* SubscriptionListener)(Subscription *subscription, Attributes *attributes, bool secure, void *user_data)

A listener for notifications received via a subscription.

Parameters:

	subscription	The subscription that matched the notification.
	attributes	The notification from the router. Note that these attributes are only valid for the duration of the callback -- they will be freed by the connection after the callback returns. If you want to refer to any part of the notification outside callback scope, you will need to copy the relevant parts before returning.
	secure	True if the notification was received securely from a client with a matching set of security keys (see elvin_subscribe_with_keys() and elvin_open_with_keys()).
	user_data	The user data pointer passed into elvin_subscription_add_listener().

See also:

elvin_subscription_add_listener()

---

Enumeration Type Documentation

enum CloseReason

Enumerator:

REASON_CLIENT_SHUTDOWN	The client was shut down normally with a call to elvin_close().
REASON_ROUTER_SHUTDOWN	The router was shut down normally.
REASON_PROTOCOL_VIOLATION	Either the client or the router decided that the protocol rules have been violated. This would only happen in the case of a serious bug in the client or router.
REASON_ROUTER_STOPPED_RESPONDING	The router failed to respond to a message. Either a low-level network error has occurred, or the router has crashed.

enum SecureMode

Selects the secure delivery/receipt mode for notifications.

Enumerator:

REQUIRE_SECURE_DELIVERY
ALLOW_INSECURE_DELIVERY

---

Function Documentation

AVIS_PUBLIC void elvin_add_close_listener	(	Elvin *	elvin,
		CloseListener	listener,
		void *	user_data
	)

Add a listener that will be called when the connection is closed.

Parameters:

	elvin	The elvin connection.
	listener	The listener to be called when the connection is either closed locally (elvin_close ()) or remotely by the router
	user_data	An optional pointer to user data to be passed into the listener when called. This can be used to provide context information to the listener function.

See also:

elvin_remove_close_listener()

AVIS_PUBLIC void elvin_add_notification_listener	(	Elvin *	elvin,
		GeneralNotificationListener	listener,
		void *	user_data
	)

Add a listener that will be called when a notification is received on any subscription created by this connection.

Parameters:

	elvin	The elvin connection.
	listener	The listener to be called when the a notification is received.
	user_data	An optional pointer to user data to be passed into the listener when called. This can be used to provide context information to the listener function.

See also:

elvin_remove_notification_listener()

elvin_subscribe()

elvin_subscription_add_listener()

AVIS_PUBLIC bool elvin_close

(

Elvin *

elvin

)

Close the elvin connection.

This may be called any number of times, calls subsequent to the first have no effect.

Parameters:

elvin

The Elvin connection instance.

Returns:

True if the connection was closed, false if it was already closed.

See also:

elvin_reset()

AVIS_PUBLIC bool elvin_event_loop

(

Elvin *

elvin

)

Continuously poll an Elvin connection for an incoming messages from the router until the client connection is closed.

Clients that create subscriptions should call this function after subscribing to receive notifications and dispatch them to their listeners.

This function will block and only return when the connection is closed by the client with elvin_close(), by the router, or due to a protocol error.

To close the connection from another thread, call elvin_invoke_close().

Example:

 Elvin *elvin = ...

 if (!elvin_event_loop (elvin))
   elvin_perror ("elvin", &elvin->error);
 

Returns:

True if no error occurred.

See also:

elvin_close()

elvin_poll()

elvin_event_loop()

elvin_invoke()

AVIS_PUBLIC bool elvin_invoke	(	Elvin *	elvin,
		InvokeHandler	handler,
		void *	parameter
	)

Invoke a function call inside the Elvin event loop thread.

This call will return immediately, and the nominated handler will be called from the event loop thread (the one calling elvin_event_loop()) at the earliest opportunity. This function is the only one that is safe to call from threads other than the one running the main event loop.

Parameters:

	elvin	The Elvin connection.
	handler	The handler to call.
	parameter	The single parameter to supply to the handler (which may be NULL)

Returns:

True if the handler was queued for callback. False indicates the connection is closed or there was an internal error.

See also:

elvin_invoke_close()

AVIS_PUBLIC bool elvin_invoke_close

(

Elvin *

elvin

)

Shortcut to invoke elvin_close() via elvin_invoke().

This can be used by multi-threaded applications to safely shut down an Elvin connection.

AVIS_PUBLIC bool elvin_is_open

(

const Elvin *

elvin

)

Test if the Elvin connection is open.

Parameters:

elvin

The Elvin connection instance.

See also:

elvin_close()

AVIS_PUBLIC bool elvin_open	(	Elvin *	elvin,
		const char *	router_uri
	)

Open a connection to an Elvin router.

Parameters:

	elvin	The Elvin connection instance.
	router_uri	The URI for the router endpoint.

Returns:

true if the connection succeeded.

Example:

 Elvin elvin;

 if (!elvin_open (&elvin, "elvin://public.elvin.org"))
 {
   elvin_perror ("open", &elvin.error);
   exit (1);
 }

 elvin_close (&elvin);
 

See also:

elvin_open_uri()

elvin_open_with_keys()

elvin_close()

elvin_is_open()

AVIS_PUBLIC bool elvin_open_uri	(	Elvin *	elvin,
		ElvinURI *	uri
	)

Open a connection to an Elvin router.

Parameters:

	elvin	The Elvin connection instance.
	uri	The URI for the router endpoint.

Returns:

true if the connection succeeded.

See also:

elvin_open()

AVIS_PUBLIC bool elvin_open_with_keys	(	Elvin *	elvin,
		ElvinURI *	uri,
		Keys *	notification_keys,
		Keys *	subscription_keys
	)

Open a connection to an Elvin router with optional security constraints.

Ownership of the keys used in this call passes to the connection, which will free them when no longer needed.

Parameters:

	elvin	The Elvin connection instance.
	uri	The URI for the router endpoint.
	notification_keys	These keys automatically apply to all notifications, exactly as if they were added to the keys in the elvin_send_with_keys() call.
	subscription_keys	These keys automatically apply to all subscriptions, exactly as if they were added to the keys in the elvin_subscribe_with_keys() call.

Returns:

true if the connection succeeded.

See also:

elvin_open_uri()

elvin_set_keys()

AVIS_PUBLIC bool elvin_poll

(

Elvin *

elvin

)

Poll an Elvin connection for a single incoming message from the router.

This will block until a notification or disconnect message is received from the router, or until AVIS_IO_TIMEOUT milliseconds have passed (in which case the error status will be ELVIN_ERROR_TIMEOUT).

On receipt of a notification, any listeners to the notification will be called from this function. On receipt of a disconnect or socket close, the connection will be shut down.

This method may be useful to clients that wish to coarsely interleave polled events with other actions (e.g. when embedding Elvin client connections in other event loops), but most clients will want to just call elvin_event_loop().

Returns:

True if no error occurred.

AVIS_PUBLIC bool elvin_remove_close_listener	(	Elvin *	elvin,
		CloseListener	listener
	)

Remove a listener added by elvin_add_close_listener().

Parameters:

	elvin	The elvin connection.
	listener	The listener to be removed.

Returns:

True if the listener was in the list and was removed.

See also:

elvin_add_close_listener()

AVIS_PUBLIC bool elvin_remove_notification_listener	(	Elvin *	elvin,
		GeneralNotificationListener	listener
	)

Remove a listener added by elvin_add_notification_listener().

Parameters:

	elvin	The elvin connection.
	listener	The listener to be removed.

Returns:

True if the listener was in the list and was removed.

See also:

elvin_add_close_listener()

AVIS_PUBLIC void elvin_reset

(

Elvin *

elvin

)

Reset a new Elvin instance to safe defaults such that the instance appears to be closed (elvin_is_open(), elvin_close() and elvin_free() are safe to call).

This should NOT be called on an open connection: use elvin_close().

See also:

elvin_close()

AVIS_PUBLIC bool elvin_send	(	Elvin *	elvin,
		Attributes *	notification
	)

Send a notification to an Elvin router.

Parameters:

	elvin	The Elvin connection instance.
	notification	The notification attributes.

Returns:

True if the send succeeded.

Example:

 Elvin *elvin = ...
 Attributes *notification = attributes_create ();

 attributes_set_int32 (notification, "favourite number", 42);
 attributes_set_string (notification, "message", "hello world");

 elvin_send (elvin, notification);

 attributes_destroy (notification);
 

See also:

elvin_subscribe()

AVIS_PUBLIC bool elvin_send_with_keys	(	Elvin *	elvin,
		Attributes *	notification,
		Keys *	notification_keys,
		SecureMode	security
	)

Send a notification to an Elvin router with security constraints.

Parameters:

	elvin	The Elvin connection instance.
	notification	The notification to send.
	notification_keys	The keys that must match for secure delivery.
	security	The security requirement. REQUIRE_SECURE_DELIVERY means the notification can only be received by subscriptions with keys matching the set supplied here (or the connections' global notification keys: see elvin_subscription_set_keys()).

See also:

elvin_send()

elvin_subscribe_with_keys()

AVIS_PUBLIC bool elvin_set_keys	(	Elvin *	elvin,
		Keys *	notification_keys,
		Keys *	subscription_keys
	)

Change the connection-wide keys used to secure the receipt and delivery of notifications.

Parameters:

	elvin	The Elvin connection.
	notification_keys	The new notification keys. These automatically apply to all notifications, exactly as if they were added to the keys in the elvin_send_with_keys() call.
	subscription_keys	The new subscription keys. These automatically apply to all subscriptions, exactly as if they were added to the keys in the elvin_subscribe_with_keys(), call. This applies to all existing and future subscriptions.

See also:

elvin_open_with_keys()

elvin_subscription_set_keys()

AVIS_PUBLIC Subscription* elvin_subscribe	(	Elvin *	elvin,
		const char *	subscription_expr
	)

Subscribe to notifications from an Elvin router.

Parameters:

	elvin	The Elvin connection instance.
	subscription_expr	The subscription expression. This expression is copied and freed when the subscription is disposed.

Returns:

The new subscription, or NULL on error.

Example:

 Elvin *elvin = ...
 Subscription *subscription =
   elvin_subscribe (elvin, "string (message)");

 if (!subscription)
 {
   elvin_perror ("subscribe", &elvin->error);
   exit (1);
 }

 elvin_unsubscribe (elvin, subscription);
 

See also:

elvin_subscribe_with_keys()

elvin_subscription_add_listener()

AVIS_PUBLIC Subscription* elvin_subscribe_with_keys	(	Elvin *	elvin,
		const char *	subscription_expr,
		Keys *	keys,
		SecureMode	security
	)

Subscribe to notifications from an Elvin router with optional security constraints.

Parameters:

	elvin	The Elvin connection instance.
	subscription_expr	The subscription expression. This expression is copied and freed when the subscription is disposed.
	keys	The keys that must match notification keys for secure delivery. Ownership of the keys passes to the connection, which will free them when no longer needed.
	security	The security mode: specifying REQUIRE_SECURE_DELIVERY means the subscription will only receive notifications that are sent by clients with keys matching the set supplied here or the global subscription key set.

Returns:

The new subscription, or NULL on error.

Example:

 Elvin *elvin = ...
 Keys *sub_keys = ...
 Subscription *subscription =
   elvin_subscribe_with_keys (elvin, "string (message)", keys,
                              REQUIRE_SECURE_DELIVERY);

 if (!subscription)
 {
   elvin_perror ("subscribe", &elvin->error);
   exit (1);
 }

 elvin_unsubscribe (elvin, subscription);
 

See also:

elvin_unsubscribe()

elvin_subscription_set_expr()

elvin_send_with_keys()

elvin_subscription_add_listener()

elvin_subscription_set_keys()

elvin_poll()

AVIS_PUBLIC void elvin_subscription_add_listener	(	Subscription *	subscription,
		SubscriptionListener	listener,
		void *	user_data
	)

Add a listener that will be called when notifications matching a subscription are received.

Parameters:

	subscription	The subscription to add the listener to.
	listener	The listener to be called for matching notifications.
	user_data	An optional pointer to user data to be passed into the listener when called. This can be used to provide context information to the listener function.

See also:

elvin_subscription_remove_listener()

elvin_add_notification_listener()

AVIS_PUBLIC bool elvin_subscription_remove_listener	(	Subscription *	subscription,
		SubscriptionListener	listener
	)

Remove a previously added subscription listener.

Parameters:

	subscription	The subscription to remove the listener from.
	listener	The listener to be removed.

Returns:

True if the listener was removed, false if it was not in the subscription list.

See also:

elvin_subscription_add_listener()

AVIS_PUBLIC bool elvin_subscription_set_expr	(	Subscription *	subscription,
		const char *	subscription_expr
	)

Change the subscription expression for an existing subscription.

Parameters:

	subscription	The subscription to change.
	subscription_expr	The new subscription expression.

See also:

elvin_subscribe()

AVIS_PUBLIC bool elvin_subscription_set_keys	(	Subscription *	subscription,
		Keys *	subscription_keys,
		SecureMode	security
	)

Change the keys used for receiving secure notifications.

Parameters:

	subscription	The subscription to change.
	subscription_keys	The new subscription keys.
	security	security The security mode: specifying REQUIRE_SECURE_DELIVERY means the subscription will only receive notifications that are sent by clients with keys matching the set supplied here or the global subscription key set.

See also:

elvin_subscribe_with_keys()

elvin_set_keys()

AVIS_PUBLIC bool elvin_unsubscribe	(	Elvin *	elvin,
		Subscription *	subscription
	)

Unsubscribe from a subscription created on an Elvin router.

Parameters:

	elvin	The Elvin connection instance.
	subscription	The subscription to remove. This will be automatically freed by the connection.

Returns:

True if the unsubscribe succeeded.

See also:

elvin_subscribe()