Main Page   Modules   Data Structures   File List   Data Fields   Related Pages  

DBusConnection
[D-BUS message system public API]

Connection to another application. More...

Data Structures

struct  DBusPreallocatedSend

Functions

DBusConnection * dbus_connection_open (const char *address, DBusError *error)
 Opens a new connection to a remote address.

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

void dbus_connection_unref (DBusConnection *connection)
 Decrements the reference count of a DBusConnection, and finalizes it if the count reaches zero.

void dbus_connection_disconnect (DBusConnection *connection)
 Closes the connection, so no further data can be sent or received.

dbus_bool_t dbus_connection_get_is_connected (DBusConnection *connection)
 Gets whether the connection is currently connected.

dbus_bool_t dbus_connection_get_is_authenticated (DBusConnection *connection)
 Gets whether the connection was authenticated.

DBusPreallocatedSend * dbus_connection_preallocate_send (DBusConnection *connection)
 Preallocates resources needed to send a message, allowing the message to be sent without the possibility of memory allocation failure.

void dbus_connection_free_preallocated_send (DBusConnection *connection, DBusPreallocatedSend *preallocated)
 Frees preallocated message-sending resources from dbus_connection_preallocate_send().

void dbus_connection_send_preallocated (DBusConnection *connection, DBusPreallocatedSend *preallocated, DBusMessage *message, dbus_uint32_t *client_serial)
 Sends a message using preallocated resources.

dbus_bool_t dbus_connection_send (DBusConnection *connection, DBusMessage *message, dbus_uint32_t *client_serial)
 Adds a message to the outgoing message queue.

dbus_bool_t dbus_connection_send_with_reply (DBusConnection *connection, DBusMessage *message, DBusMessageHandler *reply_handler, int timeout_milliseconds)
 Queues a message to send, as with dbus_connection_send_message(), but also sets up a DBusMessageHandler to receive a reply to the message.

DBusMessagedbus_connection_send_with_reply_and_block (DBusConnection *connection, DBusMessage *message, int timeout_milliseconds, DBusError *error)
 Sends a message and blocks a certain time period while waiting for a reply.

void dbus_connection_flush (DBusConnection *connection)
 Blocks until the outgoing message queue is empty.

DBusMessagedbus_connection_borrow_message (DBusConnection *connection)
 Returns the first-received message from the incoming message queue, leaving it in the queue.

void dbus_connection_return_message (DBusConnection *connection, DBusMessage *message)
 Used to return a message after peeking at it using dbus_connection_borrow_message().

void dbus_connection_steal_borrowed_message (DBusConnection *connection, DBusMessage *message)
 Used to keep a message after peeking at it using dbus_connection_borrow_message().

DBusMessagedbus_connection_pop_message (DBusConnection *connection)
 Returns the first-received message from the incoming message queue, removing it from the queue.

DBusDispatchStatus dbus_connection_get_dispatch_status (DBusConnection *connection)
 Gets the current state (what we would currently return from dbus_connection_dispatch()) but doesn't actually dispatch any messages.

DBusDispatchStatus dbus_connection_dispatch (DBusConnection *connection)
 Processes data buffered while handling watches, queueing zero or more incoming messages.

dbus_bool_t dbus_connection_set_watch_functions (DBusConnection *connection, DBusAddWatchFunction add_function, DBusRemoveWatchFunction remove_function, DBusWatchToggledFunction toggled_function, void *data, DBusFreeFunction free_data_function)
 Sets the watch functions for the connection.

dbus_bool_t dbus_connection_set_timeout_functions (DBusConnection *connection, DBusAddTimeoutFunction add_function, DBusRemoveTimeoutFunction remove_function, DBusTimeoutToggledFunction toggled_function, void *data, DBusFreeFunction free_data_function)
 Sets the timeout functions for the connection.

void dbus_connection_set_wakeup_main_function (DBusConnection *connection, DBusWakeupMainFunction wakeup_main_function, void *data, DBusFreeFunction free_data_function)
 Sets the mainloop wakeup function for the connection.

void dbus_connection_set_dispatch_status_function (DBusConnection *connection, DBusDispatchStatusFunction function, void *data, DBusFreeFunction free_data_function)
 Set a function to be invoked when the dispatch status changes.

dbus_bool_t dbus_connection_get_unix_user (DBusConnection *connection, unsigned long *uid)
 Gets the UNIX user ID of the connection if any.

void dbus_connection_set_unix_user_function (DBusConnection *connection, DBusAllowUnixUserFunction function, void *data, DBusFreeFunction free_data_function)
 Sets a predicate function used to determine whether a given user ID is allowed to connect.

