DBusPendingCall implementation details
D-Bus secret internal implementation details

DBusPendingCall private implementation details. More...

## Data Structures

struct | DBusPendingCall
| Implementation details of DBusPendingCall - all fields are private. More...

## Macros

#define | CONNECTION_LOCK(connection)
| Internals of DBusPendingCall.
#define | CONNECTION_UNLOCK(connection)
| shorter and more visible way to write _dbus_connection_unlock()

## Functions

DBusPendingCall * | _dbus_pending_call_new_unlocked (DBusConnection *connection, int timeout_milliseconds, DBusTimeoutHandler timeout_handler)
| Creates a new pending reply object.
void | _dbus_pending_call_set_reply_unlocked (DBusPendingCall *pending, DBusMessage *message)
| Sets the reply of a pending call with the given message, or if the message is NULL, by timing out the pending call.
void | _dbus_pending_call_start_completion_unlocked (DBusPendingCall *pending)
| Sets the pending call to completed.
void | _dbus_pending_call_finish_completion (DBusPendingCall *pending)
| Call the notifier function for the pending call.
void | _dbus_pending_call_queue_timeout_error_unlocked (DBusPendingCall *pending, DBusConnection *connection)
| If the pending call hasn't been timed out, add its timeout error reply to the connection's incoming message queue.
dbus_bool_t | _dbus_pending_call_is_timeout_added_unlocked (DBusPendingCall *pending)
| Checks to see if a timeout has been added.
void | _dbus_pending_call_set_timeout_added_unlocked (DBusPendingCall *pending, dbus_bool_t is_added)
| Sets wether the timeout has been added.
DBusTimeout * | _dbus_pending_call_get_timeout_unlocked (DBusPendingCall *pending)
| Retrives the timeout.
dbus_uint32_t | _dbus_pending_call_get_reply_serial_unlocked (DBusPendingCall *pending)
| Gets the reply's serial number.
void | _dbus_pending_call_set_reply_serial_unlocked (DBusPendingCall *pending, dbus_uint32_t serial)
| Sets the reply's serial number.
DBusConnection * | _dbus_pending_call_get_connection_and_lock (DBusPendingCall *pending)
| Gets the connection associated with this pending call.
DBusConnection * | _dbus_pending_call_get_connection_unlocked (DBusPendingCall *pending)
| Gets the connection associated with this pending call.
dbus_bool_t | _dbus_pending_call_set_timeout_error_unlocked (DBusPendingCall *pending, DBusMessage *message, dbus_uint32_t serial)
| Sets the reply message associated with the pending call to a timeout error.
DBusPendingCall * | _dbus_pending_call_ref_unlocked (DBusPendingCall *pending)
| Increments the reference count on a pending call, while the lock on its connection is already held.
void | _dbus_pending_call_unref_and_unlock (DBusPendingCall *pending)
| Decrements the reference count on a pending call, freeing it if the count reaches 0.
dbus_bool_t | _dbus_pending_call_get_completed_unlocked (DBusPendingCall *pending)
| Checks whether the pending call has received a reply yet, or not.
dbus_bool_t | _dbus_pending_call_set_data_unlocked (DBusPendingCall *pending, dbus_int32_t slot, void *data, DBusFreeFunction free_data_func)
| Stores a pointer on a DBusPendingCall, along with an optional function to be used for freeing the data when the data is set again, or when the pending call is finalized.

## Detailed Description

DBusPendingCall private implementation details.

The guts of DBusPendingCall and its methods.

## Macro Definition Documentation

## CONNECTION_LOCK

#define CONNECTION_LOCK | ( |  | connection | ) |

Value:
_dbus_connection_lock(connection)
_dbus_connection_lock
DBUS_PRIVATE_EXPORT void _dbus_connection_lock(DBusConnection *connection)
Acquires the connection lock.
Definition dbus-connection.c:392

Internals of DBusPendingCall.

Opaque object representing a reply message that we're waiting for. shorter and more visible way to write _dbus_connection_lock()

