dbus/dbus-pending-call.c

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