GDBusConnection: allow async property handling

[platform/upstream/glib.git] / gio / gdbusconnection.h

diff --git a/gio/gdbusconnection.h b/gio/gdbusconnection.h
index 1325e37..02caedc 100644 (file)
--- a/gio/gdbusconnection.h
+++ b/gio/gdbusconnection.h
@@ -340,9 +340,38 @@ typedef gboolean  (*GDBusInterfaceSetPropertyFunc) (GDBusConnection       *conne
  * Virtual table for handling properties and method calls for a D-Bus
  * interface.
  *
- * If you want to handle getting/setting D-Bus properties asynchronously, simply
- * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
- * D-Bus interface using g_dbus_connection_register_object().
+ * Since 2.38, if you want to handle getting/setting D-Bus properties
+ * asynchronously, give %NULL as your get_property() or set_property()
+ * function.  The D-Bus call will be directed to your @method_call
+ * function, with the provided @interface_name set to
+ * <literal>"org.freedesktop.DBus.Properties"</literal>.
+ *
+ * The usual checks on the validity of the calls is performed.  For
+ * <literal>'Get'</literal> calls, an error is automatically returned if
+ * the property does not exist or the permissions do not allow access.
+ * The same checks are performed for <literal>'Set'</literal> calls, and
+ * the provided value is also checked for being the correct type.
+ *
+ * For both <literal>'Get'</literal> and <literal>'Set'</literal> calls,
+ * the #GDBusMethodInvocation passed to the method_call handler can be
+ * queried with g_dbus_method_invocation_get_property_info() to get a
+ * pointer to the #GDBusPropertyInfo of the property.
+ *
+ * If you have readable properties specified in your interface info, you
+ * must ensure that you either provide a non-%NULL @get_property()
+ * function or provide implementations of both the
+ * <literal>'Get'</literal> and <literal>'GetAll'</literal> methods on
+ * the <literal>'org.freedesktop.DBus.Properties'</literal> interface in
+ * your @method_call function.  Note that the required return type of
+ * the <literal>'Get'</literal> call is <literal>(v)</literal>, not the
+ * type of the property.  <literal>'GetAll'</literal> expects a return
+ * value of type <literal>a{sv}<literal>.
+ *
+ * If you have writable properties specified in your interface info, you
+ * must ensure that you either provide a non-%NULL @set_property()
+ * function or provide an implementation of the <literal>'Set'</literal>
+ * call.  If implementing the call, you must return the value of type
+ * %G_VARIANT_TYPE_UNIT.
  *
  * Since: 2.26
  */