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  * @todo error messages on bad address could really be better.
 195  * DBusResultCode is a bit limiting here.
 196  *
 197  * @param address the address of this server.
 198  * @param result location to store rationale for failure.
 199  * @returns a new DBusServer, or #NULL on failure.
 200  *
 201  */
 202 DBusServer*
 203 dbus_server_listen (const char     *address,
 204                     DBusResultCode *result)
 205 {
 206   DBusServer *server;
 207   DBusAddressEntry **entries;
 208   int len, i;
 209
 210   if (!dbus_parse_address (address, &entries, &len, result))
 211     return NULL;
 212
 213   server = NULL;
 214
 215   for (i = 0; i < len; i++)
 216     {
 217       const char *method = dbus_address_entry_get_method (entries[i]);
 218
 219       if (strcmp (method, "unix") == 0)
 220         {
 221           const char *path = dbus_address_entry_get_value (entries[i], "path");
 222
 223           if (path == NULL)
 224             goto bad_address;
 225
 226           server = _dbus_server_new_for_domain_socket (path, result);
 227
 228           if (server)
 229             break;
 230         }
 231       else if (strcmp (method, "debug") == 0)
 232         {
 233           const char *name = dbus_address_entry_get_value (entries[i], "name");
 234
 235           if (name == NULL)
 236             goto bad_address;
 237
 238           server = _dbus_server_debug_new (name, result);
 239
 240           if (server)
 241             break;
 242         }
 243       else
 244         goto bad_address;
 245     }
 246
 247   dbus_address_entries_free (entries);
 248   return server;
 249
 250  bad_address:
 251   dbus_address_entries_free (entries);
 252   dbus_set_result (result, DBUS_RESULT_BAD_ADDRESS);
 253
 254   return NULL;
 255 }
 256
 257 /**
 258  * Increments the reference count of a DBusServer.
 259  *
 260  * @param server the server.
 261  */
 262 void
 263 dbus_server_ref (DBusServer *server)
 264 {
 265   server->refcount += 1;
 266 }
 267
 268 /**
 269  * Decrements the reference count of a DBusServer.  Finalizes the
 270  * server if the reference count reaches zero. The server connection
 271  * will be closed as with dbus_server_disconnect() when the server is
 272  * finalized.
 273  *
 274  * @param server the server.
 275  */
 276 void
 277 dbus_server_unref (DBusServer *server)
 278 {
 279   _dbus_assert (server != NULL);
 280   _dbus_assert (server->refcount > 0);
 281
 282   server->refcount -= 1;
 283   if (server->refcount == 0)
 284     {
 285       _dbus_assert (server->vtable->finalize != NULL);
 286
 287       (* server->vtable->finalize) (server);
 288     }
 289 }
 290
 291 /**
 292  * Releases the server's address and stops listening for
 293  * new clients. If called more than once, only the first
 294  * call has an effect. Does not modify the server's
 295  * reference count.
 296  *
 297  * @param server the server.
 298  */
 299 void
 300 dbus_server_disconnect (DBusServer *server)
 301 {
 302   _dbus_assert (server->vtable->disconnect != NULL);
 303
 304   if (server->disconnected)
 305     return;
 306
 307   (* server->vtable->disconnect) (server);
 308   server->disconnected = TRUE;
 309 }
 310
 311 /**
 312  * Returns #TRUE if the server is still listening for new connections.
 313  *
 314  * @param server the server.
 315  */
 316 dbus_bool_t
 317 dbus_server_get_is_connected (DBusServer *server)
 318 {
 319   return !server->disconnected;
 320 }
 321
 322 /**
 323  * Sets a function to be used for handling new connections.  The given
 324  * function is passed each new connection as the connection is
 325  * created. If the new connection function increments the connection's
 326  * reference count, the connection will stay alive. Otherwise, the
 327  * connection will be unreferenced and closed.
 328  *
 329  * @param server the server.
 330  * @param function a function to handle new connections.
 331  * @param data data to pass to the new connection handler.
 332  * @param free_data_function function to free the data.
 333  */
 334 void
 335 dbus_server_set_new_connection_function (DBusServer                *server,
 336                                          DBusNewConnectionFunction  function,
 337                                          void                      *data,
 338                                          DBusFreeFunction           free_data_function)
 339 {
 340   if (server->new_connection_free_data_function != NULL)
 341     (* server->new_connection_free_data_function) (server->new_connection_data);
 342
 343   server->new_connection_function = function;
 344   server->new_connection_data = data;
 345   server->new_connection_free_data_function = free_data_function;
 346 }
 347
 348 /**
 349  * Sets the watch functions for the connection. These functions are
 350  * responsible for making the application's main loop aware of file
 351  * descriptors that need to be monitored for events.
 352  *
 353  * This function behaves exactly like dbus_connection_set_watch_functions();
 354  * see the documentation for that routine.
 355  *
 356  * @param server the server.
 357  * @param add_function function to begin monitoring a new descriptor.
 358  * @param remove_function function to stop monitoring a descriptor.
 359  * @param data data to pass to add_function and remove_function.
 360  * @param free_data_function function to be called to free the data.
 361  */
 362 void
 363 dbus_server_set_watch_functions (DBusServer              *server,
 364                                  DBusAddWatchFunction     add_function,
 365                                  DBusRemoveWatchFunction  remove_function,
 366                                  void                    *data,
 367                                  DBusFreeFunction         free_data_function)
 368 {
 369   _dbus_watch_list_set_functions (server->watches,
 370                                   add_function,
 371                                   remove_function,
 372                                   data,
 373                                   free_data_function);
 374 }
 375
 376 /**
 377  * Sets the timeout functions for the connection. These functions are
 378  * responsible for making the application's main loop aware of timeouts.
 379  *
 380  * This function behaves exactly like dbus_connection_set_timeout_functions();
 381  * see the documentation for that routine.
 382  *
 383  * @param server the server.
 384  * @param add_function function to add a timeout.
 385  * @param remove_function function to remove a timeout.
 386  * @param data data to pass to add_function and remove_function.
 387  * @param free_data_function function to be called to free the data.
 388  */
 389 void
 390 dbus_server_set_timeout_functions (DBusServer                *server,
 391                                    DBusAddTimeoutFunction     add_function,
 392                                    DBusRemoveTimeoutFunction  remove_function,
 393                                    void                      *data,
 394                                    DBusFreeFunction           free_data_function)
 395 {
 396   _dbus_timeout_list_set_functions (server->timeouts,
 397                                     add_function, remove_function,
 398                                     data, free_data_function);
 399 }
 400
 401 /**
 402  * Called to notify the server when a previously-added watch
 403  * is ready for reading or writing, or has an exception such
 404  * as a hangup.
 405  *
 406  * @param server the server.
 407  * @param watch the watch.
 408  * @param condition the current condition of the file descriptors being watched.
 409  */
 410 void
 411 dbus_server_handle_watch (DBusServer              *server,
 412                           DBusWatch               *watch,
 413                           unsigned int             condition)
 414 {
 415   _dbus_assert (server->vtable->handle_watch != NULL);
 416
 417   _dbus_watch_sanitize_condition (watch, &condition);
 418
 419   (* server->vtable->handle_watch) (server, watch, condition);
 420 }
 421
 422 /**
 423  * Sets the maximum number of connections that can be open at one
 424  * time for this server. If the maximum is reached, and another
 425  * client tries to connect, then the oldest unauthenticated client
 426  * will be dropped. If no unauthenticated client exists, then
 427  * the new connection will be refused.
 428  *
 429  * If the maximum is set to a number lower than the current
 430  * number of connections, no current connections are
 431  * disconnected.
 432  *
 433  * @todo honoring max_connections has not been implemented
 434  * yet. The only real work involved is keeping a list
 435  * of live connections on the DBusServer so the oldest
 436  * unauthenticated client can be located when required.
 437  *
 438  * @todo for a systemwide daemon, we need a max number of connections
 439  * per user, since any user can authenticate a bunch of connections
 440  * and create a DOS.
 441  *
 442  * @todo a single process might listen on multiple mechanisms
 443  * (multiple DBusServer) and might want the max connections
 444  * value to span all those servers. Should consider
 445  * changing the API accordingly, though I'm inclined to
 446  * punt this to the app that wants to do it instead of
 447  * putting it in the library.
 448  *
 449  * @param server the server
 450  * @param max_connections maximum number of connections allowed
 451  */
 452 void
 453 dbus_server_set_max_connections (DBusServer *server,
 454                                  int         max_connections)
 455 {
 456   server->max_connections = max_connections;
 457 }
 458
 459 /**
 460  * Gets the maximum number of connections that can be active
 461  * at a time for this server.
 462  *
 463  * @param server the server
 464  * @returns maximum number of connections at once
 465  */
 466 int
 467 dbus_server_get_max_connections (DBusServer *server)
 468 {
 469   return server->max_connections;
 470 }
 471
 472 /**
 473  * Gets the number of #DBusConnection to this server that
 474  * have not yet been finalized. i.e. all #DBusConnection that
 475  * were passed to #DBusNewConnectionFunction and have not yet been
 476  * finalized will count in this total.
 477  *
 478  * @param server the server
 479  * @returns the number of connections
 480  */
 481 int
 482 dbus_server_get_n_connections (DBusServer *server)
 483 {
 484   return _dbus_counter_get_value (server->connection_counter);
 485 }
 486
 487 /** @} */
 488