• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
_dbus_pending_call_trace_ref(DBusPendingCall * pending_call,int old_refcount,int new_refcount,const char * why)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*
_dbus_pending_call_new_unlocked(DBusConnection * connection,int timeout_milliseconds,DBusTimeoutHandler timeout_handler)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
_dbus_pending_call_set_reply_unlocked(DBusPendingCall * pending,DBusMessage * message)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
_dbus_pending_call_complete(DBusPendingCall * pending)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
_dbus_pending_call_queue_timeout_error_unlocked(DBusPendingCall * pending,DBusConnection * connection)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
_dbus_pending_call_is_timeout_added_unlocked(DBusPendingCall * pending)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
_dbus_pending_call_set_timeout_added_unlocked(DBusPendingCall * pending,dbus_bool_t is_added)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 *
_dbus_pending_call_get_timeout_unlocked(DBusPendingCall * pending)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
_dbus_pending_call_get_reply_serial_unlocked(DBusPendingCall * pending)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
_dbus_pending_call_set_reply_serial_unlocked(DBusPendingCall * pending,dbus_uint32_t serial)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 *
_dbus_pending_call_get_connection_and_lock(DBusPendingCall * pending)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 *
_dbus_pending_call_get_connection_unlocked(DBusPendingCall * pending)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
_dbus_pending_call_set_timeout_error_unlocked(DBusPendingCall * pending,DBusMessage * message,dbus_uint32_t serial)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 *
_dbus_pending_call_ref_unlocked(DBusPendingCall * pending)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
_dbus_pending_call_last_unref(DBusPendingCall * pending)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
_dbus_pending_call_unref_and_unlock(DBusPendingCall * pending)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
_dbus_pending_call_get_completed_unlocked(DBusPendingCall * pending)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
_dbus_pending_call_set_data_unlocked(DBusPendingCall * pending,dbus_int32_t slot,void * data,DBusFreeFunction free_data_func)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 *
dbus_pending_call_ref(DBusPendingCall * pending)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
dbus_pending_call_unref(DBusPendingCall * pending)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
dbus_pending_call_set_notify(DBusPendingCall * pending,DBusPendingCallNotifyFunction function,void * user_data,DBusFreeFunction free_user_data)629  dbus_pending_call_set_notify (DBusPendingCall              *pending,
630                                DBusPendingCallNotifyFunction function,
631                                void                         *user_data,
632                                DBusFreeFunction              free_user_data)
633  {
634    dbus_bool_t ret = FALSE;
635  
636    _dbus_return_val_if_fail (pending != NULL, FALSE);
637  
638    CONNECTION_LOCK (pending->connection);
639  
640    /* could invoke application code! */
641    if (!_dbus_pending_call_set_data_unlocked (pending, notify_user_data_slot,
642                                               user_data, free_user_data))
643      goto out;
644  
645    pending->function = function;
646    ret = TRUE;
647  
648  out:
649    CONNECTION_UNLOCK (pending->connection);
650  
651    return ret;
652  }
653  
654  /**
655   * Cancels the pending call, such that any reply or error received
656   * will just be ignored.  Drops the dbus library's internal reference
657   * to the #DBusPendingCall so will free the call if nobody else is
658   * holding a reference. However you usually get a reference from
659   * dbus_connection_send_with_reply() so probably your app owns a ref
660   * also.
661   *
662   * Note that canceling a pending call will <em>not</em> simulate a
663   * timed-out call; if a call times out, then a timeout error reply is
664   * received. If you cancel the call, no reply is received unless the
665   * the reply was already received before you canceled.
666   *
667   * @param pending the pending call
668   */
669  void
dbus_pending_call_cancel(DBusPendingCall * pending)670  dbus_pending_call_cancel (DBusPendingCall *pending)
671  {
672    _dbus_return_if_fail (pending != NULL);
673  
674    _dbus_connection_remove_pending_call (pending->connection,
675                                          pending);
676  }
677  
678  /**
679   * Checks whether the pending call has received a reply
680   * yet, or not.
681   *
682   * @param pending the pending call
683   * @returns #TRUE if a reply has been received
684   */
685  dbus_bool_t
dbus_pending_call_get_completed(DBusPendingCall * pending)686  dbus_pending_call_get_completed (DBusPendingCall *pending)
687  {
688    dbus_bool_t completed;
689  
690    _dbus_return_val_if_fail (pending != NULL, FALSE);
691  
692    CONNECTION_LOCK (pending->connection);
693    completed = pending->completed;
694    CONNECTION_UNLOCK (pending->connection);
695  
696    return completed;
697  }
698  
699  /**
700   * Gets the reply, or returns #NULL if none has been received
701   * yet. Ownership of the reply message passes to the caller. This
702   * function can only be called once per pending call, since the reply
703   * message is tranferred to the caller.
704   *
705   * @param pending the pending call
706   * @returns the reply message or #NULL.
707   */
708  DBusMessage*
dbus_pending_call_steal_reply(DBusPendingCall * pending)709  dbus_pending_call_steal_reply (DBusPendingCall *pending)
710  {
711    DBusMessage *message;
712  
713    _dbus_return_val_if_fail (pending != NULL, NULL);
714    _dbus_return_val_if_fail (pending->completed, NULL);
715    _dbus_return_val_if_fail (pending->reply != NULL, NULL);
716  
717    CONNECTION_LOCK (pending->connection);
718  
719    message = pending->reply;
720    pending->reply = NULL;
721  
722    CONNECTION_UNLOCK (pending->connection);
723  
724    _dbus_message_trace_ref (message, -1, -1, "dbus_pending_call_steal_reply");
725    return message;
726  }
727  
728  /**
729   * Block until the pending call is completed.  The blocking is as with
730   * dbus_connection_send_with_reply_and_block(); it does not enter the
731   * main loop or process other messages, it simply waits for the reply
732   * in question.
733   *
734   * If the pending call is already completed, this function returns
735   * immediately.
736   *
737   * @todo when you start blocking, the timeout is reset, but it should
738   * really only use time remaining since the pending call was created.
739   * This requires storing timestamps instead of intervals in the timeout
740   *
741   * @param pending the pending call
742   */
743  void
dbus_pending_call_block(DBusPendingCall * pending)744  dbus_pending_call_block (DBusPendingCall *pending)
745  {
746    _dbus_return_if_fail (pending != NULL);
747  
748    _dbus_connection_block_pending_call (pending);
749  }
750  
751  /**
752   * Allocates an integer ID to be used for storing application-specific
753   * data on any DBusPendingCall. The allocated ID may then be used
754   * with dbus_pending_call_set_data() and dbus_pending_call_get_data().
755   * The passed-in slot must be initialized to -1, and is filled in
756   * with the slot ID. If the passed-in slot is not -1, it's assumed
757   * to be already allocated, and its refcount is incremented.
758   *
759   * The allocated slot is global, i.e. all DBusPendingCall objects will
760   * have a slot with the given integer ID reserved.
761   *
762   * @param slot_p address of a global variable storing the slot
763   * @returns #FALSE on failure (no memory)
764   */
765  dbus_bool_t
dbus_pending_call_allocate_data_slot(dbus_int32_t * slot_p)766  dbus_pending_call_allocate_data_slot (dbus_int32_t *slot_p)
767  {
768    _dbus_return_val_if_fail (slot_p != NULL, FALSE);
769  
770    return _dbus_data_slot_allocator_alloc (&slot_allocator,
771                                            &_DBUS_LOCK_NAME (pending_call_slots),
772                                            slot_p);
773  }
774  
775  /**
776   * Deallocates a global ID for #DBusPendingCall data slots.
777   * dbus_pending_call_get_data() and dbus_pending_call_set_data() may
778   * no longer be used with this slot.  Existing data stored on existing
779   * DBusPendingCall objects will be freed when the #DBusPendingCall is
780   * finalized, but may not be retrieved (and may only be replaced if
781   * someone else reallocates the slot).  When the refcount on the
782   * passed-in slot reaches 0, it is set to -1.
783   *
784   * @param slot_p address storing the slot to deallocate
785   */
786  void
dbus_pending_call_free_data_slot(dbus_int32_t * slot_p)787  dbus_pending_call_free_data_slot (dbus_int32_t *slot_p)
788  {
789    _dbus_return_if_fail (slot_p != NULL);
790    _dbus_return_if_fail (*slot_p >= 0);
791  
792    _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
793  }
794  
795  /**
796   * Stores a pointer on a #DBusPendingCall, along
797   * with an optional function to be used for freeing
798   * the data when the data is set again, or when
799   * the pending call is finalized. The slot number
800   * must have been allocated with dbus_pending_call_allocate_data_slot().
801   *
802   * @param pending the pending_call
803   * @param slot the slot number
804   * @param data the data to store
805   * @param free_data_func finalizer function for the data
806   * @returns #TRUE if there was enough memory to store the data
807   */
808  dbus_bool_t
dbus_pending_call_set_data(DBusPendingCall * pending,dbus_int32_t slot,void * data,DBusFreeFunction free_data_func)809  dbus_pending_call_set_data (DBusPendingCall  *pending,
810                              dbus_int32_t      slot,
811                              void             *data,
812                              DBusFreeFunction  free_data_func)
813  {
814    dbus_bool_t retval;
815  
816    _dbus_return_val_if_fail (pending != NULL, FALSE);
817    _dbus_return_val_if_fail (slot >= 0, FALSE);
818  
819  
820    CONNECTION_LOCK (pending->connection);
821    retval = _dbus_pending_call_set_data_unlocked (pending, slot, data, free_data_func);
822    CONNECTION_UNLOCK (pending->connection);
823    return retval;
824  }
825  
826  /**
827   * Retrieves data previously set with dbus_pending_call_set_data().
828   * The slot must still be allocated (must not have been freed).
829   *
830   * @param pending the pending_call
831   * @param slot the slot to get data from
832   * @returns the data, or #NULL if not found
833   */
834  void*
dbus_pending_call_get_data(DBusPendingCall * pending,dbus_int32_t slot)835  dbus_pending_call_get_data (DBusPendingCall   *pending,
836                              dbus_int32_t       slot)
837  {
838    void *res;
839  
840    _dbus_return_val_if_fail (pending != NULL, NULL);
841  
842    CONNECTION_LOCK (pending->connection);
843    res = _dbus_data_slot_list_get (&slot_allocator,
844                                    &pending->slot_list,
845                                    slot);
846    CONNECTION_UNLOCK (pending->connection);
847  
848    return res;
849  }
850  
851  /** @} */
852