Main Page   Modules   Data Structures   File List   Data Fields   Related Pages  

DBusWatch implementation details
[D-BUS internal implementation details]

implementation details for DBusWatch More...

Data Structures

struct  DBusWatch
struct  DBusWatchList
 DBusWatchList implementation details. More...


Typedefs

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


Functions

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

void _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_set_handler (DBusWatch *watch, DBusWatchHandler handler, void *data, DBusFreeFunction free_data_function)
 Sets the handler for the 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 33 of file dbus-watch.h.


Function Documentation

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 139 of file dbus-watch.c.

Referenced by _dbus_babysitter_unref().

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 326 of file dbus-watch.c.

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

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

void _dbus_watch_list_free DBusWatchList   watch_list
 

Frees a DBusWatchList.

Parameters:
watch_list the watch list.

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

References _dbus_list_clear(), _dbus_list_foreach(), _dbus_watch_list_set_functions(), dbus_free(), and DBusWatchList::watches.

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

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 202 of file dbus-watch.c.

References dbus_new0, and NULL.

Referenced by _dbus_connection_new_for_transport(), and _dbus_server_init_base().

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 359 of file dbus-watch.c.

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

Referenced by _dbus_connection_remove_watch(), and _dbus_server_remove_watch().

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 247 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, FALSE, 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().

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 386 of file dbus-watch.c.

References NULL, DBusWatchList::watch_data, and DBusWatchList::watch_toggled_function.

Referenced by _dbus_connection_toggle_watch(), and _dbus_server_toggle_watch().

DBusWatch* _dbus_watch_new int    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 64 of file dbus-watch.c.

References _dbus_assert, dbus_new0, and NULL.

Referenced by _dbus_server_new_for_fd(), _dbus_spawn_async_with_babysitter(), and _dbus_transport_new_for_fd().

void _dbus_watch_ref DBusWatch   watch
 

Increments the reference count of a DBusWatch object.

Parameters:
watch the watch object.

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

Referenced by _dbus_transport_handle_watch(), and _dbus_watch_list_add_watch().

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 155 of file dbus-watch.c.

Referenced by _dbus_transport_handle_watch(), and dbus_watch_handle().

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:
watch the watch
handler the new handler
data the data
free_data_function free data with this

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

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 111 of file dbus-watch.c.

References _dbus_assert, dbus_free(), and dbus_watch_set_data().

Referenced by _dbus_babysitter_unref(), _dbus_server_new_for_fd(), _dbus_transport_handle_watch(), _dbus_transport_new_for_fd(), _dbus_watch_list_add_watch(), and _dbus_watch_list_remove_watch().


Generated on Wed Oct 22 14:05:10 2003 for D-BUS by doxygen1.3-rc3