Avis Client Library: avis/elvin.h File Reference

# 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)", sub_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()