Definition at line 55 of file dbus-pending-call.c.

Referenced by _dbus_connection_block_pending_call(), _dbus_connection_close_if_only_one_ref(), _dbus_connection_close_possibly_shared(), _dbus_connection_handle_watch(), _dbus_connection_lock(), _dbus_connection_new_for_transport(), _dbus_connection_remove_pending_call(), _dbus_pending_call_get_connection_and_lock(), _dbus_pending_call_set_data_unlocked(), dbus_connection_add_filter(), dbus_connection_borrow_message(), dbus_connection_can_send_type(), dbus_connection_close(), dbus_connection_dispatch(), dbus_connection_flush(), dbus_connection_get_adt_audit_session_data(), dbus_connection_get_dispatch_status(), dbus_connection_get_is_anonymous(), dbus_connection_get_is_authenticated(), dbus_connection_get_is_connected(), dbus_connection_get_max_message_size(), dbus_connection_get_max_message_unix_fds(), dbus_connection_get_max_received_size(), dbus_connection_get_max_received_unix_fds(), dbus_connection_get_object_path_data(), dbus_connection_get_outgoing_size(), dbus_connection_get_outgoing_unix_fds(), dbus_connection_get_server_id(), dbus_connection_get_socket(), dbus_connection_get_unix_process_id(), dbus_connection_get_unix_user(), dbus_connection_get_windows_user(), dbus_connection_has_messages_to_send(), dbus_connection_list_registered(), dbus_connection_pop_message(), dbus_connection_preallocate_send(), dbus_connection_remove_filter(), dbus_connection_return_message(), dbus_connection_send(), dbus_connection_send_preallocated(), dbus_connection_send_with_reply(), dbus_connection_send_with_reply_and_block(), dbus_connection_set_allow_anonymous(), dbus_connection_set_builtin_filters_enabled(), dbus_connection_set_dispatch_status_function(), dbus_connection_set_exit_on_disconnect(), dbus_connection_set_max_message_size(), dbus_connection_set_max_message_unix_fds(), dbus_connection_set_max_received_size(), dbus_connection_set_max_received_unix_fds(), dbus_connection_set_route_peer_messages(), dbus_connection_set_timeout_functions(), dbus_connection_set_unix_user_function(), dbus_connection_set_wakeup_main_function(), dbus_connection_set_watch_functions(), dbus_connection_set_windows_user_function(), dbus_connection_steal_borrowed_message(), dbus_connection_unregister_object_path(), dbus_pending_call_get_completed(), dbus_pending_call_get_data(), dbus_pending_call_set_data(), dbus_pending_call_set_notify(), and dbus_pending_call_steal_reply().

## CONNECTION_UNLOCK

#define CONNECTION_UNLOCK | ( |  | connection | ) |

Value:
_dbus_connection_unlock(connection)
_dbus_connection_unlock
DBUS_PRIVATE_EXPORT void _dbus_connection_unlock(DBusConnection *connection)
Releases the connection lock.
Definition dbus-connection.c:403

shorter and more visible way to write _dbus_connection_unlock()

Definition at line 59 of file dbus-pending-call.c.