dbus_bool_t dbus_connection_add_filter (DBusConnection *connection, DBusMessageHandler *handler)
 Adds a message filter.

void dbus_connection_remove_filter (DBusConnection *connection, DBusMessageHandler *handler)
 Removes a previously-added message filter.

dbus_bool_t dbus_connection_register_handler (DBusConnection *connection, DBusMessageHandler *handler, const char **messages_to_handle, int n_messages)
 Registers a handler for a list of message names.

void dbus_connection_unregister_handler (DBusConnection *connection, DBusMessageHandler *handler, const char **messages_to_handle, int n_messages)
 Unregisters a handler for a list of message names.

dbus_bool_t dbus_connection_allocate_data_slot (dbus_int32_t *slot_p)
 Allocates an integer ID to be used for storing application-specific data on any DBusConnection.

void dbus_connection_free_data_slot (dbus_int32_t *slot_p)
 Deallocates a global ID for connection data slots.

dbus_bool_t dbus_connection_set_data (DBusConnection *connection, dbus_int32_t slot, void *data, DBusFreeFunction free_data_func)
 Stores a pointer on a DBusConnection, along with an optional function to be used for freeing the data when the data is set again, or when the connection is finalized.

void * dbus_connection_get_data (DBusConnection *connection, dbus_int32_t slot)
 Retrieves data previously set with dbus_connection_set_data().

void dbus_connection_set_change_sigpipe (dbus_bool_t will_modify_sigpipe)
 This function sets a global flag for whether dbus_connection_new() will set SIGPIPE behavior to SIG_IGN.

void dbus_connection_set_max_message_size (DBusConnection *connection, long size)
 Specifies the maximum size message this connection is allowed to receive.

long dbus_connection_get_max_message_size (DBusConnection *connection)
 Gets the value set by dbus_connection_set_max_message_size().

void dbus_connection_set_max_received_size (DBusConnection *connection, long size)
 Sets the maximum total number of bytes that can be used for all messages received on this connection.

long dbus_connection_get_max_received_size (DBusConnection *connection)
 Gets the value set by dbus_connection_set_max_received_size().

long dbus_connection_get_outgoing_size (DBusConnection *connection)
 Gets the approximate size in bytes of all messages in the outgoing message queue.


Detailed Description

Connection to another application.

A DBusConnection represents a connection to another application. Messages can be sent and received via this connection. The other application may be a message bus; for convenience, the function dbus_bus_get() is provided to automatically open a connection to the well-known message buses.

In brief a DBusConnection is a message queue associated with some message transport mechanism such as a socket. The connection maintains a queue of incoming messages and a queue of outgoing messages.

Incoming messages are normally processed by calling dbus_connection_dispatch(). dbus_connection_dispatch() runs any handlers registered for the topmost message in the message queue, then discards the message, then returns.

dbus_connection_get_dispatch_status() indicates whether messages are currently in the queue that need dispatching. dbus_connection_set_dispatch_status_function() allows you to set a function to be used to monitor the dispatch status.

If you're using GLib or Qt add-on libraries for D-BUS, there are special convenience functions in those libraries that hide all the details of dispatch and watch/timeout monitoring. For example, dbus_connection_setup_with_g_main().

If you aren't using these add-on libraries, you have to manually call dbus_connection_set_dispatch_status_function(), dbus_connection_set_watch_functions(), dbus_connection_set_timeout_functions() providing appropriate functions to integrate the connection with your application's main loop.

When you use dbus_connection_send() or one of its variants to send a message, the message is added to the outgoing queue. It's actually written to the network later; either in dbus_watch_handle() invoked by your main loop, or in dbus_connection_flush() which blocks until it can write out the entire outgoing queue. The GLib/Qt add-on libraries again handle the details here for you by setting up watch functions.

When a connection is disconnected, you are guaranteed to get a message with the name #DBUS_MESSAGE_LOCAL_DISCONNECT.

You may not drop the last reference to a DBusConnection until that connection has been disconnected.

You may dispatch the unprocessed incoming message queue even if the connection is disconnected. However, #DBUS_MESSAGE_LOCAL_DISCONNECT will always be the last message in the queue (obviously no messages are received after disconnection).

DBusConnection has thread locks and drops them when invoking user callbacks, so in general is transparently threadsafe. However, DBusMessage does NOT have thread locks; you must not send the same message to multiple DBusConnection that will be used from different threads.


Function Documentation

dbus_bool_t dbus_connection_add_filter DBusConnection   connection,
DBusMessageHandler   handler
 

