Main Page   Modules   Data Structures   File List   Data Fields   Related Pages  

DBusConnection implementation details
[D-BUS internal implementation details]

Implementation details of DBusConnection. More...

Data Structures

struct  DBusConnection
 Implementation details of DBusConnection. More...

struct  ReplyHandlerData

Defines

#define DEFAULT_TIMEOUT_VALUE   (15 * 1000)
 default timeout value when waiting for a message reply


Functions

void _dbus_connection_lock (DBusConnection *connection)
 Acquires the connection lock.

void _dbus_connection_unlock (DBusConnection *connection)
 Releases the connection lock.

void _dbus_connection_queue_received_message_link (DBusConnection *connection, DBusList *link)
 Adds a message-containing list link to the incoming message queue, taking ownership of the link and the message's current refcount.

dbus_bool_t _dbus_connection_have_messages_to_send (DBusConnection *connection)
 Checks whether there are messages in the outgoing message queue.

DBusMessage_dbus_connection_get_message_to_send (DBusConnection *connection)
 Gets the next outgoing message.

void _dbus_connection_message_sent (DBusConnection *connection, DBusMessage *message)
 Notifies the connection that a message has been sent, so the message can be removed from the outgoing queue.

dbus_bool_t _dbus_connection_add_watch (DBusConnection *connection, DBusWatch *watch)
 Adds a watch using the connection's DBusAddWatchFunction if available.

void _dbus_connection_remove_watch (DBusConnection *connection, DBusWatch *watch)
 Removes a watch using the connection's DBusRemoveWatchFunction if available.

void _dbus_connection_toggle_watch (DBusConnection *connection, DBusWatch *watch, dbus_bool_t enabled)
 Toggles a watch and notifies app via connection's DBusWatchToggledFunction if available.

dbus_bool_t _dbus_connection_add_timeout (DBusConnection *connection, DBusTimeout *timeout)
 Adds a timeout using the connection's DBusAddTimeoutFunction if available.

void _dbus_connection_remove_timeout (DBusConnection *connection, DBusTimeout *timeout)
 Removes a timeout using the connection's DBusRemoveTimeoutFunction if available.

void _dbus_connection_toggle_timeout (DBusConnection *connection, DBusTimeout *timeout, dbus_bool_t enabled)
 Toggles a timeout and notifies app via connection's DBusTimeoutToggledFunction if available.

void _dbus_connection_notify_disconnected (DBusConnection *connection)
 Tells the connection that the transport has been disconnected.

void _dbus_connection_do_iteration (DBusConnection *connection, unsigned int flags, int timeout_milliseconds)
 Queues incoming messages and sends outgoing messages for this connection, optionally blocking in the process.

DBusConnection_dbus_connection_new_for_transport (DBusTransport *transport)
 Creates a new connection for the given transport.

void _dbus_connection_ref_unlocked (DBusConnection *connection)
 Increments the reference count of a DBusConnection.

void _dbus_connection_handler_destroyed_locked (DBusConnection *connection, DBusMessageHandler *handler)
 Used to notify a connection when a DBusMessageHandler is destroyed, so the connection can drop any reference to the handler.

dbus_bool_t _dbus_connection_handle_watch (DBusWatch *watch, unsigned int condition, void *data)
 A callback for use with dbus_watch_new() to create a DBusWatch.


Detailed Description

Implementation details of DBusConnection.


Function Documentation

dbus_bool_t _dbus_connection_add_timeout DBusConnection   connection,
DBusTimeout   timeout
 

Adds a timeout using the connection's DBusAddTimeoutFunction if available.

Otherwise records the timeout to be added when said function is available. Also re-adds the timeout if the DBusAddTimeoutFunction changes. May fail due to lack of memory. The timeout will fire repeatedly until removed.

Parameters:
connection the connection.
timeout the timeout to add.
Returns:
TRUE on success.

Definition at line 482 of file dbus-connection.c.

References _dbus_timeout_list_add_timeout(), FALSE, and DBusConnection::timeouts.

Referenced by dbus_connection_send_with_reply().

dbus_bool_t _dbus_connection_add_watch DBusConnection   connection,
DBusWatch   watch
 

Adds a watch using the connection's DBusAddWatchFunction if available.

Otherwise records the watch to be added when said function is available. Also re-adds the watch if the DBusAddWatchFunction changes. May fail due to lack of memory.

Parameters:
connection the connection.
watch the watch to add.
Returns:
TRUE on success.

Definition at line 424 of file dbus-connection.c.

References _dbus_watch_list_add_watch(), FALSE, and DBusConnection::watches.

void _dbus_connection_do_iteration DBusConnection   connection,
unsigned int    flags,
int    timeout_milliseconds
 

