dbus/dbus-connection.c

   1 /* -*- mode: C; c-file-style: "gnu" -*- */
   2 /* dbus-connection.c DBusConnection object
   3  *
   4  * Copyright (C) 2002, 2003  Red Hat Inc.
   5  *
   6  * Licensed under the Academic Free License version 1.2
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program 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 General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; 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-connection.h"
  25 #include "dbus-list.h"
  26 #include "dbus-timeout.h"
  27 #include "dbus-transport.h"
  28 #include "dbus-watch.h"
  29 #include "dbus-connection-internal.h"
  30 #include "dbus-list.h"
  31 #include "dbus-hash.h"
  32 #include "dbus-message-internal.h"
  33 #include "dbus-message-handler.h"
  34 #include "dbus-threads.h"
  35 #include "dbus-protocol.h"
  36 #include "dbus-dataslot.h"
  37
  38 /**
  39  * @defgroup DBusConnection DBusConnection
  40  * @ingroup  DBus
  41  * @brief Connection to another application
  42  *
  43  * A DBusConnection represents a connection to another
  44  * application. Messages can be sent and received via this connection.
  45  *
  46  * The connection maintains a queue of incoming messages and a queue
  47  * of outgoing messages. dbus_connection_pop_message() and friends
  48  * can be used to read incoming messages from the queue.
  49  * Outgoing messages are automatically discarded as they are
  50  * written to the network.
  51  *
  52  * In brief a DBusConnection is a message queue associated with some
  53  * message transport mechanism such as a socket.
  54  *
  55  */
  56
  57 /**
  58  * @defgroup DBusConnectionInternals DBusConnection implementation details
  59  * @ingroup  DBusInternals
  60  * @brief Implementation details of DBusConnection
  61  *
  62  * @{
  63  */
  64
  65 /** default timeout value when waiting for a message reply */
  66 #define DEFAULT_TIMEOUT_VALUE (15 * 1000)
  67
  68 static dbus_bool_t _dbus_modify_sigpipe = TRUE;
  69
  70 /**
  71  * Implementation details of DBusConnection. All fields are private.
  72  */
  73 struct DBusConnection
  74 {
  75   int refcount; /**< Reference count. */
  76
  77   DBusMutex *mutex; /**< Lock on the entire DBusConnection */
  78
  79   dbus_bool_t dispatch_acquired; /**< Protects dispatch_message */
  80   DBusCondVar *dispatch_cond;    /**< Protects dispatch_message */
  81
  82   dbus_bool_t io_path_acquired;  /**< Protects transport io path */
  83   DBusCondVar *io_path_cond;     /**< Protects transport io path */
  84
  85   DBusList *outgoing_messages; /**< Queue of messages we need to send, send the end of the list first. */
  86   DBusList *incoming_messages; /**< Queue of messages we have received, end of the list received most recently. */
  87
  88   DBusMessage *message_borrowed; /**< True if the first incoming message has been borrowed */
  89   DBusCondVar *message_returned_cond; /**< Used with dbus_connection_borrow_message() */
  90
  91   int n_outgoing;              /**< Length of outgoing queue. */
  92   int n_incoming;              /**< Length of incoming queue. */
  93
  94   DBusTransport *transport;    /**< Object that sends/receives messages over network. */
  95   DBusWatchList *watches;      /**< Stores active watches. */
  96   DBusTimeoutList *timeouts;   /**< Stores active timeouts. */
  97
  98   DBusHashTable *handler_table; /**< Table of registered DBusMessageHandler */
  99   DBusList *filter_list;        /**< List of filters. */
 100
 101   DBusDataSlotList slot_list;   /**< Data stored by allocated integer ID */
 102
 103   DBusHashTable *pending_replies;  /**< Hash of message serials and their message handlers. */
 104   DBusCounter *connection_counter; /**< Counter that we decrement when finalized */
 105
 106   int client_serial;            /**< Client serial. Increments each time a message is sent  */
 107   DBusList *disconnect_message_link; /**< Preallocated list node for queueing the disconnection message */
 108
 109   DBusWakeupMainFunction wakeup_main_function; /**< Function to wake up the mainloop  */
 110   void *wakeup_main_data; /**< Application data for wakeup_main_function */
 111   DBusFreeFunction free_wakeup_main_data; /**< free wakeup_main_data */
 112 };
 113
 114 typedef struct
 115 {
 116   DBusConnection *connection;
 117   DBusMessageHandler *handler;
 118   DBusTimeout *timeout;
 119   int serial;
 120
 121   DBusList *timeout_link; /* Preallocated timeout response */
 122
 123   dbus_bool_t timeout_added;
 124   dbus_bool_t connection_added;
 125 } ReplyHandlerData;
 126
 127 static void reply_handler_data_free (ReplyHandlerData *data);
 128
 129 static void _dbus_connection_remove_timeout_locked (DBusConnection *connection,
 130                                                     DBusTimeout    *timeout);
 131
 132 /**
 133  * Acquires the connection lock.
 134  *
 135  * @param connection the connection.
 136  */
 137 void
 138 _dbus_connection_lock (DBusConnection *connection)
 139 {
 140   dbus_mutex_lock (connection->mutex);
 141 }
 142
 143 /**
 144  * Releases the connection lock.
 145  *
 146  * @param connection the connection.
 147  */
 148 void
 149 _dbus_connection_unlock (DBusConnection *connection)
 150 {
 151   dbus_mutex_unlock (connection->mutex);
 152 }
 153
 154 /**
 155  * Wakes up the main loop if it is sleeping
 156  * Needed if we're e.g. queueing outgoing messages
 157  * on a thread while the mainloop sleeps.
 158  *
 159  * @param connection the connection.
 160  */
 161 static void
 162 _dbus_connection_wakeup_mainloop (DBusConnection *connection)
 163 {
 164   if (connection->wakeup_main_function)
 165     (*connection->wakeup_main_function) (connection->wakeup_main_data);
 166 }
 167
 168 /**
 169  * Adds a message to the incoming message queue, returning #FALSE
 170  * if there's insufficient memory to queue the message.
 171  *
 172  * @param connection the connection.
 173  * @param message the message to queue.
 174  * @returns #TRUE on success.
 175  */
 176 dbus_bool_t
 177 _dbus_connection_queue_received_message (DBusConnection *connection,
 178                                          DBusMessage    *message)
 179 {
 180   ReplyHandlerData *reply_handler_data;
 181   dbus_int32_t reply_serial;
 182
 183   _dbus_assert (_dbus_transport_get_is_authenticated (connection->transport));
 184
 185   if (!_dbus_list_append (&connection->incoming_messages,
 186                           message))
 187     return FALSE;
 188
 189   /* If this is a reply we're waiting on, remove timeout for it */
 190   reply_serial = dbus_message_get_reply_serial (message);
 191   if (reply_serial != -1)
 192     {
 193       reply_handler_data = _dbus_hash_table_lookup_int (connection->pending_replies,
 194                                                         reply_serial);
 195       if (reply_handler_data != NULL)
 196         {
 197           if (reply_handler_data->timeout_added)
 198             _dbus_connection_remove_timeout_locked (connection,
 199                                                     reply_handler_data->timeout);
 200           reply_handler_data->timeout_added = FALSE;
 201         }
 202     }
 203
 204   dbus_message_ref (message);
 205   connection->n_incoming += 1;
 206
 207   _dbus_connection_wakeup_mainloop (connection);
 208
 209   _dbus_assert (dbus_message_get_name (message) != NULL);
 210   _dbus_verbose ("Message %p (%s) added to incoming queue %p, %d incoming\n",
 211                  message, dbus_message_get_name (message),
 212                  connection,
 213                  connection->n_incoming);
 214
 215   return TRUE;
 216 }
 217
 218 /**
 219  * Adds a link + message to the incoming message queue.
 220  * Can't fail. Takes ownership of both link and message.
 221  *
 222  * @param connection the connection.
 223  * @param link the list node and message to queue.
 224  *
 225  * @todo This needs to wake up the mainloop if it is in
 226  * a poll/select and this is a multithreaded app.
 227  */
 228 static void
 229 _dbus_connection_queue_synthesized_message_link (DBusConnection *connection,
 230                                                  DBusList *link)
 231 {
 232   _dbus_list_append_link (&connection->incoming_messages, link);
 233
 234   connection->n_incoming += 1;
 235
 236   _dbus_connection_wakeup_mainloop (connection);
 237
 238   _dbus_verbose ("Synthesized message %p added to incoming queue %p, %d incoming\n",
 239                  link->data, connection, connection->n_incoming);
 240 }
 241
 242
 243 /**
 244  * Checks whether there are messages in the outgoing message queue.
 245  *
 246  * @param connection the connection.
 247  * @returns #TRUE if the outgoing queue is non-empty.
 248  */
 249 dbus_bool_t
 250 _dbus_connection_have_messages_to_send (DBusConnection *connection)
 251 {
 252   return connection->outgoing_messages != NULL;
 253 }
 254
 255 /**
 256  * Gets the next outgoing message. The message remains in the
 257  * queue, and the caller does not own a reference to it.
 258  *
 259  * @param connection the connection.
 260  * @returns the message to be sent.
 261  */
 262 DBusMessage*
 263 _dbus_connection_get_message_to_send (DBusConnection *connection)
 264 {
 265   return _dbus_list_get_last (&connection->outgoing_messages);
 266 }
 267
 268 /**
 269  * Notifies the connection that a message has been sent, so the
 270  * message can be removed from the outgoing queue.
 271  *
 272  * @param connection the connection.
 273  * @param message the message that was sent.
 274  */
 275 void
 276 _dbus_connection_message_sent (DBusConnection *connection,
 277                                DBusMessage    *message)
 278 {
 279   _dbus_assert (_dbus_transport_get_is_authenticated (connection->transport));
 280   _dbus_assert (message == _dbus_list_get_last (&connection->outgoing_messages));
 281
 282   _dbus_list_pop_last (&connection->outgoing_messages);
 283   dbus_message_unref (message);
 284
 285   connection->n_outgoing -= 1;
 286
 287   _dbus_verbose ("Message %p removed from outgoing queue %p, %d left to send\n",
 288                  message, connection, connection->n_outgoing);
 289
 290   if (connection->n_outgoing == 0)
 291     _dbus_transport_messages_pending (connection->transport,
 292                                       connection->n_outgoing);
 293 }
 294
 295 /**
 296  * Adds a watch using the connection's DBusAddWatchFunction if
 297  * available. Otherwise records the watch to be added when said
 298  * function is available. Also re-adds the watch if the
 299  * DBusAddWatchFunction changes. May fail due to lack of memory.
 300  *
 301  * @param connection the connection.
 302  * @param watch the watch to add.
 303  * @returns #TRUE on success.
 304  */
 305 dbus_bool_t
 306 _dbus_connection_add_watch (DBusConnection *connection,
 307                             DBusWatch      *watch)
 308 {
 309   if (connection->watches) /* null during finalize */
 310     return _dbus_watch_list_add_watch (connection->watches,
 311                                        watch);
 312   else
 313     return FALSE;
 314 }
 315
 316 /**
 317  * Removes a watch using the connection's DBusRemoveWatchFunction
 318  * if available. It's an error to call this function on a watch
 319  * that was not previously added.
 320  *
 321  * @param connection the connection.
 322  * @param watch the watch to remove.
 323  */
 324 void
 325 _dbus_connection_remove_watch (DBusConnection *connection,
 326                                DBusWatch      *watch)
 327 {
 328   if (connection->watches) /* null during finalize */
 329     _dbus_watch_list_remove_watch (connection->watches,
 330                                    watch);
 331 }
 332
 333 /**
 334  * Adds a timeout using the connection's DBusAddTimeoutFunction if
 335  * available. Otherwise records the timeout to be added when said
 336  * function is available. Also re-adds the timeout if the
 337  * DBusAddTimeoutFunction changes. May fail due to lack of memory.
 338  * The timeout will fire repeatedly until removed.
 339  *
 340  * @param connection the connection.
 341  * @param timeout the timeout to add.
 342  * @returns #TRUE on success.
 343  */
 344 dbus_bool_t
 345 _dbus_connection_add_timeout (DBusConnection *connection,
 346                               DBusTimeout    *timeout)
 347 {
 348  if (connection->timeouts) /* null during finalize */
 349     return _dbus_timeout_list_add_timeout (connection->timeouts,
 350                                            timeout);
 351   else
 352     return FALSE;
 353 }
 354
 355 /**
 356  * Removes a timeout using the connection's DBusRemoveTimeoutFunction
 357  * if available. It's an error to call this function on a timeout
 358  * that was not previously added.
 359  *
 360  * @param connection the connection.
 361  * @param timeout the timeout to remove.
 362  */
 363 void
 364 _dbus_connection_remove_timeout (DBusConnection *connection,
 365                                  DBusTimeout    *timeout)
 366 {
 367   if (connection->timeouts) /* null during finalize */
 368     _dbus_timeout_list_remove_timeout (connection->timeouts,
 369                                        timeout);
 370 }
 371
 372 static void
 373 _dbus_connection_remove_timeout_locked (DBusConnection *connection,
 374                                         DBusTimeout    *timeout)
 375 {
 376   dbus_mutex_lock (connection->mutex);
 377   _dbus_connection_remove_timeout (connection, timeout);
 378   dbus_mutex_unlock (connection->mutex);
 379 }
 380
 381
 382 /**
 383  * Tells the connection that the transport has been disconnected.
 384  * Results in posting a disconnect message on the incoming message
 385  * queue.  Only has an effect the first time it's called.
 386  *
 387  * @param connection the connection
 388  */
 389 void
 390 _dbus_connection_notify_disconnected (DBusConnection *connection)
 391 {
 392   if (connection->disconnect_message_link)
 393     {
 394       /* We haven't sent the disconnect message already */
 395       _dbus_connection_queue_synthesized_message_link (connection,
 396                                                        connection->disconnect_message_link);
 397       connection->disconnect_message_link = NULL;
 398     }
 399 }
 400
 401
 402 /**
 403  * Acquire the transporter I/O path. This must be done before
 404  * doing any I/O in the transporter. May sleep and drop the
 405  * connection mutex while waiting for the I/O path.
 406  *
 407  * @param connection the connection.
 408  * @param timeout_milliseconds maximum blocking time, or -1 for no limit.
 409  * @returns TRUE if the I/O path was acquired.
 410  */
 411 static dbus_bool_t
 412 _dbus_connection_acquire_io_path (DBusConnection *connection,
 413                                   int timeout_milliseconds)
 414 {
 415   dbus_bool_t res = TRUE;
 416
 417   if (connection->io_path_acquired)
 418     {
 419       if (timeout_milliseconds != -1)
 420         res = dbus_condvar_wait_timeout (connection->io_path_cond,
 421                                          connection->mutex,
 422                                          timeout_milliseconds);
 423       else
 424         dbus_condvar_wait (connection->io_path_cond, connection->mutex);
 425     }
 426
 427   if (res)
 428     {
 429       _dbus_assert (!connection->io_path_acquired);
 430
 431       connection->io_path_acquired = TRUE;
 432     }
 433
 434   return res;
 435 }
 436
 437 /**
 438  * Release the I/O path when you're done with it. Only call
 439  * after you've acquired the I/O. Wakes up at most one thread
 440  * currently waiting to acquire the I/O path.
 441  *
 442  * @param connection the connection.
 443  */
 444 static void
 445 _dbus_connection_release_io_path (DBusConnection *connection)
 446 {
 447   _dbus_assert (connection->io_path_acquired);
 448
 449   connection->io_path_acquired = FALSE;
 450   dbus_condvar_wake_one (connection->io_path_cond);
 451 }
 452
 453
 454 /**
 455  * Queues incoming messages and sends outgoing messages for this
 456  * connection, optionally blocking in the process. Each call to
 457  * _dbus_connection_do_iteration() will call select() or poll() one
 458  * time and then read or write data if possible.
 459  *
 460  * The purpose of this function is to be able to flush outgoing
 461  * messages or queue up incoming messages without returning
 462  * control to the application and causing reentrancy weirdness.
 463  *
 464  * The flags parameter allows you to specify whether to
 465  * read incoming messages, write outgoing messages, or both,
 466  * and whether to block if no immediate action is possible.
 467  *
 468  * The timeout_milliseconds parameter does nothing unless the
 469  * iteration is blocking.
 470  *
 471  * If there are no outgoing messages and DBUS_ITERATION_DO_READING
 472  * wasn't specified, then it's impossible to block, even if
 473  * you specify DBUS_ITERATION_BLOCK; in that case the function
 474  * returns immediately.
 475  *
 476  * @param connection the connection.
 477  * @param flags iteration flags.
 478  * @param timeout_milliseconds maximum blocking time, or -1 for no limit.
 479  */
 480 void
 481 _dbus_connection_do_iteration (DBusConnection *connection,
 482                                unsigned int    flags,
 483                                int             timeout_milliseconds)
 484 {
 485   if (connection->n_outgoing == 0)
 486     flags &= ~DBUS_ITERATION_DO_WRITING;
 487
 488   if (_dbus_connection_acquire_io_path (connection,
 489                                         (flags & DBUS_ITERATION_BLOCK)?timeout_milliseconds:0))
 490     {
 491       _dbus_transport_do_iteration (connection->transport,
 492                                     flags, timeout_milliseconds);
 493       _dbus_connection_release_io_path (connection);
 494     }
 495 }
 496
 497 /**
 498  * Creates a new connection for the given transport.  A transport
 499  * represents a message stream that uses some concrete mechanism, such
 500  * as UNIX domain sockets. May return #NULL if insufficient
 501  * memory exists to create the connection.
 502  *
 503  * @param transport the transport.
 504  * @returns the new connection, or #NULL on failure.
 505  */
 506 DBusConnection*
 507 _dbus_connection_new_for_transport (DBusTransport *transport)
 508 {
 509   DBusConnection *connection;
 510   DBusWatchList *watch_list;
 511   DBusTimeoutList *timeout_list;
 512   DBusHashTable *handler_table, *pending_replies;
 513   DBusMutex *mutex;
 514   DBusCondVar *message_returned_cond;
 515   DBusCondVar *dispatch_cond;
 516   DBusCondVar *io_path_cond;
 517   DBusList *disconnect_link;
 518   DBusMessage *disconnect_message;
 519
 520   watch_list = NULL;
 521   connection = NULL;
 522   handler_table = NULL;
 523   pending_replies = NULL;
 524   timeout_list = NULL;
 525   mutex = NULL;
 526   message_returned_cond = NULL;
 527   dispatch_cond = NULL;
 528   io_path_cond = NULL;
 529   disconnect_link = NULL;
 530   disconnect_message = NULL;
 531
 532   watch_list = _dbus_watch_list_new ();
 533   if (watch_list == NULL)
 534     goto error;
 535
 536   timeout_list = _dbus_timeout_list_new ();
 537   if (timeout_list == NULL)
 538     goto error;
 539
 540   handler_table =
 541     _dbus_hash_table_new (DBUS_HASH_STRING,
 542                           dbus_free, NULL);
 543   if (handler_table == NULL)
 544     goto error;
 545
 546   pending_replies =
 547     _dbus_hash_table_new (DBUS_HASH_INT,
 548                           NULL, (DBusFreeFunction)reply_handler_data_free);
 549   if (pending_replies == NULL)
 550     goto error;
 551
 552   connection = dbus_new0 (DBusConnection, 1);
 553   if (connection == NULL)
 554     goto error;
 555
 556   mutex = dbus_mutex_new ();
 557   if (mutex == NULL)
 558     goto error;
 559
 560   message_returned_cond = dbus_condvar_new ();
 561   if (message_returned_cond == NULL)
 562     goto error;
 563
 564   dispatch_cond = dbus_condvar_new ();
 565   if (dispatch_cond == NULL)
 566     goto error;
 567
 568   io_path_cond = dbus_condvar_new ();
 569   if (io_path_cond == NULL)
 570     goto error;
 571
 572   disconnect_message = dbus_message_new (NULL, DBUS_MESSAGE_LOCAL_DISCONNECT);
 573   if (disconnect_message == NULL)
 574     goto error;
 575
 576   disconnect_link = _dbus_list_alloc_link (disconnect_message);
 577   if (disconnect_link == NULL)
 578     goto error;
 579
 580   if (_dbus_modify_sigpipe)
 581     _dbus_disable_sigpipe ();
 582
 583   connection->refcount = 1;
 584   connection->mutex = mutex;
 585   connection->dispatch_cond = dispatch_cond;
 586   connection->io_path_cond = io_path_cond;
 587   connection->message_returned_cond = message_returned_cond;
 588   connection->transport = transport;
 589   connection->watches = watch_list;
 590   connection->timeouts = timeout_list;
 591   connection->handler_table = handler_table;
 592   connection->pending_replies = pending_replies;
 593   connection->filter_list = NULL;
 594
 595   _dbus_data_slot_list_init (&connection->slot_list);
 596
 597   connection->client_serial = 1;
 598
 599   connection->disconnect_message_link = disconnect_link;
 600
 601   _dbus_transport_ref (transport);
 602   _dbus_transport_set_connection (transport, connection);
 603
 604   return connection;
 605
 606  error:
 607   if (disconnect_message != NULL)
 608     dbus_message_unref (disconnect_message);
 609
 610   if (disconnect_link != NULL)
 611     _dbus_list_free_link (disconnect_link);
 612
 613   if (io_path_cond != NULL)
 614     dbus_condvar_free (io_path_cond);
 615
 616   if (dispatch_cond != NULL)
 617     dbus_condvar_free (dispatch_cond);
 618
 619   if (message_returned_cond != NULL)
 620     dbus_condvar_free (message_returned_cond);
 621
 622   if (mutex != NULL)
 623     dbus_mutex_free (mutex);
 624
 625   if (connection != NULL)
 626     dbus_free (connection);
 627
 628   if (handler_table)
 629     _dbus_hash_table_unref (handler_table);
 630
 631   if (pending_replies)
 632     _dbus_hash_table_unref (pending_replies);
 633
 634   if (watch_list)
 635     _dbus_watch_list_free (watch_list);
 636
 637   if (timeout_list)
 638     _dbus_timeout_list_free (timeout_list);
 639
 640   return NULL;
 641 }
 642
 643 static dbus_int32_t
 644 _dbus_connection_get_next_client_serial (DBusConnection *connection)
 645 {
 646   int serial;
 647
 648   serial = connection->client_serial++;
 649
 650   if (connection->client_serial < 0)
 651     connection->client_serial = 1;
 652
 653   return serial;
 654 }
 655
 656 /**
 657  * Used to notify a connection when a DBusMessageHandler is
 658  * destroyed, so the connection can drop any reference
 659  * to the handler. This is a private function, but still
 660  * takes the connection lock. Don't call it with the lock held.
 661  *
 662  * @todo needs to check in pending_replies too.
 663  *
 664  * @param connection the connection
 665  * @param handler the handler
 666  */
 667 void
 668 _dbus_connection_handler_destroyed_locked (DBusConnection     *connection,
 669                                            DBusMessageHandler *handler)
 670 {
 671   DBusHashIter iter;
 672   DBusList *link;
 673
 674   dbus_mutex_lock (connection->mutex);
 675
 676   _dbus_hash_iter_init (connection->handler_table, &iter);
 677   while (_dbus_hash_iter_next (&iter))
 678     {
 679       DBusMessageHandler *h = _dbus_hash_iter_get_value (&iter);
 680
 681       if (h == handler)
 682         _dbus_hash_iter_remove_entry (&iter);
 683     }
 684
 685   link = _dbus_list_get_first_link (&connection->filter_list);
 686   while (link != NULL)
 687     {
 688       DBusMessageHandler *h = link->data;
 689       DBusList *next = _dbus_list_get_next_link (&connection->filter_list, link);
 690
 691       if (h == handler)
 692         _dbus_list_remove_link (&connection->filter_list,
 693                                 link);
 694
 695       link = next;
 696     }
 697   dbus_mutex_unlock (connection->mutex);
 698 }
 699
 700 /**
 701  * Adds the counter used to count the number of open connections.
 702  * Increments the counter by one, and saves it to be decremented
 703  * again when this connection is finalized.
 704  *
 705  * @param connection a #DBusConnection
 706  * @param counter counter that tracks number of connections
 707  */
 708 void
 709 _dbus_connection_set_connection_counter (DBusConnection *connection,
 710                                          DBusCounter    *counter)
 711 {
 712   _dbus_assert (connection->connection_counter == NULL);
 713
 714   connection->connection_counter = counter;
 715   _dbus_counter_ref (connection->connection_counter);
 716   _dbus_counter_adjust (connection->connection_counter, 1);
 717 }
 718
 719 /** @} */
 720
 721 /**
 722  * @addtogroup DBusConnection
 723  *
 724  * @{
 725  */
 726
 727 /**
 728  * Opens a new connection to a remote address.
 729  *
 730  * @todo specify what the address parameter is. Right now
 731  * it's just the name of a UNIX domain socket. It should be
 732  * something more complex that encodes which transport to use.
 733  *
 734  * If the open fails, the function returns #NULL, and provides
 735  * a reason for the failure in the result parameter. Pass
 736  * #NULL for the result parameter if you aren't interested
 737  * in the reason for failure.
 738  *
 739  * @param address the address.
 740  * @param result address where a result code can be returned.
 741  * @returns new connection, or #NULL on failure.
 742  */
 743 DBusConnection*
 744 dbus_connection_open (const char     *address,
 745                       DBusResultCode *result)
 746 {
 747   DBusConnection *connection;
 748   DBusTransport *transport;
 749
 750   transport = _dbus_transport_open (address, result);
 751   if (transport == NULL)
 752     return NULL;
 753
 754   connection = _dbus_connection_new_for_transport (transport);
 755
 756   _dbus_transport_unref (transport);
 757
 758   if (connection == NULL)
 759     {
 760       dbus_set_result (result, DBUS_RESULT_NO_MEMORY);
 761       return NULL;
 762     }
 763
 764   return connection;
 765 }
 766
 767 /**
 768  * Increments the reference count of a DBusConnection.
 769  *
 770  * @param connection the connection.
 771  */
 772 void
 773 dbus_connection_ref (DBusConnection *connection)
 774 {
 775   dbus_mutex_lock (connection->mutex);
 776   _dbus_assert (connection->refcount > 0);
 777
 778   connection->refcount += 1;
 779   dbus_mutex_unlock (connection->mutex);
 780 }
 781
 782 /**
 783  * Increments the reference count of a DBusConnection.
 784  * Requires that the caller already holds the connection lock.
 785  *
 786  * @param connection the connection.
 787  */
 788 void
 789 _dbus_connection_ref_unlocked (DBusConnection *connection)
 790 {
 791   _dbus_assert (connection->refcount > 0);
 792   connection->refcount += 1;
 793 }
 794
 795
 796 /* This is run without the mutex held, but after the last reference
 797  * to the connection has been dropped we should have no thread-related
 798  * problems
 799  */
 800 static void
 801 _dbus_connection_last_unref (DBusConnection *connection)
 802 {
 803   DBusHashIter iter;
 804   DBusList *link;
 805
 806   /* You have to disconnect the connection before unref:ing it. Otherwise
 807    * you won't get the disconnected message.
 808    */
 809   _dbus_assert (!_dbus_transport_get_is_connected (connection->transport));
 810
 811   if (connection->connection_counter != NULL)
 812     {
 813       /* subtract ourselves from the counter */
 814       _dbus_counter_adjust (connection->connection_counter, - 1);
 815       _dbus_counter_unref (connection->connection_counter);
 816       connection->connection_counter = NULL;
 817     }
 818
 819   _dbus_watch_list_free (connection->watches);
 820   connection->watches = NULL;
 821
 822   _dbus_timeout_list_free (connection->timeouts);
 823   connection->timeouts = NULL;
 824
 825   /* calls out to application code... */
 826   _dbus_data_slot_list_free (&connection->slot_list);
 827
 828   _dbus_hash_iter_init (connection->handler_table, &iter);
 829   while (_dbus_hash_iter_next (&iter))
 830     {
 831       DBusMessageHandler *h = _dbus_hash_iter_get_value (&iter);
 832
 833       _dbus_message_handler_remove_connection (h, connection);
 834     }
 835
 836   link = _dbus_list_get_first_link (&connection->filter_list);
 837   while (link != NULL)
 838     {
 839       DBusMessageHandler *h = link->data;
 840       DBusList *next = _dbus_list_get_next_link (&connection->filter_list, link);
 841
 842       _dbus_message_handler_remove_connection (h, connection);
 843
 844       link = next;
 845     }
 846
 847   _dbus_hash_table_unref (connection->handler_table);
 848   connection->handler_table = NULL;
 849
 850   _dbus_hash_table_unref (connection->pending_replies);
 851   connection->pending_replies = NULL;
 852
 853   _dbus_list_clear (&connection->filter_list);
 854
 855   _dbus_list_foreach (&connection->outgoing_messages,
 856                       (DBusForeachFunction) dbus_message_unref,
 857                       NULL);
 858   _dbus_list_clear (&connection->outgoing_messages);
 859
 860   _dbus_list_foreach (&connection->incoming_messages,
 861                       (DBusForeachFunction) dbus_message_unref,
 862                       NULL);
 863   _dbus_list_clear (&connection->incoming_messages);
 864
 865   _dbus_transport_unref (connection->transport);
 866
 867   if (connection->disconnect_message_link)
 868     {
 869       DBusMessage *message = connection->disconnect_message_link->data;
 870       dbus_message_unref (message);
 871       _dbus_list_free_link (connection->disconnect_message_link);
 872     }
 873
 874   dbus_condvar_free (connection->dispatch_cond);
 875   dbus_condvar_free (connection->io_path_cond);
 876   dbus_condvar_free (connection->message_returned_cond);
 877
 878   dbus_mutex_free (connection->mutex);
 879
 880   dbus_free (connection);
 881 }
 882
 883 /**
 884  * Decrements the reference count of a DBusConnection, and finalizes
 885  * it if the count reaches zero.  It is a bug to drop the last reference
 886  * to a connection that has not been disconnected.
 887  *
 888  * @param connection the connection.
 889  */
 890 void
 891 dbus_connection_unref (DBusConnection *connection)
 892 {
 893   dbus_bool_t last_unref;
 894
 895   dbus_mutex_lock (connection->mutex);
 896
 897   _dbus_assert (connection != NULL);
 898   _dbus_assert (connection->refcount > 0);
 899
 900   connection->refcount -= 1;
 901   last_unref = (connection->refcount == 0);
 902
 903   dbus_mutex_unlock (connection->mutex);
 904
 905   if (last_unref)
 906     _dbus_connection_last_unref (connection);
 907 }
 908
 909 /**
 910  * Closes the connection, so no further data can be sent or received.
 911  * Any further attempts to send data will result in errors.  This
 912  * function does not affect the connection's reference count.  It's
 913  * safe to disconnect a connection more than once; all calls after the
 914  * first do nothing. It's impossible to "reconnect" a connection, a
 915  * new connection must be created.
 916  *
 917  * @param connection the connection.
 918  */
 919 void
 920 dbus_connection_disconnect (DBusConnection *connection)
 921 {
 922   dbus_mutex_lock (connection->mutex);
 923   _dbus_transport_disconnect (connection->transport);
 924   dbus_mutex_unlock (connection->mutex);
 925 }
 926
 927 /**
 928  * Gets whether the connection is currently connected.  All
 929  * connections are connected when they are opened.  A connection may
 930  * become disconnected when the remote application closes its end, or
 931  * exits; a connection may also be disconnected with
 932  * dbus_connection_disconnect().
 933  *
 934  * @param connection the connection.
 935  * @returns #TRUE if the connection is still alive.
 936  */
 937 dbus_bool_t
 938 dbus_connection_get_is_connected (DBusConnection *connection)
 939 {
 940   dbus_bool_t res;
 941
 942   dbus_mutex_lock (connection->mutex);
 943   res = _dbus_transport_get_is_connected (connection->transport);
 944   dbus_mutex_unlock (connection->mutex);
 945
 946   return res;
 947 }
 948
 949 /**
 950  * Gets whether the connection was authenticated. (Note that
 951  * if the connection was authenticated then disconnected,
 952  * this function still returns #TRUE)
 953  *
 954  * @param connection the connection
 955  * @returns #TRUE if the connection was ever authenticated
 956  */
 957 dbus_bool_t
 958 dbus_connection_get_is_authenticated (DBusConnection *connection)
 959 {
 960   dbus_bool_t res;
 961
 962   dbus_mutex_lock (connection->mutex);
 963   res = _dbus_transport_get_is_authenticated (connection->transport);
 964   dbus_mutex_unlock (connection->mutex);
 965
 966   return res;
 967 }
 968
 969 /**
 970  * Preallocates resources needed to send a message, allowing the message
 971  * to be sent without the possibility of memory allocation failure.
 972  * Allows apps to create a future guarantee that they can send
 973  * a message regardless of memory shortages.
 974  *
 975  * @param connection the connection we're preallocating for.
 976  * @returns the preallocated resources, or #NULL
 977  */
 978 DBusPreallocatedSend*
 979 dbus_connection_preallocate_send (DBusConnection *connection)
 980 {
 981   /* we store "connection" in the link just to enforce via
 982    * assertion that preallocated links are only used
 983    * with the connection they were created for.
 984    */
 985   return (DBusPreallocatedSend*) _dbus_list_alloc_link (connection);
 986 }
 987
 988 /**
 989  * Frees preallocated message-sending resources from
 990  * dbus_connection_preallocate_send(). Should only
 991  * be called if the preallocated resources are not used
 992  * to send a message.
 993  *
 994  * @param connection the connection
 995  * @param preallocated the resources
 996  */
 997 void
 998 dbus_connection_free_preallocated_send (DBusConnection       *connection,
 999                                         DBusPreallocatedSend *preallocated)