Adds a message filter.

Filters are handlers that are run on all incoming messages, prior to the normal handlers registered with dbus_connection_register_handler(). Filters are run in the order that they were added. The same handler can be added as a filter more than once, in which case it will be run more than once. Filters added during a filter callback won't be run on the message being processed.

The connection does NOT add a reference to the message handler; instead, if the message handler is finalized, the connection simply forgets about it. Thus the caller of this function must keep a reference to the message handler.

Parameters:
connection the connection
handler the handler
Returns:
TRUE on success, FALSE if not enough memory.

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

References _dbus_list_append(), _dbus_message_handler_add_connection(), _dbus_message_handler_remove_connection(), FALSE, filter_list, and TRUE.

dbus_bool_t dbus_connection_allocate_data_slot dbus_int32_t   slot_p
 

Allocates an integer ID to be used for storing application-specific data on any DBusConnection.

The allocated ID may then be used with dbus_connection_set_data() and dbus_connection_get_data(). The passed-in slot must be initialized to -1, and is filled in with the slot ID. If the passed-in slot is not -1, it's assumed to be already allocated, and its refcount is incremented.

The allocated slot is global, i.e. all DBusConnection objects will have a slot with the given integer ID reserved.

Parameters:
slot_p address of a global variable storing the slot
Returns:
FALSE on failure (no memory)

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

References _dbus_data_slot_allocator_alloc().

Referenced by dbus_connection_setup_with_g_main().

DBusMessage* dbus_connection_borrow_message DBusConnection   connection
 

Returns the first-received message from the incoming message queue, leaving it in the queue.

If the queue is empty, returns NULL.

The caller does not own a reference to the returned message, and must either return it using dbus_connection_return_message() or keep it after calling dbus_connection_steal_borrowed_message(). No one can get at the message while its borrowed, so return it as quickly as possible and don't keep a reference to it after returning it. If you need to keep the message, make a copy of it.

Parameters:
connection the connection.
Returns:
next message in the incoming queue.

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

References _dbus_list_get_first(), dbus_connection_get_dispatch_status(), incoming_messages, message_borrowed, and NULL.

void dbus_connection_disconnect DBusConnection   connection
 

Closes the connection, so no further data can be sent or received.

Any further attempts to send data will result in errors. This function does not affect the connection's reference count. It's safe to disconnect a connection more than once; all calls after the first do nothing. It's impossible to "reconnect" a connection, a new connection must be created.

Parameters:
connection the connection.

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

References _dbus_transport_disconnect(), and transport.

Referenced by dbus_bus_get().

DBusDispatchStatus dbus_connection_dispatch DBusConnection   connection
 

Processes data buffered while handling watches, queueing zero or more incoming messages.

Then pops the first-received message from the current incoming message queue, runs any handlers for it, and unrefs the message. Returns a status indicating whether messages/data remain, more memory is needed, or all data has been processed.

Even if the dispatch status is #DBUS_DISPATCH_DATA_REMAINS, does not necessarily dispatch a message, as the data may be part of authentication or the like.

Parameters:
connection the connection
Returns:
dispatch status

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

References _dbus_connection_ref_unlocked(), _dbus_hash_table_lookup_int(), _dbus_hash_table_lookup_string(), _dbus_list_clear(), _dbus_list_copy(), _dbus_list_foreach(), _dbus_list_free_link(), _dbus_list_get_first_link(), _dbus_list_get_next_link, _dbus_message_handler_handle_message(), _dbus_warn(), DBusList::data, dbus_connection_unref(), dbus_int32_t, dbus_message_get_name(), dbus_message_get_reply_serial(), dbus_message_unref(), filter_list, handler_table, NULL, and pending_replies.

void dbus_connection_flush DBusConnection   connection
 

Blocks until the outgoing message queue is empty.

Parameters:
connection the connection.

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

References _dbus_connection_do_iteration(), and n_outgoing.

Referenced by dbus_connection_send_with_reply_and_block().

void dbus_connection_free_data_slot dbus_int32_t   slot_p
 

Deallocates a global ID for connection data slots.

dbus_connection_get_data() and dbus_connection_set_data() may no longer be used with this slot. Existing data stored on existing DBusConnection objects will be freed when the connection is finalized, but may not be retrieved (and may only be replaced if someone else reallocates the slot). When the refcount on the passed-in slot reaches 0, it is set to -1.

Parameters:
slot_p address storing the slot to deallocate

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

References _dbus_data_slot_allocator_free().

void dbus_connection_free_preallocated_send DBusConnection   connection,
DBusPreallocatedSend *    preallocated
 