Referenced by _dbus_connection_close_if_only_one_ref(), _dbus_connection_handle_watch(), _dbus_connection_new_for_transport(), _dbus_connection_send_and_unlock(), _dbus_pending_call_set_data_unlocked(), _dbus_pending_call_unref_and_unlock(), dbus_connection_add_filter(), dbus_connection_borrow_message(), dbus_connection_can_send_type(), dbus_connection_close(), dbus_connection_dispatch(), dbus_connection_get_adt_audit_session_data(), dbus_connection_get_dispatch_status(), dbus_connection_get_is_anonymous(), dbus_connection_get_is_authenticated(), dbus_connection_get_is_connected(), dbus_connection_get_max_message_size(), dbus_connection_get_max_message_unix_fds(), dbus_connection_get_max_received_size(), dbus_connection_get_max_received_unix_fds(), dbus_connection_get_object_path_data(), dbus_connection_get_outgoing_size(), dbus_connection_get_outgoing_unix_fds(), dbus_connection_get_server_id(), dbus_connection_get_socket(), dbus_connection_get_unix_process_id(), dbus_connection_get_unix_user(), dbus_connection_get_windows_user(), dbus_connection_has_messages_to_send(), dbus_connection_preallocate_send(), dbus_connection_remove_filter(), dbus_connection_send(), dbus_connection_send_preallocated(), dbus_connection_send_with_reply(), dbus_connection_send_with_reply_and_block(), dbus_connection_set_allow_anonymous(), dbus_connection_set_builtin_filters_enabled(), dbus_connection_set_dispatch_status_function(), dbus_connection_set_exit_on_disconnect(), dbus_connection_set_max_message_size(), dbus_connection_set_max_message_unix_fds(), dbus_connection_set_max_received_size(), dbus_connection_set_max_received_unix_fds(), dbus_connection_set_route_peer_messages(), dbus_connection_set_timeout_functions(), dbus_connection_set_unix_user_function(), dbus_connection_set_wakeup_main_function(), dbus_connection_set_watch_functions(), dbus_connection_set_windows_user_function(), dbus_pending_call_get_completed(), dbus_pending_call_get_data(), dbus_pending_call_set_data(), dbus_pending_call_set_notify(), and dbus_pending_call_steal_reply().

## Function Documentation

## _dbus_pending_call_finish_completion()

void _dbus_pending_call_finish_completion | ( | DBusPendingCall * | pending | ) |

Call the notifier function for the pending call.

This method must be called after the connection lock has been released, and must be paired with a call to _dbus_pending_call_start_completion_unlocked().

Parameters

  pending | the pending call

Definition at line 235 of file dbus-pending-call.c.

References _dbus_assert, DBusPendingCall::completed, dbus_pending_call_get_data(), and DBusPendingCall::function.

## _dbus_pending_call_get_completed_unlocked()

dbus_bool_t _dbus_pending_call_get_completed_unlocked | ( | DBusPendingCall * | pending | ) |

Checks whether the pending call has received a reply yet, or not.

Assumes connection lock is held.

Parameters

  pending | the pending call

Returns
  TRUE if a reply has been received

Definition at line 509 of file dbus-pending-call.c.

References DBusPendingCall::completed.

Referenced by _dbus_connection_block_pending_call(), and _dbus_connection_do_iteration_unlocked().

## _dbus_pending_call_get_connection_and_lock()

DBusConnection * _dbus_pending_call_get_connection_and_lock | ( | DBusPendingCall * | pending | ) |

Gets the connection associated with this pending call.

Parameters

  pending | the pending_call

Returns
  the connection associated with the pending call

Definition at line 352 of file dbus-pending-call.c.

References _dbus_assert, DBusPendingCall::connection, CONNECTION_LOCK, and NULL.

Referenced by _dbus_connection_block_pending_call().

## _dbus_pending_call_get_connection_unlocked()

DBusConnection * _dbus_pending_call_get_connection_unlocked | ( | DBusPendingCall * | pending | ) |

Gets the connection associated with this pending call.

Parameters

  pending | the pending_call

Returns
  the connection associated with the pending call

Definition at line 367 of file dbus-pending-call.c.

References _dbus_assert, DBusPendingCall::connection, and NULL.

## _dbus_pending_call_get_reply_serial_unlocked()

dbus_uint32_t _dbus_pending_call_get_reply_serial_unlocked | ( | DBusPendingCall * | pending | ) |

Gets the reply's serial number.

Parameters

  pending | the pending_call

Returns
  a serial number for the reply or 0

Definition at line 322 of file dbus-pending-call.c.

References _dbus_assert, NULL, and DBusPendingCall::reply_serial.

Referenced by _dbus_connection_block_pending_call(), and _dbus_connection_do_iteration_unlocked().

