include/wvdbusconn.h

   1 /* -*- Mode: C++ -*-
   2  * Worldvisions Weaver Software:
   3  *   Copyright (C) 2004-2006 Net Integration Technologies, Inc.
   4  *
   5  * Pathfinder Software:
   6  *   Copyright (C) 2007, Carillon Information Security Inc.
   7  *
   8  * This library is licensed under the LGPL, please read LICENSE for details.
   9  *
  10  * A WvDBusConn represents a connection to another application. Messages
  11  * can be sent and received via this connection. In most cases, the
  12  * other application is a message bus.
  13  */
  14 #ifndef __WVDBUSCONN_H
  15 #define __WVDBUSCONN_H
  16
  17 #include "wvstreamclone.h"
  18 #include "wvlog.h"
  19 #include "wvdbusmsg.h"
  20 #include "wvhashtable.h"
  21 #include "wvuid.h"
  22
  23 #define WVDBUS_DEFAULT_TIMEOUT (300*1000)
  24
  25 class WvDBusConn;
  26
  27 /**
  28  * The data type of callbacks used by WvDBusConn::add_callback().  The
  29  * return value should be true if the callback processes the message, false
  30  * otherwise.
  31  */
  32 typedef wv::function<bool(WvDBusMsg&)> WvDBusCallback;
  33
  34 class IWvDBusAuth
  35 {
  36 public:
  37     virtual ~IWvDBusAuth() { };
  38
  39     /**
  40      * Main action callback.  Called whenever d seems to have data available.
  41      * Return false if you're not yet authorized and need to be called again
  42      * when data is available; return true if you're done.
  43      *
  44      * If authorization fails, call seterr on d with an appropriate error
  45      * message.
  46      */
  47     virtual bool authorize(WvDBusConn &c) = 0;
  48
  49     // Returns the unix UID negotiated during authentication.  Boring on the
  50     // client side (generally just getuid()), more useful for the server.
  51     virtual wvuid_t get_uid() = 0;
  52 };
  53
  54
  55 class WvDBusClientAuth : public IWvDBusAuth
  56 {
  57     bool sent_request;
  58 public:
  59     WvDBusClientAuth();
  60     virtual bool authorize(WvDBusConn &c);
  61     virtual wvuid_t get_uid();
  62 };
  63
  64
  65 class WvDBusConn : public WvStreamClone
  66 {
  67     bool client, authorized, in_post_select;
  68     WvString _uniquename;
  69     IWvDBusAuth *auth;
  70
  71 public:
  72     WvLog log;
  73
  74     /**
  75      * Creates a new dbus connection using the given WvStreams moniker.
  76      *
  77      * WvDBus uses special monikers for the "standard" DBus buses:
  78      * dbus:system, dbus:session, and dbus:starter.  These correspond to
  79      * DBUS_BUS_SYSTEM, DBUS_BUS_SESSION, and DBUS_BUS_STARTER, respectively.
  80      *
  81      * If a non-NULL _auth parameter is passed, the WvDBusConn object takes
  82      * ownership of it and will delete it at some point (possibly before
  83      * the WvDBusConn itself is destroyed).
  84      */
  85     WvDBusConn(WvStringParm moniker, IWvDBusAuth *_auth = NULL,
  86                bool _client = true);
  87
  88     /**
  89      * Creates a new dbus connection from the given stream.  Takes ownership
  90      * of the stream and will WVRELEASE() it when done.
  91      */
  92     WvDBusConn(IWvStream *_cloned, IWvDBusAuth *_auth = NULL,
  93                bool _client = true);
  94
  95     void init(IWvDBusAuth *_auth, bool _client);
  96
  97     /**
  98      * Release this connection.  If this is the last owner of the associated
  99      * DBusConnection object, the connection itself closes.
 100      */
 101     virtual ~WvDBusConn();
 102
 103     void set_uniquename(WvStringParm s);
 104     void try_auth();
 105     void send_hello();
 106     wvuid_t get_uid() { return auth ? auth->get_uid() : WVUID_INVALID; }
 107
 108     void out(WvStringParm s);
 109     void out(WVSTRING_FORMAT_DECL)
 110         { return out(WvString(WVSTRING_FORMAT_CALL)); }
 111     const char *in();
 112
 113     /**
 114      * Request the given service name on DBus.  There's no guarantee the
 115      * server will let us have the requested name, though.
 116      *
 117      * The name will be released when this connection object is destroyed.
 118      */
 119     void request_name(WvStringParm name, const WvDBusCallback &onreply = 0,
 120                       time_t msec_timeout = WVDBUS_DEFAULT_TIMEOUT);
 121
 122     /**
 123      * Return this connection's unique name on the bus, assigned by the server
 124      * at connect time.
 125      */
 126     WvString uniquename() const;
 127
 128     /**
 129      * Close the underlying stream.  The object becomes unusable.  This is
 130      * also called whenever an error is set.
 131      */
 132     virtual void close();
 133
 134     /**
 135      * Send a message on the bus, not expecting any reply.  Returns the
 136      * assigned serial number in case you want to track it some other way.
 137      */
 138     uint32_t send(WvDBusMsg msg);
 139
 140     /**
 141      * Send a message on the bus, calling onreply() when the reply comes in
 142      * or the messages times out.
 143      */
 144     void send(WvDBusMsg msg, const WvDBusCallback &onreply,
 145               time_t msec_timeout = WVDBUS_DEFAULT_TIMEOUT);
 146
 147     /**
 148      * Send a message on the bus and wait for a reply to come in, returning
 149      * the message when it does.  There is always a reply, even if it's
 150      * "message expired" or some other error message.
 151      *
 152      * The serial_cb parameter allows you to create a callback which is called
 153      * after 'send' but before the runonce() loop is initiated, allowing you
 154      * to perform some kind of setup based on the serial number of the message.
 155      *
 156      * It waits by doing this->runonce().  Streams on the globallist may run.
 157      *
 158      * WARNING: this function does a synchronous wait operation, and thus
 159      * does not play nicely in single-threaded WvStreams applications.  Use
 160      * with extreme care.
 161      */
 162     WvDBusMsg send_and_wait(WvDBusMsg msg,
 163                             time_t msec_timeout = WVDBUS_DEFAULT_TIMEOUT,
 164                             wv::function<void(uint32_t)> serial_cb = 0);
 165
 166     /**
 167      * The priority level of a callback registration.  This defines the order
 168      * in which callbacks are processed, from lowest to highest integer.
 169      */
 170     enum CallbackPri {
 171         PriSystem    = 0,     // implemented by DBus or WvDBus.  Don't use.
 172         PriSpecific  = 5000,  // strictly limited by interface/method
 173         PriNormal    = 6000,  // a reasonably selective callback
 174         PriBridge    = 7000,  // proxy selectively to other listeners
 175         PriBroadcast = 8000,  // last-resort proxy to all listeners
 176         PriGaveUp    = 9900,  // run this if nothing else works
 177     };
 178
 179     /**
 180      * Adds a callback to the connection: all received messages will be
 181      * sent to all callbacks to look at and possibly process.  This method
 182      * is simple and flexible, but it can be slow if you have too many
 183      * callbacks set.
 184      *
 185      * Your application is very unlikely to have "too many" callbacks.  If
 186      * for some reason you need to register lots of separate callbacks,
 187      * make your own data structure for them and register just a single
 188      * callback here that looks things up in your own structure.
 189      *
 190      * 'pri' defines the callback sort order.  When calling callbacks, we
 191      * call them in priority order until the first callback returns 'true'.
 192      * If you just want to log certain messages and let other people handle
 193      * them, use a high priority but return 'false'.
 194      *
 195      * 'cookie' is used to identify this callback for del_callback().  Your
 196      * 'this' pointer is a useful value here.
 197      */
 198     void add_callback(CallbackPri pri, WvDBusCallback cb, void *cookie = NULL);
 199
 200     /**
 201      * Delete all callbacks that have the given cookie.
 202      */
 203     void del_callback(void *cookie);
 204
 205     /**
 206      * Called by for each received message.  Returns true if we handled
 207      * this message, false if not.  You should not need to call or override
 208      * this; see add_callback() instead.
 209      */
 210     virtual bool filter_func(WvDBusMsg &msg);
 211
 212     /**
 213      * Returns true if there are no outstanding messages that have not
 214      * received (or timed out) their reply.  Mostly useful in unit tests
 215      * that want to terminate once all messages have been processed.
 216      */
 217     bool isidle();
 218
 219 private:
 220     time_t mintimeout_msec();
 221     virtual bool post_select(SelectInfo &si);
 222
 223     struct Pending
 224     {
 225         WvDBusMsg msg; // needed in case we need to generate timeout replies
 226         uint32_t serial;
 227         WvDBusCallback cb;
 228         WvTime valid_until;
 229
 230         Pending(WvDBusMsg &_msg, const WvDBusCallback &_cb,
 231                 time_t msec_timeout)
 232             : msg(_msg), cb(_cb)
 233         {
 234             serial = msg.get_serial();
 235             if (msec_timeout < 0)
 236                 msec_timeout = 5*3600*1000; // "forever" is a few hours
 237             valid_until = msecadd(wvstime(), msec_timeout);
 238         }
 239     };
 240     DeclareWvDict(Pending, uint32_t, serial);
 241
 242     PendingDict pending;
 243     WvDynBuf in_queue, out_queue;
 244
 245     void expire_pending(Pending *p);
 246     void cancel_pending(uint32_t serial);
 247     void add_pending(WvDBusMsg &msg, WvDBusCallback cb,
 248                      time_t msec_timeout);
 249     bool _registered(WvDBusMsg &msg);
 250
 251     struct CallbackInfo
 252     {
 253         CallbackPri pri;
 254         WvDBusCallback cb;
 255         void *cookie;
 256
 257         CallbackInfo(CallbackPri _pri,
 258                      const WvDBusCallback &_cb, void *_cookie)
 259             : cb(_cb)
 260             { pri = _pri; cookie = _cookie; }
 261     };
 262     static int priority_order(const CallbackInfo *a, const CallbackInfo *b);
 263
 264     DeclareWvList(CallbackInfo);
 265     CallbackInfoList callbacks;
 266
 267 };
 268
 269 #endif // __WVDBUSCONN_H