Frees preallocated message-sending resources from dbus_connection_preallocate_send().

Should only be called if the preallocated resources are not used to send a message.

Parameters:
connection the connection
preallocated the resources

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

References _dbus_counter_unref(), _dbus_list_free_link(), and dbus_free().

void* dbus_connection_get_data DBusConnection   connection,
dbus_int32_t    slot
 

Retrieves data previously set with dbus_connection_set_data().

The slot must still be allocated (must not have been freed).

Parameters:
connection the connection
slot the slot to get data from
Returns:
the data, or NULL if not found

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

References _dbus_data_slot_list_get(), and slot_list.

DBusDispatchStatus dbus_connection_get_dispatch_status DBusConnection   connection
 

Gets the current state (what we would currently return from dbus_connection_dispatch()) but doesn't actually dispatch any messages.

Parameters:
connection the connection.
Returns:
current dispatch status

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

Referenced by dbus_connection_borrow_message(), and dbus_connection_pop_message().

dbus_bool_t dbus_connection_get_is_authenticated DBusConnection   connection
 

Gets whether the connection was authenticated.

(Note that if the connection was authenticated then disconnected, this function still returns TRUE)

Parameters:
connection the connection
Returns:
TRUE if the connection was ever authenticated

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

References _dbus_transport_get_is_authenticated(), dbus_bool_t, and transport.

dbus_bool_t dbus_connection_get_is_connected DBusConnection   connection
 

Gets whether the connection is currently connected.

All connections are connected when they are opened. A connection may become disconnected when the remote application closes its end, or exits; a connection may also be disconnected with dbus_connection_disconnect().

Parameters:
connection the connection.
Returns:
TRUE if the connection is still alive.

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

References dbus_bool_t.

Referenced by dbus_connection_send_with_reply_and_block().

long dbus_connection_get_max_message_size DBusConnection   connection
 

Gets the value set by dbus_connection_set_max_message_size().

Parameters:
connection the connection
Returns:
the max size of a single message

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

References _dbus_transport_get_max_message_size(), and transport.

long dbus_connection_get_max_received_size DBusConnection   connection
 

Gets the value set by dbus_connection_set_max_received_size().

Parameters:
connection the connection
Returns:
the max size of all live messages

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

References _dbus_transport_get_max_received_size(), and transport.

long dbus_connection_get_outgoing_size DBusConnection   connection
 

Gets the approximate size in bytes of all messages in the outgoing message queue.

The size is approximate in that you shouldn't use it to decide how many bytes to read off the network or anything of that nature, as optimizations may choose to tell small white lies to avoid performance overhead.

Parameters:
connection the connection
Returns:
the number of bytes that have been queued up but not sent

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

References _dbus_counter_get_value(), and outgoing_counter.

dbus_bool_t dbus_connection_get_unix_user DBusConnection   connection,
unsigned long *    uid
 

Gets the UNIX user ID of the connection if any.

Returns TRUE if the uid is filled in. Always returns FALSE on non-UNIX platforms. Always returns FALSE prior to authenticating the connection.

Parameters:
connection the connection
uid return location for the user ID
Returns:
TRUE if uid is filled in with a valid user ID

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

References _dbus_transport_get_is_authenticated(), _dbus_transport_get_unix_user(), dbus_bool_t, FALSE, and transport.

DBusConnection* dbus_connection_open const char *    address,
DBusError *    error
 

Opens a new connection to a remote address.

Todo:
specify what the address parameter is. Right now it's just the name of a UNIX domain socket. It should be something more complex that encodes which transport to use.
If the open fails, the function returns NULL, and provides a reason for the failure in the result parameter. Pass NULL for the result parameter if you aren't interested in the reason for failure.

Parameters:
address the address.
error address where an error can be returned.
Returns:
new connection, or NULL on failure.

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

References _dbus_connection_new_for_transport(), _dbus_transport_open(), _dbus_transport_unref(), dbus_set_error(), and NULL.

Referenced by dbus_bus_get().

DBusMessage* dbus_connection_pop_message DBusConnection   connection
 

Returns the first-received message from the incoming message queue, removing it from the queue.

The caller owns a reference to the returned message. If the queue is empty, returns NULL.

This function bypasses any message handlers that are registered, and so using it is usually wrong. Instead, let the main loop invoke dbus_connection_dispatch(). Popping messages manually is only useful in very simple programs that don't share a DBusConnection with any libraries or other modules.

Parameters:
connection the connection.
Returns:
next message in the incoming queue.

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

References dbus_connection_get_dispatch_status(), and NULL.

