implementation details for DBusWatch More...

Data Structures
struct	DBusWatch
	Implementation of DBusWatch. More...

struct	DBusWatchList
	DBusWatchList implementation details. More...

Macros
#define	_DBUS_WATCH_NVAL (1<<4)

Typedefs
typedef struct DBusWatchList	DBusWatchList
	Opaque data type representing a list of watches and a set of DBusAddWatchFunction/DBusRemoveWatchFunction.

typedef dbus_bool_t(*	DBusWatchHandler) (DBusWatch watch, unsigned int flags, void data)
	function to run when the watch is handled

Functions
dbus_bool_t	_dbus_watch_get_enabled (DBusWatch *watch)

dbus_bool_t	_dbus_watch_get_oom_last_time (DBusWatch *watch)

void	_dbus_watch_set_oom_last_time (DBusWatch *watch, dbus_bool_t oom)

DBusWatch *	_dbus_watch_new (DBusPollable fd, unsigned int flags, dbus_bool_t enabled, DBusWatchHandler handler, void *data, DBusFreeFunction free_data_function)
	Creates a new DBusWatch.

DBusWatch *	_dbus_watch_ref (DBusWatch *watch)
	Increments the reference count of a DBusWatch object.

void	_dbus_watch_unref (DBusWatch *watch)
	Decrements the reference count of a DBusWatch object and finalizes the object if the count reaches zero.

void	_dbus_watch_invalidate (DBusWatch *watch)
	Clears the file descriptor from a now-invalid watch object so that no one tries to use it.

void	_dbus_watch_sanitize_condition (DBusWatch watch, unsigned int condition)
	Sanitizes the given condition so that it only contains flags that the DBusWatch requested.

DBusWatchList *	_dbus_watch_list_new (void)
	Creates a new watch list.

void	_dbus_watch_list_free (DBusWatchList *watch_list)
	Frees a DBusWatchList.

dbus_bool_t	_dbus_watch_list_set_functions (DBusWatchList watch_list, DBusAddWatchFunction add_function, DBusRemoveWatchFunction remove_function, DBusWatchToggledFunction toggled_function, void data, DBusFreeFunction free_data_function)
	Sets the watch functions.

dbus_bool_t	_dbus_watch_list_add_watch (DBusWatchList watch_list, DBusWatch watch)
	Adds a new watch to the watch list, invoking the application DBusAddWatchFunction if appropriate.

void	_dbus_watch_list_remove_watch (DBusWatchList watch_list, DBusWatch watch)
	Removes a watch from the watch list, invoking the application's DBusRemoveWatchFunction if appropriate.

void	_dbus_watch_list_toggle_watch (DBusWatchList watch_list, DBusWatch watch, dbus_bool_t enabled)
	Sets a watch to the given enabled state, invoking the application's DBusWatchToggledFunction if appropriate.

void	_dbus_watch_list_toggle_all_watches (DBusWatchList *watch_list, dbus_bool_t enabled)
	Sets all watches to the given enabled state, invoking the application's DBusWatchToggledFunction if appropriate.

void	_dbus_watch_set_handler (DBusWatch watch, DBusWatchHandler handler, void data, DBusFreeFunction free_data_function)
	Sets the handler for the watch.

DBusSocket	_dbus_watch_get_socket (DBusWatch *watch)

DBUS_PRIVATE_EXPORT DBusPollable	_dbus_watch_get_pollable (DBusWatch *watch)

Detailed Description

implementation details for DBusWatch

Macro Definition Documentation

◆ _DBUS_WATCH_NVAL

#define _DBUS_WATCH_NVAL (1<<4)

Definition at line 42 of file dbus-watch.h.

Typedef Documentation

◆ DBusWatchHandler

typedef dbus_bool_t(* DBusWatchHandler) (DBusWatch *watch, unsigned int flags, void *data)

function to run when the watch is handled

Definition at line 45 of file dbus-watch.h.

◆ DBusWatchList

DBusWatchList

Opaque data type representing a list of watches and a set of DBusAddWatchFunction/DBusRemoveWatchFunction.

