DBusConnection for c

dbus的C API

D-Bus 1.13.10

dbus的C API

Data Structures | Typedefs | Enumerations | Functions

DBusConnection

Connection to another application. More...

Data Structures
struct	DBusObjectPathVTable
	Virtual table that must be implemented to handle a portion of the object path hierarchy. More... 必须实现以处理部分对象路径层次结构的虚拟表使用dbus_connection_register_object_path（）或dbus_connection_register_fallback（）将vtable附加到特定路径。

	struct DBusObjectPathVTable { DBusObjectPathUnregisterFunction unregister_function; //< Function to unregister this handler / DBusObjectPathMessageFunction message_function; // < Function to handle messages / void ( dbus_internal_pad1) (void ); /< Reserved for future expansion / void ( dbus_internal_pad2) (void ); /< Reserved for future expansion / void ( dbus_internal_pad3) (void ); /< Reserved for future expansion / void ( dbus_internal_pad4) (void ); /< Reserved for future expansion / };

Typedefs
typedef struct DBusPreallocatedSend	DBusPreallocatedSend
	Opaque type representing preallocated resources so a message can be sent without further memory allocation. More... 代表预分配资源的不透明类型，因此无需进一步分配内存即可发送消息

typedef struct DBusConnection	DBusConnection
	Opaque type representing a connection to a remote application and associated incoming/outgoing message queues. More... 不透明类型，表示与远程应用程序和关联的传入/传出消息队列的连接

typedef struct DBusObjectPathVTable	DBusObjectPathVTable
	Set of functions that must be implemented to handle messages sent to a particular object path. More...

typedef dbus_bool_t(*	DBusAddWatchFunction) (DBusWatch watch, void data)
	Called when libdbus needs a new watch to be monitored by the main loop. More...

typedef void(*	DBusWatchToggledFunction) (DBusWatch watch, void data)
	Called when dbus_watch_get_enabled() may return a different value than it did before. More...

typedef void(*	DBusRemoveWatchFunction) (DBusWatch watch, void data)
	Called when libdbus no longer needs a watch to be monitored by the main loop. More...

typedef dbus_bool_t(*	DBusAddTimeoutFunction) (DBusTimeout timeout, void data)
	Called when libdbus needs a new timeout to be monitored by the main loop. More...

typedef void(*	DBusTimeoutToggledFunction) (DBusTimeout timeout, void data)
	Called when dbus_timeout_get_enabled() may return a different value than it did before. More...

typedef void(*	DBusRemoveTimeoutFunction) (DBusTimeout timeout, void data)
	Called when libdbus no longer needs a timeout to be monitored by the main loop. More...

typedef void(*	DBusDispatchStatusFunction) (DBusConnection connection, DBusDispatchStatus new_status, void data)
	Called when the return value of dbus_connection_get_dispatch_status() may have changed. More...

typedef void(*	DBusWakeupMainFunction) (void *data)
	Called when the main loop's thread should be notified that there's now work to do. More... 当主循环的线程应该被通知有工作要做时调用。

typedef dbus_bool_t(*	DBusAllowUnixUserFunction) (DBusConnection connection, unsigned long uid, void data)
	Called during authentication to check whether the given UNIX user ID is allowed to connect, if the client tried to auth as a UNIX user ID. More... 在身份验证期间调用，以检查给定的UNIX用户ID是否允许连接（如果客户端尝试作为UNIX用户ID进行身份验证）

typedef dbus_bool_t(*	DBusAllowWindowsUserFunction) (DBusConnection connection, const char user_sid, void *data)
	Called during authentication to check whether the given Windows user ID is allowed to connect, if the client tried to auth as a Windows user ID. More...

typedef void(*	DBusPendingCallNotifyFunction) (DBusPendingCall pending, void user_data)
	Called when a pending call now has a reply available. More... 当挂起的调用现在有一个可用的应答时调用

typedef DBusHandlerResult(*	DBusHandleMessageFunction) (DBusConnection connection, DBusMessage message, void *user_data)
	Called when a message needs to be handled. More...

typedef void(*	DBusObjectPathUnregisterFunction) (DBusConnection connection, void user_data)
	Called when a DBusObjectPathVTable is unregistered (or its connection is freed). More...

typedef DBusHandlerResult(*	DBusObjectPathMessageFunction) (DBusConnection connection, DBusMessage message, void *user_data)
	Called when a message is sent to a registered object path. More...

Enumerations
enum	DBusWatchFlags { DBUS_WATCH_READABLE = 1 << 0, DBUS_WATCH_WRITABLE = 1 << 1, DBUS_WATCH_ERROR = 1 << 2, DBUS_WATCH_HANGUP = 1 << 3 }
	Indicates the status of a DBusWatch. More...

enum	DBusDispatchStatus { DBUS_DISPATCH_DATA_REMAINS, DBUS_DISPATCH_COMPLETE, DBUS_DISPATCH_NEED_MEMORY }
	Indicates the status of incoming data on a DBusConnection. More... 指示DBusConnection上传入数据的状态.这确定是否需要调用dbus_connection_dispatch（）。

枚举器
DBUS_WATCH_READABLE	就像在POLLIN中一样。
DBUS_WATCH_WRITABLE	就像在POLLOUT中一样。
DBUS_WATCH_ERROR	就像在POLLERR中一样（不能监视它，但是可以以传递给dbus_watch_handle（）的当前状态存在）。
DBUS_WATCH_HANGUP	就像在POLLHUP中一样（无法监视它，但是可以以传递给dbus_watch_handle（）的当前状态存在）。

枚举器
DBUS_DISPATCH_DATA_REMAINS	有更多数据可能转换为消息。
DBUS_DISPATCH_COMPLETE	当前所有可用的数据均已处理。
DBUS_DISPATCH_NEED_MEMORY	需要更多内存才能继续。

Functions
DBusConnection *	dbus_connection_open (const char address, DBusError error)
	Gets a connection to a remote address. More...

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

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

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

void	dbus_connection_close (DBusConnection *connection)
	Closes a private connection, so no further data can be sent or received. More...

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

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

dbus_bool_t	dbus_connection_get_is_anonymous (DBusConnection *connection)
	Gets whether the connection is not authenticated as a specific user. More...

char *	dbus_connection_get_server_id (DBusConnection *connection)
	Gets the ID of the server address we are authenticated to, if this connection is on the client side. More...

dbus_bool_t	dbus_connection_can_send_type (DBusConnection *connection, int type)
	Tests whether a certain type can be send via the connection. More...

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. More...

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. More...

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

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

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

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(), but also returns a DBusPendingCall used to receive a reply to the message. More...

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. More...

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

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. More...

dbus_bool_t	dbus_connection_read_write (DBusConnection *connection, int timeout_milliseconds)
	This function is intended for use with applications that don't want to write a main loop and deal with DBusWatch and DBusTimeout. More...

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

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

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

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

DBusDispatchStatus	dbus_connection_get_dispatch_status (DBusConnection *connection)
	Gets the current state of the incoming message queue. More...

DBusDispatchStatus	dbus_connection_dispatch (DBusConnection *connection)
	Processes any incoming data. More...

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. More...

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. More...

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. More...

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. More...

dbus_bool_t	dbus_connection_get_unix_fd (DBusConnection connection, int fd)
	Get the UNIX file descriptor of the connection, if any. More...

dbus_bool_t	dbus_connection_get_socket (DBusConnection connection, int fd)
	Gets the underlying Windows or UNIX socket file descriptor of the connection, if any. More...

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

dbus_bool_t	dbus_connection_get_unix_process_id (DBusConnection connection, unsigned long pid)
	Gets the process ID of the connection if any. More...

dbus_bool_t	dbus_connection_get_adt_audit_session_data (DBusConnection connection, void data, dbus_int32_t data_size)
	Gets the ADT audit data of the connection if any. More...

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. More...

dbus_bool_t	_dbus_connection_get_linux_security_label (DBusConnection connection, char *label_p)

DBusCredentials *	_dbus_connection_get_credentials (DBusConnection *connection)

dbus_bool_t	dbus_connection_get_windows_user (DBusConnection connection, char *windows_sid_p)
	Gets the Windows user SID of the connection if known. More...

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

void	dbus_connection_set_allow_anonymous (DBusConnection *connection, dbus_bool_t value)
	This function must be called on the server side of a connection when the connection is first seen in the DBusNewConnectionFunction. More...

void	dbus_connection_set_route_peer_messages (DBusConnection *connection, dbus_bool_t value)
	Normally DBusConnection automatically handles all messages to the org.freedesktop.DBus.Peer interface. More...

dbus_bool_t	dbus_connection_add_filter (DBusConnection connection, DBusHandleMessageFunction function, void user_data, DBusFreeFunction free_data_function)
	Adds a message filter. More...

void	dbus_connection_remove_filter (DBusConnection connection, DBusHandleMessageFunction function, void user_data)
	Removes a previously-added message filter. More...

dbus_bool_t	dbus_connection_try_register_object_path (DBusConnection connection, const char path, const DBusObjectPathVTable vtable, void user_data, DBusError *error)
	Registers a handler for a given path in the object hierarchy. More...

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. More...

dbus_bool_t	dbus_connection_try_register_fallback (DBusConnection connection, const char path, const DBusObjectPathVTable vtable, void user_data, DBusError *error)
	Registers a fallback handler for a given subsection of the object hierarchy. More...

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. More...

dbus_bool_t	dbus_connection_unregister_object_path (DBusConnection connection, const char path)
	Unregisters the handler registered with exactly the given path. More...

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(). More...

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. More...

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. More...

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

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. More...

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

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. More...

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

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

void	dbus_connection_set_max_message_unix_fds (DBusConnection *connection, long n)
	Specifies the maximum number of unix fds a message on this connection is allowed to receive. More...

long	dbus_connection_get_max_message_unix_fds (DBusConnection *connection)
	Gets the value set by dbus_connection_set_max_message_unix_fds(). More...

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. More...

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

void	dbus_connection_set_max_received_unix_fds (DBusConnection *connection, long n)
	Sets the maximum total number of unix fds that can be used for all messages received on this connection. More...

long	dbus_connection_get_max_received_unix_fds (DBusConnection *connection)
	Gets the value set by dbus_connection_set_max_received_unix_fds(). More...

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

long	dbus_connection_get_outgoing_unix_fds (DBusConnection *connection)
	Gets the approximate number of uni fds of all messages in the outgoing message queue. More...

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

Detailed Description

Connection to another application.

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

DBusConnection表示到另一个应用程序的连接。可以通过此连接发送和接收消息。另一个应用程序可能是消息总线；为了方便起见，提供了函数dbus_bus_get()来自动打开到已知消息总线的连接。

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.

简而言之，DBusConnection是与某些消息传输机制（例如套接字）关联的消息队列。该连接维护传入消息队列和传出消息队列。

Several functions use the following terms:

read means to fill the incoming message queue by reading from the socket
write means to drain the outgoing queue by writing to the socket
dispatch means to drain the incoming queue by invoking application-provided message handlers

The function dbus_connection_read_write_dispatch() for example does all three of these things, offering a simple alternative to a main loop.

In an application with a main loop, the read/write/dispatch operations are usually separate.

The connection provides DBusWatch and DBusTimeout objects to the main loop. These are used to know when reading, writing, or dispatching should be performed.

Incoming messages are 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, but want to process messages asynchronously, you must 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. This can be tricky to get right; main loops are not simple.

If you don't need to be asynchronous, you can ignore DBusWatch, DBusTimeout, and dbus_connection_dispatch(). Instead, dbus_connection_read_write_dispatch() can be used.

Or, in very simple applications, dbus_connection_pop_message() may be all you need, allowing you to avoid setting up any handler functions (see dbus_connection_add_filter(), dbus_connection_register_object_path() for more on handlers).

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).