DBusPreallocatedSend* dbus_connection_preallocate_send DBusConnection   connection
 

Preallocates resources needed to send a message, allowing the message to be sent without the possibility of memory allocation failure.

Allows apps to create a future guarantee that they can send a message regardless of memory shortages.

Parameters:
connection the connection we're preallocating for.
Returns:
the preallocated resources, or NULL

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

void dbus_connection_ref DBusConnection   connection
 

Increments the reference count of a DBusConnection.

Parameters:
connection the connection.

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

References _dbus_assert, _dbus_atomic_inc(), and refcount.

Referenced by dbus_bus_get().

dbus_bool_t dbus_connection_register_handler DBusConnection   connection,
DBusMessageHandler   handler,
const char **    messages_to_handle,
int    n_messages
 

Registers a handler for a list of message names.

A single handler can be registered for any number of message names, but each message name can only have one handler at a time. It's not allowed to call this function with the name of a message that already has a handler. If the function returns FALSE, the handlers were not registered due to lack of memory.

The connection does NOT add a reference to the message handler; instead, if the message handler is finalized, the connection simply forgets about it. Thus the caller of this function must keep a reference to the message handler.

Todo:
the messages_to_handle arg may be more convenient if it's a single string instead of an array. Though right now MessageHandler is sort of designed to say be associated with an entire object with multiple methods, that's why for example the connection only weakrefs it. So maybe the "manual" API should be different.
Parameters:
connection the connection
handler the handler
messages_to_handle the messages to handle
n_messages the number of message names in messages_to_handle
Returns:
TRUE on success, FALSE if no memory or another handler already exists

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

References _dbus_hash_iter_get_value(), _dbus_hash_iter_lookup(), _dbus_hash_iter_remove_entry(), _dbus_hash_iter_set_value(), _dbus_message_handler_add_connection(), _dbus_strdup(), _dbus_warn(), dbus_connection_unregister_handler(), dbus_free(), FALSE, handler_table, NULL, and TRUE.

void dbus_connection_remove_filter DBusConnection   connection,
DBusMessageHandler   handler
 

Removes a previously-added message filter.

It is a programming error to call this function for a handler that has not been added as a filter. If the given handler was added more than once, only one instance of it will be removed (the most recently-added instance).

Parameters:
connection the connection
handler the handler to remove

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

References _dbus_list_remove_last(), _dbus_message_handler_remove_connection(), _dbus_warn(), and filter_list.

void dbus_connection_return_message DBusConnection   connection,
DBusMessage   message
 

Used to return a message after peeking at it using dbus_connection_borrow_message().

Parameters:
connection the connection
message the message from dbus_connection_borrow_message()

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

References _dbus_assert, dbus_condvar_wake_all(), message_borrowed, message_returned_cond, and NULL.

dbus_bool_t dbus_connection_send DBusConnection   connection,
DBusMessage   message,
dbus_uint32_t   client_serial
 

Adds a message to the outgoing message queue.

Does not block to write the message to the network; that happens asynchronously. To force the message to be written, call dbus_connection_flush(). Because this only queues the message, the only reason it can fail is lack of memory. Even if the connection is disconnected, no error will be returned.

If the function fails due to lack of memory, it returns FALSE. The function will never fail for other reasons; even if the connection is disconnected, you can queue an outgoing message, though obviously it won't be sent.

Parameters:
connection the connection.
message the message to write.
client_serial return location for client serial.
Returns:
TRUE on success.

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

References FALSE, NULL, and TRUE.

Referenced by dbus_connection_send_with_reply(), and dbus_connection_send_with_reply_and_block().

void dbus_connection_send_preallocated DBusConnection   connection,
DBusPreallocatedSend *    preallocated,
DBusMessage   message,
dbus_uint32_t   client_serial
 

Sends a message using preallocated resources.

This function cannot fail. It works identically to dbus_connection_send() in other respects. Preallocated resources comes from dbus_connection_preallocate_send(). This function "consumes" the preallocated resources, they need not be freed separately.

Parameters:
connection the connection
preallocated the preallocated resources
message the message to send
client_serial return location for client serial assigned to the message

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

dbus_bool_t dbus_connection_send_with_reply DBusConnection   connection,
DBusMessage   message,
DBusMessageHandler   reply_handler,
int    timeout_milliseconds
 

Queues a message to send, as with dbus_connection_send_message(), but also sets up a DBusMessageHandler to receive a reply to the message.

If no reply is received in the given timeout_milliseconds, expires the pending reply and sends the DBusMessageHandler a synthetic error reply (generated in-process, not by the remote application) indicating that a timeout occurred.

