Add remaining examples and g_dbus_connection_send_message*() docs

2 files changed, 131 insertions, 4 deletions

diff --git a/gdbus/gdbusconnection.c b/gdbus/gdbusconnection.c
index a70672a..e921d8f 100644
--- a/gdbus/gdbusconnection.c
+++ b/gdbus/gdbusconnection.c
@@ -67,12 +67,19 @@
  * @include: gdbus/gdbus.h
  *
  * <para><note>
- * This class is rarely used directly. If you are writing an application, it is often
- * easier to use the g_bus_own_name() or g_bus_watch_name() APIs.
+ * This class is rarely used directly in D-Bus clients. If you are
+ * writing an D-Bus client, it is often easier to use the
+ * g_bus_own_name(), g_bus_watch_name() or g_bus_watch_proxy() APIs.
  * </note></para>
-
+ *
  * The #GDBusConnection type is used for D-Bus connections to remote
  * peers such as a message buses.
+ *
+ * <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gdbus/example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ *
+ * <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gdbus/example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ *
+ * <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gdbus/example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
  */
 
 /* ---------------------------------------------------------------------------------------------------- */
@@ -938,6 +945,31 @@ g_dbus_connection_send_message_unlocked (GDBusConnection     *connection,
   return ret;
 }
 
+/**
+ * g_dbus_connection_send_message:
+ * @connection: A #GDBusConnection.
+ * @message: A #GDBusMessage
+ * @out_serial: Return location for serial number assigned to @message when sending it or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Asynchronously sends @message to the peer represented by @connection.
+ *
+ * If @out_serial is not %NULL, then the serial number assigned to
+ * @message by @connection will be written to this location prior to
+ * submitting the message to the underlying transport.
+ *
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+ * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
+ * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ *
+ * See <xref linkend="gdbus-server"/> and <xref
+ * linkend="gdbus-unix-fd-client"/> for an example of how to use this
+ * low-level API to send and receive UNIX file descriptors.
+ *
+ * Returns: %TRUE if the message was well-formed and queued for
+ * transmission, %FALSE if @error is set.
+ */
 gboolean
 g_dbus_connection_send_message (GDBusConnection     *connection,
                                 GDBusMessage        *message,
@@ -1220,6 +1252,38 @@ g_dbus_connection_send_message_with_reply_unlocked (GDBusConnection     *connect
   ;
 }
 
+/**
+ * g_dbus_connection_send_message_with_reply:
+ * @connection: A #GDBusConnection.
+ * @message: A #GDBusMessage.
+ * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
+ * @out_serial: Return location for serial number assigned to @message when sending it or %NULL.
+ * @cancellable: A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
+ * care about the result.
+ * @user_data: The data to pass to @callback.
+ *
+ * Asynchronously sends @message to the peer represented by @connection.
+ *
+ * If @out_serial is not %NULL, then the serial number assigned to
+ * @message by @connection will be written to this location prior to
+ * submitting the message to the underlying transport.
+ *
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+ * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
+ * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ *
+ * This is an asynchronous method. When the operation is finished, @callback will be invoked
+ * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * of the thread you are calling this method from. You can then call
+ * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
+ * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
+ *
+ * See <xref linkend="gdbus-server"/> and <xref
+ * linkend="gdbus-unix-fd-client"/> for an example of how to use this
+ * low-level API to send and receive UNIX file descriptors.
+ */
 void
 g_dbus_connection_send_message_with_reply (GDBusConnection     *connection,
                                            GDBusMessage        *message,
@@ -1244,6 +1308,24 @@ g_dbus_connection_send_message_with_reply (GDBusConnection     *connection,
   CONNECTION_UNLOCK (connection);
 }
 
+/**
+ * g_dbus_connection_send_message_with_reply_finish:
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply().
+ * @error: Return location for error or %NULL.
+ *
+ * Finishes an operation started with g_dbus_connection_send_message_with_reply().
+ *
+ * Note that @error is only set if a local in-process error
+ * occured. That is to say that the returned #GDBusMessage object may
+ * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
+ * g_dbus_message_to_gerror() to transcode this to a #GError.
+ *
+ * See <xref linkend="gdbus-server"/> and <xref
+ * linkend="gdbus-unix-fd-client"/> for an example of how to use this
+ * low-level API to send and receive UNIX file descriptors.
+ *
+ * Returns: A #GDBusMessage or %NULL if @error is set.
+ */
 GDBusMessage *
 g_dbus_connection_send_message_with_reply_finish (GDBusConnection     *connection,
                                                   GAsyncResult        *res,
@@ -1297,6 +1379,40 @@ send_message_with_reply_sync_cb (GDBusConnection *connection,
   g_main_loop_quit (data->loop);
 }
 
+/**
+ * g_dbus_connection_send_message_with_reply_sync:
+ * @connection: A #GDBusConnection.
+ * @message: A #GDBusMessage.
+ * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
+ * @out_serial: Return location for serial number assigned to @message when sending it or %NULL.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Synchronously sends @message to the peer represented by @connection
+ * and blocks the calling thread until a reply is received or the
+ * timeout is reached. See g_dbus_connection_send_message_with_reply()
+ * for the asynchronous version of this method.
+ *
+ * If @out_serial is not %NULL, then the serial number assigned to
+ * @message by @connection will be written to this location prior to
+ * submitting the message to the underlying transport.
+ *
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+ * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
+ * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ *
+ * Note that @error is only set if a local in-process error
+ * occured. That is to say that the returned #GDBusMessage object may
+ * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
+ * g_dbus_message_to_gerror() to transcode this to a #GError.
+ *
+ * See <xref linkend="gdbus-server"/> and <xref
+ * linkend="gdbus-unix-fd-client"/> for an example of how to use this
+ * low-level API to send and receive UNIX file descriptors.
+ *
+ * Returns: A #GDBusMessage that is the reply to @message or %NULL if @error is set.
+ */
 GDBusMessage *
 g_dbus_connection_send_message_with_reply_sync (GDBusConnection     *connection,
                                                 GDBusMessage        *message,
@@ -3652,6 +3768,8 @@ obj_message_func (GDBusConnection *connection,
  * If an existing callback is already registered at @object_path and
  * @interface_name, then @error is set to #G_IO_ERROR_EXISTS.
  *
+ * See <xref linkend="gdbus-server"/> for an example of how to use this method.
+ *
  * Returns: 0 if @error is set, otherwise a registration id (never 0)
  * that can be used with g_dbus_connection_unregister_object() .
  */
@@ -4538,6 +4656,8 @@ subtree_message_func (GDBusConnection *connection,
  * for object paths not registered via g_dbus_connection_register_object()
  * or other bindings.
  *
+ * See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method.
+ *
  * Returns: 0 if @error is set, otherwise a subtree registration id (never 0)
  * that can be used with g_dbus_connection_unregister_subtree() .
  */
diff --git a/gdbus/gdbusmethodinvocation.c b/gdbus/gdbusmethodinvocation.c
index 28ab3a1..0bd096d 100644
--- a/gdbus/gdbusmethodinvocation.c
+++ b/gdbus/gdbusmethodinvocation.c
@@ -470,7 +470,14 @@ g_dbus_method_invocation_get_connection (GDBusMethodInvocation *invocation)
  * g_dbus_method_invocation_get_message:
  * @invocation: A #GDBusMethodInvocation.
  *
- * Gets the #GDBusMessage for the method invocation.
+ * Gets the #GDBusMessage for the method invocation. This is useful if
+ * you need to use low-level protocol features, such as UNIX file
+ * descriptor passing, that cannot be properly expressed in the
+ * #GVariant API.
+ *
+ * See <xref linkend="gdbus-server"/> and <xref
+ * linkend="gdbus-unix-fd-client"/> for an example of how to use this
+ * low-level API to send and receive UNIX file descriptors.
  *
  * Returns: A #GDBusMessage. Do not free, it is owned by @invocation.
  */