Queues incoming messages and sends outgoing messages for this connection, optionally blocking in the process.

Each call to _dbus_connection_do_iteration() will call select() or poll() one time and then read or write data if possible.

The purpose of this function is to be able to flush outgoing messages or queue up incoming messages without returning control to the application and causing reentrancy weirdness.

The flags parameter allows you to specify whether to read incoming messages, write outgoing messages, or both, and whether to block if no immediate action is possible.

The timeout_milliseconds parameter does nothing unless the iteration is blocking.

If there are no outgoing messages and DBUS_ITERATION_DO_READING wasn't specified, then it's impossible to block, even if you specify DBUS_ITERATION_BLOCK; in that case the function returns immediately.

Parameters:
connection the connection.
flags iteration flags.
timeout_milliseconds maximum blocking time, or -1 for no limit.

Definition at line 636 of file dbus-connection.c.

References _dbus_transport_do_iteration(), DBusConnection::n_outgoing, and DBusConnection::transport.

Referenced by dbus_connection_flush(), and dbus_connection_send_with_reply_and_block().

DBusMessage* _dbus_connection_get_message_to_send DBusConnection   connection
 

Gets the next outgoing message.

The message remains in the queue, and the caller does not own a reference to it.

Parameters:
connection the connection.
Returns:
the message to be sent.

Definition at line 365 of file dbus-connection.c.

References _dbus_list_get_last(), and DBusConnection::outgoing_messages.

dbus_bool_t _dbus_connection_handle_watch DBusWatch   watch,
unsigned int    condition,
void *    data
 

A callback for use with dbus_watch_new() to create a DBusWatch.

Todo:
This is basically a hack - we could delete _dbus_transport_handle_watch() and the virtual handle_watch in DBusTransport if we got rid of it. The reason this is some work is threading, see the _dbus_connection_handle_watch() implementation.
Parameters:
watch the watch.
condition the current condition of the file descriptors being watched.
data must be a pointer to a DBusConnection
Returns:
FALSE if the IO condition may not have been fully handled due to lack of memory

Definition at line 899 of file dbus-connection.c.

References _dbus_transport_handle_watch(), dbus_bool_t, and DBusConnection::transport.

void _dbus_connection_handler_destroyed_locked DBusConnection   connection,
DBusMessageHandler   handler
 

Used to notify a connection when a DBusMessageHandler is destroyed, so the connection can drop any reference to the handler.

This is a private function, but still takes the connection lock. Don't call it with the lock held.

Todo:
needs to check in pending_replies too.
Parameters:
connection the connection
handler the handler

Definition at line 853 of file dbus-connection.c.

References _dbus_hash_iter_get_value(), _dbus_hash_iter_init(), _dbus_hash_iter_next(), _dbus_hash_iter_remove_entry(), _dbus_list_get_first_link(), _dbus_list_get_next_link, _dbus_list_remove_link(), DBusList::data, DBusConnection::filter_list, DBusConnection::handler_table, and NULL.

Referenced by dbus_message_handler_unref().

dbus_bool_t _dbus_connection_have_messages_to_send DBusConnection   connection
 

Checks whether there are messages in the outgoing message queue.

Parameters:
connection the connection.
Returns:
TRUE if the outgoing queue is non-empty.

Definition at line 352 of file dbus-connection.c.

References NULL, and DBusConnection::outgoing_messages.

void _dbus_connection_lock DBusConnection   connection
 

Acquires the connection lock.

Parameters:
connection the connection.

Definition at line 214 of file dbus-connection.c.

void _dbus_connection_message_sent DBusConnection   connection,
DBusMessage   message
 

Notifies the connection that a message has been sent, so the message can be removed from the outgoing queue.

Called with the connection lock held.

Parameters:
connection the connection.
message the message that was sent.

Definition at line 379 of file dbus-connection.c.

References _dbus_assert, _dbus_list_get_last_link(), _dbus_list_prepend_link(), _dbus_list_unlink(), _dbus_message_remove_size_counter(), _dbus_transport_messages_pending(), DBusList::data, dbus_message_unref(), DBusConnection::link_cache, DBusConnection::n_outgoing, DBusConnection::outgoing_counter, DBusConnection::outgoing_messages, and DBusConnection::transport.

DBusConnection* _dbus_connection_new_for_transport DBusTransport   transport
 

Creates a new connection for the given transport.

A transport represents a message stream that uses some concrete mechanism, such as UNIX domain sockets. May return NULL if insufficient memory exists to create the connection.

Parameters:
transport the transport.
Returns:
the new connection, or NULL on failure.

Definition at line 662 of file dbus-connection.c.

