_dbus_bindings/conn-methods.c

   1 /* Implementation of normal Python-accessible methods on the _dbus_bindings
   2  * Connection type; separated out to keep the file size manageable.
   3  *
   4  * Copyright (C) 2006 Collabora Ltd. <http://www.collabora.co.uk/>
   5  *
   6  * Licensed under the Academic Free License version 2.1
   7  *
   8  * This library is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU Lesser General Public License as published by
  10  * the Free Software Foundation; either version 2.1 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public License
  19  * along with this library; if not, write to the Free Software
  20  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21  *
  22  */
  23
  24 #include "dbus_bindings-internal.h"
  25 #include "conn-internal.h"
  26
  27 static void
  28 _object_path_unregister(DBusConnection *conn, void *user_data)
  29 {
  30     PyGILState_STATE gil = PyGILState_Ensure();
  31     PyObject *tuple = NULL;
  32     Connection *conn_obj = NULL;
  33     PyObject *callable;
  34
  35     conn_obj = (Connection *)DBusPyConnection_ExistingFromDBusConnection(conn);
  36     if (!conn_obj) goto out;
  37     TRACE(conn_obj);
  38
  39     DBG("Connection at %p unregistering object path %s",
  40         conn_obj, PyString_AS_STRING((PyObject *)user_data));
  41     tuple = DBusPyConnection_GetObjectPathHandlers((PyObject *)conn_obj, (PyObject *)user_data);
  42     if (!tuple) goto out;
  43     if (tuple == Py_None) goto out;
  44
  45     DBG("%s", "... yes we have handlers for that object path");
  46
  47     /* 0'th item is the unregisterer (if that's a word) */
  48     callable = PyTuple_GetItem(tuple, 0);
  49     if (callable && callable != Py_None) {
  50         DBG("%s", "... and we even have an unregisterer");
  51         /* any return from the unregisterer is ignored */
  52         Py_XDECREF(PyObject_CallFunctionObjArgs(callable, conn_obj, NULL));
  53     }
  54 out:
  55     Py_XDECREF(conn_obj);
  56     Py_XDECREF(tuple);
  57     /* the user_data (a Python str) is no longer ref'd by the DBusConnection */
  58     Py_XDECREF((PyObject *)user_data);
  59     if (PyErr_Occurred()) {
  60         PyErr_Print();
  61     }
  62     PyGILState_Release(gil);
  63 }
  64
  65 static DBusHandlerResult
  66 _object_path_message(DBusConnection *conn, DBusMessage *message,
  67                      void *user_data)
  68 {
  69     DBusHandlerResult ret;
  70     PyGILState_STATE gil = PyGILState_Ensure();
  71     Connection *conn_obj = NULL;
  72     PyObject *tuple = NULL;
  73     PyObject *msg_obj;
  74     PyObject *callable;             /* borrowed */
  75
  76     dbus_message_ref(message);
  77     msg_obj = DBusPyMessage_ConsumeDBusMessage(message);
  78     if (!msg_obj) {
  79         ret = DBUS_HANDLER_RESULT_NEED_MEMORY;
  80         goto out;
  81     }
  82
  83     conn_obj = (Connection *)DBusPyConnection_ExistingFromDBusConnection(conn);
  84     if (!conn_obj) {
  85         ret = DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
  86         goto out;
  87     }
  88     TRACE(conn_obj);
  89
  90     DBG("Connection at %p messaging object path %s",
  91         conn_obj, PyString_AS_STRING((PyObject *)user_data));
  92     DBG_DUMP_MESSAGE(message);
  93     tuple = DBusPyConnection_GetObjectPathHandlers((PyObject *)conn_obj, (PyObject *)user_data);
  94     if (!tuple || tuple == Py_None) {
  95         ret = DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
  96         goto out;
  97     }
  98
  99     DBG("%s", "... yes we have handlers for that object path");
 100
 101     /* 1st item (0-based) is the message callback */
 102     callable = PyTuple_GetItem(tuple, 1);
 103     if (!callable) {
 104         DBG("%s", "... error getting message handler from tuple");
 105         ret = DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
 106     }
 107     else if (callable == Py_None) {
 108         /* there was actually no handler after all */
 109         DBG("%s", "... but those handlers don't do messages");
 110         ret = DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
 111     }
 112     else {
 113         DBG("%s", "... and we have a message handler for that object path");
 114         ret = DBusPyConnection_HandleMessage(conn_obj, msg_obj, callable);
 115     }
 116
 117 out:
 118     Py_XDECREF(msg_obj);
 119     Py_XDECREF(conn_obj);
 120     Py_XDECREF(tuple);
 121     if (PyErr_Occurred()) {
 122         PyErr_Print();
 123     }
 124     PyGILState_Release(gil);
 125     return ret;
 126 }
 127
 128 static const DBusObjectPathVTable _object_path_vtable = {
 129     _object_path_unregister,
 130     _object_path_message,
 131 };
 132
 133 static DBusHandlerResult
 134 _filter_message(DBusConnection *conn, DBusMessage *message, void *user_data)
 135 {
 136     DBusHandlerResult ret;
 137     PyGILState_STATE gil = PyGILState_Ensure();
 138     Connection *conn_obj = NULL;
 139     PyObject *callable = NULL;
 140     PyObject *msg_obj;
 141 #ifndef DBUS_PYTHON_DISABLE_CHECKS
 142     Py_ssize_t i, size;
 143 #endif
 144
 145     dbus_message_ref(message);
 146     msg_obj = DBusPyMessage_ConsumeDBusMessage(message);
 147     if (!msg_obj) {
 148         DBG("%s", "OOM while trying to construct Message");
 149         ret = DBUS_HANDLER_RESULT_NEED_MEMORY;
 150         goto out;
 151     }
 152
 153     conn_obj = (Connection *)DBusPyConnection_ExistingFromDBusConnection(conn);
 154     if (!conn_obj) {
 155         DBG("%s", "failed to traverse DBusConnection -> Connection weakref");
 156         ret = DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
 157         goto out;
 158     }
 159     TRACE(conn_obj);
 160
 161     /* The user_data is a pointer to a Python object. To avoid
 162      * cross-library reference cycles, the DBusConnection isn't allowed
 163      * to reference it. However, as long as the Connection is still
 164      * alive, its ->filters list owns a reference to the same Python
 165      * object, so the object should also still be alive.
 166      *
 167      * To ensure that this works, be careful whenever manipulating the
 168      * filters list! (always put things in the list *before* giving
 169      * them to libdbus, etc.)
 170      */
 171 #ifdef DBUS_PYTHON_DISABLE_CHECKS
 172     callable = (PyObject *)user_data;
 173 #else
 174     size = PyList_GET_SIZE(conn_obj->filters);
 175     for (i = 0; i < size; i++) {
 176         callable = PyList_GET_ITEM(conn_obj->filters, i);
 177         if (callable == user_data) {
 178             Py_INCREF(callable);
 179         }
 180         else {
 181             callable = NULL;
 182         }
 183     }
 184
 185     if (!callable) {
 186         DBG("... filter %p has vanished from ->filters, so not calling it",
 187             user_data);
 188         ret = DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
 189         goto out;
 190     }
 191 #endif
 192
 193     ret = DBusPyConnection_HandleMessage(conn_obj, msg_obj, callable);
 194 out:
 195     Py_XDECREF(msg_obj);
 196     Py_XDECREF(conn_obj);
 197     Py_XDECREF(callable);
 198     PyGILState_Release(gil);
 199     return ret;
 200 }
 201
 202 PyDoc_STRVAR(Connection__require_main_loop__doc__,
 203 "_require_main_loop()\n\n"
 204 "Raise an exception if this Connection is not bound to any main loop -\n"
 205 "in this state, asynchronous calls, receiving signals and exporting objects\n"
 206 "will not work.\n"
 207 "\n"
 208 "`dbus.mainloop.NULL_MAIN_LOOP` is treated like a valid main loop - if you're\n"
 209 "using that, you presumably know what you're doing.\n");
 210 static PyObject *
 211 Connection__require_main_loop (Connection *self, PyObject *args UNUSED)
 212 {
 213     if (!self->has_mainloop) {
 214         PyErr_SetString(PyExc_RuntimeError,
 215                         "To make asynchronous calls, receive signals or "
 216                         "export objects, D-Bus connections must be attached "
 217                         "to a main loop by passing mainloop=... to the "
 218                         "constructor or calling "
 219                         "dbus.set_default_main_loop(...)");
 220         return NULL;
 221     }
 222     Py_RETURN_NONE;
 223 }
 224
 225 PyDoc_STRVAR(Connection_close__doc__,
 226 "close()\n\n"
 227 "Close the connection.");
 228 static PyObject *
 229 Connection_close (Connection *self, PyObject *args UNUSED)
 230 {
 231     TRACE(self);
 232     /* Because the user explicitly asked to close the connection, we'll even
 233     let them close shared connections. */
 234     if (self->conn) {
 235         Py_BEGIN_ALLOW_THREADS
 236         dbus_connection_close(self->conn);
 237         Py_END_ALLOW_THREADS
 238     }
 239     Py_RETURN_NONE;
 240 }
 241
 242 PyDoc_STRVAR(Connection_get_is_connected__doc__,
 243 "get_is_connected() -> bool\n\n"
 244 "Return true if this Connection is connected.\n");
 245 static PyObject *
 246 Connection_get_is_connected (Connection *self, PyObject *args UNUSED)
 247 {
 248     dbus_bool_t ret;
 249
 250     TRACE(self);
 251     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 252     Py_BEGIN_ALLOW_THREADS
 253     ret = dbus_connection_get_is_connected(self->conn);
 254     Py_END_ALLOW_THREADS
 255     return PyBool_FromLong(ret);
 256 }
 257
 258 PyDoc_STRVAR(Connection_get_is_authenticated__doc__,
 259 "get_is_authenticated() -> bool\n\n"
 260 "Return true if this Connection was ever authenticated.\n");
 261 static PyObject *
 262 Connection_get_is_authenticated (Connection *self, PyObject *args UNUSED)
 263 {
 264     dbus_bool_t ret;
 265
 266     TRACE(self);
 267     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 268     Py_BEGIN_ALLOW_THREADS
 269     ret = dbus_connection_get_is_authenticated(self->conn);
 270     Py_END_ALLOW_THREADS
 271     return PyBool_FromLong(ret);
 272 }
 273
 274 PyDoc_STRVAR(Connection_set_exit_on_disconnect__doc__,
 275 "set_exit_on_disconnect(bool)\n\n"
 276 "Set whether the C function ``_exit`` will be called when this Connection\n"
 277 "becomes disconnected. This will cause the program to exit without calling\n"
 278 "any cleanup code or exit handlers.\n"
 279 "\n"
 280 "The default is for this feature to be disabled for Connections and enabled\n"
 281 "for Buses.\n");
 282 static PyObject *
 283 Connection_set_exit_on_disconnect (Connection *self, PyObject *args)
 284 {
 285     int exit_on_disconnect;
 286
 287     TRACE(self);
 288     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 289     if (!PyArg_ParseTuple(args, "i:set_exit_on_disconnect",
 290                           &exit_on_disconnect)) {
 291         return NULL;
 292     }
 293     Py_BEGIN_ALLOW_THREADS
 294     dbus_connection_set_exit_on_disconnect(self->conn,
 295                                            exit_on_disconnect ? 1 : 0);
 296     Py_END_ALLOW_THREADS
 297     Py_RETURN_NONE;
 298 }
 299
 300 PyDoc_STRVAR(Connection_send_message__doc__,
 301 "send_message(msg) -> long\n\n"
 302 "Queue the given message for sending, and return the message serial number.\n"
 303 "\n"
 304 ":Parameters:\n"
 305 "   `msg` : dbus.lowlevel.Message\n"
 306 "       The message to be sent.\n"
 307 );
 308 static PyObject *
 309 Connection_send_message(Connection *self, PyObject *args)
 310 {
 311     dbus_bool_t ok;
 312     PyObject *obj;
 313     DBusMessage *msg;
 314     dbus_uint32_t serial;
 315
 316     TRACE(self);
 317     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 318     if (!PyArg_ParseTuple(args, "O", &obj)) return NULL;
 319
 320     msg = DBusPyMessage_BorrowDBusMessage(obj);
 321     if (!msg) return NULL;
 322
 323     Py_BEGIN_ALLOW_THREADS
 324     ok = dbus_connection_send(self->conn, msg, &serial);
 325     Py_END_ALLOW_THREADS
 326
 327     if (!ok) {
 328         return PyErr_NoMemory();
 329     }
 330
 331     return PyLong_FromUnsignedLong(serial);
 332 }
 333
 334 /* The timeout is in seconds here, since that's conventional in Python. */
 335 PyDoc_STRVAR(Connection_send_message_with_reply__doc__,
 336 "send_message_with_reply(msg, reply_handler, timeout_s=-1, "
 337 "require_main_loop=False) -> dbus.lowlevel.PendingCall\n\n"
 338 "Queue the message for sending; expect a reply via the returned PendingCall,\n"
 339 "which can also be used to cancel the pending call.\n"
 340 "\n"
 341 ":Parameters:\n"
 342 "   `msg` : dbus.lowlevel.Message\n"
 343 "       The message to be sent\n"
 344 "   `reply_handler` : callable\n"
 345 "       Asynchronous reply handler: will be called with one positional\n"
 346 "       parameter, a Message instance representing the reply.\n"
 347 "   `timeout_s` : float\n"
 348 "       If the reply takes more than this many seconds, a timeout error\n"
 349 "       will be created locally and raised instead. If this timeout is\n"
 350 "       negative (default), a sane default (supplied by libdbus) is used.\n"
 351 "   `require_main_loop` : bool\n"
 352 "       If True, raise RuntimeError if this Connection does not have a main\n"
 353 "       loop configured. If False (default) and there is no main loop, you are\n"
 354 "       responsible for calling block() on the PendingCall.\n"
 355 "\n"
 356 );
 357 static PyObject *
 358 Connection_send_message_with_reply(Connection *self, PyObject *args, PyObject *kw)
 359 {
 360     dbus_bool_t ok;
 361     double timeout_s = -1.0;
 362     int timeout_ms;
 363     PyObject *obj, *callable;
 364     DBusMessage *msg;
 365     DBusPendingCall *pending;
 366     int require_main_loop = 0;
 367     static char *argnames[] = {"msg", "reply_handler", "timeout_s",
 368                                "require_main_loop", NULL};
 369
 370     TRACE(self);
 371     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 372     if (!PyArg_ParseTupleAndKeywords(args, kw,
 373                                      "OO|fi:send_message_with_reply",
 374                                      argnames,
 375                                      &obj, &callable, &timeout_s,
 376                                      &require_main_loop)) {
 377         return NULL;
 378     }
 379     if (require_main_loop && !Connection__require_main_loop(self, NULL)) {
 380         return NULL;
 381     }
 382
 383     msg = DBusPyMessage_BorrowDBusMessage(obj);
 384     if (!msg) return NULL;
 385
 386     if (timeout_s < 0) {
 387         timeout_ms = -1;
 388     }
 389     else {
 390         if (timeout_s > ((double)INT_MAX) / 1000.0) {
 391             PyErr_SetString(PyExc_ValueError, "Timeout too long");
 392             return NULL;
 393         }
 394         timeout_ms = (int)(timeout_s * 1000.0);
 395     }
 396
 397     Py_BEGIN_ALLOW_THREADS
 398     ok = dbus_connection_send_with_reply(self->conn, msg, &pending,
 399                                          timeout_ms);
 400     Py_END_ALLOW_THREADS
 401
 402     if (!ok) {
 403         return PyErr_NoMemory();
 404     }
 405
 406     return DBusPyPendingCall_ConsumeDBusPendingCall(pending, callable);
 407 }
 408
 409 /* Again, the timeout is in seconds, since that's conventional in Python. */
 410 PyDoc_STRVAR(Connection_send_message_with_reply_and_block__doc__,
 411 "send_message_with_reply_and_block(msg, timeout_s=-1)"
 412 " -> dbus.lowlevel.Message\n\n"
 413 "Send the message and block while waiting for a reply.\n"
 414 "\n"
 415 "This does not re-enter the main loop, so it can lead to a deadlock, if\n"
 416 "the called method tries to make a synchronous call to a method in this\n"
 417 "application. As such, it's probably a bad idea.\n"
 418 "\n"
 419 ":Parameters:\n"
 420 "   `msg` : dbus.lowlevel.Message\n"
 421 "       The message to be sent\n"
 422 "   `timeout_s` : float\n"
 423 "       If the reply takes more than this many seconds, a timeout error\n"
 424 "       will be created locally and raised instead. If this timeout is\n"
 425 "       negative (default), a sane default (supplied by libdbus) is used.\n"
 426 ":Returns:\n"
 427 "   A `dbus.lowlevel.Message` instance (probably a `dbus.lowlevel.MethodReturnMessage`) on success\n"
 428 ":Raises dbus.DBusException:\n"
 429 "   On error (including if the reply arrives but is an\n"
 430 "   error message)\n"
 431 "\n"
 432 );
 433 static PyObject *
 434 Connection_send_message_with_reply_and_block(Connection *self, PyObject *args)
 435 {
 436     double timeout_s = -1.0;
 437     int timeout_ms;
 438     PyObject *obj;
 439     DBusMessage *msg, *reply;
 440     DBusError error;
 441
 442     TRACE(self);
 443     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 444     if (!PyArg_ParseTuple(args, "O|f:send_message_with_reply_and_block", &obj,
 445                           &timeout_s)) {
 446         return NULL;
 447     }
 448
 449     msg = DBusPyMessage_BorrowDBusMessage(obj);
 450     if (!msg) return NULL;
 451
 452     if (timeout_s < 0) {
 453         timeout_ms = -1;
 454     }
 455     else {
 456         if (timeout_s > ((double)INT_MAX) / 1000.0) {
 457             PyErr_SetString(PyExc_ValueError, "Timeout too long");
 458             return NULL;
 459         }
 460         timeout_ms = (int)(timeout_s * 1000.0);
 461     }
 462
 463     dbus_error_init(&error);
 464     Py_BEGIN_ALLOW_THREADS
 465     reply = dbus_connection_send_with_reply_and_block(self->conn, msg,
 466                                                       timeout_ms, &error);
 467     Py_END_ALLOW_THREADS
 468
 469     if (!reply) {
 470         return DBusPyException_ConsumeError(&error);
 471     }
 472     return DBusPyMessage_ConsumeDBusMessage(reply);
 473 }
 474
 475 PyDoc_STRVAR(Connection_flush__doc__,
 476 "flush()\n\n"
 477 "Block until the outgoing message queue is empty.\n");
 478 static PyObject *
 479 Connection_flush (Connection *self, PyObject *args UNUSED)
 480 {
 481     TRACE(self);
 482     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 483     Py_BEGIN_ALLOW_THREADS
 484     dbus_connection_flush (self->conn);
 485     Py_END_ALLOW_THREADS
 486     Py_RETURN_NONE;
 487 }
 488
 489 /* Unsupported:
 490  * dbus_connection_preallocate_send
 491  * dbus_connection_free_preallocated_send
 492  * dbus_connection_send_preallocated
 493  * dbus_connection_borrow_message
 494  * dbus_connection_return_message
 495  * dbus_connection_steal_borrowed_message
 496  * dbus_connection_pop_message
 497  */
 498
 499 /* Non-main-loop handling not yet implemented: */
 500     /* dbus_connection_read_write_dispatch */
 501     /* dbus_connection_read_write */
 502
 503 /* Main loop handling not yet implemented: */
 504     /* dbus_connection_get_dispatch_status */
 505     /* dbus_connection_dispatch */
 506     /* dbus_connection_set_watch_functions */
 507     /* dbus_connection_set_timeout_functions */
 508     /* dbus_connection_set_wakeup_main_function */
 509     /* dbus_connection_set_dispatch_status_function */
 510
 511 /* Normally in Python this would be called fileno(), but I don't want to
 512  * encourage people to select() on it */
 513 PyDoc_STRVAR(Connection_get_unix_fd__doc__,
 514 "get_unix_fd() -> int or None\n\n"
 515 "Get the connection's UNIX file descriptor, if any.\n\n"
 516 "This can be used for SELinux access control checks with ``getpeercon()``\n"
 517 "for example. **Do not** read or write to the file descriptor, or try to\n"
 518 "``select()`` on it.\n");
 519 static PyObject *
 520 Connection_get_unix_fd (Connection *self, PyObject *unused UNUSED)
 521 {
 522     int fd;
 523     dbus_bool_t ok;
 524
 525     TRACE(self);
 526     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 527     Py_BEGIN_ALLOW_THREADS
 528     ok = dbus_connection_get_unix_fd (self->conn, &fd);
 529     Py_END_ALLOW_THREADS
 530     if (!ok) Py_RETURN_NONE;
 531     return PyInt_FromLong(fd);
 532 }
 533
 534 PyDoc_STRVAR(Connection_get_peer_unix_user__doc__,
 535 "get_peer_unix_user() -> long or None\n\n"
 536 "Get the UNIX user ID at the other end of the connection, if it has been\n"
 537 "authenticated. Return None if this is a non-UNIX platform or the\n"
 538 "connection has not been authenticated.\n");
 539 static PyObject *
 540 Connection_get_peer_unix_user (Connection *self, PyObject *unused UNUSED)
 541 {
 542     unsigned long uid;
 543     dbus_bool_t ok;
 544
 545     TRACE(self);
 546     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 547     Py_BEGIN_ALLOW_THREADS
 548     ok = dbus_connection_get_unix_user (self->conn, &uid);
 549     Py_END_ALLOW_THREADS
 550     if (!ok) Py_RETURN_NONE;
 551     return PyLong_FromUnsignedLong (uid);
 552 }
 553
 554 PyDoc_STRVAR(Connection_get_peer_unix_process_id__doc__,
 555 "get_peer_unix_process_id() -> long or None\n\n"
 556 "Get the UNIX process ID at the other end of the connection, if it has been\n"
 557 "authenticated. Return None if this is a non-UNIX platform or the\n"
 558 "connection has not been authenticated.\n");
 559 static PyObject *
 560 Connection_get_peer_unix_process_id (Connection *self, PyObject *unused UNUSED)
 561 {
 562     unsigned long pid;
 563     dbus_bool_t ok;
 564
 565     TRACE(self);
 566     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 567     Py_BEGIN_ALLOW_THREADS
 568     ok = dbus_connection_get_unix_process_id (self->conn, &pid);
 569     Py_END_ALLOW_THREADS
 570     if (!ok) Py_RETURN_NONE;
 571     return PyLong_FromUnsignedLong (pid);
 572 }
 573
 574 /* TODO: wrap dbus_connection_set_unix_user_function Pythonically */
 575
 576 PyDoc_STRVAR(Connection_add_message_filter__doc__,
 577 "add_message_filter(callable)\n\n"
 578 "Add the given message filter to the internal list.\n\n"
 579 "Filters are handlers that are run on all incoming messages, prior to the\n"
 580 "objects registered to handle object paths.\n"
 581 "\n"
 582 "Filters are run in the order that they were added. The same handler can\n"
 583 "be added as a filter more than once, in which case it will be run more\n"
 584 "than once. Filters added during a filter callback won't be run on the\n"
 585 "message being processed.\n"
 586 );
 587 static PyObject *
 588 Connection_add_message_filter(Connection *self, PyObject *callable)
 589 {
 590     dbus_bool_t ok;
 591
 592     TRACE(self);
 593     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 594     /* The callable must be referenced by ->filters *before* it is
 595      * given to libdbus, which does not own a reference to it.
 596      */
 597     if (PyList_Append(self->filters, callable) < 0) {
 598         return NULL;
 599     }
 600
 601     Py_BEGIN_ALLOW_THREADS
 602     ok = dbus_connection_add_filter(self->conn, _filter_message, callable,
 603                                     NULL);
 604     Py_END_ALLOW_THREADS
 605
 606     if (!ok) {
 607         Py_XDECREF(PyObject_CallMethod(self->filters, "remove", "(O)",
 608                                        callable));
 609         PyErr_NoMemory();
 610         return NULL;
 611     }
 612     Py_RETURN_NONE;
 613 }
 614
 615 PyDoc_STRVAR(Connection_remove_message_filter__doc__,
 616 "remove_message_filter(callable)\n\n"
 617 "Remove the given message filter (see `add_message_filter` for details).\n"
 618 "\n"
 619 ":Raises LookupError:\n"
 620 "   The given callable is not among the registered filters\n");
 621 static PyObject *
 622 Connection_remove_message_filter(Connection *self, PyObject *callable)
 623 {
 624     PyObject *obj;
 625
 626     TRACE(self);
 627     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 628     /* It's safe to do this before removing it from libdbus, because
 629      * the presence of callable in our arguments means we have a ref
 630      * to it. */
 631     obj = PyObject_CallMethod(self->filters, "remove", "(O)", callable);
 632     if (!obj) return NULL;
 633     Py_DECREF(obj);
 634
 635     Py_BEGIN_ALLOW_THREADS
 636     dbus_connection_remove_filter(self->conn, _filter_message, callable);
 637     Py_END_ALLOW_THREADS
 638
 639     Py_RETURN_NONE;
 640 }
 641
 642 PyDoc_STRVAR(Connection__register_object_path__doc__,
 643 "register_object_path(path, on_message, on_unregister=None, fallback=False)\n"
 644 "\n"
 645 "Register a callback to be called when messages arrive at the given\n"
 646 "object-path. Used to export objects' methods on the bus in a low-level\n"
 647 "way. For the high-level interface to this functionality (usually\n"
 648 "recommended) see the `dbus.service.Object` base class.\n"
 649 "\n"
 650 ":Parameters:\n"
 651 "   `path` : str\n"
 652 "       Object path to be acted on\n"
 653 "   `on_message` : callable\n"
 654 "       Called when a message arrives at the given object-path, with\n"
 655 "       two positional parameters: the first is this Connection,\n"
 656 "       the second is the incoming `dbus.lowlevel.Message`.\n"
 657 "   `on_unregister` : callable or None\n"
 658 "       If not None, called when the callback is unregistered.\n"
 659 "   `fallback` : bool\n"
 660 "       If True (the default is False), when a message arrives for a\n"
 661 "       'subdirectory' of the given path and there is no more specific\n"
 662 "       handler, use this handler. Normally this handler is only run if\n"
 663 "       the paths match exactly.\n"
 664 );
 665 static PyObject *
 666 Connection__register_object_path(Connection *self, PyObject *args,
 667                                  PyObject *kwargs)
 668 {
 669     dbus_bool_t ok;
 670     int fallback = 0;
 671     PyObject *callbacks, *path, *tuple, *on_message, *on_unregister = Py_None;
 672     static char *argnames[] = {"path", "on_message", "on_unregister",
 673                                "fallback", NULL};
 674
 675     TRACE(self);
 676     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 677     if (!Connection__require_main_loop(self, NULL)) {
 678         return NULL;
 679     }
 680     if (!PyArg_ParseTupleAndKeywords(args, kwargs,
 681                                      "OO|Oi:_register_object_path",
 682                                      argnames,
 683                                      &path,
 684                                      &on_message, &on_unregister,
 685                                      &fallback)) return NULL;
 686
 687     /* Take a reference to path, which we give away to libdbus in a moment.
 688
 689     Also, path needs to be a string (not a subclass which could do something
 690     mad) to preserve the desirable property that the DBusConnection can
 691     never strongly reference the Connection, even indirectly.
 692     */
 693     if (PyString_CheckExact(path)) {
 694         Py_INCREF(path);
 695     }
 696     else if (PyUnicode_Check(path)) {
 697         path = PyUnicode_AsUTF8String(path);
 698         if (!path) return NULL;
 699     }
 700     else if (PyString_Check(path)) {
 701         path = PyString_FromString(PyString_AS_STRING(path));
 702         if (!path) return NULL;
 703     }
 704     else {
 705         PyErr_SetString(PyExc_TypeError, "path must be a str or unicode object");
 706         return NULL;
 707     }
 708
 709     if (!dbus_py_validate_object_path(PyString_AS_STRING(path))) {
 710         Py_DECREF(path);
 711         return NULL;
 712     }
 713
 714     tuple = Py_BuildValue("(OO)", on_unregister, on_message);
 715     if (!tuple) {
 716         Py_DECREF(path);
 717         return NULL;
 718     }
 719
 720     /* Guard against registering a handler that already exists. */
 721     callbacks = PyDict_GetItem(self->object_paths, path);
 722     if (callbacks && callbacks != Py_None) {
 723         PyErr_Format(PyExc_KeyError, "Can't register the object-path "
 724                      "handler for '%s': there is already a handler",
 725                      PyString_AS_STRING(path));
 726         Py_DECREF(tuple);
 727         Py_DECREF(path);
 728         return NULL;
 729     }
 730
 731     /* Pre-allocate a slot in the dictionary, so we know we'll be able
 732      * to replace it with the callbacks without OOM.
 733      * This ensures we can keep libdbus' opinion of whether those
 734      * paths are handled in sync with our own. */
 735     if (PyDict_SetItem(self->object_paths, path, Py_None) < 0) {
 736         Py_DECREF(tuple);
 737         Py_DECREF(path);
 738         return NULL;
 739     }
 740
 741     Py_BEGIN_ALLOW_THREADS
 742     if (fallback) {
 743         ok = dbus_connection_register_fallback(self->conn,
 744                                                PyString_AS_STRING(path),
 745                                                &_object_path_vtable,
 746                                                path);
 747     }
 748     else {
 749         ok = dbus_connection_register_object_path(self->conn,
 750                                                   PyString_AS_STRING(path),
 751                                                   &_object_path_vtable,
 752                                                   path);
 753     }
 754     Py_END_ALLOW_THREADS
 755
 756     if (ok) {
 757         if (PyDict_SetItem(self->object_paths, path, tuple) < 0) {
 758             /* That shouldn't have happened, we already allocated enough
 759             memory for it. Oh well, try to undo the registration to keep
 760             things in sync. If this fails too, we've leaked a bit of
 761             memory in libdbus, but tbh we should never get here anyway. */
 762             Py_BEGIN_ALLOW_THREADS
 763             ok = dbus_connection_unregister_object_path(self->conn,
 764                                                     PyString_AS_STRING(path));
 765             Py_END_ALLOW_THREADS
 766             return NULL;
 767         }
 768         /* don't DECREF path: libdbus owns a ref now */
 769         Py_DECREF(tuple);
 770         Py_RETURN_NONE;
 771     }
 772     else {
 773         /* Oops, OOM. Tidy up, if we can, ignoring any error. */
 774         PyDict_DelItem(self->object_paths, path);
 775         PyErr_Clear();
 776         Py_DECREF(tuple);
 777         Py_DECREF(path);
 778         PyErr_NoMemory();
 779         return NULL;
 780     }
 781 }
 782
 783 PyDoc_STRVAR(Connection__unregister_object_path__doc__,
 784 "unregister_object_path(path)\n\n"
 785 "Remove a previously registered handler for the given object path.\n"
 786 "\n"
 787 ":Parameters:\n"
 788 "   `path` : str\n"
 789 "       The object path whose handler is to be removed\n"
 790 ":Raises KeyError: if there is no handler registered for exactly that\n"
 791 "   object path.\n"
 792 );
 793 static PyObject *
 794 Connection__unregister_object_path(Connection *self, PyObject *args,
 795                                    PyObject *kwargs)
 796 {
 797     dbus_bool_t ok;
 798     PyObject *path;
 799     PyObject *callbacks;
 800     static char *argnames[] = {"path", NULL};
 801
 802     TRACE(self);
 803     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 804     if (!PyArg_ParseTupleAndKeywords(args, kwargs,
 805                                      "O:_unregister_object_path",
 806                                      argnames, &path)) return NULL;
 807
 808     /* Take a ref to the path. Same comments as for _register_object_path. */
 809     if (PyString_CheckExact(path)) {
 810         Py_INCREF(path);
 811     }
 812     else if (PyUnicode_Check(path)) {
 813         path = PyUnicode_AsUTF8String(path);
 814         if (!path) return NULL;
 815     }
 816     else if (PyString_Check(path)) {
 817         path = PyString_FromString(PyString_AS_STRING(path));
 818         if (!path) return NULL;
 819     }
 820     else {
 821         PyErr_SetString(PyExc_TypeError, "path must be a str or unicode object");
 822         return NULL;
 823     }
 824
 825     /* Guard against unregistering a handler that doesn't, in fact, exist,
 826     or whose unregistration is already in progress. */
 827     callbacks = PyDict_GetItem(self->object_paths, path);
 828     if (!callbacks || callbacks == Py_None) {
 829         PyErr_Format(PyExc_KeyError, "Can't unregister the object-path "
 830                      "handler for '%s': there is no such handler",
 831                      PyString_AS_STRING(path));
 832         Py_DECREF(path);
 833         return NULL;
 834     }
 835
 836     /* Hang on to a reference to the callbacks for the moment. */
 837     Py_INCREF(callbacks);
 838
 839     /* Get rid of the object-path while we still have the GIL, to
 840     guard against unregistering twice from different threads (which
 841     causes undefined behaviour in libdbus).
 842
 843     Because deletion would make it possible for the re-insertion below
 844     to fail, we instead set the handler to None as a placeholder.
 845     */
 846     if (PyDict_SetItem(self->object_paths, path, Py_None) < 0) {
 847         /* If that failed, there's no need to be paranoid as below - the
 848         callbacks are still set, so we failed, but at least everything
 849         is in sync. */
 850         Py_DECREF(callbacks);
 851         Py_DECREF(path);
 852         return NULL;
 853     }
 854
 855     /* BEGIN PARANOIA
 856     This is something of a critical section - the dict of object-paths
 857     and libdbus' internal structures are out of sync for a bit. We have
 858     to be able to cope with that.
 859
 860     It's really annoying that dbus_connection_unregister_object_path
 861     can fail, *and* has undefined behaviour if the object path has
 862     already been unregistered. Either/or would be fine.
 863     */
 864
 865     Py_BEGIN_ALLOW_THREADS
 866     ok = dbus_connection_unregister_object_path(self->conn,
 867                                                 PyString_AS_STRING(path));
 868     Py_END_ALLOW_THREADS
 869
 870     if (ok) {
 871         Py_DECREF(callbacks);
 872         PyDict_DelItem(self->object_paths, path);
 873         /* END PARANOIA on successful code path */
 874         /* The above can't fail unless by some strange trickery the key is no
 875         longer present. Ignore any errors. */
 876         Py_DECREF(path);
 877         PyErr_Clear();
 878         Py_RETURN_NONE;
 879     }
 880     else {
 881         /* Oops, OOM. Put the callbacks back in the dict so
 882          * we'll have another go if/when the user frees some memory
 883          * and tries calling this method again. */
 884         PyDict_SetItem(self->object_paths, path, callbacks);
 885         /* END PARANOIA on failing code path */
 886         /* If the SetItem failed, there's nothing we can do about it - but
 887         since we know it's an existing entry, it shouldn't be able to fail
 888         anyway. */
 889         Py_DECREF(path);
 890         Py_DECREF(callbacks);
 891         return PyErr_NoMemory();
 892     }
 893 }
 894
 895     /* dbus_connection_get_object_path_data - not useful to Python,
 896      * the object path data is just a PyString containing the path */
 897     /* dbus_connection_list_registered could be useful, though */
 898
 899 /* dbus_connection_set_change_sigpipe - sets global state */
 900
 901 /* Maxima. Does Python code ever need to manipulate these?
 902  * OTOH they're easy to wrap */
 903     /* dbus_connection_set_max_message_size */
 904     /* dbus_connection_get_max_message_size */
 905     /* dbus_connection_set_max_received_size */
 906     /* dbus_connection_get_max_received_size */
 907
 908 /* dbus_connection_get_outgoing_size - almost certainly unneeded */
 909
 910 struct PyMethodDef DBusPyConnection_tp_methods[] = {
 911 #define ENTRY(name, flags) {#name, (PyCFunction)Connection_##name, flags, Connection_##name##__doc__}
 912     ENTRY(_require_main_loop, METH_NOARGS),
 913     ENTRY(close, METH_NOARGS),
 914     ENTRY(flush, METH_NOARGS),
 915     ENTRY(get_is_connected, METH_NOARGS),
 916     ENTRY(get_is_authenticated, METH_NOARGS),
 917     ENTRY(set_exit_on_disconnect, METH_VARARGS),
 918     ENTRY(get_unix_fd, METH_NOARGS),
 919     ENTRY(get_peer_unix_user, METH_NOARGS),
 920     ENTRY(get_peer_unix_process_id, METH_NOARGS),
 921     ENTRY(add_message_filter, METH_O),
 922     ENTRY(_register_object_path, METH_VARARGS|METH_KEYWORDS),
 923     ENTRY(remove_message_filter, METH_O),
 924     ENTRY(send_message, METH_VARARGS),
 925     ENTRY(send_message_with_reply, METH_VARARGS|METH_KEYWORDS),
 926     ENTRY(send_message_with_reply_and_block, METH_VARARGS),
 927     ENTRY(_unregister_object_path, METH_VARARGS|METH_KEYWORDS),
 928     {NULL},
 929 #undef ENTRY
 930 };
 931
 932 /* vim:set ft=c cino< sw=4 sts=4 et: */