Automatically handles removing/re-adding watches when the DBusAddWatchFunction is updated or changed. Holds a reference count to each watch.

Used in the implementation of both DBusServer and DBusClient.

Definition at line 40 of file dbus-watch.h.

Function Documentation

◆ _dbus_watch_get_enabled()

dbus_bool_t _dbus_watch_get_enabled ( DBusWatch * watch )

Definition at line 59 of file dbus-watch.c.

◆ _dbus_watch_get_oom_last_time()

DBUS_PRIVATE_EXPORT dbus_bool_t _dbus_watch_get_oom_last_time ( DBusWatch * watch )

Definition at line 65 of file dbus-watch.c.

◆ _dbus_watch_get_pollable()

DBUS_PRIVATE_EXPORT DBusPollable _dbus_watch_get_pollable ( DBusWatch * watch )

Definition at line 623 of file dbus-watch.c.

◆ _dbus_watch_get_socket()

DBusSocket _dbus_watch_get_socket ( DBusWatch * watch )

Definition at line 607 of file dbus-watch.c.

◆ _dbus_watch_invalidate()

DBUS_PRIVATE_EXPORT void _dbus_watch_invalidate ( DBusWatch * watch )

Clears the file descriptor from a now-invalid watch object so that no one tries to use it.

This is because a watch may stay alive due to reference counts after the file descriptor is closed. Invalidation makes it easier to catch bugs. It also keeps people from doing dorky things like assuming file descriptors are unique (never recycled).

Parameters

watch the watch object.

Definition at line 171 of file dbus-watch.c.

References DBusWatch::fd, and DBusWatch::flags.

Referenced by _dbus_babysitter_unref(), _dbus_server_new_for_socket(), _dbus_spawn_async_with_babysitter(), and _dbus_transport_new_for_socket().

◆ _dbus_watch_list_add_watch()

DBUS_PRIVATE_EXPORT dbus_bool_t _dbus_watch_list_add_watch	(	DBusWatchList *	watch_list,
		DBusWatch *	watch
	)

Adds a new watch to the watch list, invoking the application DBusAddWatchFunction if appropriate.

Parameters

watch_list	the watch list.
watch	the watch to add.

Returns: TRUE on success, FALSE if no memory.

Definition at line 383 of file dbus-watch.c.

References _dbus_list_append(), _dbus_list_remove_last(), _dbus_watch_ref(), _dbus_watch_unref(), DBusWatchList::add_watch_function, FALSE, DBusWatch::fd, NULL, TRUE, DBusWatchList::watch_data, and DBusWatchList::watches.

Referenced by _dbus_connection_add_watch_unlocked(), _dbus_server_add_watch(), and _dbus_spawn_async_with_babysitter().

◆ _dbus_watch_list_free()

DBUS_PRIVATE_EXPORT void _dbus_watch_list_free ( DBusWatchList * watch_list )

Frees a DBusWatchList.

Parameters

watch_list the watch list.

Definition at line 251 of file dbus-watch.c.

References _dbus_list_clear_full(), _dbus_watch_list_set_functions(), _dbus_watch_unref(), dbus_free(), NULL, and DBusWatchList::watches.

Referenced by _dbus_babysitter_unref(), _dbus_connection_new_for_transport(), _dbus_server_finalize_base(), and _dbus_server_init_base().

◆ _dbus_watch_list_new()

DBUS_PRIVATE_EXPORT DBusWatchList * _dbus_watch_list_new ( void )

Creates a new watch list.

Returns NULL if insufficient memory exists.

Returns: the new watch list, or NULL on failure.

Definition at line 234 of file dbus-watch.c.

References dbus_new0, and NULL.

Referenced by _dbus_connection_new_for_transport(), and _dbus_server_init_base().

◆ _dbus_watch_list_remove_watch()

DBUS_PRIVATE_EXPORT void _dbus_watch_list_remove_watch	(	DBusWatchList *	watch_list,
		DBusWatch *	watch
	)

Removes a watch from the watch list, invoking the application's DBusRemoveWatchFunction if appropriate.

