gio/gdbusobjectmanager.c

   1 /* GDBus - GLib D-Bus Library
   2  *
   3  * Copyright (C) 2008-2010 Red Hat, Inc.
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-or-later
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General
  18  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  19  *
  20  * Author: David Zeuthen <davidz@redhat.com>
  21  */
  22
  23 #include "config.h"
  24
  25 #include "gdbusobject.h"
  26 #include "gdbusobjectmanager.h"
  27 #include "gdbusinterface.h"
  28 #include "gdbusutils.h"
  29
  30 #include "glibintl.h"
  31 #include "gmarshal-internal.h"
  32
  33 /**
  34  * SECTION:gdbusobjectmanager
  35  * @short_description: Base type for D-Bus object managers
  36  * @include: gio/gio.h
  37  *
  38  * The #GDBusObjectManager type is the base type for service- and
  39  * client-side implementations of the standardized
  40  * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
  41  * interface.
  42  *
  43  * See #GDBusObjectManagerClient for the client-side implementation
  44  * and #GDBusObjectManagerServer for the service-side implementation.
  45  */
  46
  47 /**
  48  * GDBusObjectManager:
  49  *
  50  * #GDBusObjectManager is an opaque data structure and can only be accessed
  51  * using the following functions.
  52  */
  53
  54 typedef GDBusObjectManagerIface GDBusObjectManagerInterface;
  55 G_DEFINE_INTERFACE (GDBusObjectManager, g_dbus_object_manager, G_TYPE_OBJECT)
  56
  57 enum {
  58   OBJECT_ADDED,
  59   OBJECT_REMOVED,
  60   INTERFACE_ADDED,
  61   INTERFACE_REMOVED,
  62   N_SIGNALS
  63 };
  64
  65 static guint signals[N_SIGNALS];
  66
  67 static void
  68 g_dbus_object_manager_default_init (GDBusObjectManagerIface *iface)
  69 {
  70   /**
  71    * GDBusObjectManager::object-added:
  72    * @manager: The #GDBusObjectManager emitting the signal.
  73    * @object: The #GDBusObject that was added.
  74    *
  75    * Emitted when @object is added to @manager.
  76    *
  77    * Since: 2.30
  78    */
  79   signals[OBJECT_ADDED] =
  80     g_signal_new (I_("object-added"),
  81                   G_TYPE_FROM_INTERFACE (iface),
  82                   G_SIGNAL_RUN_LAST,
  83                   G_STRUCT_OFFSET (GDBusObjectManagerIface, object_added),
  84                   NULL,
  85                   NULL,
  86                   NULL,
  87                   G_TYPE_NONE,
  88                   1,
  89                   G_TYPE_DBUS_OBJECT);
  90
  91   /**
  92    * GDBusObjectManager::object-removed:
  93    * @manager: The #GDBusObjectManager emitting the signal.
  94    * @object: The #GDBusObject that was removed.
  95    *
  96    * Emitted when @object is removed from @manager.
  97    *
  98    * Since: 2.30
  99    */
 100   signals[OBJECT_REMOVED] =
 101     g_signal_new (I_("object-removed"),
 102                   G_TYPE_FROM_INTERFACE (iface),
 103                   G_SIGNAL_RUN_LAST,
 104                   G_STRUCT_OFFSET (GDBusObjectManagerIface, object_removed),
 105                   NULL,
 106                   NULL,
 107                   NULL,
 108                   G_TYPE_NONE,
 109                   1,
 110                   G_TYPE_DBUS_OBJECT);
 111
 112   /**
 113    * GDBusObjectManager::interface-added:
 114    * @manager: The #GDBusObjectManager emitting the signal.
 115    * @object: The #GDBusObject on which an interface was added.
 116    * @interface: The #GDBusInterface that was added.
 117    *
 118    * Emitted when @interface is added to @object.
 119    *
 120    * This signal exists purely as a convenience to avoid having to
 121    * connect signals to all objects managed by @manager.
 122    *
 123    * Since: 2.30
 124    */
 125   signals[INTERFACE_ADDED] =
 126     g_signal_new (I_("interface-added"),
 127                   G_TYPE_FROM_INTERFACE (iface),
 128                   G_SIGNAL_RUN_LAST,
 129                   G_STRUCT_OFFSET (GDBusObjectManagerIface, interface_added),
 130                   NULL,
 131                   NULL,
 132                   _g_cclosure_marshal_VOID__OBJECT_OBJECT,
 133                   G_TYPE_NONE,
 134                   2,
 135                   G_TYPE_DBUS_OBJECT,
 136                   G_TYPE_DBUS_INTERFACE);
 137   g_signal_set_va_marshaller (signals[INTERFACE_ADDED],
 138                               G_TYPE_FROM_INTERFACE (iface),
 139                               _g_cclosure_marshal_VOID__OBJECT_OBJECTv);
 140
 141   /**
 142    * GDBusObjectManager::interface-removed:
 143    * @manager: The #GDBusObjectManager emitting the signal.
 144    * @object: The #GDBusObject on which an interface was removed.
 145    * @interface: The #GDBusInterface that was removed.
 146    *
 147    * Emitted when @interface has been removed from @object.
 148    *
 149    * This signal exists purely as a convenience to avoid having to
 150    * connect signals to all objects managed by @manager.
 151    *
 152    * Since: 2.30
 153    */
 154   signals[INTERFACE_REMOVED] =
 155     g_signal_new (I_("interface-removed"),
 156                   G_TYPE_FROM_INTERFACE (iface),
 157                   G_SIGNAL_RUN_LAST,
 158                   G_STRUCT_OFFSET (GDBusObjectManagerIface, interface_removed),
 159                   NULL,
 160                   NULL,
 161                   _g_cclosure_marshal_VOID__OBJECT_OBJECT,
 162                   G_TYPE_NONE,
 163                   2,
 164                   G_TYPE_DBUS_OBJECT,
 165                   G_TYPE_DBUS_INTERFACE);
 166   g_signal_set_va_marshaller (signals[INTERFACE_REMOVED],
 167                               G_TYPE_FROM_INTERFACE (iface),
 168                               _g_cclosure_marshal_VOID__OBJECT_OBJECTv);
 169
 170 }
 171
 172 /* ---------------------------------------------------------------------------------------------------- */
 173
 174 /**
 175  * g_dbus_object_manager_get_object_path:
 176  * @manager: A #GDBusObjectManager.
 177  *
 178  * Gets the object path that @manager is for.
 179  *
 180  * Returns: A string owned by @manager. Do not free.
 181  *
 182  * Since: 2.30
 183  */
 184 const gchar *
 185 g_dbus_object_manager_get_object_path (GDBusObjectManager *manager)
 186 {
 187   GDBusObjectManagerIface *iface = G_DBUS_OBJECT_MANAGER_GET_IFACE (manager);
 188   return iface->get_object_path (manager);
 189 }
 190
 191 /**
 192  * g_dbus_object_manager_get_objects:
 193  * @manager: A #GDBusObjectManager.
 194  *
 195  * Gets all #GDBusObject objects known to @manager.
 196  *
 197  * Returns: (transfer full) (element-type GDBusObject): A list of
 198  *   #GDBusObject objects. The returned list should be freed with
 199  *   g_list_free() after each element has been freed with
 200  *   g_object_unref().
 201  *
 202  * Since: 2.30
 203  */
 204 GList *
 205 g_dbus_object_manager_get_objects (GDBusObjectManager *manager)
 206 {
 207   GDBusObjectManagerIface *iface = G_DBUS_OBJECT_MANAGER_GET_IFACE (manager);
 208   return iface->get_objects (manager);
 209 }
 210
 211 /**
 212  * g_dbus_object_manager_get_object:
 213  * @manager: A #GDBusObjectManager.
 214  * @object_path: Object path to look up.
 215  *
 216  * Gets the #GDBusObject at @object_path, if any.
 217  *
 218  * Returns: (transfer full) (nullable): A #GDBusObject or %NULL. Free with
 219  *   g_object_unref().
 220  *
 221  * Since: 2.30
 222  */
 223 GDBusObject *
 224 g_dbus_object_manager_get_object (GDBusObjectManager *manager,
 225                                   const gchar        *object_path)
 226 {
 227   GDBusObjectManagerIface *iface = G_DBUS_OBJECT_MANAGER_GET_IFACE (manager);
 228   g_return_val_if_fail (g_variant_is_object_path (object_path), NULL);
 229   return iface->get_object (manager, object_path);
 230 }
 231
 232 /**
 233  * g_dbus_object_manager_get_interface:
 234  * @manager: A #GDBusObjectManager.
 235  * @object_path: Object path to look up.
 236  * @interface_name: D-Bus interface name to look up.
 237  *
 238  * Gets the interface proxy for @interface_name at @object_path, if
 239  * any.
 240  *
 241  * Returns: (transfer full) (nullable): A #GDBusInterface instance or %NULL. Free
 242  *   with g_object_unref().
 243  *
 244  * Since: 2.30
 245  */
 246 GDBusInterface *
 247 g_dbus_object_manager_get_interface (GDBusObjectManager *manager,
 248                                      const gchar        *object_path,
 249                                      const gchar        *interface_name)
 250 {
 251   GDBusObjectManagerIface *iface = G_DBUS_OBJECT_MANAGER_GET_IFACE (manager);
 252   g_return_val_if_fail (g_variant_is_object_path (object_path), NULL);
 253   g_return_val_if_fail (g_dbus_is_interface_name (interface_name), NULL);
 254   return iface->get_interface (manager, object_path, interface_name);
 255 }