_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     if (!pending) {
 407         /* connection is disconnected (doesn't return FALSE!) */
 408         return DBusPyException_SetString ("Connection is disconnected - "
 409                                           "unable to make method call");
 410     }
 411
 412     return DBusPyPendingCall_ConsumeDBusPendingCall(pending, callable);
 413 }
 414
 415 /* Again, the timeout is in seconds, since that's conventional in Python. */
 416 PyDoc_STRVAR(Connection_send_message_with_reply_and_block__doc__,
 417 "send_message_with_reply_and_block(msg, timeout_s=-1)"
 418 " -> dbus.lowlevel.Message\n\n"
 419 "Send the message and block while waiting for a reply.\n"
 420 "\n"
 421 "This does not re-enter the main loop, so it can lead to a deadlock, if\n"
 422 "the called method tries to make a synchronous call to a method in this\n"
 423 "application. As such, it's probably a bad idea.\n"
 424 "\n"
 425 ":Parameters:\n"
 426 "   `msg` : dbus.lowlevel.Message\n"
 427 "       The message to be sent\n"
 428 "   `timeout_s` : float\n"
 429 "       If the reply takes more than this many seconds, a timeout error\n"
 430 "       will be created locally and raised instead. If this timeout is\n"
 431 "       negative (default), a sane default (supplied by libdbus) is used.\n"
 432 ":Returns:\n"
 433 "   A `dbus.lowlevel.Message` instance (probably a `dbus.lowlevel.MethodReturnMessage`) on success\n"
 434 ":Raises dbus.DBusException:\n"
 435 "   On error (including if the reply arrives but is an\n"
 436 "   error message)\n"
 437 "\n"
 438 );
 439 static PyObject *
 440 Connection_send_message_with_reply_and_block(Connection *self, PyObject *args)
 441 {
 442     double timeout_s = -1.0;
 443     int timeout_ms;
 444     PyObject *obj;
 445     DBusMessage *msg, *reply;
 446     DBusError error;
 447
 448     TRACE(self);
 449     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 450     if (!PyArg_ParseTuple(args, "O|f:send_message_with_reply_and_block", &obj,
 451                           &timeout_s)) {
 452         return NULL;
 453     }
 454
 455     msg = DBusPyMessage_BorrowDBusMessage(obj);
 456     if (!msg) return NULL;
 457
 458     if (timeout_s < 0) {
 459         timeout_ms = -1;
 460     }
 461     else {
 462         if (timeout_s > ((double)INT_MAX) / 1000.0) {
 463             PyErr_SetString(PyExc_ValueError, "Timeout too long");
 464             return NULL;
 465         }
 466         timeout_ms = (int)(timeout_s * 1000.0);
 467     }
 468
 469     dbus_error_init(&error);
 470     Py_BEGIN_ALLOW_THREADS
 471     reply = dbus_connection_send_with_reply_and_block(self->conn, msg,
 472                                                       timeout_ms, &error);
 473     Py_END_ALLOW_THREADS
 474
 475     /* FIXME: if we instead used send_with_reply and blocked on the resulting
 476      * PendingCall, then we could get all args from the error, not just
 477      * the first */
 478     if (!reply) {
 479         return DBusPyException_ConsumeError(&error);
 480     }
 481     return DBusPyMessage_ConsumeDBusMessage(reply);
 482 }
 483
 484 PyDoc_STRVAR(Connection_flush__doc__,
 485 "flush()\n\n"
 486 "Block until the outgoing message queue is empty.\n");
 487 static PyObject *
 488 Connection_flush (Connection *self, PyObject *args UNUSED)
 489 {
 490     TRACE(self);
 491     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 492     Py_BEGIN_ALLOW_THREADS
 493     dbus_connection_flush (self->conn);
 494     Py_END_ALLOW_THREADS
 495     Py_RETURN_NONE;
 496 }
 497
 498 /* Unsupported:
 499  * dbus_connection_preallocate_send
 500  * dbus_connection_free_preallocated_send
 501  * dbus_connection_send_preallocated
 502  * dbus_connection_borrow_message
 503  * dbus_connection_return_message
 504  * dbus_connection_steal_borrowed_message
 505  * dbus_connection_pop_message
 506  */
 507
 508 /* Non-main-loop handling not yet implemented: */
 509     /* dbus_connection_read_write_dispatch */
 510     /* dbus_connection_read_write */
 511
 512 /* Main loop handling not yet implemented: */
 513     /* dbus_connection_get_dispatch_status */
 514     /* dbus_connection_dispatch */
 515     /* dbus_connection_set_watch_functions */
 516     /* dbus_connection_set_timeout_functions */
 517     /* dbus_connection_set_wakeup_main_function */
 518     /* dbus_connection_set_dispatch_status_function */
 519
 520 /* Normally in Python this would be called fileno(), but I don't want to
 521  * encourage people to select() on it */
 522 PyDoc_STRVAR(Connection_get_unix_fd__doc__,
 523 "get_unix_fd() -> int or None\n\n"
 524 "Get the connection's UNIX file descriptor, if any.\n\n"
 525 "This can be used for SELinux access control checks with ``getpeercon()``\n"
 526 "for example. **Do not** read or write to the file descriptor, or try to\n"
 527 "``select()`` on it.\n");
 528 static PyObject *
 529 Connection_get_unix_fd (Connection *self, PyObject *unused UNUSED)
 530 {
 531     int fd;
 532     dbus_bool_t ok;
 533
 534     TRACE(self);
 535     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 536     Py_BEGIN_ALLOW_THREADS
 537     ok = dbus_connection_get_unix_fd (self->conn, &fd);
 538     Py_END_ALLOW_THREADS
 539     if (!ok) Py_RETURN_NONE;
 540     return PyInt_FromLong(fd);
 541 }
 542
 543 PyDoc_STRVAR(Connection_get_peer_unix_user__doc__,
 544 "get_peer_unix_user() -> long or None\n\n"
 545 "Get the UNIX user ID at the other end of the connection, if it has been\n"
 546 "authenticated. Return None if this is a non-UNIX platform or the\n"
 547 "connection has not been authenticated.\n");
 548 static PyObject *
 549 Connection_get_peer_unix_user (Connection *self, PyObject *unused UNUSED)
 550 {
 551     unsigned long uid;
 552     dbus_bool_t ok;
 553
 554     TRACE(self);
 555     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 556     Py_BEGIN_ALLOW_THREADS
 557     ok = dbus_connection_get_unix_user (self->conn, &uid);
 558     Py_END_ALLOW_THREADS
 559     if (!ok) Py_RETURN_NONE;
 560     return PyLong_FromUnsignedLong (uid);
 561 }
 562
 563 PyDoc_STRVAR(Connection_get_peer_unix_process_id__doc__,
 564 "get_peer_unix_process_id() -> long or None\n\n"
 565 "Get the UNIX process ID at the other end of the connection, if it has been\n"
 566 "authenticated. Return None if this is a non-UNIX platform or the\n"
 567 "connection has not been authenticated.\n");
 568 static PyObject *
 569 Connection_get_peer_unix_process_id (Connection *self, PyObject *unused UNUSED)
 570 {
 571     unsigned long pid;
 572     dbus_bool_t ok;
 573
 574     TRACE(self);
 575     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 576     Py_BEGIN_ALLOW_THREADS
 577     ok = dbus_connection_get_unix_process_id (self->conn, &pid);
 578     Py_END_ALLOW_THREADS
 579     if (!ok) Py_RETURN_NONE;
 580     return PyLong_FromUnsignedLong (pid);
 581 }
 582
 583 /* TODO: wrap dbus_connection_set_unix_user_function Pythonically */
 584
 585 PyDoc_STRVAR(Connection_add_message_filter__doc__,
 586 "add_message_filter(callable)\n\n"
 587 "Add the given message filter to the internal list.\n\n"
 588 "Filters are handlers that are run on all incoming messages, prior to the\n"
 589 "objects registered to handle object paths.\n"
 590 "\n"
 591 "Filters are run in the order that they were added. The same handler can\n"
 592 "be added as a filter more than once, in which case it will be run more\n"
 593 "than once. Filters added during a filter callback won't be run on the\n"
 594 "message being processed.\n"
 595 );
 596 static PyObject *
 597 Connection_add_message_filter(Connection *self, PyObject *callable)
 598 {
 599     dbus_bool_t ok;
 600
 601     TRACE(self);
 602     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 603     /* The callable must be referenced by ->filters *before* it is
 604      * given to libdbus, which does not own a reference to it.
 605      */
 606     if (PyList_Append(self->filters, callable) < 0) {
 607         return NULL;
 608     }
 609
 610     Py_BEGIN_ALLOW_THREADS
 611     ok = dbus_connection_add_filter(self->conn, _filter_message, callable,
 612                                     NULL);
 613     Py_END_ALLOW_THREADS
 614
 615     if (!ok) {
 616         Py_XDECREF(PyObject_CallMethod(self->filters, "remove", "(O)",
 617                                        callable));
 618         PyErr_NoMemory();
 619         return NULL;
 620     }
 621     Py_RETURN_NONE;
 622 }
 623
 624 PyDoc_STRVAR(Connection_remove_message_filter__doc__,
 625 "remove_message_filter(callable)\n\n"
 626 "Remove the given message filter (see `add_message_filter` for details).\n"
 627 "\n"
 628 ":Raises LookupError:\n"
 629 "   The given callable is not among the registered filters\n");
 630 static PyObject *
 631 Connection_remove_message_filter(Connection *self, PyObject *callable)
 632 {
 633     PyObject *obj;
 634
 635     TRACE(self);
 636     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 637     /* It's safe to do this before removing it from libdbus, because
 638      * the presence of callable in our arguments means we have a ref
 639      * to it. */
 640     obj = PyObject_CallMethod(self->filters, "remove", "(O)", callable);
 641     if (!obj) return NULL;
 642     Py_DECREF(obj);
 643
 644     Py_BEGIN_ALLOW_THREADS
 645     dbus_connection_remove_filter(self->conn, _filter_message, callable);
 646     Py_END_ALLOW_THREADS
 647
 648     Py_RETURN_NONE;
 649 }
 650
 651 PyDoc_STRVAR(Connection__register_object_path__doc__,
 652 "register_object_path(path, on_message, on_unregister=None, fallback=False)\n"
 653 "\n"
 654 "Register a callback to be called when messages arrive at the given\n"
 655 "object-path. Used to export objects' methods on the bus in a low-level\n"
 656 "way. For the high-level interface to this functionality (usually\n"
 657 "recommended) see the `dbus.service.Object` base class.\n"
 658 "\n"
 659 ":Parameters:\n"
 660 "   `path` : str\n"
 661 "       Object path to be acted on\n"
 662 "   `on_message` : callable\n"
 663 "       Called when a message arrives at the given object-path, with\n"
 664 "       two positional parameters: the first is this Connection,\n"
 665 "       the second is the incoming `dbus.lowlevel.Message`.\n"
 666 "   `on_unregister` : callable or None\n"
 667 "       If not None, called when the callback is unregistered.\n"
 668 "   `fallback` : bool\n"
 669 "       If True (the default is False), when a message arrives for a\n"
 670 "       'subdirectory' of the given path and there is no more specific\n"
 671 "       handler, use this handler. Normally this handler is only run if\n"
 672 "       the paths match exactly.\n"
 673 );
 674 static PyObject *
 675 Connection__register_object_path(Connection *self, PyObject *args,
 676                                  PyObject *kwargs)
 677 {
 678     dbus_bool_t ok;
 679     int fallback = 0;
 680     PyObject *callbacks, *path, *tuple, *on_message, *on_unregister = Py_None;
 681     static char *argnames[] = {"path", "on_message", "on_unregister",
 682                                "fallback", NULL};
 683
 684     TRACE(self);
 685     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 686     if (!Connection__require_main_loop(self, NULL)) {
 687         return NULL;
 688     }
 689     if (!PyArg_ParseTupleAndKeywords(args, kwargs,
 690                                      "OO|Oi:_register_object_path",
 691                                      argnames,
 692                                      &path,
 693                                      &on_message, &on_unregister,
 694                                      &fallback)) return NULL;
 695
 696     /* Take a reference to path, which we give away to libdbus in a moment.
 697
 698     Also, path needs to be a string (not a subclass which could do something
 699     mad) to preserve the desirable property that the DBusConnection can
 700     never strongly reference the Connection, even indirectly.
 701     */
 702     if (PyString_CheckExact(path)) {
 703         Py_INCREF(path);
 704     }
 705     else if (PyUnicode_Check(path)) {
 706         path = PyUnicode_AsUTF8String(path);
 707         if (!path) return NULL;
 708     }
 709     else if (PyString_Check(path)) {
 710         path = PyString_FromString(PyString_AS_STRING(path));
 711         if (!path) return NULL;
 712     }
 713     else {
 714         PyErr_SetString(PyExc_TypeError, "path must be a str or unicode object");
 715         return NULL;
 716     }
 717
 718     if (!dbus_py_validate_object_path(PyString_AS_STRING(path))) {
 719         Py_DECREF(path);
 720         return NULL;
 721     }
 722
 723     tuple = Py_BuildValue("(OO)", on_unregister, on_message);
 724     if (!tuple) {
 725         Py_DECREF(path);
 726         return NULL;
 727     }
 728
 729     /* Guard against registering a handler that already exists. */
 730     callbacks = PyDict_GetItem(self->object_paths, path);
 731     if (callbacks && callbacks != Py_None) {
 732         PyErr_Format(PyExc_KeyError, "Can't register the object-path "
 733                      "handler for '%s': there is already a handler",
 734                      PyString_AS_STRING(path));
 735         Py_DECREF(tuple);
 736         Py_DECREF(path);
 737         return NULL;
 738     }
 739
 740     /* Pre-allocate a slot in the dictionary, so we know we'll be able
 741      * to replace it with the callbacks without OOM.
 742      * This ensures we can keep libdbus' opinion of whether those
 743      * paths are handled in sync with our own. */
 744     if (PyDict_SetItem(self->object_paths, path, Py_None) < 0) {
 745         Py_DECREF(tuple);
 746         Py_DECREF(path);
 747         return NULL;
 748     }
 749
 750     Py_BEGIN_ALLOW_THREADS
 751     if (fallback) {
 752         ok = dbus_connection_register_fallback(self->conn,
 753                                                PyString_AS_STRING(path),
 754                                                &_object_path_vtable,
 755                                                path);
 756     }
 757     else {
 758         ok = dbus_connection_register_object_path(self->conn,
 759                                                   PyString_AS_STRING(path),
 760                                                   &_object_path_vtable,
 761                                                   path);
 762     }
 763     Py_END_ALLOW_THREADS
 764
 765     if (ok) {
 766         if (PyDict_SetItem(self->object_paths, path, tuple) < 0) {
 767             /* That shouldn't have happened, we already allocated enough
 768             memory for it. Oh well, try to undo the registration to keep
 769             things in sync. If this fails too, we've leaked a bit of
 770             memory in libdbus, but tbh we should never get here anyway. */
 771             Py_BEGIN_ALLOW_THREADS
 772             ok = dbus_connection_unregister_object_path(self->conn,
 773                                                     PyString_AS_STRING(path));
 774             Py_END_ALLOW_THREADS
 775             return NULL;
 776         }
 777         /* don't DECREF path: libdbus owns a ref now */
 778         Py_DECREF(tuple);
 779         Py_RETURN_NONE;
 780     }
 781     else {
 782         /* Oops, OOM. Tidy up, if we can, ignoring any error. */
 783         PyDict_DelItem(self->object_paths, path);
 784         PyErr_Clear();
 785         Py_DECREF(tuple);
 786         Py_DECREF(path);
 787         PyErr_NoMemory();
 788         return NULL;
 789     }
 790 }
 791
 792 PyDoc_STRVAR(Connection__unregister_object_path__doc__,
 793 "unregister_object_path(path)\n\n"
 794 "Remove a previously registered handler for the given object path.\n"
 795 "\n"
 796 ":Parameters:\n"
 797 "   `path` : str\n"
 798 "       The object path whose handler is to be removed\n"
 799 ":Raises KeyError: if there is no handler registered for exactly that\n"
 800 "   object path.\n"
 801 );
 802 static PyObject *
 803 Connection__unregister_object_path(Connection *self, PyObject *args,
 804                                    PyObject *kwargs)
 805 {
 806     dbus_bool_t ok;
 807     PyObject *path;
 808     PyObject *callbacks;
 809     static char *argnames[] = {"path", NULL};
 810
 811     TRACE(self);
 812     DBUS_PY_RAISE_VIA_NULL_IF_FAIL(self->conn);
 813     if (!PyArg_ParseTupleAndKeywords(args, kwargs,
 814                                      "O:_unregister_object_path",
 815                                      argnames, &path)) return NULL;
 816
 817     /* Take a ref to the path. Same comments as for _register_object_path. */
 818     if (PyString_CheckExact(path)) {
 819         Py_INCREF(path);
 820     }
 821     else if (PyUnicode_Check(path)) {
 822         path = PyUnicode_AsUTF8String(path);
 823         if (!path) return NULL;
 824     }
 825     else if (PyString_Check(path)) {
 826         path = PyString_FromString(PyString_AS_STRING(path));
 827         if (!path) return NULL;
 828     }
 829     else {
 830         PyErr_SetString(PyExc_TypeError, "path must be a str or unicode object");
 831         return NULL;
 832     }
 833
 834     /* Guard against unregistering a handler that doesn't, in fact, exist,
 835     or whose unregistration is already in progress. */
 836     callbacks = PyDict_GetItem(self->object_paths, path);
 837     if (!callbacks || callbacks == Py_None) {
 838         PyErr_Format(PyExc_KeyError, "Can't unregister the object-path "
 839                      "handler for '%s': there is no such handler",
 840                      PyString_AS_STRING(path));
 841         Py_DECREF(path);
 842         return NULL;
 843     }
 844
 845     /* Hang on to a reference to the callbacks for the moment. */
 846     Py_INCREF(callbacks);
 847
 848     /* Get rid of the object-path while we still have the GIL, to
 849     guard against unregistering twice from different threads (which
 850     causes undefined behaviour in libdbus).
 851
 852     Because deletion would make it possible for the re-insertion below
 853     to fail, we instead set the handler to None as a placeholder.
 854     */
 855     if (PyDict_SetItem(self->object_paths, path, Py_None) < 0) {
 856         /* If that failed, there's no need to be paranoid as below - the
 857         callbacks are still set, so we failed, but at least everything
 858         is in sync. */
 859         Py_DECREF(callbacks);
 860         Py_DECREF(path);
 861         return NULL;
 862     }
 863
 864     /* BEGIN PARANOIA
 865     This is something of a critical section - the dict of object-paths
 866     and libdbus' internal structures are out of sync for a bit. We have
 867     to be able to cope with that.
 868
 869     It's really annoying that dbus_connection_unregister_object_path
 870     can fail, *and* has undefined behaviour if the object path has
 871     already been unregistered. Either/or would be fine.
 872     */
 873
 874     Py_BEGIN_ALLOW_THREADS
 875     ok = dbus_connection_unregister_object_path(self->conn,
 876                                                 PyString_AS_STRING(path));
 877     Py_END_ALLOW_THREADS
 878
 879     if (ok) {
 880         Py_DECREF(callbacks);
 881         PyDict_DelItem(self->object_paths, path);
 882         /* END PARANOIA on successful code path */
 883         /* The above can't fail unless by some strange trickery the key is no
 884         longer present. Ignore any errors. */
 885         Py_DECREF(path);
 886         PyErr_Clear();
 887         Py_RETURN_NONE;
 888     }
 889     else {
 890         /* Oops, OOM. Put the callbacks back in the dict so
 891          * we'll have another go if/when the user frees some memory
 892          * and tries calling this method again. */
 893         PyDict_SetItem(self->object_paths, path, callbacks);
 894         /* END PARANOIA on failing code path */
 895         /* If the SetItem failed, there's nothing we can do about it - but
 896         since we know it's an existing entry, it shouldn't be able to fail
 897         anyway. */
 898         Py_DECREF(path);
 899         Py_DECREF(callbacks);
 900         return PyErr_NoMemory();
 901     }
 902 }
 903
 904     /* dbus_connection_get_object_path_data - not useful to Python,
 905      * the object path data is just a PyString containing the path */
 906     /* dbus_connection_list_registered could be useful, though */
 907
 908 /* dbus_connection_set_change_sigpipe - sets global state */
 909
 910 /* Maxima. Does Python code ever need to manipulate these?
 911  * OTOH they're easy to wrap */
 912     /* dbus_connection_set_max_message_size */
 913     /* dbus_connection_get_max_message_size */
 914     /* dbus_connection_set_max_received_size */
 915     /* dbus_connection_get_max_received_size */
 916
 917 /* dbus_connection_get_outgoing_size - almost certainly unneeded */
 918
 919 PyDoc_STRVAR(new_for_bus__doc__,
 920 "Connection._new_for_bus([address: str or int]) -> Connection\n"
 921 "\n"
 922 "If the address is an int it must be one of the constants BUS_SESSION,\n"
 923 "BUS_SYSTEM, BUS_STARTER; if a string, it must be a D-Bus address.\n"
 924 "The default is BUS_SESSION.\n"
 925 );
 926
 927 PyDoc_STRVAR(get_unique_name__doc__,
 928 "get_unique_name() -> str\n\n"
 929 "Return this application's unique name on this bus.\n"
 930 "\n"
 931 ":Raises DBusException: if the connection has no unique name yet\n"
 932 "   (for Bus objects this can't happen, for peer-to-peer connections\n"
 933 "   this means you haven't called `set_unique_name`)\n");
 934
 935 PyDoc_STRVAR(set_unique_name__doc__,
 936 "set_unique_name(str)\n\n"
 937 "Set this application's unique name on this bus. Raise ValueError if it has\n"
 938 "already been set.\n");
 939
 940 struct PyMethodDef DBusPyConnection_tp_methods[] = {
 941 #define ENTRY(name, flags) {#name, (PyCFunction)Connection_##name, flags, Connection_##name##__doc__}
 942     ENTRY(_require_main_loop, METH_NOARGS),
 943     ENTRY(close, METH_NOARGS),
 944     ENTRY(flush, METH_NOARGS),
 945     ENTRY(get_is_connected, METH_NOARGS),
 946     ENTRY(get_is_authenticated, METH_NOARGS),
 947     ENTRY(set_exit_on_disconnect, METH_VARARGS),
 948     ENTRY(get_unix_fd, METH_NOARGS),
 949     ENTRY(get_peer_unix_user, METH_NOARGS),
 950     ENTRY(get_peer_unix_process_id, METH_NOARGS),
 951     ENTRY(add_message_filter, METH_O),
 952     ENTRY(_register_object_path, METH_VARARGS|METH_KEYWORDS),
 953     ENTRY(remove_message_filter, METH_O),
 954     ENTRY(send_message, METH_VARARGS),
 955     ENTRY(send_message_with_reply, METH_VARARGS|METH_KEYWORDS),
 956     ENTRY(send_message_with_reply_and_block, METH_VARARGS),
 957     ENTRY(_unregister_object_path, METH_VARARGS|METH_KEYWORDS),
 958     {"_new_for_bus", (PyCFunction)DBusPyConnection_NewForBus,
 959         METH_CLASS|METH_VARARGS|METH_KEYWORDS,
 960         new_for_bus__doc__},
 961     {"get_unique_name", (PyCFunction)DBusPyConnection_GetUniqueName,
 962         METH_NOARGS,
 963         get_unique_name__doc__},
 964     {"set_unique_name", (PyCFunction)DBusPyConnection_SetUniqueName,
 965         METH_VARARGS,
 966         set_unique_name__doc__},
 967     {NULL},
 968 #undef ENTRY
 969 };
 970
 971 /* vim:set ft=c cino< sw=4 sts=4 et: */