dbus/dbus-pending-call.c

   1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
   2 /* dbus-pending-call.c Object representing a call in progress.
   3  *
   4  * Copyright (C) 2002, 2003 Red Hat Inc.
   5  *
   6  * Licensed under the Academic Free License version 2.1
   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., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  21  *
  22  */
  23
  24 #include <config.h>
  25 #include "dbus-internals.h"
  26 #include "dbus-connection-internal.h"
  27 #include "dbus-message-internal.h"
  28 #include "dbus-pending-call-internal.h"
  29 #include "dbus-pending-call.h"
  30 #include "dbus-list.h"
  31 #include "dbus-threads.h"
  32 #include "dbus-test.h"
  33
  34 /**
  35  * @defgroup DBusPendingCallInternals DBusPendingCall implementation details
  36  * @ingroup DBusInternals
  37  * @brief DBusPendingCall private implementation details.
  38  *
  39  * The guts of DBusPendingCall and its methods.
  40  *
  41  * @{
  42  */
  43
  44 /**
  45  * @brief Internals of DBusPendingCall
  46  *
  47  * Opaque object representing a reply message that we're waiting for.
  48  */
  49
  50 /**
  51  * shorter and more visible way to write _dbus_connection_lock()
  52  */
  53 #define CONNECTION_LOCK(connection)   _dbus_connection_lock(connection)
  54 /**
  55  * shorter and more visible way to write _dbus_connection_unlock()
  56  */
  57 #define CONNECTION_UNLOCK(connection) _dbus_connection_unlock(connection)
  58
  59 /**
  60  * Implementation details of #DBusPendingCall - all fields are private.
  61  */
  62 struct DBusPendingCall
  63 {
  64   DBusAtomic refcount;                            /**< reference count */
  65
  66   DBusDataSlotList slot_list;                     /**< Data stored by allocated integer ID */
  67
  68   DBusPendingCallNotifyFunction function;         /**< Notifier when reply arrives. */
  69
  70   DBusConnection *connection;                     /**< Connections we're associated with */
  71   DBusMessage *reply;                             /**< Reply (after we've received it) */
  72   DBusTimeout *timeout;                           /**< Timeout */
  73
  74   DBusList *timeout_link;                         /**< Preallocated timeout response */
  75
  76   dbus_uint32_t reply_serial;                     /**< Expected serial of reply */
  77
  78   unsigned int completed : 1;                     /**< TRUE if completed */
  79   unsigned int timeout_added : 1;                 /**< Have added the timeout */
  80 };
  81
  82 #ifdef DBUS_ENABLE_VERBOSE_MODE
  83 static void
  84 _dbus_pending_call_trace_ref (DBusPendingCall *pending_call,
  85     int old_refcount,
  86     int new_refcount,
  87     const char *why)
  88 {
  89   static int enabled = -1;
  90
  91   _dbus_trace_ref ("DBusPendingCall", pending_call, old_refcount,
  92       new_refcount, why, "DBUS_PENDING_CALL_TRACE", &enabled);
  93 }
  94 #else
  95 #define _dbus_pending_call_trace_ref(p, o, n, w) \
  96   do \
  97   {\
  98     (void) (o); \
  99     (void) (n); \
 100   } while (0)
 101 #endif
 102
 103 static dbus_int32_t notify_user_data_slot = -1;
 104
 105 /**
 106  * Creates a new pending reply object.
 107  *
 108  * @param connection connection where reply will arrive
 109  * @param timeout_milliseconds length of timeout, -1 (or
 110  *  #DBUS_TIMEOUT_USE_DEFAULT) for default,
 111  *  #DBUS_TIMEOUT_INFINITE for no timeout
 112  * @param timeout_handler timeout handler, takes pending call as data
 113  * @returns a new #DBusPendingCall or #NULL if no memory.
 114  */
 115 DBusPendingCall*
 116 _dbus_pending_call_new_unlocked (DBusConnection    *connection,
 117                                  int                timeout_milliseconds,
 118                                  DBusTimeoutHandler timeout_handler)
 119 {
 120   DBusPendingCall *pending;
 121   DBusTimeout *timeout;
 122
 123   _dbus_assert (timeout_milliseconds >= 0 || timeout_milliseconds == -1);
 124
 125   if (timeout_milliseconds == -1)
 126     timeout_milliseconds = _DBUS_DEFAULT_TIMEOUT_VALUE;
 127
 128   if (!dbus_pending_call_allocate_data_slot (&notify_user_data_slot))
 129     return NULL;
 130
 131   pending = dbus_new0 (DBusPendingCall, 1);
 132
 133   if (pending == NULL)
 134     {
 135       dbus_pending_call_free_data_slot (&notify_user_data_slot);
 136       return NULL;
 137     }
 138
 139   if (timeout_milliseconds != DBUS_TIMEOUT_INFINITE)
 140     {
 141       timeout = _dbus_timeout_new (timeout_milliseconds,
 142                                    timeout_handler,
 143                                    pending, NULL);
 144
 145       if (timeout == NULL)
 146         {
 147           dbus_pending_call_free_data_slot (&notify_user_data_slot);
 148           dbus_free (pending);
 149           return NULL;
 150         }
 151
 152       pending->timeout = timeout;
 153     }
 154   else
 155     {
 156       pending->timeout = NULL;
 157     }
 158
 159   _dbus_atomic_inc (&pending->refcount);
 160   pending->connection = connection;
 161   _dbus_connection_ref_unlocked (pending->connection);
 162
 163   _dbus_data_slot_list_init (&pending->slot_list);
 164
 165   _dbus_pending_call_trace_ref (pending, 0, 1, "new_unlocked");
 166
 167   return pending;
 168 }
 169
 170 /**
 171  * Sets the reply of a pending call with the given message,
 172  * or if the message is #NULL, by timing out the pending call.
 173  *
 174  * @param pending the pending call
 175  * @param message the message to complete the call with, or #NULL
 176  *  to time out the call
 177  */
 178 void
 179 _dbus_pending_call_set_reply_unlocked (DBusPendingCall *pending,
 180                                        DBusMessage     *message)
 181 {
 182   if (message == NULL)
 183     {
 184       message = pending->timeout_link->data;
 185       _dbus_list_clear (&pending->timeout_link);
 186     }
 187   else
 188     dbus_message_ref (message);
 189
 190   _dbus_verbose ("  handing message %p (%s) to pending call serial %u\n",
 191                  message,
 192                  dbus_message_get_type (message) == DBUS_MESSAGE_TYPE_METHOD_RETURN ?
 193                  "method return" :
 194                  dbus_message_get_type (message) == DBUS_MESSAGE_TYPE_ERROR ?
 195                  "error" : "other type",
 196                  pending->reply_serial);
 197
 198   _dbus_assert (pending->reply == NULL);
 199   _dbus_assert (pending->reply_serial == dbus_message_get_reply_serial (message));
 200   pending->reply = message;
 201 }
 202
 203 /**
 204  * Calls notifier function for the pending call
 205  * and sets the call to completed.
 206  *
 207  * @param pending the pending call
 208  *
 209  */
 210 void
 211 _dbus_pending_call_complete (DBusPendingCall *pending)
 212 {
 213   _dbus_assert (!pending->completed);
 214
 215   pending->completed = TRUE;
 216
 217   if (pending->function)
 218     {
 219       void *user_data;
 220       user_data = dbus_pending_call_get_data (pending,
 221                                               notify_user_data_slot);
 222
 223       (* pending->function) (pending, user_data);
 224     }
 225 }
 226
 227 /**
 228  * If the pending call hasn't been timed out, add its timeout
 229  * error reply to the connection's incoming message queue.
 230  *
 231  * @param pending the pending call
 232  * @param connection the connection the call was sent to
 233  */
 234 void
 235 _dbus_pending_call_queue_timeout_error_unlocked (DBusPendingCall *pending,
 236                                                  DBusConnection  *connection)
 237 {
 238   _dbus_assert (connection == pending->connection);
 239
 240   if (pending->timeout_link)
 241     {
 242       _dbus_connection_queue_synthesized_message_link (connection,
 243                                                        pending->timeout_link);
 244       pending->timeout_link = NULL;
 245     }
 246 }
 247
 248 /**
 249  * Checks to see if a timeout has been added
 250  *
 251  * @param pending the pending_call
 252  * @returns #TRUE if there is a timeout or #FALSE if not
 253  */
 254 dbus_bool_t
 255 _dbus_pending_call_is_timeout_added_unlocked (DBusPendingCall  *pending)
 256 {
 257   _dbus_assert (pending != NULL);
 258
 259   return pending->timeout_added;
 260 }
 261
 262
 263 /**
 264  * Sets wether the timeout has been added
 265  *
 266  * @param pending the pending_call
 267  * @param is_added whether or not a timeout is added
 268  */
 269 void
 270 _dbus_pending_call_set_timeout_added_unlocked (DBusPendingCall  *pending,
 271                                                dbus_bool_t       is_added)
 272 {
 273   _dbus_assert (pending != NULL);
 274
 275   pending->timeout_added = is_added;
 276 }
 277
 278
 279 /**
 280  * Retrives the timeout
 281  *
 282  * @param pending the pending_call
 283  * @returns a timeout object or NULL if call has no timeout
 284  */
 285 DBusTimeout *
 286 _dbus_pending_call_get_timeout_unlocked (DBusPendingCall  *pending)
 287 {
 288   _dbus_assert (pending != NULL);
 289
 290   return pending->timeout;
 291 }
 292
 293 /**
 294  * Gets the reply's serial number
 295  *
 296  * @param pending the pending_call
 297  * @returns a serial number for the reply or 0
 298  */
 299 dbus_uint32_t
 300 _dbus_pending_call_get_reply_serial_unlocked (DBusPendingCall  *pending)
 301 {
 302   _dbus_assert (pending != NULL);
 303
 304   return pending->reply_serial;
 305 }
 306
 307 /**
 308  * Sets the reply's serial number
 309  *
 310  * @param pending the pending_call
 311  * @param serial the serial number
 312  */
 313 void
 314 _dbus_pending_call_set_reply_serial_unlocked  (DBusPendingCall *pending,
 315                                                dbus_uint32_t serial)
 316 {
 317   _dbus_assert (pending != NULL);
 318   _dbus_assert (pending->reply_serial == 0);
 319
 320   pending->reply_serial = serial;
 321 }
 322
 323 /**
 324  * Gets the connection associated with this pending call.
 325  *
 326  * @param pending the pending_call
 327  * @returns the connection associated with the pending call
 328  */
 329 DBusConnection *
 330 _dbus_pending_call_get_connection_and_lock (DBusPendingCall *pending)
 331 {
 332   _dbus_assert (pending != NULL);
 333
 334   CONNECTION_LOCK (pending->connection);
 335   return pending->connection;
 336 }
 337
 338 /**
 339  * Gets the connection associated with this pending call.
 340  *
 341  * @param pending the pending_call
 342  * @returns the connection associated with the pending call
 343  */
 344 DBusConnection *
 345 _dbus_pending_call_get_connection_unlocked (DBusPendingCall *pending)
 346 {
 347   _dbus_assert (pending != NULL);
 348
 349   return pending->connection;
 350 }
 351
 352 /**
 353  * Sets the reply message associated with the pending call to a timeout error
 354  *
 355  * @param pending the pending_call
 356  * @param message the message we are sending the error reply to
 357  * @param serial serial number for the reply
 358  * @return #FALSE on OOM
 359  */
 360 dbus_bool_t
 361 _dbus_pending_call_set_timeout_error_unlocked (DBusPendingCall *pending,
 362                                                DBusMessage     *message,
 363                                                dbus_uint32_t    serial)
 364 {
 365   DBusList *reply_link;
 366   DBusMessage *reply;
 367
 368   reply = dbus_message_new_error (message, DBUS_ERROR_NO_REPLY,
 369                                   "Did not receive a reply. Possible causes include: "
 370                                   "the remote application did not send a reply, "
 371                                   "the message bus security policy blocked the reply, "
 372                                   "the reply timeout expired, or "
 373                                   "the network connection was broken.");
 374   if (reply == NULL)
 375     return FALSE;
 376
 377   reply_link = _dbus_list_alloc_link (reply);
 378   if (reply_link == NULL)
 379     {
 380       /* it's OK to unref this, nothing that could have attached a callback
 381        * has ever seen it */
 382       dbus_message_unref (reply);
 383       return FALSE;
 384     }
 385
 386   pending->timeout_link = reply_link;
 387
 388   _dbus_pending_call_set_reply_serial_unlocked (pending, serial);
 389
 390   return TRUE;
 391 }
 392
 393 /**
 394  * Increments the reference count on a pending call,
 395  * while the lock on its connection is already held.
 396  *
 397  * @param pending the pending call object
 398  * @returns the pending call object
 399  */
 400 DBusPendingCall *
 401 _dbus_pending_call_ref_unlocked (DBusPendingCall *pending)
 402 {
 403   dbus_int32_t old_refcount;
 404
 405   old_refcount = _dbus_atomic_inc (&pending->refcount);
 406   _dbus_pending_call_trace_ref (pending, old_refcount, old_refcount + 1,
 407       "ref_unlocked");
 408
 409   return pending;
 410 }
 411
 412
 413 static void
 414 _dbus_pending_call_last_unref (DBusPendingCall *pending)
 415 {
 416   DBusConnection *connection;
 417
 418   /* If we get here, we should be already detached
 419    * from the connection, or never attached.
 420    */
 421   _dbus_assert (!pending->timeout_added);
 422
 423   connection = pending->connection;
 424
 425   /* this assumes we aren't holding connection lock... */
 426   _dbus_data_slot_list_free (&pending->slot_list);
 427
 428   if (pending->timeout != NULL)
 429     _dbus_timeout_unref (pending->timeout);
 430
 431   if (pending->timeout_link)
 432     {
 433       dbus_message_unref ((DBusMessage *)pending->timeout_link->data);
 434       _dbus_list_free_link (pending->timeout_link);
 435       pending->timeout_link = NULL;
 436     }
 437
 438   if (pending->reply)
 439     {
 440       dbus_message_unref (pending->reply);
 441       pending->reply = NULL;
 442     }
 443
 444   dbus_free (pending);
 445
 446   dbus_pending_call_free_data_slot (&notify_user_data_slot);
 447
 448   /* connection lock should not be held. */
 449   /* Free the connection last to avoid a weird state while
 450    * calling out to application code where the pending exists
 451    * but not the connection.
 452    */
 453   dbus_connection_unref (connection);
 454 }
 455
 456 /**
 457  * Decrements the reference count on a pending call,
 458  * freeing it if the count reaches 0. Assumes
 459  * connection lock is already held.
 460  *
 461  * @param pending the pending call object
 462  */
 463 void
 464 _dbus_pending_call_unref_and_unlock (DBusPendingCall *pending)
 465 {
 466   dbus_int32_t old_refcount;
 467
 468   old_refcount = _dbus_atomic_dec (&pending->refcount);
 469   _dbus_assert (old_refcount > 0);
 470   _dbus_pending_call_trace_ref (pending, old_refcount,
 471       old_refcount - 1, "unref_and_unlock");
 472
 473   CONNECTION_UNLOCK (pending->connection);
 474
 475   if (old_refcount == 1)
 476     _dbus_pending_call_last_unref (pending);
 477 }
 478
 479 /**
 480  * Checks whether the pending call has received a reply
 481  * yet, or not. Assumes connection lock is held.
 482  *
 483  * @param pending the pending call
 484  * @returns #TRUE if a reply has been received
 485  */
 486 dbus_bool_t
 487 _dbus_pending_call_get_completed_unlocked (DBusPendingCall    *pending)
 488 {
 489   return pending->completed;
 490 }
 491
 492 static DBusDataSlotAllocator slot_allocator;
 493 _DBUS_DEFINE_GLOBAL_LOCK (pending_call_slots);
 494
 495 /**
 496  * Stores a pointer on a #DBusPendingCall, along
 497  * with an optional function to be used for freeing
 498  * the data when the data is set again, or when
 499  * the pending call is finalized. The slot number
 500  * must have been allocated with dbus_pending_call_allocate_data_slot().
 501  *
 502  * @param pending the pending_call
 503  * @param slot the slot number
 504  * @param data the data to store
 505  * @param free_data_func finalizer function for the data
 506  * @returns #TRUE if there was enough memory to store the data
 507  */
 508 dbus_bool_t
 509 _dbus_pending_call_set_data_unlocked (DBusPendingCall  *pending,
 510                                      dbus_int32_t      slot,
 511                                      void             *data,
 512                                      DBusFreeFunction  free_data_func)
 513 {
 514   DBusFreeFunction old_free_func;
 515   void *old_data;
 516   dbus_bool_t retval;
 517
 518   retval = _dbus_data_slot_list_set (&slot_allocator,
 519                                      &pending->slot_list,
 520                                      slot, data, free_data_func,
 521                                      &old_free_func, &old_data);
 522
 523   /* Drop locks to call out to app code */
 524   CONNECTION_UNLOCK (pending->connection);
 525
 526   if (retval)
 527     {
 528       if (old_free_func)
 529         (* old_free_func) (old_data);
 530     }
 531
 532   CONNECTION_LOCK (pending->connection);
 533
 534   return retval;
 535 }
 536
 537 /** @} */
 538
 539 /**
 540  * @defgroup DBusPendingCall DBusPendingCall
 541  * @ingroup  DBus
 542  * @brief Pending reply to a method call message
 543  *
 544  * A DBusPendingCall is an object representing an
 545  * expected reply. A #DBusPendingCall can be created
 546  * when you send a message that should have a reply.
 547  *
 548  * @{
 549  */
 550
 551 /**
 552  * @def DBUS_TIMEOUT_INFINITE
 553  *
 554  * An integer constant representing an infinite timeout. This has the
 555  * numeric value 0x7fffffff (the largest 32-bit signed integer).
 556  *
 557  * For source compatibility with D-Bus versions earlier than 1.4.12, use
 558  * 0x7fffffff, or INT32_MAX (assuming your platform has it).
 559  */
 560
 561 /**
 562  * @def DBUS_TIMEOUT_USE_DEFAULT
 563  *
 564  * An integer constant representing a request to use the default timeout.
 565  * This has numeric value -1.
 566  *
 567  * For source compatibility with D-Bus versions earlier than 1.4.12, use a
 568  * literal -1.
 569  */
 570
 571 /**
 572  * @typedef DBusPendingCall
 573  *
 574  * Opaque data type representing a message pending.
 575  */
 576
 577 /**
 578  * Increments the reference count on a pending call.
 579  *
 580  * @param pending the pending call object
 581  * @returns the pending call object
 582  */
 583 DBusPendingCall *
 584 dbus_pending_call_ref (DBusPendingCall *pending)
 585 {
 586   dbus_int32_t old_refcount;
 587
 588   _dbus_return_val_if_fail (pending != NULL, NULL);
 589
 590   old_refcount = _dbus_atomic_inc (&pending->refcount);
 591   _dbus_pending_call_trace_ref (pending, old_refcount, old_refcount + 1,
 592       "ref");
 593
 594   return pending;
 595 }
 596
 597 /**
 598  * Decrements the reference count on a pending call,
 599  * freeing it if the count reaches 0.
 600  *
 601  * @param pending the pending call object
 602  */
 603 void
 604 dbus_pending_call_unref (DBusPendingCall *pending)
 605 {
 606   dbus_int32_t old_refcount;
 607
 608   _dbus_return_if_fail (pending != NULL);
 609
 610   old_refcount = _dbus_atomic_dec (&pending->refcount);
 611   _dbus_pending_call_trace_ref (pending, old_refcount, old_refcount - 1,
 612       "unref");
 613
 614   if (old_refcount == 1)
 615     _dbus_pending_call_last_unref(pending);
 616 }
 617
 618 /**
 619  * Sets a notification function to be called when the reply is
 620  * received or the pending call times out.
 621  *
 622  * @param pending the pending call
 623  * @param function notifier function
 624  * @param user_data data to pass to notifier function
 625  * @param free_user_data function to free the user data
 626  * @returns #FALSE if not enough memory
 627  */
 628 dbus_bool_t
 629 dbus_pending_call_set_notify (DBusPendingCall              *pending,
 630                               DBusPendingCallNotifyFunction function,
 631                               void                         *user_data,
 632                               DBusFreeFunction              free_user_data)
 633 {
 634   _dbus_return_val_if_fail (pending != NULL, FALSE);
 635
 636   CONNECTION_LOCK (pending->connection);
 637
 638   /* could invoke application code! */
 639   if (!_dbus_pending_call_set_data_unlocked (pending, notify_user_data_slot,
 640                                              user_data, free_user_data))
 641     return FALSE;
 642
 643   pending->function = function;
 644
 645   CONNECTION_UNLOCK (pending->connection);
 646
 647   return TRUE;
 648 }
 649
 650 /**
 651  * Cancels the pending call, such that any reply or error received
 652  * will just be ignored.  Drops the dbus library's internal reference
 653  * to the #DBusPendingCall so will free the call if nobody else is
 654  * holding a reference. However you usually get a reference from
 655  * dbus_connection_send_with_reply() so probably your app owns a ref
 656  * also.
 657  *
 658  * Note that canceling a pending call will <em>not</em> simulate a
 659  * timed-out call; if a call times out, then a timeout error reply is
 660  * received. If you cancel the call, no reply is received unless the
 661  * the reply was already received before you canceled.
 662  *
 663  * @param pending the pending call
 664  */
 665 void
 666 dbus_pending_call_cancel (DBusPendingCall *pending)
 667 {
 668   _dbus_return_if_fail (pending != NULL);
 669
 670   _dbus_connection_remove_pending_call (pending->connection,
 671                                         pending);
 672 }
 673
 674 /**
 675  * Checks whether the pending call has received a reply
 676  * yet, or not.
 677  *
 678  * @param pending the pending call
 679  * @returns #TRUE if a reply has been received
 680  */
 681 dbus_bool_t
 682 dbus_pending_call_get_completed (DBusPendingCall *pending)
 683 {
 684   dbus_bool_t completed;
 685
 686   _dbus_return_val_if_fail (pending != NULL, FALSE);
 687
 688   CONNECTION_LOCK (pending->connection);
 689   completed = pending->completed;
 690   CONNECTION_UNLOCK (pending->connection);
 691
 692   return completed;
 693 }
 694
 695 /**
 696  * Gets the reply, or returns #NULL if none has been received
 697  * yet. Ownership of the reply message passes to the caller. This
 698  * function can only be called once per pending call, since the reply
 699  * message is tranferred to the caller.
 700  *
 701  * @param pending the pending call
 702  * @returns the reply message or #NULL.
 703  */
 704 DBusMessage*
 705 dbus_pending_call_steal_reply (DBusPendingCall *pending)
 706 {
 707   DBusMessage *message;
 708
 709   _dbus_return_val_if_fail (pending != NULL, NULL);
 710   _dbus_return_val_if_fail (pending->completed, NULL);
 711   _dbus_return_val_if_fail (pending->reply != NULL, NULL);
 712
 713   CONNECTION_LOCK (pending->connection);
 714
 715   message = pending->reply;
 716   pending->reply = NULL;
 717
 718   CONNECTION_UNLOCK (pending->connection);
 719
 720   _dbus_message_trace_ref (message, -1, -1, "dbus_pending_call_steal_reply");
 721   return message;
 722 }
 723
 724 /**
 725  * Block until the pending call is completed.  The blocking is as with
 726  * dbus_connection_send_with_reply_and_block(); it does not enter the
 727  * main loop or process other messages, it simply waits for the reply
 728  * in question.
 729  *
 730  * If the pending call is already completed, this function returns
 731  * immediately.
 732  *
 733  * @todo when you start blocking, the timeout is reset, but it should
 734  * really only use time remaining since the pending call was created.
 735  * This requires storing timestamps instead of intervals in the timeout
 736  *
 737  * @param pending the pending call
 738  */
 739 void
 740 dbus_pending_call_block (DBusPendingCall *pending)
 741 {
 742   _dbus_return_if_fail (pending != NULL);
 743
 744   _dbus_connection_block_pending_call (pending);
 745 }
 746
 747 /**
 748  * Allocates an integer ID to be used for storing application-specific
 749  * data on any DBusPendingCall. The allocated ID may then be used
 750  * with dbus_pending_call_set_data() and dbus_pending_call_get_data().
 751  * The passed-in slot must be initialized to -1, and is filled in
 752  * with the slot ID. If the passed-in slot is not -1, it's assumed
 753  * to be already allocated, and its refcount is incremented.
 754  *
 755  * The allocated slot is global, i.e. all DBusPendingCall objects will
 756  * have a slot with the given integer ID reserved.
 757  *
 758  * @param slot_p address of a global variable storing the slot
 759  * @returns #FALSE on failure (no memory)
 760  */
 761 dbus_bool_t
 762 dbus_pending_call_allocate_data_slot (dbus_int32_t *slot_p)
 763 {
 764   _dbus_return_val_if_fail (slot_p != NULL, FALSE);
 765
 766   return _dbus_data_slot_allocator_alloc (&slot_allocator,
 767                                           &_DBUS_LOCK_NAME (pending_call_slots),
 768                                           slot_p);
 769 }
 770
 771 /**
 772  * Deallocates a global ID for #DBusPendingCall data slots.
 773  * dbus_pending_call_get_data() and dbus_pending_call_set_data() may
 774  * no longer be used with this slot.  Existing data stored on existing
 775  * DBusPendingCall objects will be freed when the #DBusPendingCall is
 776  * finalized, but may not be retrieved (and may only be replaced if
 777  * someone else reallocates the slot).  When the refcount on the
 778  * passed-in slot reaches 0, it is set to -1.
 779  *
 780  * @param slot_p address storing the slot to deallocate
 781  */
 782 void
 783 dbus_pending_call_free_data_slot (dbus_int32_t *slot_p)
 784 {
 785   _dbus_return_if_fail (slot_p != NULL);
 786   _dbus_return_if_fail (*slot_p >= 0);
 787
 788   _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
 789 }
 790
 791 /**
 792  * Stores a pointer on a #DBusPendingCall, along
 793  * with an optional function to be used for freeing
 794  * the data when the data is set again, or when
 795  * the pending call is finalized. The slot number
 796  * must have been allocated with dbus_pending_call_allocate_data_slot().
 797  *
 798  * @param pending the pending_call
 799  * @param slot the slot number
 800  * @param data the data to store
 801  * @param free_data_func finalizer function for the data
 802  * @returns #TRUE if there was enough memory to store the data
 803  */
 804 dbus_bool_t
 805 dbus_pending_call_set_data (DBusPendingCall  *pending,
 806                             dbus_int32_t      slot,
 807                             void             *data,
 808                             DBusFreeFunction  free_data_func)
 809 {
 810   dbus_bool_t retval;
 811
 812   _dbus_return_val_if_fail (pending != NULL, FALSE);
 813   _dbus_return_val_if_fail (slot >= 0, FALSE);
 814
 815
 816   CONNECTION_LOCK (pending->connection);
 817   retval = _dbus_pending_call_set_data_unlocked (pending, slot, data, free_data_func);
 818   CONNECTION_UNLOCK (pending->connection);
 819   return retval;
 820 }
 821
 822 /**
 823  * Retrieves data previously set with dbus_pending_call_set_data().
 824  * The slot must still be allocated (must not have been freed).
 825  *
 826  * @param pending the pending_call
 827  * @param slot the slot to get data from
 828  * @returns the data, or #NULL if not found
 829  */
 830 void*
 831 dbus_pending_call_get_data (DBusPendingCall   *pending,
 832                             dbus_int32_t       slot)
 833 {
 834   void *res;
 835
 836   _dbus_return_val_if_fail (pending != NULL, NULL);
 837
 838   CONNECTION_LOCK (pending->connection);
 839   res = _dbus_data_slot_list_get (&slot_allocator,
 840                                   &pending->slot_list,
 841                                   slot);
 842   CONNECTION_UNLOCK (pending->connection);
 843
 844   return res;
 845 }
 846
 847 /** @} */