## _dbus_pending_call_get_timeout_unlocked()

DBusTimeout * _dbus_pending_call_get_timeout_unlocked | ( | DBusPendingCall * | pending | ) |

Retrives the timeout.

Parameters

  pending | the pending_call

Returns
  a timeout object or NULL if call has no timeout

Definition at line 308 of file dbus-pending-call.c.

References _dbus_assert, NULL, and DBusPendingCall::timeout.

Referenced by _dbus_connection_block_pending_call(), and _dbus_connection_queue_received_message_link().

## _dbus_pending_call_is_timeout_added_unlocked()

dbus_bool_t _dbus_pending_call_is_timeout_added_unlocked | ( | DBusPendingCall * | pending | ) |

Checks to see if a timeout has been added.

Parameters

  pending | the pending_call

Returns
  TRUE if there is a timeout or FALSE if not

Definition at line 277 of file dbus-pending-call.c.

References _dbus_assert, NULL, and DBusPendingCall::timeout_added.

Referenced by _dbus_connection_queue_received_message_link().

## _dbus_pending_call_new_unlocked()

DBusPendingCall * _dbus_pending_call_new_unlocked | ( | DBusConnection * | connection,
|  | int | timeout_milliseconds,
|  | DBusTimeoutHandler | timeout_handler )

Creates a new pending reply object.

Parameters

  connection | connection where reply will arrive
  timeout_milliseconds | length of timeout, -1 (or DBUS_TIMEOUT_USE_DEFAULT) for default, DBUS_TIMEOUT_INFINITE for no timeout
  timeout_handler | timeout handler, takes pending call as data

Returns
  a new DBusPendingCall or NULL if no memory.

Definition at line 120 of file dbus-pending-call.c.

References _dbus_assert, _dbus_atomic_inc(), _dbus_connection_ref_unlocked(), _dbus_data_slot_list_init(), _dbus_timeout_new(), DBusPendingCall::connection, dbus_free(), dbus_new0, dbus_pending_call_allocate_data_slot(), dbus_pending_call_free_data_slot(), DBUS_TIMEOUT_INFINITE, NULL, DBusPendingCall::refcount, DBusPendingCall::slot_list, and DBusPendingCall::timeout.

Referenced by dbus_connection_send_with_reply().

## _dbus_pending_call_queue_timeout_error_unlocked()

void _dbus_pending_call_queue_timeout_error_unlocked | ( | DBusPendingCall * | pending,
|  | DBusConnection * | connection )

If the pending call hasn't been timed out, add its timeout error reply to the connection's incoming message queue.

Parameters

  pending | the pending call
  connection | the connection the call was sent to

Definition at line 257 of file dbus-pending-call.c.

References _dbus_assert, _dbus_connection_queue_synthesized_message_link(), DBusPendingCall::connection, NULL, and DBusPendingCall::timeout_link.

## _dbus_pending_call_ref_unlocked()

DBusPendingCall * _dbus_pending_call_ref_unlocked | ( | DBusPendingCall * | pending | ) |

Increments the reference count on a pending call, while the lock on its connection is already held.

Parameters

  pending | the pending call object

Returns
  the pending call object

Definition at line 423 of file dbus-pending-call.c.

References _dbus_atomic_inc(), and DBusPendingCall::refcount.

## _dbus_pending_call_set_data_unlocked()

dbus_bool_t _dbus_pending_call_set_data_unlocked | ( | DBusPendingCall * | pending,
|  | dbus_int32_t | slot,
|  | void * | data,
|  | DBusFreeFunction | free_data_func )

Stores a pointer on a DBusPendingCall, along with an optional function to be used for freeing the data when the data is set again, or when the pending call is finalized.

The slot number must have been allocated with dbus_pending_call_allocate_data_slot().

Parameters

  pending | the pending_call
  slot | the slot number
  data | the data to store
  free_data_func | finalizer function for the data

Returns
  TRUE if there was enough memory to store the data

Definition at line 531 of file dbus-pending-call.c.

