X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gio%2Fgdbusproxy.c;h=33492b718ca2f3145eeb3bc3dd86d83e40b9bc7c;hb=853692bdfd9f8a87aed70d21f643dc13b57c92d1;hp=f83188e269706bc8cdacbc212858431b3ab877a3;hpb=4b94c0831e449374ce769cb4938a28b3dca59a43;p=platform%2Fupstream%2Fglib.git diff --git a/gio/gdbusproxy.c b/gio/gdbusproxy.c index f83188e..33492b7 100644 --- a/gio/gdbusproxy.c +++ b/gio/gdbusproxy.c @@ -13,9 +13,7 @@ * 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 */ @@ -74,21 +72,20 @@ * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). * * The generic #GDBusProxy::g-properties-changed and - * #GDBusProxy::g-signal signals are not very convenient to work - * with. Therefore, the recommended way of working with proxies is to - * subclass #GDBusProxy, and have more natural properties and signals - * in your derived class. See - * for how this can easily be done using the - * gdbus-codegen - * tool. + * #GDBusProxy::g-signal signals are not very convenient to work with. + * Therefore, the recommended way of working with proxies is to subclass + * #GDBusProxy, and have more natural properties and signals in your derived + * class. This [example][gdbus-example-gdbus-codegen] shows how this can + * easily be done using the [gdbus-codegen][gdbus-codegen] tool. * * A #GDBusProxy instance can be used from multiple threads but note * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed * and #GObject::notify) are emitted in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * of the thread where the instance was constructed. * - * GDBusProxy for a well-known-nameFIXME: MISSING XINCLUDE CONTENT + * An example using a proxy for a well-known name can be found in + * [gdbus-example-watch-proxy.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-proxy.c) */ /* lock protecting the mutable properties: name_owner, timeout_msec, @@ -187,10 +184,10 @@ static void initable_iface_init (GInitableIface *initable_iface); static void async_initable_iface_init (GAsyncInitableIface *async_initable_iface); G_DEFINE_TYPE_WITH_CODE (GDBusProxy, g_dbus_proxy, G_TYPE_OBJECT, + G_ADD_PRIVATE (GDBusProxy) G_IMPLEMENT_INTERFACE (G_TYPE_DBUS_INTERFACE, dbus_interface_iface_init) G_IMPLEMENT_INTERFACE (G_TYPE_INITABLE, initable_iface_init) - G_IMPLEMENT_INTERFACE (G_TYPE_ASYNC_INITABLE, async_initable_iface_init) - ); + G_IMPLEMENT_INTERFACE (G_TYPE_ASYNC_INITABLE, async_initable_iface_init)) static void g_dbus_proxy_dispose (GObject *object) @@ -363,27 +360,23 @@ g_dbus_proxy_class_init (GDBusProxyClass *klass) * Ensure that interactions with this proxy conform to the given * interface. This is mainly to ensure that malformed data received * from the other peer is ignored. The given #GDBusInterfaceInfo is - * said to be the expected interface. + * said to be the "expected interface". * * The checks performed are: - * - * - * When completing a method call, if the type signature of - * the reply message isn't what's expected, the reply is - * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT. - * - * - * Received signals that have a type signature mismatch are dropped and - * a warning is logged via g_warning(). - * - * - * Properties received via the initial GetAll() call - * or via the ::PropertiesChanged signal (on the - * org.freedesktop.DBus.Properties interface) or - * set using g_dbus_proxy_set_cached_property() with a type signature - * mismatch are ignored and a warning is logged via g_warning(). - * - * + * - When completing a method call, if the type signature of + * the reply message isn't what's expected, the reply is + * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT. + * + * - Received signals that have a type signature mismatch are dropped and + * a warning is logged via g_warning(). + * + * - Properties received via the initial `GetAll()` call or via the + * `::PropertiesChanged` signal (on the + * [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) + * interface) or set using g_dbus_proxy_set_cached_property() + * with a type signature mismatch are ignored and a warning is + * logged via g_warning(). + * * Note that these checks are never done on methods, signals and * properties that are not referenced in the given * #GDBusInterfaceInfo, since extending a D-Bus interface on the @@ -592,8 +585,8 @@ g_dbus_proxy_class_init (GDBusProxyClass *klass) * @invalidated_properties will always be empty. * * This signal corresponds to the - * PropertiesChanged D-Bus signal on the - * org.freedesktop.DBus.Properties interface. + * `PropertiesChanged` D-Bus signal on the + * `org.freedesktop.DBus.Properties` interface. * * Since: 2.26 */ @@ -633,14 +626,12 @@ g_dbus_proxy_class_init (GDBusProxyClass *klass) G_TYPE_STRING, G_TYPE_VARIANT); - - g_type_class_add_private (klass, sizeof (GDBusProxyPrivate)); } static void g_dbus_proxy_init (GDBusProxy *proxy) { - proxy->priv = G_TYPE_INSTANCE_GET_PRIVATE (proxy, G_TYPE_DBUS_PROXY, GDBusProxyPrivate); + proxy->priv = g_dbus_proxy_get_instance_private (proxy); proxy->priv->signal_subscription_data = g_slice_new0 (SignalSubscriptionData); proxy->priv->signal_subscription_data->ref_count = 1; proxy->priv->signal_subscription_data->proxy = proxy; @@ -795,7 +786,7 @@ g_dbus_proxy_get_cached_property (GDBusProxy *proxy, * * If the @value #GVariant is floating, it is consumed. This allows * convenient 'inline' use of g_variant_new(), e.g. - * |[ + * |[ * g_dbus_proxy_set_cached_property (proxy, * "SomeProperty", * g_variant_new ("(si)", @@ -803,20 +794,19 @@ g_dbus_proxy_get_cached_property (GDBusProxy *proxy, * 42)); * ]| * - * Normally you will not need to use this method since @proxy is - * tracking changes using the - * org.freedesktop.DBus.Properties.PropertiesChanged - * D-Bus signal. However, for performance reasons an object may decide - * to not use this signal for some properties and instead use a - * proprietary out-of-band mechanism to transmit changes. + * Normally you will not need to use this method since @proxy + * is tracking changes using the + * `org.freedesktop.DBus.Properties.PropertiesChanged` + * D-Bus signal. However, for performance reasons an object may + * decide to not use this signal for some properties and instead + * use a proprietary out-of-band mechanism to transmit changes. * * As a concrete example, consider an object with a property - * ChatroomParticipants which is an array of - * strings. Instead of transmitting the same (long) array every time - * the property changes, it is more efficient to only transmit the - * delta using e.g. signals ChatroomParticipantJoined(String - * name) and ChatroomParticipantParted(String - * name). + * `ChatroomParticipants` which is an array of strings. Instead of + * transmitting the same (long) array every time the property changes, + * it is more efficient to only transmit the delta using e.g. signals + * `ChatroomParticipantJoined(String name)` and + * `ChatroomParticipantParted(String name)`. * * Since: 2.26 */ @@ -1727,7 +1717,8 @@ async_initable_init_second_async (GAsyncInitable *initable, } else { - if (proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START) + if ((proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START) || + (proxy->priv->flags & G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION)) { async_init_call_get_name_owner (data); } @@ -2041,9 +2032,9 @@ initable_iface_init (GInitableIface *initable_iface) * to handle signals from the remote object. * * If @name is a well-known name and the - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name - * owner currently exists, the message bus will be requested to launch - * a name owner for the name. + * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION + * flags aren't set and no name owner currently exists, the message bus + * will be requested to launch a name owner for the name. * * This is a failable asynchronous constructor - when the proxy is * ready, @callback will be invoked and you can use @@ -2051,7 +2042,7 @@ initable_iface_init (GInitableIface *initable_iface) * * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Since: 2.26 */ @@ -2138,14 +2129,14 @@ g_dbus_proxy_new_finish (GAsyncResult *res, * to handle signals from the remote object. * * If @name is a well-known name and the - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name - * owner currently exists, the message bus will be requested to launch - * a name owner for the name. + * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION + * flags aren't set and no name owner currently exists, the message bus + * will be requested to launch a name owner for the name. * * This is a synchronous failable constructor. See g_dbus_proxy_new() * and g_dbus_proxy_new_finish() for the asynchronous version. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * @@ -2201,7 +2192,7 @@ g_dbus_proxy_new_sync (GDBusConnection *connection, * * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Since: 2.26 */ @@ -2266,7 +2257,7 @@ g_dbus_proxy_new_for_bus_finish (GAsyncResult *res, * * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * @@ -2974,7 +2965,7 @@ g_dbus_proxy_call_sync_internal (GDBusProxy *proxy, * * If the @parameters #GVariant is floating, it is consumed. This allows * convenient 'inline' use of g_variant_new(), e.g.: - * |[ + * |[ * g_dbus_proxy_call (proxy, * "TwoStrings", * g_variant_new ("(ss)", @@ -2984,7 +2975,7 @@ g_dbus_proxy_call_sync_internal (GDBusProxy *proxy, * -1, * NULL, * (GAsyncReadyCallback) two_strings_done, - * &data); + * &data); * ]| * * If @proxy has an expected interface (see @@ -2993,7 +2984,7 @@ g_dbus_proxy_call_sync_internal (GDBusProxy *proxy, * * This is an asynchronous method. When the operation is finished, * @callback will be invoked in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. * You can then call g_dbus_proxy_call_finish() to get the result of * the operation. See g_dbus_proxy_call_sync() for the synchronous @@ -3065,7 +3056,7 @@ g_dbus_proxy_call_finish (GDBusProxy *proxy, * * If the @parameters #GVariant is floating, it is consumed. This allows * convenient 'inline' use of g_variant_new(), e.g.: - * |[ + * |[ * g_dbus_proxy_call_sync (proxy, * "TwoStrings", * g_variant_new ("(ss)", @@ -3074,7 +3065,7 @@ g_dbus_proxy_call_finish (GDBusProxy *proxy, * G_DBUS_CALL_FLAGS_NONE, * -1, * NULL, - * &error); + * &error); * ]| * * The calling thread is blocked until a reply is received. See