Reply handlers see their replies after message filters see them, but before message handlers added with dbus_connection_register_handler() see them, regardless of the reply message's name. Reply handlers are only handed a single message as a reply, after one reply has been seen the handler is removed. If a filter filters out the reply before the handler sees it, the reply is immediately timed out and a timeout error reply is generated. If a filter removes the timeout error reply then the reply handler will never be called. Filters should not do this.

If NULL is passed for the reply_handler, the timeout reply will still be generated and placed into the message queue, but no specific message handler will receive the reply.

If -1 is passed for the timeout, a sane default timeout is used. -1 is typically the best value for the timeout for this reason, unless you want a very short or very long timeout. There is no way to avoid a timeout entirely, other than passing INT_MAX for the timeout to postpone it indefinitely.

Parameters:
connection the connection
message the message to send
reply_handler message handler expecting the reply, or NULL
timeout_milliseconds timeout in milliseconds or -1 for default
Returns:
TRUE if the message is successfully queued, FALSE if no memory.

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

References _dbus_connection_add_timeout(), _dbus_hash_table_insert_int(), _dbus_hash_table_remove_int(), _dbus_list_alloc_link(), _dbus_message_handler_add_connection(), _dbus_message_set_serial(), _dbus_timeout_new(), _dbus_timeout_unref(), dbus_connection_send(), dbus_int32_t, dbus_message_get_serial(), dbus_message_handler_ref(), dbus_message_new_error_reply(), dbus_message_unref(), dbus_new0, DEFAULT_TIMEOUT_VALUE, FALSE, pending_replies, and TRUE.

DBusMessage* dbus_connection_send_with_reply_and_block DBusConnection   connection,
DBusMessage   message,
int    timeout_milliseconds,
DBusError *    error
 

Sends a message and blocks a certain time period while waiting for a reply.

This function does not dispatch any message handlers until the main loop has been reached. This function is used to do non-reentrant "method calls." If a reply is received, it is returned, and removed from the incoming message queue. If it is not received, NULL is returned and the error is set to #DBUS_ERROR_NO_REPLY. If something else goes wrong, result is set to whatever is appropriate, such as #DBUS_ERROR_NO_MEMORY or #DBUS_ERROR_DISCONNECTED.

Todo:
could use performance improvements (it keeps scanning the whole message queue for example) and has thread issues, see comments in source
Parameters:
connection the connection
message the message to send
timeout_milliseconds timeout in milliseconds or -1 for default
error return location for error message
Returns:
the message that is the reply or NULL with an error code if the function fails.

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

References _dbus_assert, _dbus_connection_do_iteration(), _dbus_get_current_time(), _dbus_sleep_milliseconds(), dbus_connection_flush(), dbus_connection_get_is_connected(), dbus_connection_send(), dbus_set_error(), dbus_uint32_t, DEFAULT_TIMEOUT_VALUE, disconnect_message_link, and NULL.

Referenced by dbus_bus_acquire_service(), dbus_bus_activate_service(), dbus_bus_register(), and dbus_bus_service_exists().

void dbus_connection_set_change_sigpipe dbus_bool_t    will_modify_sigpipe
 

This function sets a global flag for whether dbus_connection_new() will set SIGPIPE behavior to SIG_IGN.

Parameters:
will_modify_sigpipe TRUE to allow sigpipe to be set to SIG_IGN

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

References FALSE.

dbus_bool_t dbus_connection_set_data DBusConnection   connection,
dbus_int32_t    slot,
void *    data,
DBusFreeFunction    free_data_func
 

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

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

Parameters:
connection the connection
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 2987 of file dbus-connection.c.

References _dbus_data_slot_list_set(), dbus_bool_t, DBusFreeFunction, and slot_list.

Referenced by dbus_connection_setup_with_g_main().

void dbus_connection_set_dispatch_status_function DBusConnection   connection,
DBusDispatchStatusFunction    function,
void *    data,
DBusFreeFunction    free_data_function
 

Set a function to be invoked when the dispatch status changes.

If the dispatch status is #DBUS_DISPATCH_DATA_REMAINS, then dbus_connection_dispatch() needs to be called to process incoming messages. However, dbus_connection_dispatch() MUST NOT BE CALLED from inside the DBusDispatchStatusFunction. Indeed, almost any reentrancy in this function is a bad idea. Instead, the DBusDispatchStatusFunction should simply save an indication that messages should be dispatched later, when the main loop is re-entered.

Parameters:
connection the connection
function function to call on dispatch status changes
data data for function
free_data_function free the function data

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

