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 #ifdef DBUS_BUILD_TESTS
  26 #include "dbus-server-debug.h"
  27 #endif
  28 #include "dbus-address.h"
  29
  30 /**
  31  * @defgroup DBusServer DBusServer
  32  * @ingroup  DBus
  33  * @brief Server that listens for new connections.
  34  *
  35  * Types and functions related to DBusServer.
  36  * A DBusServer represents a server that other applications
  37  * can connect to. Each connection from another application
  38  * is represented by a DBusConnection.
  39  */
  40
  41 /**
  42  * @defgroup DBusServerInternals DBusServer implementation details
  43  * @ingroup  DBusInternals
  44  * @brief Implementation details of DBusServer
  45  *
  46  * @{
  47  */
  48
  49 /**
  50  * Initializes the members of the DBusServer base class.
  51  * Chained up to by subclass constructors.
  52  *
  53  * @param server the server.
  54  * @param vtable the vtable for the subclass.
  55  * @returns #TRUE on success.
  56  */
  57 dbus_bool_t
  58 _dbus_server_init_base (DBusServer             *server,
  59                         const DBusServerVTable *vtable)
  60 {
  61   server->vtable = vtable;
  62   server->refcount = 1;
  63
  64   server->watches = _dbus_watch_list_new ();
  65   if (server->watches == NULL)
  66     return FALSE;
  67
  68   server->timeouts = _dbus_timeout_list_new ();
  69   if (server->timeouts == NULL)
  70     {
  71       _dbus_watch_list_free (server->watches);
  72       server->watches = NULL;
  73       return FALSE;
  74     }
  75
  76   server->connection_counter = _dbus_counter_new ();
  77   if (server->connection_counter == NULL)
  78     {
  79       _dbus_watch_list_free (server->watches);
  80       server->watches = NULL;
  81       _dbus_timeout_list_free (server->timeouts);
  82       server->timeouts = NULL;
  83
  84       return FALSE;
  85     }
  86
  87   server->max_connections = 256; /* same as an X server, seems like a nice default */
  88
  89   return TRUE;
  90 }
  91
  92 /**
  93  * Finalizes the members of the DBusServer base class.
  94  * Chained up to by subclass finalizers.
  95  *
  96  * @param server the server.
  97  */
  98 void
  99 _dbus_server_finalize_base (DBusServer *server)
 100 {
 101   dbus_server_set_new_connection_function (server, NULL, NULL, NULL);
 102
 103   if (!server->disconnected)
 104     dbus_server_disconnect (server);
 105
 106   _dbus_watch_list_free (server->watches);
 107   _dbus_timeout_list_free (server->timeouts);
 108   _dbus_counter_unref (server->connection_counter);
 109 }
 110
 111 /**
 112  * Adds a watch for this server, chaining out to application-provided
 113  * watch handlers.
 114  *
 115  * @param server the server.
 116  * @param watch the watch to add.
 117  */
 118 dbus_bool_t
 119 _dbus_server_add_watch (DBusServer *server,
 120                         DBusWatch  *watch)
 121 {
 122   return _dbus_watch_list_add_watch (server->watches, watch);
 123 }
 124
 125 /**
 126  * Removes a watch previously added with _dbus_server_remove_watch().
 127  *
 128  * @param server the server.
 129  * @param watch the watch to remove.
 130  */
 131 void
 132 _dbus_server_remove_watch  (DBusServer *server,
 133                             DBusWatch  *watch)
 134 {
 135   _dbus_watch_list_remove_watch (server->watches, watch);
 136 }
 137
 138 /**
 139  * Adds a timeout for this server, chaining out to application-provided
 140  * timeout handlers.
 141  *
 142  * @param server the server.
 143  * @param timeout the timeout to add.
 144  */
 145 dbus_bool_t
 146 _dbus_server_add_timeout (DBusServer  *server,
 147                           DBusTimeout *timeout)
 148 {
 149   return _dbus_timeout_list_add_timeout (server->timeouts, timeout);
 150 }
 151
 152 /**
 153  * Removes a timeout previously added with _dbus_server_add_timeout().
 154  *
 155  * @param server the server.
 156  * @param timeout the timeout to remove.
 157  */
 158 void
 159 _dbus_server_remove_timeout (DBusServer  *server,
 160                              DBusTimeout *timeout)
 161 {
 162   _dbus_timeout_list_remove_timeout (server->timeouts, timeout);
 163 }
 164
 165 /** @} */
 166
 167 /**
 168  * @addtogroup DBusServer
 169  *
 170  * @{
 171  */
 172
 173
 174 /**
 175  * @typedef DBusServer
 176  *
 177  * An opaque object representing a server that listens for
 178  * connections from other applications. Each time a connection
 179  * is made, a new DBusConnection is created and made available
 180  * via an application-provided DBusNewConnectionFunction.
 181  * The DBusNewConnectionFunction is provided with
 182  * dbus_server_set_new_connection_function().
 183  *
 184  */
 185
 186 /**
 187  * Listens for new connections on the given address.
 188  * Returns #NULL if listening fails for any reason.
 189  * Otherwise returns a new #DBusServer.
 190  * dbus_server_set_new_connection_function() and
 191  * dbus_server_set_watch_functions() should be called
 192  * immediately to render the server fully functional.
 193  *
 194  * @param address the address of this server.
 195  * @param result location to store rationale for failure.
 196  * @returns a new DBusServer, or #NULL on failure.
 197  *
 198  */
 199 DBusServer*
 200 dbus_server_listen (const char     *address,
 201                     DBusResultCode *result)
 202 {
 203   DBusServer *server;
 204   DBusAddressEntry **entries;
 205   int len, i;
 206
 207   if (!dbus_parse_address (address, &entries, &len, result))
 208     return NULL;
 209
 210   server = NULL;
 211
 212   for (i = 0; i < len; i++)
 213     {
 214       const char *method = dbus_address_entry_get_method (entries[i]);
 215
 216       if (strcmp (method, "unix") == 0)
 217         {
 218           const char *path = dbus_address_entry_get_value (entries[i], "path");
 219
 220           if (path == NULL)
 221             goto bad_address;
 222
 223           server = _dbus_server_new_for_domain_socket (path, result);
 224
 225           if (server)
 226             break;
 227         }
 228       else if (strcmp (method, "debug") == 0)
 229         {
 230           const char *name = dbus_address_entry_get_value (entries[i], "name");
 231
 232           if (name == NULL)
 233             goto bad_address;
 234
 235           server = _dbus_server_debug_new (name, result);
 236
 237           if (server)
 238             break;
 239         }
 240       else goto bad_address;
 241     }
 242
 243   dbus_address_entries_free (entries);
 244   return server;
 245
 246  bad_address:
 247   dbus_address_entries_free (entries);
 248   dbus_set_result (result, DBUS_RESULT_BAD_ADDRESS);
 249
 250   return NULL;
 251 }
 252
 253 /**
 254  * Increments the reference count of a DBusServer.
 255  *
 256  * @param server the server.
 257  */
 258 void
 259 dbus_server_ref (DBusServer *server)
 260 {
 261   server->refcount += 1;
 262 }
 263
 264 /**
 265  * Decrements the reference count of a DBusServer.  Finalizes the
 266  * server if the reference count reaches zero. The server connection
 267  * will be closed as with dbus_server_disconnect() when the server is
 268  * finalized.
 269  *
 270  * @param server the server.
 271  */
 272 void
 273 dbus_server_unref (DBusServer *server)
 274 {
 275   _dbus_assert (server != NULL);
 276   _dbus_assert (server->refcount > 0);
 277
 278   server->refcount -= 1;
 279   if (server->refcount == 0)
 280     {
 281       _dbus_assert (server->vtable->finalize != NULL);
 282
 283       (* server->vtable->finalize) (server);
 284     }
 285 }
 286
 287 /**
 288  * Releases the server's address and stops listening for
 289  * new clients. If called more than once, only the first
 290  * call has an effect. Does not modify the server's
 291  * reference count.
 292  *
 293  * @param server the server.
 294  */
 295 void
 296 dbus_server_disconnect (DBusServer *server)
 297 {
 298   _dbus_assert (server->vtable->disconnect != NULL);
 299
 300   if (server->disconnected)
 301     return;
 302
 303   (* server->vtable->disconnect) (server);
 304   server->disconnected = TRUE;
 305 }
 306
 307 /**
 308  * Returns #TRUE if the server is still listening for new connections.
 309  *
 310  * @param server the server.
 311  */
 312 dbus_bool_t
 313 dbus_server_get_is_connected (DBusServer *server)
 314 {
 315   return !server->disconnected;
 316 }
 317
 318 /**
 319  * Sets a function to be used for handling new connections.  The given
 320  * function is passed each new connection as the connection is
 321  * created. If the new connection function increments the connection's
 322  * reference count, the connection will stay alive. Otherwise, the
 323  * connection will be unreferenced and closed.
 324  *
 325  * @param server the server.
 326  * @param function a function to handle new connections.
 327  * @param data data to pass to the new connection handler.
 328  * @param free_data_function function to free the data.
 329  */
 330 void
 331 dbus_server_set_new_connection_function (DBusServer                *server,
 332                                          DBusNewConnectionFunction  function,
 333                                          void                      *data,
 334                                          DBusFreeFunction           free_data_function)
 335 {
 336   if (server->new_connection_free_data_function != NULL)
 337     (* server->new_connection_free_data_function) (server->new_connection_data);
 338
 339   server->new_connection_function = function;
 340   server->new_connection_data = data;
 341   server->new_connection_free_data_function = free_data_function;
 342 }
 343
 344 /**
 345  * Sets the watch functions for the connection. These functions are
 346  * responsible for making the application's main loop aware of file
 347  * descriptors that need to be monitored for events.
 348  *
 349  * This function behaves exactly like dbus_connection_set_watch_functions();
 350  * see the documentation for that routine.
 351  *
 352  * @param server the server.
 353  * @param add_function function to begin monitoring a new descriptor.
 354  * @param remove_function function to stop monitoring a descriptor.
 355  * @param data data to pass to add_function and remove_function.
 356  * @param free_data_function function to be called to free the data.
 357  */
 358 void
 359 dbus_server_set_watch_functions (DBusServer              *server,
 360                                  DBusAddWatchFunction     add_function,
 361                                  DBusRemoveWatchFunction  remove_function,
 362                                  void                    *data,
 363                                  DBusFreeFunction         free_data_function)
 364 {
 365   _dbus_watch_list_set_functions (server->watches,
 366                                   add_function,
 367                                   remove_function,
 368                                   data,
 369                                   free_data_function);
 370 }
 371
 372 /**
 373  * Sets the timeout functions for the connection. These functions are
 374  * responsible for making the application's main loop aware of timeouts.
 375  *
 376  * This function behaves exactly like dbus_connection_set_timeout_functions();
 377  * see the documentation for that routine.
 378  *
 379  * @param server the server.
 380  * @param add_function function to add a timeout.
 381  * @param remove_function function to remove a timeout.
 382  * @param data data to pass to add_function and remove_function.
 383  * @param free_data_function function to be called to free the data.
 384  */
 385 void
 386 dbus_server_set_timeout_functions (DBusServer                *server,
 387                                    DBusAddTimeoutFunction     add_function,
 388                                    DBusRemoveTimeoutFunction  remove_function,
 389                                    void                      *data,
 390                                    DBusFreeFunction           free_data_function)
 391 {
 392   _dbus_timeout_list_set_functions (server->timeouts,
 393                                     add_function, remove_function,
 394                                     data, free_data_function);
 395 }
 396
 397 /**
 398  * Called to notify the server when a previously-added watch
 399  * is ready for reading or writing, or has an exception such
 400  * as a hangup.
 401  *
 402  * @param server the server.
 403  * @param watch the watch.
 404  * @param condition the current condition of the file descriptors being watched.
 405  */
 406 void
 407 dbus_server_handle_watch (DBusServer              *server,
 408                           DBusWatch               *watch,
 409                           unsigned int             condition)
 410 {
 411   _dbus_assert (server->vtable->handle_watch != NULL);
 412
 413   _dbus_watch_sanitize_condition (watch, &condition);
 414
 415   (* server->vtable->handle_watch) (server, watch, condition);
 416 }
 417
 418 /**
 419  * Sets the maximum number of connections that can be open at one
 420  * time for this server. If the maximum is reached, and another
 421  * client tries to connect, then the oldest unauthenticated client
 422  * will be dropped. If no unauthenticated client exists, then
 423  * the new connection will be refused.
 424  *
 425  * If the maximum is set to a number lower than the current
 426  * number of connections, no current connections are
 427  * disconnected.
 428  *
 429  * @todo honoring max_connections has not been implemented
 430  * yet. The only real work involved is keeping a list
 431  * of live connections on the DBusServer so the oldest
 432  * unauthenticated client can be located when required.
 433  *
 434  * @todo for a systemwide daemon, we need a max number of connections
 435  * per user, since any user can authenticate a bunch of connections
 436  * and create a DOS.
 437  *
 438  * @todo a single process might listen on multiple mechanisms
 439  * (multiple DBusServer) and might want the max connections
 440  * value to span all those servers. Should consider
 441  * changing the API accordingly, though I'm inclined to
 442  * punt this to the app that wants to do it instead of
 443  * putting it in the library.
 444  *
 445  * @param server the server
 446  * @param max_connections maximum number of connections allowed
 447  */
 448 void
 449 dbus_server_set_max_connections (DBusServer *server,
 450                                  int         max_connections)
 451 {
 452   server->max_connections = max_connections;
 453 }
 454
 455 /**
 456  * Gets the maximum number of connections that can be active
 457  * at a time for this server.
 458  *
 459  * @param server the server
 460  * @returns maximum number of connections at once
 461  */
 462 int
 463 dbus_server_get_max_connections (DBusServer *server)
 464 {
 465   return server->max_connections;
 466 }
 467
 468 /**
 469  * Gets the number of #DBusConnection to this server that
 470  * have not yet been finalized. i.e. all #DBusConnection that
 471  * were passed to #DBusNewConnectionFunction and have not yet been
 472  * finalized will count in this total.
 473  *
 474  * @param server the server
 475  * @returns the number of connections
 476  */
 477 int
 478 dbus_server_get_n_connections (DBusServer *server)
 479 {
 480   return _dbus_counter_get_value (server->connection_counter);
 481 }
 482
 483 /** @} */
 484