diff options
author | Will Thompson <will.thompson@collabora.co.uk> | 2011-10-10 15:10:59 +0100 |
---|---|---|
committer | Will Thompson <will.thompson@collabora.co.uk> | 2011-10-10 15:11:13 +0100 |
commit | 43a87ab723d8c21880c18bfd084a5c03e90ad89f (patch) | |
tree | 720ba6c5b90f136b68a438a691ce3cc2bfe98ea6 | |
parent | 468c19fb3ee29da725d9ed9acd07325ad2b329f4 (diff) | |
download | telepathy-glib-43a87ab723d8c21880c18bfd084a5c03e90ad89f.tar.gz |
Update to telepathy-spec 0.24.0
This also includes the updates to the Call-based example code omitted
from fa81060.
29 files changed, 2668 insertions, 1072 deletions
diff --git a/examples/future/call-cm/call-channel.c b/examples/future/call-cm/call-channel.c index 6cdcf9024..f96f9c1b4 100644 --- a/examples/future/call-cm/call-channel.c +++ b/examples/future/call-cm/call-channel.c @@ -217,10 +217,11 @@ example_call_channel_init (ExampleCallChannel *self) self->priv->call_state = FUTURE_CALL_STATE_UNKNOWN; /* set in constructed */ self->priv->call_flags = 0; - self->priv->call_state_reason = tp_value_array_build (3, + self->priv->call_state_reason = tp_value_array_build (4, G_TYPE_UINT, 0, /* actor */ G_TYPE_UINT, FUTURE_CALL_STATE_CHANGE_REASON_UNKNOWN, G_TYPE_STRING, "", + G_TYPE_STRING, "", G_TYPE_INVALID); self->priv->call_state_details = tp_asv_new ( NULL, NULL); @@ -270,7 +271,7 @@ constructed (GObject *object) /* This is an incoming call, so the self-handle is locally * pending, to indicate that we need to answer. */ example_call_channel_set_state (self, - FUTURE_CALL_STATE_PENDING_RECEIVER, 0, self->priv->handle, + FUTURE_CALL_STATE_RINGING, 0, self->priv->handle, FUTURE_CALL_STATE_CHANGE_REASON_USER_REQUESTED, "", NULL); } @@ -559,7 +560,7 @@ example_call_channel_terminate (ExampleCallChannel *self, * remove peers on call termination or not. For now this example does. */ g_array_append_val (au, self->priv->handle); future_svc_channel_type_call_emit_call_members_changed (self, - empty_uu_map, au); + empty_uu_map, au, self->priv->call_state_reason); g_hash_table_unref (empty_uu_map); g_array_free (au, TRUE); @@ -965,6 +966,7 @@ media_remove_streams (TpSvcChannelTypeStreamedMedia *iface, static void streams_removed_cb (ExampleCallContent *content, const GPtrArray *stream_paths G_GNUC_UNUSED, + const GArray *reason G_GNUC_UNUSED, ExampleCallChannel *self) { gchar *path, *name; @@ -980,7 +982,8 @@ streams_removed_cb (ExampleCallContent *content, g_hash_table_remove (self->priv->contents, name); future_svc_call_content_emit_removed (content); - future_svc_channel_type_call_emit_content_removed (self, path); + future_svc_channel_type_call_emit_content_removed (self, path, + self->priv->call_state_reason); g_free (path); g_free (name); @@ -1029,7 +1032,7 @@ simulate_contact_answered_cb (gpointer p) /* otherwise, we're waiting for a response from the contact, which now * arrives */ - g_assert (self->priv->call_state == FUTURE_CALL_STATE_PENDING_RECEIVER); + g_assert_cmpuint (self->priv->call_state, ==, FUTURE_CALL_STATE_RINGING); g_message ("SIGNALLING: receive: contact answered our call"); @@ -1080,7 +1083,7 @@ simulate_contact_busy_cb (gpointer p) /* otherwise, we're waiting for a response from the contact, which now * arrives */ - g_assert (self->priv->call_state == FUTURE_CALL_STATE_PENDING_RECEIVER); + g_assert_cmpuint (self->priv->call_state, ==, FUTURE_CALL_STATE_RINGING); g_message ("SIGNALLING: receive: call terminated: <user-is-busy/>"); @@ -1202,7 +1205,7 @@ simulate_contact_ringing_cb (gpointer p) g_hash_table_insert (uu_map, GUINT_TO_POINTER (self->priv->handle), GUINT_TO_POINTER (self->priv->peer_flags)); future_svc_channel_type_call_emit_call_members_changed (self, - uu_map, empty_au); + uu_map, empty_au, self->priv->call_state_reason); g_hash_table_unref (uu_map); g_array_free (empty_au, TRUE); @@ -1240,7 +1243,7 @@ example_call_channel_initiate_outgoing (ExampleCallChannel *self) { g_message ("SIGNALLING: send: new streamed media call"); example_call_channel_set_state (self, - FUTURE_CALL_STATE_PENDING_RECEIVER, 0, + FUTURE_CALL_STATE_RINGING, 0, tp_base_connection_get_self_handle (self->priv->conn), FUTURE_CALL_STATE_CHANGE_REASON_USER_REQUESTED, "", NULL); @@ -1266,7 +1269,7 @@ call_set_ringing (FutureSvcChannelTypeCall *iface, goto finally; } - if (self->priv->call_state != FUTURE_CALL_STATE_PENDING_RECEIVER) + if (self->priv->call_state != FUTURE_CALL_STATE_RINGING) { g_set_error (&error, TP_ERRORS, TP_ERROR_NOT_AVAILABLE, "Ringing() makes no sense now that we're not pending receiver"); @@ -1275,7 +1278,7 @@ call_set_ringing (FutureSvcChannelTypeCall *iface, g_message ("SIGNALLING: send: ring, ring!"); - example_call_channel_set_state (self, FUTURE_CALL_STATE_PENDING_RECEIVER, + example_call_channel_set_state (self, FUTURE_CALL_STATE_RINGING, self->priv->call_flags | FUTURE_CALL_FLAG_LOCALLY_RINGING, tp_base_connection_get_self_handle (self->priv->conn), FUTURE_CALL_STATE_CHANGE_REASON_USER_REQUESTED, "", NULL); @@ -1300,7 +1303,7 @@ accept_incoming_call (ExampleCallChannel *self) GHashTableIter iter; gpointer v; - g_assert (self->priv->call_state == FUTURE_CALL_STATE_PENDING_RECEIVER); + g_assert_cmpint (self->priv->call_state, ==, FUTURE_CALL_STATE_RINGING); g_message ("SIGNALLING: send: Accepting incoming call from %s", tp_handle_inspect (contact_repo, self->priv->handle)); @@ -1363,7 +1366,7 @@ call_accept (FutureSvcChannelTypeCall *iface G_GNUC_UNUSED, } else { - if (self->priv->call_state == FUTURE_CALL_STATE_PENDING_RECEIVER) + if (self->priv->call_state == FUTURE_CALL_STATE_RINGING) { accept_incoming_call (self); future_svc_channel_type_call_return_from_accept (context); diff --git a/examples/future/call-cm/call-content.c b/examples/future/call-cm/call-content.c index 6ccd2490b..52ebe49be 100644 --- a/examples/future/call-cm/call-content.c +++ b/examples/future/call-cm/call-content.c @@ -337,6 +337,7 @@ example_call_content_stream_removed_cb (ExampleCallContent *self, { GPtrArray *paths; gchar *path; + GValueArray *reason; g_return_if_fail (EXAMPLE_IS_CALL_CONTENT (self)); g_return_if_fail (EXAMPLE_IS_CALL_STREAM (stream)); @@ -347,9 +348,16 @@ example_call_content_stream_removed_cb (ExampleCallContent *self, NULL); paths = g_ptr_array_sized_new (1); g_ptr_array_add (paths, path); - future_svc_call_content_emit_streams_removed (self, paths); + reason = tp_value_array_build (4, + G_TYPE_UINT, 0, + G_TYPE_UINT, FUTURE_CALL_STATE_CHANGE_REASON_UNKNOWN, + G_TYPE_STRING, "", + G_TYPE_STRING, "", + G_TYPE_INVALID); + future_svc_call_content_emit_streams_removed (self, paths, reason); g_free (path); g_ptr_array_free (paths, TRUE); + g_value_array_free (reason); g_object_unref (self->priv->stream); self->priv->stream = NULL; diff --git a/examples/future/call-cm/call-stream.c b/examples/future/call-cm/call-stream.c index ea205df8b..ead31d7f9 100644 --- a/examples/future/call-cm/call-stream.c +++ b/examples/future/call-cm/call-stream.c @@ -367,6 +367,8 @@ example_call_stream_close (ExampleCallStream *self) void example_call_stream_accept_proposed_direction (ExampleCallStream *self) { + GValueArray *reason; + if (self->priv->removed || self->priv->local_sending_state != FUTURE_SENDING_STATE_PENDING_SEND) return; @@ -375,8 +377,15 @@ example_call_stream_accept_proposed_direction (ExampleCallStream *self) self->priv->object_path); self->priv->local_sending_state = FUTURE_SENDING_STATE_SENDING; + reason = tp_value_array_build (4, + G_TYPE_UINT, 0, + G_TYPE_UINT, FUTURE_CALL_STATE_CHANGE_REASON_UNKNOWN, + G_TYPE_STRING, "", + G_TYPE_STRING, "", + G_TYPE_INVALID); future_svc_call_stream_emit_local_sending_state_changed (self, - self->priv->local_sending_state); + self->priv->local_sending_state, reason); + g_value_array_free (reason); } void @@ -384,6 +393,7 @@ example_call_stream_simulate_contact_agreed_to_send (ExampleCallStream *self) { GHashTable *updated_members; GArray *removed_members; + GValueArray *reason; if (self->priv->removed || self->priv->remote_sending_state != FUTURE_SENDING_STATE_PENDING_SEND) @@ -398,10 +408,17 @@ example_call_stream_simulate_contact_agreed_to_send (ExampleCallStream *self) removed_members = g_array_sized_new (FALSE, FALSE, sizeof (guint), 0); g_hash_table_insert (updated_members, GUINT_TO_POINTER (self->priv->handle), GUINT_TO_POINTER (FUTURE_SENDING_STATE_SENDING)); + reason = tp_value_array_build (4, + G_TYPE_UINT, 0, + G_TYPE_UINT, FUTURE_CALL_STATE_CHANGE_REASON_UNKNOWN, + G_TYPE_STRING, "", + G_TYPE_STRING, "", + G_TYPE_INVALID); future_svc_call_stream_emit_remote_members_changed (self, updated_members, - removed_members); + removed_members, reason); g_hash_table_unref (updated_members); g_array_free (removed_members, TRUE); + g_value_array_free (reason); } static gboolean @@ -416,6 +433,12 @@ example_call_stream_change_direction (ExampleCallStream *self, gboolean want_to_send, gboolean want_to_receive) { GHashTable *updated_members = g_hash_table_new (NULL, NULL); + GValueArray *reason = tp_value_array_build (4, + G_TYPE_UINT, 0, + G_TYPE_UINT, FUTURE_CALL_STATE_CHANGE_REASON_UNKNOWN, + G_TYPE_STRING, "", + G_TYPE_STRING, "", + G_TYPE_INVALID); if (want_to_send) { @@ -432,7 +455,7 @@ example_call_stream_change_direction (ExampleCallStream *self, self->priv->object_path); self->priv->local_sending_state = FUTURE_SENDING_STATE_SENDING; future_svc_call_stream_emit_local_sending_state_changed (self, - self->priv->local_sending_state); + self->priv->local_sending_state, reason); } } else @@ -445,7 +468,7 @@ example_call_stream_change_direction (ExampleCallStream *self, self->priv->object_path); self->priv->local_sending_state = FUTURE_SENDING_STATE_NONE; future_svc_call_stream_emit_local_sending_state_changed (self, - self->priv->local_sending_state); + self->priv->local_sending_state, reason); } else if (self->priv->local_sending_state == FUTURE_SENDING_STATE_PENDING_SEND) @@ -454,7 +477,7 @@ example_call_stream_change_direction (ExampleCallStream *self, self->priv->object_path); self->priv->local_sending_state = FUTURE_SENDING_STATE_NONE; future_svc_call_stream_emit_local_sending_state_changed (self, - self->priv->local_sending_state); + self->priv->local_sending_state, reason); } } @@ -496,12 +519,13 @@ example_call_stream_change_direction (ExampleCallStream *self, sizeof (guint), 0); future_svc_call_stream_emit_remote_members_changed (self, - updated_members, removed_members); + updated_members, removed_members, reason); g_array_free (removed_members, TRUE); } g_hash_table_unref (updated_members); + g_value_array_free (reason); } /* The remote user wants to change the direction of this stream according @@ -512,7 +536,12 @@ example_call_stream_receive_direction_request (ExampleCallStream *self, gboolean remote_send) { GHashTable *updated_members = g_hash_table_new (NULL, NULL); - + GValueArray *reason = tp_value_array_build (4, + G_TYPE_UINT, 0, + G_TYPE_UINT, FUTURE_CALL_STATE_CHANGE_REASON_UNKNOWN, + G_TYPE_STRING, "", + G_TYPE_STRING, "", + G_TYPE_INVALID); /* In some protocols, streams cannot be neither sending nor receiving, so * if a stream is set to TP_MEDIA_STREAM_DIRECTION_NONE, this is equivalent * to removing it. (This is true in XMPP, for instance.) @@ -531,7 +560,7 @@ example_call_stream_receive_direction_request (ExampleCallStream *self, /* ask the user for permission */ self->priv->local_sending_state = FUTURE_SENDING_STATE_PENDING_SEND; future_svc_call_stream_emit_local_sending_state_changed (self, - self->priv->local_sending_state); + self->priv->local_sending_state, reason); } else { @@ -552,14 +581,14 @@ example_call_stream_receive_direction_request (ExampleCallStream *self, self->priv->object_path); self->priv->local_sending_state = FUTURE_SENDING_STATE_NONE; future_svc_call_stream_emit_local_sending_state_changed (self, - self->priv->local_sending_state); + self->priv->local_sending_state, reason); } else if (self->priv->local_sending_state == FUTURE_SENDING_STATE_PENDING_SEND) { self->priv->local_sending_state = FUTURE_SENDING_STATE_NONE; future_svc_call_stream_emit_local_sending_state_changed (self, - self->priv->local_sending_state); + self->priv->local_sending_state, reason); } else { @@ -613,12 +642,13 @@ example_call_stream_receive_direction_request (ExampleCallStream *self, sizeof (guint), 0); future_svc_call_stream_emit_remote_members_changed (self, - updated_members, removed_members); + updated_members, removed_members, reason); g_array_free (removed_members, TRUE); } g_hash_table_unref (updated_members); + g_value_array_free (reason); } static void diff --git a/extensions/misc.xml b/extensions/misc.xml index af9d1c65d..217cedfb7 100644 --- a/extensions/misc.xml +++ b/extensions/misc.xml @@ -4,7 +4,6 @@ <tp:title>Miscellaneous extensions from the future</tp:title> -<xi:include href="../spec/Call_Content_Codec_Offer.xml"/> <xi:include href="../spec/Call_Stream_Endpoint.xml"/> </tp:spec> diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml index 270d99b08..e97e98fce 100644 --- a/spec/Call_Content.xml +++ b/spec/Call_Content.xml @@ -20,91 +20,31 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call.Content.DRAFT" + <interface name="org.freedesktop.Telepathy.Call1.Content" tp:causes-havoc="experimental"> <tp:added version="0.19.0">(draft 1)</tp:added> + <tp:requires + interface="org.freedesktop.Telepathy.Call1.Interface.Mute"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> This object represents one Content inside a <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>. For + namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>. For example, in an audio/video call there would be one audio content and one video content. Each content has one or more <tp:dbus-ref - namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref> objects which + namespace="ofdT.Call1">Stream</tp:dbus-ref> objects which represent the actual transport to one or more remote contacts. </tp:docstring> - <tp:enum name="Content_Removal_Reason" type="u"> - <tp:added version="0.21.2"/> - <tp:docstring> - A representation of the reason for a content to be removed, - which may be used by simple clients, or used as a fallback - when the DBus_Reason is not understood. This enum will be - extended with future reasons as and when appropriate, so - clients SHOULD keep up to date with its values, but also be - happy to fallback to the Unknown value when an unknown value - is encountered. - </tp:docstring> - - <tp:enumvalue suffix="Unknown" value="0"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - We just don't know. Unknown values of this enum SHOULD also be - treated like this. - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="User_Requested" value="1"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The local user requests that this content is removed - from the call.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Error" value="2"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>There is an error with the content which means that it - has to be removed from the call.</p> - </tp:docstring> - </tp:enumvalue> - - <tp:enumvalue suffix="Unsupported" value="3"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Some aspect of the content is unsupported so has to be - removed from the call.</p> - </tp:docstring> - </tp:enumvalue> - </tp:enum> - <method name="Remove" tp:name-for-bindings="Remove"> <tp:changed version="0.21.2">previously there were no arguments</tp:changed> <tp:docstring> - Remove the content from the call. + Remove the content from the call. This will cause + <tp:member-ref>Removed</tp:member-ref>((self_handle, + <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>, "", "")) to be + emitted. </tp:docstring> - <arg direction="in" name="Reason" type="u" - tp:type="Content_Removal_Reason"> - <tp:docstring> - A generic hangup reason. - </tp:docstring> - </arg> - - <arg direction="in" name="Detailed_Removal_Reason" type="s" - tp:type="DBus_Error_Name"> - <tp:docstring> - A more specific reason for the content removal, if one is - available, or an empty string. - </tp:docstring> - </arg> - - <arg direction="in" name="Message" type="s"> - <tp:docstring> - A human-readable message for the reason of removing the - content, such as "Fatal streaming failure" or "no codec - intersection". This property can be left empty if no reason - is to be given. - </tp:docstring> - </arg> - <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" /> <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> @@ -120,7 +60,7 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when the content is removed from the call. This is the same as the <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT.ContentRemoved</tp:dbus-ref> + namespace="ofdT.Channel.Type">Call1.ContentRemoved</tp:dbus-ref> signal.</p> </tp:docstring> </signal> @@ -130,8 +70,9 @@ <tp:added version="0.19.11"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Extra interfaces provided by this content, such as <tp:dbus-ref - namespace="ofdT.Call">Content.Interface.Media.DRAFT</tp:dbus-ref> or - <tp:dbus-ref namespace="ofdT.Call">Content.Interface.Mute.DRAFT</tp:dbus-ref>. + namespace="ofdT.Call1">Content.Interface.Media</tp:dbus-ref>, + <tp:dbus-ref namespace="ofdT.Channel">Interface.Hold</tp:dbus-ref> or + <tp:dbus-ref namespace="ofdT.Call1">Interface.Mute</tp:dbus-ref>. This SHOULD NOT include the Content interface itself, and cannot change once the content has been created.</p> </tp:docstring> @@ -164,13 +105,13 @@ The disposition of this content, which defines whether to automatically start sending data on the streams when <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> is + namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref> is called on the channel. </tp:docstring> <tp:enumvalue suffix="None" value="0"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The content has no specific disposition + The content has no specific disposition. </tp:docstring> </tp:enumvalue> @@ -178,14 +119,14 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The content was initially part of the call. When <tp:dbus-ref - namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> + namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref> is called on the channel, all streams of this content with <tp:dbus-ref - namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref> - set to <tp:type>Sending_State</tp:type>_Pending_Send will be - moved to <tp:type>Sending_State</tp:type>_Sending as if + namespace="ofdT.Call1.Stream">LocalSendingState</tp:dbus-ref> + set to <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> will be + moved to <tp:value-ref type="Sending_State">Sending</tp:value-ref> as if <tp:dbus-ref - namespace="ofdT.Call.Stream.DRAFT">SetSending</tp:dbus-ref> + namespace="ofdT.Call1.Stream">SetSending</tp:dbus-ref> (True) had been called.</p> </tp:docstring> </tp:enumvalue> @@ -208,7 +149,7 @@ <arg name="Streams" type="ao"> <tp:docstring> The <tp:dbus-ref - namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were + namespace="ofdT.Call1">Stream</tp:dbus-ref>s which were added. </tp:docstring> </arg> @@ -221,19 +162,24 @@ <p>Emitted when streams are removed from a call</p> </tp:docstring> <arg name="Streams" type="ao"> - <tp:docstring> - The <tp:dbus-ref - namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were - removed. - </tp:docstring> - </arg> + <tp:docstring> + The <tp:dbus-ref + namespace="ofdT.Call1">Stream</tp:dbus-ref>s which were + removed. + </tp:docstring> + </arg> + <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason"> + <tp:docstring> + Why the content was removed. + </tp:docstring> + </arg> </signal> <property name="Streams" tp:name-for-bindings="Streams" type="ao" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The list of <tp:dbus-ref namespace="ofdT.Call" - >Stream.DRAFT</tp:dbus-ref> objects that exist in this + <p>The list of <tp:dbus-ref namespace="ofdT.Call1" + >Stream</tp:dbus-ref> objects that exist in this content.</p> <tp:rationale> diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml deleted file mode 100644 index f88143f69..000000000 --- a/spec/Call_Content_Codec_Offer.xml +++ /dev/null @@ -1,87 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Call_Content_Codec_Offer" - xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2009-2010 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.Call.Content.CodecOffer.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - This object represents an offer of a Codec payload mapping. - </tp:docstring> - - <method name="Accept" tp:name-for-bindings="Accept"> - <arg name="Codecs" direction="in" - type="a(usuua{ss})" tp:type="Codec[]"> - <tp:docstring> - The local codec mapping to send to the remote contacts and - to use in the <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>. - </tp:docstring> - </arg> - <tp:docstring> - Accept the updated Codec mapping and update the local mapping. - </tp:docstring> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The codecs given as the argument are invalid in some way. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="Reject" tp:name-for-bindings="Reject"> - <tp:docstring> - Reject the proposed update to the codecs - FIXME add error codes and strings here - </tp:docstring> - </method> - - <property name="Interfaces" tp:name-for-bindings="Interfaces" - type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Extra interfaces provided by this codec offer. This SHOULD - NOT include the CodecOffer interface itself, and cannot change - once the content has been created.</p> - </tp:docstring> - </property> - - <property name="RemoteContactCodecs" - tp:name-for-bindings="Remote_Contact_Codecs" - type="a(usuua{ss})" tp:type="Codec[]" access="read" - tp:immutable="yes"> - <tp:docstring> - A list of codecs the remote contact supports. - </tp:docstring> - </property> - - <property name="RemoteContact" tp:name-for-bindings="Remote_Contact" - type="u" tp:type="Contact_Handle" access="read" tp:immutable="yes"> - <tp:docstring> - The contact handle that this codec offer applies to. - </tp:docstring> - </property> - - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 038ce8c7a..ca5ed36bf 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -20,99 +20,116 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT" + <interface + name="org.freedesktop.Telepathy.Call1.Content.Interface.Media" tp:causes-havoc="experimental"> - <tp:added version="0.19.0">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/> + <tp:added version="0.23.4">(draft 2)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Call1.Content"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Interface to use by a software implementation of media streaming. The reason behind splitting the members of this interface out from the main <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> interface is + namespace="ofdT.Call1">Content</tp:dbus-ref> interface is that the software is not necessarily what controls the media. An example of this is in GSM phones, where the CM just tells the phone to dial a number and it does the audio routing in a device specific hardware way and the CM does not need to concern itself with codecs.</p> - <h4>Codec negotiation</h4> + <h4>Codec Negotiation</h4> <p>When a new <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channel - appears, whether it was requested or not, a <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> - will either be waiting in the - <tp:member-ref>CodecOffer</tp:member-ref> property, or will + namespace="ofdT.Channel.Type">Call1</tp:dbus-ref> channel + appears (whether it was requested or not) a <tp:dbus-ref + namespace="ofdT.Call1.Content">MediaDescription</tp:dbus-ref> + object will either be waiting in the + <tp:member-ref>MediaDescriptionOffer</tp:member-ref> property, or will appear at some point via the - <tp:member-ref>NewCodecOffer</tp:member-ref> signal.</p> - - <p>The <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> - property on the codec offer lists the codecs which are - supported by the remote contact, and so will determine the - codecs that should be proposed by the local user's streaming - implementation. An empty list means all codecs can be proposed.</p> - - <p>For incoming calls on protocols where codecs are proposed when - starting the call (for example, <a - href="http://xmpp.org/extensions/xep-0166.html">Jingle</a>), - the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> - will contain information on the codecs that have already been - proposed by the remote contact, otherwise the codec map will - be the empty list.</p> - - <p>The streaming implementation should look at the remote codec - map and the codecs known by the local user and call - <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT.Accept</tp:dbus-ref> - on the intersection of these two codec lists.</p> - - <p>This means that in practice, outgoing calls will have a codec - offer pop up with no information in the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>, - so the local user will call <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref> - with the list of all codecs supported. If this codec offer is - accepted, then <tp:member-ref>CodecsChanged</tp:member-ref> - will fire with the details of the codecs passed into - <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>. If - the call is incoming, then the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> - will contain details of the remote contact's codecs and the - local user will call <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref> - with the codecs that both sides understand. After the codec - set is accepted, <tp:member-ref>CodecsChanged</tp:member-ref> - will fire to signal this change.</p> - - <h4>Protocols without codec negotiation</h4> - - <p>For protocols where the codecs are not negotiable, instead of - popping up the initial content's <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> - object with an empty <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>, - the CM should set the supported codec values to known codec - values in the said object's codec map.</p> + <tp:member-ref>NewMediaDescriptionOffer</tp:member-ref> signal.</p> + + <p>If nothing is known about the remote side's Media capabilities + (e.g. outgoing SIP/XMPP call), this <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> will pop up with {<tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >HasRemoteInformation</tp:dbus-ref> = false, <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >FurtherNegotiationRequired</tp:dbus-ref> = true}, and the local + user's streaming implementation SHOULD call + <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >Accept</tp:dbus-ref>, + with a description of all supported codecs and other features. + The CM will then send this information to the remote side (and + <tp:member-ref>LocalMediaDescriptionChanged</tp:member-ref> will fire + with details of the description passed into <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >Accept</tp:dbus-ref> for debugging purposes). + </p> + <p>When the remote codecs and other content information are available + (e.g. Remote user replies to initial offer, or sends a new offer of + their own, a new <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> will appear, with {<tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >HasRemoteInformation</tp:dbus-ref> = true, <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >FurtherNegotiationRequired</tp:dbus-ref> = false}, + and the <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >Codecs</tp:dbus-ref> + property on the description offer set to the codecs which are + supported by the remote contact. The local user's streaming + implementation SHOULD then call Accept, with a description + that is compatible with the one one in the offer. After the codec + set is accepted, both + <tp:member-ref>LocalMediaDescriptionChanged</tp:member-ref> and + <tp:member-ref>RemoteMediaDescriptionsChanged</tp:member-ref> + will fire to signal their respective changes, to aid with debugging. + Note that if <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >Accept</tp:dbus-ref> is called, with <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >FurtherNegotiationRequired</tp:dbus-ref> set to false, + the CM should be able to rely on the fact that the + description passed into Accept is compatible with the one in the + offer, and the description passed into Accept will not be signalled to + the remote side. + </p> <h4>Changing codecs mid-call</h4> - <p>To update the codec list used mid-call, the - <tp:member-ref>UpdateCodecs</tp:member-ref> method should be - called with details of the new codec list. If this is - accepted, then <tp:member-ref>CodecsChanged</tp:member-ref> - will be emitted with the new codec set.</p> + <p>To update the codecs in the local (and optionally remote) media + descriptions mid-call, the + <tp:member-ref>UpdateLocalMediaDescription</tp:member-ref> method + should be called with details of the new codec list. If this is + accepted, then + <tp:member-ref>LocalMediaDescriptionChanged</tp:member-ref> + will be emitted with the new codec set. + </p> + <p> If parameters requiring negotiation are changed, then the + <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >FurtherNegotiationRequired</tp:dbus-ref> property should be set to + TRUE, and the new media description should + only be used once they come in a new MediaDescriptionOffer + </p> <p>If the other side decides to update his or her codec list during a call, a new <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + namespace="ofdT.Call1.Content">MediaDescription</tp:dbus-ref> object will appear through - <tp:member-ref>NewCodecOffer</tp:member-ref> which should be + <tp:member-ref>NewMediaDescriptionOffer</tp:member-ref> which should be acted on as documented above.</p> + <h4>Protocols without negotiation</h4> + + <p>For protocols where the codecs are not negotiable, the initial content's <tp:dbus-ref + namespace="ofdT.Call1.Content">MediaDescription</tp:dbus-ref> + object will appear with <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >HasRemoteInformation</tp:dbus-ref>, + set to true and the known supported codec values in <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >Codecs</tp:dbus-ref>. + </p> </tp:docstring> <tp:struct name="Codec" array-name="Codec_List"> @@ -140,6 +157,23 @@ Number of channels of the codec if applicable, otherwise 0. </tp:docstring> </tp:member> + <tp:member name="Updated" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + This should be set to true in calls to <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription" + >Accept</tp:dbus-ref> and + <tp:member-ref>UpdateLocalMediaDescription</tp:member-ref> if this + codec has changed in a way that needs to be signalled over the + network. If it is set to false, the CM is allowed ignore any + differences between the current parameters and the previous ones + <tp:rationale> + This mechanism may be used to save bandwidth and avoid the CM + having to calculate diffs against previous versions of this + struct, which can lead to false-positives (e.g. redundant ptime + updates). + </tp:rationale> + </tp:docstring> + </tp:member> <tp:member name="Parameters" type="a{ss}" tp:type="String_String_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Extra parameters for this codec. @@ -156,174 +190,279 @@ A contact handle. </tp:docstring> </tp:member> - <tp:member name="Codecs" type="a(usuua{ss})" tp:type="Codec[]"> + <tp:member name="Codecs" type="a(usuuba{ss})" tp:type="Codec[]"> <tp:docstring> The codecs that the contact supports. </tp:docstring> </tp:member> </tp:mapping> - <tp:struct name="Codec_Offering"> + <tp:mapping name="Contact_Media_Description_Properties_Map"> + <tp:member name="Remote_Contact" type="u" tp:type="Handle"> + <tp:docstring> + The remote contact this description refers to or 0. This matches the + <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >RemoteContact</tp:dbus-ref> property on + <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> + </tp:docstring> + </tp:member> + <tp:member name="Media_Description_Properties" type="a{sv}" + tp:type="Media_Description_Properties"> + <tp:docstring> + The properties of the description + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:struct name="Media_Description_Offer"> <tp:docstring> - A codec offer and its corresponding remote contact codec map. + The remote description offer and its information </tp:docstring> - <tp:member name="Codec_Offer" type="o"> + <tp:member name="Media_Description" type="o"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The object path to the <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT</tp:dbus-ref> + The object path to the <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> </tp:docstring> </tp:member> <tp:member name="Remote_Contact" type="u" tp:type="Contact_Handle"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The contact handle that this codec offer applies to. + The contact handle that this description applies to. </tp:docstring> </tp:member> - <tp:member name="Remote_Contact_Codecs" type="a(usuua{ss})" - tp:type="Codec[]"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property - of the codec offer. + <tp:member name="Properties" type="a{sv}" + tp:type="Media_Description_Properties"> + <tp:docstring> + The immutable properties of all interfaces of the codec description. + + <tp:rationale> + Having all the codec description properties here saves a D-Bus + round-trip - it shouldn't be necessary to get the properties from the + MediaDescription object, in practice. + </tp:rationale> </tp:docstring> </tp:member> </tp:struct> - <signal name="CodecsChanged" tp:name-for-bindings="Codecs_Changed"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when the codecs in use change.</p> - - <p>As well as acting as change notification for the - <tp:member-ref>ContactCodecMap</tp:member-ref>, emission of this - signal implies that the <tp:member-ref>CodecOffer</tp:member-ref> - property has changed to <code>('/', {})</code>.</p> + <method name="UpdateLocalMediaDescription" + tp:name-for-bindings="Update_Local_Media_Description"> + <tp:docstring> + Update the local codec mapping and other interfaces of the + MediaDescription. This method should only be + used during an existing call to update the local media description. + This may trigger a re-negotiation which may result in new + new MediaDescriptionOffers if the "FurtherNegotiationRequired" + property is TRUE. + Otherwise, only parameters which strictly describe the media being sent + can be changed. </tp:docstring> - <arg name="Updated_Codecs" type="a{ua(usuua{ss})}" - tp:type="Contact_Codec_Map"> - <tp:docstring> - A map from contact to his or her codecs. Each pair in this - map is added to the - <tp:member-ref>ContactCodecMap</tp:member-ref> property, - replacing any previous pair with that key. - </tp:docstring> - </arg> - <arg name="Removed_Contacts" type="au" tp:type="Contact_Handle[]"> + <arg name="Remote_Contact" type="u" tp:type="Handle" direction="in"> <tp:docstring> - A list of keys which were removed from the - <tp:member-ref>ContactCodecMap</tp:member-ref>, probably because - those contacts left the call. + The remote contact that this description should be negotiated with + (or 0 to mean "negotiate this with everyone"). Note that encoding + the same video multiple times is often needlessly expensive, so + differences in MediaDescriptions negotiated with different parties + in the call should be limited to payloading parameters if possible. </tp:docstring> </arg> - </signal> - - <method name="UpdateCodecs" tp:name-for-bindings="Update_Codecs"> - <tp:docstring> - Update the local codec mapping. This method should only be - used during an existing call to update the codec mapping. - </tp:docstring> - <arg name="Codecs" direction="in" - type="a(usuua{ss})" tp:type="Codec[]"> + <arg name="MediaDescription" direction="in" type="a{sv}" + tp:type="Media_Description_Properties"> <tp:docstring> - The codecs now supported by the local user. + The updated media description that the local side wants to use. </tp:docstring> </arg> <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> <tp:docstring> - Raised when a <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> - object exists and is referred to in the - <tp:member-ref>CodecOffer</tp:member-ref> property which - should be used instead of calling this method, or before - the content's initial <tp:dbus-ref - namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> - object has appeared. + The protocol does not support changing the codecs mid-call. </tp:docstring> </tp:error> - </tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The description given is invalid in some way. + </tp:docstring> + </tp:error> + </tp:possible-errors> </method> - <property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map" - type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read"> + <property name="RemoteMediaDescriptions" + tp:name-for-bindings="Remote_Media_Descriptions" + type="a{ua{sv}}" + tp:type="Contact_Media_Description_Properties_Map" access="read"> <tp:docstring> - <p>A map from contact handles (including the local user's own handle) - to the codecs supported by that contact.</p> - - <p>Change notification is via the - <tp:member-ref>CodecsChanged</tp:member-ref> signal.</p> + <p>A map from contact handles to descriptions supported by that + contact.</p> + + <p>Keys of this map will appear in at most one <tp:dbus-ref + namespace="ofdT.Call1.Stream">RemoteMembers</tp:dbus-ref>. + See <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >RemoteContact</tp:dbus-ref> for more details on how to map between + MediaDescriptions and Streams.</p> </tp:docstring> </property> - <signal name="NewCodecOffer" tp:name-for-bindings="New_Codec_Offer"> + <property name="LocalMediaDescriptions" + tp:name-for-bindings="Local_Media_Descriptions" + type="a{ua{sv}}" + tp:type="Contact_Media_Description_Properties_Map" access="read"> + <tp:docstring> + <p>A map from contact handles to the descriptions the local side + responsed with.</p> </tp:docstring> + </property> + + <signal name="NewMediaDescriptionOffer" + tp:name-for-bindings="New_Media_Description_Offer"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming - implementation MUST respond by calling the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT" + <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> appears. The streaming + >implementation MUST respond by calling the + <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" >Accept</tp:dbus-ref> or <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT" - >Reject</tp:dbus-ref> method on the codec offer object.</p> + namespace="ofdT.Call1.Content.MediaDescription" + >Reject</tp:dbus-ref> method on the description object appeared.</p> <p>Emission of this signal indicates that the - <tp:member-ref>CodecOffer</tp:member-ref> property has changed to - <code>(Contact, Offer, Codecs)</code>.</p> + <tp:member-ref>MediaDescriptionOffer</tp:member-ref> property has + changed to + <code>(Description, Contact, MediaDescriptionProperties)</code>.</p> + + <p>When the MediaDescriptionOffer has been dealt with then + <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media" + >MediaDescriptionOfferDone</tp:dbus-ref> must be emitted + before <tp:dbus-ref + namespace="ofdT.Call1.Content.Interface.Media" + >NewMediaDescriptionOffer</tp:dbus-ref> is emitted again. + </p> + </tp:docstring> + <arg name="Media_Description" type="o"> + <tp:docstring> + The object path of the new media description. This replaces any + previous media description. + </tp:docstring> + </arg> <arg name="Contact" type="u"> <tp:docstring> - The contact the codec offer belongs to. + The remote contact the media description belongs to. </tp:docstring> </arg> - <arg name="Offer" type="o"> + <arg name="Properties" type="a{sv}" + tp:type="Media_Description_Properties"> + <tp:docstring> + The immutable properties of the remote media description. + + <tp:rationale> + Having all the MediaDescription properties here saves a D-Bus + round-trip - it shouldn't be necessary to get the properties from the + MediaDescription object, in practice. + </tp:rationale> + </tp:docstring> + </arg> + </signal> + + <signal name="MediaDescriptionOfferDone" + tp:name-for-bindings="Media_Description_Offer_Done"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> has been handled. </p> + <p>Emission of this signal indicates that the + <tp:member-ref>MediaDescriptionOffer</tp:member-ref> property has + changed to + <code>("/", 0, {})</code>.</p> + </tp:docstring> + </signal> + + + <signal name="LocalMediaDescriptionChanged" + tp:name-for-bindings="Local_Media_Description_Changed"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Change notification for + <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media" + >LocalMediaDescriptions</tp:dbus-ref> + </p> + </tp:docstring> + + <arg name="Remote_Contact" type="u" tp:type="Handle"> <tp:docstring> - The object path of the new codec offer. This replaces any previous - codec offer. + The remote contact that this description was negotiated with + (or 0 to mean "negotiated with everyone"). </tp:docstring> </arg> - <arg name="Codecs" type="a(usuua{ss})" tp:type="Codec[]"> + + <arg name="Updated_Media_Description" type="a{sv}" + tp:type="Media_Description_Properties"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property - of the codec offer.</p> + <p>The local content description that was updated</p> + </tp:docstring> + </arg> + </signal> - <tp:rationale> - Having the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> - property here saves a D-Bus round-trip - it shouldn't be - necessary to get the property from the CodecOffer object, in - practice. - </tp:rationale> + <signal name="RemoteMediaDescriptionsChanged" + tp:name-for-bindings="Remote_Media_Descriptions_Changed"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Change notification for + <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media" + >RemoteMediaDescriptions</tp:dbus-ref> + </p> + </tp:docstring> + + <arg name="Updated_Media_Descriptions" type="a{ua{sv}}" + tp:type="Contact_Media_Description_Properties_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The remote content descriptions that were updated</p> + </tp:docstring> + </arg> + </signal> + + <signal name="MediaDescriptionsRemoved" + tp:name-for-bindings="Media_Descriptions_Removed"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Removal notification for + <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media" + >RemoteMediaDescriptions</tp:dbus-ref> + and + <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media" + >LocalMediaDescriptions</tp:dbus-ref> + </p> + </tp:docstring> + + <arg name="Removed_Media_Descriptions" type="au" + tp:type="Contact_Handle[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The local and remote content descriptions that are no longer part + of this content</p> </tp:docstring> </arg> </signal> - <property name="CodecOffer" tp:name-for-bindings="Codec_Offer" - type="(oua(usuua{ss}))" tp:type="Codec_Offering" access="read"> + <property name="MediaDescriptionOffer" + tp:name-for-bindings="Media_Description_Offer" + type="(oua{sv})" tp:type="Media_Description_Offer" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The object path to the current - <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT</tp:dbus-ref> object, its - <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT.RemoteContact</tp:dbus-ref> and - <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> properties. + <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> object, its + <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >RemoteContact</tp:dbus-ref> and + a mapping of the MediaDescriptions properties. If the object path is "/" then there isn't an outstanding - codec offer, and the mapping MUST be empty.</p> + content description, and the mapping MUST be empty.</p> <tp:rationale> - Having the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT" - >RemoteContact</tp:dbus-ref> and - <tp:dbus-ref namespace="ofdT.Call.Content.CodecOffer.DRAFT" - >RemoteContactCodecs</tp:dbus-ref> + Having all <tp:dbus-ref + namespace="ofdT.Call1.Content">MediaDescription</tp:dbus-ref> properties here saves a D-Bus round-trip - it shouldn't be - necessary to get these properties from the CodecOffer object, in - practice. + necessary to get these properties from the Content MediaDescription + object, in practice. </tp:rationale> <p>Change notification is via the - <tp:member-ref>NewCodecOffer</tp:member-ref> (which replaces the - value of this property with a new codec offer), and - <tp:member-ref>CodecsChanged</tp:member-ref> (which implies that - there is no longer any active codec offer) signals.</p> + <tp:member-ref>NewMediaDescriptionOffer</tp:member-ref> and + <tp:member-ref>MediaDescriptionOfferDone</tp:member-ref> signals. + </p> </tp:docstring> </property> @@ -362,6 +501,81 @@ <p>The packetization method in use for this content.</p> </tp:docstring> </property> + + <signal name="DTMFChangeRequested" + tp:name-for-bindings="DTMF_Change_Requested"> + <tp:docstring> + Used by the CM to relay instructions from <tp:dbus-ref + namespace="ofdT">Channel.Interface.DTMF</tp:dbus-ref> to the streaming + implementation. If any contact in this call supports the + telephone-event codec in their MediaDescription, this event should be + sent as outlined in RFC 4733. Otherwise, it should be sent as an + audible tone. + </tp:docstring> + <arg name="Event" type="y" tp:type="DTMF_Event"> + <tp:docstring> + The event to send (or stop sending). + </tp:docstring> + </arg> + <arg name="State" type="u" tp:type="Sending_State"> + <tp:docstring> + Either <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> or + <tp:value-ref type="Sending_State">Pending_Stop_Sending</tp:value-ref>. + </tp:docstring> + </arg> + </signal> + + <method name="AcknowledgeDTMFChange" + tp:name-for-bindings="Acknowledge_DTMF_Change"> + <tp:docstring> + Called by the streaming implementation in response to + <tp:member-ref>DTMFChangeRequested</tp:member-ref> to confirm that it + has started or stopped sending the event in question. + </tp:docstring> + <arg name="Event" type="y" tp:type="DTMF_Event" direction="in"> + <tp:docstring> + The event referred to in the corresponding + <tp:member-ref>DTMFChangeRequested</tp:member-ref> signal. + </tp:docstring> + </arg> + <arg name="State" type="u" tp:type="Sending_State" direction="in"> + <tp:docstring> + Either <tp:value-ref type="Sending_State">Sending</tp:value-ref> or + <tp:value-ref type="Sending_State">None</tp:value-ref>. + </tp:docstring> + </arg> + </method> + + <property name="CurrentDTMFEvent" + tp:name-for-bindings="Current_DTMF_Event" type="y" tp:type="DTMF_Event" + access="read"> + <tp:docstring> + The currently requested DTMF event (for state-recoverability of + <tp:member-ref>DTMFChangeRequested</tp:member-ref>). Should be ignored + if <tp:member-ref>CurrentDTMFState</tp:member-ref> is None. + </tp:docstring> + </property> + + <property name="CurrentDTMFState" + tp:name-for-bindings="Current_DTMF_State" type="u" tp:type="Sending_State" + access="read"> + <tp:docstring> + The current DTMF state (for state-recoverability of + <tp:member-ref>DTMFChangeRequested</tp:member-ref>). + </tp:docstring> + </property> + + <method name="Fail" tp:name-for-bindings="Fail"> + <tp:docstring> + Signal an unrecoverable error for this content, and remove it. + </tp:docstring> + <arg direction="in" name="Reason" type="(uuss)" + tp:type="Call_State_Reason"> + <tp:docstring> + A reason struct describing the error. + </tp:docstring> + </arg> + </method> </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml deleted file mode 100644 index f926e03cd..000000000 --- a/spec/Call_Content_Interface_Mute.xml +++ /dev/null @@ -1,85 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Call_Content_Interface_Mute" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> - <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> - <tp:license xmlns="http://www.w3.org/1999/xhtml"> -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 Street, Fifth Floor, Boston, MA 02110-1301, USA. - </tp:license> - - <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Mute.DRAFT" tp:causes-havoc="experimental"> - <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Interface for calls which may be muted. This only makes sense - for channels where audio or video is streaming between members.</p> - - <p>Muting a call content indicates that the user does not wish to send - outgoing audio or video.</p> - - <p>Although it's client's responsibility to actually mute the microphone - or turn off the camera, using this interface the client can also - inform the CM and other clients of that fact.</p> - - <tp:rationale> - For some protocols, the fact that the content is muted needs - to be transmitted to the peer; for others, the notification - to the peer is only informational (eg. XMPP), and some - protocols may have no notion of muting at all. - </tp:rationale> - </tp:docstring> - - <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed"> - <tp:docstring> - Emitted to indicate that the mute state has changed for this call content. - This may occur as a consequence of the client calling - <tp:member-ref>SetMuted</tp:member-ref>, or as an indication that another - client has (un)muted the content. - </tp:docstring> - <arg name="MuteState" type="b"> - <tp:docstring> - True if the content is now muted. - </tp:docstring> - </arg> - </signal> - - <property name="MuteState" type="b" - access="read" tp:name-for-bindings="Mute_State"> - <tp:docstring> - True if the content is muted. - </tp:docstring> - </property> - - <method name="SetMuted" tp:name-for-bindings="Set_Muted"> - <tp:changed version="0.21.2">renamed from SetMuted to Mute</tp:changed> - <tp:changed version="0.21.3">renamed back from Mute to SetMuted</tp:changed> - <arg direction="in" name="Muted" type="b"> - <tp:docstring> - True if the client has muted the content. - </tp:docstring> - </arg> - <tp:docstring> - <p>Inform the CM that the call content has been muted or unmuted by - the client.</p> - - <p>It is the client's responsibility to actually mute or unmute the - microphone or camera used for the content. However, the client - MUST call this whenever it mutes or unmutes the content.</p> - </tp:docstring> - </method> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Interface_Video_Control.xml b/spec/Call_Content_Interface_Video_Control.xml index b066de42b..a300f3b5f 100644 --- a/spec/Call_Content_Interface_Video_Control.xml +++ b/spec/Call_Content_Interface_Video_Control.xml @@ -20,10 +20,10 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call.Content.Interface.VideoControl.DRAFT" + <interface name="org.freedesktop.Telepathy.Call1.Content.Interface.VideoControl" tp:causes-havoc="experimental"> <tp:added version="0.21.10">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT"/> + <tp:requires interface="org.freedesktop.Telepathy.Call1.Content.Interface.Media"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An interface that allows the connection manager to control the video diff --git a/spec/Call_Content_Media_Description.xml b/spec/Call_Content_Media_Description.xml new file mode 100644 index 000000000..7c494a410 --- /dev/null +++ b/spec/Call_Content_Media_Description.xml @@ -0,0 +1,236 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Media_Description" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2009-2010 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.Call1.Content.MediaDescription" + tp:causes-havoc="experimental"> + <tp:added version="0.23.4">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + This object represents a remote Description Offer to which the local + streaming implementation should reply with its local Description. + + This is intended as a temporary transactional object for use with <tp:dbus-ref + namespace="ofdT.Call1">Content.Interface.Media</tp:dbus-ref>. + There will always be 0 or 1 MediaDescription object per Content. + In most cases, this object will stay alive until you call either + <tp:member-ref>Accept</tp:member-ref> or + <tp:member-ref>Reject</tp:member-ref>, and then disappear. + There are some cases (e.g. an endpoint being removed from the call) + where a MediaDescription object will disappear before you have had a + chance to either Accept or Reject it. + </tp:docstring> + + <method name="Accept" tp:name-for-bindings="Accept"> + <arg name="Local_Media_Description" direction="in" + type="a{sv}" tp:type="Media_Description_Properties"> + <tp:docstring> + The local description to send to the remote contacts and + to use in the <tp:dbus-ref + namespace="ofdT.Call1">Content</tp:dbus-ref>. + </tp:docstring> + </arg> + <tp:docstring> + Accepts the updated Description and update the corresponding + local description. If FurtherNegotiationRequired is True, + calling this method will generally cause a network round-trip + and a new MediaDescription to be offered (hopefully with + FurtherNegotiationRequired set to False). + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The description given is invalid in some way. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Reject" tp:name-for-bindings="Reject"> + <tp:docstring> + Reject the proposed update to the remote description. + </tp:docstring> + <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason" + direction="out"> + <tp:docstring> + A structured reason for the rejection. + </tp:docstring> + </arg> + </method> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Extra interfaces provided by this media description. This SHOULD + NOT include the Description interface itself.</p> + </tp:docstring> + </property> + + <property name="FurtherNegotiationRequired" + tp:name-for-bindings="Further_Negotiation_Required" type="b" + access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml" > + <p> If this is set to True by the CM in a MediaDescriptionOffer, it + means "This is an offer under the SDP Offer/Answer model. Whatever + you accept this offer with is what I will send to the other side in + my answer." + + If this is set to False by the CM then it means "This is an Answer + under the SDP Offer/Answer model, and if it remains False in the + Accept(), no further codec negotiation needs to happen." + + If this is set to True by the streaming implementation (e.g. in an + Accept or UpdateLocalMediaDescription call) then a new SDP + Offer/Answer round-trip will be initiated. + </p> + </tp:docstring> + </property> + + <property name="HasRemoteInformation" + tp:name-for-bindings="Has_Remote_Information" type="b" + access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml" > + <p> True if this offer contains information from the remote side: + If False then the Accept response solely depends on the + capabilities and preferences of the local side. + + In most protocols this property will be False for the initial + DescriptionOffer on an outgoing call. + </p> + </tp:docstring> + </property> + + <property name="Codecs" + tp:name-for-bindings="Codecs" + type="a(usuuba{ss})" tp:type="Codec[]" access="read" + tp:immutable="yes"> + <tp:docstring> + A list of codecs the remote contact supports. When used with + <tp:member-ref>Accept</tp:member-ref>, it means the locally supported + codecs. + </tp:docstring> + </property> + + <property name="RemoteContact" tp:name-for-bindings="Remote_Contact" + type="u" tp:type="Contact_Handle" access="read" tp:immutable="yes"> + <tp:docstring> + The contact handle that this description applies to. + + This property can be used as an opaque identifier, and searched for in + <tp:dbus-ref namespace="ofdT.Call1.Stream" + >RemoteMembers</tp:dbus-ref> for each Stream in this Content, to + determine which Stream this MediaDescription applies to. If multiple + MediaDescriptions apply to the same Stream, the + <tp:member-ref>SSRCs</tp:member-ref> property should be used to + separate media before decoding. + + If this property is 0, this MediaDescription applies to all streams, + so the above matching method is unneccesary (e.g. in conference calls + with a mixer, media from all participants is mixed into one stream). + + When calling Accept or UpdateLocalMediaDescription, this should always + be set to 0, or omitted, because it is assumed that you send the same + MediaDescription to everyone (Encoding a stream separately for each + contact in a call is inefficient, and should be avoided). + </tp:docstring> + </property> + + <tp:mapping name="Contact_SSRCs_Map"> + <tp:member name="Contact" type="u" tp:type="Handle"> + <tp:docstring> + The remote contact these SSRCs belong to or 0. + </tp:docstring> + </tp:member> + <tp:member name="SSRCs" type="au"> + <tp:docstring> + The list of Synchronisation Sources. + </tp:docstring> + </tp:member> + </tp:mapping> + + <property name="SSRCs" tp:name-for-bindings="SSRCs" + type="a{uau}" tp:type="Contact_SSRCs_Map" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map from Handle to list of Synchronisation Sources, as defined by + RFC 3550.</p> + + <p>Some protocols require the negotiation of SSRC identifiers for RTP + streams. If this is the case, then MediaDescription offers will appear + with this property set. The streaming implementation should then call + <tp:member-ref>Accept</tp:member-ref> with a map from 0 to a + list containing a single SSRC (which does not collide with these, + or any previously seen SSRCs). If a new MediaDescription offer + appears with an SSRC the same as one in <tp:dbus-ref + namespace="ofdT.Call1.Content.Interface.Media" + >LocalMediaDescriptions</tp:dbus-ref>, then the streaming + implementation should pick a new SSRC to resolve the collision.</p> + + <p>It is expected that this list will normally be at most one element long, + but it is kept as a list for extensibility. The concatenation of all + SSRCs associated with a Stream should contain no duplicate entries. If + there are collisions, then it is the responsibility of the protocol + implementation to resolve them and generate new offers.</p> + + <p>If this property is omitted, then the streaming implementation can + assume that there is only one MediaDescription per Stream.</p> + + <p>If there is a single multicast Call Stream with multiple + Remote Members, and all members are forced to use the same + MediaDescription, this map can be used by the streaming implementation + to determine which video sources belong to which contacts (e.g. in + order to put a name under each face in the call)</p> + </tp:docstring> + </property> + + <tp:mapping name="Media_Description_Properties"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + A mapping containing all properties that define the information from a + <tp:dbus-ref + namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref> and its interfaces. + </p> + + <p> + If <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >HasRemoteInformation</tp:dbus-ref> is True, then this mapping + will always contains at least + <tp:dbus-ref namespace="ofdT.Call1.Content.MediaDescription" + >Codecs</tp:dbus-ref> + </p> + </tp:docstring> + + <tp:member name="Media_Description_Property" + type="s" tp:type="DBus_Qualified_Member"> + <tp:docstring> + A D-Bus interface name, followed by a dot and a D-Bus property name. + </tp:docstring> + </tp:member> + <tp:member name="Media_Description_Property_Value" type="v"> + <tp:docstring> + The value of the property + </tp:docstring> + </tp:member> + </tp:mapping> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Media_Description_Interface_RTCP_Extended_Reports.xml b/spec/Call_Content_Media_Description_Interface_RTCP_Extended_Reports.xml new file mode 100644 index 000000000..f973306cb --- /dev/null +++ b/spec/Call_Content_Media_Description_Interface_RTCP_Extended_Reports.xml @@ -0,0 +1,145 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Media_Description_Interface_RTCP_Extended_Reports" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +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 Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call1.Content.MediaDescription.Interface.RTCPExtendedReports" + tp:causes-havoc="experimental"> + <tp:added version="0.23.4">(draft version, not API-stable)</tp:added> + <tp:requires + interface="org.freedesktop.Telepathy.Call1.Content.MediaDescription"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This codec offer interface provides a method of signalling for + RTCP extended reports, documented by <em>RTP Control Protocol + Extended Reports (RTCP XR)</em> (RFC 3611). CMs should ignore + all RTCP Extended Report parameters that are not listed + in this spec at the time of implementation. More parameters can be + added to the spec as required.</p> + + <p>For more details on what RTCP extended reports can do and how + to use them, one should refer to + <a href="http://www.faqs.org/rfcs/rfc3611.html">RFC 3611</a>.</p> + + </tp:docstring> + + <property access="read" type="u" name="LossRLEMaxSize" tp:name-for-bindings="Loss_RLE_Max_Size"> + <tp:docstring> + If non-zero, enable Loss Run Length Encoded Report Blocks. The value + of this integer represents the max-size of report blocks, as specified + in RFC 3611 section 5.1. MAXUINT32 is used to indicate that there is + no limit. + </tp:docstring> + </property> + <property access="read" type="u" name="DuplicateRLEMaxSize" tp:name-for-bindings="Duplicate_RLE_Max_Size"> + <tp:docstring> + If non-zero, enable Duplicate Run-Length-Encoded Report Blocks. The + value of this integer represents the max-size of report blocks, as + specified in RFC 3611 section 5.1. MAXUINT32 is used to indicate that + there is no limit. + </tp:docstring> + </property> + <property access="read" type="u" name="PacketReceiptTimesMaxSize" tp:name-for-bindings="Packet_Receipt_Times_Max_Size"> + <tp:docstring> + If non-zero, enable Packet Receipt Times Report Blocks. The + value of this integer represents the max-size of report blocks, as + specified in RFC 3611 section 5.1. MAXUINT32 is used to indicate that + there is no limit. + </tp:docstring> + </property> + <property access="read" type="u" name="DLRRMaxSize" tp:name-for-bindings="DLRR_Max_Size"> + <tp:docstring> + If non-zero, enable Receiver Reference Time and Delay since Last + Receiver Report Blocks (for estimating Round Trip Times between + non-senders and other parties in the call. The value of this integer + represents the max-size of report blocks, as specified in RFC 3611 + section 5.1. MAXUINT32 is used to indicate that there is no limit. + </tp:docstring> + </property> + <property access="read" type="u" tp:type="RCPT_XR_RTT_Mode" + name="RTTMode" tp:name-for-bindings="RTT_Mode"> + <tp:docstring> + Who is allowed to send Delay since Last Receiver Reports. + </tp:docstring> + </property> + + <property access="read" type="u" tp:type="RTCP_XR_Statistics_Flags" + name="StatisticsFlags" tp:name-for-bindings="Statistics_Flags"> + <tp:docstring> + Which fields SHOULD be included in the statistics summary + report blocks that are sent, and whether to send VoIP Metrics Report + Blocks. There can be zero or more flags + set. + </tp:docstring> + </property> + + <property access="read" type="b" name="EnableMetrics" tp:name-for-bindings="Enable_Metrics"> + <tp:docstring> + Whether to enable VoIP Metrics Report Blocks. These blocks are of a + fixed size. + </tp:docstring> + </property> + + <tp:flags name="RTCP_XR_Statistics_Flags" type="u"> + <tp:flag suffix="Loss" value="1"> + <tp:docstring> + Loss report flag, as defined in RFC3611 section 4.6. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Duplicate" value="2"> + <tp:docstring> + Duplicate report flag, as defined in RFC3611 section 4.6. + </tp:docstring> + </tp:flag> + <tp:flag suffix="Jitter" value="4"> + <tp:docstring> + Jitter flag, as defined in RFC3611 section 4.6. + </tp:docstring> + </tp:flag> + <tp:flag suffix="TTL" value="8"> + <tp:docstring> + First bit of TTL or Hop Limit flag, as defined in RFC3611 section + 4.6. + </tp:docstring> + </tp:flag> + <tp:flag suffix="HL" value="16"> + <tp:docstring> + Second bit of TTL or Hop Limit flag, as defined in RFC3611 section + 4.6. + </tp:docstring> + </tp:flag> + </tp:flags> + + <tp:enum name="RCPT_XR_RTT_Mode" type="u"> + <tp:enumvalue suffix="All" value="0"> + <tp:docstring> + Both RTP data senders and data receivers MAY send DLRR + blocks. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Sender" value="1"> + <tp:docstring> + Only active RTP senders MAY send DLRR blocks, i.e., non RTP + senders SHALL NOT send DLRR blocks. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Media_Description_Interface_RTCP_Feedback.xml b/spec/Call_Content_Media_Description_Interface_RTCP_Feedback.xml new file mode 100644 index 000000000..f586fe4c2 --- /dev/null +++ b/spec/Call_Content_Media_Description_Interface_RTCP_Feedback.xml @@ -0,0 +1,61 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Media_Description_Interface_RTCP_Feedback" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +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 Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call1.Content.MediaDescription.Interface.RTCPFeedback" + tp:causes-havoc="experimental"> + <tp:added version="0.23.4">(draft version, not API-stable)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Call1.Content.MediaDescription"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This codec offer interface provides a method of signalling + support for RTCP feedback, documented by <em>Extended RTP + Profile for Real-time Transport Control Protocol (RTCP)-Based + Feedback (RTP/AVPF)</em> (RFC 4585).</p> + + <p>The codec identifiers used in the description of the Feedback Messages + sent in the <tp:dbus-ref + namespace="ofdT.Call1.Content.MediaDescription">Accept</tp:dbus-ref>'s + should match those used for the RemoteCodecs in the same Accept call. + </p> + + <p>For more details on what RTCP Feedback can do and how to use + it, one should refer to + <a href="http://www.faqs.org/rfcs/rfc4585.html">RFC 4585</a>.</p> + + </tp:docstring> + + <property name="FeedbackMessages" type="a{u(ua(sss))}" + tp:type="RTCP_Feedback_Message_Map" + access="read" tp:name-for-bindings="Feedback_Messages"> + <tp:docstring> + A map of remote feedback codec properties that are supported. + </tp:docstring> + </property> + + <property name="DoesAVPF" type="b" + access="read" tp:name-for-bindings="Does_AVPF"> + <tp:docstring> + True if the remote contact supports Audio-Visual Profile + Feedback (AVPF), otherwise False. + </tp:docstring> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Media_Description_Interface_RTP_Header_Extensions.xml b/spec/Call_Content_Media_Description_Interface_RTP_Header_Extensions.xml new file mode 100644 index 000000000..a35615add --- /dev/null +++ b/spec/Call_Content_Media_Description_Interface_RTP_Header_Extensions.xml @@ -0,0 +1,73 @@ +<?xml version="1.0" ?> +<node name="/Call_Content_Media_Description_Interface_RTP_Header_Extensions" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +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 Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call1.Content.MediaDescription.Interface.RTPHeaderExtensions" + tp:causes-havoc="experimental"> + <tp:added version="0.23.4">(draft version, not API-stable)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Call1.Content.MediaDescription"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This media description interface provides a method of signalling + support for RTP Header Extensions, documented by + <em>A General Mechanism for RTP Header Extensions (RFC 5285)</em>.</p> + + <p>For more details on the General Mechanism for RTP Header Extensions + and how to use them, one should refer to + <a href="http://www.faqs.org/rfcs/rfc5285.html">RFC 5285</a>.</p> + + </tp:docstring> + + <tp:struct name="RTP_Header_Extension" + array-name="RTP_Header_Extensions_List"> + <tp:docstring> + A struct defining a RTP Header extension. + </tp:docstring> + <tp:member type="u" name="ID"> + <tp:docstring> + Identifier to be negotiated. + </tp:docstring> + </tp:member> + <tp:member type="u" tp:type="Media_Stream_Direction" name="Direction"> + <tp:docstring> + Direction in which the Header Extension is negotiated. + </tp:docstring> + </tp:member> + <tp:member type="s" name="URI"> + <tp:docstring> + URI defining the extension. + </tp:docstring> + </tp:member> + <tp:member type="s" name="Parameters"> + <tp:docstring> + Feedback parameters as a string. Format is defined in the relevant RFC. + </tp:docstring> + </tp:member> + </tp:struct> + + <property name="HeaderExtensions" type="a(uuss)" + tp:type="RTP_Header_Extension[]" + access="read" tp:name-for-bindings="Header_Extensions"> + <tp:docstring> + A list of remote header extensions which are supported. + </tp:docstring> + </property> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Interface_Mute.xml b/spec/Call_Interface_Mute.xml new file mode 100644 index 000000000..e0089720f --- /dev/null +++ b/spec/Call_Interface_Mute.xml @@ -0,0 +1,144 @@ +<?xml version="1.0" ?> +<node name="/Call_Interface_Mute" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright> + <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +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 Street, Fifth Floor, Boston, MA 02110-1301, USA. + </tp:license> + + <interface name="org.freedesktop.Telepathy.Call1.Interface.Mute" tp:causes-havoc="experimental"> + <tp:added version="0.19.6">(draft version, not API-stable)</tp:added> + <tp:xor-requires interface="org.freedesktop.Telepathy.Channel.Type.Call1"/> + <tp:xor-requires interface="org.freedesktop.Telepathy.Call1.Content"/> + <tp:xor-requires interface="org.freedesktop.Telepathy.Call1.Stream"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for calls which may be muted. This only makes sense + for channels where audio or video is streaming between members.</p> + + <p>Muting a call content indicates that the user does not wish to send + outgoing audio or video.</p> + + <p>It should always be possible to mute an entire call. It is sometimes + also possible to mute individual Contents (e.g. to prevent background + noise from disturbing other participants, but remain visible on + webcam) or to mute individual streams (e.g. to "whisper" to other call + participants)</p> + + <tp:rationale> + For some protocols, the fact that the content is muted needs + to be transmitted to the peer; for others, the notification + to the peer is only informational (eg. XMPP), and some + protocols may have no notion of muting at all. + </tp:rationale> + </tp:docstring> + + <tp:enum name="Local_Mute_State" type="u"> + <tp:docstring> + The mute state of (at least part of) the call. See + <tp:member-ref>LocalMuteState</tp:member-ref> for more details. + </tp:docstring> + + <tp:enumvalue value="0" suffix="Unmuted"> + <tp:docstring> + All streams are unmuted (the call is active). New channels SHOULD + have this mute state. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="1" suffix="Muted"> + <tp:docstring> + All streams are Muted. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="2" suffix="Pending_Mute"> + <tp:docstring> + The connection manager is attempting to move to state Muted, but + has not yet completed that operation. It is unspecified whether + any, all or none of the streams making up the channel are muted. + Examining the Mute state of Call Contents (if applicable) may + provide more useful information. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="3" suffix="Pending_Unmute"> + <tp:docstring> + The connection manager is attempting to move to state Unmuted, but + has not yet completed that operation. It is unspecified whether + any, all or none of the streams making up the channel are muted. + Examining the Mute state of Call Contents or Streams may + provide more useful information. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue value="4" suffix="Partially_Muted"> + <tp:docstring> + Some of the constituent Streams are Muted. This state only makes + sense on Call Channels or Contents. + Examining the Mute state of Call Contents or Streams should + provide more useful information. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed"> + <tp:docstring> + Emitted to indicate that the mute state has changed for this call content. + This may occur as a consequence of the client calling + <tp:member-ref>RequestMuted</tp:member-ref>, or as an indication that another + client has (un)muted the content. + </tp:docstring> + <arg name="MuteState" type="u" tp:type="Local_Mute_State"> + <tp:docstring> + The new mute state. + </tp:docstring> + </arg> + </signal> + + <property name="LocalMuteState" type="u" tp:type="Local_Mute_State" + access="read" tp:name-for-bindings="Local_Mute_State"> + <tp:docstring> + The current mute state of this part of the call. New + <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref>s should + inherit the value of this property from the parent + <tp:dbus-ref namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>. + Similarly, <tp:dbus-ref namespace="ofdT.Call1">Stream</tp:dbus-ref>s + should inherit it from the parent <tp:dbus-ref + namespace="ofdT.Call1">Content</tp:dbus-ref>. + </tp:docstring> + </property> + + <method name="RequestMuted" tp:name-for-bindings="Request_Muted"> + <tp:changed version="0.21.2">renamed from SetMuted to Mute</tp:changed> + <tp:changed version="0.21.3">renamed back from Mute to SetMuted</tp:changed> + <arg direction="in" name="Muted" type="b"> + <tp:docstring> + True if the client wishes to mute the Content or Call. + </tp:docstring> + </arg> + <tp:docstring> + <p>Inform the CM that the Call, Content or Stream should be muted or + unmuted.</p> + + <p>The CM will tell the streaming implementation to Mute Streams as + required, and emit <tp:member-ref>MuteStateChanged</tp:member-ref> + when done.</p> + </tp:docstring> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml index 1d7b28147..2693f5305 100644 --- a/spec/Call_Stream.xml +++ b/spec/Call_Stream.xml @@ -20,13 +20,16 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call.Stream.DRAFT" + <interface name="org.freedesktop.Telepathy.Call1.Stream" tp:causes-havoc="experimental"> <tp:added version="0.19.0">(draft 1)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> One stream inside a <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>. + namespace="ofdT.Call1">Content</tp:dbus-ref>. A stream is + a single flow of packets to and from a single remote endpoint. + If your call connects to multiple people, you could have + multiple streams. </tp:docstring> <method name="SetSending" tp:name-for-bindings="Set_Sending"> @@ -39,18 +42,24 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If True, the <tp:member-ref>LocalSendingState</tp:member-ref> should - change to <tp:type>Sending_State</tp:type>_Sending, if it isn't + change to <tp:value-ref type="Sending_State">Sending</tp:value-ref>, if it isn't already.</p> <p>If False, the <tp:member-ref>LocalSendingState</tp:member-ref> should - change to <tp:type>Sending_State</tp:type>_None, if it isn't + change to <tp:value-ref type="Sending_State">None</tp:value-ref>, if it isn't already.</p> </tp:docstring> </arg> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented" /> + <tp:error name="org.freedesktop.Telepathy.Error.NotYet"> + <tp:docstring>If the call has not been accepted yet, calling + SetSending(True) is an error. See + <tp:member-ref>LocalSendingState</tp:member-ref> for details. + </tp:docstring> + </tp:error> </tp:possible-errors> </method> @@ -116,6 +125,11 @@ property, as a result of the contact leaving this stream </tp:docstring> </arg> + <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason"> + <tp:docstring> + A structured reason for the change. + </tp:docstring> + </arg> </signal> <signal name="LocalSendingStateChanged" @@ -130,6 +144,12 @@ <tp:member-ref>LocalSendingState</tp:member-ref>. </tp:docstring> </arg> + + <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason"> + <tp:docstring> + A structured reason for the change. + </tp:docstring> + </arg> </signal> <tp:enum name="Sending_State" type="u"> @@ -184,7 +204,7 @@ <tp:added version="0.19.11"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Extra interfaces provided by this stream, such as <tp:dbus-ref - namespace="ofdT.Call">Stream.Interface.Media.DRAFT</tp:dbus-ref>. + namespace="ofdT.Call1">Stream.Interface.Media</tp:dbus-ref>. This SHOULD NOT include the Stream interface itself, and cannot change once the stream has been created.</p> </tp:docstring> @@ -194,18 +214,28 @@ type="a{uu}" access="read" tp:type="Contact_Sending_State_Map"> <tp:changed version="0.21.2">renamed from Senders</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A map from remote contacts to their sending state. The - local user's sending state is shown in - <tp:member-ref>LocalSendingState</tp:member-ref>.</p> - - <p><tp:type>Sending_State</tp:type>_Pending_Send indicates - that another contact has asked the local user to send - media.</p> - - <p>Other contacts' handles in this map indicate whether they are - sending media to the contacts in this stream. - Sending_State_Pending_Send indicates contacts who are not sending but - have been asked to do so.</p> + <p>A map from remote contacts to their sending state.</p> + + <p>Media sent to this stream will be sent to all members listed here. + All members listed here will also appear in <tp:dbus-ref + namespace="ofdT.Channel.Type.Call1">CallMembers</tp:dbus-ref>, + and each CallMembers member will be listed in at most one Stream per + Content. Therefore, to hide things from a member of the + call, UIs only need to mute one Stream per Content.</p> + + <p>Contacts' handles in this map indicate whether they are + sending media to this stream. Sending_State_Pending_Send indicates + contacts who are not sending but have been asked to do so. The + local user's sending state is shown in <tp:member-ref + >LocalSendingState</tp:member-ref>.</p> + + <p>This mapping is also used by the streaming implementation to map + from <tp:dbus-ref namespace="ofdT.Call1.Content" + >MediaDescription</tp:dbus-ref>s to Streams. In this use-case, + all of the senders in this stream will be represented in + <tp:dbus-ref namespace="ofdT.Call1.Content.Interface.Media" + >RemoteMediaDescriptions</tp:dbus-ref>. This use-case should not + affect anything that does not handle media streaming.</p> </tp:docstring> </property> @@ -228,20 +258,20 @@ special-cased. </tp:rationale> - <p>A value of <tp:type>Sending_State</tp:type>_Pending_Send for + <p>A value of <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> for this property indicates that the other side requested the - local user start sending media, which can be done by calling - <tp:member-ref>SetSending</tp:member-ref>. When a call is - accepted, all initial contents with streams that have a - local sending state of - <tp:type>Sending_State</tp:type>_Pending_Send are - automatically set to sending. For example, on an incoming - call it means you need to <tp:dbus-ref - namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> - to start the actual call, on an outgoing call it might mean - you need to call <tp:dbus-ref - namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref> - before actually starting the call.</p> + local user start sending media (which can be done by calling either + <tp:member-ref>SetSending</tp:member-ref> or <tp:dbus-ref + namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref>).</p> + + <p>When <tp:dbus-ref + namespace="ofdT.Channel.Type.Call1">Accept</tp:dbus-ref> is + called, all streams with a local sending state of + <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> and the associated + <tp:dbus-ref namespace="ofdT.Call1.Content" + >Disposition</tp:dbus-ref> set to + <tp:value-ref type="Call_Content_Disposition">Initial</tp:value-ref> are + automatically set to sending.</p> </tp:docstring> </property> diff --git a/spec/Call_Stream_Endpoint.xml b/spec/Call_Stream_Endpoint.xml index cf1783d1e..2aa7e52f3 100644 --- a/spec/Call_Stream_Endpoint.xml +++ b/spec/Call_Stream_Endpoint.xml @@ -20,7 +20,7 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call.Stream.Endpoint.DRAFT" + <interface name="org.freedesktop.Telepathy.Call1.Stream.Endpoint" tp:causes-havoc="experimental"> <tp:added version="0.19.0">(draft 1)</tp:added> @@ -92,39 +92,99 @@ </arg> </signal> - <signal name="CandidateSelected" - tp:name-for-bindings="Candidate_Selected"> + <tp:struct name="Candidate_Pair" array-name="Candidate_Pair_List"> + <tp:docstring>A Pair of candidates.</tp:docstring> + <tp:member name="Local" type="(usua{sv})" tp:type="Candidate"> + <tp:docstring>The local candidate.</tp:docstring> + </tp:member> + <tp:member name="Remote" type="(usua{sv})" tp:type="Candidate"> + <tp:docstring>The remote candidate.</tp:docstring> + </tp:member> + </tp:struct> + + <signal name="CandidatePairSelected" + tp:name-for-bindings="Candidate_Pair_Selected"> <tp:docstring> - Emitted when a candidate is selected for use in the stream. + Emitted when a candidate is selected for use in the stream by the + controlling side of an ICE session. + The controlled side should call + <tp:member-ref>AcceptSelectedCandidatePair</tp:member-ref> or + <tp:member-ref>RejectSelectedCandidatePair</tp:member-ref> when + connectivity checks have either succeeded or failed for this candidate + pair. See also: <tp:member-ref>SelectedCandidatePairs</tp:member-ref>. </tp:docstring> - <arg name="Candidate" + <arg name="Local_Candidate" + type="(usua{sv})" tp:type="Candidate"> + <tp:docstring> + The local candidate that has been selected. + </tp:docstring> + </arg> + <arg name="Remote_Candidate" type="(usua{sv})" tp:type="Candidate"> <tp:docstring> - The candidate that has been selected. + The remote candidate that has been selected. </tp:docstring> </arg> </signal> - <property name="SelectedCandidate" - tp:name-for-bindings="Selected_Candidate" - type="(usua{sv})" tp:type="Candidate" access="read"> - <tp:docstring> - The candidate that has been selected for use to stream packets - to the remote contact. Change notification is given via the - the <tp:member-ref>CandidateSelected</tp:member-ref> signal. + <property name="SelectedCandidatePairs" + tp:name-for-bindings="Selected_Candidate_Pairs" + type="a((usua{sv})(usua{sv}))" tp:type="Candidate_Pair[]" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The candidates that have been selected for use to stream packets + to the remote contact for each component of the stream. + Change notification is given via the + the <tp:member-ref>CandidatePairSelected</tp:member-ref> signal.</p> + + <p>Note to client implementors (from <a + href="http://tools.ietf.org/html/rfc5245#section-9.2.2.3">RFC 5245 + section 9.2.2.3</a>):</p> + + <blockquote> + <p>If at least one of the pairs is In-Progress, the agent SHOULD wait + for those checks to complete, and as each completes, redo the + processing in this section until there are no losing pairs.</p> + </blockquote> + + <p>Also note that some or all of the local candidates in this list may + represent a peer-reflexive candidate that do not appear in + <tp:dbus-ref namespace="ofdT.Call1.Stream.Interface.Media" + >LocalCandidates</tp:dbus-ref>.</p> + + <p>See <a href='http://tools.ietf.org/html/rfc5245#appendix-B.6'>RFC + 5245 Appendix B.6.</a> for more details about why this is.</p> </tp:docstring> </property> - <method name="SetSelectedCandidate" - tp:name-for-bindings="Set_Selected_Candidate"> - <tp:docstring> - Set the value of - <tp:member-ref>CandidateSelected</tp:member-ref>. + <method name="SetSelectedCandidatePair" + tp:name-for-bindings="Set_Selected_Candidate_Pair"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Update the entry in + <tp:member-ref>SelectedCandidatePairs</tp:member-ref> + for a particular component, and signal it to the remote side.</p> + + <p>This method should only be called by the controlling side of an + ICE session. See <tp:member-ref>CandidatePairSelected</tp:member-ref> + for details.</p> + + <tp:rationale> + <p>In the SDP offer/answer model, this signalling will take place as + generating an updated offer. + Note that updates may be queued up until information about all + components of all streams is gathered.</p> + </tp:rationale> </tp:docstring> - <arg name="Candidate" + <arg name="Local_Candidate" + type="(usua{sv})" tp:type="Candidate" direction="in"> + <tp:docstring> + The local candidate that has been selected. + </tp:docstring> + </arg> + <arg name="Remote_Candidate" type="(usua{sv})" tp:type="Candidate" direction="in"> <tp:docstring> - The candidate that has been selected. + The remote candidate that has been selected. </tp:docstring> </arg> <tp:possible-errors> @@ -132,36 +192,95 @@ </tp:possible-errors> </method> - <property name="StreamState" tp:name-for-bindings="Stream_State" - type="u" tp:type="Media_Stream_State" + <tp:enum name="Stream_Endpoint_State" type="u"> + <tp:docstring> + Represents the state of ICE negotiation for a single component of a + stream to an endpoint. + </tp:docstring> + <tp:enumvalue suffix="Connecting" value="0"> + <tp:docstring> + Candidate gathering and connectivity checks are in progress. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Provisionally_Connected" value="1"> + <tp:docstring> + The streaming implementation has found at least one working + candidate pair. It is possible to send media at this point, but the + controlling side has yet to negotiate the final candidates for use + in this call. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Fully_Connected" value="2"> + <tp:docstring> + This component of the stream is connected, and an updated offer has + been sent and accepted (finalising the candidates to be used for the + call). This should be set by the CM in response to + <tp:member-ref>AcceptSelectedCandidatePair</tp:member-ref>. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Exhausted_Candidates" value="3"> + <tp:docstring> + The streaming implementation has tried connecting to all of the + available candidates and none of them have connected. This is + distinct from Failed, because the CM might be able to provide more + candidates later (more likely in XMPP than SIP). + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Failed" value="4"> + <tp:docstring> + The CM and streaming implementation are in agreement that it is + impossible to connect to this endpoint. This value should only be + set by the CM. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:mapping name="Component_State_Map"> + <tp:member name="Component" type="u" tp:type="Stream_Component"/> + <tp:member name="State" type="u" tp:type="Stream_Endpoint_State"/> + </tp:mapping> + + <property name="EndpointState" tp:name-for-bindings="Endpoint_State" + type="a{uu}" tp:type="Component_State_Map" access="read"> <tp:docstring> - The stream state of the endpoint. + The state of ICE negotiation with this Endpoint for each component of + the stream. </tp:docstring> </property> - <signal name="StreamStateChanged" - tp:name-for-bindings="Stream_State_Changed"> + <signal name="EndpointStateChanged" + tp:name-for-bindings="Endpoint_State_Changed"> <tp:docstring> - Emitted when the <tp:member-ref>StreamState</tp:member-ref> + Emitted when the <tp:member-ref>EndpointState</tp:member-ref> property changes. </tp:docstring> - <arg name="state" type="u" tp:type="Media_Stream_State"> + <arg name="Component" type="u" tp:type="Stream_Component"> + <tp:docstring> + The component whose state has changed. + </tp:docstring> + </arg> + <arg name="State" type="u" tp:type="Stream_Endpoint_State"> <tp:docstring> - The new <tp:member-ref>StreamState</tp:member-ref> value. + The new state of this component. </tp:docstring> </arg> </signal> - <method name="SetStreamState" - tp:name-for-bindings="Set_Stream_State"> + <method name="SetEndpointState" + tp:name-for-bindings="Set_Endpoint_State"> <tp:docstring> - Change the <tp:member-ref>StreamState</tp:member-ref> of the + Change the <tp:member-ref>EndpointState</tp:member-ref> of the endpoint. </tp:docstring> - <arg direction="in" name="State" type="u" tp:type="Media_Stream_State"> + <arg direction="in" name="Component" type="u" tp:type="Stream_Component"> + <tp:docstring> + The component whose state needs updating. + </tp:docstring> + </arg> + <arg direction="in" name="State" type="u" tp:type="Stream_Endpoint_State"> <tp:docstring> - The requested stream state. + The new state of this component. </tp:docstring> </arg> <tp:possible-errors> @@ -170,6 +289,54 @@ </tp:possible-errors> </method> + <method name="AcceptSelectedCandidatePair" + tp:name-for-bindings="Accept_Selected_Candidate_Pair"> + <tp:docstring> + Called in response to + <tp:member-ref>CandidatePairSelected</tp:member-ref> if/when this + candidate pair is known to have passed its connectivity checks. + </tp:docstring> + <arg name="Local_Candidate" + type="(usua{sv})" tp:type="Candidate" direction="in"> + <tp:docstring> + The local candidate that has been selected. + </tp:docstring> + </arg> + <arg name="Remote_Candidate" + type="(usua{sv})" tp:type="Candidate" direction="in"> + <tp:docstring> + The remote candidate that has been selected. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> + </method> + + <method name="RejectSelectedCandidatePair" + tp:name-for-bindings="Reject_Selected_Candidate_Pair"> + <tp:docstring> + Called in response to + <tp:member-ref>CandidatePairSelected</tp:member-ref> if/when this + candidate pair is known to have failed its connectivity checks. + </tp:docstring> + <arg name="Local_Candidate" + type="(usua{sv})" tp:type="Candidate" direction="in"> + <tp:docstring> + The local candidate that has been selected. + </tp:docstring> + </arg> + <arg name="Remote_Candidate" + type="(usua{sv})" tp:type="Candidate" direction="in"> + <tp:docstring> + The remote candidate that has been selected. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + </tp:possible-errors> + </method> + <property name="Transport" tp:name-for-bindings="Transport" type="u" tp:type="Stream_Transport_Type" access="read"> <tp:docstring> @@ -177,6 +344,57 @@ </tp:docstring> </property> + <property name="Controlling" tp:name-for-bindings="Controlling" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + The local side is taking the controlling role (as defined by ICE RFC + 5245). Change notification is given via the + <tp:member-ref>ControllingChanged</tp:member-ref> signal.</p> + + <tp:rationale>In ICE, the Caller is normally in controlling mode (and + the Callee in controlled-mode), except if the Caller is doing ICE-Lite, + in which case it's reversed. The Controlling side is responsible for + selecting nominated pairs, and generating updated offers upon + conclusion of ICE.</tp:rationale> + </tp:docstring> + </property> + + <method name="SetControlling" + tp:name-for-bindings="Set_Controlling"> + <tp:docstring> + Set whether the local side is taking the Controlling role. Note that + if there are multiple endpoints (e.g. SIP call forking) it may be the + case that all endpoints need to have the same controlling/controlled + orientation. + </tp:docstring> + <arg name="Controlling" type="b" direction="in"> + <tp:docstring> + The new value of <tp:member-ref>Controlling</tp:member-ref>. + </tp:docstring> + </arg> + </method> + + <signal name="ControllingChanged" + tp:name-for-bindings="Controlling_Changed"> + <tp:docstring> + The value of <tp:member-ref>Controlling</tp:member-ref> has changed. + </tp:docstring> + <arg name="Controlling" type="b"> + <tp:docstring> + The new value of <tp:member-ref>Controlling</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <property name="IsICELite" tp:name-for-bindings="Is_ICE_Lite" + type="b" access="read"> + <tp:docstring> + The Remote side is an ICE Lite endpoint. (The local side is assumed to + always be an ICE Full implementation.) + </tp:docstring> + </property> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml index 54476f0fa..450d5ea42 100644 --- a/spec/Call_Stream_Interface_Media.xml +++ b/spec/Call_Stream_Interface_Media.xml @@ -20,35 +20,210 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT" + <interface name="org.freedesktop.Telepathy.Call1.Stream.Interface.Media" tp:causes-havoc="experimental"> <tp:added version="0.19.0">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.Call.Stream.DRAFT"/> + <tp:requires interface="org.freedesktop.Telepathy.Call1.Stream"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - [FIXME] + <p>This interface deals with how to connect a stream to an + endpoint. It contains all that is required to describe the + local endpoint, to succesfully establish a connection. While a + call is established, one may try to connect to multiple remote + endpoints at the same time. This is called forking in the SIP + jargon. Informations related to the connections are on the + <tp:dbus-ref + namespace="ofdT.Call1.Stream">Endpoint</tp:dbus-ref> + objects. Once the call is established, there MUST be a single + endpoint left.</p> <h4>ICE restarts</h4> - <p>If the <tp:dbus-ref - namespace="ofdT.Call.Stream.Endpoint.DRAFT">RemoteCredentialsSet</tp:dbus-ref> - signal is fired during a call once it has been called before - whilst setting up the call for initial use, and the - credentials have changed, then there has been an ICE - restart. In such a case, the CM SHOULD also empty the remote - candidate list in the <tp:dbus-ref - namespace="ofdT.Call.Stream">Endpoint.DRAFT</tp:dbus-ref>.</p> - - <p>If the CM does an ICE restart, then the - <tp:member-ref>PleaseRestartICE</tp:member-ref> signal is - emitted and the streaming implementation should then call - <tp:member-ref>SetCredentials</tp:member-ref> again.</p> + <p>If the CM wants to do an ICE restart, then the + <tp:member-ref>ICERestartPending</tp:member-ref> property is set, + and the <tp:member-ref>ICERestartRequested</tp:member-ref> signal is + emitted. The streaming implementation should then call + <tp:member-ref>SetCredentials</tp:member-ref> again. This will trigger + the actual ICE restart, and cause + <tp:member-ref>LocalCandidates</tp:member-ref> to be cleared.</p> <p>For more information on ICE restarts see <a href="http://tools.ietf.org/html/rfc5245#section-9.1.1.1">RFC 5245 section 9.1.1.1</a></p> </tp:docstring> + <tp:enum type="u" name="Stream_Flow_State"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The type of <tp:member-ref>SendingState</tp:member-ref> + and <tp:member-ref>ReceivingState</tp:member-ref>. + </tp:docstring> + <tp:enumvalue suffix="Stopped" value="0"> + <tp:docstring> + No data is flowing (or expected to be flowing) at this time. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Pending_Start" value="1"> + <tp:docstring> + The streaming implementation has been told to start or receiving, + but has not yet indicated that it is doing so. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Pending_Stop" value="2"> + <tp:docstring> + The streaming implementation has been told to stop sending or + receiving data, but it has not yet indicated that it has done so. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Started" value="3"> + <tp:docstring> + The streaming implementation is successfully sending or receiving + data, and everything is going swimmingly. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Pending_Pause" value="4"> + <tp:docstring> + The streaming implementation has been told to pause sending or + displaying data, but it has not yet indicated that it has done so. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Paused" value="5"> + <tp:docstring> + The streaming implementation has successfully paused either sending or + displaying data, and the local user's privacy or peace-and-quiet is + protected. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="SendingState" tp:name-for-bindings="Sending_State" + type="u" tp:type="Stream_Flow_State" access="read"> + <tp:docstring> + Indicates whether the streaming implementation is/should be sending + media for this stream. The streaming implementation should be able to + rely on reading this value and listening to + <tp:member-ref>SendingStateChanged</tp:member-ref> to + determine whether it should be sending media or not. It should not + need to listen to the Mute/Hold interfaces on the Call/Content. + Feedback on success should be given via + <tp:member-ref>CompleteSendingStateChange</tp:member-ref>. Failures + should be reported via <tp:member-ref>ReportSendingFailure</tp:member-ref>. + </tp:docstring> + </property> + + <signal name="SendingStateChanged" + tp:name-for-bindings="Sending_State_Changed"> + <tp:docstring> + Change notification for <tp:member-ref>SendingState</tp:member-ref>. + Note that this information is duplicated onto the Stream interface, so + that UIs can ignore the Media interface, and streaming implementations + can ignore everything but the media interface. + </tp:docstring> + <arg name="State" type="u" tp:type="Stream_Flow_State"> + <tp:docstring> + The new value of SendingState. + </tp:docstring> + </arg> + </signal> + + <method name="CompleteSendingStateChange" + tp:name-for-bindings="Complete_Sending_State_Change"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called in response to + <tp:member-ref>SendingStateChanged</tp:member-ref>(Pending_*, *) to + indicate that the media state has successfully progressed from + Pending_{Start, Stop, Pause} to the corresponding non-pending + state.</p> + </tp:docstring> + <arg name="State" type="u" tp:type="Stream_Flow_State" direction="in"> + <tp:docstring> + The new (non-pending) value of SendingState. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The state change made no sense, and was ignored by the CM. The + most likely cause for this is a race-condition between the CM + emitting a new state change and the streaming implementation + responding to the previous state change. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="ReportSendingFailure" + tp:name-for-bindings="Report_Sending_Failure"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Can be called at any point to indicate a failure in the outgoing + portion of the stream. + </tp:docstring> + <arg name="Reason" type="u" tp:type="Call_State_Change_Reason" + direction="in"/> + <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in"/> + <arg name="Message" type="s" direction="in"/> + </method> + + <property name="ReceivingState" tp:name-for-bindings="Receiving_State" + type="u" tp:type="Stream_Flow_State" access="read"> + <tp:docstring> + The counterpart of <tp:member-ref>SendingState</tp:member-ref>. + Indicates whether the streaming implementation is/should be expecting + to receive media for this stream. The CM should only tell the + streaming implementation to stop receiving if it has been told to put + the stream on hold, or the stream has been removed from the call. + </tp:docstring> + </property> + + <signal name="ReceivingStateChanged" + tp:name-for-bindings="Receiving_State_Changed"> + <tp:docstring> + Change notification for <tp:member-ref>ReceivingState</tp:member-ref>. + </tp:docstring> + <arg name="State" type="u" tp:type="Stream_Flow_State"> + <tp:docstring> + The new value of ReceivingState. + </tp:docstring> + </arg> + </signal> + + <method name="CompleteReceivingStateChange" + tp:name-for-bindings="Complete_Receiving_State_Change"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called in response to + <tp:member-ref>ReceivingStateChanged</tp:member-ref>(Pending_*, *) to + indicate that the media state has successfully progressed from + Pending_{Start, Stop, Pause} to the corresponding non-pending + state.</p> + </tp:docstring> + <arg name="State" type="u" tp:type="Stream_Flow_State" direction="in"> + <tp:docstring> + The new (non-pending) value of ReceivingState. + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The state change made no sense, and was ignored by the CM. The + most likely cause for this is a race-condition between the CM + emitting a new state change and the streaming implementation + responding to the previous state change. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="ReportReceivingFailure" + tp:name-for-bindings="Report_Receiving_Failure"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Can be called at any point to indicate a failure in the outgoing + portion of the stream. + </tp:docstring> + <arg name="Reason" type="u" tp:type="Call_State_Change_Reason" + direction="in"/> + <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in"/> + <arg name="Message" type="s" direction="in"/> + </method> + <method name="SetCredentials" tp:name-for-bindings="Set_Credentials"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Used to set the username fragment and password for streams that have @@ -66,6 +241,57 @@ </arg> </method> + <tp:enum type="u" name="Call_Stream_Candidate_Type"> + <tp:docstring> + The network topology that an IP candidate represents. This can + sometimes be used to infer what kind of performance characteristics + (latency, bandwith, etc) can be expected of connections made to this + candidate. + </tp:docstring> + <tp:enumvalue suffix="None" value="0"> + <tp:docstring> + This is not an IP candidate. This is a reserved value, and should + not be seen on the bus. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Host" value="1"> + <tp:docstring> + This candidate represents a direct connection to the host, as its + address is taken directly the host's IP stack. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Server_Reflexive" value="2"> + <tp:docstring> + This candidate probably represents a connection to the host through + a NAT device, as its address was discovered by sending a binding + request to a STUN server or similar. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Peer_Reflexive" value="3"> + <tp:docstring> + This candidate probably represents a good route between the host and + its peer, as its address was discovered by sending a STUN binding + request to one of the candidates advertised by the peer. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Relay" value="4"> + <tp:docstring> + This candidate represents the address of a relay server (usually + somewhere on the public internet). This candidate is the most likely + to work, but all media will go via a relay server, so latency is + likely to be higher than other types of candidate. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Multicast" value="5"> + <tp:docstring> + This candidate represents a Multicast group. This value should only + appear if the Stream's <tp:member-ref>Transport</tp:member-ref> is + set to Multicast. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:mapping name="Candidate_Info"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Extra information about the candidate. Allowed and mandatory keys @@ -73,32 +299,48 @@ used:</p> <dl> - <dt>Type (u)</dt> - <dd>type of candidate (host, srflx, prflx, relay)</dd> - - <dt>Foundation (s)</dt> - <dd>the foundation of this candiate</dd> + <dt><code>type</code> - u</dt> + <dd>The type of candidate + (<tp:type>Call_Stream_Candidate_Type</tp:type>)</dd> + + <dt><code>foundation</code> - s</dt> + <dd>The foundation of this candidate</dd> + + <dt><code>protocol</code> - u</dt> + <dd>Underlying protocol of the candidate + (<tp:type>Media_Stream_Base_Proto</tp:type>) </dd> + + <dt><code>priority</code> - u</dt> + <dd>Priority of the candidate (should be a number between 0 and + 65535). Most ICE implementations will prefer the highest priority + candidate pair that manages to connect. For backwards + compatibility with non-ICE SIP clients, the lowest priority + candidate may be sent as a raw UDP fallback candidate. + It is recommended that a relay candidate is used as the lowest + priority candidate if possible. If both IPv4 and IPv6 raw udp + fallback candidates are available, they should be set to the + same priority and advertised to the CM at the same time. The CM + will decide which to advertise to the remote end.</dd> + + <dt><code>base-ip</code> - s</dt> + <dd>The underlying Host address where media sent to this + (non-host-type) candidate will eventually arrive.</dd> + + <dt><code>base-port</code> - u</dt> + <dd>The underlying Host port where media sent to this + (non-host-type) candidate will eventually arrive.</dd> - <dt>Protocol (u) </dt> - <dd>Underlying protocol of the candidate (udp, tcp) </dd> - - <dt>Priority (u) </dt> - <dd>Priority of the candidate </dd> - - <dt>BaseIP (u) </dt> - <dd>Base IP of this candidate </dd> - - <dt>Username (s) </dt> + <dt><code>username</code> - s</dt> <dd>Username of this candidate (only if credentials are per candidate)</dd> - <dt>Password (s) </dt> + <dt><code>password</code> - s</dt> <dd>Password of this candidate (only if credentials are per candidate)</dd> - <dt>RawUDPFallback (b) </dt> - <dd>Indicate whether this candidate may be used to provide a UDP - fallback</dd> + <dt><code>ttl</code> - u</dt> + <dd>The TTL mandated for RTP/RTCP packets sent to a multicast group + (only valid for Multicast Streams)</dd> </dl> </tp:docstring> <tp:member name="Key" type="s"> @@ -156,7 +398,9 @@ <tp:docstring> Add candidates to the <tp:member-ref>LocalCandidates</tp:member-ref> property and - signal them to the remote contact(s). + signal them to the remote contact(s). Note that connection managers + MAY delay the sending of candidates until + <tp:member-ref>FinishInitialCandidates</tp:member-ref> is called. </tp:docstring> <arg name="Candidates" direction="in" type="a(usua{sv})" tp:type="Candidate[]"> @@ -166,11 +410,15 @@ </arg> </method> - <method name="CandidatesPrepared" - tp:name-for-bindings="Candidates_Prepared"> + <method name="FinishInitialCandidates" + tp:name-for-bindings="Finish_Initial_Candidates"> <tp:docstring> This indicates to the CM that the initial batch of candidates - has been added. + has been added, and should now be processed/sent to the remote side. + <tp:rationale> + Protocols supporting Raw UDP SHOULD wait for FinishInitialCandidates, + and then set the lowest priority candidate as the Raw UDP candidate. + </tp:rationale> </tp:docstring> </method> @@ -190,7 +438,7 @@ Raw UDP, with or without STUN. All streaming clients are assumed to support this transport, so there is no handler capability token for it in the <tp:dbus-ref namespace="ofdT.Channel.Type" - >Call.DRAFT</tp:dbus-ref> interface. + >Call1</tp:dbus-ref> interface. [This corresponds to "none" or "stun" in the old Media.StreamHandler interface.] </tp:docstring> @@ -277,8 +525,14 @@ <property name="LocalCredentials" tp:name-for-bindings="Local_Credentials" type="(ss)" tp:type="Stream_Credentials" access="read"> <tp:docstring> - [FIXME]. Change notification is via the + The local credentials are sent to the remote site over the + signalling protocol. They are used in ICE to make sure that + the connectivity checks come from the right peer. Change + notification is via the <tp:member-ref>LocalCredentialsChanged</tp:member-ref> signal. + + This property will be a pair of empty strings if ICE has not yet been + started. </tp:docstring> </property> @@ -287,7 +541,10 @@ <tp:changed version="0.21.2">renamed from LocalCredentailsSet</tp:changed> <tp:docstring> Emitted when the value of - <tp:member-ref>LocalCredentials</tp:member-ref> changes. + <tp:member-ref>LocalCredentials</tp:member-ref> changes to a non-empty + value. This should only happen when the streaming implementation calls + <tp:member-ref>SetCredentials</tp:member-ref>, so this signal is + mostly useful for debugging. </tp:docstring> <arg name="Username" type="s" /> <arg name="Password" type="s" /> @@ -333,7 +590,7 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A list of mappings describing TURN or Google relay servers available for the client to use in its candidate gathering, as - determined from the protocol. Map keys are:</p> + determined from the protocol. Well-known map keys are:</p> <dl> <dt><code>ip</code> - s</dt> @@ -366,6 +623,22 @@ <dd>The UDP or TCP port of the relay server as an ASCII unsigned integer</dd> + <dt><code>unique-id</code> - s</dt> + <dd>A string identifying the relay server. If two RelayInfo entries + have the same unique-id, but different <code>type</code>s, there + is usually little point in connecting to both. Use + <code>priority</code> to determine which version to prefer in this + case. Can also be used by the streaming implementation to avoid + connecting to the same relay multiple times if relaying is + required for both audio and video.</dd> + + <dt><code>priority</code> - u</dt> + <dd>A number determining which version of a server to prefer (if + multiple are present with the same <code>unique-id</code>, + the one with the highest priority should be used, or the streaming + implementation should use the one whose <code>type</code> has the + most desirable properties)</dd> + <dt><code>username</code> - s</dt> <dd>The username to use</dd> @@ -451,8 +724,8 @@ <property name="Endpoints" tp:name-for-bindings="Endpoints" type="ao" access="read"> <tp:docstring> - <p>The list of <tp:dbus-ref namespace="ofdT.Call.Stream" - >Endpoint.DRAFT</tp:dbus-ref> objects that exist for this + <p>The list of <tp:dbus-ref namespace="ofdT.Call1.Stream" + >Endpoint</tp:dbus-ref> objects that exist for this stream.</p> <p>Change notification is via the @@ -460,14 +733,38 @@ </tp:docstring> </property> - <signal name="PleaseRestartICE" - tp:name-for-bindings="Please_Restart_ICE"> + <signal name="ICERestartRequested" + tp:name-for-bindings="ICE_Restart_Requested"> <tp:docstring> - Emitted when the CM does an ICE restart to notify the - streaming implementation that it should call + Emitted when the remote side requests an ICE restart (e.g. third party + call control, when the remote endpoint changes). The streaming + implementation should call <tp:member-ref>SetCredentials</tp:member-ref> again. </tp:docstring> </signal> + + <property name="ICERestartPending" + tp:name-for-bindings="ICE_Restart_Pending" access="read" type="b"> + <tp:docstring> + State recovery for <tp:member-ref>ICERestartRequested</tp:member-ref>. + Set when the signal is emitted, and unset when + <tp:member-ref>SetCredentials</tp:member-ref> is called. + Useful for debugging. + </tp:docstring> + </property> + + <method name="Fail" tp:name-for-bindings="Fail"> + <tp:docstring> + Signal an unrecoverable error for this stream, and remove it. If all + streams are removed from a content, then it will also be removed. + </tp:docstring> + <arg direction="in" name="Reason" type="(uuss)" + tp:type="Call_State_Reason"> + <tp:docstring> + A structured reason for stream removal. + </tp:docstring> + </arg> + </method> </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml index 242c95284..58a222c19 100644 --- a/spec/Channel_Interface_Media_Signalling.xml +++ b/spec/Channel_Interface_Media_Signalling.xml @@ -21,6 +21,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/> + <tp:changed version="0.24.0">The old-style Telepathy properties, + deprecated since March 2009, have been removed.</tp:changed> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An interface for signalling a channel containing synchronised media @@ -104,54 +106,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> - <tp:property name="nat-traversal" type="s"> - <tp:deprecated version="0.17.22">Use the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> - property on the Media.StreamHandler, if available; use this - as a fallback.</tp:deprecated> - <tp:docstring> - A string indicating the NAT traversal techniques employed by the - streams within this channel if they do not have a <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref> - property. The possible values are the same as for the NATTraversal - property on the streams. - </tp:docstring> - </tp:property> - - <tp:property name="stun-server" type="s"> - <tp:deprecated version="0.17.22">Use the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref> - property on the Media.StreamHandler, if available; use this - as a fallback.</tp:deprecated> - <tp:docstring> - The IP address or hostname of the STUN server to use for NAT traversal - if the individual streams do not specify one. - </tp:docstring> - </tp:property> - - <tp:property name="stun-port" type="q"> - <tp:deprecated version="0.17.22">Use the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref> - property on the Media.StreamHandler, if available; use this - as a fallback.</tp:deprecated> - <tp:docstring> - The UDP port number to use on the provided STUN server. - </tp:docstring> - </tp:property> - - <tp:property name="gtalk-p2p-relay-token" type="s"> - <tp:deprecated version="0.17.22">XMPP connection managers - supporting the Google Talk relay server SHOULD make the necessary - HTTP requests to find a username and password, and use those - to populate the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Media.StreamHandler">RelayInfo</tp:dbus-ref> - property on the Media.StreamHandler.</tp:deprecated> - <tp:docstring> - The authentication token for use with the Google Talk peer-to-peer relay - server. - </tp:docstring> - </tp:property> - <tp:hct name="gtalk-p2p"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The client can implement streaming for streams whose <tp:dbus-ref diff --git a/spec/Channel_Interface_Password.xml b/spec/Channel_Interface_Password.xml index 4e201ddf5..8aec20015 100644 --- a/spec/Channel_Interface_Password.xml +++ b/spec/Channel_Interface_Password.xml @@ -1,7 +1,7 @@ <?xml version="1.0" ?> <node name="/Channel_Interface_Password" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> <tp:copyright> -Copyright © 2005-2009 Collabora Limited +Copyright © 2005-2011 Collabora Limited Copyright © 2005-2009 Nokia Corporation Copyright © 2006 INdT </tp:copyright> @@ -90,14 +90,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </method> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Interface for channels that may have a password set that users need - to provide before being able to join, or may be able to view or change - once they have joined the channel.</p> + to provide before being able to join. The + <tp:member-ref>GetPasswordFlags</tp:member-ref> method and the + associated <tp:member-ref>PasswordFlagsChanged</tp:member-ref> + signal indicate whether the user must now provide a password to join + the channel.</p> - <p>The <tp:member-ref>GetPasswordFlags</tp:member-ref> method and the - associated <tp:member-ref>PasswordFlagsChanged</tp:member-ref> - signal indicate whether the channel has a password, whether the user - must now provide it to join, and whether it can be viewed or changed - by the user.</p> + <p>Once the user has joined the channel, the current + password-protectedness of the room can be checked (and possibly + modified) using the <tp:dbus-ref + namespace='ofdT.Channel.Interface'>RoomConfig1</tp:dbus-ref> + interface, if implemented.</p> </tp:docstring> </interface> </node> diff --git a/spec/Channel_Interface_Room.xml b/spec/Channel_Interface_Room.xml index ffdf4a96d..8f3d3c150 100644 --- a/spec/Channel_Interface_Room.xml +++ b/spec/Channel_Interface_Room.xml @@ -21,10 +21,9 @@ 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.Channel.Interface.Room2"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:added version="0.19.11">(draft 1)</tp:added> + <tp:added version="0.24.0">(version 2)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Different IM protocols use a variety of ways to name chat rooms. The @@ -40,7 +39,9 @@ href="http://xmpp.org/extensions/xep-0045.html#createroom-unique"><acronym title="XMPP Extension Protocol">XEP</acronym>-0045 §10.1.4 <q>Requesting a Unique Room Name</q></a> defines a protocol for - requesting a unique, opaque room name on the server.</p> + requesting a unique, opaque room name on the server. Note that + this interface is not restricted to Text channels, and can + also be used on Call channels.</p> <p>This interface intends to support and differentiate these mechanisms more clearly than the <tp:dbus-ref @@ -61,7 +62,7 @@ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> = <code>"#telepathy"</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>"#telepathy"</code>, + <tp:member-ref>RoomName</tp:member-ref> = <code>"#telepathy"</code>, <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating that the room has a human-readable identifier, and is not confined to a particular server on the network. @@ -82,7 +83,7 @@ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> = <code>"0xdeadbeef"</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>RoomName</tp:member-ref> = <code>""</code>, <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating that the room has an identifier but no human-readable name. </li> @@ -91,7 +92,7 @@ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> = <code>None</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>RoomName</tp:member-ref> = <code>""</code>, <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating that the room has neither an identifier (so it cannot be re-joined later) nor a human-readable name. @@ -105,7 +106,7 @@ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> = <code>"jdev@conference.jabber.org"</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>"jdev"</code>, + <tp:member-ref>RoomName</tp:member-ref> = <code>"jdev"</code>, <tp:member-ref>Server</tp:member-ref> = <code>"conference.jabber.org"</code>. </li> @@ -116,7 +117,7 @@ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> = <code>"private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com"</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>RoomName</tp:member-ref> = <code>""</code>, <tp:member-ref>Server</tp:member-ref> = <code>"groupchat.google.com"</code>, indicating that the room has a persistent identifier, no human-readable name, and is hosted by a @@ -131,7 +132,7 @@ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> = <code>"lrcgsnthzvwm@conference.jabber.org"</code>, - <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>, + <tp:member-ref>RoomName</tp:member-ref> = <code>""</code>, <tp:member-ref>Server</tp:member-ref> = <code>"conference.jabber.org"</code>, indicating that the room has a persistent identifier, no human-readable name, and is hosted by a @@ -165,7 +166,7 @@ >TargetHandle</tp:dbus-ref>.</p> <p>If, like IRC, the room identifiers are also human-readable, the - RCCs should also include RoomID in <var>Allowed_Properties</var>:</p> + RCCs should also include RoomName in <var>Allowed_Properties</var>:</p> <blockquote> <pre> @@ -179,7 +180,7 @@ >TargetID</tp:dbus-ref>, ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" >TargetHandle</tp:dbus-ref>, - ...<tp:member-ref>RoomID</tp:member-ref> + ...<tp:member-ref>RoomName</tp:member-ref> ] ), @@ -187,14 +188,14 @@ >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type" >Text</tp:dbus-ref> }, - Allowed = [ ...<tp:member-ref>RoomID</tp:member-ref>, + Allowed = [ ...<tp:member-ref>RoomName</tp:member-ref>, ] )</pre></blockquote> - <p>Requests may specify the RoomID in place of + <p>Requests may specify the RoomName in place of <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - . Note how <tp:member-ref>RoomID</tp:member-ref> appears + . Note how <tp:member-ref>RoomName</tp:member-ref> appears in <var>Allowed_Properties</var> of a different RCC because when <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" >TargetHandleType</tp:dbus-ref> is omitted (or is None), both @@ -202,7 +203,7 @@ >TargetHandle</tp:dbus-ref> and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" >TargetID</tp:dbus-ref> must also be omitted. - <tp:member-ref>RoomID</tp:member-ref> is allowed in conjuction + <tp:member-ref>RoomName</tp:member-ref> is allowed in conjuction with <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> @@ -221,7 +222,7 @@ fallback conference server is specified on jabber connections in gabble.</p> - <p>If the protocol supports unnamed rooms, <tp:member-ref>RoomID</tp:member-ref> + <p>If the protocol supports unnamed rooms, <tp:member-ref>RoomName</tp:member-ref> should be fixed to the empty string, and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> should be None:</p> @@ -233,7 +234,7 @@ >Text</tp:dbus-ref>, ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel" >TargetHandleType</tp:dbus-ref>: None, - ...<tp:member-ref>RoomID</tp:member-ref>: "", + ...<tp:member-ref>RoomName</tp:member-ref>: "", }, Allowed = [ ] )</pre></blockquote> @@ -242,7 +243,7 @@ <p>When explicitly joining a room, the CM cannot know whether the room ID is unique or not. As a result, if this is the case, adding an - empty string <tp:member-ref>RoomID</tp:member-ref> into the channel + empty string <tp:member-ref>RoomName</tp:member-ref> into the channel request will ensure the CM knows. For example:</p> <blockquote> @@ -250,16 +251,16 @@ { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room, ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "qwerasdfzxcv@conference.jabber.org", - ...<tp:member-ref>RoomID</tp:member-ref>: "" + ...<tp:member-ref>RoomName</tp:member-ref>: "" }</pre></blockquote> - <p>If <tp:member-ref>RoomID</tp:member-ref> features in + <p>If <tp:member-ref>RoomName</tp:member-ref> features in <var>Allowed_Properties</var> then the only value allowed in conjunction with <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> is the empty string. Requests with conflicting <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> - and <tp:member-ref>RoomID</tp:member-ref> properties + and <tp:member-ref>RoomName</tp:member-ref> properties will fail with InvalidArgument.</p> <p>To create a XEP-0045 §10.1.4 uniquely-named room channel @@ -269,7 +270,7 @@ <blockquote> <pre> { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, - ...<tp:member-ref>RoomID</tp:member-ref>: "" + ...<tp:member-ref>RoomName</tp:member-ref>: "" ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org" }</pre> </blockquote> @@ -282,20 +283,20 @@ { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>, ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room, ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "kajsdhkajshdfjkshdfjkhs@conference.jabber.org", - ...<tp:member-ref>RoomID</tp:member-ref>: "" + ...<tp:member-ref>RoomName</tp:member-ref>: "" ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org" }</pre> </blockquote> <p>The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs) and then created a room with such a name on the said server. The empty - <tp:member-ref>RoomID</tp:member-ref> property shows that the room name + <tp:member-ref>RoomName</tp:member-ref> property shows that the room name is not human-readable.</p> </tp:docstring> - <property name="RoomID" tp:name-for-bindings="Room_ID" type="s" - access="read"> + <property name="RoomName" tp:name-for-bindings="Room_Name" type="s" + access="read" tp:immutable="yes" tp:requestable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The human-readable identifier of a chat room. Note that if non-empty, this property (and perhaps also @@ -303,7 +304,10 @@ a channel request to join the room. XMPP MUCs have a room name concept which is more like a topic, except more persistent. This D-Bus property is <strong>not</strong> this - XMPP room name, but the bit before the @ in the room jid.</p> + XMPP room name, but the bit before the @ in the room jid; see + <tp:dbus-ref + namespace='ofdT.Channel.Interface'>RoomConfig1.Title</tp:dbus-ref> + for that concept.</p> <p>This property cannot change during the lifetime of the channel. It should appear in the <var>Allowed_Properties</var> of a @@ -314,7 +318,7 @@ </property> <property name="Server" tp:name-for-bindings="Server" type="s" - access="read"> + access="read" tp:immutable="yes" tp:requestable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>For protocols with a concept of chatrooms on multiple servers with different DNS names (like XMPP), the DNS name of the server hosting @@ -328,46 +332,6 @@ and only if non-empty values are supported.</p> </tp:docstring> </property> - - <tp:struct name="Room_Subject"> - <tp:docstring> - A struct representing the subject of a room channel. - </tp:docstring> - <tp:member type="s" name="Subject"> - <tp:docstring> - A human-readable description of the current subject of - conversation in the channel, similar to /topic in IRC. - </tp:docstring> - </tp:member> - <tp:member type="s" name="Actor"> - <tp:docstring> - A normalized contact ID representing who last modified the - subject, or the empty string if it is not known. - </tp:docstring> - </tp:member> - <tp:member type="x" tp:type="Unix_Timestamp64" name="Timestamp"> - <tp:docstring> - A unix timestamp indicating when the subject was last modified. - </tp:docstring> - </tp:member> - </tp:struct> - - <property name="Subject" tp:name-for-bindings="Subject" - type="(ssx)" tp:type="Room_Subject" access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The subject on the room such as the topic in an IRC channel, - or the room name in XMPP MUCs. In protocols which do not support - subjects (like MSN), this property should be ("", "", 0).</p> - - <tp:rationale>This property replaces the subject, subject-contact, and - subject-timestamp Telepathy properties of Text channels, as Telepathy - properties are soon to be deprecated completely.</tp:rationale> - - <p>This property may change during the lifetime of the channel and - MUST not be included in a channel request.</p> - </tp:docstring> - </property> - </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Room_Config.xml b/spec/Channel_Interface_Room_Config.xml new file mode 100644 index 000000000..2ae7f1fd8 --- /dev/null +++ b/spec/Channel_Interface_Room_Config.xml @@ -0,0 +1,248 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Room_Config" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2011 Collabora Ltd.</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.Channel.Interface.RoomConfig1"> + <tp:added version="0.24.0">version 1. This replaces the old-school + Telepathy properties on <tp:dbus-ref + namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>.</tp:added> + <tp:requires interface='org.freedesktop.Telepathy.Channel.Interface.Room2'/> + <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" + value="true"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Represents the configuration of a chatroom, some aspects of which may + be modifiable by the user, depending on their priviledges. This + corresponds to the room configuration on XMPP, and various channel mode + flags on IRC.</p> + + <p>The “topic” (on IRC) or “subject” (on XMPP) is not part of this + interface; it can be found on the <tp:dbus-ref + namespace='ofdT.Channel.Interface'>Subject2</tp:dbus-ref> + interface.</p> + </tp:docstring> + + <property name="Anonymous" tp:name-for-bindings="Anonymous" type="b" access="read"> + <tp:docstring> + <code>True</code> if people may join the channel without other members being made + aware of their identity. + </tp:docstring> + </property> + <property name="InviteOnly" tp:name-for-bindings="InviteOnly" type="b" access="read"> + <tp:docstring> + <code>True</code> if people may not join the channel until they have been invited. + </tp:docstring> + </property> + <property name="Limit" tp:name-for-bindings="Limit" type="u" access="read"> + <tp:docstring> + The limit to the number of members; or <tt>0</tt> if there is no limit. + </tp:docstring> + </property> + <property name="Moderated" tp:name-for-bindings="Moderated" type="b" access="read"> + <tp:docstring> + <code>True</code> if channel membership is not sufficient to allow participation. + </tp:docstring> + </property> + <property name="Title" tp:name-for-bindings="Title" type="s" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + A human-visible name for the channel, if it differs from <tp:dbus-ref + namespace='ofdT.Channel.Interface'>Room2.RoomName</tp:dbus-ref>; the + empty string, otherwise. + + <tp:rationale> + <p>On XMPP, this represents the <code>muc#roomconfig_roomname</code> + field of the <a + href='http://xmpp.org/extensions/xep-0045.html#registrar-formtype-owner'><code>muc#roomconfig</code></a> + form. So for <code>jdev@conference.jabber.org</code>, for example:</p> + + <ul> + <li><tp:dbus-ref + namespace='ofdT.Channel.Interface'>Room2.RoomName</tp:dbus-ref> + = <code>"jdev"</code>;</li> + <li><tp:dbus-ref + namespace='ofdT.Channel.Interface'>Room2.Server</tp:dbus-ref> + = <code>"conference.jabber.org"</code>;</li> + <li><tp:member-ref>Title</tp:member-ref> = <code>"General Jabber + development discussion"</code>.</li> + </ul> + + <p>XEP-0045 is awful.</p> + </tp:rationale> + </tp:docstring> + </property> + <property name="Description" tp:name-for-bindings="Description" type="s" access="read"> + <tp:docstring> + A human-readable description of the channel's overall purpose; if any. + </tp:docstring> + </property> + <property name="Persistent" tp:name-for-bindings="Persistent" type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <code>True</code> if the channel will remain in existence on the server after all + members have left it. + </tp:docstring> + </property> + <property name="Private" tp:name-for-bindings="Private" type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <code>True</code> if the channel is not visible to non-members. + </tp:docstring> + </property> + + <property name="PasswordProtected" type="b" access="read" + tp:name-for-bindings="Password_Protected"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <code>True</code> if contacts joining this channel must provide a + password to be granted entry. Note that this property does not + indicate that a password is required <em>right now</em>; see the + <tp:dbus-ref namespace='ofdT.Channel.Interface'>Password</tp:dbus-ref> + interface for the API used to provide a password while joining a room. + </tp:docstring> + </property> + + <property name="Password" tp:name-for-bindings="Password" type="s" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + If <tp:member-ref>PasswordProtected</tp:member-ref> is + <code>True</code>, the password required to enter the channel, if + known. If the password is unknown, or + <tp:member-ref>PasswordProtected</tp:member-ref> is + <code>False</code>, the empty string. + + <tp:rationale> + On XMPP—bless its cotton socks!—non-owners of a MUC cannot see its + current password, even if they just provided the password in order to + join the room… + </tp:rationale> + </tp:docstring> + </property> + + <property name="CanUpdateConfiguration" type="b" access="read" + tp:name-for-bindings="Can_Update_Configuration"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + If <code>True</code>, the user may call + <tp:member-ref>UpdateConfiguration</tp:member-ref> to change the values + of the properties listed in + <tp:member-ref>MutableProperties</tp:member-ref>. + </tp:docstring> + </property> + + <property name="MutableProperties" type="as" access="read" + tp:name-for-bindings="Mutable_Properties"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of (unqualified) property names on this interface which may + be modified using <tp:member-ref>UpdateConfiguration</tp:member-ref> + (if <tp:member-ref>CanUpdateConfiguration</tp:member-ref> is + <code>True</code>). Properties not listed here cannot be + modified.</p> + + <p>For example, IRC does not have the concept of joining a room without + other participants knowing your true identity; so on IRC the + <tp:member-ref>Anonymous</tp:member-ref> property will always be + <code>False</code>, and + <tp:member-ref>MutableProperties</tp:member-ref> will not include + <code>"Anonymous"</code>.</p> + </tp:docstring> + </property> + + <property name="ConfigurationRetrieved" type="b" access="read" + tp:name-for-bindings="Configuration_Retrieved"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p><code>True</code> once the initial room configuration has been + retrieved, or <code>False</code> otherwise. On some services, this + may take some time after you've joined a room to fetch the + configuration. Once this property changes to <code>True</code>, the + other properties on this interface can be assumed to be accurate; + this property MUST not change to <code>False</code> after it becomes + <code>True</code>.</p> + + <tp:rationale> + <p>An application's “configure this room” dialog might choose to + display a spinner while this property is <code>False</code>, rather + than allowing the user to edit probably-inaccurate + configuration.</p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="UpdateConfiguration" tp:name-for-bindings="Update_Configuration"> + <arg direction="in" name="Properties" type="a{sv}"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + The new values of one or more properties on this interface, which + must be listed in + <tp:member-ref>MutableProperties</tp:member-ref>. For + instance, to set up a channel for discussing top-secret corporate + merge plans, this parameter might be: + </p> + + <blockquote> + <pre>{ + 'Private': True, + 'InviteOnly': True, + 'Description': "The first rule of #inteltakeover is: do not talk about #inteltakeover", +}</pre></blockquote> + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <tp:member-ref>CanUpdateConfiguration</tp:member-ref> is + <code>True</code>, modifies the current values of one or more + room properties. This method SHOULD NOT return until the change has + been accepted or declined by the server.</p> + + <p>Note that the server may ostensibly accept the changes (thus + allowing this method to return success) but signal different values; + for example, the server might truncate + <tp:member-ref>Title</tp:member-ref> to some maximum length. Callers + SHOULD continue to listen for the <code>PropertiesChanged</code> + signal, and trust the values it signals over those provided to this + method.</p> + </tp:docstring> + + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The user is not allowed to reconfigure this room. + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + One or more of the specified properties is unknown, or ill-typed. + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + One or more of the specified properties cannot be modified on this + protocol. + </tp:docstring> + </tp:error> + + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The room's current configuration has not yet been retrieved, so we + cannot update it just yet. The application might like to try again + once the <tp:member-ref>ConfigurationRetrieved</tp:member-ref> + property becomes <code>True</code>. + </tp:docstring> + </tp:error> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Subject.xml b/spec/Channel_Interface_Subject.xml new file mode 100644 index 000000000..1ea7d55b9 --- /dev/null +++ b/spec/Channel_Interface_Subject.xml @@ -0,0 +1,127 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Subject" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2010–2011 Collabora Ltd.</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.Channel.Interface.Subject2"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:added version="0.24.0">(version 2)</tp:added> + <annotation name="org.freedesktop.DBus.Property.EmitsChangedSignal" + value="true"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface channels can implement to support subjects. Most + of the time this will be implemented by channels implementing + the <tp:dbus-ref + namespace="ofdT.Channel.Interface">Room2</tp:dbus-ref> + interface, but some protocols support subjects in 1-to-1 chats + (such as Skype). Note that this interface is not restricted to + Text channels, and can also be used on Call channels.</p> + </tp:docstring> + + <method name="SetSubject" tp:name-for-bindings="Set_Subject"> + <arg direction="in" type="s" name="Subject"> + <tp:docstring>The new subject.</tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Set the room's subject. Clients SHOULD look at the subject + flags before calling this method as the user might not have + permission to set the subject.</p> + + <p>A successful return of this method indicates a successful + change in subject, but clients should still listen for changes + to the <tp:member-ref>Subject</tp:member-ref> property for + further changes by other users or the server.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <property name="Subject" tp:name-for-bindings="Subject" + type="s" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The human-readable subject on the channel such as the topic + in an IRC channel, or the room name in XMPP MUCs.</p> + + <tp:rationale>This property replaces the subject Telepathy + property of Text channels, as Telepathy properties are soon to + be deprecated completely.</tp:rationale> + + <p>This property may change during the lifetime of the channel and + MUST not be included in a channel request.</p> + </tp:docstring> + </property> + + <property name="Actor" tp:name-for-bindings="Actor" + type="s" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The normalized contact ID representing who last modified + the subject, or the empty string if it is not known.</p> + + <tp:rationale>This property replaces the subject-contact + Telepathy property of Text channels, as Telepathy properties + are soon to be deprecated completely.</tp:rationale> + </tp:docstring> + </property> + + <property name="ActorHandle" tp:name-for-bindings="Actor_Handle" + type="u" tp:type="Contact_Handle" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The handle corresponding to <tp:member-ref>Actor</tp:member-ref>.</p> + </tp:docstring> + </property> + + <property name="Timestamp" tp:name-for-bindings="Timestamp" + type="x" tp:type="Unix_Timestamp64" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A unix timestamp indicating when the subject was last + modified.</p> + + <tp:rationale>This property replaces the subject-timestamp + Telepathy property of Text channels, as Telepathy properties + are soon to be deprecated completely.</tp:rationale> + </tp:docstring> + </property> + + <property name="CanSet" tp:name-for-bindings="Can_Set" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>TRUE if the <tp:member-ref>Subject</tp:member-ref> property + can be set by the user by calling + <tp:member-ref>SetSubject</tp:member-ref>, otherwise + FALSE.</p> + + <p>If implementations are unsure of what this value should be + it SHOULD still be set to what it believes the value + is. As a result, clients should be aware that + <tp:member-ref>SetSubject</tp:member-ref> can still fail + even with this property set to TRUE.</p> + + <tp:rationale>In XMPP it is impossible to know whether an + occupant can set the subject as XMPP server implementations + are wildly inconsistent.</tp:rationale> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml index e1474c5ac..585c7000c 100644 --- a/spec/Channel_Type_Call.xml +++ b/spec/Channel_Type_Call.xml @@ -17,11 +17,13 @@ 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. </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT" + <interface name="org.freedesktop.Telepathy.Channel.Type.Call1" tp:causes-havoc="experimental"> <tp:added version="0.19.0">(draft 1)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires + interface="org.freedesktop.Telepathy.Call1.Interface.Mute"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A channel type for making audio and video calls. Call channels supersede the old <tp:dbus-ref @@ -52,7 +54,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <h4>Contents</h4> - <p><tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> + <p><tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref> objects represent the actual media that forms the Call (for example an audio content and a video content). Calls always have one or more Content objects associated with them. As a @@ -62,10 +64,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. as the Requestable Channel Classes will document.</p> <p><tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects have + namespace="ofdT.Call1">Content</tp:dbus-ref> objects have one or more stream associated with them. More information on these streams and how to maniuplate them can be found on the - <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> + <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref> interface page.</p> <h4>Outgoing calls</h4> @@ -77,7 +79,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <pre> <tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({ ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, + namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>, ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', ...<tp:member-ref>InitialAudio</tp:member-ref>: True, @@ -100,26 +102,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>After a new Call channel is requested, the <tp:member-ref>CallState</tp:member-ref> property will be - <tp:type>Call_State</tp:type>_Pending_Initiator. As the local + <tp:value-ref type="Call_State">Pending_Initiator</tp:value-ref>. As the local user is the initiator, the call must be accepted by the handler by calling the <tp:member-ref>Accept</tp:member-ref> method. At this point, <tp:member-ref>CallState</tp:member-ref> changes - to <tp:type>Call_State</tp:type>_Pending_Receiver which signifies - that the call is ringing, waiting for the remote contact to - accept the call. All changes to - <tp:member-ref>CallState</tp:member-ref> property are signalled - using the <tp:member-ref>CallStateChanged</tp:member-ref> - signal.</p> + to <tp:value-ref type="Call_State">Initialising</tp:value-ref>, which signifies + that the call is waiting for the network to do + something. When the CM has information indicating that the remote contact has been + notified about the call (or immediately if the network is known not to convey such + information) it should also change to + <tp:value-ref type="Call_State">Ringing</tp:value-ref>. All changes to + the <tp:member-ref>CallState</tp:member-ref> property are signalled using + the <tp:member-ref>CallStateChanged</tp:member-ref> signal.</p> <p>When the call is accepted by the remote contact, the <tp:member-ref>CallStateChanged</tp:member-ref> signal fires again to show that <tp:member-ref>CallState</tp:member-ref> = - <tp:type>Call_State</tp:type>_Accepted.</p> + <tp:value-ref type="Call_State">Accepted</tp:value-ref>.</p> <p>At this point <a href="http://telepathy.freedesktop.org/doc/telepathy-farstream/">telepathy-farstream</a> will signal that a pad is available for the handler to show - in the user interface.</p> + in the user interface. Once media is correctly flowing in both + directions, the state will change to + <tp:value-ref type="Call_State">Active</tp:value-ref>, to inform the user that they + have a correctly working call there is nothing amiss.</p> <h5>Missed calls</h5> @@ -129,10 +136,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. not do this and rely on the call initiator terminating the call. A missed call is shown in a Call channel by the <tp:member-ref>CallState</tp:member-ref> property changing to - <tp:type>Call_State</tp:type>_Ended, and the + <tp:value-ref type="Call_State">Ended</tp:value-ref>, and the <tp:member-ref>CallStateReason</tp:member-ref> property changing to (remote contact, - <tp:type>Call_State_Change_Reason</tp:type>_No_Answer, "").</p> + <tp:value-ref type="Call_State_Change_Reason">No_Answer</tp:value-ref>, "").</p> <h5>Rejected calls</h5> @@ -140,10 +147,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. talking to the local user, he or she can reject his or her incoming call. This will be shown in the Call channel by <tp:member-ref>CallState</tp:member-ref> changing to - <tp:type>Call_State</tp:type>_Ended and the + <tp:value-ref type="Call_State">Ended</tp:value-ref> and the <tp:member-ref>CallStateReason</tp:member-ref> property changing to (remote contact, - <tp:type>Call_State</tp:type>_Change_Reason_User_Requested, + <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>, "org.freedesktop.Telepathy.Error.Rejected").</p> <h4>Incoming calls</h4> @@ -159,7 +166,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. /org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel, { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, + namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>, ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>: 42, @@ -186,24 +193,26 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. The new channel should also be given to telepathy-farstream to work out how the two participants will connect together. telepathy-farstream will call the appropriate methods on the call's - <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>s + <tp:dbus-ref namespace="ofdT.Call1">Content</tp:dbus-ref>s to negotiate codecs and transports.</p> <p>To pick up the call, the handler should call <tp:member-ref>Accept</tp:member-ref>. The <tp:member-ref>CallState</tp:member-ref> property changes to - <tp:type>Call_State</tp:type>_Accepted and once media is + <tp:value-ref type="Call_State">Accepted</tp:value-ref> and once media is being transferred, telepathy-farstream will notify the handler of a new pad to be shown to the local user in the - UI</p> + UI. Once media is correctly flowing in both directions, the state will + change to <tp:value-ref type="Call_State">Active</tp:value-ref>, to inform the user + that they have a correctly working call there is nothing amiss.</p> <p>To reject the call, the handler should call the <tp:member-ref>Hangup</tp:member-ref> method. The <tp:member-ref>CallState</tp:member-ref> property will change to - <tp:type>Call_State</tp:type>_Ended and the + <tp:value-ref type="Call_State">Ended</tp:value-ref> and the <tp:member-ref>CallStateReason</tp:member-ref> property will change to (self handle, - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>, "org.freedesktop.Telepathy.Error.Rejected").</p> <h4>Ongoing calls</h4> @@ -221,7 +230,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <blockquote> <pre><tp:member-ref>AddContent</tp:member-ref>("video", - <tp:type>Media_Stream_Type</tp:type>_Video)</pre> + <tp:value-ref type="Media_Stream_Type">Video</tp:value-ref>)</pre> </blockquote> <p>Assuming no errors, the new video content will be added to @@ -232,142 +241,42 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>A similar method is used for removing contents from a call, except that the <tp:dbus-ref - namespace="ofdT.Call.Content.DRAFT">Remove</tp:dbus-ref> method + namespace="ofdT.Call1.Content">Remove</tp:dbus-ref> method is on the <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> object.</p> + namespace="ofdT.Call1">Content</tp:dbus-ref> object.</p> <h5>Ending the call</h5> <p>To end the call, the handler should call the <tp:member-ref>Hangup</tp:member-ref> method. The <tp:member-ref>CallState</tp:member-ref> property will change to - <tp:type>Call_State</tp:type>_Ended and + <tp:value-ref type="Call_State">Ended</tp:value-ref> and <tp:member-ref>CallStateReason</tp:member-ref> will change to (self handle, - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>, "org.freedesktop.Telepathy.Error.Cancelled").</p> <p>If the other participant hangs up first then the <tp:member-ref>CallState</tp:member-ref> property will change to - <tp:type>Call_State</tp:type>_Ended and + <tp:value-ref type="Call_State">Ended</tp:value-ref> and <tp:member-ref>CallStateReason</tp:member-ref> will change to (remote contact, - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>, "org.freedesktop.Telepathy.Error.Terminated").</p> <h4>Multi-party calls</h4> - [TODO] - - <h4>Call states</h4> - - <p>There are many combinations of the - <tp:member-ref>CallState</tp:member-ref> and - <tp:member-ref>CallStateReason</tp:member-ref> properties which - mean different things. Here is a table to try to make these - meanings clearer:</p> - - <table> - <tr> - <th rowspan="2"><tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref></th> - <th rowspan="2"><tp:member-ref>CallState</tp:member-ref></th> - <th colspan="3"><tp:member-ref>CallStateReason</tp:member-ref></th> - <th rowspan="2">Meaning</th> - </tr> - <tr> - <th>Actor</th> - <th>Reason</th> - <th>DBus_Reason</th> - </tr> - <!-- Pending_Initiator --> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Pending_Initiator</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The outgoing call channel is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref>.</td> - </tr> - <!-- Pending_Receiver --> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Pending_Receiver</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The outgoing call is waiting for the remote contact to pick up the call.</td> - </tr> - <tr> - <td>False</td> - <td><tp:type>Call_State</tp:type>_Pending_Receiver</td> - <td>0</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_Unknown</td> - <td>""</td> - <td>The incoming call is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref> on the call.</td> - </tr> - <!-- Accepted --> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Accepted</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The remote contact accepted the outgoing call.</td> - </tr> - <tr> - <td>False</td> - <td><tp:type>Call_State</tp:type>_Accepted</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td>""</td> - <td>The local user accepted the incoming call.</td> - </tr> - <!-- Ended --> - <tr> - <td>True or False</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Self handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td><tp:error-ref>Cancelled</tp:error-ref></td> - <td>The local user hung up the incoming or outgoing call.</td> - </tr> - <tr> - <td>True or False</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td><tp:error-ref>Terminated</tp:error-ref></td> - <td>The remote contact hung up the incoming or outgoing call.</td> - </tr> - <tr> - <td>True</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_No_Answer</td> - <td>""</td> - <td>The outgoing call was not picked up and the call ended.</td> - </tr> - <tr> - <td>False</td> - <td><tp:type>Call_State</tp:type>_Ended</td> - <td>Remote contact handle</td> - <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td> - <td><tp:error-ref>PickedUpElsewhere</tp:error-ref></td> - <td>The incoming call was ended because it was picked up elsewhere.</td> - </tr> - </table> - <h4>Requestable channel classes</h4> <p>The <tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref> for <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels + namespace="ofdT.Channel.Type">Call1</tp:dbus-ref> channels can be:</p> <blockquote> <pre> -[( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, +[( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>, ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, ...<tp:member-ref>InitialVideo</tp:member-ref>: True }, @@ -376,7 +285,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. ...<tp:member-ref>InitialAudioName</tp:member-ref> ] ), -( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>, +( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call1</tp:dbus-ref>, ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact, ...<tp:member-ref>InitialAudio</tp:member-ref>: True }, @@ -393,13 +302,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. class, and vice versa for CMs without audio support.</p> <p>Handlers should not close <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels + namespace="ofdT.Channel.Type">Call1</tp:dbus-ref> channels without first calling <tp:member-ref>Hangup</tp:member-ref> on the channel. If a Call handler crashes, the <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will call <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> on the channel which SHOULD also imply a call to - <tp:member-ref>Hangup</tp:member-ref>(<tp:type>Call_State_Change_Reason</tp:type>_User_Requested, + <tp:member-ref>Hangup</tp:member-ref>(<tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref>, "org.freedesktop.Telepathy.Error.Terminated", "") before actually closing the channel.</p> @@ -415,13 +324,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> property is False, and the <tp:member-ref>CallState</tp:member-ref> is - <tp:type>Call_State</tp:type>_Pending_Receiver (an incoming - call waiting on the local user to pick up). While this is - the case, this method SHOULD change the - <tp:member-ref>CallFlags</tp:member-ref> to include - <tp:type>Call_Flags</tp:type>_Locally_Ringing, and notify the + <tp:value-ref type="Call_State">Ringing</tp:value-ref> (an incoming + call is ready and waiting for the user to be notified). Calling this method + SHOULD set <tp:member-ref>CallFlags</tp:member-ref>' bit + <tp:value-ref type="Call_Flags">Locally_Ringing</tp:value-ref>, and notify the remote contact that the local user has been alerted (if the - protocol implements this); repeated calls to this method + protocol supports this); repeated calls to this method SHOULD succeed, but have no further effect.</p> <p>In all other states, this method SHOULD fail with the error @@ -438,7 +346,47 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> The call is no longer in state - <tp:type>Call_State</tp:type>_Pending_Receiver. + <tp:value-ref type="Call_State">Ringing</tp:value-ref>. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="SetQueued" tp:name-for-bindings="Set_Queued"> + <tp:changed version="0.21.2">renamed from Ringing</tp:changed> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Notifies the CM that the local user is already in a call, so this + call has been put in a call-waiting style queue.</p> + + <p>This method is only useful if the + channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> + property is False, and + the <tp:member-ref>CallState</tp:member-ref> is + <tp:value-ref type="Call_State">Initialising</tp:value-ref> or + <tp:value-ref type="Call_State">Ringing</tp:value-ref>. Calling this method + SHOULD set <tp:member-ref>CallFlags</tp:member-ref>' bit + <tp:value-ref type="Call_Flags">Locally_Queued</tp:value-ref>, and notify the + remote contact that the call is in a queue (if the + protocol supports this); repeated calls to this method + SHOULD succeed, but have no further effect.</p> + + <p>Locally_Queued is a little like Locally_Held, but applies to calls that have not + been Accepted (the Locally_Queued flag should be unset by the CM when Accept + is called). It should also be set in response to the state of the + world, rather than in response to user action.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The call was <tp:dbus-ref namespace="ofdT.Channel" + >Requested</tp:dbus-ref>, so ringing does not make sense. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The call is no longer in state + <tp:value-ref type="Call_State">Initialising</tp:value-ref> or _Ringing. </tp:docstring> </tp:error> </tp:possible-errors> @@ -447,16 +395,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <method name="Accept" tp:name-for-bindings="Accept"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>For incoming calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver, accept the - incoming call; this changes the - <tp:member-ref>CallState</tp:member-ref> to - <tp:type>Call_State</tp:type>_Accepted.</p> + <tp:value-ref type="Call_State">Ringing</tp:value-ref>, accept the incoming call. + This changes the <tp:member-ref>CallState</tp:member-ref> to + <tp:value-ref type="Call_State">Accepted</tp:value-ref>.</p> <p>For outgoing calls in state - <tp:type>Call_State</tp:type>_Pending_Initiator, actually + <tp:value-ref type="Call_State">Pending_Initiator</tp:value-ref>, actually call the remote contact; this changes the <tp:member-ref>CallState</tp:member-ref> to - <tp:type>Call_State</tp:type>_Pending_Receiver.</p> + <tp:value-ref type="Call_State">Initialising</tp:value-ref>.</p> <p>Otherwise, this method SHOULD fail with the error NotAvailable.</p> @@ -464,15 +411,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. client (user interface) is handling the channel.</p> <p>When this method is called, for each <tp:dbus-ref - namespace="ofdT.Call" >Content.DRAFT</tp:dbus-ref> whose - <tp:dbus-ref namespace="ofdT.Call.Content.DRAFT" + namespace="ofdT.Call1" >Content</tp:dbus-ref> whose + <tp:dbus-ref namespace="ofdT.Call1.Content" >Disposition</tp:dbus-ref> is - <tp:type>Call_Content_Disposition</tp:type>_Initial, any + <tp:value-ref type="Call_Content_Disposition">Initial</tp:value-ref>, any streams where the <tp:dbus-ref - namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref> - is <tp:type>Sending_State</tp:type>_Pending_Send will be - moved to <tp:type>Sending_State</tp:type>_Sending as if - <tp:dbus-ref namespace="ofdT.Call.Stream.DRAFT" + namespace="ofdT.Call1.Stream">LocalSendingState</tp:dbus-ref> + is <tp:value-ref type="Sending_State">Pending_Send</tp:value-ref> will be + moved to <tp:value-ref type="Sending_State">Sending</tp:value-ref> as if + <tp:dbus-ref namespace="ofdT.Call1.Stream" >SetSending</tp:dbus-ref>(True) had been called.</p> </tp:docstring> @@ -531,8 +478,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <method name="AddContent" tp:name-for-bindings="Add_Content"> <tp:docstring> Request that a new <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> of type - Content_Type is added to the Call. Handlers should check the + namespace="ofdT.Call1">Content</tp:dbus-ref> of type + Content_Type is added to the Call1. Handlers should check the value of the <tp:member-ref>MutableContents</tp:member-ref> property before trying to add another content as it might not be allowed. @@ -569,7 +516,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> Path to the newly-created <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Call.Content.DRAFT</tp:dbus-ref> object. + >Call1.Content</tp:dbus-ref> object. </tp:docstring> </arg> @@ -585,6 +532,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. CM. </tp:docstring> </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Media.UnsupportedType"> + <tp:docstring> + The media stream type requested is not supported by either the + local or remote side. + </tp:docstring> + </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"> <tp:docstring> The content type requested cannot be added to this @@ -600,26 +553,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <signal name="ContentAdded" tp:name-for-bindings="Content_Added"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> is added to the call.</p> + <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call1" + >Content</tp:dbus-ref> is added to the call.</p> </tp:docstring> <arg name="Content" type="o"> <tp:docstring> - Path to the newly-created <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> object. + Path to the newly-created <tp:dbus-ref namespace="ofdT.Call1" + >Content</tp:dbus-ref> object. </tp:docstring> </arg> </signal> <signal name="ContentRemoved" tp:name-for-bindings="Content_Removed"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> is removed from the call.</p> + <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call1" + >Content</tp:dbus-ref> is removed from the call.</p> </tp:docstring> <arg name="Content" type="o"> <tp:docstring> - The <tp:dbus-ref namespace="ofdT.Call" - >Content.DRAFT</tp:dbus-ref> which was removed. + The <tp:dbus-ref namespace="ofdT.Call1" + >Content</tp:dbus-ref> which was removed. + </tp:docstring> + </arg> + <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason"> + <tp:docstring> + Why the content was removed. </tp:docstring> </arg> </signal> @@ -628,7 +586,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. tp:name-for-bindings="Contents"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The list of <tp:dbus-ref - namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects that + namespace="ofdT.Call1">Content</tp:dbus-ref> objects that are part of this call. Change notification is via the <tp:member-ref>ContentAdded</tp:member-ref> and <tp:member-ref>ContentRemoved</tp:member-ref> signals. @@ -643,17 +601,33 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>The allowed transitions are:</p> <ul> - <li>Pending_Initiator → Pending_Receiver (for outgoing calls, + <li>Pending_Initiator → Initialising (for outgoing calls, when <tp:member-ref>Accept</tp:member-ref> is called)</li> - <li>Pending_Receiver → Accepted (for incoming calls, when - <tp:member-ref>Accept</tp:member-ref> is called; for outgoing - calls to a contact, when the remote contact accepts the call; - for joining a conference call, when the local user successfully - joins the conference)</li> - <li>Accepted → Pending_Receiver (when transferred to another - contact)</li> - <li>any state → Ended (when the call is terminated normally, or - when an error occurs)</li> + <li>Initialising → Ringing (for outgoing calls, when + the remote client indicates that the user has been notified about + the call. If the network is known not to provide feedback about whether + the remote side is ringing, then the call should immediately be + set to Ringing.</li> + <li>Initialising → Ringing (for incoming calls, when e.g. the + implementation has been initialised far enough that it is sensible + to notify the user about the call (to reduce the probability that + the user will pick up the call and have it immediately fail). + The UI should then alert the user about the call, and call + <tp:member-ref>SetRinging</tp:member-ref>)</li> + <li>Ringing → Accepted (for outgoing calls to a contact, + when the remote contact accepts the call; for incoming calls, when + <tp:member-ref>Accept</tp:member-ref> is called.)</li> + <li>Accepted → Active (when the local user successfully + joins the call/conference, and media is known to be flowing + successfully; also, when temporary connection problems are + resolved (See below)). If the network is known not to provide + feedback about when the call is properly connected, the call + should immediately be set to Active.</li> + <li>Active → Accepted (when there are temporary connection problems + that the CM is aware of and able to recover from)</li> + <li>any state → Ended (when the call is terminated + normally, or when an error occurs that the CM is unable to recover + from)</li> </ul> <p>Clients MAY consider unknown values from this enum to be an @@ -661,7 +635,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. specification is declared to be stable.</p> </tp:docstring> - <tp:enumvalue suffix="Unknown" value = "0"> + <tp:enumvalue suffix="Unknown" value="0"> <tp:docstring> The call state is not known. This call state MUST NOT appear as a value of the <tp:member-ref>CallState</tp:member-ref> property, but @@ -669,7 +643,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. unknown. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Pending_Initiator" value = "1"> + <tp:enumvalue suffix="Pending_Initiator" value="1"> <tp:docstring> The initiator of the call hasn't accepted the call yet. This state only makes sense for outgoing calls, where it means that the local @@ -678,17 +652,48 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. called. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Pending_Receiver" value = "2"> + <tp:enumvalue suffix="Initialising" value="2"> <tp:docstring> - The receiver (the contact being called) hasn't accepted the call yet. + Progress has been made in placing the call, but the + contact has not been made aware of the call yet. This corresponds to SIP's + status code 183 Session Progress, and should be used for the period + where the CM is waiting for the streaming implementation to + initialise (before sending the initial INVITE or equivalent) and when the + outgoing call has reached a gateway or ICE negotiation is pending. + UIs should not produce a dialtone or start ringing if the call is in + this state. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Accepted" value = "3"> + <tp:enumvalue suffix="Ringing" value="3"> <tp:docstring> - The contact being called has accepted the call. + In the outgoing case: at least one called user has been alerted + about the call (a SIP 180 (Ringing) packet or equivalent has been + received) but none have answered, so the call cannot go to Accepted + (use <tp:value-ref type="Call_Member_Flags">Ringing</tp:value-ref> to determine which + members have been informed and which haven't, if you care). UIs + SHOULD produce a dialtone for outgoing calls in this state. + + In the incoming case, the local user should be informed of the call + as soon as the call reaches this state (and + <tp:member-ref>SetRinging</tp:member-ref> should be called + to inform the CM that this has happened, so that it can relay this + fact to the caller using a SIP 180 (Ringing) packet or equivalent). </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Ended" value = "4"> + <tp:enumvalue suffix="Accepted" value="4"> + <tp:docstring> + The contact being called has accepted the call, but the call is not + in the Active state (The most common reason for this is that the + streaming implementation hasn't connected yet). + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Active" value="5"> + <tp:docstring> + The contact being called has accepted the call, and discourse between + at least two parties should now be possible. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Ended" value="6"> <tp:docstring> The call has ended, either via normal termination or an error. </tp:docstring> @@ -697,43 +702,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:flags name="Call_Flags" value-prefix="Call_Flag" type="u"> <tp:docstring> - A set of flags representing the status of the call as a whole, - providing more specific information than the - <tp:member-ref>CallState</tp:member-ref>. Many of these flags only make - sense in a particular state. + A set of flags representing additional information than is available + in <tp:member-ref>CallState</tp:member-ref>. Many of these flags only make + sense in a particular (or may explain why a call is in a specific + state). </tp:docstring> - - <tp:flag suffix="Locally_Ringing" value="1"> - <tp:docstring> - The local contact has been alerted about the call but has not - responded; if possible, the remote contact(s) have been informed of - this fact. This flag only makes sense on incoming calls in - state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD - be set when <tp:member-ref>SetRinging</tp:member-ref> is - called successfully, and unset when the state changes. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Queued" value="2"> - <tp:docstring> - The contact is temporarily unavailable, and the call has been placed - in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony). - This flag only makes sense on outgoing 1-1 calls in - state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD be - set or unset according to informational messages from other - contacts. - </tp:docstring> - </tp:flag> - - <tp:flag suffix="Locally_Held" value="4"> + <tp:flag suffix="Locally_Held" value="1"> <tp:docstring> The call has been put on hold by the local user, e.g. using the <tp:dbus-ref namespace="ofdT.Channel.Interface" >Hold</tp:dbus-ref> interface. This flag SHOULD only be set if there is at least one Content, and all Contents are - locally held; it makes sense on calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver - or <tp:type>Call_State</tp:type>_Accepted. + locally held. <tp:rationale> Otherwise, in transient situations where some but not all contents @@ -741,32 +721,61 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. is on hold, which could lead to the user saying something they'll regret, while under the impression that the other contacts can't hear them! + + This flag exists as a simplified proxy for <tp:dbus-ref + namespace="ofdT.Channel.Interface.Hold" + >HoldStateChanged</tp:dbus-ref>, + to reduce the number of signals that need to be + listened to by a simple UI. </tp:rationale> </tp:docstring> </tp:flag> - <tp:flag suffix="Forwarded" value="8"> + <tp:flag suffix="Locally_Muted" value="2"> <tp:docstring> - The initiator of the call originally called a contact other than the - current recipient of the call, but the call was then forwarded or - diverted. This flag only makes sense on outgoing calls, in state - <tp:type>Call_State</tp:type>_Pending_Receiver or - <tp:type>Call_State</tp:type>_Accepted. It SHOULD be set or unset - according to informational messages from other contacts. + The call has been muted by the local user, e.g. using the + <tp:dbus-ref namespace="ofdT.Call1.Interface" + >Mute</tp:dbus-ref> interface. This flag SHOULD only + be set if there is at least one Content, and all Contents + are locally muted (for the same reason as Locally_Held). + + <tp:rationale> + This flag exists to provide a simplified verson of <tp:dbus-ref + namespace="ofdT.Call1.Interface.Mute" + >MuteStateChanged</tp:dbus-ref>, + to reduce the number of signals that need to be + listened to by a simple UI. + </tp:rationale> </tp:docstring> </tp:flag> - <tp:flag suffix="In_Progress" value="16"> + <tp:flag suffix="Locally_Ringing" value="4"> <tp:docstring> - Progress has been made in placing the outgoing call, but the - contact may not have been made aware of the call yet - (so the Ringing state is not appropriate). This corresponds to SIP's - status code 183 Session Progress, and could be used when the - outgoing call has reached a gateway, for instance. - This flag only makes sense on outgoing calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver, and SHOULD be set - or unset according to informational messages from servers, gateways - and other infrastructure. + This flag exists for observability of the + <tp:member-ref>SetRinging</tp:member-ref> method (e.g. so that + loggers can tell whether the call got as far as alerting the user, + or whether something went wrong before then). It should be set when + the SetRinging is called, and unset when the call leaves + <tp:value-ref type="Call_State">Ringing</tp:value-ref>. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Locally_Queued" value="8"> + <tp:docstring> + This flag exists for observability of the + <tp:member-ref>SetQueued</tp:member-ref> method. It should be set + when the SetQueued is called, and unset when the call leaves + <tp:value-ref type="Call_State">Ringing</tp:value-ref>. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Forwarded" value="16"> + <tp:docstring> + The initiator of the call originally called a contact other than the + current recipient of the call, but the call was then forwarded or + diverted. This flag only makes sense on outgoing calls. It SHOULD be + set or unset according to informational messages from other + contacts. </tp:docstring> </tp:flag> @@ -787,17 +796,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </tp:flag> - <tp:flag suffix="Muted" value="64"> - <tp:docstring> - The call has been muted by the local user, e.g. using the - <tp:dbus-ref namespace="ofdT.Call.Content.Interface" - >Mute.DRAFT</tp:dbus-ref> interface. This flag SHOULD only - be set if there is at least one Content, and all Contents - are locally muted; it makes sense on calls in state - <tp:type>Call_State</tp:type>_Pending_Receiver or - <tp:type>Call_State</tp:type>_Accepted. - </tp:docstring> - </tp:flag> </tp:flags> <property name="CallStateDetails" @@ -815,7 +813,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <dd>An optional human-readable message sent when the call was ended, corresponding to the Message argument to the <tp:member-ref>Hangup</tp:member-ref> method. This is only - applicable when the call state is <tp:type>Call_State</tp:type>_Ended. + applicable when the call state is <tp:value-ref type="Call_State">Ended</tp:value-ref>. <tp:rationale> XMPP Jingle can send such messages. </tp:rationale> @@ -824,7 +822,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <dt>queue-message - s</dt> <dd>An optional human-readable message sent when the local contact is being held in a queue. This is only applicable when - <tp:type>Call_Flags</tp:type>_Queued is in the call flags. + <tp:value-ref type="Call_Flags">Locally_Queued</tp:value-ref> is in the call flags. <tp:rationale> SIP 182 notifications can have human-readable messages attached. </tp:rationale> @@ -835,7 +833,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:member-ref>CallStateReason</tp:member-ref>. This will not normally be localized or suitable for display to users, and is only applicable when the call state is - <tp:type>Call_State</tp:type>_Ended.</dd> + <tp:value-ref type="Call_State">Ended</tp:value-ref>.</dd> <dt>balance-required - i</dt> <dd>Optionally included when a call cannot be connected because @@ -898,7 +896,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="User_Requested" value="1"> + <tp:enumvalue suffix="Progress_Made" value="1"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Situation normal. Progress has been made in the setup/teardown of + the call (and it didn't require any user interaction). + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="User_Requested" value="2"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The change was requested by the contact indicated by the Actor member of a <tp:type>Call_State_Reason</tp:type> struct.</p> @@ -913,7 +918,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Forwarded" value="2"> + <tp:enumvalue suffix="Forwarded" value="3"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The call was forwarded. If known, the handle of the contact the call was forwarded to will be indicated by the Actor member @@ -921,15 +926,113 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="No_Answer" value="3"> + <tp:enumvalue suffix="Rejected" value="4"> <tp:added version="0.21.2"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The <tp:member-ref>CallState</tp:member-ref> changed from - <tp:type>Call_State</tp:type>_Pending_Receiver to - <tp:type>Call_State</tp:type>_Ended because the initiator + <tp:value-ref type="Call_State">Ringing</tp:value-ref> or + <tp:value-ref type="Call_State">Ended</tp:value-ref> (or a content's direction + changed) because it was rejected by the remote user.</p> + <p>Corresponds to <tp:error-ref>Rejected</tp:error-ref></p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="No_Answer" value="5"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The <tp:member-ref>CallState</tp:member-ref> changed from + <tp:value-ref type="Call_State">Ringing</tp:value-ref> or + <tp:value-ref type="Call_State">Ended</tp:value-ref> because the initiator ended the call before the receiver accepted it. With an incoming call this state change reason signifies a missed - call.</p> + call, or one that was picked up elsewhere before it was + picked up here.</p> + <p>Corresponds to <tp:error-ref>NoAnswer</tp:error-ref> or + <tp:error-ref>PickedUpElsewhere</tp:error-ref></p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Invalid_Contact" value="6"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The <tp:member-ref>CallState</tp:member-ref> changed because one + of the addresses does not exist on the network.</p> + <p>Corresponds to <tp:error-ref>DoesNotExist</tp:error-ref></p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Permission_Denied" value="7"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The <tp:member-ref>CallState</tp:member-ref> changed because the + local user is not authorised.</p> + <p>Corresponds to <tp:error-ref>PermissionDenied</tp:error-ref> or + <tp:error-ref>InsufficientBalance</tp:error-ref> + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Busy" value="8"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The <tp:member-ref>CallState</tp:member-ref> changed from + <tp:value-ref type="Call_State">Ringing</tp:value-ref> + <tp:value-ref type="Call_State">Ended</tp:value-ref> because the receiver is busy + (e.g. is already engaged in another call, and has not placed the + initiator in a call-waiting queue).</p> + <p>Corresponds to <tp:error-ref>Busy</tp:error-ref></p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Internal_Error" value="9"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There has been an unexpected error in either the CM or some other + local component.</p> + <p>Corresponds to <tp:error-ref>Confused</tp:error-ref> or + <tp:error-ref>Media.StreamingError</tp:error-ref> + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Service_Error" value="10"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There has been an unexpected error in the server or some other + remote component.</p> + <p>Corresponds to + <tp:error-ref>ServiceConfused</tp:error-ref> + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Network_Error" value="11"> + <tp:added version="0.21.2"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>There has been a network error related to the CM or the + signalling part of the call (compare and contrast: + Streaming_Error).</p> + <p>Corresponds to + <tp:error-ref>NetworkError</tp:error-ref></p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Media_Error" value="12"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Some aspect of the content is unsupported so has to be + removed from the call.</p> + <p>Corresponds to <tp:error-ref>Media.UnsupportedType</tp:error-ref> + or <tp:error-ref>Media.CodecsIncompatible</tp:error-ref> + </p> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Connectivity_Error" value="13"> + <tp:docstring> + <p>It was not possible for the streaming implementation to connect + to any of the users participating in this call or content.</p> + <p>Corresponds to <tp:error-ref>ConnectionFailed</tp:error-ref> or + <tp:error-ref>ConnectionLost</tp:error-ref></p> </tp:docstring> </tp:enumvalue> </tp:enum> @@ -952,7 +1055,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring> The reason, chosen from a limited set of possibilities defined by the Telepathy specification. If - <tp:type>Call_State_Change_Reason</tp:type>_User_Requested then + <tp:value-ref type="Call_State_Change_Reason">User_Requested</tp:value-ref> then the Actor member will dictate whether it was the local user or a remote contact responsible. </tp:docstring> @@ -978,10 +1081,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:rationale> </tp:docstring> </tp:member> + + <tp:member type="s" name="Message"> + <tp:docstring> + An optional debug message, to expediate debugging the potentially + many processes involved in a call. This may be communicated across + the network in protocols that support doing so, but it is not + essential. + </tp:docstring> + </tp:member> </tp:struct> <property name="CallStateReason" tp:name-for-bindings="Call_State_Reason" - type="(uus)" access="read" tp:type="Call_State_Reason"> + type="(uuss)" access="read" tp:type="Call_State_Reason"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The reason for the last change to the <tp:member-ref>CallState</tp:member-ref> and/or @@ -1015,7 +1127,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </arg> - <arg name="Call_State_Reason" type="(uus)" tp:type="Call_State_Reason"> + <arg name="Call_State_Reason" type="(uuss)" tp:type="Call_State_Reason"> <tp:docstring> The new value of the <tp:member-ref>CallStateReason</tp:member-ref> property. @@ -1045,8 +1157,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>If this is False, the handler is responsible for doing the actual media streaming for at least some contents itself. Those contents - will have the <tp:dbus-ref namespace="ofdT.Call.Content.Interface" - >Media.DRAFT</tp:dbus-ref> interface, to communicate the necessary + will have the <tp:dbus-ref namespace="ofdT.Call1.Content.Interface" + >Media</tp:dbus-ref> interface, to communicate the necessary information to a streaming implementation. Connection managers SHOULD operate like this, if possible.</p> @@ -1077,7 +1189,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:rationale> </tp:docstring> - <tp:flag suffix="Ringing" value = "1"> + <tp:flag suffix="Ringing" value="1"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The remote contact's client has told us that the contact has been alerted about the call but has not responded.</p> @@ -1090,7 +1202,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </tp:flag> - <tp:flag suffix="Held" value = "2"> + <tp:flag suffix="Held" value="2"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The call member has put this call on hold.</p> @@ -1102,7 +1214,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </tp:flag> - <tp:flag suffix="Conference_Host" value="4"> + <tp:flag suffix="Muted" value="4"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The call member has muted their participation in this call. Note + that many protocols will not signal this flag, so clients should + not rely on it being set.</p> + + <tp:rationale> + <p>This is a flag per member, not a flag for the call as a whole, + because in conference calls, any member could mute their own + streams.</p> + </tp:rationale> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Conference_Host" value="8"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> This contact has merged this call into a conference. Note that GSM provides a notification when the remote party merges a call into a @@ -1146,6 +1272,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. from <tp:member-ref>CallMembers</tp:member-ref>. </tp:docstring> </arg> + <arg name="Reason" type="(uuss)" tp:type="Call_State_Reason"> + <tp:docstring> + A structured reason for the change. + </tp:docstring> + </arg> </signal> <property name="CallMembers" tp:name-for-bindings="Call_Members" @@ -1176,7 +1307,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If set on a requested channel, this indicates the transport that should be used for this call. Where not applicable, this property - is defined to be <tp:type>Stream_Transport_Type</tp:type>_Unknown, + is defined to be <tp:value-ref type="Stream_Transport_Type">Unknown</tp:value-ref>, in particular, on CMs with hardware streaming.</p> <tp:rationale> @@ -1195,7 +1326,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. the connection manager should immediately attempt to establish an audio stream to the remote contact, making it unnecessary for the client to call <tp:dbus-ref - namespace="ofdT.Channel.Type.Call.DRAFT">AddContent</tp:dbus-ref>.</p> + namespace="ofdT.Channel.Type.Call1">AddContent</tp:dbus-ref>.</p> <p>If this property, or InitialVideo, is passed to EnsureChannel (as opposed to CreateChannel), the connection manager SHOULD ignore @@ -1210,7 +1341,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>If True on an unrequested (incoming) channel, this indicates that the remote contact initially requested an audio stream; this does not imply that that audio stream is still active (as indicated by - <tp:dbus-ref namespace="ofdT.Channel.Type.Call.DRAFT" + <tp:dbus-ref namespace="ofdT.Channel.Type.Call1" >Contents</tp:dbus-ref>).</p> <p>The name of this new content can be decided by using the @@ -1331,7 +1462,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. must be requested at the start of the call if video is desired. User interfaces may use this pseudo-capability as a hint to display separate "Audio call" and "Video call" buttons, rather - than a single "Call" button with the option to add and remove + than a single "Call1" button with the option to add and remove video once the call has started for contacts without this flag. </p> </tp:rationale> @@ -1353,32 +1484,32 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <tp:hct name="gtalk-p2p"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_GTalk_P2P.</p> + namespace="ofdT.Call1.Stream.Interface.Media">Transport</tp:dbus-ref> + property is <tp:value-ref type="Stream_Transport_Type">GTalk_P2P</tp:value-ref>.</p> </tp:docstring> </tp:hct> <tp:hct name="ice"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_ICE.</p> + namespace="ofdT.Call1.Stream.Interface.Media">Transport</tp:dbus-ref> + property is <tp:value-ref type="Stream_Transport_Type">ICE</tp:value-ref>.</p> </tp:docstring> </tp:hct> <tp:hct name="wlm-2009"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_WLM_2009.</p> + namespace="ofdT.Call1.Stream.Interface.Media">Transport</tp:dbus-ref> + property is <tp:value-ref type="Stream_Transport_Type">WLM_2009</tp:value-ref>.</p> </tp:docstring> </tp:hct> <tp:hct name="shm"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The client can implement streaming for streams whose <tp:dbus-ref - namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref> - property is <tp:type>Stream_Transport_Type</tp:type>_SHM.</p> + namespace="ofdT.Call1.Stream.Interface.Media">Transport</tp:dbus-ref> + property is <tp:value-ref type="Stream_Transport_Type">SHM</tp:value-ref>.</p> </tp:docstring> </tp:hct> @@ -1413,11 +1544,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. property:</p> <ul> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora</code></li> - <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264</code></li> + <li><code>org.freedesktop.Telepathy.Channel.Type.Call1/audio</code></li> + <li><code>org.freedesktop.Telepathy.Channel.Type.Call1/audio/speex</code></li> + <li><code>org.freedesktop.Telepathy.Channel.Type.Call1/video</code></li> + <li><code>org.freedesktop.Telepathy.Channel.Type.Call1/video/theora</code></li> + <li><code>org.freedesktop.Telepathy.Channel.Type.Call1/video/h264</code></li> </ul> <p>Clients MAY have media signalling abilities without explicitly diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml index 98f745822..b2b886f14 100644 --- a/spec/Channel_Type_Room_List.xml +++ b/spec/Channel_Type_Room_List.xml @@ -86,7 +86,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <dt>subject (s)</dt> <dd>The current subject of conversation in the room (as would be returned by getting the string part of the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + namespace="org.freedesktop.Telepathy.Channel.Interface.Subject2" >Subject</tp:dbus-ref> property)</dd> <dt>members (u)</dt> @@ -101,13 +101,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <dt>room-id (s)</dt> <dd>The human-readable identifier of a chat room (as would be returned by getting the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" - >RoomID</tp:dbus-ref> property)</dd> + namespace="org.freedesktop.Telepathy.Channel.Interface.Room2" + >RoomName</tp:dbus-ref> property)</dd> <dt>server (s)</dt> <dd>The DNS name of the server hosting these channels (as would be returned by getting the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" + namespace="org.freedesktop.Telepathy.Channel.Interface.Room2" >Server</tp:dbus-ref> property)</dd> </dl> </tp:docstring> diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index 86bf567fc..76123293c 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -24,6 +24,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/> <tp:changed version="0.21.5">The Messages interface is now mandatory</tp:changed> + <tp:changed version="0.24.0">This interface used to have a bunch of + clunky <tp:dbus-ref + namespace='org.freedesktop'>Telepathy.Properties</tp:dbus-ref>. They have + been removed in favour of D-Bus properties on the <tp:dbus-ref + namespace='ofdT.Channel.Interface'>Room2</tp:dbus-ref>, <tp:dbus-ref + namespace='ofdT.Channel.Interface'>Subject2</tp:dbus-ref> and + <tp:dbus-ref namespace='ofdT.Channel.Interface'>RoomConfig1</tp:dbus-ref> + interfaces.</tp:changed> <tp:simple-type name="Message_ID" type="u" array-name="Message_ID_List"> <tp:docstring> @@ -430,92 +438,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:flag> </tp:flags> - <tp:property name="anonymous" type="b"> - <tp:docstring> - True if people may join the channel without other members being made - aware of their identity. - </tp:docstring> - </tp:property> - <tp:property name="invite-only" type="b"> - <tp:docstring> - True if people may not join the channel until they have been invited. - </tp:docstring> - </tp:property> - <tp:property name="limit" type="u"> - <tp:docstring> - The limit to the number of members, if limited is true. - </tp:docstring> - </tp:property> - <tp:property name="limited" type="b"> - <tp:docstring> - True if there is a limit to the number of channel members. - </tp:docstring> - </tp:property> - <tp:property name="moderated" type="b"> - <tp:docstring> - True if channel membership is not sufficient to allow participation. - </tp:docstring> - </tp:property> - <tp:property name="name" type="s"> - <tp:docstring> - A human-visible name for the channel, if it differs from the channel's - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>. - </tp:docstring> - </tp:property> - <tp:property name="description" type="s"> - <tp:docstring> - A human-readable description of the channel's overall purpose. - </tp:docstring> - </tp:property> - <tp:property name="password" type="s"> - <tp:docstring> - The password required to enter the channel if password-required is true. - </tp:docstring> - </tp:property> - <tp:property name="password-required" type="b"> - <tp:docstring> - True if a password must be provided to enter the channel. - </tp:docstring> - </tp:property> - <tp:property name="persistent" type="b"> - <tp:docstring> - True if the channel will remain in existence on the server after all - members have left it. - </tp:docstring> - </tp:property> - <tp:property name="private" type="b"> - <tp:docstring> - True if the channel is not visible to non-members. - </tp:docstring> - </tp:property> - <tp:property name="subject" type="s"> - <tp:docstring> - A human-readable description of the current subject of conversation in - the channel, similar to /topic in IRC. This is equivalent to the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" - >Subject</tp:dbus-ref> property in the Room interface which will replace - this Telepathy property. - </tp:docstring> - </tp:property> - <tp:property name="subject-contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - A contact handle representing who last modified the subject, or 0 - if it isn't known. This is equivalent to the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" - >Subject</tp:dbus-ref> property in the Room interface which will replace - this Telepathy property. - </tp:docstring> - </tp:property> - <tp:property name="subject-timestamp" type="u" tp:type="Unix_Timestamp"> - <tp:docstring> - A unix timestamp indicating when the subject was last modified. - This is equivalent to the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT" - >Subject</tp:dbus-ref> property in the Room interface which will replace - this Telepathy property. - </tp:docstring> - </tp:property> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A channel type for sending and receiving messages. This channel type is primarily used for textual messages, but can also be used for @@ -680,6 +602,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ eventually need a distinction between Close and Destroy.</p> </tp:rationale> + <p>Opaquely-named rejoinable chatrooms (such as Skype rooms) are + represented using the properties in the <tp:dbus-ref + namespace="ofdT.Channel.Interface">Room2</tp:dbus-ref> + interface. Instructions and examples of how to request + such channels are given in said interface's description.</p> + </tp:docstring> </interface> </node> diff --git a/spec/Makefile.am b/spec/Makefile.am index 767780e59..553a454f6 100644 --- a/spec/Makefile.am +++ b/spec/Makefile.am @@ -9,10 +9,13 @@ EXTRA_DIST = \ Account_Manager_Interface_Hidden.xml \ Authentication_TLS_Certificate.xml \ Call_Content.xml \ - Call_Content_Codec_Offer.xml \ Call_Content_Interface_Media.xml \ - Call_Content_Interface_Mute.xml \ Call_Content_Interface_Video_Control.xml \ + Call_Content_Media_Description.xml \ + Call_Content_Media_Description_Interface_RTCP_Extended_Reports.xml \ + Call_Content_Media_Description_Interface_RTCP_Feedback.xml \ + Call_Content_Media_Description_Interface_RTP_Header_Extensions.xml \ + Call_Interface_Mute.xml \ Call_Stream.xml \ Call_Stream_Endpoint.xml \ Call_Stream_Interface_Media.xml \ @@ -38,11 +41,13 @@ EXTRA_DIST = \ Channel_Interface_Messages.xml \ Channel_Interface_Password.xml \ Channel_Interface_Room.xml \ + Channel_Interface_Room_Config.xml \ Channel_Interface_SASL_Authentication.xml \ Channel_Interface_SMS.xml \ Channel_Interface_Securable.xml \ Channel_Interface_Service_Point.xml \ Channel_Interface_Splittable.xml \ + Channel_Interface_Subject.xml \ Channel_Interface_Transfer.xml \ Channel_Interface_Tube.xml \ Channel_Request.xml \ diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml index bc9c8b260..09ce3b9c2 100644 --- a/spec/Properties_Interface.xml +++ b/spec/Properties_Interface.xml @@ -19,6 +19,8 @@ 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.Properties"> + <tp:deprecated version="0.24.0">All uses of this interface have been + expunged, and it may now be laid to rest.</tp:deprecated> <tp:struct name="Property_Spec" array-name="Property_Spec_List"> <tp:docstring>A struct (property ID, property name, D-Bus signature, diff --git a/spec/all.xml b/spec/all.xml index 18b8b3295..f8ed0380e 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.23.4</tp:version> +<tp:version>0.24.0</tp:version> <tp:copyright>Copyright © 2005-2011 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright> @@ -165,10 +165,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Interface_Group.xml"/> <xi:include href="Channel_Interface_Password.xml"/> <xi:include href="Channel_Interface_Room.xml"/> + <xi:include href="Channel_Interface_Room_Config.xml"/> <xi:include href="Channel_Interface_SASL_Authentication.xml"/> <xi:include href="Channel_Interface_Credentials_Storage.xml"/> <xi:include href="Channel_Interface_Securable.xml"/> <xi:include href="Channel_Interface_Service_Point.xml"/> + <xi:include href="Channel_Interface_Subject.xml"/> <xi:include href="Channel_Interface_Tube.xml"/> <tp:section name="Text-specific interfaces"> diff --git a/tests/dbus/call-example.c b/tests/dbus/call-example.c index 0e3cfb7af..a0923dd55 100644 --- a/tests/dbus/call-example.c +++ b/tests/dbus/call-example.c @@ -427,7 +427,7 @@ loop_until_answered (Test *test) g_assert_no_error (test->error); if (tp_asv_get_uint32 (test->get_all_return, "CallState", - NULL) != FUTURE_CALL_STATE_PENDING_RECEIVER) + NULL) != FUTURE_CALL_STATE_RINGING) return; } } @@ -791,7 +791,7 @@ test_no_answer (Test *test, g_assert_no_error (test->error); assert_call_properties (test->get_all_return, - FUTURE_CALL_STATE_PENDING_RECEIVER, test->self_handle, + FUTURE_CALL_STATE_RINGING, test->self_handle, FUTURE_CALL_STATE_CHANGE_REASON_USER_REQUESTED, "", TRUE, 0, /* call flags */ TRUE, TRUE, FALSE); /* initial audio/video must be TRUE, FALSE */ @@ -994,7 +994,7 @@ test_incoming (Test *test, g_main_loop_run (test->mainloop); g_assert_no_error (test->error); assert_call_properties (test->get_all_return, - FUTURE_CALL_STATE_PENDING_RECEIVER, test->peer_handle, + FUTURE_CALL_STATE_RINGING, test->peer_handle, FUTURE_CALL_STATE_CHANGE_REASON_USER_REQUESTED, "", TRUE, 0, /* call flags */ TRUE, TRUE, FALSE); /* initial audio/video must be TRUE, FALSE */ |