index.html
Main Page
|
modules.html
Modules
|
namespaces.html
Namespace List
|
hierarchy.html
Class Hierarchy
|
annotated.html
Data Structures
|
dirs.html
Directories
|
files.html
File List
|
namespacemembers.html
Namespace Members
|
functions.html
Data Fields
|
pages.html
Related Pages
DBusConnection
[
group__DBus.html
D-BUS low-level public API
]
Connection to another application.
#_details
More...
Functions
structDBusConnection.html
DBusConnection
*
group__DBusConnection.html#ga1
dbus_connection_open
(const char *address,
structDBusError.html
DBusError
*error)
Gets a connection to a remote address.
#ga1
structDBusConnection.html
DBusConnection
*
group__DBusConnection.html#ga2
dbus_connection_open_private
(const char *address,
structDBusError.html
DBusError
*error)
Opens a new, dedicated connection to a remote address.
#ga2
structDBusConnection.html
DBusConnection
*
group__DBusConnection.html#ga3
dbus_connection_ref
(
structDBusConnection.html
DBusConnection
*connection)
Increments the reference count of a
structDBusConnection.html
DBusConnection
.
#ga3
void
group__DBusConnection.html#ga5
dbus_connection_unref
(
structDBusConnection.html
DBusConnection
*connection)
Decrements the reference count of a
structDBusConnection.html
DBusConnection
, and finalizes it if the count reaches zero.
#ga5
void
group__DBusConnection.html#ga6
dbus_connection_close
(
structDBusConnection.html
DBusConnection
*connection)
Closes the connection, so no further data can be sent or received.
#ga6
void
group__DBusConnection.html#ga7
dbus_connection_disconnect
(
structDBusConnection.html
DBusConnection
*connection)
Alias for
group__DBusConnection.html#ga6
dbus_connection_close()
.
#ga7
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga9
dbus_connection_get_is_connected
(
structDBusConnection.html
DBusConnection
*connection)
Gets whether the connection is currently connected.
#ga9
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga10
dbus_connection_get_is_authenticated
(
structDBusConnection.html
DBusConnection
*connection)
Gets whether the connection was authenticated.
#ga10
void
group__DBusConnection.html#ga11
dbus_connection_set_exit_on_disconnect
(
structDBusConnection.html
DBusConnection
*connection,
group__DBusTypes.html#ga2
dbus_bool_t
exit_on_disconnect)
Set whether _exit() should be called when the connection receives a disconnect signal.
#ga11
structDBusPreallocatedSend.html
DBusPreallocatedSend
*
group__DBusConnection.html#ga13
dbus_connection_preallocate_send
(
structDBusConnection.html
DBusConnection
*connection)
Preallocates resources needed to send a message, allowing the message to be sent without the possibility of memory allocation failure.
#ga13
void
group__DBusConnection.html#ga14
dbus_connection_free_preallocated_send
(
structDBusConnection.html
DBusConnection
*connection,
structDBusPreallocatedSend.html
DBusPreallocatedSend
*preallocated)
Frees preallocated message-sending resources from
group__DBusConnection.html#ga13
dbus_connection_preallocate_send()
.
#ga14
void
group__DBusConnection.html#ga17
dbus_connection_send_preallocated
(
structDBusConnection.html
DBusConnection
*connection,
structDBusPreallocatedSend.html
DBusPreallocatedSend
*preallocated,
structDBusMessage.html
DBusMessage
*message,
group__DBusTypes.html#ga3
dbus_uint32_t
*client_serial)
Sends a message using preallocated resources.
#ga17
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga19
_dbus_connection_send_and_unlock
(
structDBusConnection.html
DBusConnection
*connection,
structDBusMessage.html
DBusMessage
*message,
group__DBusTypes.html#ga3
dbus_uint32_t
*client_serial)
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga20
dbus_connection_send
(
structDBusConnection.html
DBusConnection
*connection,
structDBusMessage.html
DBusMessage
*message,
group__DBusTypes.html#ga3
dbus_uint32_t
*client_serial)
Adds a message to the outgoing message queue.
#ga20
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga22
dbus_connection_send_with_reply
(
structDBusConnection.html
DBusConnection
*connection,
structDBusMessage.html
DBusMessage
*message,
structDBusPendingCall.html
DBusPendingCall
**pending_return, int timeout_milliseconds)
Queues a message to send, as with dbus_connection_send_message(), but also returns a
structDBusPendingCall.html
DBusPendingCall
used to receive a reply to the message.
#ga22
void
group__DBusConnection.html#ga25
_dbus_connection_block_pending_call
(
structDBusPendingCall.html
DBusPendingCall
*pending)
Blocks until a pending call times out or gets a reply.
#ga25
structDBusMessage.html
DBusMessage
*
group__DBusConnection.html#ga26
dbus_connection_send_with_reply_and_block
(
structDBusConnection.html
DBusConnection
*connection,
structDBusMessage.html
DBusMessage
*message, int timeout_milliseconds,
structDBusError.html
DBusError
*error)
Sends a message and blocks a certain time period while waiting for a reply.
#ga26
void
group__DBusConnection.html#ga27
dbus_connection_flush
(
structDBusConnection.html
DBusConnection
*connection)
Blocks until the outgoing message queue is empty.
#ga27
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga28
dbus_connection_read_write_dispatch
(
structDBusConnection.html
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
structDBusWatch.html
DBusWatch
and
structDBusTimeout.html
DBusTimeout
.
#ga28
structDBusMessage.html
DBusMessage
*
group__DBusConnection.html#ga29
dbus_connection_borrow_message
(
structDBusConnection.html
DBusConnection
*connection)
Returns the first-received message from the incoming message queue, leaving it in the queue.
#ga29
void
group__DBusConnection.html#ga30
dbus_connection_return_message
(
structDBusConnection.html
DBusConnection
*connection,
structDBusMessage.html
DBusMessage
*message)
Used to return a message after peeking at it using
group__DBusConnection.html#ga29
dbus_connection_borrow_message()
.
#ga30
void
group__DBusConnection.html#ga31
dbus_connection_steal_borrowed_message
(
structDBusConnection.html
DBusConnection
*connection,
structDBusMessage.html
DBusMessage
*message)
Used to keep a message after peeking at it using
group__DBusConnection.html#ga29
dbus_connection_borrow_message()
.
#ga31
structDBusMessage.html
DBusMessage
*
group__DBusConnection.html#ga35
dbus_connection_pop_message
(
structDBusConnection.html
DBusConnection
*connection)
Returns the first-received message from the incoming message queue, removing it from the queue.
#ga35
DBusDispatchStatus
group__DBusConnection.html#ga37
dbus_connection_get_dispatch_status
(
structDBusConnection.html
DBusConnection
*connection)
Gets the current state (what we would currently return from
group__DBusConnection.html#ga40
dbus_connection_dispatch()
) but doesn't actually dispatch any messages.
#ga37
DBusDispatchStatus
group__DBusConnection.html#ga40
dbus_connection_dispatch
(
structDBusConnection.html
DBusConnection
*connection)
Processes data buffered while handling watches, queueing zero or more incoming messages.
#ga40
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga41
dbus_connection_set_watch_functions
(
structDBusConnection.html
DBusConnection
*connection, DBusAddWatchFunction add_function, DBusRemoveWatchFunction remove_function, DBusWatchToggledFunction toggled_function, void *data,
group__DBusMemory.html#ga8
DBusFreeFunction
free_data_function)
Sets the watch functions for the connection.
#ga41
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga42
dbus_connection_set_timeout_functions
(
structDBusConnection.html
DBusConnection
*connection, DBusAddTimeoutFunction add_function, DBusRemoveTimeoutFunction remove_function, DBusTimeoutToggledFunction toggled_function, void *data,
group__DBusMemory.html#ga8
DBusFreeFunction
free_data_function)
Sets the timeout functions for the connection.
#ga42
void
group__DBusConnection.html#ga43
dbus_connection_set_wakeup_main_function
(
structDBusConnection.html
DBusConnection
*connection, DBusWakeupMainFunction wakeup_main_function, void *data,
group__DBusMemory.html#ga8
DBusFreeFunction
free_data_function)
Sets the mainloop wakeup function for the connection.
#ga43
void
group__DBusConnection.html#ga44
dbus_connection_set_dispatch_status_function
(
structDBusConnection.html
DBusConnection
*connection, DBusDispatchStatusFunction function, void *data,
group__DBusMemory.html#ga8
DBusFreeFunction
free_data_function)
Set a function to be invoked when the dispatch status changes.
#ga44
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga45
dbus_connection_get_unix_fd
(
structDBusConnection.html
DBusConnection
*connection, int *fd)
Get the UNIX file descriptor of the connection, if any.
#ga45
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga46
dbus_connection_get_unix_user
(
structDBusConnection.html
DBusConnection
*connection, unsigned long *uid)
Gets the UNIX user ID of the connection if any.
#ga46
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga47
dbus_connection_get_unix_process_id
(
structDBusConnection.html
DBusConnection
*connection, unsigned long *pid)
Gets the process ID of the connection if any.
#ga47
void
group__DBusConnection.html#ga48
dbus_connection_set_unix_user_function
(
structDBusConnection.html
DBusConnection
*connection, DBusAllowUnixUserFunction function, void *data,
group__DBusMemory.html#ga8
DBusFreeFunction
free_data_function)
Sets a predicate function used to determine whether a given user ID is allowed to connect.
#ga48
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga49
dbus_connection_add_filter
(
structDBusConnection.html
DBusConnection
*connection, DBusHandleMessageFunction function, void *user_data,
group__DBusMemory.html#ga8
DBusFreeFunction
free_data_function)
Adds a message filter.
#ga49
void
group__DBusConnection.html#ga50
dbus_connection_remove_filter
(
structDBusConnection.html
DBusConnection
*connection, DBusHandleMessageFunction function, void *user_data)
Removes a previously-added message filter.
#ga50
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga51
dbus_connection_register_object_path
(
structDBusConnection.html
DBusConnection
*connection, const char *path, const
structDBusObjectPathVTable.html
DBusObjectPathVTable
*vtable, void *user_data)
Registers a handler for a given path in the object hierarchy.
#ga51
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga52
dbus_connection_register_fallback
(
structDBusConnection.html
DBusConnection
*connection, const char *path, const
structDBusObjectPathVTable.html
DBusObjectPathVTable
*vtable, void *user_data)
Registers a fallback handler for a given subsection of the object hierarchy.
#ga52
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga53
dbus_connection_unregister_object_path
(
structDBusConnection.html
DBusConnection
*connection, const char *path)
Unregisters the handler registered with exactly the given path.
#ga53
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga54
dbus_connection_get_object_path_data
(
structDBusConnection.html
DBusConnection
*connection, const char *path, void **data_p)
Gets the user data passed to
group__DBusConnection.html#ga51
dbus_connection_register_object_path()
or
group__DBusConnection.html#ga52
dbus_connection_register_fallback()
.
#ga54
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga55
dbus_connection_list_registered
(
structDBusConnection.html
DBusConnection
*connection, const char *parent_path, char ***child_entries)
Lists the registered fallback handlers and object path handlers at the given parent_path.
#ga55
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga56
dbus_connection_allocate_data_slot
(
group__DBusTypes.html#ga4
dbus_int32_t
*slot_p)
Allocates an integer ID to be used for storing application-specific data on any
structDBusConnection.html
DBusConnection
.
#ga56
void
group__DBusConnection.html#ga57
dbus_connection_free_data_slot
(
group__DBusTypes.html#ga4
dbus_int32_t
*slot_p)
Deallocates a global ID for connection data slots.
#ga57
group__DBusTypes.html#ga2
dbus_bool_t
group__DBusConnection.html#ga58
dbus_connection_set_data
(
structDBusConnection.html
DBusConnection
*connection,
group__DBusTypes.html#ga4
dbus_int32_t
slot, void *data,
group__DBusMemory.html#ga8
DBusFreeFunction
free_data_func)
Stores a pointer on a
structDBusConnection.html
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.
#ga58
void *
group__DBusConnection.html#ga59
dbus_connection_get_data
(
structDBusConnection.html
DBusConnection
*connection,
group__DBusTypes.html#ga4
dbus_int32_t
slot)
Retrieves data previously set with
group__DBusConnection.html#ga58
dbus_connection_set_data()
.
#ga59
void
group__DBusConnection.html#ga60
dbus_connection_set_change_sigpipe
(
group__DBusTypes.html#ga2
dbus_bool_t
will_modify_sigpipe)
This function sets a global flag for whether dbus_connection_new() will set SIGPIPE behavior to SIG_IGN.
#ga60
void
group__DBusConnection.html#ga61
dbus_connection_set_max_message_size
(
structDBusConnection.html
DBusConnection
*connection, long size)
Specifies the maximum size message this connection is allowed to receive.
#ga61
long
group__DBusConnection.html#ga62
dbus_connection_get_max_message_size
(
structDBusConnection.html
DBusConnection
*connection)
Gets the value set by
group__DBusConnection.html#ga61
dbus_connection_set_max_message_size()
.
#ga62
void
group__DBusConnection.html#ga63
dbus_connection_set_max_received_size
(
structDBusConnection.html
DBusConnection
*connection, long size)
Sets the maximum total number of bytes that can be used for all messages received on this connection.
#ga63
long
group__DBusConnection.html#ga64
dbus_connection_get_max_received_size
(
structDBusConnection.html
DBusConnection
*connection)
Gets the value set by
group__DBusConnection.html#ga63
dbus_connection_set_max_received_size()
.
#ga64
long
group__DBusConnection.html#ga65
dbus_connection_get_outgoing_size
(
structDBusConnection.html
DBusConnection
*connection)
Gets the approximate size in bytes of all messages in the outgoing message queue.
#ga65
Detailed Description
Connection to another application.
A
structDBusConnection.html
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
group__DBusBus.html#ga0
dbus_bus_get()
is provided to automatically open a connection to the well-known message buses.
In brief a
structDBusConnection.html
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
group__DBusConnection.html#ga40
dbus_connection_dispatch()
.
group__DBusConnection.html#ga40
dbus_connection_dispatch()
runs any handlers registered for the topmost message in the message queue, then discards the message, then returns.
group__DBusConnection.html#ga37
dbus_connection_get_dispatch_status()
indicates whether messages are currently in the queue that need dispatching.
group__DBusConnection.html#ga44
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,
group__DBusGLib.html#ga14
dbus_connection_setup_with_g_main()
.
If you aren't using these add-on libraries, you have to manually call
group__DBusConnection.html#ga44
dbus_connection_set_dispatch_status_function()
,
group__DBusConnection.html#ga41
dbus_connection_set_watch_functions()
,
group__DBusConnection.html#ga42
dbus_connection_set_timeout_functions()
providing appropriate functions to integrate the connection with your application's main loop.
When you use
group__DBusConnection.html#ga20
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
group__DBusWatch.html#ga5
dbus_watch_handle()
invoked by your main loop, or in
group__DBusConnection.html#ga27
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
structDBusConnection.html
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).
structDBusConnection.html
DBusConnection
has thread locks and drops them when invoking user callbacks, so in general is transparently threadsafe. However,
structDBusMessage.html
DBusMessage
does NOT have thread locks; you must not send the same message to multiple
structDBusConnection.html
DBusConnection
that will be used from different threads.
Function Documentation
void _dbus_connection_block_pending_call
(
structDBusPendingCall.html
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.html#_todo000017
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
dbus-connection_8c-source.html#l02571
2571
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-internals_8h-source.html#l00100
_dbus_assert
,
dbus-connection_8c-source.html#l01034
_dbus_connection_do_iteration_unlocked()
,
dbus-sysdeps_8c-source.html#l01990
_dbus_get_current_time()
,
dbus-connection_8c-source.html#l00875
_dbus_pending_call_complete_and_unlock()
,
dbus-connection_8c-source.html#l02800
dbus_connection_flush()
,
dbus-message_8c-source.html#l01097
dbus_message_unref()
,
dbus-pending-call_8c-source.html#l00265
dbus_pending_call_get_completed()
,
dbus-pending-call_8c-source.html#l00154
dbus_pending_call_ref()
,
dbus-pending-call_8c-source.html#l00170
dbus_pending_call_unref()
,
dbus-timeout_8c-source.html#l00412
dbus_timeout_get_interval()
, and
group__DBusMacros.html#ga4
NULL
.
Referenced by
dbus-pending-call_8c-source.html#l00308
dbus_pending_call_block()
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_add_filter
(
structDBusConnection.html
DBusConnection
*
connection
,
DBusHandleMessageFunction
function
,
void *
user_data
,
group__DBusMemory.html#ga8
DBusFreeFunction
free_data_function
)
Adds a message filter.
Filters are handlers that are run on all incoming messages, prior to the objects registered with
group__DBusConnection.html#ga51
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.html#_todo000021
Todo:
we don't run filters on messages while blocking without entering the main loop, since filters are run as part of
group__DBusConnection.html#ga40
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:
group__DBusMacros.html#ga2
TRUE
on success,
group__DBusMacros.html#ga3
FALSE
if not enough memory.
Definition at line
dbus-connection_8c-source.html#l04146
4146
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-list_8c-source.html#l00249
_dbus_list_append()
,
dbus-memory_8h-source.html#l00042
dbus_new0
,
group__DBusMacros.html#ga3
FALSE
,
dbus-connection_8c-source.html#l00213
filter_list
,
dbus-connection_8c-source.html#l00167
DBusMessageFilter::free_user_data_function
,
dbus-connection_8c-source.html#l00165
DBusMessageFilter::function
,
group__DBusMacros.html#ga4
NULL
,
dbus-connection_8c-source.html#l00164
DBusMessageFilter::refcount
,
group__DBusMacros.html#ga2
TRUE
,
dbus-connection_8c-source.html#l00166
DBusMessageFilter::user_data
, and
dbus-sysdeps_8h-source.html#l00192
DBusAtomic::value
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_allocate_data_slot
(
group__DBusTypes.html#ga4
dbus_int32_t
*
slot_p
)
Allocates an integer ID to be used for storing application-specific data on any
structDBusConnection.html
DBusConnection
.
The allocated ID may then be used with
group__DBusConnection.html#ga58
dbus_connection_set_data()
and
group__DBusConnection.html#ga59
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
structDBusConnection.html
DBusConnection
objects will have a slot with the given integer ID reserved.
Parameters:
slot_p
address of a global variable storing the slot
Returns:
group__DBusMacros.html#ga3
FALSE
on failure (no memory)
Definition at line
dbus-connection_8c-source.html#l04456
4456
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-dataslot_8c-source.html#l00067
_dbus_data_slot_allocator_alloc()
, and
dbus-internals_8h-source.html#l00267
_DBUS_LOCK_NAME
.
Referenced by
dbus-gmain_8c-source.html#l00563
dbus_connection_setup_with_g_main()
.
structDBusMessage.html
DBusMessage
* dbus_connection_borrow_message
(
structDBusConnection.html
DBusConnection
*
connection
)
Returns the first-received message from the incoming message queue, leaving it in the queue.
If the queue is empty, returns
group__DBusMacros.html#ga4
NULL
.
The caller does not own a reference to the returned message, and must either return it using
group__DBusConnection.html#ga30
dbus_connection_return_message()
or keep it after calling
group__DBusConnection.html#ga31
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.
group__DBusConnection.html#ga40
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
group__DBusConnection.html#ga40
dbus_connection_dispatch()
.
Parameters:
connection
the connection.
Returns:
next message in the incoming queue.
Definition at line
dbus-connection_8c-source.html#l02930
2930
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-internals_8h-source.html#l00100
_dbus_assert
,
dbus-list_8c-source.html#l00626
_dbus_list_get_first()
,
dbus-connection_8c-source.html#l03347
dbus_connection_get_dispatch_status()
,
dbus-connection_8c-source.html#l00198
incoming_messages
,
dbus-connection_8c-source.html#l00200
message_borrowed
, and
group__DBusMacros.html#ga4
NULL
.
void dbus_connection_close
(
structDBusConnection.html
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
group__DBusConnection.html#ga44
dbus_connection_set_dispatch_status_function()
, as the disconnect message it generates needs to be dispatched.
Parameters:
connection
the connection.
Definition at line
dbus-connection_8c-source.html#l01930
1930
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-memory_8c-source.html#l00682
_dbus_current_generation
,
dbus-transport_8c-source.html#l00397
_dbus_transport_disconnect()
,
dbus-connection_8c-source.html#l00251
generation
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00209
transport
.
Referenced by
dbus-bus_8c-source.html#l00328
dbus_bus_get()
, and
dbus-connection_8c-source.html#l01957
dbus_connection_disconnect()
.
void dbus_connection_disconnect
(
structDBusConnection.html
DBusConnection
*
connection
)
Alias for
group__DBusConnection.html#ga6
dbus_connection_close()
.
This method is DEPRECATED and will be removed for 1.0. Change your code to use
group__DBusConnection.html#ga6
dbus_connection_close()
instead.
Parameters:
connection
the connection.
deprecated.html#_deprecated000001
Deprecated:
Definition at line
dbus-connection_8c-source.html#l01957
1957
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-connection_8c-source.html#l01930
dbus_connection_close()
.
DBusDispatchStatus dbus_connection_dispatch
(
structDBusConnection.html
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.html#_todo000018
Todo:
some FIXME in here about handling DBUS_HANDLER_RESULT_NEED_MEMORY
todo.html#_todo000018
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
dbus-connection_8c-source.html#l03435
3435
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-internals_8h-source.html#l00112
_dbus_assert_not_reached
,
dbus-connection_8c-source.html#l01258
_dbus_connection_ref_unlocked()
,
dbus-sysdeps_8c-source.html#l02705
_dbus_exit()
,
dbus-hash_8c-source.html#l01186
_dbus_hash_table_lookup_int()
,
dbus-list_8c-source.html#l00556
_dbus_list_clear()
,
dbus-list_8c-source.html#l00734
_dbus_list_copy()
,
dbus-list_8c-source.html#l00796
_dbus_list_foreach()
,
dbus-list_8c-source.html#l00233
_dbus_list_free_link()
,
dbus-list_8c-source.html#l00581
_dbus_list_get_first_link()
,
dbus-list_8h-source.html#l00094
_dbus_list_get_next_link
,
dbus-object-tree_8c-source.html#l00749
_dbus_object_tree_dispatch_and_unlock()
,
dbus-connection_8c-source.html#l00875
_dbus_pending_call_complete_and_unlock()
,
dbus-string_8c-source.html#l01230
_dbus_string_append_printf()
,
dbus-string_8c-source.html#l00261
_dbus_string_free()
,
dbus-string_8c-source.html#l00174
_dbus_string_init()
,
dbus-list_8h-source.html#l00039
DBusList::data
,
dbus-connection_8c-source.html#l01884
dbus_connection_unref()
,
dbus-message_8c-source.html#l02539
dbus_message_get_interface()
,
dbus-message_8c-source.html#l02619
dbus_message_get_member()
,
dbus-message_8c-source.html#l00419
dbus_message_get_reply_serial()
,
dbus-message_8c-source.html#l02819
dbus_message_get_signature()
,
dbus-message_8c-source.html#l01129
dbus_message_get_type()
,
dbus-message_8c-source.html#l02908
dbus_message_is_signal()
,
dbus-message_8c-source.html#l00914
dbus_message_new_error()
,
dbus-message_8c-source.html#l01097
dbus_message_unref()
,
dbus-pending-call_8c-source.html#l00170
dbus_pending_call_unref()
,
dbus-connection_8c-source.html#l00244
exit_on_disconnect
,
dbus-connection_8c-source.html#l00213
filter_list
,
dbus-connection_8c-source.html#l00165
DBusMessageFilter::function
,
group__DBusMacros.html#ga4
NULL
,
dbus-connection_8c-source.html#l00235
objects
,
dbus-connection_8c-source.html#l00217
pending_replies
, and
dbus-connection_8c-source.html#l00166
DBusMessageFilter::user_data
.
Referenced by
dbus-connection_8c-source.html#l02867
dbus_connection_read_write_dispatch()
.
void dbus_connection_flush
(
structDBusConnection.html
DBusConnection
*
connection
)
Blocks until the outgoing message queue is empty.
Parameters:
connection
the connection.
Definition at line
dbus-connection_8c-source.html#l02800
2800
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-connection_8c-source.html#l01034
_dbus_connection_do_iteration_unlocked()
,
dbus-connection_8c-source.html#l00204
n_outgoing
, and
group__DBusMacros.html#ga4
NULL
.
Referenced by
dbus-connection_8c-source.html#l02571
_dbus_connection_block_pending_call()
, and
dbus-glib_8c-source.html#l00047
dbus_g_connection_flush()
.
void dbus_connection_free_data_slot
(
group__DBusTypes.html#ga4
dbus_int32_t
*
slot_p
)
Deallocates a global ID for connection data slots.
group__DBusConnection.html#ga59
dbus_connection_get_data()
and
group__DBusConnection.html#ga58
dbus_connection_set_data()
may no longer be used with this slot. Existing data stored on existing
structDBusConnection.html
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
dbus-connection_8c-source.html#l04475
4475
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-dataslot_8c-source.html#l00161
_dbus_data_slot_allocator_free()
.
void dbus_connection_free_preallocated_send
(
structDBusConnection.html
DBusConnection
*
connection
,
structDBusPreallocatedSend.html
DBusPreallocatedSend
*
preallocated
)
Frees preallocated message-sending resources from
group__DBusConnection.html#ga13
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
dbus-connection_8c-source.html#l02128
2128
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-resources_8c-source.html#l00118
_dbus_counter_unref()
,
dbus-list_8c-source.html#l00233
_dbus_list_free_link()
,
dbus-connection_8c-source.html#l00176
DBusPreallocatedSend::connection
,
dbus-connection_8c-source.html#l00178
DBusPreallocatedSend::counter_link
,
dbus-list_8h-source.html#l00039
DBusList::data
,
dbus-memory_8c-source.html#l00612
dbus_free()
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00177
DBusPreallocatedSend::queue_link
.
void* dbus_connection_get_data
(
structDBusConnection.html
DBusConnection
*
connection
,
group__DBusTypes.html#ga4
dbus_int32_t
slot
)
Retrieves data previously set with
group__DBusConnection.html#ga58
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
group__DBusMacros.html#ga4
NULL
if not found
Definition at line
dbus-connection_8c-source.html#l04536
4536
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-dataslot_8c-source.html#l00295
_dbus_data_slot_list_get()
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00215
slot_list
.
Referenced by
dbus-gmain_8c-source.html#l00563
dbus_connection_setup_with_g_main()
.
DBusDispatchStatus dbus_connection_get_dispatch_status
(
structDBusConnection.html
DBusConnection
*
connection
)
Gets the current state (what we would currently return from
group__DBusConnection.html#ga40
dbus_connection_dispatch()
) but doesn't actually dispatch any messages.
Parameters:
connection
the connection.
Returns:
current dispatch status
Definition at line
dbus-connection_8c-source.html#l03347
3347
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
group__DBusMacros.html#ga4
NULL
.
Referenced by
dbus-connection_8c-source.html#l02930
dbus_connection_borrow_message()
,
dbus-connection_8c-source.html#l03144
dbus_connection_pop_message()
, and
dbus-connection_8c-source.html#l02867
dbus_connection_read_write_dispatch()
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_get_is_authenticated
(
structDBusConnection.html
DBusConnection
*
connection
)
Gets whether the connection was authenticated.
(Note that if the connection was authenticated then disconnected, this function still returns
group__DBusMacros.html#ga2
TRUE
)
Parameters:
connection
the connection
Returns:
group__DBusMacros.html#ga2
TRUE
if the connection was ever authenticated
Definition at line
dbus-connection_8c-source.html#l02002
2002
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-transport_8c-source.html#l00438
_dbus_transport_get_is_authenticated()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00209
transport
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_get_is_connected
(
structDBusConnection.html
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
group__DBusConnection.html#ga6
dbus_connection_close()
.
Parameters:
connection
the connection.
Returns:
group__DBusMacros.html#ga2
TRUE
if the connection is still alive.
Definition at line
dbus-connection_8c-source.html#l01980
1980
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
group__DBusMacros.html#ga3
FALSE
, and
group__DBusMacros.html#ga4
NULL
.
long dbus_connection_get_max_message_size
(
structDBusConnection.html
DBusConnection
*
connection
)
Gets the value set by
group__DBusConnection.html#ga61
dbus_connection_set_max_message_size()
.
Parameters:
connection
the connection
Returns:
the max size of a single message
Definition at line
dbus-connection_8c-source.html#l04593
4593
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-transport_8c-source.html#l00922
_dbus_transport_get_max_message_size()
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00209
transport
.
long dbus_connection_get_max_received_size
(
structDBusConnection.html
DBusConnection
*
connection
)
Gets the value set by
group__DBusConnection.html#ga63
dbus_connection_set_max_received_size()
.
Parameters:
connection
the connection
Returns:
the max size of all live messages
Definition at line
dbus-connection_8c-source.html#l04649
4649
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-transport_8c-source.html#l00952
_dbus_transport_get_max_received_size()
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00209
transport
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_get_object_path_data
(
structDBusConnection.html
DBusConnection
*
connection
,
const char *
path
,
void **
data_p
)
Gets the user data passed to
group__DBusConnection.html#ga51
dbus_connection_register_object_path()
or
group__DBusConnection.html#ga52
dbus_connection_register_fallback()
.
If nothing was registered at this path, the data is filled in with
group__DBusMacros.html#ga4
NULL
.
Parameters:
connection
the connection
path
the path you registered with
data_p
location to store the user data, or
group__DBusMacros.html#ga4
NULL
Returns:
group__DBusMacros.html#ga3
FALSE
if not enough memory
Definition at line
dbus-connection_8c-source.html#l04377
4377
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-object-tree_8c-source.html#l01081
_dbus_decompose_path()
,
dbus-object-tree_8c-source.html#l00917
_dbus_object_tree_get_user_data_unlocked()
,
dbus-memory_8c-source.html#l00650
dbus_free_string_array()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
,
dbus-connection_8c-source.html#l00235
objects
, and
group__DBusMacros.html#ga2
TRUE
.
Referenced by
dbus-gobject_8c-source.html#l01649
dbus_g_connection_lookup_g_object()
.
long dbus_connection_get_outgoing_size
(
structDBusConnection.html
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
dbus-connection_8c-source.html#l04672
4672
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-resources_8c-source.html#l00168
_dbus_counter_get_value()
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00207
outgoing_counter
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_get_unix_fd
(
structDBusConnection.html
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
structDBusWatch.html
DBusWatch
for main loop integration. Not all connections will have a file descriptor. So for adding descriptors to the main loop, use
group__DBusWatch.html#ga0
dbus_watch_get_fd()
and so forth.
Parameters:
connection
the connection
fd
return location for the file descriptor.
Returns:
group__DBusMacros.html#ga2
TRUE
if fd is successfully obtained.
Definition at line
dbus-connection_8c-source.html#l04006
4006
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-transport_8c-source.html#l00665
_dbus_transport_get_unix_fd()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00209
transport
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_get_unix_process_id
(
structDBusConnection.html
DBusConnection
*
connection
,
unsigned long *
pid
)
Gets the process ID of the connection if any.
Returns
group__DBusMacros.html#ga2
TRUE
if the uid is filled in. Always returns
group__DBusMacros.html#ga3
FALSE
prior to authenticating the connection.
Parameters:
connection
the connection
pid
return location for the process ID
Returns:
group__DBusMacros.html#ga2
TRUE
if uid is filled in with a valid process ID
Definition at line
dbus-connection_8c-source.html#l04067
4067
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-transport_8c-source.html#l00438
_dbus_transport_get_is_authenticated()
,
dbus-transport_8c-source.html#l00997
_dbus_transport_get_unix_process_id()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00209
transport
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_get_unix_user
(
structDBusConnection.html
DBusConnection
*
connection
,
unsigned long *
uid
)
Gets the UNIX user ID of the connection if any.
Returns
group__DBusMacros.html#ga2
TRUE
if the uid is filled in. Always returns
group__DBusMacros.html#ga3
FALSE
on non-UNIX platforms. Always returns
group__DBusMacros.html#ga3
FALSE
prior to authenticating the connection.
Parameters:
connection
the connection
uid
return location for the user ID
Returns:
group__DBusMacros.html#ga2
TRUE
if uid is filled in with a valid user ID
Definition at line
dbus-connection_8c-source.html#l04036
4036
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-transport_8c-source.html#l00438
_dbus_transport_get_is_authenticated()
,
dbus-transport_8c-source.html#l00965
_dbus_transport_get_unix_user()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00209
transport
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_list_registered
(
structDBusConnection.html
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
group__DBusMemory.html#ga4
dbus_free_string_array()
.
Parameters:
connection
the connection
parent_path
the path to list the child handlers of
child_entries
returns
group__DBusMacros.html#ga4
NULL
-terminated array of children
Returns:
group__DBusMacros.html#ga3
FALSE
if no memory to allocate the child entries
Definition at line
dbus-connection_8c-source.html#l04414
4414
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-object-tree_8c-source.html#l01081
_dbus_decompose_path()
,
dbus-object-tree_8c-source.html#l01045
_dbus_object_tree_list_registered_and_unlock()
,
dbus-memory_8c-source.html#l00650
dbus_free_string_array()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00235
objects
.
structDBusConnection.html
DBusConnection
* dbus_connection_open
(
const char *
address
,
structDBusError.html
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
group__DBusConnection.html#ga1
dbus_connection_open()
asks to connect to the same server.
Use
group__DBusConnection.html#ga2
dbus_connection_open_private()
to get a dedicated connection not shared with other callers of
group__DBusConnection.html#ga1
dbus_connection_open()
.
If the open fails, the function returns
group__DBusMacros.html#ga4
NULL
, and provides a reason for the failure in the error parameter. Pass
group__DBusMacros.html#ga4
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
group__DBusMacros.html#ga4
NULL
on failure.
Definition at line
dbus-connection_8c-source.html#l01694
1694
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
group__DBusMacros.html#ga4
NULL
, and
group__DBusMacros.html#ga2
TRUE
.
Referenced by
dbus-bus_8c-source.html#l00328
dbus_bus_get()
.
structDBusConnection.html
DBusConnection
* dbus_connection_open_private
(
const char *
address
,
structDBusError.html
DBusError
*
error
)
Opens a new, dedicated connection to a remote address.
Unlike
group__DBusConnection.html#ga1
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
group__DBusMacros.html#ga4
NULL
, and provides a reason for the failure in the error parameter. Pass
group__DBusMacros.html#ga4
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
group__DBusMacros.html#ga4
NULL
on failure.
Definition at line
dbus-connection_8c-source.html#l01724
1724
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
group__DBusMacros.html#ga3
FALSE
, and
group__DBusMacros.html#ga4
NULL
.
structDBusMessage.html
DBusMessage
* dbus_connection_pop_message
(
structDBusConnection.html
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
group__DBusMacros.html#ga4
NULL
.
This function bypasses any message handlers that are registered, and so using it is usually wrong. Instead, let the main loop invoke
group__DBusConnection.html#ga40
dbus_connection_dispatch()
. Popping messages manually is only useful in very simple programs that don't share a
structDBusConnection.html
DBusConnection
with any libraries or other modules.
There is a lock that covers all ways of accessing the incoming message queue, so
group__DBusConnection.html#ga40
dbus_connection_dispatch()
,
group__DBusConnection.html#ga35
dbus_connection_pop_message()
,
group__DBusConnection.html#ga29
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
dbus-connection_8c-source.html#l03144
3144
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-connection_8c-source.html#l03347
dbus_connection_get_dispatch_status()
, and
group__DBusMacros.html#ga4
NULL
.
structDBusPreallocatedSend.html
DBusPreallocatedSend
* dbus_connection_preallocate_send
(
structDBusConnection.html
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
group__DBusMacros.html#ga4
NULL
Definition at line
dbus-connection_8c-source.html#l02102
2102
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
group__DBusMacros.html#ga4
NULL
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_read_write_dispatch
(
structDBusConnection.html
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
structDBusWatch.html
DBusWatch
and
structDBusTimeout.html
DBusTimeout
.
An example usage would be:
while
(
group__DBusConnection.html#ga28
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
group__DBusConnection.html#ga40
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:
group__DBusMacros.html#ga2
TRUE
if the disconnect message has not been processed
Definition at line
dbus-connection_8c-source.html#l02867
2867
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-connection_8c-source.html#l01034
_dbus_connection_do_iteration_unlocked()
,
dbus-connection_8c-source.html#l03435
dbus_connection_dispatch()
,
dbus-connection_8c-source.html#l03347
dbus_connection_get_dispatch_status()
,
dbus-connection_8c-source.html#l00220
disconnect_message_link
,
group__DBusMacros.html#ga3
FALSE
,
dbus-connection_8c-source.html#l00205
n_incoming
, and
group__DBusMacros.html#ga4
NULL
.
structDBusConnection.html
DBusConnection
* dbus_connection_ref
(
structDBusConnection.html
DBusConnection
*
connection
)
Increments the reference count of a
structDBusConnection.html
DBusConnection
.
Parameters:
connection
the connection.
Returns:
the connection.
Definition at line
dbus-connection_8c-source.html#l01746
1746
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-internals_8h-source.html#l00100
_dbus_assert
,
dbus-sysdeps_8c-source.html#l01809
_dbus_atomic_inc()
,
dbus-memory_8c-source.html#l00682
_dbus_current_generation
,
dbus-connection_8c-source.html#l00251
generation
,
group__DBusMacros.html#ga4
NULL
,
dbus-connection_8c-source.html#l00188
refcount
, and
dbus-sysdeps_8h-source.html#l00192
DBusAtomic::value
.
Referenced by
dbus-bus_8c-source.html#l00328
dbus_bus_get()
,
dbus-glib_8c-source.html#l00183
dbus_connection_get_g_type()
, and
dbus-glib_8c-source.html#l00059
dbus_g_connection_ref()
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_register_fallback
(
structDBusConnection.html
DBusConnection
*
connection
,
const char *
path
,
const
structDBusObjectPathVTable.html
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:
group__DBusMacros.html#ga3
FALSE
if not enough memory
Definition at line
dbus-connection_8c-source.html#l04305
4305
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-object-tree_8c-source.html#l01081
_dbus_decompose_path()
,
dbus-object-tree_8c-source.html#l00403
_dbus_object_tree_register()
,
dbus-memory_8c-source.html#l00650
dbus_free_string_array()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
,
dbus-connection_8c-source.html#l00235
objects
, and
group__DBusMacros.html#ga2
TRUE
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_register_object_path
(
structDBusConnection.html
DBusConnection
*
connection
,
const char *
path
,
const
structDBusObjectPathVTable.html
DBusObjectPathVTable
*
vtable
,
void *
user_data
)
Registers a handler for a given path in the object hierarchy.
The given vtable handles messages sent to exactly the given path.
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:
group__DBusMacros.html#ga3
FALSE
if not enough memory
Definition at line
dbus-connection_8c-source.html#l04262
4262
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-object-tree_8c-source.html#l01081
_dbus_decompose_path()
,
dbus-object-tree_8c-source.html#l00403
_dbus_object_tree_register()
,
dbus-memory_8c-source.html#l00650
dbus_free_string_array()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00235
objects
.
Referenced by
dbus-gobject_8c-source.html#l01616
dbus_g_connection_register_g_object()
.
void dbus_connection_remove_filter
(
structDBusConnection.html
DBusConnection
*
connection
,
DBusHandleMessageFunction
function
,
void *
user_data
)
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
function
the handler to remove
user_data
user data for the handler to remove
Definition at line
dbus-connection_8c-source.html#l04198
4198
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-list_8c-source.html#l00594
_dbus_list_get_last_link()
,
dbus-list_8h-source.html#l00095
_dbus_list_get_prev_link
,
dbus-list_8c-source.html#l00541
_dbus_list_remove_link()
,
dbus-internals_8c-source.html#l00203
_dbus_warn()
,
dbus-list_8h-source.html#l00039
DBusList::data
,
dbus-connection_8c-source.html#l00213
filter_list
,
dbus-connection_8c-source.html#l00167
DBusMessageFilter::free_user_data_function
,
dbus-connection_8c-source.html#l00165
DBusMessageFilter::function
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00166
DBusMessageFilter::user_data
.
void dbus_connection_return_message
(
structDBusConnection.html
DBusConnection
*
connection
,
structDBusMessage.html
DBusMessage
*
message
)
Used to return a message after peeking at it using
group__DBusConnection.html#ga29
dbus_connection_borrow_message()
.
Only called if message from
group__DBusConnection.html#ga29
dbus_connection_borrow_message()
was non-
group__DBusMacros.html#ga4
NULL
.
Parameters:
connection
the connection
message
the message from
group__DBusConnection.html#ga29
dbus_connection_borrow_message()
Definition at line
dbus-connection_8c-source.html#l02975
2975
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-internals_8h-source.html#l00100
_dbus_assert
,
dbus-connection_8c-source.html#l00241
dispatch_acquired
,
dbus-connection_8c-source.html#l00200
message_borrowed
, and
group__DBusMacros.html#ga4
NULL
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_send
(
structDBusConnection.html
DBusConnection
*
connection
,
structDBusMessage.html
DBusMessage
*
message
,
group__DBusTypes.html#ga3
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
group__DBusConnection.html#ga27
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
group__DBusMacros.html#ga3
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:
group__DBusMacros.html#ga2
TRUE
on success.
Definition at line
dbus-connection_8c-source.html#l02334
2334
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-connection_8c-source.html#l02292
_dbus_connection_send_and_unlock()
,
group__DBusMacros.html#ga3
FALSE
, and
group__DBusMacros.html#ga4
NULL
.
Referenced by
dbus-gobject_8c-source.html#l01866
dbus_g_method_return()
,
dbus-gobject_8c-source.html#l01915
dbus_g_method_return_error()
,
dbus-gproxy_8c-source.html#l02366
dbus_g_proxy_call_no_reply()
, and
dbus-gproxy_8c-source.html#l02450
dbus_g_proxy_send()
.
void dbus_connection_send_preallocated
(
structDBusConnection.html
DBusConnection
*
connection
,
structDBusPreallocatedSend.html
DBusPreallocatedSend
*
preallocated
,
structDBusMessage.html
DBusMessage
*
message
,
group__DBusTypes.html#ga3
dbus_uint32_t
*
client_serial
)
Sends a message using preallocated resources.
This function cannot fail. It works identically to
group__DBusConnection.html#ga20
dbus_connection_send()
in other respects. Preallocated resources comes from
group__DBusConnection.html#ga13
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
dbus-connection_8c-source.html#l02248
2248
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-connection_8c-source.html#l00176
DBusPreallocatedSend::connection
,
dbus-message_8c-source.html#l02539
dbus_message_get_interface()
,
dbus-message_8c-source.html#l02619
dbus_message_get_member()
,
dbus-message_8c-source.html#l01129
dbus_message_get_type()
, and
group__DBusMacros.html#ga4
NULL
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_send_with_reply
(
structDBusConnection.html
DBusConnection
*
connection
,
structDBusMessage.html
DBusMessage
*
message
,
structDBusPendingCall.html
DBusPendingCall
**
pending_return
,
int
timeout_milliseconds
)
Queues a message to send, as with dbus_connection_send_message(), but also returns a
structDBusPendingCall.html
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
structDBusPendingCall.html
DBusPendingCall
will see a reply message after any filters, but before any object instances or other handlers. A
structDBusPendingCall.html
DBusPendingCall
will always see exactly one reply message, unless it's cancelled with
group__DBusPendingCall.html#ga4
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
structDBusPendingCall.html
DBusPendingCall
will get confused. Filtering the timeout error is thus considered a bug and will print a warning.
If
group__DBusMacros.html#ga4
NULL
is passed for the pending_return, the
structDBusPendingCall.html
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
group__DBusConnection.html#ga20
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.
Parameters:
connection
the connection
message
the message to send
pending_return
return location for a
structDBusPendingCall.html
DBusPendingCall
object, or
group__DBusMacros.html#ga4
NULL
timeout_milliseconds
timeout in milliseconds or -1 for default
Returns:
group__DBusMacros.html#ga2
TRUE
if the message is successfully queued,
group__DBusMacros.html#ga3
FALSE
if no memory.
Definition at line
dbus-connection_8c-source.html#l02416
2416
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-list_8c-source.html#l00221
_dbus_list_alloc_link()
,
dbus-message_8c-source.html#l00162
_dbus_message_set_serial()
,
dbus-pending-call_8c-source.html#l00052
_dbus_pending_call_new()
,
dbus-message_8c-source.html#l00384
dbus_message_get_serial()
,
dbus-message_8c-source.html#l00914
dbus_message_new_error()
,
dbus-message_8c-source.html#l01097
dbus_message_unref()
,
dbus-pending-call_8c-source.html#l00170
dbus_pending_call_unref()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
,
dbus-connection-internal_8h-source.html#l00117
DBusPendingCall::reply_serial
,
dbus-connection-internal_8h-source.html#l00115
DBusPendingCall::timeout_link
, and
group__DBusMacros.html#ga2
TRUE
.
Referenced by
dbus-connection_8c-source.html#l02753
dbus_connection_send_with_reply_and_block()
.
structDBusMessage.html
DBusMessage
* dbus_connection_send_with_reply_and_block
(
structDBusConnection.html
DBusConnection
*
connection
,
structDBusMessage.html
DBusMessage
*
message
,
int
timeout_milliseconds
,
structDBusError.html
DBusError
*
error
)
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,
group__DBusMacros.html#ga4
NULL
is returned and the error is set to DBUS_ERROR_NO_REPLY. If an error reply is received, it is converted to a
structDBusError.html
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.
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
group__DBusMacros.html#ga4
NULL
with an error code if the function fails.
Definition at line
dbus-connection_8c-source.html#l02753
2753
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-internals_8h-source.html#l00100
_dbus_assert
,
dbus-connection_8c-source.html#l02416
dbus_connection_send_with_reply()
,
dbus-message_8c-source.html#l01097
dbus_message_unref()
,
dbus-pending-call_8c-source.html#l00308
dbus_pending_call_block()
,
dbus-pending-call_8c-source.html#l00280
dbus_pending_call_steal_reply()
,
dbus-pending-call_8c-source.html#l00170
dbus_pending_call_unref()
,
dbus-message_8c-source.html#l03074
dbus_set_error_from_message()
,
group__DBusMacros.html#ga3
FALSE
, and
group__DBusMacros.html#ga4
NULL
.
Referenced by
dbus-bus_8c-source.html#l00560
dbus_bus_get_unix_user()
,
dbus-bus_8c-source.html#l00716
dbus_bus_name_has_owner()
,
dbus-bus_8c-source.html#l00428
dbus_bus_register()
,
dbus-bus_8c-source.html#l00641
dbus_bus_request_name()
, and
dbus-bus_8c-source.html#l00785
dbus_bus_start_service_by_name()
.
void dbus_connection_set_change_sigpipe
(
group__DBusTypes.html#ga2
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
group__DBusMacros.html#ga2
TRUE
to allow sigpipe to be set to SIG_IGN
Definition at line
dbus-connection_8c-source.html#l04561
4561
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
group__DBusMacros.html#ga3
FALSE
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_set_data
(
structDBusConnection.html
DBusConnection
*
connection
,
group__DBusTypes.html#ga4
dbus_int32_t
slot
,
void *
data
,
group__DBusMemory.html#ga8
DBusFreeFunction
free_data_func
)
Stores a pointer on a
structDBusConnection.html
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
group__DBusConnection.html#ga56
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:
group__DBusMacros.html#ga2
TRUE
if there was enough memory to store the data
Definition at line
dbus-connection_8c-source.html#l04496
4496
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-dataslot_8c-source.html#l00233
_dbus_data_slot_list_set()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00215
slot_list
.
Referenced by
dbus-gmain_8c-source.html#l00563
dbus_connection_setup_with_g_main()
.
void dbus_connection_set_dispatch_status_function
(
structDBusConnection.html
DBusConnection
*
connection
,
DBusDispatchStatusFunction
function
,
void *
data
,
group__DBusMemory.html#ga8
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
group__DBusConnection.html#ga40
dbus_connection_dispatch()
needs to be called to process incoming messages. However,
group__DBusConnection.html#ga40
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
dbus-connection_8c-source.html#l03968
3968
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-connection_8c-source.html#l00227
dispatch_status_data
,
dbus-connection_8c-source.html#l00226
dispatch_status_function
,
dbus-connection_8c-source.html#l00228
free_dispatch_status_data
, and
group__DBusMacros.html#ga4
NULL
.
void dbus_connection_set_exit_on_disconnect
(
structDBusConnection.html
DBusConnection
*
connection
,
group__DBusTypes.html#ga2
dbus_bool_t
exit_on_disconnect
)
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
group__DBusMacros.html#ga3
FALSE
; but for message bus connections returned from
group__DBusBus.html#ga0
dbus_bus_get()
it will be toggled on by default.
Parameters:
connection
the connection
exit_on_disconnect
group__DBusMacros.html#ga2
TRUE
if _exit() should be called after a disconnect signal
Definition at line
dbus-connection_8c-source.html#l02029
2029
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-connection_8c-source.html#l00244
exit_on_disconnect
,
group__DBusMacros.html#ga3
FALSE
, and
group__DBusMacros.html#ga4
NULL
.
Referenced by
dbus-bus_8c-source.html#l00328
dbus_bus_get()
.
void dbus_connection_set_max_message_size
(
structDBusConnection.html
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
structDBusConnection.html
DBusConnection
size
maximum message size the connection can receive, in bytes
Definition at line
dbus-connection_8c-source.html#l04575
4575
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-transport_8c-source.html#l00909
_dbus_transport_set_max_message_size()
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00209
transport
.
void dbus_connection_set_max_received_size
(
structDBusConnection.html
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
dbus-connection_8c-source.html#l04631
4631
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-transport_8c-source.html#l00934
_dbus_transport_set_max_received_size()
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00209
transport
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_set_timeout_functions
(
structDBusConnection.html
DBusConnection
*
connection
,
DBusAddTimeoutFunction
add_function
,
DBusRemoveTimeoutFunction
remove_function
,
DBusTimeoutToggledFunction
toggled_function
,
void *
data
,
group__DBusMemory.html#ga8
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
group__DBusTimeout.html#ga4
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
group__DBusTimeout.html#ga4
dbus_timeout_get_enabled()
every time anyway. Whenever a timeout is toggled, its interval may change.
The
structDBusTimeout.html
DBusTimeout
can be queried for the timer interval using
group__DBusTimeout.html#ga0
dbus_timeout_get_interval()
.
group__DBusTimeout.html#ga3
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:
group__DBusMacros.html#ga3
FALSE
on failure (no memory)
Definition at line
dbus-connection_8c-source.html#l03867
3867
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-connection_8c-source.html#l01258
_dbus_connection_ref_unlocked()
,
dbus-timeout_8c-source.html#l00238
_dbus_timeout_list_set_functions()
,
dbus-internals_8c-source.html#l00203
_dbus_warn()
,
dbus-connection_8c-source.html#l01884
dbus_connection_unref()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00211
timeouts
.
Referenced by
dbus-gmain_8c-source.html#l00563
dbus_connection_setup_with_g_main()
, and
integrator_8cpp-source.html#l00122
DBusQt::Internal::Integrator::Integrator()
.
void dbus_connection_set_unix_user_function
(
structDBusConnection.html
DBusConnection
*
connection
,
DBusAllowUnixUserFunction
function
,
void *
data
,
group__DBusMemory.html#ga8
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
group__DBusMacros.html#ga2
TRUE
, the connection is allowed to proceed, otherwise the connection is disconnected.
If the function is set to
group__DBusMacros.html#ga4
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
dbus-connection_8c-source.html#l04104
4104
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-transport_8c-source.html#l01032
_dbus_transport_set_unix_user_function()
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00209
transport
.
void dbus_connection_set_wakeup_main_function
(
structDBusConnection.html
DBusConnection
*
connection
,
DBusWakeupMainFunction
wakeup_main_function
,
void *
data
,
group__DBusMemory.html#ga8
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
dbus-connection_8c-source.html#l03926
3926
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-connection_8c-source.html#l00224
free_wakeup_main_data
,
group__DBusMacros.html#ga4
NULL
,
dbus-connection_8c-source.html#l00223
wakeup_main_data
, and
dbus-connection_8c-source.html#l00222
wakeup_main_function
.
Referenced by
dbus-gmain_8c-source.html#l00563
dbus_connection_setup_with_g_main()
, and
integrator_8cpp-source.html#l00122
DBusQt::Internal::Integrator::Integrator()
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_set_watch_functions
(
structDBusConnection.html
DBusConnection
*
connection
,
DBusAddWatchFunction
add_function
,
DBusRemoveWatchFunction
remove_function
,
DBusWatchToggledFunction
toggled_function
,
void *
data
,
group__DBusMemory.html#ga8
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
group__DBusWatch.html#ga4
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
group__DBusWatch.html#ga4
dbus_watch_get_enabled()
every time anyway.
The
structDBusWatch.html
DBusWatch
can be queried for the file descriptor to watch using
group__DBusWatch.html#ga0
dbus_watch_get_fd()
, and for the events to watch for using
group__DBusWatch.html#ga1
dbus_watch_get_flags()
. The flags returned by
group__DBusWatch.html#ga1
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,
group__DBusWatch.html#ga5
dbus_watch_handle()
should be called to notify the connection of the file descriptor's condition.
group__DBusWatch.html#ga5
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
structDBusWatch.html
DBusWatch
after it has been passed to remove_function.
If
group__DBusMacros.html#ga3
FALSE
is returned due to lack of memory, the failure may be due to a
group__DBusMacros.html#ga3
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
group__DBusMacros.html#ga3
FALSE
is returned the net result should be that
group__DBusConnection.html#ga41
dbus_connection_set_watch_functions()
has no effect, but the add_function and remove_function may have been called.
todo.html#_todo000020
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:
group__DBusMacros.html#ga3
FALSE
on failure (no memory)
Definition at line
dbus-connection_8c-source.html#l03785
3785
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-connection_8c-source.html#l01258
_dbus_connection_ref_unlocked()
,
dbus-internals_8c-source.html#l00203
_dbus_warn()
,
dbus-watch_8c-source.html#l00253
_dbus_watch_list_set_functions()
,
dbus-connection_8c-source.html#l01884
dbus_connection_unref()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
, and
dbus-connection_8c-source.html#l00210
watches
.
Referenced by
dbus-gmain_8c-source.html#l00563
dbus_connection_setup_with_g_main()
, and
integrator_8cpp-source.html#l00122
DBusQt::Internal::Integrator::Integrator()
.
void dbus_connection_steal_borrowed_message
(
structDBusConnection.html
DBusConnection
*
connection
,
structDBusMessage.html
DBusMessage
*
message
)
Used to keep a message after peeking at it using
group__DBusConnection.html#ga29
dbus_connection_borrow_message()
.
Before using this function, see the caveats/warnings in the documentation for
group__DBusConnection.html#ga35
dbus_connection_pop_message()
.
Parameters:
connection
the connection
message
the message from
group__DBusConnection.html#ga29
dbus_connection_borrow_message()
Definition at line
dbus-connection_8c-source.html#l03004
3004
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-internals_8h-source.html#l00100
_dbus_assert
,
dbus-list_8c-source.html#l00663
_dbus_list_pop_first()
,
dbus-connection_8c-source.html#l00241
dispatch_acquired
,
dbus-connection_8c-source.html#l00198
incoming_messages
,
dbus-connection_8c-source.html#l00200
message_borrowed
,
dbus-connection_8c-source.html#l00205
n_incoming
, and
group__DBusMacros.html#ga4
NULL
.
void dbus_connection_unref
(
structDBusConnection.html
DBusConnection
*
connection
)
Decrements the reference count of a
structDBusConnection.html
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.html#_todo000016
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
dbus-connection_8c-source.html#l01884
1884
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-internals_8h-source.html#l00100
_dbus_assert
,
dbus-sysdeps_8c-source.html#l01832
_dbus_atomic_dec()
,
dbus-memory_8c-source.html#l00682
_dbus_current_generation
,
dbus-connection_8c-source.html#l00251
generation
,
group__DBusMacros.html#ga4
NULL
,
dbus-connection_8c-source.html#l00188
refcount
, and
dbus-sysdeps_8h-source.html#l00192
DBusAtomic::value
.
Referenced by
dbus-object-tree_8c-source.html#l00446
_dbus_object_tree_unregister_and_unlock()
,
dbus-bus_8c-source.html#l00328
dbus_bus_get()
,
dbus-connection_8c-source.html#l03435
dbus_connection_dispatch()
,
dbus-glib_8c-source.html#l00183
dbus_connection_get_g_type()
,
dbus-connection_8c-source.html#l03867
dbus_connection_set_timeout_functions()
,
dbus-connection_8c-source.html#l03785
dbus_connection_set_watch_functions()
, and
dbus-glib_8c-source.html#l00075
dbus_g_connection_unref()
.
group__DBusTypes.html#ga2
dbus_bool_t
dbus_connection_unregister_object_path
(
structDBusConnection.html
DBusConnection
*
connection
,
const char *
path
)
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.
Parameters:
connection
the connection
path
a '/' delimited string of path elements
Returns:
group__DBusMacros.html#ga3
FALSE
if not enough memory
Definition at line
dbus-connection_8c-source.html#l04345
4345
of file
dbus-connection_8c-source.html
dbus-connection.c
.
References
dbus-object-tree_8c-source.html#l01081
_dbus_decompose_path()
,
dbus-object-tree_8c-source.html#l00446
_dbus_object_tree_unregister_and_unlock()
,
dbus-memory_8c-source.html#l00650
dbus_free_string_array()
,
group__DBusMacros.html#ga3
FALSE
,
group__DBusMacros.html#ga4
NULL
,
dbus-connection_8c-source.html#l00235
objects
, and
group__DBusMacros.html#ga2
TRUE
.
Generated on Tue Sep 13 01:28:08 2005 for D-BUS by
http://www.doxygen.org/index.html
doxygen
1.4.4