References _dbus_counter_new(), _dbus_counter_unref(), _dbus_data_slot_list_init(), _dbus_disable_sigpipe(), _dbus_hash_table_new(), _dbus_hash_table_unref(), _dbus_list_alloc_link(), _dbus_list_free_link(), _dbus_timeout_list_free(), _dbus_timeout_list_new(), _dbus_transport_ref(), _dbus_transport_set_connection(), _dbus_watch_list_free(), _dbus_watch_list_new(), DBusConnection::client_serial, dbus_condvar_free(), dbus_condvar_new(), dbus_free(), dbus_message_new(), dbus_message_unref(), dbus_mutex_free(), dbus_mutex_new(), dbus_new0, DBusConnection::disconnect_message_link, DBusConnection::dispatch_cond, DBusConnection::filter_list, DBusConnection::handler_table, DBusConnection::io_path_cond, DBusConnection::last_dispatch_status, DBusConnection::message_returned_cond, DBusConnection::mutex, NULL, DBusConnection::outgoing_counter, DBusConnection::pending_replies, DBusConnection::refcount, DBusConnection::slot_list, DBusConnection::timeouts, DBusConnection::transport, and DBusConnection::watches.

Referenced by dbus_connection_open().

void _dbus_connection_notify_disconnected DBusConnection   connection
 

Tells the connection that the transport has been disconnected.

Results in posting a disconnect message on the incoming message queue. Only has an effect the first time it's called.

Parameters:
connection the connection

Definition at line 545 of file dbus-connection.c.

References DBusConnection::disconnect_message_link, and NULL.

Referenced by _dbus_transport_disconnect().

void _dbus_connection_queue_received_message_link DBusConnection   connection,
DBusList   link
 

Adds a message-containing list link to the incoming message queue, taking ownership of the link and the message's current refcount.

Cannot fail due to lack of memory.

Parameters:
connection the connection.
link the message link to queue.

Definition at line 281 of file dbus-connection.c.

References _dbus_assert, _dbus_hash_table_lookup_int(), _dbus_list_append_link(), DBusList::data, dbus_int32_t, dbus_message_get_reply_serial(), FALSE, DBusConnection::incoming_messages, DBusConnection::n_incoming, NULL, DBusConnection::pending_replies, and DBusConnection::transport.

Referenced by _dbus_transport_queue_messages().

void _dbus_connection_ref_unlocked DBusConnection   connection
 

Increments the reference count of a DBusConnection.

Requires that the caller already holds the connection lock.

Parameters:
connection the connection.

Definition at line 818 of file dbus-connection.c.

References _dbus_assert, _dbus_atomic_inc(), and DBusConnection::refcount.

Referenced by dbus_connection_dispatch(), dbus_connection_set_timeout_functions(), and dbus_connection_set_watch_functions().

void _dbus_connection_remove_timeout DBusConnection   connection,
DBusTimeout   timeout
 

Removes a timeout using the connection's DBusRemoveTimeoutFunction if available.

It's an error to call this function on a timeout that was not previously added.

Parameters:
connection the connection.
timeout the timeout to remove.

Definition at line 501 of file dbus-connection.c.

References _dbus_timeout_list_remove_timeout(), and DBusConnection::timeouts.

void _dbus_connection_remove_watch DBusConnection   connection,
DBusWatch   watch
 

Removes a watch using the connection's DBusRemoveWatchFunction if available.

It's an error to call this function on a watch that was not previously added.

Parameters:
connection the connection.
watch the watch to remove.

Definition at line 443 of file dbus-connection.c.

References _dbus_watch_list_remove_watch(), and DBusConnection::watches.

void _dbus_connection_toggle_timeout DBusConnection   connection,
DBusTimeout   timeout,
dbus_bool_t    enabled
 

Toggles a timeout and notifies app via connection's DBusTimeoutToggledFunction if available.

It's an error to call this function on a timeout that was not previously added.

Parameters:
connection the connection.
timeout the timeout to toggle.
enabled whether to enable or disable

Definition at line 528 of file dbus-connection.c.

References _dbus_timeout_list_toggle_timeout(), and DBusConnection::timeouts.

void _dbus_connection_toggle_watch DBusConnection   connection,
DBusWatch   watch,
dbus_bool_t    enabled
 

Toggles a watch and notifies app via connection's DBusWatchToggledFunction if available.

It's an error to call this function on a watch that was not previously added.

Parameters:
connection the connection.
watch the watch to toggle.
enabled whether to enable or disable

Definition at line 461 of file dbus-connection.c.

References _dbus_watch_list_toggle_watch(), and DBusConnection::watches.

void _dbus_connection_unlock DBusConnection   connection
 

Releases the connection lock.

Parameters:
connection the connection.

Definition at line 225 of file dbus-connection.c.


Generated on Wed Oct 22 14:05:07 2003 for D-BUS by doxygen1.3-rc3