References DBusFreeFunction, dispatch_status_data, dispatch_status_function, and free_dispatch_status_data.

void dbus_connection_set_max_message_size DBusConnection   connection,
long    size
 

Specifies the maximum size message this connection is allowed to receive.

Larger messages will result in disconnecting the connection.

Parameters:
connection a DBusConnection
size maximum message size the connection can receive, in bytes

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

References _dbus_transport_set_max_message_size(), and transport.

void dbus_connection_set_max_received_size DBusConnection   connection,
long    size
 

Sets the maximum total number of bytes that can be used for all messages received on this connection.

Messages count toward the maximum until they are finalized. When the maximum is reached, the connection will not read more data until some messages are finalized.

The semantics of the maximum are: if outstanding messages are already above the maximum, additional messages will not be read. The semantics are not: if the next message would cause us to exceed the maximum, we don't read it. The reason is that we don't know the size of a message until after we read it.

Thus, the max live messages size can actually be exceeded by up to the maximum size of a single message.

Also, if we read say 1024 bytes off the wire in a single read(), and that contains a half-dozen small messages, we may exceed the size max by that amount. But this should be inconsequential.

This does imply that we can't call read() with a buffer larger than we're willing to exceed this limit by.

Parameters:
connection the connection
size the maximum size in bytes of all outstanding messages

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

References _dbus_transport_set_max_received_size(), and transport.

dbus_bool_t dbus_connection_set_timeout_functions DBusConnection   connection,
DBusAddTimeoutFunction    add_function,
DBusRemoveTimeoutFunction    remove_function,
DBusTimeoutToggledFunction    toggled_function,
void *    data,
DBusFreeFunction    free_data_function
 

Sets the timeout functions for the connection.

These functions are responsible for making the application's main loop aware of timeouts. When using Qt, typically the DBusAddTimeoutFunction would create a QTimer. When using GLib, the DBusAddTimeoutFunction would call g_timeout_add.

The DBusTimeoutToggledFunction notifies the application that the timeout has been enabled or disabled. Call dbus_timeout_get_enabled() to check this. A disabled timeout should have no effect, and enabled timeout should be added to the main loop. This feature is used instead of simply adding/removing the timeout because enabling/disabling can be done without memory allocation. With Qt, QTimer::start() and QTimer::stop() can be used to enable and disable. The toggled function may be NULL if a main loop re-queries dbus_timeout_get_enabled() every time anyway. Whenever a timeout is toggled, its interval may change.

The DBusTimeout can be queried for the timer interval using dbus_timeout_get_interval(). dbus_timeout_handle() should be called repeatedly, each time the interval elapses, starting after it has elapsed once. The timeout stops firing when it is removed with the given remove_function. The timer interval may change whenever the timeout is added, removed, or toggled.

Parameters:
connection the connection.
add_function function to add a timeout.
remove_function function to remove a timeout.
toggled_function function to notify of enable/disable
data data to pass to add_function and remove_function.
free_data_function function to be called to free the data.
Returns:
FALSE on failure (no memory)

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

References _dbus_connection_ref_unlocked(), _dbus_timeout_list_set_functions(), dbus_bool_t, dbus_connection_unref(), and timeouts.

Referenced by dbus_connection_setup_with_g_main().

void dbus_connection_set_unix_user_function DBusConnection   connection,
DBusAllowUnixUserFunction    function,
void *    data,
DBusFreeFunction    free_data_function
 

Sets a predicate function used to determine whether a given user ID is allowed to connect.

When an incoming connection has authenticated with a particular user ID, this function is called; if it returns TRUE, the connection is allowed to proceed, otherwise the connection is disconnected.

If the function is set to NULL (as it is by default), then only the same UID as the server process will be allowed to connect.

Parameters:
connection the connection
function the predicate
data data to pass to the predicate
free_data_function function to free the data

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

References _dbus_transport_set_unix_user_function(), DBusFreeFunction, NULL, and transport.

void dbus_connection_set_wakeup_main_function DBusConnection   connection,
DBusWakeupMainFunction    wakeup_main_function,
void *    data,
DBusFreeFunction    free_data_function
 

Sets the mainloop wakeup function for the connection.

Thi function is responsible for waking up the main loop (if its sleeping) when some some change has happened to the connection that the mainloop needs to reconsiders (e.g. a message has been queued for writing). When using Qt, this typically results in a call to QEventLoop::wakeUp(). When using GLib, it would call g_main_context_wakeup().

Parameters:
connection the connection.
wakeup_main_function function to wake up the mainloop
data data to pass wakeup_main_function
free_data_function function to be called to free the data.

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