Parameters

watch_list	the watch list.
watch	the watch to remove.

Definition at line 416 of file dbus-watch.c.

References _dbus_assert_not_reached, _dbus_list_remove(), _dbus_watch_unref(), DBusWatch::fd, NULL, DBusWatchList::remove_watch_function, DBusWatchList::watch_data, and DBusWatchList::watches.

Referenced by _dbus_connection_remove_watch_unlocked(), and _dbus_server_remove_watch().

◆ _dbus_watch_list_set_functions()

DBUS_PRIVATE_EXPORT dbus_bool_t _dbus_watch_list_set_functions	(	DBusWatchList *	watch_list,
		DBusAddWatchFunction	add_function,
		DBusRemoveWatchFunction	remove_function,
		DBusWatchToggledFunction	toggled_function,
		void *	data,
		DBusFreeFunction	free_data_function
	)

Sets the watch functions.

This function is the "backend" for dbus_connection_set_watch_functions() and dbus_server_set_watch_functions().

Parameters

watch_list	the watch list.
add_function	the add watch function.
remove_function	the remove watch function.
toggled_function	function on toggling enabled flag, or NULL
data	the data for those functions.
free_data_function	the function to free the data.

Returns: FALSE if not enough memory

Definition at line 297 of file dbus-watch.c.

References _dbus_list_foreach(), _dbus_list_get_first_link(), _dbus_list_get_next_link, DBusWatchList::add_watch_function, DBusList::data, dbus_watch_get_flags(), FALSE, DBusWatch::fd, NULL, DBusWatchList::remove_watch_function, TRUE, DBusWatchList::watch_data, DBusWatchList::watch_free_data_function, DBusWatchList::watch_toggled_function, and DBusWatchList::watches.

Referenced by _dbus_babysitter_set_watch_functions(), _dbus_watch_list_free(), dbus_connection_set_watch_functions(), and dbus_server_set_watch_functions().

◆ _dbus_watch_list_toggle_all_watches()

void _dbus_watch_list_toggle_all_watches	(	DBusWatchList *	watch_list,
		dbus_bool_t	enabled
	)

Sets all watches to the given enabled state, invoking the application's DBusWatchToggledFunction if appropriate.

Parameters

watch_list	the watch list.
enabled	TRUE to enable

Definition at line 474 of file dbus-watch.c.

References _dbus_list_get_first_link(), _dbus_list_get_next_link, _dbus_watch_list_toggle_watch(), DBusList::data, NULL, and DBusWatchList::watches.

Referenced by _dbus_server_toggle_all_watches().

◆ _dbus_watch_list_toggle_watch()

void _dbus_watch_list_toggle_watch	(	DBusWatchList *	watch_list,
		DBusWatch *	watch,
		dbus_bool_t	enabled
	)

Sets a watch to the given enabled state, invoking the application's DBusWatchToggledFunction if appropriate.

Parameters

watch_list	the watch list.
watch	the watch to toggle.
enabled	TRUE to enable

Definition at line 443 of file dbus-watch.c.

References DBusWatch::enabled, DBusWatch::fd, NULL, DBusWatchList::watch_data, and DBusWatchList::watch_toggled_function.

Referenced by _dbus_connection_toggle_watch_unlocked(), and _dbus_watch_list_toggle_all_watches().

◆ _dbus_watch_new()

DBUS_PRIVATE_EXPORT DBusWatch * _dbus_watch_new	(	DBusPollable	fd,
		unsigned int	flags,
		dbus_bool_t	enabled,
		DBusWatchHandler	handler,
		void *	data,
		DBusFreeFunction	free_data_function
	)

Creates a new DBusWatch.

Used to add a file descriptor to be polled by a main loop.

Parameters

fd	the file descriptor to be watched.
flags	the conditions to watch for on the descriptor.
enabled	the initial enabled state
handler	the handler function
data	data for handler function
free_data_function	function to free the data

Returns: the new DBusWatch object.

Definition at line 90 of file dbus-watch.c.

