[Telepathy-commits] [telepathy-mission-control/master] Add ChannelRequests interface and stub implementation
Alberto Mardegan
alberto.mardegan at nokia.com
Mon Nov 17 00:05:20 PST 2008
Add the interface ChannelRequests to the Account object, and provide empty
implementations of its methods.
---
src/Makefile.am | 4 +
src/mcd-account-requests.c | 111 +++++++++++
src/mcd-account-requests.h | 41 ++++
src/mcd-account.c | 4 +
xml/Account_Interface_ChannelRequests.xml | 294 +++++++++++++++++++++++++++++
xml/Makefile.am | 1 +
xml/nmc5.xml | 1 +
7 files changed, 456 insertions(+), 0 deletions(-)
create mode 100644 src/mcd-account-requests.c
create mode 100644 src/mcd-account-requests.h
create mode 100644 xml/Account_Interface_ChannelRequests.xml
diff --git a/src/Makefile.am b/src/Makefile.am
index 07cb9ab..1b67617 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -14,6 +14,7 @@ mission_control_include = \
mcd-account-compat.h \
mcd-account-conditions.h \
mcd-account-connection.h \
+ mcd-account-requests.h \
mcd-account-manager.h \
mcd-account-manager-creation.h \
mcd-account-manager-query.h \
@@ -46,6 +47,7 @@ nodist_geninclude_HEADERS = \
_gen/gtypes.h \
_gen/svc-Account.h \
_gen/svc-Account_Interface_Avatar.h \
+ _gen/svc-Account_Interface_ChannelRequests.h \
_gen/svc-Account_Interface_Compat.h \
_gen/svc-Account_Interface_Conditions.h \
_gen/svc-Account_Manager.h \
@@ -62,6 +64,7 @@ nodist_libmissioncontrol_server_la_SOURCES = \
_gen/signals-marshal.list \
_gen/svc-Account.c \
_gen/svc-Account_Interface_Avatar.c \
+ _gen/svc-Account_Interface_ChannelRequests.c \
_gen/svc-Account_Interface_Compat.c \
_gen/svc-Account_Interface_Conditions.c \
_gen/svc-Account_Manager.c \
@@ -110,6 +113,7 @@ libmissioncontrol_server_la_SOURCES = \
mcd-account-compat.c \
mcd-account-conditions.c \
mcd-account-connection.c \
+ mcd-account-requests.c \
mcd-account-manager.c \
mcd-account-manager-creation.c \
mcd-account-manager-query.c \
diff --git a/src/mcd-account-requests.c b/src/mcd-account-requests.c
new file mode 100644
index 0000000..1b3d9ff
--- /dev/null
+++ b/src/mcd-account-requests.c
@@ -0,0 +1,111 @@
+/* vi: set et sw=4 ts=4 cino=t0,(0: */
+/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4; tab-width: 4 -*- */
+/*
+ * This file is part of mission-control
+ *
+ * Copyright (C) 2008 Nokia Corporation.
+ *
+ * Contact: Alberto Mardegan <alberto.mardegan at nokia.com>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * version 2.1 as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * 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., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA
+ *
+ */
+
+#include <stdio.h>
+#include <string.h>
+#include <glib/gstdio.h>
+#include <glib/gi18n.h>
+#include <config.h>
+
+#include <dbus/dbus-glib-lowlevel.h>
+#include <telepathy-glib/svc-generic.h>
+#include <telepathy-glib/gtypes.h>
+#include <telepathy-glib/util.h>
+#include "mcd-account.h"
+#include "mcd-account-priv.h"
+#include "mcd-account-requests.h"
+#include "mcd-account-manager.h"
+#include "_gen/interfaces.h"
+
+
+const McdDBusProp account_channelrequests_properties[] = {
+ { 0 },
+};
+
+static void
+account_request_create (McSvcAccountInterfaceChannelRequests *self,
+ GHashTable *properties, guint64 user_time,
+ const gchar *preferred_handler,
+ DBusGMethodInvocation *context)
+{
+ GError *error = NULL;
+ const gchar *request_id;
+
+ if (error)
+ {
+ dbus_g_method_return_error (context, error);
+ g_error_free (error);
+ return;
+ }
+ request_id = "/com/nokia/chavo/request/r3";
+ mc_svc_account_interface_channelrequests_return_from_create (context,
+ request_id);
+}
+
+static void
+account_request_ensure_channel (McSvcAccountInterfaceChannelRequests *self,
+ GHashTable *properties, guint64 user_time,
+ const gchar *preferred_handler,
+ DBusGMethodInvocation *context)
+{
+ GError *error = NULL;
+ const gchar *request_id;
+
+ if (error)
+ {
+ dbus_g_method_return_error (context, error);
+ g_error_free (error);
+ return;
+ }
+ request_id = "/com/nokia/chavo/request/r4";
+ mc_svc_account_interface_channelrequests_return_from_ensure_channel
+ (context, request_id);
+}
+
+static void
+account_request_cancel (McSvcAccountInterfaceChannelRequests *self,
+ const gchar *request_id,
+ DBusGMethodInvocation *context)
+{
+ GError *error;
+
+ error = g_error_new (TP_ERRORS, TP_ERROR_NOT_IMPLEMENTED,
+ "%s is currently just a stub", G_STRFUNC);
+ dbus_g_method_return_error (context, error);
+ g_error_free (error);
+}
+
+void
+account_channelrequests_iface_init (McSvcAccountInterfaceChannelRequestsClass *iface,
+ gpointer iface_data)
+{
+#define IMPLEMENT(x) mc_svc_account_interface_channelrequests_implement_##x (\
+ iface, account_request_##x)
+ IMPLEMENT(create);
+ IMPLEMENT(ensure_channel);
+ IMPLEMENT(cancel);
+#undef IMPLEMENT
+}
+
diff --git a/src/mcd-account-requests.h b/src/mcd-account-requests.h
new file mode 100644
index 0000000..e6b0cdb
--- /dev/null
+++ b/src/mcd-account-requests.h
@@ -0,0 +1,41 @@
+/* vi: set et sw=4 ts=4 cino=t0,(0: */
+/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4; tab-width: 4 -*- */
+/*
+ * mcd-account.h - the Telepathy Account D-Bus interface (service side)
+ *
+ * Copyright (C) 2008 Nokia Corporation
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * 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., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#ifndef __MCD_ACCOUNT_REQUESTS_H__
+#define __MCD_ACCOUNT_REQUESTS_H__
+
+#include <telepathy-glib/dbus.h>
+#include <telepathy-glib/enums.h>
+/* auto-generated stubs */
+#include "_gen/svc-Account_Interface_ChannelRequests.h"
+
+#include "mcd-dbusprop.h"
+
+G_BEGIN_DECLS
+
+extern const McdDBusProp account_channelrequests_properties[];
+
+void account_channelrequests_iface_init
+ (McSvcAccountInterfaceChannelRequestsClass *iface, gpointer iface_data);
+
+G_END_DECLS
+#endif
diff --git a/src/mcd-account.c b/src/mcd-account.c
index e82131f..5d98f98 100644
--- a/src/mcd-account.c
+++ b/src/mcd-account.c
@@ -40,6 +40,7 @@
#include "mcd-account-compat.h"
#include "mcd-account-conditions.h"
#include "mcd-account-connection.h"
+#include "mcd-account-requests.h"
#include "mcd-account-manager.h"
#include "mcd-signals-marshal.h"
#include "mcd-manager.h"
@@ -71,6 +72,9 @@ static const McdInterfaceData account_interfaces[] = {
MCD_IMPLEMENT_IFACE (mc_svc_account_interface_avatar_get_type,
account_avatar,
MC_IFACE_ACCOUNT_INTERFACE_AVATAR),
+ MCD_IMPLEMENT_IFACE (mc_svc_account_interface_channelrequests_get_type,
+ account_channelrequests,
+ MC_IFACE_ACCOUNT_INTERFACE_CHANNELREQUESTS),
MCD_IMPLEMENT_IFACE (mc_svc_account_interface_compat_get_type,
account_compat,
MC_IFACE_ACCOUNT_INTERFACE_COMPAT),
diff --git a/xml/Account_Interface_ChannelRequests.xml b/xml/Account_Interface_ChannelRequests.xml
new file mode 100644
index 0000000..e0f2723
--- /dev/null
+++ b/xml/Account_Interface_ChannelRequests.xml
@@ -0,0 +1,294 @@
+<?xml version="1.0" ?>
+<node name="/Account_Interface_ChannelRequests" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Account.Interface.ChannelRequests">
+ <tp:requires interface="org.freedesktop.Telepathy.Account"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The ChannelRequests interface provides methods to create and cancel channel requests, and signals to monitor them.</p>
+ </tp:docstring>
+
+ <method name="Create">
+ <tp:docstring>
+ Create a channel request.
+ </tp:docstring>
+
+ <arg direction="in" name="Requested_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties. This has the same
+ semantics as the corresponding parameter to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.
+ </p>
+
+ <p>Certain properties will not necessarily make sense in this
+ dictionary: for instance,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ can only be given if the requester is able to interact with a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ to the desired account.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="User_Action_Time" type="t"
+ tp:type="Unix_Timestamp64">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred, or 0 if this channel
+ request is for some reason not involving user action.
+ This value will eventually be passed as the
+ <code>User_Action_Time</code> parameter of <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Preferred_Handler" type="s"
+ tp:type="DBus_Well_Known_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>)
+ of the preferred handler for this
+ channel, or an empty string to indicate that any handler would be
+ acceptable. The channel dispatcher SHOULD dispatch as many as
+ possible of the resulting channels (ideally, all of them)
+ to that handler, and SHOULD remember the preferred handler
+ so it can try to dispatch subsequent channels in the same bundle
+ to the same handler.</p>
+
+ <tp:rationale>
+ <p>This must be the well-known bus name, not the unique name,
+ to ensure that all handlers do indeed have the Client API,
+ and the Client object on the handler can be located easily.</p>
+
+ <p>This is partly so the channel dispatcher can call
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>
+ on it, and partly so the channel dispatcher
+ can recover state if it crashes and is restarted.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Request" type="o">
+ <tp:docstring>
+ A
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref>
+ object. Currently the object itself is not implemented and this
+ object path should be used only like a unique indentifier for the
+ channel request.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The Preferred_Handler is syntactically invalid or does
+ not start with <code>org.freedesktop.Telepathy.Client.</code>,
+ the Account does not exist, or one of the Requested_Properties
+ is invalid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+
+ </method>
+
+ <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Start a request to ensure that a channel exists, creating it if
+ necessary.</p>
+ </tp:docstring>
+
+ <arg direction="in" name="Requested_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties. This has the same
+ semantics as the corresponding parameter to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>.
+ </p>
+
+ <p>Certain properties will not necessarily make sense in this
+ dictionary: for instance,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ can only be given if the requester is able to interact with a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ to the desired account.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="User_Action_Time" type="t"
+ tp:type="Unix_Timestamp64">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred, or 0 if this channel
+ request is for some reason not involving user action.
+ This value will eventually be passed as the
+ <code>User_Action_Time</code> parameter of <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Preferred_Handler" type="s"
+ tp:type="DBus_Well_Known_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>)
+ of the preferred handler for this
+ channel, or an empty string to indicate that any handler would be
+ acceptable.</p>
+
+ <tp:rationale>
+ <p>This must be the well-known bus name, not the unique name,
+ to ensure that all handlers do indeed have the Client API,
+ and the Client object on the handler can be located easily.</p>
+
+ <p>This is partly so the channel dispatcher can call
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>
+ on it, and partly so the channel dispatcher
+ can recover state if it crashes and is restarted.</p>
+ </tp:rationale>
+
+ <p>If any new channels are created in response to this
+ request, the channel dispatcher SHOULD dispatch as many as
+ possible of the resulting channels (ideally, all of them)
+ to that handler, and SHOULD remember the preferred handler
+ so it can try to dispatch subsequent channels in the same bundle
+ to the same handler. If the requested channel already exists (that
+ is, <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>
+ returns <code>Yours=False</code>) then the channel dispatcher
+ SHOULD re-dispatch the channel to its existing handler, and MUST
+ NOT dispatch it to this client (unless it is the existing handler);
+ the request is still deemed to have succeeded in this case.</p>
+
+ <tp:rationale>
+ <p>An address book application, for example, might call <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.ChannelDispatcher.DRAFT'>EnsureChannel</tp:dbus-ref>
+ to ensure that a text channel with a particular contact is
+ displayed to the user; it does not care whether a new channel was
+ made. An IM client might call <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.ChannelDispatcher.DRAFT'>EnsureChannel</tp:dbus-ref>
+ in response to the user double-clicking an entry in the contact
+ list, with itself as the <code>Preferred_Handler</code>; if the
+ user already has a conversation with that contact in another
+ application, they would expect the existing window to be
+ presented, rather than their double-click leading to an error
+ message. So the request should succeed, even if its
+ <code>Preferred_Handler</code> is not used.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Request" type="o">
+ <tp:docstring>
+ A
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref>
+ object.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The Preferred_Handler is syntactically invalid or does
+ not start with <code>org.freedesktop.Telepathy.Client.</code>,
+ the Account does not exist, or one of the Requested_Properties
+ is invalid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+
+ </method>
+
+ <method name="Cancel">
+ <tp:docstring>
+ <p>Cancel a channel request. The precise effect depends on the
+ current progress of the request.</p>
+
+ <p>If the connection manager has not already been asked to create
+ a channel, then <tp:member-ref>Failed</tp:member-ref> is emitted
+ immediately, and the channel request is removed.</p>
+
+ <p>If the connection manager has already been asked to create a
+ channel but has not produced one yet (e.g. if <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ has been called, but has not yet returned), then the
+ ChannelDispatcher will remember that the request has been cancelled.
+ When the channel appears, it will be closed (if it was newly
+ created and can be closed), and will not be dispatched to a
+ handler.</p>
+
+ <p>If the connection manager has already returned a channel, but the
+ channel has not yet been dispatched to a handler
+ then the channel dispatcher will not dispatch that
+ channel to a handler. If the channel was newly created for this
+ request, the channel dispatcher will close it with Close; otherwise,
+ the channel dispatcher will ignore it. In either case,
+ <tp:member-ref>Failed</tp:member-ref> will be emitted when processing
+ has been completed.</p>
+
+ <p>If Failed is emitted in response to this method, the error SHOULD be
+ <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p>
+
+ <p>If the channel has already been dispatched to a handler, then
+ it's too late to call this method, and the channel request will
+ no longer exist.</p>
+ </tp:docstring>
+
+ <arg type="o" name="Request" direction="in">
+ <tp:docstring>The channel request to be cancelled.</tp:docstring>
+ </arg>
+
+ </method>
+
+ <signal name="Failed" tp:name-for-bindings="Failed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel request has failed. It is no longer present,
+ and further methods must not be called on it.</p>
+ </tp:docstring>
+
+ <arg name="Request" type="o">
+ <tp:docstring>The channel request.</tp:docstring>
+ </arg>
+
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of a D-Bus error. This can come from various sources,
+ including the error raised by CreateChannel, or an error generated
+ to represent failure to establish the Connection.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message" type="s">
+ <tp:docstring>
+ If the first argument of the D-Bus error message was a string,
+ that string. Otherwise, an empty string.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="Succeeded" tp:name-for-bindings="Succeeded">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel request has succeeded. It is no longer present,
+ and further methods must not be called on it.</p>
+ </tp:docstring>
+
+ <arg name="Request" type="o">
+ <tp:docstring>The channel request.</tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/xml/Makefile.am b/xml/Makefile.am
index 4518f68..abf8750 100644
--- a/xml/Makefile.am
+++ b/xml/Makefile.am
@@ -10,6 +10,7 @@ SPECS = MissionControl.xml \
Account_Manager_Interface_Query.xml \
Account.xml \
Account_Interface_Avatar.xml \
+ Account_Interface_ChannelRequests.xml \
Account_Interface_Compat.xml \
Account_Interface_Conditions.xml \
Client.xml \
diff --git a/xml/nmc5.xml b/xml/nmc5.xml
index ab23c6c..8f19419 100644
--- a/xml/nmc5.xml
+++ b/xml/nmc5.xml
@@ -6,6 +6,7 @@
<xi:include href="Account.xml"/>
<xi:include href="Account_Interface_Avatar.xml"/>
+<xi:include href="Account_Interface_ChannelRequests.xml"/>
<xi:include href="Account_Interface_Compat.xml"/>
<xi:include href="Account_Interface_Conditions.xml"/>
<xi:include href="Account_Manager.xml"/>
--
1.5.6.5
More information about the Telepathy-commits
mailing list