References DBusFreeFunction, free_wakeup_main_data, wakeup_main_data, and wakeup_main_function.

Referenced by dbus_connection_setup_with_g_main().

dbus_bool_t dbus_connection_set_watch_functions DBusConnection   connection,
DBusAddWatchFunction    add_function,
DBusRemoveWatchFunction    remove_function,
DBusWatchToggledFunction    toggled_function,
void *    data,
DBusFreeFunction    free_data_function
 

Sets the watch functions for the connection.

These functions are responsible for making the application's main loop aware of file descriptors that need to be monitored for events, using select() or poll(). When using Qt, typically the DBusAddWatchFunction would create a QSocketNotifier. When using GLib, the DBusAddWatchFunction could call g_io_add_watch(), or could be used as part of a more elaborate GSource. Note that when a watch is added, it may not be enabled.

The DBusWatchToggledFunction notifies the application that the watch has been enabled or disabled. Call dbus_watch_get_enabled() to check this. A disabled watch should have no effect, and enabled watch should be added to the main loop. This feature is used instead of simply adding/removing the watch because enabling/disabling can be done without memory allocation. The toggled function may be NULL if a main loop re-queries dbus_watch_get_enabled() every time anyway.

The DBusWatch can be queried for the file descriptor to watch using dbus_watch_get_fd(), and for the events to watch for using dbus_watch_get_flags(). The flags returned by dbus_watch_get_flags() will only contain DBUS_WATCH_READABLE and DBUS_WATCH_WRITABLE, never DBUS_WATCH_HANGUP or DBUS_WATCH_ERROR; all watches implicitly include a watch for hangups, errors, and other exceptional conditions.

Once a file descriptor becomes readable or writable, or an exception occurs, dbus_watch_handle() should be called to notify the connection of the file descriptor's condition.

dbus_watch_handle() cannot be called during the DBusAddWatchFunction, as the connection will not be ready to handle that watch yet.

It is not allowed to reference a DBusWatch after it has been passed to remove_function.

If FALSE is returned due to lack of memory, the failure may be due to a FALSE return from the new add_function. If so, the add_function may have been called successfully one or more times, but the remove_function will also have been called to remove any successful adds. i.e. if FALSE is returned the net result should be that dbus_connection_set_watch_functions() has no effect, but the add_function and remove_function may have been called.

Todo:
We need to drop the lock when we call the add/remove/toggled functions which can be a side effect of setting the watch functions.
Parameters:
connection the connection.
add_function function to begin monitoring a new descriptor.
remove_function function to stop monitoring a descriptor.
toggled_function function to notify of enable/disable
data data to pass to add_function and remove_function.
free_data_function function to be called to free the data.
Returns:
FALSE on failure (no memory)

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

References _dbus_connection_ref_unlocked(), _dbus_watch_list_set_functions(), dbus_bool_t, dbus_connection_unref(), and watches.

Referenced by dbus_connection_setup_with_g_main().

void dbus_connection_steal_borrowed_message DBusConnection   connection,
DBusMessage   message
 

Used to keep a message after peeking at it using dbus_connection_borrow_message().

Before using this function, see the caveats/warnings in the documentation for dbus_connection_pop_message().

Parameters:
connection the connection
message the message from dbus_connection_borrow_message()

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

References _dbus_assert, _dbus_list_pop_first(), dbus_condvar_wake_all(), incoming_messages, message_borrowed, message_returned_cond, n_incoming, and NULL.

void dbus_connection_unref DBusConnection   connection
 

Decrements the reference count of a DBusConnection, and finalizes it if the count reaches zero.

It is a bug to drop the last reference to a connection that has not been disconnected.

Todo:
in practice it can be quite tricky to never unref a connection that's still connected; maybe there's some way we could avoid the requirement.
Parameters:
connection the connection.

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

References _dbus_assert, _dbus_atomic_dec(), dbus_bool_t, and refcount.

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

void dbus_connection_unregister_handler DBusConnection   connection,
DBusMessageHandler   handler,
const char **    messages_to_handle,
int    n_messages
 

Unregisters a handler for a list of message names.

The handlers must have been previously registered.

Parameters:
connection the connection
handler the handler
messages_to_handle the messages to handle
n_messages the number of message names in messages_to_handle

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

References _dbus_hash_iter_get_value(), _dbus_hash_iter_lookup(), _dbus_hash_iter_remove_entry(), _dbus_message_handler_remove_connection(), _dbus_warn(), and handler_table.

Referenced by dbus_connection_register_handler().


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