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) |
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. |
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.
|
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.
Definition at line 2571 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(). |
|
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.
Definition at line 4146 of file dbus-connection.c. References _dbus_list_append(), dbus_new0, FALSE, filter_list, DBusMessageFilter::free_user_data_function, DBusMessageFilter::function, NULL, DBusMessageFilter::refcount, TRUE, DBusMessageFilter::user_data, and DBusAtomic::value. |
|
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.
Definition at line 4456 of file dbus-connection.c. References _dbus_data_slot_allocator_alloc(), and _DBUS_LOCK_NAME. Referenced by dbus_connection_setup_with_g_main(). |
|
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().
Definition at line 2930 of file dbus-connection.c. References _dbus_assert, _dbus_list_get_first(), dbus_connection_get_dispatch_status(), incoming_messages, message_borrowed, and NULL. |
|
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.
Definition at line 1930 of file dbus-connection.c. References _dbus_current_generation, _dbus_transport_disconnect(), generation, NULL, and transport. Referenced by dbus_bus_get(), and dbus_connection_disconnect(). |
|
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.
Definition at line 1957 of file dbus-connection.c. References dbus_connection_close(). |
|
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.
Definition at line 3435 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_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(). |
|
Blocks until the outgoing message queue is empty.
Definition at line 2800 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(). |
|
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.
Definition at line 4475 of file dbus-connection.c. References _dbus_data_slot_allocator_free(). |
|
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.
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. |
|
Retrieves data previously set with dbus_connection_set_data(). The slot must still be allocated (must not have been freed).
Definition at line 4536 of file dbus-connection.c. References _dbus_data_slot_list_get(), NULL, and slot_list. Referenced by dbus_connection_setup_with_g_main(). |
|
Gets the current state (what we would currently return from dbus_connection_dispatch()) but doesn't actually dispatch any messages.
Definition at line 3347 of file dbus-connection.c. References NULL. Referenced by dbus_connection_borrow_message(), dbus_connection_pop_message(), and dbus_connection_read_write_dispatch(). |
|
Gets whether the connection was authenticated. (Note that if the connection was authenticated then disconnected, this function still returns TRUE)
Definition at line 2002 of file dbus-connection.c. References _dbus_transport_get_is_authenticated(), FALSE, NULL, and transport. |
|
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().
Definition at line 1980 of file dbus-connection.c. |
|
Gets the value set by dbus_connection_set_max_message_size().
Definition at line 4593 of file dbus-connection.c. References _dbus_transport_get_max_message_size(), NULL, and transport. |
|
Gets the value set by dbus_connection_set_max_received_size().
Definition at line 4649 of file dbus-connection.c. References _dbus_transport_get_max_received_size(), NULL, and transport. |
|
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.
Definition at line 4377 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(). |
|
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.
Definition at line 4672 of file dbus-connection.c. References _dbus_counter_get_value(), NULL, and outgoing_counter. |
|
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.
Definition at line 4006 of file dbus-connection.c. References _dbus_transport_get_unix_fd(), FALSE, NULL, and transport. |
|
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.
Definition at line 4067 of file dbus-connection.c. References _dbus_transport_get_is_authenticated(), _dbus_transport_get_unix_process_id(), FALSE, NULL, and transport. |
|
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.
Definition at line 4036 of file dbus-connection.c. References _dbus_transport_get_is_authenticated(), _dbus_transport_get_unix_user(), FALSE, NULL, and transport. |
|
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().
Definition at line 4414 of file dbus-connection.c. References _dbus_decompose_path(), _dbus_object_tree_list_registered_and_unlock(), dbus_free_string_array(), FALSE, NULL, and objects. |
|
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.
Definition at line 1694 of file dbus-connection.c. Referenced by dbus_bus_get(). |
|
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.
Definition at line 1724 of file dbus-connection.c. |
|
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.
Definition at line 3144 of file dbus-connection.c. References dbus_connection_get_dispatch_status(), and NULL. |
|
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.
Definition at line 2102 of file dbus-connection.c. References NULL. |
|
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.
Definition at line 2867 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. |
|
Increments the reference count of a DBusConnection.
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_bus_get(), dbus_connection_get_g_type(), and dbus_g_connection_ref(). |
|
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."
Definition at line 4305 of file dbus-connection.c. References _dbus_decompose_path(), _dbus_object_tree_register(), dbus_free_string_array(), FALSE, NULL, objects, and TRUE. |
|
Registers a handler for a given path in the object hierarchy. The given vtable handles messages sent to exactly the given path.
Definition at line 4262 of file dbus-connection.c. References _dbus_decompose_path(), _dbus_object_tree_register(), dbus_free_string_array(), FALSE, NULL, and objects. Referenced by dbus_g_connection_register_g_object(). |
|
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).
Definition at line 4198 of file dbus-connection.c. References _dbus_list_get_last_link(), _dbus_list_get_prev_link, _dbus_list_remove_link(), _dbus_warn(), DBusList::data, filter_list, DBusMessageFilter::free_user_data_function, DBusMessageFilter::function, NULL, and DBusMessageFilter::user_data. |
|
Used to return a message after peeking at it using dbus_connection_borrow_message(). Only called if message from dbus_connection_borrow_message() was non-NULL.
Definition at line 2975 of file dbus-connection.c. References _dbus_assert, dispatch_acquired, message_borrowed, and NULL. |
|
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.
Definition at line 2334 of file dbus-connection.c. References _dbus_connection_send_and_unlock(), FALSE, and NULL. Referenced by dbus_g_method_return(), dbus_g_method_return_error(), dbus_g_proxy_call_no_reply(), and dbus_g_proxy_send(). |
|
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.
Definition at line 2248 of file dbus-connection.c. References DBusPreallocatedSend::connection, dbus_message_get_interface(), dbus_message_get_member(), dbus_message_get_type(), and NULL. |
|
Queues a message to send, as with dbus_connection_send_message(), but also returns a DBusPendingCall used to receive a reply to the message. If no reply is received in the given timeout_milliseconds, this function expires the pending reply and generates a synthetic error reply (generated in-process, not by the remote application) indicating that a timeout occurred. A DBusPendingCall will see a reply message after any filters, but before any object instances or other handlers. A DBusPendingCall will always see exactly one reply message, unless it's cancelled with dbus_pending_call_cancel(). 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 DBusPendingCall will get confused. Filtering the timeout error is thus considered a bug and will print a warning. If NULL is passed for the pending_return, the DBusPendingCall will still be generated internally, and used to track the message reply timeout. This means a timeout error will occur if no reply arrives, unlike with dbus_connection_send(). 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.
Definition at line 2416 of file dbus-connection.c. References _dbus_list_alloc_link(), _dbus_message_set_serial(), _dbus_pending_call_new(), dbus_message_get_serial(), dbus_message_new_error(), dbus_message_unref(), dbus_pending_call_unref(), FALSE, NULL, DBusPendingCall::reply_serial, DBusPendingCall::timeout_link, and TRUE. Referenced by dbus_connection_send_with_reply_and_block(). |
|
Sends a message and blocks a certain time period while waiting for a reply. This function does not reenter the main loop, i.e. messages other than the reply are queued up but not processed. This function is used to do non-reentrant "method calls." If a normal 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 an error reply is received, it is converted to a DBusError and returned as an error, then the reply message is deleted. If something else goes wrong, result is set to whatever is appropriate, such as DBUS_ERROR_NO_MEMORY or DBUS_ERROR_DISCONNECTED.
Definition at line 2753 of file dbus-connection.c. References _dbus_assert, dbus_connection_send_with_reply(), dbus_message_unref(), dbus_pending_call_block(), dbus_pending_call_steal_reply(), dbus_pending_call_unref(), dbus_set_error_from_message(), FALSE, and NULL. Referenced by dbus_bus_get_unix_user(), dbus_bus_name_has_owner(), dbus_bus_register(), dbus_bus_request_name(), and dbus_bus_start_service_by_name(). |
|
This function sets a global flag for whether dbus_connection_new() will set SIGPIPE behavior to SIG_IGN.
Definition at line 4561 of file dbus-connection.c. References FALSE. |
|
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().
Definition at line 4496 of file dbus-connection.c. References _dbus_data_slot_list_set(), FALSE, NULL, and slot_list. Referenced by dbus_connection_setup_with_g_main(). |
|
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.
Definition at line 3968 of file dbus-connection.c. References dispatch_status_data, dispatch_status_function, free_dispatch_status_data, and NULL. |
|
Set whether _exit() should be called when the connection receives a disconnect signal. The call to _exit() comes after any handlers for the disconnect signal run; handlers can cancel the exit by calling this function. By default, exit_on_disconnect is FALSE; but for message bus connections returned from dbus_bus_get() it will be toggled on by default.
Definition at line 2029 of file dbus-connection.c. References exit_on_disconnect, FALSE, and NULL. Referenced by dbus_bus_get(). |
|
Specifies the maximum size message this connection is allowed to receive. Larger messages will result in disconnecting the connection.
Definition at line 4575 of file dbus-connection.c. References _dbus_transport_set_max_message_size(), NULL, and transport. |
|
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.
Definition at line 4631 of file dbus-connection.c. References _dbus_transport_set_max_received_size(), NULL, and transport. |
|
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.
Definition at line 3867 of file dbus-connection.c. References _dbus_connection_ref_unlocked(), _dbus_timeout_list_set_functions(), _dbus_warn(), dbus_connection_unref(), FALSE, NULL, and timeouts. Referenced by dbus_connection_setup_with_g_main(), and DBusQt::Internal::Integrator::Integrator(). |
|
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.
Definition at line 4104 of file dbus-connection.c. References _dbus_transport_set_unix_user_function(), NULL, and transport. |
|
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().
Definition at line 3926 of file dbus-connection.c. References free_wakeup_main_data, NULL, wakeup_main_data, and wakeup_main_function. Referenced by dbus_connection_setup_with_g_main(), and DBusQt::Internal::Integrator::Integrator(). |
|
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.
Definition at line 3785 of file dbus-connection.c. References _dbus_connection_ref_unlocked(), _dbus_warn(), _dbus_watch_list_set_functions(), dbus_connection_unref(), FALSE, NULL, and watches. Referenced by dbus_connection_setup_with_g_main(), and DBusQt::Internal::Integrator::Integrator(). |
|
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().
Definition at line 3004 of file dbus-connection.c. References _dbus_assert, _dbus_list_pop_first(), dispatch_acquired, incoming_messages, message_borrowed, n_incoming, and NULL. |
|
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.
Definition at line 1884 of file dbus-connection.c. References _dbus_assert, _dbus_atomic_dec(), _dbus_current_generation, generation, NULL, refcount, and DBusAtomic::value. Referenced by _dbus_object_tree_unregister_and_unlock(), dbus_bus_get(), dbus_connection_dispatch(), dbus_connection_get_g_type(), dbus_connection_set_timeout_functions(), dbus_connection_set_watch_functions(), and dbus_g_connection_unref(). |
|
Unregisters the handler registered with exactly the given path. It's a bug to call this function for a path that isn't registered. Can unregister both fallback paths and object paths.
Definition at line 4345 of file dbus-connection.c. References _dbus_decompose_path(), _dbus_object_tree_unregister_and_unlock(), dbus_free_string_array(), FALSE, NULL, objects, and TRUE. |