diff --git a/docs/reference/gio/gdbus-codegen.xml b/docs/reference/gio/gdbus-codegen.xml index 5f229d4ba..f574b3b15 100644 --- a/docs/reference/gio/gdbus-codegen.xml +++ b/docs/reference/gio/gdbus-codegen.xml @@ -53,8 +53,8 @@ Generating C code - When generating C code, an abstract - #GTypeInterface-derived type is generated for each D-Bus + When generating C code, a + #GInterface-derived type is generated for each D-Bus interface. Additionally, for every generated type, FooBar, two concrete instantiable types, FooBarProxy and FooBarSkeleton, implementing @@ -142,11 +142,11 @@ - + KEY VALUE Used together with and - to annotate the given XML files. It + to annotate the given XML files (for each , there must be exactly one and ). It can be used with interfaces, methods, signals, properties and arguments in the following way: @@ -167,8 +167,13 @@ gdbus-codegen --c-namespace MyApp \ --key dog --value wuff \ myapp-dbus-interfaces.xml ]]> + + Any UTF-8 string can be used for the value of + and . + + @@ -224,7 +229,8 @@ gdbus-codegen --c-namespace MyApp \ When generating C code, this field is used to ensure - function pointer order for preserving ABI/API. + function pointer order for preserving ABI/API, see . When generating Docbook XML, the value of this tag appears @@ -331,7 +337,7 @@ gdbus-codegen --c-namespace MyApp \ As an easier alternative to using the org.gtk.GDBus.DocString annotation, note that - XML parser used by gdbus-codegen parses XML + parser used by gdbus-codegen parses XML comments in a way similar to gtk-doc: + + If both XML comments and + org.gtk.GDBus.DocString or + org.gtk.GDBus.DocString.Short annotations are + present, the latter wins. + @@ -617,7 +629,7 @@ my_app_frobber_proxy_new_sync (GDBusConnection *connection, Note that all property access is via #GDBusProxy's - property cache so no IO is ever done when reading properties. + property cache so no I/O is ever done when reading properties. Also note that setting a property will cause the org.freedesktop.DBus.Properties.Set method to be called on the remote object. This call, however, is asynchronous @@ -697,14 +709,14 @@ on_handle_hello_world (MyAppFrobber *object, &error); ]]> - To facility atomic changesets (multiple properties changing at + To facilitate atomic changesets (multiple properties changing at the same time), #GObject::notify signals are queued up when received. The queue is drained in an idle handler and will cause emissions of the org.freedesktop.DBus.Properties::PropertiesChanged - signal with all the properties that has changed. Use - g_dbus_interface_skeleton_flush() or g_dbus_object_skeleton_flush() to - empty the queue immediately. + signal with all the properties that have changed. Use + g_dbus_interface_skeleton_flush() or + g_dbus_object_skeleton_flush() to empty the queue immediately. @@ -750,20 +762,40 @@ on_handle_hello_world (MyAppFrobber *object, - + Stability Guarantees - No guarantees about the API and ABI of the code generated by - gdbus-codegen are given. This means that code - generated by future versions of this program may have a different - API or ABI even if the underlying D-Bus interface hasn't - changed. As such, always include the generated code in - distribution tarballs and never expose the code in any stable - interfaces. + The generated C functions are guaranteed to not change their ABI + that is, if a method, signal or property does not change its + signature in the introspection XML, the generated C functions will + not change its C ABI either. One exception to this guarantee is if + you are using type 'h' for passing file + descriptors on Unix. Future versions of gdbus-codegen will include + guarantees for this type as well. - Future versions of gdbus-codegen will provide - ABI and API guarantees on the generated code. + The ABI of the generated #GTypes will be preserved only if + the org.gtk.GDBus.Since annotation is used + judiciously — this is because the VTable for the #GInterface + relies on functions pointers for signal handlers. Specifically, if + a D-Bus method, property or signal or is added to a D-Bus + interface, then ABI of the generated #GInterface type is preserved + if, and only if, each added method, property signal is annotated + with they org.gtk.GDBus.Since annotation using + a greater version number than previous versions. + + + The generated C code currently happens to be annotated with gtk-doc / GObject + Introspection comments / annotations. The layout and + contents might change in the future so no guarantees about + e.g. SECTION usage etc. is given. + + + While the generated Docbook for D-Bus interfaces isn't expected to + change, no guarantees are given at this point. diff --git a/docs/reference/gio/migrating-gdbus.xml b/docs/reference/gio/migrating-gdbus.xml index 8977b746a..de6754c2e 100644 --- a/docs/reference/gio/migrating-gdbus.xml +++ b/docs/reference/gio/migrating-gdbus.xml @@ -237,6 +237,9 @@ on_name_acquired (GDBusConnection *connection, +
+ Generating code and docs +
Using gdbus-codegen @@ -297,4 +300,6 @@ gdbus-codegen --interface-prefix org.gtk.GDBus.Example.ObjectManager. \ +
+ diff --git a/gio/gdbusobjectmanagerserver.c b/gio/gdbusobjectmanagerserver.c index 1f348f2f5..ecb90244d 100644 --- a/gio/gdbusobjectmanagerserver.c +++ b/gio/gdbusobjectmanagerserver.c @@ -48,8 +48,10 @@ * clients can keep caches up to date by only listening to D-Bus * signals. * - * See #GDBusObjectManagerClient for the client-side code that is intended to - * be used with #GDBusObjectManagerServer. + * See #GDBusObjectManagerClient for the client-side code that is + * intended to be used with #GDBusObjectManagerServer or any D-Bus + * object implementing the org.freedesktop.DBus.ObjectManager + * interface. */ typedef struct