1000 {
1001   DBusList *link = (DBusList*) preallocated;
1002   _dbus_assert (link->data == connection);
1003   _dbus_list_free_link (link);
1004 }
1005
1006 /**
1007  * Sends a message using preallocated resources. This function cannot fail.
1008  * It works identically to dbus_connection_send() in other respects.
1009  * Preallocated resources comes from dbus_connection_preallocate_send().
1010  * This function "consumes" the preallocated resources, they need not
1011  * be freed separately.
1012  *
1013  * @param connection the connection
1014  * @param preallocated the preallocated resources
1015  * @param message the message to send
1016  * @param client_serial return location for client serial assigned to the message
1017  */
1018 void
1019 dbus_connection_send_preallocated (DBusConnection       *connection,
1020                                    DBusPreallocatedSend *preallocated,
1021                                    DBusMessage          *message,
1022                                    dbus_int32_t         *client_serial)
1023 {
1024   DBusList *link = (DBusList*) preallocated;
1025   dbus_int32_t serial;
1026
1027   _dbus_assert (link->data == connection);
1028   _dbus_assert (dbus_message_get_name (message) != NULL);
1029
1030   dbus_mutex_lock (connection->mutex);
1031
1032   link->data = message;
1033   _dbus_list_prepend_link (&connection->outgoing_messages,
1034                            link);
1035
1036   dbus_message_ref (message);
1037   connection->n_outgoing += 1;
1038
1039   _dbus_verbose ("Message %p (%s) added to outgoing queue %p, %d pending to send\n",
1040                  message,
1041                  dbus_message_get_name (message),
1042                  connection,
1043                  connection->n_outgoing);
1044
1045   if (dbus_message_get_serial (message) == -1)
1046     {
1047       serial = _dbus_connection_get_next_client_serial (connection);
1048       _dbus_message_set_serial (message, serial);
1049     }
1050
1051   if (client_serial)
1052     *client_serial = dbus_message_get_serial (message);
1053
1054   _dbus_message_lock (message);
1055
1056   if (connection->n_outgoing == 1)
1057     _dbus_transport_messages_pending (connection->transport,
1058                                       connection->n_outgoing);
1059
1060   _dbus_connection_wakeup_mainloop (connection);
1061
1062   dbus_mutex_unlock (connection->mutex);
1063 }
1064
1065 /**
1066  * Adds a message to the outgoing message queue. Does not block to
1067  * write the message to the network; that happens asynchronously. To
1068  * force the message to be written, call dbus_connection_flush().
1069  * Because this only queues the message, the only reason it can
1070  * fail is lack of memory. Even if the connection is disconnected,
1071  * no error will be returned.
1072  *
1073  * If the function fails, it returns #FALSE and returns the
1074  * reason for failure via the result parameter.
1075  * The result parameter can be #NULL if you aren't interested
1076  * in the reason for the failure.
1077  *
1078  * @param connection the connection.
1079  * @param message the message to write.
1080  * @param client_serial return location for client serial.
1081  * @returns #TRUE on success.
1082  */
1083 dbus_bool_t
1084 dbus_connection_send (DBusConnection *connection,
1085                       DBusMessage    *message,
1086                       dbus_int32_t   *client_serial)
1087 {
1088   DBusPreallocatedSend *preallocated;
1089
1090   preallocated = dbus_connection_preallocate_send (connection);
1091   if (preallocated == NULL)
1092     {
1093       return FALSE;
1094     }
1095   else
1096     {
1097       dbus_connection_send_preallocated (connection, preallocated, message, client_serial);
1098       return TRUE;
1099     }
1100 }
1101
1102 static void
1103 reply_handler_timeout (void *data)
1104 {
1105   DBusConnection *connection;
1106   ReplyHandlerData *reply_handler_data = data;
1107
1108   connection = reply_handler_data->connection;
1109
1110   dbus_mutex_lock (connection->mutex);
1111   if (reply_handler_data->timeout_link)
1112     {
1113       _dbus_connection_queue_synthesized_message_link (connection,
1114                                                        reply_handler_data->timeout_link);
1115       reply_handler_data->timeout_link = NULL;
1116     }
1117
1118   _dbus_connection_remove_timeout (connection,
1119                                    reply_handler_data->timeout);
1120   reply_handler_data->timeout_added = FALSE;
1121
1122   dbus_mutex_unlock (connection->mutex);
1123 }
1124
1125 static void
1126 reply_handler_data_free (ReplyHandlerData *data)
1127 {
1128   if (!data)
1129     return;
1130
1131   if (data->timeout_added)
1132     _dbus_connection_remove_timeout_locked (data->connection,
1133                                             data->timeout);
1134
1135   if (data->connection_added)
1136     _dbus_message_handler_remove_connection (data->handler,
1137                                              data->connection);
1138
1139   if (data->timeout_link)
1140     {
1141       dbus_message_unref ((DBusMessage *)data->timeout_link->data);
1142       _dbus_list_free_link (data->timeout_link);
1143     }
1144
1145   dbus_message_handler_unref (data->handler);
1146
1147   dbus_free (data);
1148 }
1149
1150 /**
1151  * Queues a message to send, as with dbus_connection_send_message(),
1152  * but also sets up a DBusMessageHandler to receive a reply to the
1153  * message. If no reply is received in the given timeout_milliseconds,
1154  * expires the pending reply and sends the DBusMessageHandler a
1155  * synthetic error reply (generated in-process, not by the remote
1156  * application) indicating that a timeout occurred.
1157  *
1158  * Reply handlers see their replies after message filters see them,
1159  * but before message handlers added with
1160  * dbus_connection_register_handler() see them, regardless of the
1161  * reply message's name. Reply handlers are only handed a single
1162  * message as a reply, after one reply has been seen the handler is
1163  * removed. If a filter filters out the reply before the handler sees
1164  * it, the reply is immediately timed out and a timeout error reply is
1165  * generated. If a filter removes the timeout error reply then the
1166  * reply handler will never be called. Filters should not do this.
1167  *
1168  * If #NULL is passed for the reply_handler, the timeout reply will
1169  * still be generated and placed into the message queue, but no
1170  * specific message handler will receive the reply.
1171  *
1172  * If -1 is passed for the timeout, a sane default timeout is used. -1
1173  * is typically the best value for the timeout for this reason, unless
1174  * you want a very short or very long timeout.  There is no way to
1175  * avoid a timeout entirely, other than passing INT_MAX for the
1176  * timeout to postpone it indefinitely.
1177  *
1178  * @param connection the connection
1179  * @param message the message to send
1180  * @param reply_handler message handler expecting the reply, or #NULL
1181  * @param timeout_milliseconds timeout in milliseconds or -1 for default
1182  * @returns #TRUE if the message is successfully queued, #FALSE if no memory.
1183  *
1184  */
1185 dbus_bool_t
1186 dbus_connection_send_with_reply (DBusConnection     *connection,
1187                                  DBusMessage        *message,
1188                                  DBusMessageHandler *reply_handler,
1189                                  int                 timeout_milliseconds)
1190 {
1191   DBusTimeout *timeout;
1192   ReplyHandlerData *data;
1193   DBusMessage *reply;
1194   DBusList *reply_link;
1195   dbus_int32_t serial = -1;
1196
1197   if (timeout_milliseconds == -1)
1198     timeout_milliseconds = DEFAULT_TIMEOUT_VALUE;
1199
1200   data = dbus_new0 (ReplyHandlerData, 1);
1201
1202   if (!data)
1203     return FALSE;
1204
1205   timeout = _dbus_timeout_new (timeout_milliseconds, reply_handler_timeout,
1206                                data, NULL);
1207
1208   if (!timeout)
1209     {
1210       reply_handler_data_free (data);
1211       return FALSE;
1212     }
1213
1214   dbus_mutex_lock (connection->mutex);
1215
1216   /* Add timeout */
1217   if (!_dbus_connection_add_timeout (connection, timeout))
1218     {
1219       reply_handler_data_free (data);
1220       _dbus_timeout_unref (timeout);
1221       dbus_mutex_unlock (connection->mutex);
1222       return FALSE;
1223     }
1224
1225   /* The connection now owns the reference to the timeout. */
1226   _dbus_timeout_unref (timeout);
1227
1228   data->timeout_added = TRUE;
1229   data->timeout = timeout;
1230   data->connection = connection;
1231
1232   if (!_dbus_message_handler_add_connection (reply_handler, connection))
1233     {
1234       dbus_mutex_unlock (connection->mutex);
1235       reply_handler_data_free (data);
1236       return FALSE;
1237     }
1238   data->connection_added = TRUE;
1239
1240   /* Assign a serial to the message */
1241   if (dbus_message_get_serial (message) == -1)
1242     {
1243       serial = _dbus_connection_get_next_client_serial (connection);
1244       _dbus_message_set_serial (message, serial);
1245     }
1246
1247   data->handler = reply_handler;
1248   data->serial = serial;
1249
1250   dbus_message_handler_ref (reply_handler);
1251
1252   reply = dbus_message_new_error_reply (message, DBUS_ERROR_NO_REPLY,
1253                                         "No reply within specified time");
1254   if (!reply)
1255     {
1256       dbus_mutex_unlock (connection->mutex);
1257       reply_handler_data_free (data);
1258       return FALSE;
1259     }
1260
1261   reply_link = _dbus_list_alloc_link (reply);
1262   if (!reply)
1263     {
1264       dbus_mutex_unlock (connection->mutex);
1265       dbus_message_unref (reply);
1266       reply_handler_data_free (data);
1267       return FALSE;
1268     }
1269
1270   data->timeout_link = reply_link;
1271
1272   /* Insert the serial in the pending replies hash. */
1273   if (!_dbus_hash_table_insert_int (connection->pending_replies, serial, data))
1274     {
1275       dbus_mutex_unlock (connection->mutex);
1276       reply_handler_data_free (data);
1277       return FALSE;
1278     }
1279
1280   dbus_mutex_unlock (connection->mutex);
1281
1282   if (!dbus_connection_send (connection, message, NULL))
1283     {
1284       /* This will free the handler data too */
1285       _dbus_hash_table_remove_int (connection->pending_replies, serial);
1286       return FALSE;
1287     }
1288
1289   return TRUE;
1290 }
1291
1292 /**
1293  * Sends a message and blocks a certain time period while waiting for a reply.
1294  * This function does not dispatch any message handlers until the main loop
1295  * has been reached. This function is used to do non-reentrant "method calls."
1296  * If a reply is received, it is returned, and removed from the incoming
1297  * message queue. If it is not received, #NULL is returned and the
1298  * error is set to #DBUS_ERROR_NO_REPLY. If something else goes
1299  * wrong, result is set to whatever is appropriate, such as
1300  * #DBUS_ERROR_NO_MEMORY or #DBUS_ERROR_DISCONNECTED.
1301  *
1302  * @todo could use performance improvements (it keeps scanning
1303  * the whole message queue for example) and has thread issues,
1304  * see comments in source
1305  *
1306  * @param connection the connection
1307  * @param message the message to send
1308  * @param timeout_milliseconds timeout in milliseconds or -1 for default
1309  * @param error return location for error message
1310  * @returns the message that is the reply or #NULL with an error code if the
1311  * function fails.
1312  */
1313 DBusMessage *
1314 dbus_connection_send_with_reply_and_block (DBusConnection     *connection,
1315                                            DBusMessage        *message,
1316                                            int                 timeout_milliseconds,
1317                                            DBusError          *error)
1318 {
1319   dbus_int32_t client_serial;
1320   DBusList *link;
1321   long start_tv_sec, start_tv_usec;
1322   long end_tv_sec, end_tv_usec;
1323   long tv_sec, tv_usec;
1324
1325   if (timeout_milliseconds == -1)
1326     timeout_milliseconds = DEFAULT_TIMEOUT_VALUE;
1327
1328   /* it would probably seem logical to pass in _DBUS_INT_MAX
1329    * for infinite timeout, but then math below would get
1330    * all overflow-prone, so smack that down.
1331    */
1332   if (timeout_milliseconds > _DBUS_ONE_HOUR_IN_MILLISECONDS * 6)
1333     timeout_milliseconds = _DBUS_ONE_HOUR_IN_MILLISECONDS * 6;
1334
1335   if (!dbus_connection_send (connection, message, &client_serial))
1336     {
1337       _DBUS_SET_OOM (error);
1338       return NULL;
1339     }
1340
1341   message = NULL;
1342
1343   /* Flush message queue */
1344   dbus_connection_flush (connection);
1345
1346   dbus_mutex_lock (connection->mutex);
1347
1348   _dbus_get_current_time (&start_tv_sec, &start_tv_usec);
1349   end_tv_sec = start_tv_sec + timeout_milliseconds / 1000;
1350   end_tv_usec = start_tv_usec + (timeout_milliseconds % 1000) * 1000;
1351   end_tv_sec += end_tv_usec / _DBUS_USEC_PER_SECOND;
1352   end_tv_usec = end_tv_usec % _DBUS_USEC_PER_SECOND;
1353
1354   _dbus_verbose ("will block %d milliseconds from %ld sec %ld usec to %ld sec %ld usec\n",
1355                  timeout_milliseconds,
1356                  start_tv_sec, start_tv_usec,
1357                  end_tv_sec, end_tv_usec);
1358
1359   /* Now we wait... */
1360   /* THREAD TODO: This is busted. What if a dispatch_message or pop_message
1361    * gets the message before we do?
1362    */
1363  block_again:
1364
1365   _dbus_connection_do_iteration (connection,
1366                                  DBUS_ITERATION_DO_READING |
1367                                  DBUS_ITERATION_BLOCK,
1368                                  timeout_milliseconds);
1369
1370   /* Check if we've gotten a reply */
1371   link = _dbus_list_get_first_link (&connection->incoming_messages);
1372
1373   while (link != NULL)
1374     {
1375       DBusMessage *reply = link->data;
1376
1377       if (dbus_message_get_reply_serial (reply) == client_serial)
1378         {
1379           _dbus_list_remove_link (&connection->incoming_messages, link);
1380           dbus_message_ref (reply);
1381
1382           dbus_mutex_unlock (connection->mutex);
1383           return reply;
1384         }
1385       link = _dbus_list_get_next_link (&connection->incoming_messages, link);
1386     }
1387
1388   _dbus_get_current_time (&tv_sec, &tv_usec);
1389
1390   if (tv_sec < start_tv_sec)
1391     ; /* clock set backward, bail out */
1392   else if (connection->disconnect_message_link == NULL)
1393     ; /* we're disconnected, bail out */
1394   else if (tv_sec < end_tv_sec ||
1395            (tv_sec == end_tv_sec && tv_usec < end_tv_usec))
1396     {
1397       timeout_milliseconds = (end_tv_sec - tv_sec) * 1000 +
1398         (end_tv_usec - tv_usec) / 1000;
1399       _dbus_verbose ("%d milliseconds remain\n", timeout_milliseconds);
1400       _dbus_assert (timeout_milliseconds > 0);
1401
1402       goto block_again; /* not expired yet */
1403     }
1404
1405   if (dbus_connection_get_is_connected (connection))
1406     dbus_set_error (error, DBUS_ERROR_NO_REPLY, "Message did not receive a reply");
1407   else
1408     dbus_set_error (error, DBUS_ERROR_DISCONNECTED, "Disconnected prior to receiving a reply");
1409
1410   dbus_mutex_unlock (connection->mutex);
1411
1412   return NULL;
1413 }
1414
1415 /**
1416  * Blocks until the outgoing message queue is empty.
1417  *
1418  * @param connection the connection.
1419  */
1420 void
1421 dbus_connection_flush (DBusConnection *connection)
1422 {
1423   /* We have to specify DBUS_ITERATION_DO_READING here
1424    * because otherwise we could have two apps deadlock
1425    * if they are both doing a flush(), and the kernel
1426    * buffers fill up.
1427    */
1428
1429   dbus_mutex_lock (connection->mutex);
1430   while (connection->n_outgoing > 0)
1431     _dbus_connection_do_iteration (connection,
1432                                    DBUS_ITERATION_DO_READING |
1433                                    DBUS_ITERATION_DO_WRITING |
1434                                    DBUS_ITERATION_BLOCK,
1435                                    -1);
1436   dbus_mutex_unlock (connection->mutex);
1437 }
1438
1439 /**
1440  * Gets the number of messages in the incoming message queue.
1441  *
1442  * @param connection the connection.
1443  * @returns the number of messages in the queue.
1444  */
1445 int
1446 dbus_connection_get_n_messages (DBusConnection *connection)
1447 {
1448   int res;
1449
1450   dbus_mutex_lock (connection->mutex);
1451   res = connection->n_incoming;
1452   dbus_mutex_unlock (connection->mutex);
1453   return res;
1454 }
1455
1456
1457 /* Call with mutex held. Will drop it while waiting and re-acquire
1458  * before returning
1459  */
1460 static void
1461 _dbus_connection_wait_for_borrowed (DBusConnection *connection)
1462 {
1463   _dbus_assert (connection->message_borrowed != NULL);
1464
1465   while (connection->message_borrowed != NULL)
1466     dbus_condvar_wait (connection->message_returned_cond, connection->mutex);
1467 }
1468
1469 /**
1470  * Returns the first-received message from the incoming message queue,
1471  * leaving it in the queue. If the queue is empty, returns #NULL.
1472  *
1473  * The caller does not own a reference to the returned message, and must
1474  * either return it using dbus_connection_return_message or keep it after
1475  * calling dbus_connection_steal_borrowed_message. No one can get at the
1476  * message while its borrowed, so return it as quickly as possible and
1477  * don't keep a reference to it after returning it. If you need to keep
1478  * the message, make a copy of it.
1479  *
1480  * @param connection the connection.
1481  * @returns next message in the incoming queue.
1482  */
1483 DBusMessage*
1484 dbus_connection_borrow_message  (DBusConnection *connection)
1485 {
1486   DBusMessage *message;
1487
1488   dbus_mutex_lock (connection->mutex);
1489
1490   if (connection->message_borrowed != NULL)
1491     _dbus_connection_wait_for_borrowed (connection);
1492
1493   message = _dbus_list_get_first (&connection->incoming_messages);
1494
1495   if (message)
1496     connection->message_borrowed = message;
1497
1498   dbus_mutex_unlock (connection->mutex);
1499   return message;
1500 }
1501
1502 /**
1503  * @todo docs
1504  */
1505 void
1506 dbus_connection_return_message (DBusConnection *connection,
1507                                 DBusMessage    *message)
1508 {
1509   dbus_mutex_lock (connection->mutex);
1510
1511   _dbus_assert (message == connection->message_borrowed);
1512
1513   connection->message_borrowed = NULL;
1514   dbus_condvar_wake_all (connection->message_returned_cond);
1515
1516   dbus_mutex_unlock (connection->mutex);
1517 }
1518
1519 /**
1520  * @todo docs
1521  */
1522 void
1523 dbus_connection_steal_borrowed_message (DBusConnection *connection,
1524                                         DBusMessage    *message)
1525 {
1526   DBusMessage *pop_message;
1527
1528   dbus_mutex_lock (connection->mutex);
1529
1530   _dbus_assert (message == connection->message_borrowed);
1531
1532   pop_message = _dbus_list_pop_first (&connection->incoming_messages);
1533   _dbus_assert (message == pop_message);
1534
1535   connection->n_incoming -= 1;
1536
1537   _dbus_verbose ("Incoming message %p stolen from queue, %d incoming\n",
1538                  message, connection->n_incoming);
1539
1540   connection->message_borrowed = NULL;
1541   dbus_condvar_wake_all (connection->message_returned_cond);
1542
1543   dbus_mutex_unlock (connection->mutex);
1544 }
1545
1546
1547 /* See dbus_connection_pop_message, but requires the caller to own
1548  * the lock before calling. May drop the lock while running.
1549  */
1550 static DBusMessage*
1551 _dbus_connection_pop_message_unlocked (DBusConnection *connection)
1552 {
1553   if (connection->message_borrowed != NULL)
1554     _dbus_connection_wait_for_borrowed (connection);
1555
1556   if (connection->n_incoming > 0)
1557     {
1558       DBusMessage *message;
1559
1560       message = _dbus_list_pop_first (&connection->incoming_messages);
1561       connection->n_incoming -= 1;
1562
1563       _dbus_verbose ("Message %p removed from incoming queue %p, %d incoming\n",
1564                      message, connection, connection->n_incoming);
1565
1566       return message;
1567     }
1568   else
1569     return NULL;
1570 }
1571
1572
1573 /**
1574  * Returns the first-received message from the incoming message queue,
1575  * removing it from the queue. The caller owns a reference to the
1576  * returned message. If the queue is empty, returns #NULL.
1577  *
1578  * @param connection the connection.
1579  * @returns next message in the incoming queue.
1580  */
1581 DBusMessage*
1582 dbus_connection_pop_message (DBusConnection *connection)
1583 {
1584   DBusMessage *message;
1585   dbus_mutex_lock (connection->mutex);
1586
1587   message = _dbus_connection_pop_message_unlocked (connection);
1588
1589   dbus_mutex_unlock (connection->mutex);
1590
1591   return message;
1592 }
1593
1594 /**
1595  * Acquire the dispatcher. This must be done before dispatching
1596  * messages in order to guarantee the right order of
1597  * message delivery. May sleep and drop the connection mutex
1598  * while waiting for the dispatcher.
1599  *
1600  * @param connection the connection.
1601  */
1602 static void
1603 _dbus_connection_acquire_dispatch (DBusConnection *connection)
1604 {
1605   if (connection->dispatch_acquired)
1606     dbus_condvar_wait (connection->dispatch_cond, connection->mutex);
1607   _dbus_assert (!connection->dispatch_acquired);
1608
1609   connection->dispatch_acquired = TRUE;
1610 }
1611
1612 /**
1613  * Release the dispatcher when you're done with it. Only call
1614  * after you've acquired the dispatcher. Wakes up at most one
1615  * thread currently waiting to acquire the dispatcher.
1616  *
1617  * @param connection the connection.
1618  */
1619 static void
1620 _dbus_connection_release_dispatch (DBusConnection *connection)
1621 {
1622   _dbus_assert (connection->dispatch_acquired);
1623
1624   connection->dispatch_acquired = FALSE;
1625   dbus_condvar_wake_one (connection->dispatch_cond);
1626 }
1627
1628 static void
1629 _dbus_connection_failed_pop (DBusConnection *connection,
1630                              DBusList *message_link)
1631 {
1632   _dbus_list_prepend_link (&connection->incoming_messages,
1633                            message_link);
1634   connection->n_incoming += 1;
1635 }
1636
1637 /**
1638  * Pops the first-received message from the current incoming message
1639  * queue, runs any handlers for it, then unrefs the message.
1640  *
1641  * @param connection the connection
1642  * @returns #TRUE if the queue is not empty after dispatch
1643  */
1644 dbus_bool_t
1645 dbus_connection_dispatch_message (DBusConnection *connection)
1646 {
1647   DBusMessageHandler *handler;
1648   DBusMessage *message;
1649   DBusList *link, *filter_list_copy, *message_link;
1650   DBusHandlerResult result;
1651   ReplyHandlerData *reply_handler_data;
1652   const char *name;
1653   dbus_int32_t reply_serial;
1654
1655   /* Preallocate link so we can put the message back on failure */
1656   message_link = _dbus_list_alloc_link (NULL);
1657   if (message_link == NULL)
1658     return FALSE;
1659
1660   dbus_mutex_lock (connection->mutex);
1661
1662   /* We need to ref the connection since the callback could potentially
1663    * drop the last ref to it */
1664   _dbus_connection_ref_unlocked (connection);
1665
1666   _dbus_connection_acquire_dispatch (connection);
1667
1668   /* This call may drop the lock during the execution (if waiting for
1669    * borrowed messages to be returned) but the order of message
1670    * dispatch if several threads call dispatch_message is still
1671    * protected by the lock, since only one will get the lock, and that
1672    * one will finish the message dispatching
1673    */
1674   message = _dbus_connection_pop_message_unlocked (connection);
1675   if (message == NULL)
1676     {
1677       _dbus_connection_release_dispatch (connection);
1678       dbus_mutex_unlock (connection->mutex);
1679       dbus_connection_unref (connection);
1680       return FALSE;
1681     }
1682
1683   message_link->data = message;
1684
1685   result = DBUS_HANDLER_RESULT_ALLOW_MORE_HANDLERS;
1686
1687   reply_serial = dbus_message_get_reply_serial (message);
1688   reply_handler_data = _dbus_hash_table_lookup_int (connection->pending_replies,
1689                                                     reply_serial);
1690
1691   if (!_dbus_list_copy (&connection->filter_list, &filter_list_copy))
1692     {
1693       _dbus_connection_release_dispatch (connection);
1694       dbus_mutex_unlock (connection->mutex);
1695       _dbus_connection_failed_pop (connection, message_link);
1696       dbus_connection_unref (connection);
1697       return FALSE;
1698     }
1699
1700   _dbus_list_foreach (&filter_list_copy,
1701                       (DBusForeachFunction)dbus_message_handler_ref,
1702                       NULL);
1703
1704   /* We're still protected from dispatch_message reentrancy here
1705    * since we acquired the dispatcher
1706    */
1707   dbus_mutex_unlock (connection->mutex);
1708
1709   link = _dbus_list_get_first_link (&filter_list_copy);
1710   while (link != NULL)
1711     {
1712       DBusMessageHandler *handler = link->data;
1713       DBusList *next = _dbus_list_get_next_link (&filter_list_copy, link);
1714
1715       result = _dbus_message_handler_handle_message (handler, connection,
1716                                                      message);
1717
1718       if (result == DBUS_HANDLER_RESULT_REMOVE_MESSAGE)
1719         break;
1720
1721       link = next;
1722     }
1723
1724   _dbus_list_foreach (&filter_list_copy,
1725                       (DBusForeachFunction)dbus_message_handler_unref,
1726                       NULL);
1727   _dbus_list_clear (&filter_list_copy);
1728
1729   dbus_mutex_lock (connection->mutex);
1730
1731   /* Did a reply we were waiting on get filtered? */
1732   if (reply_handler_data && result == DBUS_HANDLER_RESULT_REMOVE_MESSAGE)
1733     {
1734       /* Queue the timeout immediately! */
1735       if (reply_handler_data->timeout_link)
1736         {
1737           _dbus_connection_queue_synthesized_message_link (connection,
1738                                                            reply_handler_data->timeout_link);
1739           reply_handler_data->timeout_link = NULL;
1740         }
1741       else
1742         {
1743           /* We already queued the timeout? Then it was filtered! */
1744           _dbus_warn ("The timeout error with reply serial %d was filtered, so the reply handler will never be called.\n", reply_serial);
1745         }
1746     }
1747
1748   if (result == DBUS_HANDLER_RESULT_REMOVE_MESSAGE)
1749     goto out;
1750
1751   if (reply_handler_data)
1752     {
1753       dbus_mutex_unlock (connection->mutex);
1754       result = _dbus_message_handler_handle_message (reply_handler_data->handler,
1755                                                      connection, message);
1756       reply_handler_data_free (reply_handler_data);
1757       dbus_mutex_lock (connection->mutex);
1758       goto out;
1759     }
1760
1761   name = dbus_message_get_name (message);
1762   if (name != NULL)
1763     {
1764       handler = _dbus_hash_table_lookup_string (connection->handler_table,
1765                                                 name);
1766       if (handler != NULL)
1767         {
1768           /* We're still protected from dispatch_message reentrancy here
1769            * since we acquired the dispatcher */
1770           dbus_mutex_unlock (connection->mutex);
1771           result = _dbus_message_handler_handle_message (handler, connection,
1772                                                          message);
1773           dbus_mutex_lock (connection->mutex);
1774           if (result == DBUS_HANDLER_RESULT_REMOVE_MESSAGE)
1775             goto out;
1776         }
1777     }
1778
1779  out:
1780   _dbus_connection_release_dispatch (connection);
1781   dbus_mutex_unlock (connection->mutex);
1782   _dbus_list_free_link (message_link);
1783   dbus_connection_unref (connection);
1784   dbus_message_unref (message);
1785
1786   return connection->n_incoming > 0;
1787 }
1788
1789 /**
1790  * Sets the watch functions for the connection. These functions are
1791  * responsible for making the application's main loop aware of file
1792  * descriptors that need to be monitored for events, using select() or
1793  * poll(). When using Qt, typically the DBusAddWatchFunction would
1794  * create a QSocketNotifier. When using GLib, the DBusAddWatchFunction
1795  * could call g_io_add_watch(), or could be used as part of a more
1796  * elaborate GSource.
1797  *
1798  * The DBusWatch can be queried for the file descriptor to watch using
1799  * dbus_watch_get_fd(), and for the events to watch for using
1800  * dbus_watch_get_flags(). The flags returned by
1801  * dbus_watch_get_flags() will only contain DBUS_WATCH_READABLE and
1802  * DBUS_WATCH_WRITABLE, never DBUS_WATCH_HANGUP or DBUS_WATCH_ERROR;
1803  * all watches implicitly include a watch for hangups, errors, and
1804  * other exceptional conditions.
1805  *
1806  * Once a file descriptor becomes readable or writable, or an exception
1807  * occurs, dbus_connection_handle_watch() should be called to
1808  * notify the connection of the file descriptor's condition.
1809  *
1810  * dbus_connection_handle_watch() cannot be called during the
1811  * DBusAddWatchFunction, as the connection will not be ready to handle
1812  * that watch yet.
1813  *
1814  * It is not allowed to reference a DBusWatch after it has been passed
1815  * to remove_function.
1816  *
1817  * If #FALSE is returned due to lack of memory, the failure may be due
1818  * to a #FALSE return from the new add_function. If so, the
1819  * add_function may have been called successfully one or more times,
1820  * but the remove_function will also have been called to remove any
1821  * successful adds. i.e. if #FALSE is returned the net result
1822  * should be that dbus_connection_set_watch_functions() has no effect,
1823  * but the add_function and remove_function may have been called.
1824  *
1825  * @param connection the connection.
1826  * @param add_function function to begin monitoring a new descriptor.
1827  * @param remove_function function to stop monitoring a descriptor.
1828  * @param data data to pass to add_function and remove_function.
1829  * @param free_data_function function to be called to free the data.
1830  * @returns #FALSE on failure (no memory)
1831  */
1832 dbus_bool_t
1833 dbus_connection_set_watch_functions (DBusConnection              *connection,
1834                                      DBusAddWatchFunction         add_function,
1835                                      DBusRemoveWatchFunction      remove_function,
1836                                      void                        *data,
1837                                      DBusFreeFunction             free_data_function)
1838 {
1839   dbus_bool_t retval;
1840
1841   dbus_mutex_lock (connection->mutex);
1842   /* ref connection for slightly better reentrancy */
1843   _dbus_connection_ref_unlocked (connection);
1844
1845   retval = _dbus_watch_list_set_functions (connection->watches,
1846                                            add_function, remove_function,
1847                                            data, free_data_function);
1848
1849   dbus_mutex_unlock (connection->mutex);
1850   /* drop our paranoid refcount */
1851   dbus_connection_unref (connection);
1852
1853   return retval;
1854 }
1855
1856 /**
1857  * Sets the timeout functions for the connection. These functions are
1858  * responsible for making the application's main loop aware of timeouts.
1859  * When using Qt, typically the DBusAddTimeoutFunction would create a
1860  * QTimer. When using GLib, the DBusAddTimeoutFunction would call
1861  * g_timeout_add.
1862  *
1863  * The DBusTimeout can be queried for the timer interval using
1864  * dbus_timeout_get_interval(). dbus_timeout_handle() should
1865  * be called repeatedly, each time the interval elapses, starting
1866  * after it has elapsed once. The timeout stops firing when
1867  * it is removed with the given remove_function.
1868  *
1869  * @param connection the connection.
1870  * @param add_function function to add a timeout.
1871  * @param remove_function function to remove a timeout.
1872  * @param data data to pass to add_function and remove_function.
1873  * @param free_data_function function to be called to free the data.
1874  * @returns #FALSE on failure (no memory)
1875  */
1876 dbus_bool_t
1877 dbus_connection_set_timeout_functions   (DBusConnection            *connection,
1878                                          DBusAddTimeoutFunction     add_function,
1879                                          DBusRemoveTimeoutFunction  remove_function,
1880                                          void                      *data,
1881                                          DBusFreeFunction           free_data_function)
1882 {
1883   dbus_bool_t retval;
1884
1885   dbus_mutex_lock (connection->mutex);
1886   /* ref connection for slightly better reentrancy */
1887   _dbus_connection_ref_unlocked (connection);
1888
1889   retval = _dbus_timeout_list_set_functions (connection->timeouts,
1890                                              add_function, remove_function,
1891                                              data, free_data_function);
1892
1893   dbus_mutex_unlock (connection->mutex);
1894   /* drop our paranoid refcount */
1895   dbus_connection_unref (connection);
1896
1897   return retval;
1898 }
1899
1900 /**
1901  * Sets the mainloop wakeup function for the connection. Thi function is
1902  * responsible for waking up the main loop (if its sleeping) when some some
1903  * change has happened to the connection that the mainloop needs to reconsiders
1904  * (e.g. a message has been queued for writing).
1905  * When using Qt, this typically results in a call to QEventLoop::wakeUp().
1906  * When using GLib, it would call g_main_context_wakeup().
1907  *
1908  *
1909  * @param connection the connection.
1910  * @param wakeup_main_function function to wake up the mainloop
1911  * @param data data to pass wakeup_main_function
1912  * @param free_data_function function to be called to free the data.
1913  */
1914 void
1915 dbus_connection_set_wakeup_main_function (DBusConnection            *connection,
1916                                           DBusWakeupMainFunction     wakeup_main_function,
1917                                           void                      *data,
1918                                           DBusFreeFunction           free_data_function)
1919 {
1920   void *old_data;
1921   DBusFreeFunction old_free_data;
1922
1923   dbus_mutex_lock (connection->mutex);
1924   old_data = connection->wakeup_main_data;
1925   old_free_data = connection->free_wakeup_main_data;
1926
1927   connection->wakeup_main_function = wakeup_main_function;
1928   connection->wakeup_main_data = data;
1929   connection->free_wakeup_main_data = free_data_function;
1930
1931   dbus_mutex_unlock (connection->mutex);
1932
1933   /* Callback outside the lock */
1934   if (old_free_data)
1935     (*old_free_data) (old_data);
1936 }
1937
1938 /**
1939  * Called to notify the connection when a previously-added watch
1940  * is ready for reading or writing, or has an exception such
1941  * as a hangup.
1942  *
1943  * @param connection the connection.
1944  * @param watch the watch.
1945  * @param condition the current condition of the file descriptors being watched.
1946  */
1947 void
1948 dbus_connection_handle_watch (DBusConnection              *connection,
1949                               DBusWatch                   *watch,
1950                               unsigned int                 condition)
1951 {
1952   dbus_mutex_lock (connection->mutex);
1953   _dbus_connection_acquire_io_path (connection, -1);
1954   _dbus_transport_handle_watch (connection->transport,
1955                                 watch, condition);
1956   _dbus_connection_release_io_path (connection);
1957   dbus_mutex_unlock (connection->mutex);
1958 }
1959
1960 /**
1961  * Adds a message filter. Filters are handlers that are run on
1962  * all incoming messages, prior to the normal handlers
1963  * registered with dbus_connection_register_handler().
1964  * Filters are run in the order that they were added.
1965  * The same handler can be added as a filter more than once, in
1966  * which case it will be run more than once.
1967  * Filters added during a filter callback won't be run on the
1968  * message being processed.
1969  *
1970  * @param connection the connection
1971  * @param handler the handler
1972  * @returns #TRUE on success, #FALSE if not enough memory.
1973  */
1974 dbus_bool_t
1975 dbus_connection_add_filter (DBusConnection      *connection,
1976                             DBusMessageHandler  *handler)
1977 {
1978   dbus_mutex_lock (connection->mutex);
1979   if (!_dbus_message_handler_add_connection (handler, connection))
1980     {
1981       dbus_mutex_unlock (connection->mutex);
1982       return FALSE;
1983     }
1984
1985   if (!_dbus_list_append (&connection->filter_list,
1986                           handler))
1987     {
1988       _dbus_message_handler_remove_connection (handler, connection);
1989       dbus_mutex_unlock (connection->mutex);
1990       return FALSE;
1991     }
1992
1993   dbus_mutex_unlock (connection->mutex);
1994   return TRUE;
1995 }
1996
1997 /**
1998  * Removes a previously-added message filter. It is a programming
1999  * error to call this function for a handler that has not
2000  * been added as a filter. If the given handler was added
2001  * more than once, only one instance of it will be removed
2002  * (the most recently-added instance).
2003  *
2004  * @param connection the connection
2005  * @param handler the handler to remove
2006  *
2007  */
2008 void
2009 dbus_connection_remove_filter (DBusConnection      *connection,
2010                                DBusMessageHandler  *handler)
2011 {
2012   dbus_mutex_lock (connection->mutex);
2013   if (!_dbus_list_remove_last (&connection->filter_list, handler))
2014     {
2015       _dbus_warn ("Tried to remove a DBusConnection filter that had not been added\n");
2016       dbus_mutex_unlock (connection->mutex);
2017       return;
2018     }
2019
2020   _dbus_message_handler_remove_connection (handler, connection);
2021
2022   dbus_mutex_unlock (connection->mutex);
2023 }
2024
2025 /**
2026  * Registers a handler for a list of message names. A single handler
2027  * can be registered for any number of message names, but each message
2028  * name can only have one handler at a time. It's not allowed to call
2029  * this function with the name of a message that already has a
2030  * handler. If the function returns #FALSE, the handlers were not
2031  * registered due to lack of memory.
2032  *
2033  * @todo the messages_to_handle arg may be more convenient if it's a
2034  * single string instead of an array. Though right now MessageHandler
2035  * is sort of designed to say be associated with an entire object with
2036  * multiple methods, that's why for example the connection only
2037  * weakrefs it.  So maybe the "manual" API should be different.
2038  *
2039  * @param connection the connection
2040  * @param handler the handler
2041  * @param messages_to_handle the messages to handle
2042  * @param n_messages the number of message names in messages_to_handle
2043  * @returns #TRUE on success, #FALSE if no memory or another handler already exists
2044  *
2045  **/
2046 dbus_bool_t
2047 dbus_connection_register_handler (DBusConnection     *connection,
2048                                   DBusMessageHandler *handler,
2049                                   const char        **messages_to_handle,
2050                                   int                 n_messages)
2051 {
2052   int i;
2053
2054   dbus_mutex_lock (connection->mutex);
2055   i = 0;
2056   while (i < n_messages)
2057     {
2058       DBusHashIter iter;
2059       char *key;
2060
2061       key = _dbus_strdup (messages_to_handle[i]);
2062       if (key == NULL)
2063         goto failed;
2064
2065       if (!_dbus_hash_iter_lookup (connection->handler_table,
2066                                    key, TRUE,
2067                                    &iter))
2068         {
2069           dbus_free (key);
2070           goto failed;
2071         }
2072
2073       if (_dbus_hash_iter_get_value (&iter) != NULL)
2074         {
2075           _dbus_warn ("Bug in application: attempted to register a second handler for %s\n",
2076                       messages_to_handle[i]);
2077           dbus_free (key); /* won't have replaced the old key with the new one */
2078           goto failed;
2079         }
2080
2081       if (!_dbus_message_handler_add_connection (handler, connection))
2082         {
2083           _dbus_hash_iter_remove_entry (&iter);
2084           /* key has freed on nuking the entry */
2085           goto failed;
2086         }
2087
2088       _dbus_hash_iter_set_value (&iter, handler);
2089
2090       ++i;
2091     }
2092
2093   dbus_mutex_unlock (connection->mutex);
2094   return TRUE;
2095
2096  failed:
2097   /* unregister everything registered so far,
2098    * so we don't fail partially
2099    */
2100   dbus_connection_unregister_handler (connection,
2101                                       handler,
2102                                       messages_to_handle,
2103                                       i);
2104
2105   dbus_mutex_unlock (connection->mutex);
2106   return FALSE;
2107 }
2108
2109 /**
2110  * Unregisters a handler for a list of message names. The handlers
2111  * must have been previously registered.
2112  *
2113  * @param connection the connection
2114  * @param handler the handler
2115  * @param messages_to_handle the messages to handle
2116  * @param n_messages the number of message names in messages_to_handle
2117  *
2118  **/
2119 void
2120 dbus_connection_unregister_handler (DBusConnection     *connection,
2121                                     DBusMessageHandler *handler,
2122                                     const char        **messages_to_handle,
2123                                     int                 n_messages)
2124 {
2125   int i;
2126
2127   dbus_mutex_lock (connection->mutex);
2128   i = 0;
2129   while (i < n_messages)
2130     {
2131       DBusHashIter iter;
2132
2133       if (!_dbus_hash_iter_lookup (connection->handler_table,
2134                                    (char*) messages_to_handle[i], FALSE,
2135                                    &iter))
2136         {
2137           _dbus_warn ("Bug in application: attempted to unregister handler for %s which was not registered\n",
2138                       messages_to_handle[i]);
2139         }
2140       else if (_dbus_hash_iter_get_value (&iter) != handler)
2141         {
2142           _dbus_warn ("Bug in application: attempted to unregister handler for %s which was registered by a different handler\n",
2143                       messages_to_handle[i]);
2144         }
2145       else
2146         {
2147           _dbus_hash_iter_remove_entry (&iter);
2148           _dbus_message_handler_remove_connection (handler, connection);
2149         }
2150
2151       ++i;
2152     }
2153
2154   dbus_mutex_unlock (connection->mutex);
2155 }
2156
2157 static DBusDataSlotAllocator slot_allocator;
2158
2159 /**
2160  * Initialize the mutex used for #DBusConnection data
2161  * slot reservations.
2162  *
2163  * @returns the mutex
2164  */
2165 DBusMutex *
2166 _dbus_connection_slots_init_lock (void)
2167 {
2168   if (!_dbus_data_slot_allocator_init (&slot_allocator))
2169     return NULL;
2170   else
2171     return slot_allocator.lock;
2172 }
2173
2174 /**
2175  * Allocates an integer ID to be used for storing application-specific
2176  * data on any DBusConnection. The allocated ID may then be used
2177  * with dbus_connection_set_data() and dbus_connection_get_data().
2178  * If allocation fails, -1 is returned. Again, the allocated
2179  * slot is global, i.e. all DBusConnection objects will
2180  * have a slot with the given integer ID reserved.
2181  *
2182  * @returns -1 on failure, otherwise the data slot ID
2183  */
2184 int
2185 dbus_connection_allocate_data_slot (void)
2186 {
2187   return _dbus_data_slot_allocator_alloc (&slot_allocator);
2188 }
2189
2190 /**
2191  * Deallocates a global ID for connection data slots.
2192  * dbus_connection_get_data() and dbus_connection_set_data()
2193  * may no longer be used with this slot.
2194  * Existing data stored on existing DBusConnection objects
2195  * will be freed when the connection is finalized,
2196  * but may not be retrieved (and may only be replaced
2197  * if someone else reallocates the slot).
2198  *
2199  * @param slot the slot to deallocate
2200  */
2201 void
2202 dbus_connection_free_data_slot (int slot)
2203 {
2204   _dbus_data_slot_allocator_free (&slot_allocator, slot);
2205 }
2206
2207 /**
2208  * Stores a pointer on a DBusConnection, along
2209  * with an optional function to be used for freeing
2210  * the data when the data is set again, or when
2211  * the connection is finalized. The slot number
2212  * must have been allocated with dbus_connection_allocate_data_slot().
2213  *
2214  * @param connection the connection
2215  * @param slot the slot number
2216  * @param data the data to store
2217  * @param free_data_func finalizer function for the data
2218  * @returns #TRUE if there was enough memory to store the data
2219  */
2220 dbus_bool_t
2221 dbus_connection_set_data (DBusConnection   *connection,
2222                           int               slot,
2223                           void             *data,
2224                           DBusFreeFunction  free_data_func)
2225 {
2226   DBusFreeFunction old_free_func;
2227   void *old_data;
2228   dbus_bool_t retval;
2229
2230   dbus_mutex_lock (connection->mutex);
2231
2232   retval = _dbus_data_slot_list_set (&slot_allocator,
2233                                      &connection->slot_list,
2234                                      slot, data, free_data_func,
2235                                      &old_free_func, &old_data);
2236
2237   dbus_mutex_unlock (connection->mutex);
2238
2239   if (retval)
2240     {
2241       /* Do the actual free outside the connection lock */
2242       if (old_free_func)
2243         (* old_free_func) (old_data);
2244     }
2245
2246   return retval;
2247 }
2248
2249 /**
2250  * Retrieves data previously set with dbus_connection_set_data().
2251  * The slot must still be allocated (must not have been freed).
2252  *
2253  * @param connection the connection
2254  * @param slot the slot to get data from
2255  * @returns the data, or #NULL if not found
2256  */
2257 void*
2258 dbus_connection_get_data (DBusConnection   *connection,
2259                           int               slot)
2260 {
2261   void *res;
2262
2263   dbus_mutex_lock (connection->mutex);
2264
2265   res = _dbus_data_slot_list_get (&slot_allocator,
2266                                   &connection->slot_list,
2267                                   slot);
2268
2269   dbus_mutex_unlock (connection->mutex);
2270
2271   return res;
2272 }
2273
2274 /**
2275  * This function sets a global flag for whether dbus_connection_new()
2276  * will set SIGPIPE behavior to SIG_IGN.
2277  *
2278  * @param will_modify_sigpipe #TRUE to allow sigpipe to be set to SIG_IGN
2279  */
2280 void
2281 dbus_connection_set_change_sigpipe (dbus_bool_t will_modify_sigpipe)
2282 {
2283   _dbus_modify_sigpipe = will_modify_sigpipe;
2284 }
2285
2286 /**
2287  * Specifies the maximum size message this connection is allowed to
2288  * receive. Larger messages will result in disconnecting the
2289  * connection.
2290  *
2291  * @param connection a #DBusConnection
2292  * @param size maximum message size the connection can receive, in bytes
2293  */
2294 void
2295 dbus_connection_set_max_message_size (DBusConnection *connection,
2296                                       long            size)
2297 {
2298   dbus_mutex_lock (connection->mutex);
2299   _dbus_transport_set_max_message_size (connection->transport,
2300                                         size);
2301   dbus_mutex_unlock (connection->mutex);
2302 }
2303
2304 /**
2305  * Gets the value set by dbus_connection_set_max_message_size().
2306  *
2307  * @param connection the connection
2308  * @returns the max size of a single message
2309  */
2310 long
2311 dbus_connection_get_max_message_size (DBusConnection *connection)
2312 {
2313   long res;
2314   dbus_mutex_lock (connection->mutex);
2315   res = _dbus_transport_get_max_message_size (connection->transport);
2316   dbus_mutex_unlock (connection->mutex);
2317   return res;
2318 }
2319
2320 /**
2321  * Sets the maximum total number of bytes that can be used for all messages
2322  * received on this connection. Messages count toward the maximum until
2323  * they are finalized. When the maximum is reached, the connection will
2324  * not read more data until some messages are finalized.
2325  *
2326  * The semantics of the maximum are: if outstanding messages are
2327  * already above the maximum, additional messages will not be read.
2328  * The semantics are not: if the next message would cause us to exceed
2329  * the maximum, we don't read it. The reason is that we don't know the
2330  * size of a message until after we read it.
2331  *
2332  * Thus, the max live messages size can actually be exceeded
2333  * by up to the maximum size of a single message.
2334  *
2335  * Also, if we read say 1024 bytes off the wire in a single read(),
2336  * and that contains a half-dozen small messages, we may exceed the
2337  * size max by that amount. But this should be inconsequential.
2338  *
2339  * @param connection the connection
2340  * @param size the maximum size in bytes of all outstanding messages
2341  */
2342 void
2343 dbus_connection_set_max_live_messages_size (DBusConnection *connection,
2344                                             long            size)
2345 {
2346   dbus_mutex_lock (connection->mutex);
2347   _dbus_transport_set_max_live_messages_size (connection->transport,
2348                                               size);
2349   dbus_mutex_unlock (connection->mutex);
2350 }
2351
2352 /**
2353  * Gets the value set by dbus_connection_set_max_live_messages_size().
2354  *
2355  * @param connection the connection
2356  * @returns the max size of all live messages
2357  */
2358 long
2359 dbus_connection_get_max_live_messages_size (DBusConnection *connection)
2360 {
2361   long res;
2362   dbus_mutex_lock (connection->mutex);
2363   res = _dbus_transport_get_max_live_messages_size (connection->transport);
2364   dbus_mutex_unlock (connection->mutex);
2365   return res;
2366 }
2367
2368 /** @} */