References _dbus_assert, dbus_new0, DBusWatch::enabled, DBusWatch::fd, DBusWatch::flags, DBusWatch::free_handler_data_function, DBusWatch::handler, DBusWatch::handler_data, NULL, and DBusWatch::refcount.

Referenced by _dbus_server_new_for_socket(), _dbus_spawn_async_with_babysitter(), and _dbus_transport_new_for_socket().

◆ _dbus_watch_ref()

DBUS_PRIVATE_EXPORT DBusWatch * _dbus_watch_ref ( DBusWatch * watch )

Increments the reference count of a DBusWatch object.

Parameters

watch the watch object.

Returns: the watch object.

Definition at line 126 of file dbus-watch.c.

References DBusWatch::refcount.

Referenced by _dbus_transport_handle_watch(), and _dbus_watch_list_add_watch().

◆ _dbus_watch_sanitize_condition()

void _dbus_watch_sanitize_condition	(	DBusWatch *	watch,
		unsigned int *	condition
	)

Sanitizes the given condition so that it only contains flags that the DBusWatch requested.

e.g. if the watch is a DBUS_WATCH_READABLE watch then DBUS_WATCH_WRITABLE will be stripped from the condition.

Parameters

watch	the watch object.
condition	address of the condition to sanitize.

Definition at line 187 of file dbus-watch.c.

References DBUS_WATCH_READABLE, DBUS_WATCH_WRITABLE, and DBusWatch::flags.

Referenced by _dbus_transport_handle_watch(), and dbus_watch_handle().

◆ _dbus_watch_set_handler()

void _dbus_watch_set_handler	(	DBusWatch *	watch,
		DBusWatchHandler	handler,
		void *	data,
		DBusFreeFunction	free_data_function
	)

Sets the handler for the watch.

Parameters

watch	the watch
handler	the new handler
data	the data
free_data_function	free data with this

Definition at line 500 of file dbus-watch.c.

References DBusWatch::free_handler_data_function, DBusWatch::handler, and DBusWatch::handler_data.

◆ _dbus_watch_set_oom_last_time()

DBUS_PRIVATE_EXPORT void _dbus_watch_set_oom_last_time	(	DBusWatch *	watch,
		dbus_bool_t	oom
	)

Definition at line 71 of file dbus-watch.c.

◆ _dbus_watch_unref()

DBUS_PRIVATE_EXPORT void _dbus_watch_unref ( DBusWatch * watch )

Decrements the reference count of a DBusWatch object and finalizes the object if the count reaches zero.

Parameters

watch the watch object.

Definition at line 140 of file dbus-watch.c.

References _dbus_assert, _dbus_warn(), dbus_free(), dbus_watch_set_data(), DBusWatch::fd, DBusWatch::free_handler_data_function, DBusWatch::handler_data, NULL, and DBusWatch::refcount.

Referenced by _dbus_babysitter_unref(), _dbus_server_new_for_socket(), _dbus_spawn_async_with_babysitter(), _dbus_transport_handle_watch(), _dbus_transport_new_for_socket(), _dbus_watch_list_add_watch(), _dbus_watch_list_free(), and _dbus_watch_list_remove_watch().

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ _DBUS_WATCH_NVAL

Typedef Documentation

◆ DBusWatchHandler

◆ DBusWatchList

Function Documentation

◆ _dbus_watch_get_enabled()

◆ _dbus_watch_get_oom_last_time()

◆ _dbus_watch_get_pollable()

◆ _dbus_watch_get_socket()

◆ _dbus_watch_invalidate()

◆ _dbus_watch_list_add_watch()

◆ _dbus_watch_list_free()

◆ _dbus_watch_list_new()

◆ _dbus_watch_list_remove_watch()

◆ _dbus_watch_list_set_functions()

◆ _dbus_watch_list_toggle_all_watches()

◆ _dbus_watch_list_toggle_watch()

◆ _dbus_watch_new()

◆ _dbus_watch_ref()

◆ _dbus_watch_sanitize_condition()

◆ _dbus_watch_set_handler()

◆ _dbus_watch_set_oom_last_time()

◆ _dbus_watch_unref()