X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gio%2Fgdbusconnection.h;h=8ffd094932129a30bbf1e0be5d4711e50e57c2c3;hb=7e5e3e142f856ac80e83a9a5110b51aa4b5b0821;hp=92d477f9599ad00320828e4fc2861da6199e69ac;hpb=3ff9894826215790fdd6c8b53584f94a7172c39f;p=platform%2Fupstream%2Fglib.git
diff --git a/gio/gdbusconnection.h b/gio/gdbusconnection.h
index 92d477f..8ffd094 100644
--- a/gio/gdbusconnection.h
+++ b/gio/gdbusconnection.h
@@ -13,20 +13,18 @@
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see .
*
* Author: David Zeuthen
*/
+#ifndef __G_DBUS_CONNECTION_H__
+#define __G_DBUS_CONNECTION_H__
+
#if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
#error "Only can be included directly."
#endif
-#ifndef __G_DBUS_CONNECTION_H__
-#define __G_DBUS_CONNECTION_H__
-
#include
G_BEGIN_DECLS
@@ -35,22 +33,27 @@ G_BEGIN_DECLS
#define G_DBUS_CONNECTION(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), G_TYPE_DBUS_CONNECTION, GDBusConnection))
#define G_IS_DBUS_CONNECTION(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_CONNECTION))
+GLIB_AVAILABLE_IN_ALL
GType g_dbus_connection_get_type (void) G_GNUC_CONST;
/* ---------------------------------------------------------------------------------------------------- */
+GLIB_AVAILABLE_IN_ALL
void g_bus_get (GBusType bus_type,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
+GLIB_AVAILABLE_IN_ALL
GDBusConnection *g_bus_get_finish (GAsyncResult *res,
GError **error);
+GLIB_AVAILABLE_IN_ALL
GDBusConnection *g_bus_get_sync (GBusType bus_type,
GCancellable *cancellable,
GError **error);
/* ---------------------------------------------------------------------------------------------------- */
+GLIB_AVAILABLE_IN_ALL
void g_dbus_connection_new (GIOStream *stream,
const gchar *guid,
GDBusConnectionFlags flags,
@@ -58,8 +61,10 @@ void g_dbus_connection_new (GIOStream
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
+GLIB_AVAILABLE_IN_ALL
GDBusConnection *g_dbus_connection_new_finish (GAsyncResult *res,
GError **error);
+GLIB_AVAILABLE_IN_ALL
GDBusConnection *g_dbus_connection_new_sync (GIOStream *stream,
const gchar *guid,
GDBusConnectionFlags flags,
@@ -67,14 +72,17 @@ GDBusConnection *g_dbus_connection_new_sync (GIOStream
GCancellable *cancellable,
GError **error);
+GLIB_AVAILABLE_IN_ALL
void g_dbus_connection_new_for_address (const gchar *address,
GDBusConnectionFlags flags,
GDBusAuthObserver *observer,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
+GLIB_AVAILABLE_IN_ALL
GDBusConnection *g_dbus_connection_new_for_address_finish (GAsyncResult *res,
GError **error);
+GLIB_AVAILABLE_IN_ALL
GDBusConnection *g_dbus_connection_new_for_address_sync (const gchar *address,
GDBusConnectionFlags flags,
GDBusAuthObserver *observer,
@@ -83,50 +91,111 @@ GDBusConnection *g_dbus_connection_new_for_address_sync (const gchar
/* ---------------------------------------------------------------------------------------------------- */
+GLIB_AVAILABLE_IN_2_40
+gchar *g_dbus_get_bus_id (GDBusConnection *connection,
+ gint timeout_msec,
+ GError **error);
+GLIB_AVAILABLE_IN_2_40
+gchar **g_dbus_get_list_names (GDBusConnection *connection,
+ gint timeout_msec,
+ GError **error);
+GLIB_AVAILABLE_IN_2_40
+gchar **g_dbus_get_list_activatable_names (GDBusConnection *connection,
+ gint timeout_msec,
+ GError **error);
+GLIB_AVAILABLE_IN_2_40
+gchar **g_dbus_get_list_queued_owners (GDBusConnection *connection,
+ const gchar *name,
+ gint timeout_msec,
+ GError **error);
+GLIB_AVAILABLE_IN_2_40
+gchar *g_dbus_get_name_owner (GDBusConnection *connection,
+ const gchar *name,
+ gint timeout_msec,
+ GError **error);
+GLIB_AVAILABLE_IN_2_40
+gboolean g_dbus_name_has_owner (GDBusConnection *connection,
+ const gchar *name,
+ gint timeout_msec,
+ GError **error);
+GLIB_AVAILABLE_IN_2_40
+guint32 g_dbus_get_connection_pid (GDBusConnection *connection,
+ const gchar *name,
+ gint timeout_msec,
+ GError **error);
+GLIB_AVAILABLE_IN_2_40
+guint32 g_dbus_get_connection_uid (GDBusConnection *connection,
+ const gchar *name,
+ gint timeout_msec,
+ GError **error);
+
+/* ---------------------------------------------------------------------------------------------------- */
+
+GLIB_AVAILABLE_IN_ALL
void g_dbus_connection_start_message_processing (GDBusConnection *connection);
+GLIB_AVAILABLE_IN_ALL
gboolean g_dbus_connection_is_closed (GDBusConnection *connection);
+GLIB_AVAILABLE_IN_ALL
GIOStream *g_dbus_connection_get_stream (GDBusConnection *connection);
+GLIB_AVAILABLE_IN_ALL
const gchar *g_dbus_connection_get_guid (GDBusConnection *connection);
+GLIB_AVAILABLE_IN_ALL
const gchar *g_dbus_connection_get_unique_name (GDBusConnection *connection);
+GLIB_AVAILABLE_IN_ALL
GCredentials *g_dbus_connection_get_peer_credentials (GDBusConnection *connection);
+
+GLIB_AVAILABLE_IN_2_34
+guint32 g_dbus_connection_get_last_serial (GDBusConnection *connection);
+
+GLIB_AVAILABLE_IN_ALL
gboolean g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
+GLIB_AVAILABLE_IN_ALL
void g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
gboolean exit_on_close);
+GLIB_AVAILABLE_IN_ALL
GDBusCapabilityFlags g_dbus_connection_get_capabilities (GDBusConnection *connection);
/* ---------------------------------------------------------------------------------------------------- */
+GLIB_AVAILABLE_IN_ALL
void g_dbus_connection_close (GDBusConnection *connection,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
+GLIB_AVAILABLE_IN_ALL
gboolean g_dbus_connection_close_finish (GDBusConnection *connection,
GAsyncResult *res,
GError **error);
+GLIB_AVAILABLE_IN_ALL
gboolean g_dbus_connection_close_sync (GDBusConnection *connection,
GCancellable *cancellable,
GError **error);
/* ---------------------------------------------------------------------------------------------------- */
+GLIB_AVAILABLE_IN_ALL
void g_dbus_connection_flush (GDBusConnection *connection,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
+GLIB_AVAILABLE_IN_ALL
gboolean g_dbus_connection_flush_finish (GDBusConnection *connection,
GAsyncResult *res,
GError **error);
+GLIB_AVAILABLE_IN_ALL
gboolean g_dbus_connection_flush_sync (GDBusConnection *connection,
GCancellable *cancellable,
GError **error);
/* ---------------------------------------------------------------------------------------------------- */
+GLIB_AVAILABLE_IN_ALL
gboolean g_dbus_connection_send_message (GDBusConnection *connection,
GDBusMessage *message,
GDBusSendMessageFlags flags,
volatile guint32 *out_serial,
GError **error);
+GLIB_AVAILABLE_IN_ALL
void g_dbus_connection_send_message_with_reply (GDBusConnection *connection,
GDBusMessage *message,
GDBusSendMessageFlags flags,
@@ -135,9 +204,11 @@ void g_dbus_connection_send_message_with_reply (GDBusConnecti
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
+GLIB_AVAILABLE_IN_ALL
GDBusMessage *g_dbus_connection_send_message_with_reply_finish (GDBusConnection *connection,
GAsyncResult *res,
GError **error);
+GLIB_AVAILABLE_IN_ALL
GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnection *connection,
GDBusMessage *message,
GDBusSendMessageFlags flags,
@@ -148,6 +219,7 @@ GDBusMessage *g_dbus_connection_send_message_with_reply_sync (GDBusConnecti
/* ---------------------------------------------------------------------------------------------------- */
+GLIB_AVAILABLE_IN_ALL
gboolean g_dbus_connection_emit_signal (GDBusConnection *connection,
const gchar *destination_bus_name,
const gchar *object_path,
@@ -155,6 +227,7 @@ gboolean g_dbus_connection_emit_signal (GDBusConnection
const gchar *signal_name,
GVariant *parameters,
GError **error);
+GLIB_AVAILABLE_IN_ALL
void g_dbus_connection_call (GDBusConnection *connection,
const gchar *bus_name,
const gchar *object_path,
@@ -167,9 +240,11 @@ void g_dbus_connection_call (GDBusConnection
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
+GLIB_AVAILABLE_IN_ALL
GVariant *g_dbus_connection_call_finish (GDBusConnection *connection,
GAsyncResult *res,
GError **error);
+GLIB_AVAILABLE_IN_ALL
GVariant *g_dbus_connection_call_sync (GDBusConnection *connection,
const gchar *bus_name,
const gchar *object_path,
@@ -181,6 +256,39 @@ GVariant *g_dbus_connection_call_sync (GDBusConnection
gint timeout_msec,
GCancellable *cancellable,
GError **error);
+GLIB_AVAILABLE_IN_2_30
+void g_dbus_connection_call_with_unix_fd_list (GDBusConnection *connection,
+ const gchar *bus_name,
+ const gchar *object_path,
+ const gchar *interface_name,
+ const gchar *method_name,
+ GVariant *parameters,
+ const GVariantType *reply_type,
+ GDBusCallFlags flags,
+ gint timeout_msec,
+ GUnixFDList *fd_list,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+GLIB_AVAILABLE_IN_2_30
+GVariant *g_dbus_connection_call_with_unix_fd_list_finish (GDBusConnection *connection,
+ GUnixFDList **out_fd_list,
+ GAsyncResult *res,
+ GError **error);
+GLIB_AVAILABLE_IN_2_30
+GVariant *g_dbus_connection_call_with_unix_fd_list_sync (GDBusConnection *connection,
+ const gchar *bus_name,
+ const gchar *object_path,
+ const gchar *interface_name,
+ const gchar *method_name,
+ GVariant *parameters,
+ const GVariantType *reply_type,
+ GDBusCallFlags flags,
+ gint timeout_msec,
+ GUnixFDList *fd_list,
+ GUnixFDList **out_fd_list,
+ GCancellable *cancellable,
+ GError **error);
/* ---------------------------------------------------------------------------------------------------- */
@@ -193,7 +301,7 @@ GVariant *g_dbus_connection_call_sync (GDBusConnection
* @interface_name: The D-Bus interface name the method was invoked on.
* @method_name: The name of the method that was invoked.
* @parameters: A #GVariant tuple with parameters.
- * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
+ * @invocation: (transfer full): A #GDBusMethodInvocation object that must be used to return a value or error.
* @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
*
* The type of the @method_call function in #GDBusInterfaceVTable.
@@ -221,7 +329,9 @@ typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
*
* The type of the @get_property function in #GDBusInterfaceVTable.
*
- * Returns: A newly-allocated #GVariant with the value for @property_name or %NULL if @error is set.
+ * Returns: A #GVariant with the value for @property_name or %NULL if
+ * @error is set. If the returned #GVariant is floating, it is
+ * consumed - otherwise its reference count is decreased by one.
*
* Since: 2.26
*/
@@ -268,9 +378,44 @@ 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 org.freedesktop.DBus.Properties
- * 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 "org.freedesktop.DBus.Properties".
+ *
+ * Ownership of the #GDBusMethodInvocation object passed to the
+ * method_call() function is transferred to your handler; you must
+ * call one of the methods of #GDBusMethodInvocation to return a reply
+ * (possibly empty), or an error. These functions also take ownership
+ * of the passed-in invocation object, so unless the invocation
+ * object has otherwise been referenced, it will be then be freed.
+ * Calling one of these functions may be done within your
+ * method_call() implementation but it also can be done at a later
+ * point to handle the method asynchronously.
+ *
+ * The usual checks on the validity of the calls is performed. For
+ * `Get` 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 `Set` calls, and the provided value is also checked for
+ * being the correct type.
+ *
+ * For both `Get` and `Set` 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 `Get` and `GetAll`
+ * methods on org.freedesktop.DBus.Properties interface in your @method_call
+ * function. Note that the required return type of the `Get` call is
+ * `(v)`, not the type of the property. `GetAll` expects a return value
+ * of type `a{sv}`.
+ *
+ * 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 `Set` call. If implementing
+ * the call, you must return the value of type %G_VARIANT_TYPE_UNIT.
*
* Since: 2.26
*/
@@ -288,6 +433,7 @@ struct _GDBusInterfaceVTable
gpointer padding[8];
};
+GLIB_AVAILABLE_IN_ALL
guint g_dbus_connection_register_object (GDBusConnection *connection,
const gchar *object_path,
GDBusInterfaceInfo *interface_info,
@@ -295,6 +441,7 @@ guint g_dbus_connection_register_object (GDBusConnection
gpointer user_data,
GDestroyNotify user_data_free_func,
GError **error);
+GLIB_AVAILABLE_IN_ALL
gboolean g_dbus_connection_unregister_object (GDBusConnection *connection,
guint registration_id);
@@ -416,6 +563,7 @@ struct _GDBusSubtreeVTable
gpointer padding[8];
};
+GLIB_AVAILABLE_IN_ALL
guint g_dbus_connection_register_subtree (GDBusConnection *connection,
const gchar *object_path,
const GDBusSubtreeVTable *vtable,
@@ -423,6 +571,7 @@ guint g_dbus_connection_register_subtree (GDBusConnection
gpointer user_data,
GDestroyNotify user_data_free_func,
GError **error);
+GLIB_AVAILABLE_IN_ALL
gboolean g_dbus_connection_unregister_subtree (GDBusConnection *connection,
guint registration_id);
@@ -450,6 +599,7 @@ typedef void (*GDBusSignalCallback) (GDBusConnection *connection,
GVariant *parameters,
gpointer user_data);
+GLIB_AVAILABLE_IN_ALL
guint g_dbus_connection_signal_subscribe (GDBusConnection *connection,
const gchar *sender,
const gchar *interface_name,
@@ -460,6 +610,7 @@ guint g_dbus_connection_signal_subscribe (GDBusConnection
GDBusSignalCallback callback,
gpointer user_data,
GDestroyNotify user_data_free_func);
+GLIB_AVAILABLE_IN_ALL
void g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
guint subscription_id);
@@ -467,35 +618,90 @@ void g_dbus_connection_signal_unsubscribe (GDBusConnection
/**
* GDBusMessageFilterFunction:
- * @connection: A #GDBusConnection.
- * @message: A #GDBusMessage.
+ * @connection: (transfer none): A #GDBusConnection.
+ * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
* @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is
* a message to be sent to the other peer.
* @user_data: User data passed when adding the filter.
*
* Signature for function used in g_dbus_connection_add_filter().
*
- * If you modify an outgoing message, make sure to return
- * %G_DBUS_MESSAGE_FILTER_RESULT_MESSAGE_ALTERED instead of
- * %G_DBUS_MESSAGE_FILTER_RESULT_NO_EFFECT so the message can be
- * re-serialized. If an error occurs during re-serialization, a
- * warning will be printed on standard error.
- *
- * Returns: A value from the #GDBusMessageFilterResult enumeration
- * describing what to do with @message.
+ * A filter function is passed a #GDBusMessage and expected to return
+ * a #GDBusMessage too. Passive filter functions that don't modify the
+ * message can simply return the @message object:
+ * |[
+ * static GDBusMessage *
+ * passive_filter (GDBusConnection *connection
+ * GDBusMessage *message,
+ * gboolean incoming,
+ * gpointer user_data)
+ * {
+ * /* inspect @message */
+ * return message;
+ * }
+ * ]|
+ * Filter functions that wants to drop a message can simply return %NULL:
+ * |[
+ * static GDBusMessage *
+ * drop_filter (GDBusConnection *connection
+ * GDBusMessage *message,
+ * gboolean incoming,
+ * gpointer user_data)
+ * {
+ * if (should_drop_message)
+ * {
+ * g_object_unref (message);
+ * message = NULL;
+ * }
+ * return message;
+ * }
+ * ]|
+ * Finally, a filter function may modify a message by copying it:
+ * |[
+ * static GDBusMessage *
+ * modifying_filter (GDBusConnection *connection
+ * GDBusMessage *message,
+ * gboolean incoming,
+ * gpointer user_data)
+ * {
+ * GDBusMessage *copy;
+ * GError *error;
+ *
+ * error = NULL;
+ * copy = g_dbus_message_copy (message, &error);
+ * /* handle @error being is set */
+ * g_object_unref (message);
+ *
+ * /* modify @copy */
+ *
+ * return copy;
+ * }
+ * ]|
+ * If the returned #GDBusMessage is different from @message and cannot
+ * be sent on @connection (it could use features, such as file
+ * descriptors, not compatible with @connection), then a warning is
+ * logged to standard error. Applications can
+ * check this ahead of time using g_dbus_message_to_blob() passing a
+ * #GDBusCapabilityFlags value obtained from @connection.
+ *
+ * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
+ * g_object_unref() or %NULL to drop the message. Passive filter
+ * functions can simply return the passed @message object.
*
* Since: 2.26
*/
-typedef GDBusMessageFilterResult (*GDBusMessageFilterFunction) (GDBusConnection *connection,
- GDBusMessage *message,
- gboolean incoming,
- gpointer user_data);
+typedef GDBusMessage *(*GDBusMessageFilterFunction) (GDBusConnection *connection,
+ GDBusMessage *message,
+ gboolean incoming,
+ gpointer user_data);
+GLIB_AVAILABLE_IN_ALL
guint g_dbus_connection_add_filter (GDBusConnection *connection,
GDBusMessageFilterFunction filter_function,
gpointer user_data,
GDestroyNotify user_data_free_func);
+GLIB_AVAILABLE_IN_ALL
void g_dbus_connection_remove_filter (GDBusConnection *connection,
guint filter_id);