After calling dbus_threads_init(), 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 if those connections will be used from different threads, for example.

Also, if you dispatch or pop messages from multiple threads, it may work in the sense that it won't crash, but it's tough to imagine sane results; it will be completely unpredictable which messages go to which threads.

It's recommended to dispatch from a single thread.

The most useful function to call from multiple threads at once is dbus_connection_send_with_reply_and_block(). That is, multiple threads can make method calls at the same time.

If you aren't using threads, you can use a main loop and dbus_pending_call_set_notify() to achieve a similar result.

Typedef Documentation

◆ DBusAddTimeoutFunction

typedef dbus_bool_t(* DBusAddTimeoutFunction) (DBusTimeout *timeout, void *data)

Called when libdbus needs a new timeout to be monitored by the main loop.

Returns FALSE if it lacks enough memory to add the watch. Set by dbus_connection_set_timeout_functions() or dbus_server_set_timeout_functions().

Definition at line 111 of file dbus-connection.h.

◆ DBusAddWatchFunction

typedef dbus_bool_t(* DBusAddWatchFunction) (DBusWatch *watch, void *data)

Called when libdbus needs a new watch to be monitored by the main loop.

Returns FALSE if it lacks enough memory to add the watch. Set by dbus_connection_set_watch_functions() or dbus_server_set_watch_functions().

Definition at line 92 of file dbus-connection.h.

◆ DBusAllowUnixUserFunction

typedef dbus_bool_t(* DBusAllowUnixUserFunction) (DBusConnection *connection, unsigned long uid, void *data)

Called during authentication to check whether the given UNIX user ID is allowed to connect, if the client tried to auth as a UNIX user ID.

Normally on Windows this would never happen. Set with dbus_connection_set_unix_user_function().

Definition at line 144 of file dbus-connection.h.

◆ DBusAllowWindowsUserFunction

typedef dbus_bool_t(* DBusAllowWindowsUserFunction) (DBusConnection *connection, const char *user_sid, void *data)

Called during authentication to check whether the given Windows user ID is allowed to connect, if the client tried to auth as a Windows user ID.

Normally on UNIX this would never happen. Set with dbus_connection_set_windows_user_function().

Definition at line 154 of file dbus-connection.h.

◆ DBusConnection

typedef struct DBusConnection DBusConnection

Opaque type representing a connection to a remote application and associated incoming/outgoing message queues.

Definition at line 52 of file dbus-connection.h.

◆ DBusDispatchStatusFunction

typedef void(* DBusDispatchStatusFunction) (DBusConnection *connection, DBusDispatchStatus new_status, void *data)

Called when the return value of dbus_connection_get_dispatch_status() may have changed.

Set with dbus_connection_set_dispatch_status_function().

Definition at line 129 of file dbus-connection.h.

◆ DBusHandleMessageFunction

typedef DBusHandlerResult(* DBusHandleMessageFunction) (DBusConnection *connection, DBusMessage *message, void *user_data)

Called when a message needs to be handled.

The result indicates whether or not more handlers should be run. Set with dbus_connection_add_filter().

Definition at line 170 of file dbus-connection.h.

◆ DBusObjectPathMessageFunction

typedef DBusHandlerResult(* DBusObjectPathMessageFunction) (DBusConnection *connection, DBusMessage *message, void *user_data)

Called when a message is sent to a registered object path.

Found in DBusObjectPathVTable which is registered with dbus_connection_register_object_path() or dbus_connection_register_fallback().

Definition at line 375 of file dbus-connection.h.

◆ DBusObjectPathUnregisterFunction

typedef void(* DBusObjectPathUnregisterFunction) (DBusConnection *connection, void *user_data)

Called when a DBusObjectPathVTable is unregistered (or its connection is freed).

Found in DBusObjectPathVTable.

Definition at line 368 of file dbus-connection.h.

◆ DBusObjectPathVTable

typedef struct DBusObjectPathVTable DBusObjectPathVTable

Set of functions that must be implemented to handle messages sent to a particular object path.

Definition at line 54 of file dbus-connection.h.

◆ DBusPendingCallNotifyFunction

typedef void(* DBusPendingCallNotifyFunction) (DBusPendingCall *pending, void *user_data)

Called when a pending call now has a reply available.

Set with dbus_pending_call_set_notify().

Definition at line 163 of file dbus-connection.h.

◆ DBusPreallocatedSend

typedef struct DBusPreallocatedSend DBusPreallocatedSend

Opaque type representing preallocated resources so a message can be sent without further memory allocation.

Definition at line 48 of file dbus-connection.h.

◆ DBusRemoveTimeoutFunction

typedef void(* DBusRemoveTimeoutFunction) (DBusTimeout *timeout, void *data)

Called when libdbus no longer needs a timeout to be monitored by the main loop.

Set by dbus_connection_set_timeout_functions() or dbus_server_set_timeout_functions().

Definition at line 124 of file dbus-connection.h.

◆ DBusRemoveWatchFunction

typedef void(* DBusRemoveWatchFunction) (DBusWatch *watch, void *data)

Called when libdbus no longer needs a watch to be monitored by the main loop.

Set by dbus_connection_set_watch_functions() or dbus_server_set_watch_functions().

Definition at line 104 of file dbus-connection.h.

◆ DBusTimeoutToggledFunction

typedef void(* DBusTimeoutToggledFunction) (DBusTimeout *timeout, void *data)

Called when dbus_timeout_get_enabled() may return a different value than it did before.

Set by dbus_connection_set_timeout_functions() or dbus_server_set_timeout_functions().

Definition at line 118 of file dbus-connection.h.

◆ DBusWakeupMainFunction

typedef void(* DBusWakeupMainFunction) (void *data)

Called when the main loop's thread should be notified that there's now work to do.

Set with dbus_connection_set_wakeup_main_function().

Definition at line 136 of file dbus-connection.h.

◆ DBusWatchToggledFunction

typedef void(* DBusWatchToggledFunction) (DBusWatch *watch, void *data)

Called when dbus_watch_get_enabled() may return a different value than it did before.

Set by dbus_connection_set_watch_functions() or dbus_server_set_watch_functions().

Definition at line 98 of file dbus-connection.h.

Enumeration Type Documentation

◆ DBusDispatchStatus

enum DBusDispatchStatus

Indicates the status of incoming data on a DBusConnection.

This determines whether dbus_connection_dispatch() needs to be called.

Enumerator
DBUS_DISPATCH_DATA_REMAINS	There is more data to potentially convert to messages.
DBUS_DISPATCH_COMPLETE	All currently available data has been processed.
DBUS_DISPATCH_NEED_MEMORY	More memory is needed to continue.

Definition at line 80 of file dbus-connection.h.

◆ DBusWatchFlags

enum DBusWatchFlags

Indicates the status of a DBusWatch.

