1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-server.c DBusServer object
4 * Copyright (C) 2002 Red Hat Inc.
6 * Licensed under the Academic Free License version 1.2
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23 #include "dbus-server.h"
24 #include "dbus-server-unix.h"
27 * @defgroup DBusServer DBusServer
29 * @brief Server that listens for new connections.
31 * Types and functions related to DBusServer.
32 * A DBusServer represents a server that other applications
33 * can connect to. Each connection from another application
34 * is represented by a DBusConnection.
38 * @defgroup DBusServerInternals DBusServer implementation details
39 * @ingroup DBusInternals
40 * @brief Implementation details of DBusServer
46 * Initializes the members of the DBusServer base class.
47 * Chained up to by subclass constructors.
49 * @param server the server.
50 * @param vtable the vtable for the subclass.
51 * @returns #TRUE on success.
54 _dbus_server_init_base (DBusServer *server,
55 const DBusServerVTable *vtable)
57 server->vtable = vtable;
60 server->watches = _dbus_watch_list_new ();
61 if (server->watches == NULL)
68 * Finalizes the members of the DBusServer base class.
69 * Chained up to by subclass finalizers.
71 * @param server the server.
74 _dbus_server_finalize_base (DBusServer *server)
76 dbus_server_set_new_connection_function (server, NULL, NULL, NULL);
78 if (!server->disconnected)
79 dbus_server_disconnect (server);
81 _dbus_watch_list_free (server->watches);
85 * Adds a watch for this server, chaining out to application-provided
88 * @param server the server.
89 * @param watch the watch to add.
92 _dbus_server_add_watch (DBusServer *server,
95 return _dbus_watch_list_add_watch (server->watches, watch);
99 * Removes a watch previously added with _dbus_server_remove_watch().
101 * @param server the server.
102 * @param watch the watch to remove.
105 _dbus_server_remove_watch (DBusServer *server,
108 _dbus_watch_list_remove_watch (server->watches, watch);
115 * @addtogroup DBusServer
122 * @typedef DBusServer
124 * An opaque object representing a server that listens for
125 * connections from other applications. Each time a connection
126 * is made, a new DBusConnection is created and made available
127 * via an application-provided DBusNewConnectionFunction.
128 * The DBusNewConnectionFunction is provided with
129 * dbus_server_set_new_connection_function().
134 * Listens for new connections on the given address.
135 * Returns #NULL if listening fails for any reason.
136 * Otherwise returns a new #DBusServer.
137 * dbus_server_set_new_connection_function() and
138 * dbus_server_set_watch_functions() should be called
139 * immediately to render the server fully functional.
141 * @param address the address of this server.
142 * @param result location to store rationale for failure.
143 * @returns a new DBusServer, or #NULL on failure.
147 dbus_server_listen (const char *address,
148 DBusResultCode *result)
152 /* For now just pretend the address is a unix domain socket path */
153 server = _dbus_server_new_for_domain_socket (address, result);
159 * Increments the reference count of a DBusServer.
161 * @param server the server.
164 dbus_server_ref (DBusServer *server)
166 server->refcount += 1;
170 * Decrements the reference count of a DBusServer. Finalizes the
171 * server if the reference count reaches zero. The server connection
172 * will be closed as with dbus_server_disconnect() when the server is
175 * @param server the server.
178 dbus_server_unref (DBusServer *server)
180 _dbus_assert (server != NULL);
181 _dbus_assert (server->refcount > 0);
183 server->refcount -= 1;
184 if (server->refcount == 0)
186 _dbus_assert (server->vtable->finalize != NULL);
188 (* server->vtable->finalize) (server);
193 * Releases the server's address and stops listening for
194 * new clients. If called more than once, only the first
195 * call has an effect. Does not modify the server's
198 * @param server the server.
201 dbus_server_disconnect (DBusServer *server)
203 _dbus_assert (server->vtable->disconnect != NULL);
205 if (server->disconnected)
208 (* server->vtable->disconnect) (server);
209 server->disconnected = TRUE;
213 * Returns #TRUE if the server is still listening for new connections.
215 * @param server the server.
218 dbus_server_get_is_connected (DBusServer *server)
220 return !server->disconnected;
224 * Sets a function to be used for handling new connections. The given
225 * function is passed each new connection as the connection is
226 * created. If the new connection function increments the connection's
227 * reference count, the connection will stay alive. Otherwise, the
228 * connection will be unreferenced and closed.
230 * @param server the server.
231 * @param function a function to handle new connections.
232 * @param data data to pass to the new connection handler.
233 * @param free_data_function function to free the data.
236 dbus_server_set_new_connection_function (DBusServer *server,
237 DBusNewConnectionFunction function,
239 DBusFreeFunction free_data_function)
241 if (server->new_connection_free_data_function != NULL)
242 (* server->new_connection_free_data_function) (server->new_connection_data);
244 server->new_connection_function = function;
245 server->new_connection_data = data;
246 server->new_connection_free_data_function = free_data_function;
250 * Sets the watch functions for the connection. These functions are
251 * responsible for making the application's main loop aware of file
252 * descriptors that need to be monitored for events.
254 * This function behaves exactly like dbus_connection_set_watch_functions();
255 * see the documentation for that routine.
257 * @param server the server.
258 * @param add_function function to begin monitoring a new descriptor.
259 * @param remove_function function to stop monitoring a descriptor.
260 * @param data data to pass to add_function and remove_function.
261 * @param free_data_function function to be called to free the data.
264 dbus_server_set_watch_functions (DBusServer *server,
265 DBusAddWatchFunction add_function,
266 DBusRemoveWatchFunction remove_function,
268 DBusFreeFunction free_data_function)
270 _dbus_watch_list_set_functions (server->watches,
278 * Called to notify the server when a previously-added watch
279 * is ready for reading or writing, or has an exception such
282 * @param server the server.
283 * @param watch the watch.
284 * @param condition the current condition of the file descriptors being watched.
287 dbus_server_handle_watch (DBusServer *server,
289 unsigned int condition)
291 _dbus_assert (server->vtable->handle_watch != NULL);
293 _dbus_watch_sanitize_condition (watch, &condition);
295 (* server->vtable->handle_watch) (server, watch, condition);