DBusConnection
[D-BUS low-level public API]

Connection to another application. More...


Functions
DBusConnection *	dbus_connection_open (const char address, DBusError error)
	Gets a connection to a remote address.
DBusConnection *	dbus_connection_open_private (const char address, DBusError error)
	Opens a new, dedicated connection to a remote address.
DBusConnection *	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_close (DBusConnection *connection)
	Closes the connection, so no further data can be sent or received.
void	dbus_connection_disconnect (DBusConnection *connection)
	Alias for dbus_connection_close().
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.
void	dbus_connection_set_exit_on_disconnect (DBusConnection *connection, dbus_bool_t exit_on_disconnect)
	Set whether _exit() should be called when the connection receives a disconnect signal.
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_and_unlock (DBusConnection connection, DBusMessage message, dbus_uint32_t *client_serial)
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, DBusPendingCall **pending_return, int timeout_milliseconds)
	Queues a message to send, as with dbus_connection_send_message(), but also returns a DBusPendingCall used to receive a reply to the message.
void	_dbus_connection_block_pending_call (DBusPendingCall *pending)
	Blocks until a pending call times out or gets a reply.
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.
void	dbus_connection_flush (DBusConnection *connection)
	Blocks until the outgoing message queue is empty.
dbus_bool_t	_dbus_connection_read_write_dispatch (DBusConnection *connection, int timeout_milliseconds, dbus_bool_t dispatch)
	This function is intended for use with applications that don't want to write a main loop and deal with DBusWatch and DBusTimeout.
dbus_bool_t	dbus_connection_read_write_dispatch (DBusConnection *connection, int timeout_milliseconds)
	This function is intended for use with applications that don't want to write a main loop and deal with DBusWatch and DBusTimeout.
dbus_bool_t	dbus_connection_read_write (DBusConnection *connection, int timeout_milliseconds)
	This function is intended for use with applications that don't want to write a main loop and deal with DBusWatch and DBusTimeout.
DBusMessage *	dbus_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().
DBusMessage *	dbus_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_fd (DBusConnection connection, int fd)
	Get the UNIX file descriptor of the connection, if any.
dbus_bool_t	dbus_connection_get_unix_user (DBusConnection connection, unsigned long uid)
	Gets the UNIX user ID of the connection if any.
dbus_bool_t	dbus_connection_get_unix_process_id (DBusConnection connection, unsigned long pid)
	Gets the process 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, DBusHandleMessageFunction function, void user_data, DBusFreeFunction free_data_function)
	Adds a message filter.
void	dbus_connection_remove_filter (DBusConnection connection, DBusHandleMessageFunction function, void user_data)
	Removes a previously-added message filter.
dbus_bool_t	dbus_connection_register_object_path (DBusConnection connection, const char path, const DBusObjectPathVTable vtable, void user_data)
	Registers a handler for a given path in the object hierarchy.
dbus_bool_t	dbus_connection_register_fallback (DBusConnection connection, const char path, const DBusObjectPathVTable vtable, void user_data)
	Registers a fallback handler for a given subsection of the object hierarchy.
dbus_bool_t	dbus_connection_unregister_object_path (DBusConnection connection, const char path)
	Unregisters the handler registered with exactly the given path.
dbus_bool_t	dbus_connection_get_object_path_data (DBusConnection connection, const char path, void **data_p)
	Gets the user data passed to dbus_connection_register_object_path() or dbus_connection_register_fallback().
dbus_bool_t	dbus_connection_list_registered (DBusConnection connection, const char parent_path, char ***child_entries)
	Lists the registered fallback handlers and object path handlers at the given parent_path.
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 APIs 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 signal "Disconnected" from the interface DBUS_INTERFACE_LOCAL, path DBUS_PATH_LOCAL.

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, "Disconnected" 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

void _dbus_connection_block_pending_call ( DBusPendingCall * pending )

Blocks until a pending call times out or gets a reply.
Does not re-enter the main loop or run filter/path-registered callbacks. The reply to the message will not be seen by filter callbacks.
Returns immediately if pending call already got a reply.

Todo:
could use performance improvements (it keeps scanning the whole message queue for example)

Parameters:

pending the pending call we block for a reply on

Definition at line 2573 of file dbus-connection.c.
References _dbus_assert, _dbus_connection_do_iteration_unlocked(), _dbus_get_current_time(), _dbus_pending_call_complete_and_unlock(), dbus_connection_flush(), dbus_message_unref(), dbus_pending_call_get_completed(), dbus_pending_call_ref(), dbus_pending_call_unref(), dbus_timeout_get_interval(), and NULL.
Referenced by dbus_pending_call_block().

