avis/elvin.h

Go to the documentation of this file.

/*
 *  Avis Elvin client library for C.
 *
 *  Copyright (C) 2008 Matthew Phillips <avis@mattp.name>
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of version 3 of the GNU Lesser General
 *  Public License as published by the Free Software Foundation.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 *  General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program. If not, see <http://www.gnu.org/licenses/>.
 */
#ifndef AVIS_ELVIN_H
#define AVIS_ELVIN_H

#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>

#define AVIS_LISTENERS_TYPE

typedef ArrayList * Listeners;

typedef struct
{
  socket_t    router_socket;
  socket_t    control_socket_read;
  socket_t    control_socket_write;
  ArrayList   subscriptions;
  Listeners   close_listeners;
  Listeners   notification_listeners;
  Keys *      notification_keys;
  Keys *      subscription_keys;
  bool        polling;
  ElvinError  error;
  time_t      last_receive_time;
} Elvin;

typedef enum
{
  REQUIRE_SECURE_DELIVERY = 0,
  ALLOW_INSECURE_DELIVERY = 1
} SecureMode;

typedef struct
{
  Elvin *      elvin;
  char *       subscription_expr;
  uint64_t     id;
  SecureMode   security;
  Listeners    listeners;
  Keys *       keys;
} Subscription;

typedef enum
{
  REASON_CLIENT_SHUTDOWN,

  REASON_ROUTER_SHUTDOWN,

  REASON_PROTOCOL_VIOLATION,

  REASON_ROUTER_STOPPED_RESPONDING
} CloseReason;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

AVIS_PUBLIC
bool elvin_subscription_remove_listener (Subscription *subscription,
                                         SubscriptionListener listener);
AVIS_PUBLIC
bool elvin_is_open (const Elvin *elvin);

AVIS_PUBLIC
bool elvin_close (Elvin *elvin);

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

AVIS_PUBLIC
bool elvin_invoke_close (Elvin *elvin);

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

AVIS_PUBLIC
bool elvin_remove_close_listener (Elvin *elvin, CloseListener listener);

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

AVIS_PUBLIC
bool elvin_remove_notification_listener (Elvin *elvin,
                                         GeneralNotificationListener listener);

AVIS_PUBLIC
bool elvin_event_loop (Elvin *elvin);

AVIS_PUBLIC
bool elvin_poll (Elvin *elvin);

#endif /* AVIS_ELVIN_H */

---