D-Bus  1.11.8
Data Structures | Macros | Typedefs | Functions
DBusWatch implementation details

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. More...
 
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. More...
 
DBusWatch_dbus_watch_ref (DBusWatch *watch)
 Increments the reference count of a DBusWatch object. More...
 
void _dbus_watch_unref (DBusWatch *watch)
 Decrements the reference count of a DBusWatch object and finalizes the object if the count reaches zero. More...
 
void _dbus_watch_invalidate (DBusWatch *watch)
 Clears the file descriptor from a now-invalid watch object so that no one tries to use it. More...
 
void _dbus_watch_sanitize_condition (DBusWatch *watch, unsigned int *condition)
 Sanitizes the given condition so that it only contains flags that the DBusWatch requested. More...
 
DBusWatchList_dbus_watch_list_new (void)
 Creates a new watch list. More...
 
void _dbus_watch_list_free (DBusWatchList *watch_list)
 Frees a DBusWatchList. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
void _dbus_watch_set_handler (DBusWatch *watch, DBusWatchHandler handler, void *data, DBusFreeFunction free_data_function)
 Sets the handler for the watch. More...
 
DBusSocket _dbus_watch_get_socket (DBusWatch *watch)
 
DBUS_PRIVATE_EXPORT DBusPollable _dbus_watch_get_pollable (DBusWatch *watch)
 

Detailed Description

implementation details for DBusWatch

Typedef Documentation

§ 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 38 of file dbus-watch.h.

Function Documentation

§ _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
watchthe watch object.

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

§ _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_listthe watch list.
watchthe watch to add.
Returns
TRUE on success, FALSE if no memory.

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

References _dbus_list_append(), _dbus_watch_ref(), DBusWatchList::add_watch_function, FALSE, NULL, and DBusWatchList::watches.

§ _dbus_watch_list_free()

DBUS_PRIVATE_EXPORT void _dbus_watch_list_free ( DBusWatchList watch_list)

§ _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 232 of file dbus-watch.c.

References dbus_new0, and NULL.

Referenced by _dbus_connection_new_for_transport().

§ _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_listthe watch list.
watchthe watch to remove.

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

References _dbus_assert_not_reached, _dbus_list_remove(), NULL, DBusWatchList::remove_watch_function, and DBusWatchList::watches.

§ _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_listthe watch list.
add_functionthe add watch function.
remove_functionthe remove watch function.
toggled_functionfunction on toggling enabled flag, or NULL
datathe data for those functions.
free_data_functionthe function to free the data.
Returns
FALSE if not enough memory

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

References _dbus_list_get_first_link(), _dbus_list_get_next_link, DBusList::data, NULL, 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_listthe watch list.
enabledTRUE to enable

Definition at line 473 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_listthe watch list.
watchthe watch to toggle.
enabledTRUE to enable

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

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

Referenced by _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
fdthe file descriptor to be watched.
flagsthe conditions to watch for on the descriptor.
enabledthe initial enabled state
handlerthe handler function
datadata for handler function
free_data_functionfunction to free the data
Returns
the new DBusWatch object.

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

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

Referenced by _dbus_server_new_for_socket(), 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
watchthe watch object.
Returns
the watch object.

Definition at line 124 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
watchthe watch object.
conditionaddress of the condition to sanitize.

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

References DBUS_WATCH_READABLE, DBUS_WATCH_WRITABLE, and DBusWatch::flags.

Referenced by _dbus_transport_handle_watch().

§ _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.

Todo:
this function only exists because of the weird way connection watches are done, see the note in docs for _dbus_connection_handle_watch().
Parameters
watchthe watch
handlerthe new handler
datathe data
free_data_functionfree data with this

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

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

§ _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
watchthe watch object.

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

References _dbus_assert, NULL, and DBusWatch::refcount.

Referenced by _dbus_transport_handle_watch(), and _dbus_watch_list_free().