Enumerator
DBUS_WATCH_READABLE	As in POLLIN.
DBUS_WATCH_WRITABLE	As in POLLOUT.
DBUS_WATCH_ERROR	As in POLLERR (can't watch for this, but can be present in current state passed to dbus_watch_handle()).
DBUS_WATCH_HANGUP	As in POLLHUP (can't watch for it, but can be present in current state passed to dbus_watch_handle()).

Definition at line 59 of file dbus-connection.h.

Function Documentation

◆ dbus_connection_add_filter()

(	DBusConnection *	connection,
	DBusHandleMessageFunction	function,
	void *	user_data,
	DBusFreeFunction	free_data_function
)

Adds a message filter.

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

过滤器是在使用dbus_connection_register_object_path（）注册对象之前对所有传入消息运行的处理程序。过滤器按添加顺序运行。同一个处理程序可以多次添加为筛选器，在这种情况下，它将多次运行。在过滤器回调中添加的过滤器将不会处理在正在处理的消息。

Todo:

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

我们在阻塞消息时不会在不进入主循环的情况下运行过滤器，因为过滤器是作为dbus_connection_dispatch（）的一部分运行的。这可能是一个特性，因为过滤器可以创建任意的可重入性。但如果你因为某种原因试图过滤METHOD_RETURN，那就太糟糕了。
Parameters

connection the connection

function 处理消息的函数

user_data 传递给函数的用户数据

free_data_function 用于释放用户数据的函数
Returns

TRUE on success, FALSE if not enough memory.

connection	the connection
function	处理消息的函数
user_data	传递给函数的用户数据
free_data_function	用于释放用户数据的函数

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

References _dbus_atomic_inc(), _dbus_list_append(), CONNECTION_LOCK, dbus_new0, FALSE, filter_list, NULL, and DBusMessageFilter::refcount.

◆ dbus_connection_allocate_data_slot()

DBUS_EXPORT dbus_bool_t dbus_connection_allocate_data_slot(dbus_int32_t * slot_p)

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

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

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

分配一个整数ID，用于在任何DBusConnection上存储特定于应用程序的数据。

然后，可以将分配的ID与dbus_connection_set_data（）和dbus_connection_get_data（）一起使用。传入的插槽必须初始化为-1，并使用插槽ID进行填充。如果传入的插槽不是-1，则假定已分配该插槽，并且其引用计数增加。

分配的插槽是全局的，即所有DBusConnection对象将具有保留给定整数ID的插槽。

Parameters

slot_p 存储插槽的全局变量的地址
Returns

FALSE on failure (no memory)

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

References _dbus_data_slot_allocator_alloc().

◆ dbus_connection_borrow_message()

DBUS_EXPORT DBusMessage * dbus_connection_borrow_message	(	DBusConnection *	connection	)

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

If the queue is empty, returns NULL.

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

dbus_connection_dispatch() will block if called while a borrowed message is outstanding; only one piece of code can be playing with the incoming queue at a time. This function will block if called during a dbus_connection_dispatch().

返回从传入消息队列收到的第一条消息，并将其留在队列中。如果队列为空，则返回空。

调用方不拥有对返回消息的引用，必须使用dbus_connection_return_message（）返回它，或者在调用dbus_connection_steal_borred_message（）后保留它。借用的消息没人能看得到，所以要尽快归还，归还后不要保留对它的引用。如果你需要保留这封信，请复印一份。

如果在未处理借用的消息时调用dbus_connection_dispatch（），则将阻塞；一次只能有一段代码在处理传入队列。如果在dbus_connection_dispatch（）期间调用此函数，则此函数将阻塞。

Parameters

connection the connection.
Returns

next message in the incoming queue.

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

References CONNECTION_LOCK, dbus_connection_get_dispatch_status(), DBUS_DISPATCH_DATA_REMAINS, and NULL.

◆ dbus_connection_can_send_type()

DBUS_EXPORT dbus_bool_t dbus_connection_can_send_type	(	DBusConnection *	connection,
		int	type
	)

Tests whether a certain type can be send via the connection.

This will always return TRUE for all types, with the exception of DBUS_TYPE_UNIX_FD. The function will return TRUE for DBUS_TYPE_UNIX_FD only on systems that know Unix file descriptors and can send them via the chosen transport and when the remote side supports this.

This function can be used to do runtime checking for types that might be unknown to the specific D-Bus client implementation version, i.e. it will return FALSE for all types this implementation does not know, including invalid or reserved types.

测试是否可以通过连接发送特定类型。

对于所有类型，这将始终返回TRUE，但DBUS_TYPE_UNIX_FD除外。对于DBUS_TYPE_UNIX_FD，只有在知道UNIX文件描述符并可以通过所选传输发送它们的系统上，并且当远程端支持此功能时，此函数才会返回TRUE。

此函数可用于运行时检查特定D-Bus客户端实现版本可能未知的类型，即对于此实现不知道的所有类型（包括无效类型或保留类型），它将返回FALSE。

Parameters

connection the connection

type the type to check
Returns

TRUE if the type may be send via the connection

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

References _dbus_transport_can_pass_unix_fd(), CONNECTION_LOCK, CONNECTION_UNLOCK, dbus_type_is_valid(), DBUS_TYPE_UNIX_FD, FALSE, NULL, transport, and TRUE.

◆ dbus_connection_close()

DBUS_EXPORT void dbus_connection_close	(	DBusConnection *	connection	)

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

This disconnects the transport (such as a socket) underlying the connection.

Attempts to send messages after closing a connection are safe, but will result in error replies generated locally in libdbus.

关闭专用连接，因此无法发送或接收更多数据。

这将断开连接下面的传输（如套接字）。

关闭连接后尝试发送消息是安全的，但会导致在libdbus中本地生成错误回复。

This function does not affect the connection's reference count. It's safe to close 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.

此函数不影响连接的引用计数。多次关闭连接是安全的;所有的调用在第一次之后什么都不做。无法“重新打开”连接，必须创建一个新连接。该函数可能会导致通过dbus_connection_set_dispatch_status_function（）调用DBusDispatchStatusFunction集合，因为需要分派它生成的断开消息。

If a connection is dropped by the remote application, it will close itself.

You must close a connection prior to releasing the last reference to the connection. If you dbus_connection_unref() for the last time without closing the connection, the results are undefined; it is a bug in your program and libdbus will try to print a warning.

如果远程应用程序断开连接，它将自动关闭。

在释放对连接的最后一个引用之前，必须关闭连接。如果您最后一次在未关闭连接的情况下使用dbus_connection_unref（），则结果是未定义的；这是程序中的错误，libdbus将尝试打印警告。

You may not close a shared connection. Connections created with dbus_connection_open() or dbus_bus_get() are shared. These connections are owned by libdbus, and applications should only unref them, never close them. Applications can know it is safe to unref these connections because libdbus will be holding a reference as long as the connection is open. Thus, either the connection is closed and it is OK to drop the last reference, or the connection is open and the app knows it does not have the last reference.

不能关闭共享连接。使用dbus_connection_open（）或dbus_bus_get（）创建的连接是共享的。这些连接归libdbus所有，应用程序应该只解除它们的绑定，并不会关闭它们。应用程序知道解除这些连接是安全的，因为只要连接打开，libdbus就会保存一个引用。因此，要么连接已关闭，可以删除最后一个引用，要么连接已打开，应用程序知道它没有到最后一个引用。

Connections created with dbus_connection_open_private() or dbus_bus_get_private() are not kept track of or referenced by libdbus. The creator of these connections is responsible for calling dbus_connection_close() prior to releasing the last reference, if the connection is not already disconnected.

使用dbus_connection_open_private（）或dbus_bus_get_private（）创建的连接不会被libdbus跟踪或引用。如果连接尚未断开，则这些连接的创建者负责在释放最后一个引用之前调用dbus_connection_close（）。

Parameters

connection the private (unshared) connection to close

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

References _dbus_current_generation, _dbus_warn_check_failed(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and shareable.

◆ dbus_connection_dispatch()

DBUS_EXPORT DBusDispatchStatus dbus_connection_dispatch	(	DBusConnection *	connection	)

Processes any incoming data.

If there's incoming raw data that has not yet been parsed, it is parsed, which may or may not result in adding messages to the incoming queue.

The incoming data buffer is filled when the connection reads from its underlying transport (such as a socket). Reading usually happens in dbus_watch_handle() or dbus_connection_read_write().

If there are complete messages in the incoming queue, dbus_connection_dispatch() removes one message from the queue and processes it. Processing has three steps.

First, any method replies are passed to DBusPendingCall or dbus_connection_send_with_reply_and_block() in order to complete the pending method call.

Second, any filters registered with dbus_connection_add_filter() are run. If any filter returns DBUS_HANDLER_RESULT_HANDLED then processing stops after that filter.

Third, if the message is a method call it is forwarded to any registered object path handlers added with dbus_connection_register_object_path() or dbus_connection_register_fallback().

A single call to dbus_connection_dispatch() will process at most one message; it will not clear the entire message queue.

Be careful about calling dbus_connection_dispatch() from inside a message handler, i.e. calling dbus_connection_dispatch() recursively. If threads have been initialized with a recursive mutex function, then this will not deadlock; however, it can certainly confuse your application.

处理任何传入数据。

如果有尚未解析的传入原始数据，则会对其进行解析，这可能会或可能不会导致向传入队列添加消息。

当连接从其底层传输（如套接字）读取数据时，将填充传入的数据缓冲区。读取通常发生在dbus_watch_handle（）或dbus_connection_read_write（）中。

如果传入队列中有完整的消息，dbus_connection_dispatch（）将从队列中删除一条消息并对其进行处理。处理有三个步骤。

首先，将任何方法应答传递给dbus pending call或dbus_connection_send_with_reply_and_block（），以完成挂起的方法调用。

其次，运行任何注册到dbus_connection_add_filter（）的过滤器。如果任何筛选器返回DBUS_HANDLER_RESULT_HANDLED，则处理将在该筛选器之后停止。

第三，如果消息是方法调用，则将其转发给添加了dbus_connection_register_object_path（）或dbus_connection_register_fallback（）的任何已注册对象路径处理程序。

对dbus_connection_dispatch（）的单个调用最多只能处理一条消息；它不会清除整个消息队列。

从消息处理程序内部调用dbus_connection_dispatch（）时要小心，即递归调用dbus_connection_dispatch（）。如果线程已经用递归互斥函数初始化，那么这不会导致死锁；但是，这肯定会混淆应用程序。

Todo:

some FIXME in here about handling DBUS_HANDLER_RESULT_NEED_MEMORY
Parameters

connectionthe connection
Returns

dispatch status, see dbus_connection_get_dispatch_status()

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

References CONNECTION_LOCK, DBUS_DISPATCH_COMPLETE, and NULL.

◆ dbus_connection_flush()

DBUS_EXPORT void dbus_connection_flush	(	DBusConnection *	connection	)

Blocks until the outgoing message queue is empty.

Parameters

connection the connection.

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

References CONNECTION_LOCK, and NULL.

◆ dbus_connection_free_data_slot()

DBUS_EXPORT void dbus_connection_free_data_slot	(	dbus_int32_t *	slot_p	)

Deallocates a global ID for connection data slots.

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

dbus_connection_get_data（）和dbus_connection_set_data（）可能不再用于此插槽。当连接完成时，存储在现有DBusConnection对象上的现有数据将被释放，但可能无法检索（并且只有在其他人重新分配插槽时才能替换）。当传入插槽上的refcount达到0时，它被设置为-1。

Parameters

slot_p 存储要释放的插槽的地址

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

References _dbus_data_slot_allocator_free().

◆ dbus_connection_free_preallocated_send()

DBUS_EXPORT void dbus_connection_free_preallocated_send	(	DBusConnection *	connection,
		DBusPreallocatedSend *	preallocated
	)

Frees preallocated message-sending resources from dbus_connection_preallocate_send().

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

释放从dbus_connection_preallocate_send（）预先分配的消息发送资源。

仅当预分配的资源不用于发送消息时才应调用。

Parameters

connection the connection

preallocated the resources

Definition at line 3190 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.

◆ dbus_connection_get_adt_audit_session_data()

(	DBusConnection *	connection,
	void **	data,
	dbus_int32_t *	data_size
)

Gets the ADT audit data of the connection if any.

Returns TRUE if the structure pointer is returned. Always returns FALSE prior to authenticating the connection.

获取连接的ADT审核数据（如果有）。

如果返回结构指针，则返回TRUE。在验证连接之前始终返回FALSE。

Parameters

connection the connection

data return location for audit data

data_size return location for length of audit data
Returns

TRUE if audit data is filled in with a valid ucred pointer

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

References _dbus_transport_get_adt_audit_session_data(), _dbus_transport_try_to_authenticate(), CONNECTION_LOCK, CONNECTION_UNLOCK, FALSE, NULL, and transport.

◆ dbus_connection_get_data()

DBUS_EXPORT void * dbus_connection_get_data	(	DBusConnection *	connection,
		dbus_int32_t	slot
	)

Retrieves data previously set with dbus_connection_set_data().

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

检索以前使用dbus_connection_set_data（）设置的数据。必须仍然分配插槽（不能释放）。

Note

This function does not take the main thread lock on DBusConnection, which allows it to be used from inside watch and timeout functions. (See the note in docs for dbus_connection_set_watch_functions().) A side effect of this is that you need to know there's a reference held on the connection while invoking dbus_connection_get_data(), or the connection could be finalized during dbus_connection_get_data().

此函数不接受DBusConnection上的主线程锁，它允许在监视和超时函数中使用它。（参见文档中有关dbus_connection_set_watch_functions（）的说明）这样做的一个副作用是，调用dbus_connection_get_data（）时需要知道连接上保留了一个引用，或者可以在dbus_connection_get_data（）期间完成连接。
Parameters

connection the connection

slot the slot to get data from
Returns

the data, or NULL if not found

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

References _dbus_data_slot_list_get(), NULL, and slot_list.

◆ dbus_connection_get_dispatch_status()

DBUS_EXPORT DBusDispatchStatus dbus_connection_get_dispatch_status	(	DBusConnection *	connection	)

Gets the current state of the incoming message queue.

DBUS_DISPATCH_DATA_REMAINS indicates that the message queue may contain messages. DBUS_DISPATCH_COMPLETE indicates that the incoming queue is empty. DBUS_DISPATCH_NEED_MEMORY indicates that there could be data, but we can't know for sure without more memory.

To process the incoming message queue, use dbus_connection_dispatch() or (in rare cases) dbus_connection_pop_message().

Note, DBUS_DISPATCH_DATA_REMAINS really means that either we have messages in the queue, or we have raw bytes buffered up that need to be parsed. When these bytes are parsed, they may not add up to an entire message. Thus, it's possible to see a status of DBUS_DISPATCH_DATA_REMAINS but not have a message yet.

In particular this happens on initial connection, because all sorts of authentication protocol stuff has to be parsed before the first message arrives.

获取传入消息队列的当前状态。

DBUS_DISPATCH_DATA_REMAINS表示消息队列可能包含消息。DBUS_DISPATCH_COMPLETE表示传入队列为空。DBUS_DISPATCH_NEED_MEMORY表示可能有数据，但如果没有更多的内存，我们就无法确定。

要处理传入的消息队列，请使用dbus_connection_dispatch（）或（在极少数情况下）dbus_connection_pop_message（）。

请注意，DBUS_DISPATCH_DATA_REMAINS实际上意味着我们在队列中有消息，或者我们有需要解析的原始字节被缓冲了。解析这些字节时，它们可能不会合计为整个消息。因此，可能会看到DBUS_DISPATCH_DATA_REMAINS的状态，但是还没有消息。尤其是在初始连接上，因为在第一条消息到达之前，必须分析各种身份验证协议。

Parameters

connection the connection.
Returns

current dispatch status

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

References CONNECTION_LOCK, DBUS_DISPATCH_COMPLETE, and NULL.

Referenced by dbus_connection_borrow_message(), and dbus_connection_pop_message().

◆ dbus_connection_get_is_anonymous()

DBUS_EXPORT dbus_bool_t dbus_connection_get_is_anonymous	(	DBusConnection *	connection	)

Gets whether the connection is not authenticated as a specific user.

If the connection is not authenticated, this function returns TRUE, and if it is authenticated but as an anonymous user, it returns TRUE. If it is authenticated as a specific user, then this returns FALSE. (Note that if the connection was authenticated as anonymous then disconnected, this function still returns TRUE.)

If the connection is not anonymous, you can use dbus_connection_get_unix_user() and dbus_connection_get_windows_user() to see who it's authorized as.

If you want to prevent non-anonymous authorization, use dbus_server_set_auth_mechanisms() to remove the mechanisms that allow proving user identity (i.e. only allow the ANONYMOUS mechanism).

获取是否未将连接认证为特定用户。

如果连接未通过身份验证，则此函数返回TRUE；如果连接已通过身份验证但为匿名用户，则返回TRUE。如果作为特定用户进行身份验证，则返回FALSE。（请注意，如果连接被验证为匿名，然后断开连接，则此函数仍返回TRUE。）

如果连接不是匿名的，则可以使用dbus_connection_get_unix_user（）和dbus_connection_get_windows_user（）查看其授权身份。

如果要防止非匿名授权，请使用dbus_server_set_auth_mechanisms（）删除允许证明用户身份的机制（即仅允许匿名机制）。

Parameters

connection the connection
Returns

TRUE if not authenticated or authenticated as anonymous

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

References _dbus_transport_get_is_anonymous(), CONNECTION_LOCK, CONNECTION_UNLOCK, FALSE, NULL, and transport.

◆ dbus_connection_get_is_authenticated()

DBUS_EXPORT dbus_bool_t dbus_connection_get_is_authenticated	(	DBusConnection *	connection	)

Gets whether the connection was authenticated.

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

获取连接是否经过身份验证。（请注意，如果连接已通过身份验证，然后断开连接，则此函数仍返回TRUE）

Parameters

connection the connection
Returns

TRUE if the connection was ever authenticated

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

References _dbus_transport_try_to_authenticate(), CONNECTION_LOCK, CONNECTION_UNLOCK, FALSE, NULL, and transport.

◆ dbus_connection_get_is_connected()

DBUS_EXPORT dbus_bool_t dbus_connection_get_is_connected	(	DBusConnection *	connection	)

Gets whether the connection is currently open.

A connection may become disconnected when the remote application closes its end, or exits; a connection may also be disconnected with dbus_connection_close().

There are not separate states for "closed" and "disconnected," the two terms are synonymous. This function should really be called get_is_open() but for historical reasons is not.

获取连接当前是否打开。

当远程应用程序关闭其端部或退出时，连接可能会断开；也可以使用dbus_connection_close（）断开连接。

对于“关闭”和“断开”这两个词没有单独的状态，这两个词是同义的。这个函数实际上应该被称为get_is_open（），由于历史原因造成了这样的情形。

Parameters

connection the connection.
Returns

TRUE if the connection is still alive.

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

References CONNECTION_LOCK, FALSE, and NULL.

◆ dbus_connection_get_max_message_size()

DBUS_EXPORT long dbus_connection_get_max_message_size	(	DBusConnection *	connection	)

Gets the value set by dbus_connection_set_max_message_size().

Parameters

connection the connection
Returns

the max size of a single message

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

References _dbus_transport_get_max_message_size(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ dbus_connection_get_max_message_unix_fds()

DBUS_EXPORT long dbus_connection_get_max_message_unix_fds	(	DBusConnection *	connection	)

Gets the value set by dbus_connection_set_max_message_unix_fds().

Parameters

connection the connection
Returns

the max numer of unix fds of a single message

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

References _dbus_transport_get_max_message_unix_fds(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ dbus_connection_get_max_received_size()

DBUS_EXPORT long dbus_connection_get_max_received_size	(	DBusConnection *	connection	)

Gets the value set by dbus_connection_set_max_received_size().

Parameters

connection the connection
Returns

the max size of all live messages

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

References _dbus_transport_get_max_received_size(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ dbus_connection_get_max_received_unix_fds()

DBUS_EXPORT long dbus_connection_get_max_received_unix_fds	(	DBusConnection *	connection	)

Gets the value set by dbus_connection_set_max_received_unix_fds().

Parameters

connection the connection
Returns

the max unix fds of all live messages

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

References _dbus_transport_get_max_received_unix_fds(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ dbus_connection_get_object_path_data()

(	DBusConnection *	connection,
	const char *	path,
	void **	data_p
)

Gets the user data passed to dbus_connection_register_object_path() or dbus_connection_register_fallback().

If nothing was registered at this path, the data is filled in with NULL.

Parameters

connection the connection、

path the path you registered with

data_p location to store the user data, or NULL
Returns

FALSE if not enough memory

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

References _dbus_decompose_path(), _dbus_object_tree_get_user_data_unlocked(), CONNECTION_LOCK, CONNECTION_UNLOCK, dbus_free_string_array(), FALSE, NULL, objects, and TRUE.

◆ dbus_connection_get_outgoing_size()

DBUS_EXPORT long dbus_connection_get_outgoing_size	(	DBusConnection *	connection	)

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

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

获取传出消息队列中所有消息的近似大小（字节）。

这个大小是近似的，因为您不应该使用它来决定从网络中读取多少字节或任何类似性质的东西，因为优化可能会选择撒一些善意的小谎来避免性能开销。

Parameters

connectionthe connection
Returns

the number of bytes that have been queued up but not sent

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

References _dbus_counter_get_size_value(), _dbus_counter_get_unix_fd_value(), CONNECTION_LOCK, CONNECTION_UNLOCK, n_incoming, n_outgoing, NULL, outgoing_counter, and transport.

◆ dbus_connection_get_outgoing_unix_fds()

DBUS_EXPORT long dbus_connection_get_outgoing_unix_fds	(	DBusConnection *	connection	)

Gets the approximate number of uni fds of all messages in the outgoing message queue.

Parameters

connection the connection
Returns

the number of unix fds that have been queued up but not sent

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

References _dbus_counter_get_unix_fd_value(), _dbus_transport_get_address(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, outgoing_counter, and transport.

◆ dbus_connection_get_server_id()

DBUS_EXPORT char * dbus_connection_get_server_id	(	DBusConnection *	connection	)

Gets the ID of the server address we are authenticated to, if this connection is on the client side.

If the connection is on the server side, this will always return NULL - use dbus_server_get_id() to get the ID of your own server, if you are the server side.

If a client-side connection is not authenticated yet, the ID may be available if it was included in the server address, but may not be available. The only way to be sure the server ID is available is to wait for authentication to complete.

In general, each mode of connecting to a given server will have its own ID. So for example, if the session bus daemon is listening on UNIX domain sockets and on TCP, then each of those modalities will have its own server ID.

If you want an ID that identifies an entire session bus, look at dbus_bus_get_id() instead (which is just a convenience wrapper around the org.freedesktop.DBus.GetId method invoked on the bus).

You can also get a machine ID; see dbus_try_get_local_machine_id() to get the machine you are on. There isn't a convenience wrapper, but you can invoke org.freedesktop.DBus.Peer.GetMachineId on any peer to get the machine ID on the other end.

The D-Bus specification describes the server ID and other IDs in a bit more detail.

获取我们经过身份验证的服务器地址的ID（如果此连接位于客户端）。

如果连接在服务器端，则始终返回空值-如果您是服务器端，则使用dbus_server_get_id（）获取自己服务器的id。

如果客户端连接尚未通过身份验证，则该ID可能已包含在服务器地址中，但可能不可用。确保服务器ID可用的唯一方法是等待身份验证完成。

一般来说，连接到给定服务器的每种模式都有自己的ID。例如，如果会话总线守护进程在UNIX域套接字和TCP上侦听，则每种模式都有自己的服务器ID。

如果您想要一个标识整个会话总线的ID，请改为查看dbus_bus_get_ID（）（它只是在总线上调用的org.freedesktop.dbus.GetId方法周围的一个方便包装器）。

您还可以获取一个机器ID；请参阅dbus_try_get_local_machine_ID（）以获取您所在的机器。虽然没有便利的封装，但是可以在任何对等机上调用org.freedesktop.DBus.Peer.GetMachineId以获取另一端的机器ID。

Parameters

connectionthe connection
Returns

the server ID or NULL if no memory or the connection is server-side

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

References _dbus_strdup(), _dbus_transport_get_server_id(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ dbus_connection_get_socket()

DBUS_EXPORT dbus_bool_t dbus_connection_get_socket	(	DBusConnection *	connection,
		int *	fd
	)

Gets the underlying Windows or UNIX socket file descriptor of the connection, if any.

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 socket. So for adding descriptors to the main loop, use dbus_watch_get_socket() and so forth.

If the connection is not socket-based, this function will return FALSE, even if the connection does have a file descriptor of some kind. i.e. this function always returns specifically a socket file descriptor.

获取基于Windows或UNIX套接字连接的文件描述符（如果有）。

不要读取或写入文件描述符，也不要尝试在其上进行select（）；使用DBusWatch进行主循环集成。并非所有连接都具有套接字。因此，要将描述符添加到主循环中，请使用dbus_watch_get_socket（）等。

如果连接不是基于套接字的，则即使连接确实具有某种文件描述符，此函数也将返回FALSE。即此函数始终专门返回套接字文件描述符。

Parameters

connectionthe connectionfdreturn location for the file descriptor.
Returns

TRUE if fd is successfully obtained.

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

Referenced by dbus_connection_get_unix_fd().

◆ dbus_connection_get_unix_fd()

DBUS_EXPORT dbus_bool_t dbus_connection_get_unix_fd	(	DBusConnection *	connection,
		int *	fd
	)

Get the UNIX file descriptor of the connection, if any.

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

If the connection is socket-based, you can also use dbus_connection_get_socket(), which will work on Windows too. This function always fails on Windows.

Right now the returned descriptor is always a socket, but that is not guaranteed.

获取连接的UNIX文件描述符（如果有）。

例如，可将其用于带有getpeercon（）的SELinux访问控制检查。不要读取或写入文件描述符，也不要尝试在其上进行select（）；使用DBusWatch进行主循环集成。并非所有连接都具有文件描述符。因此，要将描述符添加到主循环中，请使用dbus_watch_get_unix_fd（）等等。

如果连接是基于套接字的，则还可以使用dbus_connection_get_socket（），它也可以在Windows上使用。在Windows上，此功能始终失败。

Parameters

connection the connection

fd return location for the file descriptor.
Returns

TRUE if fd is successfully obtained.

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

References dbus_connection_get_socket(), FALSE, NULL, and transport.

◆ dbus_connection_get_unix_process_id()

DBUS_EXPORT dbus_bool_t dbus_connection_get_unix_process_id	(	DBusConnection *	connection,
		unsigned long *	pid
	)

Gets the process ID of the connection if any.

Returns TRUE if the pid is filled in. Always returns FALSE prior to authenticating the connection.

获取连接的进程ID（如果有）。

如果填写了pid，则返回TRUE。在验证连接之前始终返回FALSE。

Parameters

connection the connection

pid return location for the process ID
Returns

TRUE if pid is filled in with a valid process ID

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

References _dbus_transport_get_unix_process_id(), _dbus_transport_try_to_authenticate(), CONNECTION_LOCK, CONNECTION_UNLOCK, FALSE, NULL, and transport.

◆ dbus_connection_get_unix_user()

DBUS_EXPORT dbus_bool_t dbus_connection_get_unix_user	(	DBusConnection *	connection,
		unsigned long *	uid
	)

Gets the UNIX user ID of the connection if known.

Returns TRUE if the uid is filled in. Always returns FALSE on non-UNIX platforms for now, though in theory someone could hook Windows to NIS or something. Always returns FALSE prior to authenticating the connection.

The UID is only read by servers from clients; clients can't usually get the UID of servers, because servers do not authenticate to clients. The returned UID is the UID the connection authenticated as.

The message bus is a server and the apps connecting to the bus are clients.

You can ask the bus to tell you the UID of another connection though if you like; this is done with dbus_bus_get_unix_user().

获取连接的UNIX用户ID（如果已知）。

如果填写了uid，则返回TRUE。目前在非UNIX平台上总是返回FALSE，尽管理论上有人可以将Windows挂接到NIS或其他东西上。在验证连接之前始终返回FALSE。

服务器只能从客户端读取UID；客户端通常无法获取服务器的UID，因为服务器不向客户端进行身份验证。返回的UID是作为连接身份验证使用的UID。

消息总线是服务器，连接到总线的应用程序是客户端。

如果愿意的话，可以dbus_bus_get_unix_user（）让总线告诉您另一个连接的UID。

Parameters

connection the connection

uid return location for the user ID
Returns

TRUE if uid is filled in with a valid user ID

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

References _dbus_assert, _dbus_transport_get_unix_user(), _dbus_transport_try_to_authenticate(), CONNECTION_LOCK, CONNECTION_UNLOCK, FALSE, NULL, and transport.

◆ dbus_connection_get_windows_user()

DBUS_EXPORT dbus_bool_t dbus_connection_get_windows_user	(	DBusConnection *	connection,
		char **	windows_sid_p
	)

Gets the Windows user SID of the connection if known.

Returns TRUE if the ID is filled in. Always returns FALSE on non-Windows platforms for now, though in theory someone could hook UNIX to Active Directory or something. Always returns FALSE prior to authenticating the connection.

The user is only read by servers from clients; clients can't usually get the user of servers, because servers do not authenticate to clients. The returned user is the user the connection authenticated as.

The message bus is a server and the apps connecting to the bus are clients.

The returned user string has to be freed with dbus_free().

The return value indicates whether the user SID is available; if it's available but we don't have the memory to copy it, then the return value is TRUE and NULL is given as the SID.

获取连接的Windows用户SID（如果已知）。

如果填写了ID，则返回TRUE。目前在非Windows平台上总是返回FALSE，尽管理论上有人可以将UNIX挂接到Active Directory或其他东西上。在验证连接之前始终返回FALSE。

服务器只能从客户端读取用户；客户端通常无法获取服务器的用户，因为服务器不向客户端进行身份验证。返回的用户只是作为连接身份验证。

消息总线是服务器，连接到总线的应用程序是客户端。

返回的用户字符串必须使用dbus_free（）释放。

返回值指示用户SID是否可用；如果它可用，但我们没有内存来复制它，则返回值为TRUE，并将NULL赋值给SID。

Todo:

We would like to be able to say "You can ask the bus to tell you the user of another connection though if you like; this is done with dbus_bus_get_windows_user()." But this has to be implemented in bus/driver.c and dbus/dbus-bus.c, and is pointless anyway since on Windows we only use the session bus for now.

如果您愿意，您可以使用dbus_bus_get_windows_user（）让总线告诉您另一个连接的用户。”但是这必须在bus/driver.c和dbus/dbus bus.c中实现，并且无论如何都是没有意义的，因为在windows上，我们现在只使用会话总线。
Parameters

connection the connection

windows_sid_p return location for an allocated copy of the user ID, or NULL if no memory
Returns

TRUE if user is available (returned value may be NULL anyway if no memory)

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

References _dbus_assert, _dbus_transport_get_windows_user(), _dbus_transport_try_to_authenticate(), CONNECTION_LOCK, CONNECTION_UNLOCK, FALSE, NULL, and transport.

◆ dbus_connection_has_messages_to_send()

DBUS_EXPORT dbus_bool_t dbus_connection_has_messages_to_send	(	DBusConnection *	connection	)

Checks whether there are messages in the outgoing message queue.

Use dbus_connection_flush() to block until all outgoing messages have been written to the underlying transport (such as a socket).

检查传出消息队列中是否有消息。

使用dbus_connection_flush（）进行阻塞，直到所有传出消息都写入底层传输（如套接字）。

Parameters

connection the connection.
Returns

TRUE if the outgoing queue is non-empty.

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

References _dbus_connection_has_messages_to_send_unlocked(), CONNECTION_LOCK, CONNECTION_UNLOCK, FALSE, and NULL.

◆ dbus_connection_list_registered()

(	DBusConnection *	connection,
	const char *	parent_path,
	char ***	child_entries
)

Lists the registered fallback handlers and object path handlers at the given parent_path.

The returned array should be freed with dbus_free_string_array().

列出给定parent_path上注册的回调处理程序和对象路径处理程序。

返回的数组应该用dbus_free_string_array（）释放。

Parameters

connection the connection

parent_path the path to list the child handlers of

child_entries returns NULL-terminated array of children
Returns

FALSE if no memory to allocate the child entries

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

References _dbus_decompose_path(), _dbus_object_tree_list_registered_and_unlock(), CONNECTION_LOCK, dbus_free_string_array(), FALSE, NULL, and objects.

◆ dbus_connection_open()

DBUS_EXPORT DBusConnection * dbus_connection_open	(	const char *	address,
		DBusError *	error
	)

Gets a connection to a remote address.

If a connection to the given address already exists, returns the existing connection with its reference count incremented. Otherwise, returns a new connection and saves the new connection for possible re-use if a future call to dbus_connection_open() asks to connect to the same server.

Use dbus_connection_open_private() to get a dedicated connection not shared with other callers of dbus_connection_open().

If the open fails, the function returns NULL, and provides a reason for the failure in the error parameter. Pass NULL for the error parameter if you aren't interested in the reason for failure.

Because this connection is shared, no user of the connection may call dbus_connection_close(). However, when you are done with the connection you should call dbus_connection_unref().

获取到远程地址的连接。

如果到给定地址的连接已经存在，则返回现有连接，并增加其引用计数。否则，则返回一个新的连接并保存该新连接以备将来使用。

使用dbus_connection_open_private（）获得不与dbus_connection_open（）的其他调用者共享的专用连接。

如果打开失败，则该函数返回NULL，并在error参数中提供失败原因。如果您对失败的原因不感兴趣，请为错误参数传递NULL。

因为此连接是共享的，所以该连接的任何用户都不能调用dbus_connection_close（）。但是，完成连接后，应调用dbus_connection_unref（）。

Note

Prefer dbus_connection_open() to dbus_connection_open_private() unless you have good reason; connections are expensive enough that it's wasteful to create lots of connections to the same server.

除非您有充分的理由，否则最好使用dbus_connection_open（）而不是dbus_connection_open_private（）。连接非常昂贵，所以不要在同一服务器的建立大量连接。
Parameters

address the address.

error address where an error can be returned.
Returns

new connection, or NULL on failure.

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

References NULL.

◆ dbus_connection_open_private()

DBUS_EXPORT DBusConnection * dbus_connection_open_private	(	const char *	address,
		DBusError *	error
	)

Opens a new, dedicated connection to a remote address.

Unlike dbus_connection_open(), always creates a new connection. This connection will not be saved or recycled by libdbus.

If the open fails, the function returns NULL, and provides a reason for the failure in the error parameter. Pass NULL for the error parameter if you aren't interested in the reason for failure.

When you are done with this connection, you must dbus_connection_close() to disconnect it, and dbus_connection_unref() to free the connection object.

(The dbus_connection_close() can be skipped if the connection is already known to be disconnected, for example if you are inside a handler for the Disconnected signal.)

打开到远程地址的新的专用连接。

与dbus_connection_open（）不同，始终创建一个新连接。 libdbus不会保存或回收此连接。

如果打开失败，则该函数返回NULL，并在error参数中提供失败原因。如果您对失败的原因不感兴趣，请为错误参数传递NULL。

完成此连接后，必须使用dbus_connection_close（）断开连接，并使用dbus_connection_unref（）释放连接对象。

（如果已知已断开连接，则可以跳过dbus_connection_close（），例如，如果您位于Disconnected信号的处理程序中。）

Note

Prefer dbus_connection_open() to dbus_connection_open_private() unless you have good reason; connections are expensive enough that it's wasteful to create lots of connections to the same server.

除非您有充分的理由，否则最好使用dbus_connection_open（）而不是dbus_connection_open_private（）。连接非常昂贵，所以不要在同一服务器的建立大量连接。
Parameters

address the address.

error address where an error can be returned.
Returns

new connection, or NULL on failure.

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

References NULL.

◆ dbus_connection_pop_message()

DBUS_EXPORT DBusMessage * dbus_connection_pop_message	(	DBusConnection *	connection	)

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

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

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

There is a lock that covers all ways of accessing the incoming message queue, so dbus_connection_dispatch(), dbus_connection_pop_message(), dbus_connection_borrow_message(), etc. will all block while one of the others in the group is running.

从传入消息队列中返回第一个收到的消息，并将其从队列中删除。

调用方拥有对所返回消息的引用。如果队列为空，则返回NULL。

此函数绕过所有已注册的消息处理程序，因此使用它通常是错误的。正常做法是让主循环调用dbus_connection_dispatch（）。手动弹出消息仅在非常简单的程序中有用，这些程序不与任何库或其他模块共享DBusConnection。

dbus_connection_dispatch（），dbus_connection_pop_message（），dbus_connection_borrow_message（）中的任意一个正在运行时将阻塞其他函数访问消息队列。

Parameters

connection the connection.
Returns

next message in the incoming queue.

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

References CONNECTION_LOCK, dbus_connection_get_dispatch_status(), DBUS_DISPATCH_DATA_REMAINS, and NULL.

◆ dbus_connection_preallocate_send()

DBUS_EXPORT DBusPreallocatedSend * dbus_connection_preallocate_send	(	DBusConnection *	connection	)

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

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

预分配发送消息所需的资源，从而可以在没有内存分配失败的情况下发送消息。

允许应用创建将来的保证，使其可以在不考虑内存不足的情况下发送消息。

Parameters

connection the connection we're preallocating for.
Returns

the preallocated resources, or NULL

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

References CONNECTION_LOCK, and NULL.

◆ dbus_connection_read_write()

DBUS_EXPORT dbus_bool_t dbus_connection_read_write	(	DBusConnection *	connection,
		int	timeout_milliseconds
	)

This function is intended for use with applications that don't want to write a main loop and deal with DBusWatch and DBusTimeout.

As long as the connection is open, this function will block until it can read or write, then read or write, then return TRUE.

If the connection is closed, the function returns FALSE.

The return value indicates whether reading or writing is still possible, i.e. whether the connection is connected.

Note that even after disconnection, messages may remain in the incoming queue that need to be processed. dbus_connection_read_write_dispatch() dispatches incoming messages for you; with dbus_connection_read_write() you have to arrange to drain the incoming queue yourself.

该函数旨在用于不想编写主循环并处理DBusWatch和DBusTimeout的应用程序。

另请参见dbus_connection_read_write_dispatch（）。

只要打开连接，该函数就会阻塞，直到可以读取或写入，然后读取或写入，然后返回TRUE。

如果连接关闭，该函数将返回FALSE。

返回值指示是否仍然可以进行读取或写入，即连接是否已连接。

请注意，即使在断开连接后，消息也可能保留在传入队列中，需要处理。 dbus_connection_read_write_dispatch（）为您调度传入消息；使用dbus_connection_read_write（），您必须自己清理传入队列。

Parameters

connection the connection

timeout_milliseconds max time to block or -1 for infinite
Returns

TRUE if still connected

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

References FALSE, and NULL.

◆ dbus_connection_read_write_dispatch()

DBUS_EXPORT dbus_bool_t dbus_connection_read_write_dispatch	(	DBusConnection *	connection,
		int	timeout_milliseconds
	)

This function is intended for use with applications that don't want to write a main loop and deal with DBusWatch and DBusTimeout.

An example usage would be:

while (dbus_connection_read_write_dispatch(connection, -1))
  ; // empty loop body

In this usage you would normally have set up a filter function to look at each message as it is dispatched. The loop terminates when the last message from the connection (the disconnected signal) is processed.

If there are messages to dispatch, this function will dbus_connection_dispatch() once, and return. If there are no messages to dispatch, this function will block until it can read or write, then read or write, then return.

The way to think of this function is that it either makes some sort of progress, or it blocks. Note that, while it is blocked on I/O, it cannot be interrupted (even by other threads), which makes this function unsuitable for applications that do more than just react to received messages.

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.

该函数旨在用于不想编写主循环并处理DBusWatch和DBusTimeout的应用程序。

在这种用法中，通常会设置一个过滤器功能来查看每条消息的发送情况。处理来自连接的最后一条消息（断开的信号）时，循环终止。

如果有消息要分派，此函数将调用dbus_connection_dispatch（）一次，然后返回。如果没有要发送的消息，则此函数将阻塞，直到可以读取或写入，然后读取或写入，然后返回。

考虑此功能的方法是它要么取得某种进展，要么就被阻止了。请注意，尽管它在I / O上被阻止，但是它不能被中断（即使被其他线程中断），这使此功能不适合于仅对收到的消息做出反应的应用程序。

返回值指示是否已处理完断开之后的消息，而不指示连接是否已连接。这很重要，因为即使在断开连接之后，您仍要处理在断开连接之前收到的所有消息。

Parameters

connection the connection

timeout_milliseconds max time to block or -1 for infinite
Returns

TRUE if the disconnect message has not been processed

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

References FALSE, and NULL.

◆ dbus_connection_ref()

DBUS_EXPORT DBusConnection * dbus_connection_ref	(	DBusConnection *	connection	)

Increments the reference count of a DBusConnection.

Parameters

connection the connection.
Returns

the connection.

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

References _dbus_atomic_inc(), _dbus_current_generation, NULL, and refcount.

◆ dbus_connection_register_fallback()

(	DBusConnection *	connection,
	const char *	path,
	const DBusObjectPathVTable *	vtable,
	void *	user_data
)

Registers a fallback handler for a given subsection of the object hierarchy.

The given vtable handles messages at or below the given path. You can use this to establish a default message handling policy for a whole "subdirectory."

It is a bug to call this function for object paths which already have a handler. Use dbus_connection_try_register_fallback() if this might be the case.

为对象层次结构的给定的一部分注册一个后备处理程序。

给定的vtable处理位于给定路径或路径以下的消息。您可以使用它为整个“子目录”建立默认的消息处理策略。

对已经具有处理程序的对象路径调用此函数是一个错误。如果是这种情况，请使用dbus_connection_try_register_fallback（）。

Parameters

connection the connection

path a '/' delimited string of path elements

vtable the virtual table

user_data data to pass to functions in the vtable
Returns

FALSE if an error (DBUS_ERROR_NO_MEMORY or DBUS_ERROR_OBJECT_PATH_IN_USE) occured

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

References DBUS_ERROR_INIT, FALSE, and NULL.

◆ 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.

The given vtable handles messages sent to exactly the given path.

It is a bug to call this function for object paths which already have a handler. Use dbus_connection_try_register_object_path() if this might be the case.

为对象层次结构中的给定路径注册一个处理程序。

给定的vtable处理发送到确切给定路径的消息。

对已经具有处理程序的对象路径调用此函数是一个错误。如果是这种情况，请使用dbus_connection_try_register_object_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

FALSE if an error (DBUS_ERROR_NO_MEMORY or DBUS_ERROR_OBJECT_PATH_IN_USE) ocurred

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

References DBUS_ERROR_INIT, FALSE, and NULL.

◆ dbus_connection_remove_filter()

(	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 5637 of file dbus-connection.c.

References _dbus_list_get_last_link(), _dbus_list_get_prev_link, _dbus_list_remove_link(), _dbus_warn_check_failed(), CONNECTION_LOCK, CONNECTION_UNLOCK, DBusList::data, filter_list, DBusMessageFilter::free_user_data_function, DBusMessageFilter::function, NULL, and DBusMessageFilter::user_data.

◆ dbus_connection_return_message()

DBUS_EXPORT void dbus_connection_return_message	(	DBusConnection *	connection,
		DBusMessage *	message
	)

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.

用于使用dbus_connection_borrow_message（）窥视消息后返回消息。

仅当来自dbus_connection_borrow_message（）的消息为非NULL时才调用。

Parameters

connection the connection

message the message from dbus_connection_borrow_message()

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

References _dbus_assert, CONNECTION_LOCK, dispatch_acquired, message_borrowed, and NULL.

◆ dbus_connection_send()

(	DBusConnection *	connection,
	DBusMessage *	message,
	dbus_uint32_t *	serial
)

Adds a message to the outgoing message queue.

Does not block to write the message to the network; that happens asynchronously. To force the message to be written, call dbus_connection_flush() however it is not necessary to call dbus_connection_flush() by hand; the message will be sent the next time the main loop is run. dbus_connection_flush() should only be used, for example, if the application was expected to exit before running the main loop.

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.

The message serial is used by the remote application to send a reply; see dbus_message_get_serial() or the D-Bus specification.

dbus_message_unref() can be called as soon as this method returns as the message queue will hold its own ref until the message is sent.

将消息添加到外发消息队列。

异步的将消息写入网络，不进行阻塞。要强制写入消息，请调用dbus_connection_flush（）。如果不手动调用dbus_connection_flush（），该消息将会在下次主循环运行时发送出去。 dbus_connection_flush（）仅应在例如运行主循环之前应退出应用程序的情况下使用。

因为这仅使消息排队，所以失败的唯一原因是内存不足。即使断开连接，也不会返回错误。如果函数由于内存不足而失败，则返回FALSE。该功能永远不会因为其他原因而失败；即使连接断开。

远程应用程序使用消息序列来发送回复。请参阅dbus_message_get_serial（）或D-Bus规范。

此方法返回后，可以立即调用dbus_message_unref（），因为直到发送消息为止消息队列也将保留其自己的ref，

Parameters

connection the connection.

message the message to write.

serial return location for message serial, or NULL if you don't care
Returns

TRUE on success.

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

References _dbus_connection_send_and_unlock(), _dbus_transport_can_pass_unix_fd(), CONNECTION_LOCK, CONNECTION_UNLOCK, FALSE, NULL, and transport.

◆ dbus_connection_send_preallocated()

(	DBusConnection *	connection,
	DBusPreallocatedSend *	preallocated,
	DBusMessage *	message,
	dbus_uint32_t *	client_serial
)

Sends a message using preallocated resources.

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

使用预分配的资源发送消息。

此功能不会失败。在其他方面，它与dbus_connection_send（）相同。预分配的资源来自dbus_connection_preallocate_send（）。此功能“消耗”预分配的资源，无需单独释放它们。

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 3216 of file dbus-connection.c.

References _dbus_transport_can_pass_unix_fd(), DBusPreallocatedSend::connection, CONNECTION_LOCK, CONNECTION_UNLOCK, dbus_message_get_interface(), dbus_message_get_member(), dbus_message_get_type(), DBUS_MESSAGE_TYPE_METHOD_CALL, DBUS_MESSAGE_TYPE_SIGNAL, NULL, and transport.

◆ 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(), 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 before any filters or registered object path handlers. See dbus_connection_dispatch() for details on when handlers are run.

A DBusPendingCall will always see exactly one reply message, unless it's cancelled with dbus_pending_call_cancel().

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. If DBUS_TIMEOUT_INFINITE is passed for the timeout, no timeout will be set and the call will block forever.

与dbus_connection_send（）一样，将要发送的消息发送到发送队列中，但还返回一个DBusPendingCall，用于接收对该消息的答复。

如果在给定的timeout_milliseconds内未收到任何答复，将结束阻塞该函数，并生成指示发生超时的综合错误答复（答复信息由本程序生成，而不是由远程应用程序生成）。

DBusPendingCall最先看到答复消息（比任何过滤器或注册的对象路径处理程序都要早看到）。有关何时运行处理程序的详细信息，请参见dbus_connection_dispatch（）。

除非已用dbus_pending_call_cancel（）取消了它，否则DBusPendingCall总是会看到完全一条答复消息。

如果为pending_return传递了NULL，则在内部仍将生成DBusPendingCall，并用于跟踪消息等待回复的超时时间。这意味着如果没有答复到达，将发生超时错误，这与dbus_connection_send（）不同。

如果为超时传递了-1，则使用合理的默认超时。由于这个原因，-1通常是超时的最佳值，除非您希望超时时间非常短。如果为超时传递了DBUS_TIMEOUT_INFINITE，则不会设置超时，并且通话将永远阻塞。

Warning

if the connection is disconnected or you try to send Unix file descriptors on a connection that does not support them, the DBusPendingCall will be set to NULL, so be careful with this.

如果连接断开，或者您尝试在不支持它们的连接上发送Unix文件描述符，则DBusPendingCall将设置为NULL，因此请小心。
Parameters

connection the connection

message the message to send

pending_return return location for a DBusPendingCall object, or NULL if connection is disconnected or when you try to send Unix file descriptors on a connection that does not support them.

timeout_milliseconds timeout in milliseconds, -1 (or DBUS_TIMEOUT_USE_DEFAULT) for default or DBUS_TIMEOUT_INFINITE for no timeout
Returns

FALSE if no memory, TRUE otherwise.

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

References _dbus_transport_can_pass_unix_fd(), CONNECTION_LOCK, CONNECTION_UNLOCK, FALSE, NULL, transport, and TRUE.

Referenced by dbus_connection_send_with_reply_and_block().

◆ dbus_connection_send_with_reply_and_block()

(	DBusConnection *	connection,
	DBusMessage *	message,
	int	timeout_milliseconds,
	DBusError *	error
)

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

This function does not reenter the main loop, i.e. messages other than the reply are queued up but not processed. This function is used to invoke method calls on a remote object.

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 and NULL is returned. If something else goes wrong, result is set to whatever is appropriate, such as DBUS_ERROR_NO_MEMORY or DBUS_ERROR_DISCONNECTED.

发送消息到outgoing queue中，并等待一个确切的时间以等待回复。

此功能不会重新进入主循环，即，除了答复之外的其他消息都已排队但未处理。此函数用于调用远程对象上的方法调用。

如果收到正常答复，则将其返回并从传入消息队列中删除。如果未收到，则返回NULL，并将错误设置为DBUS_ERROR_NO_REPLY。如果收到错误回复，则将其转换为DBusError并作为错误返回，然后删除回复消息并返回NULL。如果出现其他问题，则将结果设置为适当的值，例如DBUS_ERROR_NO_MEMORY或DBUS_ERROR_DISCONNECTED。

Warning

While this function blocks the calling thread will not be processing the incoming message queue. This means you can end up deadlocked if the application you're talking to needs you to reply to a method. To solve this, either avoid the situation, block in a separate thread from the main connection-dispatching thread, or use dbus_pending_call_set_notify() to avoid blocking.

当此函数阻塞调用线程时，调用线程将不会处理传入消息队列。这意味着，如果与您对话的应用程序需要您回复某个方法，那么您可能会陷入僵局。要解决这个问题，要么避免这种情况，在主连接调度线程的单独线程中阻塞，要么使用dbus pending call set notify()来避免阻塞。
Parameters

connection the connection

message the message to send

timeout_milliseconds timeout in milliseconds, -1 (or DBUS_TIMEOUT_USE_DEFAULT) for default or DBUS_TIMEOUT_INFINITE for no timeout

error return location for error message
Returns

the message that is the reply or NULL with an error code if the function fails.

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

References _dbus_assert, _dbus_transport_can_pass_unix_fd(), CONNECTION_LOCK, CONNECTION_UNLOCK, dbus_connection_send_with_reply(), DBUS_ERROR_DISCONNECTED, DBUS_ERROR_FAILED, dbus_message_unref(), dbus_pending_call_block(), dbus_pending_call_steal_reply(), dbus_pending_call_unref(), dbus_set_error(), dbus_set_error_from_message(), NULL, and transport.

Referenced by dbus_bus_get_id(), dbus_bus_get_unix_user(), dbus_bus_name_has_owner(), dbus_bus_release_name(), dbus_bus_request_name(), and dbus_bus_start_service_by_name().

◆ dbus_connection_set_allow_anonymous()

DBUS_EXPORT void dbus_connection_set_allow_anonymous	(	DBusConnection *	connection,
		dbus_bool_t	value
	)

This function must be called on the server side of a connection when the connection is first seen in the DBusNewConnectionFunction.

If set to TRUE (the default is FALSE), then the connection can proceed even if the client does not authenticate as some user identity, i.e. clients can connect anonymously.

This setting interacts with the available authorization mechanisms (see dbus_server_set_auth_mechanisms()). Namely, an auth mechanism such as ANONYMOUS that supports anonymous auth must be included in the list of available mechanisms for anonymous login to work.

This setting also changes the default rule for connections authorized as a user; normally, if a connection authorizes as a user identity, it is permitted if the user identity is root or the user identity matches the user identity of the server process. If anonymous connections are allowed, however, then any user identity is allowed.

You can override the rules for connections authorized as a user identity with dbus_connection_set_unix_user_function() and dbus_connection_set_windows_user_function().

当首次在DBusNewConnectionFunction中看到连接时，必须在连接的服务器端调用此函数。

如果设置为TRUE（默认值为FALSE），则即使客户端未通过某些用户身份验证，连接也可以继续进行，即客户端可以匿名连接。

此设置与可用的授权机制进行交互（请参见dbus_server_set_auth_mechanisms（））。即，必须将支持匿名身份验证的身份验证机制（例如ANONYMOUS）包括在可用机制列表中，以使匿名登录起作用。

此设置还更改了授权为用户的连接的默认规则。通常，如果连接授权为用户身份，则允许该用户身份为root或用户身份与服务器进程的用户身份匹配。但是，如果允许匿名连接，则允许任何用户身份。

您可以使用dbus_connection_set_unix_user_function（）和dbus_connection_set_windows_user_function（）覆盖授权为用户身份的连接规则。

Parameters

connection the connection

value whether to allow authentication as an anonymous user

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

References _dbus_transport_set_allow_anonymous(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ dbus_connection_set_change_sigpipe()

DBUS_EXPORT 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.

此函数设置一个全局标志，用于dbus_connection_new()是否能将SIGPIPE行为设置为SIG IGN。

Parameters

will_modify_sigpipe TRUE to allow sigpipe to be set to SIG_IGN

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

◆ dbus_connection_set_data()

(	DBusConnection *	connection,
	dbus_int32_t	slot,
	void *	data,
	DBusFreeFunction	free_data_func
)

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

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

在DBusConnection上存储一个指针，以及一个可选函数，用于在数据再次设置或连接完成时释放数据。slot必须用dbus_connection_allocate_data_slot()分配。

Note

This function does not take the main thread lock on DBusConnection, which allows it to be used from inside watch and timeout functions. (See the note in docs for dbus_connection_set_watch_functions().) A side effect of this is that you need to know there's a reference held on the connection while invoking dbus_connection_set_data(), or the connection could be finalized during dbus_connection_set_data().

该函数不占用DBusConnection上的主线程锁，因此可以从内部watch and timeout functions中使用它。（有关dbus_connection_set_watch_functions（）的信息，请参阅文档中的注释。）这样做的副作用是，您需要在调用dbus_connection_set_data（）时知道该连接上保留了一个引用，或者可以在dbus_connection_set_data（）期间完成该连接。
Parameters

connection the connection

slot the slot number

data the data to store

free_data_func finalizer function for the data
Returns

TRUE if there was enough memory to store the data

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

References _dbus_data_slot_list_set(), FALSE, NULL, and slot_list.

◆ dbus_connection_set_dispatch_status_function()

(	DBusConnection *	connection,
	DBusDispatchStatusFunction	function,
	void *	data,
	DBusFreeFunction	free_data_function
)

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

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

If you don't set a dispatch status function, you have to be sure to dispatch on every iteration of your main loop, especially if dbus_watch_handle() or dbus_timeout_handle() were called.

设置在调度状态更改时要调用的函数。

如果调度状态为DBUS_DISPATCH_DATA_REMAINS，则需要调用dbus_connection_dispatch（）来处理传入消息。但是，绝不能从DBusDispatchStatusFunction内部调用dbus_connection_dispatch（）。此函数是不可重入的。相反，DBusDispatchStatusFunction应该只保存一个标志，即当重新进入主循环时，消息就可以进行调度了。

如果未设置调度状态功能，则必须确保在主循环的每次迭代中进行调度，尤其是在调用dbus_watch_handle（）或dbus_timeout_handle（）的情况下

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 5097 of file dbus-connection.c.

References CONNECTION_LOCK, CONNECTION_UNLOCK, dispatch_status_data, dispatch_status_function, free_dispatch_status_data, and NULL.

◆ dbus_connection_set_exit_on_disconnect()

DBUS_EXPORT 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.

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.

设置在连接接收到断开连接信号时是否应调用_exit（）。

调用_exit（）之后，将运行任何用于断开信号的处理程序。处理程序可以通过调用此函数来取消退出。

默认情况下，exit_on_disconnect为FALSE；但是对于从dbus_bus_get（）返回的消息总线连接，默认情况下它将被打开。

Parameters

connection the connection

exit_on_disconnect TRUE if _exit() should be called after a disconnect signal

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

References CONNECTION_LOCK, CONNECTION_UNLOCK, exit_on_disconnect, FALSE, and NULL.

◆ dbus_connection_set_max_message_size()

DBUS_EXPORT void dbus_connection_set_max_message_size	(	DBusConnection *	connection,
		long	size
	)

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

Larger messages will result in disconnecting the connection.

指定允许此连接接收的最大大小的消息以byte为单位。较大的消息将导致断开连接。

Parameters

connection a DBusConnection

size maximum message size the connection can receive, in bytes

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

References _dbus_transport_set_max_message_size(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ dbus_connection_set_max_message_unix_fds()

DBUS_EXPORT void dbus_connection_set_max_message_unix_fds	(	DBusConnection *	connection,
		long	n
	)

Specifies the maximum number of unix fds a message on this connection is allowed to receive.

Messages with more unix fds will result in disconnecting the connection.

指定允许此连接上的消息接收的unix fds的最大数目。

带有更多unix fds的消息将导致断开连接。

Parameters

connection a DBusConnection

n maximum message unix fds the connection can receive

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

References _dbus_transport_set_max_message_unix_fds(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ dbus_connection_set_max_received_size()

DBUS_EXPORT void dbus_connection_set_max_received_size	(	DBusConnection *	connection,
		long	size
	)

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

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

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

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

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

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

设置可用于此连接上收到的所有消息的最大字节总数。

消息在完成之前会一直计入最大值。达到最大值后，在完成某些消息之前，连接将不会读取更多数据。

最大值的语义是：如果未完成的消息已经超过最大值，则不会读取其他消息，语义不是：如果下一条消息会使我们超过最大值，则不会阅读。原因是直到阅读完消息，我们才知道消息的大小。

因此，最大实时消息大小实际上可以超出单个消息的最大大小。

另外，如果我们在单个read（）中从连接中读取了1024个字节，并且其中包含六个小消息，则我们可能超出最大大小上限。但这应该无关紧要。

这确实意味着我们不能使用大于我们愿意超过此限制的缓冲区来调用read（）。

Parameters

connection the connection

size the maximum size in bytes of all outstanding messages

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

References _dbus_transport_set_max_received_size(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ dbus_connection_set_max_received_unix_fds()

DBUS_EXPORT void dbus_connection_set_max_received_unix_fds	(	DBusConnection *	connection,
		long	n
	)

Sets the maximum total number of unix fds 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 are analogous to those of dbus_connection_set_max_received_size().

设置可用于此连接上接收的所有消息的最大unix fd总数。在消息最终确定之前，它们的数量一直占最大值。当达到最大值时，连接将不会读取更多数据，直到一些消息处理完成为止。该语义类似于dbus_connection_set_max_received_size().

Parameters

connection the connection

n the maximum size in bytes of all outstanding messages

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

References _dbus_transport_set_max_received_unix_fds(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ dbus_connection_set_route_peer_messages()

DBUS_EXPORT void dbus_connection_set_route_peer_messages	(	DBusConnection *	connection,
		dbus_bool_t	value
	)

Normally DBusConnection automatically handles all messages to the org.freedesktop.DBus.Peer interface.

However, the message bus wants to be able to route methods on that interface through the bus and to other applications. If routing peer messages is enabled, then messages with the org.freedesktop.DBus.Peer interface that also have a bus destination name set will not be automatically handled by the DBusConnection and instead will be dispatched normally to the application.

If a normal application sets this flag, it can break things badly. So don't set this unless you are the message bus.

通常，DBusConnection会自动处理所有到org.freedesktop.DBus.Peer接口的消息。

但是，消息总线希望能够通过总线将该接口上的方法路由到其他应用程序。如果设置了该函数的value为true，那么具有org.freedesktop.DBus.Peer接口的消息也设置了总线目标名称，则DBusConnection不会自动处理它们，而是将它们正常分派到应用程序。

如果普通应用程序设置了此标志，则可能会严重的bug。因此，除非您是消息总线，否则请不要进行设置。

Parameters

connection the connection

value TRUE to pass through org.freedesktop.DBus.Peer messages with a bus name set

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

References CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and route_peer_messages.

◆ dbus_connection_set_timeout_functions()

(	DBusConnection *	connection,
	DBusAddTimeoutFunction	add_function,
	DBusRemoveTimeoutFunction	remove_function,
	DBusTimeoutToggledFunction	toggled_function,
	void *	data,
	DBusFreeFunction	free_data_function
)

Sets the timeout functions for the connection.

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

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

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

设置连接的超时函数。

这些功能主要负责通知应用程序的超时。使用Qt时，通常DBusAddTimeoutFunction将创建一个QTimer。使用GLib时，DBusAddTimeoutFunction将调用g_timeout_add。

DBusTimeoutToggledFunction通知应用程序已启用或禁用超时。调用dbus_timeout_get_enabled（）进行检查。禁用的超时应该不起任何作用，启用的超时应该添加到主循环中。使用此功能，而不应该简单地添加/删除超时，因为启用/禁用可以在不分配内存的情况下完成。通过Qt，可以使用QTimer :: start（）和QTimer :: stop（）启用和禁用。如果主循环始终每次都重新查询dbus_timeout_get_enabled（），则切换后的函数可能为NULL。无论何时切换超时，其间隔都可能改变。

可以使用dbus_timeout_get_interval（）在计时器间隔内查询DBusTimeout。 dbus_timeout_handle（）应该在间隔每经过一次后重复调用一次，从间隔一次后开始。当使用给定的remove_function删除超时时，它将停止触发。每当添加，删除或切换超时时，计时器间隔就可能改变。

Note

The thread lock on DBusConnection is held while timeout functions are invoked, so inside these functions you may not invoke any methods on DBusConnection or it will deadlock. See the comments in the code or http://lists.freedesktop.org/archives/dbus/2007-July/thread.html#8144 if you encounter this issue and want to attempt writing a patch.

在调用超时功能时，将保留DBusConnection上的线程锁，因此在这些函数内，您可能无法调用DBusConnection上的任何方法，否则它将死锁。如果遇到此问题并想尝试编写补丁，请参见代码中的注释或http://lists.freedesktop.org/archives/dbus/2007-July/thread.html#8144。

Parameters

connection	the connection.
add_function	function to add a timeout.
remove_function	function to remove a timeout.
toggled_function	function to notify of enable/disable
data	data to pass to add_function and remove_function.
free_data_function	function to be called to free the data.

Returns

FALSE on failure (no memory)

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

References _dbus_timeout_list_set_functions(), CONNECTION_LOCK, CONNECTION_UNLOCK, FALSE, NULL, and timeouts.

◆ dbus_connection_set_unix_user_function()

(	DBusConnection *	connection,
	DBusAllowUnixUserFunction	function,
	void *	data,
	DBusFreeFunction	free_data_function
)

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

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

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

On Windows, the function will be set and its free_data_function will be invoked when the connection is freed or a new function is set. However, the function will never be called, because there are no UNIX user ids to pass to it, or at least none of the existing auth protocols would allow authenticating as a UNIX user on Windows.

设置用于确定是否允许连接给定用户ID的断言函数。

当传入的连接已使用特定的用户ID进行身份验证时，将调用此断言函数；如果断言函数返回TRUE，则允许进行连接，否则断开连接。

如果该功能设置为NULL（默认情况下为NULL），则仅允许与服务器进程相同的UID进行连接。此外，始终允许root用户连接。

在Windows上，将在释放连接或设置新函数时设置该函数并调用其free_data_function。但是，永远不会调用该函数，因为没有UNIX用户ID传递给该函数，或者至少没有现有的身份验证协议允许在Windows上以UNIX用户身份进行身份验证。

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 5334 of file dbus-connection.c.

References _dbus_transport_set_unix_user_function(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ 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.

This function is responsible for waking up the main loop (if its sleeping in another thread) when some some change has happened to the connection that the mainloop needs to reconsider (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().

设置连接的mainloop唤醒功能。

当需要重新考虑主循环的连接发生某些更改时（例如，一条消息已排队等待写入），此功能负责唤醒主循环（如果主循环在另一个线程中休眠）。使用Qt时，通常会导致调用QEventLoop :: wakeUp（）。使用GLib时，它将调用g_main_context_wakeup（）。

Parameters

connectionthe connection.wakeup_main_functionfunction to wake up the mainloopdatadata to pass wakeup_main_functionfree_data_functionfunction to be called to free the data.

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

References CONNECTION_LOCK, CONNECTION_UNLOCK, free_wakeup_main_data, NULL, wakeup_main_data, and wakeup_main_function.

◆ dbus_connection_set_watch_functions()

(	DBusConnection *	connection,
	DBusAddWatchFunction	add_function,
	DBusRemoveWatchFunction	remove_function,
	DBusWatchToggledFunction	toggled_function,
	void *	data,
	DBusFreeFunction	free_data_function
)

Sets the watch functions for the connection.

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

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

The DBusWatch can be queried for the file descriptor to watch using dbus_watch_get_unix_fd() or dbus_watch_get_socket(), 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.

设置连接的监视功能。

这些函数负责使应用程序的主循环知道需要使用select（）或poll（）监视事件的文件描述符。使用Qt时，通常DBusAddWatchFunction将创建QSocketNotifier。使用GLib时，DBusAddWatchFunction可以调用g_io_add_watch（），或者可以用作更详尽的GSource的一部分。请注意，添加手表后，可能无法启用它。

DBusWatchToggledFunction通知应用程序监视已启用或禁用。调用dbus_watch_get_enabled（）进行检查。禁用的监视应该没有任何作用，应该将启用的监视添加到主循环中。使用此功能，而不是简单地添加/删除监视，因为启用/禁用可以在不分配内存的情况下完成。如果主循环始终每次都重新查询dbus_watch_get_enabled（），则切换后的函数可能为NULL。

可以查询DBusWatch以使用dbus_watch_get_unix_fd（）或dbus_watch_get_socket（）来查询要监视的文件描述符，并使用dbus_watch_get_flags（）来查询要监视的事件。 dbus_watch_get_flags（）返回的标志仅包含DBUS_WATCH_READABLE和DBUS_WATCH_WRITABLE，从不包含DBUS_WATCH_HANGUP或DBUS_WATCH_ERROR；所有监视都隐含了断开，错误和其他异常情况的监视。

一旦文件描述符变得可读或可写，或发生异常，应调用dbus_watch_handle（）通知监视了文件描述符状态的连接。

在DBusAddWatchFunction期间无法调用dbus_watch_handle（），因为该连接尚未准备好处理该监视。

在将DBusWatch传递给remove_function之后，不允许引用它。

如果由于内存不足而返回FALSE，则失败可能是由于新的add_function返回了FALSE。如果是这样，则add_function可能已被成功调用一次或多次，但还将调用remove_function来删除任何成功的添加。也就是说，如果返回FALSE，则最终结果应该是dbus_connection_set_watch_functions（）无效，但是可能已调用add_function和remove_function。

Note

The thread lock on DBusConnection is held while watch functions are invoked, so inside these functions you may not invoke any methods on DBusConnection or it will deadlock. See the comments in the code or http://lists.freedesktop.org/archives/dbus/2007-July/tread.html#8144 if you encounter this issue and want to attempt writing a patch.

在调用监视功能时，将保留DBusConnection上的线程锁，因此在这些函数内，您不能在DBusConnection上调用任何方法，否则它将死锁。如果遇到此问题并想尝试编写补丁，请参见代码中的注释或http://lists.freedesktop.org/archives/dbus/2007-July/tread.html#8144。

Parameters

connection	the connection.
add_function	function to begin monitoring a new descriptor.
remove_function	function to stop monitoring a descriptor.
toggled_function	function to notify of enable/disable
data	data to pass to add_function and remove_function.
free_data_function	function to be called to free the data.

Returns

FALSE on failure (no memory)

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

References _dbus_watch_list_set_functions(), CONNECTION_LOCK, CONNECTION_UNLOCK, FALSE, NULL, and watches.

◆ dbus_connection_set_windows_user_function()

(	DBusConnection *	connection,
	DBusAllowWindowsUserFunction	function,
	void *	data,
	DBusFreeFunction	free_data_function
)

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

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

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

On UNIX, the function will be set and its free_data_function will be invoked when the connection is freed or a new function is set. However, the function will never be called, because there is no way right now to authenticate as a Windows user on UNIX.

设置用于确定是否允许连接给定用户ID的断言函数。

当传入的连接已使用特定的用户ID进行身份验证时，将调用此函数；如果此函数返回TRUE，则允许进行连接，否则断开连接。

如果将功能设置为NULL（默认情况下为NULL），则仅允许拥有服务器进程的同一用户连接。

在UNIX上，将释放连接或设置新功能时，将设置该函数并调用其free_data_function。但是，该函数永远不会被调用，因为目前无法在UNIX上以Windows用户身份进行身份验证。

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 5478 of file dbus-connection.c.

References _dbus_transport_set_windows_user_function(), CONNECTION_LOCK, CONNECTION_UNLOCK, NULL, and transport.

◆ dbus_connection_steal_borrowed_message()

DBUS_EXPORT void dbus_connection_steal_borrowed_message	(	DBusConnection *	connection,
		DBusMessage *	message
	)

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

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

用于在使用dbus_connection_borrow_message（）窥视消息后保留消息。

使用此功能之前，请参阅dbus_connection_pop_message（）的文档中的警告/警告。

Parameters

connection the connection、

message the message from dbus_connection_borrow_message()

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

References _dbus_assert, _dbus_list_pop_first(), CONNECTION_LOCK, dispatch_acquired, incoming_messages, message_borrowed, n_incoming, and NULL.

◆ dbus_connection_try_register_fallback()

(	DBusConnection *	connection,
	const char *	path,
	const DBusObjectPathVTable *	vtable,
	void *	user_data,
	DBusError *	error
)

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."

为对象层次结构的给定子部分注册一个回调处理程序。

给定的vtable处理位于给定路径或路径以下的消息。您可以使用它为整个“子目录”建立默认的消息处理策略。

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
error	address where an error can be returned

Returns

FALSE if an error (DBUS_ERROR_NO_MEMORY or DBUS_ERROR_OBJECT_PATH_IN_USE) is reported

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

References FALSE, and NULL.

◆ dbus_connection_try_register_object_path()

(	DBusConnection *	connection,
	const char *	path,
	const DBusObjectPathVTable *	vtable,
	void *	user_data,
	DBusError *	error
)

Registers a handler for a given path in the object hierarchy.

The given vtable handles messages sent to exactly the given path.

为对象层次结构中的给定路径注册处理程序。给定的vtable处理发送到指定路径的消息。

Parameters

connectionthe connectionpatha '/' delimited string of path elementsvtablethe virtual tableuser_datadata to pass to functions in the vtableerroraddress where an error can be returned
Returns

FALSE if an error (DBUS_ERROR_NO_MEMORY or DBUS_ERROR_OBJECT_PATH_IN_USE) is reported

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

References FALSE, and NULL.

◆ dbus_connection_unref()

DBUS_EXPORT void dbus_connection_unref	(	DBusConnection *	connection	)

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

Note: it is a bug to drop the last reference to a connection that is still connected.

For shared connections, libdbus will own a reference as long as the connection is connected, so you can know that either you don't have the last reference, or it's OK to drop the last reference. Most connections are shared. dbus_connection_open() and dbus_bus_get() return shared connections.

For private connections, the creator of the connection must arrange for dbus_connection_close() to be called prior to dropping the last reference. Private connections come from dbus_connection_open_private() or dbus_bus_get_private().

对DBusConnection的引用计数进行递减，如果该计数为零，则对其进行终止。

注意：删除最后一个对仍处于连接状态的连接的引用是一个错误。

对于共享连接，只要连接已连接，libdbus将拥有一个引用，因此您可以知道您没有最后一个引用，也可以删除最后一个引用。大多数连接是共享的。 dbus_connection_open（）和dbus_bus_get（）返回共享连接。

对于专用连接，连接的创建者必须安排在删除最后一个引用之前调用dbus_connection_close（）。专用连接来自dbus_connection_open_private（）或dbus_bus_get_private（）。

Parameters

connection the connection.

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

References _dbus_atomic_dec(), _dbus_current_generation, NULL, and refcount.

◆ dbus_connection_unregister_object_path()

DBUS_EXPORT dbus_bool_t dbus_connection_unregister_object_path	(	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.

注销给定路径path上注册的处理程序。

为未注册的路径调用此函数是一个错误。可以注销后备路径和对象路径。

Parameters

connection the connection

path a '/' delimited string of path elements
Returns

FALSE if not enough memory

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

References _dbus_decompose_path(), _dbus_object_tree_unregister_and_unlock(), CONNECTION_LOCK, dbus_free_string_array(), FALSE, NULL, objects, and TRUE.

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