References _dbus_data_slot_list_set(), DBusPendingCall::connection, CONNECTION_LOCK, CONNECTION_UNLOCK, and DBusPendingCall::slot_list.

Referenced by dbus_pending_call_set_data(), and dbus_pending_call_set_notify().

## _dbus_pending_call_set_reply_serial_unlocked()

void _dbus_pending_call_set_reply_serial_unlocked | ( | DBusPendingCall * | pending,
|  | dbus_uint32_t | serial )

Sets the reply's serial number.

Parameters

  pending | the pending_call
  serial | the serial number

Definition at line 336 of file dbus-pending-call.c.

References _dbus_assert, NULL, and DBusPendingCall::reply_serial.

Referenced by _dbus_pending_call_set_timeout_error_unlocked().

## _dbus_pending_call_set_reply_unlocked()

void _dbus_pending_call_set_reply_unlocked | ( | DBusPendingCall * | pending,
|  | DBusMessage * | message )

Sets the reply of a pending call with the given message, or if the message is NULL, by timing out the pending call.

Parameters

  pending | the pending call
  message | the message to complete the call with, or NULL to time out the call

Definition at line 183 of file dbus-pending-call.c.

References _dbus_assert, _dbus_list_clear(), DBusList::data, dbus_message_get_reply_serial(), dbus_message_get_type(), dbus_message_ref(), DBUS_MESSAGE_TYPE_ERROR, DBUS_MESSAGE_TYPE_METHOD_RETURN, NULL, DBusPendingCall::reply, DBusPendingCall::reply_serial, and DBusPendingCall::timeout_link.

## _dbus_pending_call_set_timeout_added_unlocked()

void _dbus_pending_call_set_timeout_added_unlocked | ( | DBusPendingCall * | pending,
|  | dbus_bool_t | is_added )

Sets wether the timeout has been added.

Parameters

  pending | the pending_call
  is_added | whether or not a timeout is added

Definition at line 292 of file dbus-pending-call.c.

References _dbus_assert, NULL, and DBusPendingCall::timeout_added.

Referenced by _dbus_connection_queue_received_message_link().

## _dbus_pending_call_set_timeout_error_unlocked()

dbus_bool_t _dbus_pending_call_set_timeout_error_unlocked | ( | DBusPendingCall * | pending,
|  | DBusMessage * | message,
|  | dbus_uint32_t | serial )

Sets the reply message associated with the pending call to a timeout error.

Parameters

  pending | the pending_call
  message | the message we are sending the error reply to
  serial | serial number for the reply

Returns
  FALSE on OOM

Definition at line 383 of file dbus-pending-call.c.

References _dbus_list_alloc_link(), _dbus_pending_call_set_reply_serial_unlocked(), DBUS_ERROR_NO_REPLY, dbus_message_new_error(), dbus_message_unref(), FALSE, NULL, DBusPendingCall::timeout_link, and TRUE.

Referenced by dbus_connection_send_with_reply().

## _dbus_pending_call_start_completion_unlocked()

void _dbus_pending_call_start_completion_unlocked | ( | DBusPendingCall * | pending | ) |

Sets the pending call to completed.

This method is called with the connection lock held, to protect pending->completed. It must be paired with a call to _dbus_pending_call_finish_completion() after the connection lock has been released.

Parameters

  pending | the pending call

Definition at line 218 of file dbus-pending-call.c.

References _dbus_assert, DBusPendingCall::completed, and TRUE.

## _dbus_pending_call_unref_and_unlock()

void _dbus_pending_call_unref_and_unlock | ( | DBusPendingCall * | pending | ) |

Decrements the reference count on a pending call, freeing it if the count reaches 0.

Assumes connection lock is already held.

Parameters

  pending | the pending call object

Definition at line 486 of file dbus-pending-call.c.

References _dbus_assert, _dbus_atomic_dec(), DBusPendingCall::connection, CONNECTION_UNLOCK, and DBusPendingCall::refcount.