dbus_bool_t _dbus_connection_read_write_dispatch ( DBusConnection * connection,

int timeout_milliseconds,

dbus_bool_t dispatch

)

This function is intended for use with applications that don't want to write a main loop and deal with DBusWatch and DBusTimeout.
An example usage would be:

while (dbus_connection_read_write_dispatch (connection, -1)) ; // empty loop body
In this usage you would normally have set up a filter function to look at each message as it is dispatched. The loop terminates when the last message from the connection (the disconnected signal) is processed.
If there are messages to dispatch and the dispatch flag is set, this function will dbus_connection_dispatch() once, and return. If there are no messages to dispatch, this function will block until it can read or write, then read or write, then return.
The way to think of this function is that it either makes some sort of progress, or it blocks.
The return value indicates whether the disconnect message has been processed, NOT whether the connection is connected. This is important because even after disconnecting, you want to process any messages you received prior to the disconnect.

Parameters:

connection the connection

timeout_milliseconds max time to block or -1 for infinite

dispatch dispatch new messages or leave them on the incoming queue

Returns:
TRUE if the disconnect message has not been processed

Definition at line 2870 of file dbus-connection.c.
References _dbus_connection_do_iteration_unlocked(), dbus_connection_dispatch(), dbus_connection_get_dispatch_status(), disconnect_message_link, FALSE, n_incoming, and NULL.
Referenced by dbus_connection_read_write(), and dbus_connection_read_write_dispatch().

dbus_bool_t dbus_connection_add_filter ( DBusConnection * connection,

DBusHandleMessageFunction function,

void * user_data,

DBusFreeFunction free_data_function

)

Adds a message filter.
Filters are handlers that are run on all incoming messages, prior to the objects registered with dbus_connection_register_object_path(). 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.

Todo:
we don't run filters on messages while blocking without entering the main loop, since filters are run as part of dbus_connection_dispatch(). This is probably a feature, as filters could create arbitrary reentrancy. But kind of sucks if you're trying to filter METHOD_RETURN for some reason.

Parameters:

connection the connection

function function to handle messages

user_data user data to pass to the function

free_data_function function to use for freeing user data

Returns:
TRUE on success, FALSE if not enough memory.

Definition at line 4217 of file dbus-connection.c.
References _dbus_list_append(), dbus_new0, FALSE, DBusMessageFilter::free_user_data_function, DBusMessageFilter::function, NULL, DBusMessageFilter::refcount, TRUE, DBusMessageFilter::user_data, and DBusAtomic::value.

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 4527 of file dbus-connection.c.
References _dbus_data_slot_allocator_alloc(), and _DBUS_LOCK_NAME.
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.
dbus_connection_dispatch() will block if called while a borrowed message is outstanding; only one piece of code can be playing with the incoming queue at a time. This function will block if called during a dbus_connection_dispatch().

Parameters:

connection the connection.

Returns:
next message in the incoming queue.

Definition at line 2996 of file dbus-connection.c.
References _dbus_assert, _dbus_list_get_first(), dbus_connection_get_dispatch_status(), incoming_messages, message_borrowed, and NULL.

