Main Page   Modules   Data Structures   File List   Data Fields   Related Pages  

DBusServer
[D-BUS message system public API]

Server that listens for new connections. More...

Typedefs

typedef DBusServer DBusServer
 An opaque object representing a server that listens for connections from other applications. More...


Functions

DBusServer * dbus_server_listen (const char *address, DBusError *error)
 Listens for new connections on the given address. More...

DBusServer * dbus_server_ref (DBusServer *server)
 Increments the reference count of a DBusServer. More...

void dbus_server_unref (DBusServer *server)
 Decrements the reference count of a DBusServer. More...

void dbus_server_disconnect (DBusServer *server)
 Releases the server's address and stops listening for new clients. More...

dbus_bool_t dbus_server_get_is_connected (DBusServer *server)
 Returns TRUE if the server is still listening for new connections. More...

char * dbus_server_get_address (DBusServer *server)
 Returns the address of the server, as a newly-allocated string which must be freed by the caller. More...

void dbus_server_set_new_connection_function (DBusServer *server, DBusNewConnectionFunction function, void *data, DBusFreeFunction free_data_function)
 Sets a function to be used for handling new connections. More...

dbus_bool_t dbus_server_set_watch_functions (DBusServer *server, 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_server_set_timeout_functions (DBusServer *server, DBusAddTimeoutFunction add_function, DBusRemoveTimeoutFunction remove_function, DBusTimeoutToggledFunction toggled_function, void *data, DBusFreeFunction free_data_function)
 Sets the timeout functions for the connection. More...

dbus_bool_t dbus_server_set_auth_mechanisms (DBusServer *server, const char **mechanisms)
 Sets the authentication mechanisms that this server offers to clients, as a list of SASL mechanisms. More...

dbus_bool_t dbus_server_allocate_data_slot (dbus_int32_t *slot_p)
 Allocates an integer ID to be used for storing application-specific data on any DBusServer. More...

void dbus_server_free_data_slot (dbus_int32_t *slot_p)
 Deallocates a global ID for server data slots. More...

dbus_bool_t dbus_server_set_data (DBusServer *server, int slot, void *data, DBusFreeFunction free_data_func)
 Stores a pointer on a DBusServer, along with an optional function to be used for freeing the data when the data is set again, or when the server is finalized. More...

void * dbus_server_get_data (DBusServer *server, int slot)
 Retrieves data previously set with dbus_server_set_data(). More...


Detailed Description

Server that listens for new connections.

Types and functions related to DBusServer. A DBusServer represents a server that other applications can connect to. Each connection from another application is represented by a DBusConnection.

Todo:
Thread safety hasn't been looked at for DBusServer

Need notification to apps of disconnection, may matter for some transports


Typedef Documentation

DBusServer
 

An opaque object representing a server that listens for connections from other applications.

Each time a connection is made, a new DBusConnection is created and made available via an application-provided DBusNewConnectionFunction. The DBusNewConnectionFunction is provided with dbus_server_set_new_connection_function().

Definition at line 36 of file dbus-server.h.


Function Documentation

dbus_bool_t dbus_server_allocate_data_slot dbus_int32_t   slot_p
 

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

The allocated ID may then be used with dbus_server_set_data() and dbus_server_get_data(). The slot must be initialized with -1. If a nonnegative slot is passed in, the refcount is incremented on that slot, rather than creating a new slot.

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

Parameters:
slot_p  address of global variable storing the slot ID
Returns:
FALSE on no memory

Definition at line 684 of file dbus-server.c.

void dbus_server_disconnect DBusServer   server
 

Releases the server's address and stops listening for new clients.

If called more than once, only the first call has an effect. Does not modify the server's reference count.

Parameters:
server  the server.

Definition at line 498 of file dbus-server.c.

References DBusServerVTable::disconnect, disconnected, and vtable.

void dbus_server_free_data_slot dbus_int32_t   slot_p
 

Deallocates a global ID for server data slots.

dbus_server_get_data() and dbus_server_set_data() may no longer be used with this slot. Existing data stored on existing DBusServer objects will be freed when the server is finalized, but may not be retrieved (and may only be replaced if someone else reallocates the slot).

Parameters:
slot_p  address of the slot to deallocate

Definition at line 703 of file dbus-server.c.

char* dbus_server_get_address DBusServer   server
 

Returns the address of the server, as a newly-allocated string which must be freed by the caller.

Parameters:
server  the server
Returns:
the address or NULL if no memory

Definition at line 532 of file dbus-server.c.

References address.

void* dbus_server_get_data DBusServer   server,
int    slot
 

Retrieves data previously set with dbus_server_set_data().

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

Parameters:
server  the server
slot  the slot to get data from
Returns:
the data, or NULL if not found

Definition at line 767 of file dbus-server.c.

References slot_list.

dbus_bool_t dbus_server_get_is_connected DBusServer   server
 

Returns TRUE if the server is still listening for new connections.

Parameters:
server  the server.

Definition at line 517 of file dbus-server.c.

References disconnected.

DBusServer* dbus_server_listen const char *    address,
DBusError   error
 

Listens for new connections on the given address.

Returns NULL if listening fails for any reason. Otherwise returns a new DBusServer. dbus_server_set_new_connection_function() and dbus_server_set_watch_functions() should be called immediately to render the server fully functional.

Todo:
error messages on bad address could really be better. DBusResultCode is a bit limiting here.
Parameters:
address  the address of this server.
error  location to store rationale for failure.
Returns:
a new DBusServer, or NULL on failure.

Definition at line 270 of file dbus-server.c.

DBusServer* dbus_server_ref DBusServer   server
 

Increments the reference count of a DBusServer.

Parameters:
server  the server.
Returns:
the server

Definition at line 456 of file dbus-server.c.

References refcount.

dbus_bool_t dbus_server_set_auth_mechanisms DBusServer   server,
const char **    mechanisms
 

Sets the authentication mechanisms that this server offers to clients, as a list of SASL mechanisms.

This function only affects connections created *after* it is called. Pass NULL instead of an array to use all available mechanisms.

Parameters:
server  the server
mechanisms  NULL-terminated array of mechanisms
Returns:
FALSE if no memory

Definition at line 643 of file dbus-server.c.

References auth_mechanisms.

dbus_bool_t dbus_server_set_data DBusServer   server,
int    slot,
void *    data,
DBusFreeFunction    free_data_func
 

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

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

Parameters:
server  the server
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 724 of file dbus-server.c.

References slot_list.

void dbus_server_set_new_connection_function DBusServer   server,
DBusNewConnectionFunction    function,
void *    data,
DBusFreeFunction    free_data_function
 

Sets a function to be used for handling new connections.

The given function is passed each new connection as the connection is created. If the new connection function increments the connection's reference count, the connection will stay alive. Otherwise, the connection will be unreferenced and closed.

Parameters:
server  the server.
function  a function to handle new connections.
data  data to pass to the new connection handler.
free_data_function  function to free the data.

Definition at line 552 of file dbus-server.c.

References new_connection_data, new_connection_free_data_function, and new_connection_function.

dbus_bool_t dbus_server_set_timeout_functions DBusServer   server,
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.

This function behaves exactly like dbus_connection_set_timeout_functions(); see the documentation for that routine.

Parameters:
server  the server.
add_function  function to add a timeout.
remove_function  function to remove a timeout.
toggled_function  function to notify when the timeout is enabled/disabled
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 617 of file dbus-server.c.

References timeouts.

dbus_bool_t dbus_server_set_watch_functions DBusServer   server,
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.

This function behaves exactly like dbus_connection_set_watch_functions(); see the documentation for that routine.

Parameters:
server  the server.
add_function  function to begin monitoring a new descriptor.
remove_function  function to stop monitoring a descriptor.
toggled_function  function to notify when the watch is enabled/disabled
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 584 of file dbus-server.c.

References watches.

void dbus_server_unref DBusServer   server
 

Decrements the reference count of a DBusServer.

Finalizes the server if the reference count reaches zero. The server connection will be closed as with dbus_server_disconnect() when the server is finalized.

Parameters:
server  the server.

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

References DBusServerVTable::finalize, refcount, and vtable.


Generated on Wed Jun 9 05:01:28 2004 for D-BUS by doxygen1.2.15