dbus/dbus-server.c

   1 /* -*- mode: C; c-file-style: "gnu" -*- */
   2 /* dbus-server.c DBusServer object
   3  *
   4  * Copyright (C) 2002  Red Hat Inc.
   5  *
   6  * Licensed under the Academic Free License version 1.2
   7  *
   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.
  12  *
  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.
  17  *
  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
  21  *
  22  */
  23 #include "dbus-server.h"
  24 #include "dbus-server-unix.h"
  25
  26 /**
  27  * @defgroup DBusServer DBusServer
  28  * @ingroup  DBus
  29  * @brief Server that listens for new connections.
  30  *
  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.
  35  */
  36
  37 /**
  38  * @defgroup DBusServerInternals DBusServer implementation details
  39  * @ingroup  DBusInternals
  40  * @brief Implementation details of DBusServer
  41  *
  42  * @{
  43  */
  44
  45 /**
  46  * Initializes the members of the DBusServer base class.
  47  * Chained up to by subclass constructors.
  48  *
  49  * @param server the server.
  50  * @param vtable the vtable for the subclass.
  51  * @returns #TRUE on success.
  52  */
  53 dbus_bool_t
  54 _dbus_server_init_base (DBusServer             *server,
  55                         const DBusServerVTable *vtable)
  56 {
  57   server->vtable = vtable;
  58   server->refcount = 1;
  59
  60   server->watches = _dbus_watch_list_new ();
  61   if (server->watches == NULL)
  62     return FALSE;
  63
  64   server->connection_counter = _dbus_counter_new ();
  65   if (server->connection_counter == NULL)
  66     {
  67       _dbus_watch_list_free (server->watches);
  68       server->watches = NULL;
  69       return FALSE;
  70     }
  71
  72   server->max_connections = 256; /* same as an X server, seems like a nice default */
  73
  74   return TRUE;
  75 }
  76
  77 /**
  78  * Finalizes the members of the DBusServer base class.
  79  * Chained up to by subclass finalizers.
  80  *
  81  * @param server the server.
  82  */
  83 void
  84 _dbus_server_finalize_base (DBusServer *server)
  85 {
  86   dbus_server_set_new_connection_function (server, NULL, NULL, NULL);
  87
  88   if (!server->disconnected)
  89     dbus_server_disconnect (server);
  90
  91   _dbus_watch_list_free (server->watches);
  92   _dbus_counter_unref (server->connection_counter);
  93 }
  94
  95 /**
  96  * Adds a watch for this server, chaining out to application-provided
  97  * watch handlers.
  98  *
  99  * @param server the server.
 100  * @param watch the watch to add.
 101  */
 102 dbus_bool_t
 103 _dbus_server_add_watch (DBusServer *server,
 104                         DBusWatch  *watch)
 105 {
 106   return _dbus_watch_list_add_watch (server->watches, watch);
 107 }
 108
 109 /**
 110  * Removes a watch previously added with _dbus_server_remove_watch().
 111  *
 112  * @param server the server.
 113  * @param watch the watch to remove.
 114  */
 115 void
 116 _dbus_server_remove_watch  (DBusServer *server,
 117                             DBusWatch  *watch)
 118 {
 119   _dbus_watch_list_remove_watch (server->watches, watch);
 120 }
 121
 122
 123 /** @} */
 124
 125 /**
 126  * @addtogroup DBusServer
 127  *
 128  * @{
 129  */
 130
 131
 132 /**
 133  * @typedef DBusServer
 134  *
 135  * An opaque object representing a server that listens for
 136  * connections from other applications. Each time a connection
 137  * is made, a new DBusConnection is created and made available
 138  * via an application-provided DBusNewConnectionFunction.
 139  * The DBusNewConnectionFunction is provided with
 140  * dbus_server_set_new_connection_function().
 141  *
 142  */
 143
 144 /**
 145  * Listens for new connections on the given address.
 146  * Returns #NULL if listening fails for any reason.
 147  * Otherwise returns a new #DBusServer.
 148  * dbus_server_set_new_connection_function() and
 149  * dbus_server_set_watch_functions() should be called
 150  * immediately to render the server fully functional.
 151  *
 152  * @param address the address of this server.
 153  * @param result location to store rationale for failure.
 154  * @returns a new DBusServer, or #NULL on failure.
 155  *
 156  */
 157 DBusServer*
 158 dbus_server_listen (const char     *address,
 159                     DBusResultCode *result)
 160 {
 161   DBusServer *server;
 162
 163   /* For now just pretend the address is a unix domain socket path */
 164   server = _dbus_server_new_for_domain_socket (address, result);
 165
 166   return server;
 167 }
 168
 169 /**
 170  * Increments the reference count of a DBusServer.
 171  *
 172  * @param server the server.
 173  */
 174 void
 175 dbus_server_ref (DBusServer *server)
 176 {
 177   server->refcount += 1;
 178 }
 179
 180 /**
 181  * Decrements the reference count of a DBusServer.  Finalizes the
 182  * server if the reference count reaches zero. The server connection
 183  * will be closed as with dbus_server_disconnect() when the server is
 184  * finalized.
 185  *
 186  * @param server the server.
 187  */
 188 void
 189 dbus_server_unref (DBusServer *server)
 190 {
 191   _dbus_assert (server != NULL);
 192   _dbus_assert (server->refcount > 0);
 193
 194   server->refcount -= 1;
 195   if (server->refcount == 0)
 196     {
 197       _dbus_assert (server->vtable->finalize != NULL);
 198
 199       (* server->vtable->finalize) (server);
 200     }
 201 }
 202
 203 /**
 204  * Releases the server's address and stops listening for
 205  * new clients. If called more than once, only the first
 206  * call has an effect. Does not modify the server's
 207  * reference count.
 208  *
 209  * @param server the server.
 210  */
 211 void
 212 dbus_server_disconnect (DBusServer *server)
 213 {
 214   _dbus_assert (server->vtable->disconnect != NULL);
 215
 216   if (server->disconnected)
 217     return;
 218
 219   (* server->vtable->disconnect) (server);
 220   server->disconnected = TRUE;
 221 }
 222
 223 /**
 224  * Returns #TRUE if the server is still listening for new connections.
 225  *
 226  * @param server the server.
 227  */
 228 dbus_bool_t
 229 dbus_server_get_is_connected (DBusServer *server)
 230 {
 231   return !server->disconnected;
 232 }
 233
 234 /**
 235  * Sets a function to be used for handling new connections.  The given
 236  * function is passed each new connection as the connection is
 237  * created. If the new connection function increments the connection's
 238  * reference count, the connection will stay alive. Otherwise, the
 239  * connection will be unreferenced and closed.
 240  *
 241  * @param server the server.
 242  * @param function a function to handle new connections.
 243  * @param data data to pass to the new connection handler.
 244  * @param free_data_function function to free the data.
 245  */
 246 void
 247 dbus_server_set_new_connection_function (DBusServer                *server,
 248                                          DBusNewConnectionFunction  function,
 249                                          void                      *data,
 250                                          DBusFreeFunction           free_data_function)
 251 {
 252   if (server->new_connection_free_data_function != NULL)
 253     (* server->new_connection_free_data_function) (server->new_connection_data);
 254
 255   server->new_connection_function = function;
 256   server->new_connection_data = data;
 257   server->new_connection_free_data_function = free_data_function;
 258 }
 259
 260 /**
 261  * Sets the watch functions for the connection. These functions are
 262  * responsible for making the application's main loop aware of file
 263  * descriptors that need to be monitored for events.
 264  *
 265  * This function behaves exactly like dbus_connection_set_watch_functions();
 266  * see the documentation for that routine.
 267  *
 268  * @param server the server.
 269  * @param add_function function to begin monitoring a new descriptor.
 270  * @param remove_function function to stop monitoring a descriptor.
 271  * @param data data to pass to add_function and remove_function.
 272  * @param free_data_function function to be called to free the data.
 273  */
 274 void
 275 dbus_server_set_watch_functions (DBusServer              *server,
 276                                  DBusAddWatchFunction     add_function,
 277                                  DBusRemoveWatchFunction  remove_function,
 278                                  void                    *data,
 279                                  DBusFreeFunction         free_data_function)
 280 {
 281   _dbus_watch_list_set_functions (server->watches,
 282                                   add_function,
 283                                   remove_function,
 284                                   data,
 285                                   free_data_function);
 286 }
 287
 288 /**
 289  * Called to notify the server when a previously-added watch
 290  * is ready for reading or writing, or has an exception such
 291  * as a hangup.
 292  *
 293  * @param server the server.
 294  * @param watch the watch.
 295  * @param condition the current condition of the file descriptors being watched.
 296  */
 297 void
 298 dbus_server_handle_watch (DBusServer              *server,
 299                           DBusWatch               *watch,
 300                           unsigned int             condition)
 301 {
 302   _dbus_assert (server->vtable->handle_watch != NULL);
 303
 304   _dbus_watch_sanitize_condition (watch, &condition);
 305
 306   (* server->vtable->handle_watch) (server, watch, condition);
 307 }
 308
 309 /**
 310  * Sets the maximum number of connections that can be open at one
 311  * time for this server. If the maximum is reached, and another
 312  * client tries to connect, then the oldest unauthenticated client
 313  * will be dropped. If no unauthenticated client exists, then
 314  * the new connection will be refused.
 315  *
 316  * If the maximum is set to a number lower than the current
 317  * number of connections, no current connections are
 318  * disconnected.
 319  *
 320  * @todo honoring max_connections has not been implemented
 321  * yet. The only real work involved is keeping a list
 322  * of live connections on the DBusServer so the oldest
 323  * unauthenticated client can be located when required.
 324  *
 325  * @todo for a systemwide daemon, we need a max number of connections
 326  * per user, since any user can authenticate a bunch of connections
 327  * and create a DOS.
 328  *
 329  * @todo a single process might listen on multiple mechanisms
 330  * (multiple DBusServer) and might want the max connections
 331  * value to span all those servers. Should consider
 332  * changing the API accordingly, though I'm inclined to
 333  * punt this to the app that wants to do it instead of
 334  * putting it in the library.
 335  *
 336  * @param server the server
 337  * @param max_connections maximum number of connections allowed
 338  */
 339 void
 340 dbus_server_set_max_connections (DBusServer *server,
 341                                  int         max_connections)
 342 {
 343   server->max_connections = max_connections;
 344 }
 345
 346 /**
 347  * Gets the maximum number of connections that can be active
 348  * at a time for this server.
 349  *
 350  * @param server the server
 351  * @returns maximum number of connections at once
 352  */
 353 int
 354 dbus_server_get_max_connections (DBusServer *server)
 355 {
 356   return server->max_connections;
 357 }
 358
 359 /**
 360  * Gets the number of #DBusConnection to this server that
 361  * have not yet been finalized. i.e. all #DBusConnection that
 362  * were passed to #DBusNewConnectionFunction and have not yet been
 363  * finalized will count in this total.
 364  *
 365  * @param server the server
 366  * @param returns the number of connections
 367  */
 368 int
 369 dbus_server_get_n_connections (DBusServer *server)
 370 {
 371   return _dbus_counter_get_value (server->connection_counter);
 372 }
 373
 374 /** @} */
 375