void dbus_connection_close ( 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 "reopen" a connection, a new connection must be created. This function may result in a call to the DBusDispatchStatusFunction set with dbus_connection_set_dispatch_status_function(), as the disconnect message it generates needs to be dispatched.

Parameters:

connection the connection.

Definition at line 1930 of file dbus-connection.c.
References _dbus_current_generation, _dbus_transport_disconnect(), generation, NULL, and transport.
Referenced by dbus_connection_disconnect().

void dbus_connection_disconnect ( DBusConnection * connection )

Alias for dbus_connection_close().
This method is DEPRECATED and will be removed for 1.0. Change your code to use dbus_connection_close() instead.

Parameters:

connection the connection.

Deprecated:

Definition at line 1957 of file dbus-connection.c.
References dbus_connection_close().

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.

Todo:
some FIXME in here about handling DBUS_HANDLER_RESULT_NEED_MEMORY

Todo:
FIXME what if we call out to application code to handle a message, holding the dispatch lock, and the application code runs the main loop and dispatches again? Probably deadlocks at the moment. Maybe we want a dispatch status of DBUS_DISPATCH_IN_PROGRESS, and then the GSource etc. could handle the situation? Right now our GSource is NO_RECURSE

Parameters:

connection the connection

Returns:
dispatch status

Definition at line 3506 of file dbus-connection.c.
References _dbus_assert_not_reached, _dbus_connection_ref_unlocked(), _dbus_exit(), _dbus_hash_table_lookup_int(), _dbus_list_clear(), _dbus_list_copy(), _dbus_list_foreach(), _dbus_list_free_link(), _dbus_list_get_first_link(), _dbus_list_get_next_link, _dbus_object_tree_dispatch_and_unlock(), _dbus_pending_call_complete_and_unlock(), _dbus_string_append_printf(), _dbus_string_free(), _dbus_string_get_const_data(), _dbus_string_init(), DBusList::data, dbus_connection_unref(), dbus_message_get_interface(), dbus_message_get_member(), dbus_message_get_reply_serial(), dbus_message_get_signature(), dbus_message_get_type(), dbus_message_is_signal(), dbus_message_new_error(), dbus_message_unref(), dbus_pending_call_unref(), exit_on_disconnect, filter_list, DBusMessageFilter::function, NULL, objects, pending_replies, and DBusMessageFilter::user_data.
Referenced by _dbus_connection_read_write_dispatch().

void dbus_connection_flush ( DBusConnection * connection )

Blocks until the outgoing message queue is empty.

Parameters:

connection the connection.

Definition at line 2802 of file dbus-connection.c.
References _dbus_connection_do_iteration_unlocked(), n_outgoing, and NULL.
Referenced by _dbus_connection_block_pending_call(), and dbus_g_connection_flush().

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 4546 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 2128 of file dbus-connection.c.
References _dbus_counter_unref(), _dbus_list_free_link(), DBusPreallocatedSend::connection, DBusPreallocatedSend::counter_link, DBusList::data, dbus_free(), NULL, and DBusPreallocatedSend::queue_link.

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 4607 of file dbus-connection.c.
References _dbus_data_slot_list_get(), and NULL.
Referenced by dbus_bus_connection_get_unique_name(), and dbus_connection_setup_with_g_main().

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 3417 of file dbus-connection.c.
References NULL.
Referenced by _dbus_connection_read_write_dispatch(), 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 2002 of file dbus-connection.c.
References _dbus_transport_get_is_authenticated(), FALSE, NULL, 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_close().

Parameters:

connection the connection.

Returns:
TRUE if the connection is still alive.

Definition at line 1980 of file dbus-connection.c.
References FALSE, and NULL.

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 4664 of file dbus-connection.c.
References _dbus_transport_get_max_message_size(), NULL, 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 4720 of file dbus-connection.c.
References _dbus_transport_get_max_received_size(), NULL, and transport.

dbus_bool_t dbus_connection_get_object_path_data ( DBusConnection * connection,

const char * path,

void ** data_p

)

Gets the user data passed to dbus_connection_register_object_path() or dbus_connection_register_fallback().
If nothing was registered at this path, the data is filled in with NULL.

Parameters:

connection the connection

path the path you registered with

data_p location to store the user data, or NULL

Returns:
FALSE if not enough memory

Definition at line 4448 of file dbus-connection.c.
References _dbus_decompose_path(), _dbus_object_tree_get_user_data_unlocked(), dbus_free_string_array(), FALSE, NULL, objects, and TRUE.
Referenced by dbus_g_connection_lookup_g_object().

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 4743 of file dbus-connection.c.
References _dbus_counter_get_value(), NULL, and outgoing_counter.

dbus_bool_t dbus_connection_get_unix_fd ( DBusConnection * connection,

int * fd

)

Get the UNIX file descriptor of the connection, if any.
This can be used for SELinux access control checks with getpeercon() for example. DO NOT read or write to the file descriptor, or try to select() on it; use DBusWatch for main loop integration. Not all connections will have a file descriptor. So for adding descriptors to the main loop, use dbus_watch_get_fd() and so forth.

Parameters:

connection the connection

fd return location for the file descriptor.

Returns:
TRUE if fd is successfully obtained.

Definition at line 4077 of file dbus-connection.c.
References _dbus_transport_get_unix_fd(), FALSE, and NULL.

dbus_bool_t dbus_connection_get_unix_process_id ( DBusConnection * connection,

unsigned long * pid

)

Gets the process ID of the connection if any.
Returns TRUE if the uid is filled in. Always returns FALSE prior to authenticating the connection.

Parameters:

connection the connection

pid return location for the process ID

Returns:
TRUE if uid is filled in with a valid process ID

Definition at line 4138 of file dbus-connection.c.
References _dbus_transport_get_is_authenticated(), _dbus_transport_get_unix_process_id(), FALSE, NULL, and transport.

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 4107 of file dbus-connection.c.
References _dbus_transport_get_is_authenticated(), _dbus_transport_get_unix_user(), FALSE, NULL, and transport.

dbus_bool_t dbus_connection_list_registered ( DBusConnection * connection,

const char * parent_path,

char *** child_entries

)

Lists the registered fallback handlers and object path handlers at the given parent_path.
The returned array should be freed with dbus_free_string_array().

Parameters:

connection the connection

parent_path the path to list the child handlers of

child_entries returns NULL-terminated array of children

Returns:
FALSE if no memory to allocate the child entries

Definition at line 4485 of file dbus-connection.c.
References _dbus_decompose_path(), _dbus_object_tree_list_registered_and_unlock(), dbus_free_string_array(), FALSE, NULL, and objects.

DBusConnection* dbus_connection_open ( const char * address,

DBusError * error

)

Gets a connection to a remote address.
If a connection to the given address already exists, returns the existing connection with its reference count incremented. Otherwise, returns a new connection and saves the new connection for possible re-use if a future call to dbus_connection_open() asks to connect to the same server.
Use dbus_connection_open_private() to get a dedicated connection not shared with other callers of dbus_connection_open().
If the open fails, the function returns NULL, and provides a reason for the failure in the error parameter. Pass NULL for the error 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 1694 of file dbus-connection.c.
References NULL, and TRUE.

DBusConnection* dbus_connection_open_private ( const char * address,

DBusError * error

)

Opens a new, dedicated connection to a remote address.
Unlike dbus_connection_open(), always creates a new connection. This connection will not be saved or recycled by libdbus.
If the open fails, the function returns NULL, and provides a reason for the failure in the error parameter. Pass NULL for the error 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 1724 of file dbus-connection.c.
References FALSE, and NULL.

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.
There is a lock that covers all ways of accessing the incoming message queue, so dbus_connection_dispatch(), dbus_connection_pop_message(), dbus_connection_borrow_message(), etc. will all block while one of the others in the group is running.

Parameters:

connection the connection.

Returns:
next message in the incoming queue.

Definition at line 3212 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 2102 of file dbus-connection.c.
References NULL.

dbus_bool_t dbus_connection_read_write ( DBusConnection * connection,

int timeout_milliseconds

)

This function is intended for use with applications that don't want to write a main loop and deal with DBusWatch and DBusTimeout.
If there are no messages to dispatch, this function will block until it can read or write, then read or write, then return.
The return value indicates whether the disconnect message has been processed, NOT whether the connection is connected. This is important because even after disconnecting, you want to process any messages you received prior to the disconnect.

Parameters:

connection the connection

timeout_milliseconds max time to block or -1 for infinite

Returns:
TRUE if the disconnect message has not been processed

Definition at line 2970 of file dbus-connection.c.
References _dbus_connection_read_write_dispatch(), and FALSE.

dbus_bool_t dbus_connection_read_write_dispatch ( DBusConnection * connection,

int timeout_milliseconds

)

This function is intended for use with applications that don't want to write a main loop and deal with DBusWatch and DBusTimeout.
An example usage would be:

while (dbus_connection_read_write_dispatch (connection, -1)) ; // empty loop body
In this usage you would normally have set up a filter function to look at each message as it is dispatched. The loop terminates when the last message from the connection (the disconnected signal) is processed.
If there are messages to dispatch, this function will dbus_connection_dispatch() once, and return. If there are no messages to dispatch, this function will block until it can read or write, then read or write, then return.
The way to think of this function is that it either makes some sort of progress, or it blocks.
The return value indicates whether the disconnect message has been processed, NOT whether the connection is connected. This is important because even after disconnecting, you want to process any messages you received prior to the disconnect.

Parameters:

connection the connection

timeout_milliseconds max time to block or -1 for infinite

Returns:
TRUE if the disconnect message has not been processed

Definition at line 2947 of file dbus-connection.c.
References _dbus_connection_read_write_dispatch(), and TRUE.

DBusConnection* dbus_connection_ref ( DBusConnection * connection )

Increments the reference count of a DBusConnection.

Parameters:

connection the connection.

Returns:
the connection.

Definition at line 1746 of file dbus-connection.c.
References _dbus_assert, _dbus_atomic_inc(), _dbus_current_generation, generation, NULL, refcount, and DBusAtomic::value.
Referenced by dbus_connection_get_g_type(), and dbus_g_connection_ref().

dbus_bool_t dbus_connection_register_fallback ( DBusConnection * connection,

const char * path,

const DBusObjectPathVTable * vtable,

void * user_data

)

Registers a fallback handler for a given subsection of the object hierarchy.
The given vtable handles messages at or below the given path. You can use this to establish a default message handling policy for a whole "subdirectory."

Parameters:

connection the connection

path a '/' delimited string of path elements

vtable the virtual table

user_data data to pass to functions in the vtable

Returns:
FALSE if not enough memory

Definition at line 4376 of file dbus-connection.c.
References _dbus_decompose_path(), _dbus_object_tree_register(), dbus_free_string_array(),

DBusConnection [D-BUS low-level public API]

Functions

Detailed Description

Function Documentation

DBusConnection
[D-BUS low-level public API]