lib/libradsec-levent.h

   1 /** @file libradsec-levent.h
   2     @brief API for libradsec-libevent.  */
   3
   4 /* FIXME: License blurb goes here.  */
   5
   6 #include <sys/socket.h>
   7 #include "libradsec.h"
   8
   9 struct rs_connection {
  10     struct rs_handle *conf;
  11     struct sockaddr_storage addr;
  12     char open_flag;
  13 };
  14
  15 typedef void (*rs_conn_connected_cb)(void *user_data /* FIXME: peer? */);
  16 typedef void (*rs_conn_disconnected_cb)(void *user_data /* FIXME: reason? */);
  17 typedef void (*rs_conn_packet_received_cb)(const struct rs_packet *packet,
  18                                            void *user_data);
  19 typedef void (*rs_conn_packet_sent_cb)(void *user_data);
  20
  21 /** Connection callbacks.  */
  22 struct rs_conn_callbacks {
  23     /** Callback invoked when the connection has been established.  */
  24     rs_conn_connected_cb connected_cb;
  25     /** Callback invoked when the connection has been torn down.  */
  26     rs_conn_disconnected_cb disconnected_cb;
  27     /** Callback invoked when a packet was received.  */
  28     rs_conn_packet_received_cb received_cb;
  29     /** Callback invoked when a packet was successfully sent.  */
  30     rs_conn_packet_sent_cb sent_cb;
  31 };
  32
  33
  34 /* Function prototypes.  */
  35
  36 /*
  37   FIXME: Do we want alloc and free?  Or perhaps init and free,
  38   decoupling allocation from initialization?  IMO we want _some_ init
  39   function, f.ex. for setting open_flag = 1 when type == UDP.
  40
  41 struct conn *conn_alloc (enum conn_type type, struct sockaddr_in6 address, ...);
  42 void conn_free (struct conn *conn);
  43 */
  44
  45 /** Open connection and return 0 on success.
  46     @param conn Connection object, obtained through a call to @a
  47     conn_alloc.
  48     @param cb Callbacks for events on the connection.  If NULL, all I/O
  49     will be blocking.
  50     @param user_data A pointer passed to the callbacks when invoked.  */
  51 int rs_conn_open(struct rs_conn *conn,
  52                  const struct rs_conn_callbacks *cb,
  53                  void *user_data);
  54
  55 /** Close connection and return 0 on success.
  56     @param conn Connection object, obtained through a call to @a
  57     conn_alloc.
  58     @param user_data A pointer passed to the callbacks when the @a
  59     disconnected_cb in @a conn is invoked.  */
  60 int rs_conn_close(struct rs_conn *conn, void *user_data); /* FIXME: return type?  */
  61
  62 /** Allocate a packet object.  Should be freed using @a rs_packet_free.  */
  63 struct rs_packet *rs_packet_alloc();
  64
  65 /** Free a packet object previously allocated with @a rs_packet_alloc.  */
  66 void rs_packet_free();
  67
  68 /** Add an attribute to a packet.
  69     @param packet The packet.
  70     @param attribute Attribute to add to packet.  */
  71 int rs_packet_add_attribute(struct rs_packet *packet,
  72                             const struct rs_attribute *attribute);
  73
  74 /** Send @a packet on @a conn and return 0 on success.
  75     @param conn Connection object, obtained through a call to @a
  76     conn_alloc and opened with @a rs_conn_open.
  77     @param packet Packet to send.
  78     @param user_data Pointer passed to @a rs_conn_packet_sent_cb, invoked
  79     when packet has been sent.
  80  */
  81 int rs_packet_send(const struct rs_conn *conn,
  82                    const struct rs_packet *packet,
  83                    void *user_data);
  84
  85 /** Return the next packet received on @a conn, blocking while waiting.
  86     The packet returned must be freed using @a rs_packet_free.  */
  87 struct rs_packet *rs_packet_receive(const struct rs_conn *conn);
  88
  89
  90 /* Thinking out loud here...
  91
  92    We could let the user drive the underlying libevent event loop in
  93    three different ways, from easiest to hairiest:
  94
  95    i) Blocking i/o model: User passes NULL for the callbacks in
  96    rs_conn_open().  The open, send and receive calls will block until
  97    the desired event occurs.  Other events occurring while waiting
  98    will be either silently discarded or signaled as an error
  99    (f.ex. broken connection while sending).
 100
 101    ii) Simple event loop interface with a timeout: User calls
 102    rs_event_loop(timeout) to process pending i/o.  Should be a good
 103    choice for most applications.
 104
 105    iii) Full libevent interface: TODO.
 106  */
 107
 108
 109 #error "Need an rs_event_loop().  And more."