From 2ec2f2edc2cdefde9a40ea119702aedfac97f3d0 Mon Sep 17 00:00:00 2001 From: Sjoerd Simons Date: Thu, 6 Jan 2011 17:41:44 +0000 Subject: Use a spec directory layout more similar to tp-glib --- spec/Call_Content.xml | 291 +++++++ spec/Call_Content_Codec_Offer.xml | 87 ++ spec/Call_Content_Interface_Media.xml | 331 ++++++++ spec/Call_Content_Interface_Mute.xml | 85 ++ spec/Call_Stream.xml | 261 ++++++ spec/Call_Stream_Endpoint.xml | 182 +++++ spec/Call_Stream_Interface_Media.xml | 440 ++++++++++ spec/Channel_Type_Call.xml | 1425 +++++++++++++++++++++++++++++++++ spec/Makefile.am | 9 + 9 files changed, 3111 insertions(+) create mode 100644 spec/Call_Content.xml create mode 100644 spec/Call_Content_Codec_Offer.xml create mode 100644 spec/Call_Content_Interface_Media.xml create mode 100644 spec/Call_Content_Interface_Mute.xml create mode 100644 spec/Call_Stream.xml create mode 100644 spec/Call_Stream_Endpoint.xml create mode 100644 spec/Call_Stream_Interface_Media.xml create mode 100644 spec/Channel_Type_Call.xml create mode 100644 spec/Makefile.am (limited to 'spec') diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml new file mode 100644 index 0000000..17ed710 --- /dev/null +++ b/spec/Call_Content.xml @@ -0,0 +1,291 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-2010 Nokia Corporation + +

This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.

+ + + + (draft 1) + + + This object represents one Content inside a Call.DRAFT. For + example, in an audio/video call there would be one audio content + and one video content. Each content has one or more Stream.DRAFT objects which + represent the actual transport to one or more remote contacts. + + + + + + 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. + + + + + We just don't know. Unknown values of this enum SHOULD also be + treated like this. + + + + + +

The local user requests that this content is removed + from the call.

+ + + + + +

There is an error with the content which means that it + has to be removed from the call.

+ + + + + +

Some aspect of the content is unsupported so has to be + removed from the call.

+ + + + + + previously there were no + arguments + + Remove the content from the call. + + + + + A generic hangup reason. + + + + + + A more specific reason for the content removal, if one is + available, or an empty string. + + + + + + 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. + + + + + + + + Raised when a Call doesn't support removing contents + (e.g. a Google Talk video call). + + + + + + + +

Emitted when the content is removed from the call. This + is the same as the Call.DRAFT.ContentRemoved + signal.

+ + + + + + +

Extra interfaces provided by this content, such as Content.Interface.Media.DRAFT or + Content.Interface.Mute.DRAFT. + This SHOULD NOT include the Content interface itself, and cannot + change once the content has been created.

+ + + + + +

The name of the content.

+ + + The content name property should be meaningful, so should be + given a name which is significant to the user. The name + could be the "audio" or "video" string localized, or perhaps + include some string identifying the source, such as a webcam + identifier. + + + + + + +

The media type of this content.

+ + + + + + The disposition of this content, which defines whether to + automatically start sending data on the streams when + Call.DRAFT is + called on the channel. + + + + + The content has no specific disposition + + + + + +

The content was initially part of the call. When + Accept + is called on the channel, all streams of this content with + LocalSendingState + set to Sending_State_Pending_Send will be + moved to Sending_State_Sending as if + SetSending + (True) had been called.

+ + + + + + + The disposition of this content. + + + + + plural version, renamed from + StreamAdded + +

Emitted when streams are added to a call.

+ + + + The Stream.DRAFTs which were + added. + + + + + + plural version, renamed from + StreamRemoved + +

Emitted when streams are removed from a call

+ + + + The Stream.DRAFTs which were + removed. + + + + + + +

The list of Stream.DRAFT objects that exist in this + content.

+ + + In a conference call multiple parties can share one media + content (say, audio), but the streaming of that media can + either be shared or separate. For example, in a multicast + conference all contacts would share one stream, while in a + Muji conference there would be a stream for each + participant. + + +

Change notification is through the + StreamsAdded and + StreamsRemoved signals.

+ + + + + + + A packetization method that can be used for a content. + + + + + Real-time Transport Protocol, as documented by RFC 3550. + + + + + + Raw media. + + + + + + MSN webcam. This is the video-only one-way type which was + used in earlier versions of WLM. Although no longer used, + modern WLM clients still support the MSN webcam protocol. + + + + + + + +

The packetization method in use for this content.

+ + + + + diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml new file mode 100644 index 0000000..f88143f --- /dev/null +++ b/spec/Call_Content_Codec_Offer.xml @@ -0,0 +1,87 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-2010 Nokia Corporation + +

This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.

+ + + + (draft 1) + + + This object represents an offer of a Codec payload mapping. + + + + + + The local codec mapping to send to the remote contacts and + to use in the Content.DRAFT. + + + + Accept the updated Codec mapping and update the local mapping. + + + + + The codecs given as the argument are invalid in some way. + + + + + + + + Reject the proposed update to the codecs + FIXME add error codes and strings here + + + + + +

Extra interfaces provided by this codec offer. This SHOULD + NOT include the CodecOffer interface itself, and cannot change + once the content has been created.

+ + + + + + A list of codecs the remote contact supports. + + + + + + The contact handle that this codec offer applies to. + + + + + + + diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml new file mode 100644 index 0000000..274d8b2 --- /dev/null +++ b/spec/Call_Content_Interface_Media.xml @@ -0,0 +1,331 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-2010 Nokia Corporation + +

This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.

+ + + + (draft 1) + + + +

Interface to use by a software implementation of media + streaming. The reason behind splitting the members of this + interface out from the main Content.DRAFT 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.

+ +

Codec negotiation

+ +

When a new Call.DRAFT channel + appears, whether it was requested or not, a CodecOffer.DRAFT + will either be waiting in the + CodecOffer property, or will + appear at some point via the + NewCodecOffer signal.

+ +

The RemoteContactCodecs + 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.

+ +

For incoming calls on protocols where codecs are proposed when + starting the call (for example, Jingle), + the RemoteContactCodecs + will contain information on the codecs that have already been + proposed by the remote contact, otherwise the codec map will + be the empty list.

+ +

The streaming implementation should look at the remote codec + map and the codecs known by the local user and call + CodecOffer.DRAFT.Accept + on the intersection of these two codec lists.

+ +

This means that in practice, outgoing calls will have a codec + offer pop up with no information in the RemoteContactCodecs, + so the local user will call Accept + with the list of all codecs supported. If this codec offer is + accepted, then CodecsChanged + will fire with the details of the codecs passed into + Accept. If + the call is incoming, then the RemoteContactCodecs + will contain details of the remote contact's codecs and the + local user will call Accept + with the codecs that both sides understand. After the codec + set is accepted, CodecsChanged + will fire to signal this change.

+ +

Protocols without codec negotiation

+ +

For protocols where the codecs are not negotiable, instead of + popping up the initial content's CodecOffer.DRAFT + object with an empty RemoteContactCodecs, + the CM should set the supported codec values to known codec + values in the said object's codec map.

+ +

Changing codecs mid-call

+ +

To update the codec list used mid-call, the + UpdateCodecs method should be + called with details of the new codec list. If this is + accepted, then CodecsChanged + will be emitted with the new codec set.

+ +

If the other side decides to update his or her codec list + during a call, a new CodecOffer.DRAFT + object will appear through + NewCodecOffer which should be + acted on as documented above.

+ + + + + + A description of a codec. + + + + Numeric identifier for the codec. This will be used as the PT in the + SDP or content description. + + + + + The name of the codec. + + + + + The clockrate of the codec. + + + + + Number of channels of the codec if applicable, otherwise 0. + + + + + Extra parameters for this codec. + + + + + + + A map from contact to the list of codecs he or she supports. + + + + A contact handle. + + + + + The codecs that the contact supports. + + + + + + + A codec offer and its corresponding remote contact codec map. + + + + The object path to the CodecOffer.DRAFT + + + + + The contact handle that this codec offer applies to. + + + + + The CodecOffer.DRAFT.RemoteContactCodecs property + of the codec offer. + + + + + + +

Emitted when the codecs in use change.

+ +

As well as acting as change notification for the + ContactCodecMap, emission of this + signal implies that the CodecOffer + property has changed to ('/', {}).

+ + + + A map from contact to his or her codecs. Each pair in this + map is added to the + ContactCodecMap property, + replacing any previous pair with that key. + + + + + A list of keys which were removed from the + ContactCodecMap, probably because + those contacts left the call. + + + + + + + Update the local codec mapping. This method should only be + used during an existing call to update the codec mapping. + + + + The codecs now supported by the local user. + + + + + + Raised when a CodecOffer.DRAFT + object exists and is referred to in the + CodecOffer property which + should be used instead of calling this method, or before + the content's initial CodecOffer.DRAFT + object has appeared. + + + + + + + +

A map from contact handles (including the local user's own handle) + to the codecs supported by that contact.

+ +

Change notification is via the + CodecsChanged signal.

+ + + + + +

Emitted when a new CodecOffer.DRAFT appears. The streaming + implementation MUST respond by calling the Accept or Reject method on the codec offer object.

+ +

Emission of this signal indicates that the + CodecOffer property has changed to + (Contact, Offer, Codecs).

+ + + + The contact the codec offer belongs to. + + + + + The object path of the new codec offer. This replaces any previous + codec offer. + + + + +

The CodecOffer.DRAFT.RemoteContactCodecs property + of the codec offer.

+ + + Having the RemoteContactCodecs + property here saves a D-Bus round-trip - it shouldn't be + necessary to get the property from the CodecOffer object, in + practice. + + + + + + + +

The object path to the current + CodecOffer.DRAFT object, its + CodecOffer.DRAFT.RemoteContact and + CodecOffer.DRAFT.RemoteContactCodecs properties. + If the object path is "/" then there isn't an outstanding + codec offer, and the mapping MUST be empty.

+ + + Having the RemoteContact and + RemoteContactCodecs + properties here saves a D-Bus round-trip - it shouldn't be + necessary to get these properties from the CodecOffer object, in + practice. + + +

Change notification is via the + NewCodecOffer (which replaces the + value of this property with a new codec offer), and + CodecsChanged (which implies that + there is no longer any active codec offer) signals.

+ + + + + diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml new file mode 100644 index 0000000..f926e03 --- /dev/null +++ b/spec/Call_Content_Interface_Mute.xml @@ -0,0 +1,85 @@ + + + Copyright © 2005-2010 Nokia Corporation + Copyright © 2005-2010 Collabora Ltd + +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. + + + + (draft version, not API-stable) + + + +

Interface for calls which may be muted. This only makes sense + for channels where audio or video is streaming between members.

+ +

Muting a call content indicates that the user does not wish to send + outgoing audio or video.

+ +

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.

+ + + 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. + + + + + + Emitted to indicate that the mute state has changed for this call content. + This may occur as a consequence of the client calling + SetMuted, or as an indication that another + client has (un)muted the content. + + + + True if the content is now muted. + + + + + + + True if the content is muted. + + + + + renamed from SetMuted to Mute + renamed back from Mute to SetMuted + + + True if the client has muted the content. + + + +

Inform the CM that the call content has been muted or unmuted by + the client.

+ +

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.

+ + + + + + diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml new file mode 100644 index 0000000..1d7b281 --- /dev/null +++ b/spec/Call_Stream.xml @@ -0,0 +1,261 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-2010 Nokia Corporation + +

This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.

+ + + + (draft 1) + + + One stream inside a Content.DRAFT. + + + + + Set the stream to start or stop sending media from the local + user to other contacts. + + + + +

If True, the + LocalSendingState should + change to Sending_State_Sending, if it isn't + already.

+ +

If False, the + LocalSendingState should + change to Sending_State_None, if it isn't + already.

+ + + + + + + + + + +

Request that a remote contact stops or starts sending on + this stream.

+ +

The CanRequestReceiving + property defines whether the protocol allows the local user to + request the other side start sending on this stream.

+ + + + +

Contact from which sending is requested

+ + + + + +

If true, request that the given contact starts to send media. + If false, request that the given contact stops sending media.

+ + + + + + + + The request contact is valid but is not involved in this + stream. + + + + + The protocol does not allow the local user to request the + other side starts sending on this stream. + + + + + + + renamed from SendersChanged to MembersChanged + renamed from MembersChanged to RemoteMembersChanged + + Emitted when RemoteMembers changes. + + + + + A mapping from channel-specific handles to their updated sending + state, whose keys include at least the members who were added, + and the members whose states changed. + + + + + The channel-specific handles that were removed from the keys + of the RemoteMembers + property, as a result of the contact leaving this stream + + + + + + + Emitted when LocalSendingState changes. + + + + + The new value of + LocalSendingState. + + + + + + + Enum indicating whether a contact is sending media. + + + + + The contact is not sending media and has not been asked to + do so. + + + + + + The contact has been asked to start sending media. + + + + + + The contact is sending media. + + + + + + The contact has been asked to stop sending media. + + + + + + + A map from a contact to his or her sending state. + + + + The contact handle. + + + + + The sending state of the contact. + + + + + + + +

Extra interfaces provided by this stream, such as Stream.Interface.Media.DRAFT. + This SHOULD NOT include the Stream interface itself, and cannot + change once the stream has been created.

+ + + + + renamed from Senders + +

A map from remote contacts to their sending state. The + local user's sending state is shown in + LocalSendingState.

+ +

Sending_State_Pending_Send indicates + that another contact has asked the local user to send + media.

+ +

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.

+ + + + + +

The local user's sending state. Media sent on this stream + should be assumed to be received, directly or indirectly, by + every other contact in the + RemoteMembers mapping. Change + notification is given via the + LocalSendingStateChanged + signal.

+ + + Implementations of the first Call draft had the self handle + in the RemoteMembers (then + called Members) map and this showed that it's annoying + having to keep track of the self handle so that it can be + special-cased. + + +

A value of Sending_State_Pending_Send for + this property indicates that the other side requested the + local user start sending media, which can be done by calling + SetSending. When a call is + accepted, all initial contents with streams that have a + local sending state of + Sending_State_Pending_Send are + automatically set to sending. For example, on an incoming + call it means you need to Accept + to start the actual call, on an outgoing call it might mean + you need to call Accept + before actually starting the call.

+ + + + + + +

If true, the user can request that a remote contact starts + sending on this stream.

+ + Not all protocols allow the user to ask the + other side to start sending media. + + + + + diff --git a/spec/Call_Stream_Endpoint.xml b/spec/Call_Stream_Endpoint.xml new file mode 100644 index 0000000..4818168 --- /dev/null +++ b/spec/Call_Stream_Endpoint.xml @@ -0,0 +1,182 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-2010 Nokia Corporation + +

This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.

+ + + + (draft 1) + + +

This object represents an endpoint for a stream. In a one-to-one + call, there will be one (bidirectional) stream per content and + one endpoint per stream (as there is only one remote + contact). In a multi-user call there is a stream for each remote + contact and each stream has one endpoint as it refers to the one + physical machine on the other end of the stream.

+ +

The multiple endpoint use case appears when SIP call forking + is used. Unlike jingle call forking (which is just making + multiple jingle calls to different resources appear as one + call), SIP call forking is actually done at the server so you + have one stream to the remote contact and then and endpoint for + each SIP client to be called.

+ + + + + The ICE credentials used for all candidates. If each candidate + has different credentials, then this property SHOULD be ("", + ""). Per-candidate credentials are set in the + Candidate's + Candidate_Info a{sv}. + + + + + + + The username set. + + + + + The password set. + + + + Emitted when the remote ICE credentials for the endpoint are + set. If each candidate has different credentials, then this + signal will never be fired. + + + + + + A list of candidates for this endpoint. + + + + + + Emitted when remote candidates are added to the + RemoteCandidates property. + + + + The candidates that were added. + + + + + + + Emitted when a candidate is selected for use in the stream. + + + + The candidate that has been selected. + + + + + + + The candidate that has been selected for use to stream packets + to the remote contact. Change notification is given via the + the CandidateSelected signal. + + + + + + Set the value of + CandidateSelected. + + + + The candidate that has been selected. + + + + + + + + + + The stream state of the endpoint. + + + + + + Emitted when the StreamState + property changes. + + + + The new StreamState value. + + + + + + + Change the StreamState of the + endpoint. + + + + The requested stream state. + + + + + + + + + + + The transport type for the stream endpoint. + + + + + + diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml new file mode 100644 index 0000000..5f2bbec --- /dev/null +++ b/spec/Call_Stream_Interface_Media.xml @@ -0,0 +1,440 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009-2010 Nokia Corporation + +

This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.

+ +

This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.

+ +

You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.

+ + + + (draft 1) + + + + [FIXME] + +

ICE restarts

+ +

If the RemoteCredentialsSet + 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 Endpoint.DRAFT.

+ +

If the CM does an ICE restart, then the + PleaseRestartICE signal is + emitted and the streaming implementation should then call + SetCredentials again.

+ +

For more information on ICE restarts see + RFC 5245 + section 9.1.1.1

+ + + + +

Used to set the username fragment and password for streams that have + global credentials.

+ + + + The username to use when authenticating on the stream. + + + + + The password to use when authenticating on the stream. + + + + + + +

Extra information about the candidate. Allowed and mandatory keys + depend on the transport protocol used. The following keys are commenly + used:

+ +
+
Type (u)
+
type of candidate (host, srflx, prflx, relay)
+ +
Foundation (s)
+
the foundation of this candiate
+ +
Protocol (u)
+
Underlying protocol of the candidate (udp, tcp)
+ +
Priority (u)
+
Priority of the candidate
+ +
BaseIP (u)
+
Base IP of this candidate
+ +
Username (s)
+
Username of this candidate + (only if credentials are per candidate)
+ +
Password (s)
+
Password of this candidate + (only if credentials are per candidate)
+ +
RawUDPFallback (b)
+
Indicate whether this candidate may be used to provide a UDP + fallback
+
+ + + One of the well-known keys documented here, or an + implementation-specific key. + + + The value corresponding to that key. + + + + + A Stream Candidate. + + The component number. + + + The IP address to use. + + + The port number to use. + + + Additional information about the candidate. + + + + + + Add candidates to the + LocalCandidates property and + signal them to the remote contact(s). + + + + The candidates to be added. + + + + + + + This indicates to the CM that the initial batch of candidates + has been added. + + + + + WLM_8_5 was removed + + A transport that can be used for streaming. + + + + The stream transport type is unknown or not applicable. + + + + + 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 Call.DRAFT interface. + [This corresponds to "none" or "stun" in the old Media.StreamHandler + interface.] + + + + + Interactive Connectivity Establishment, as defined by RFC + 5245. Note that this value covers ICE-UDP only. + [This corresponds to "ice-udp" in the old + Media.StreamHandler interface.] + + + + + Google Talk peer-to-peer connectivity establishment, as implemented + by libjingle 0.3. + [This corresponds to "gtalk-p2p" in the old Media.StreamHandler + interface.] + + + + + The transport used by Windows Live Messenger 2009 or later, which + resembles ICE draft 19. + [This corresponds to "wlm-2009" in the old Media.StreamHandler + interface.] + + + + + + Shared memory transport, as implemented by the GStreamer + shmsrc and shmsink plugins. + + + + + + + The transport for this stream. + + + + + + [FIXME]. Change notification is via the + LocalCandidatesAdded signal. + + + + + + Emitted when local candidates are added to the + LocalCandidates property. + + + + Candidates that have been added. + + + + + + A username and password pair. + + + The username. + + + + The password. + + + + + + [FIXME]. Change notification is via the + LocalCredentialsChanged signal. + + + + + renamed from LocalCredentailsSet + + Emitted when the value of + LocalCredentials changes. + + + + + + + + Emitted when the value of + RelayInfo changes. + + + + + + + Emitted when the value of + STUNServers changes. + + + + + + +

The IP addresses of possible STUN servers to use for NAT + traversal, as dotted-quad IPv4 address literals or RFC2373 + IPv6 address literals. Change notification is via the + STUNServersChanged + signal. The IP addresses MUST NOT be given as DNS hostnames.

+ + + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + to make life easier for streaming implementations. + + + + + + +

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:

+ +
+
ip - s
+
The IP address of the relay server as a dotted-quad IPv4 + address literal or an RFC2373 IPv6 address literal. This MUST NOT + be a DNS hostname. + + + High-quality connection managers already need an asynchronous + DNS resolver, so they might as well resolve this name to an IP + and make life easier for streaming implementations. + +
+ +
type - s
+
+

Either udp for UDP (UDP MUST be assumed if this + key is omitted), tcp for TCP, or + tls.

+ +

The precise meaning of this key depends on the + Transport property: if + Transport is ICE, tls means + TLS over TCP as referenced by ICE draft 19, and if + Transport is GTalk_P2P, tls means + a fake SSL session over TCP as implemented by libjingle.

+
+ +
port - q
+
The UDP or TCP port of the relay server as an ASCII unsigned + integer
+ +
username - s
+
The username to use
+ +
password - s
+
The password to use
+ +
component - u
+
The component number to use this relay server for, as an + ASCII unsigned integer; if not included, this relay server + may be used for any or all components. + + + In ICE draft 6, as used by Google Talk, credentials are only + valid once, so each component needs relaying separately. + +
+
+ + +

An equivalent of the gtalk-p2p-relay-token property on + MediaSignalling channels is not included here. The connection + manager should be responsible for making the necessary HTTP + requests to turn the token into a username and password.

+ + +

The type of relay server that this represents depends on + the value of the Transport + property. If Transport is ICE, this is a TURN server; + if Transport is GTalk_P2P, this is a Google relay server; + otherwise, the meaning of RelayInfo is undefined.

+ +

If relaying is not possible for this stream, the list is + empty.

+ +

Change notification is given via the + RelayInfoChanged signal.

+ + + + + +

Signals that the initial information about STUN and Relay servers + has been retrieved, i.e. the + HasServerInfo property is + now true.

+ + + + + +

True if all the initial information about STUN servers and Relay + servers has been retrieved. Change notification is via the + ServerInfoRetrieved signal.

+ + + Streaming implementations that can't cope with STUN and + relay servers being added later SHOULD wait for this + property to become true before proceeding. + + + + + + + Emitted when the Endpoints property + changes. + + + + Endpoints that were added. + + + + + Endpoints that no longer exist. + + + + + + +

The list of Endpoint.DRAFT objects that exist for this + stream.

+ +

Change notification is via the + EndpointsChanged signal.

+ + + + + + Emitted when the CM does an ICE restart to notify the + streaming implementation that it should call + SetCredentials again. + + + + + diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml new file mode 100644 index 0000000..eb1a663 --- /dev/null +++ b/spec/Channel_Type_Call.xml @@ -0,0 +1,1425 @@ + + + Copyright © 2009-2010 Collabora Limited + Copyright © 2009-2010 Nokia Corporation + + This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + + (draft 1) + + + +

A channel type for making audio and video calls. Call + channels supersede the old StreamedMedia + channel type. Call channels are much more flexible than its + predecessor and allow more than two participants.

+ +

Handlers are advised against executing all the media + signalling, codec and candidate negotiation themselves but + instead use a helper library such as telepathy-farsight + which when given a new Call channel will set up the + transports and codecs and create GStreamer pads which + can be added to the handler UI. This is useful as it means + the handler does not have to worry how exactly the + connection between the call participants is being made.

+ +

The TargetHandle and + TargetID + properties in a Call channel refer to the contact that the + user initially called, or which contact initially called the + user. Even in a conference call, where there are multiple + contacts in the call, these properties refer to the + initial contact, who might have left the conference since + then. As a result, handlers should not rely on these + properties.

+ +

Contents

+ +

Content.DRAFT 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.

+ +

Content.DRAFT objects have + one or more stream associated with them. More information on + these streams and how to maniuplate them can be found on the + Content.DRAFT + interface page.

+ +

Outgoing calls

+ +

To make an audio-only call to a contact foo@example.com + handlers should call:

+ +
+ 
+CreateChannel({
+  ...ChannelType: ...Call.DRAFT,
+  ...TargetHandleType: Contact,
+  ...TargetID: 'foo@example.com',
+  ...InitialAudio: True,
+})
+ +

As always, TargetHandle may be used + in place of + TargetID + if the contact's handle is already known. To make an audio + and video call, the handler should also specify + InitialVideo The + connection manager SHOULD return a channel whose immutable + properties contain the local user as the InitiatorHandle, the + remote contact as the TargetHandle, + Requested = + True (indicating the call is outgoing).

+ +

After a new Call channel is requested, the + CallState property will be + Call_State_Pending_Initiator. As the local + user is the initiator, the call must be accepted by the handler + by calling the Accept method. + At this point, CallState changes + to Call_State_Pending_Receiver which signifies + that the call is ringing, waiting for the remote contact to + accept the call. All changes to + CallState property are signalled + using the CallStateChanged + signal.

+ +

When the call is accepted by the remote contact, the + CallStateChanged signal fires + again to show that CallState = + Call_State_Accepted.

+ +

At this point telepathy-farsight + will signal that a pad is available for the handler to show + in the user interface.

+ +
Missed calls
+ +

If the remote contact does not accept the call in time, then + the call can be terminated by the server. Note that this only + happens in some protocols. Most XMPP clients, for example, do + not do this and rely on the call initiator terminating the call. + A missed call is shown in a Call channel by the + CallState property changing to + Call_State_Ended, and the + CallStateReason property changing + to (remote contact, + Call_State_Change_Reason_No_Answer, "").

+ +
Rejected calls
+ +

If the remote contact decides he or she does not feel like + talking to the local user, he or she can reject his or her + incoming call. This will be shown in the Call channel by + CallState changing to + Call_State_Ended and the + CallStateReason property + changing to (remote contact, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Rejected").

+ +

Incoming calls

+ +

When an incoming call occurs, something like the following + NewChannels + signal will occur:

+ +
+ 
+NewChannels([
+  /org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel,
+  {
+    ...ChannelType: ...Call.DRAFT,
+    ...TargetHandleType: Contact,
+    ...TargetID: 'foo@example.com',
+    ...TargetHandle: 42,
+    ...Requested: False,
+    ...InitialAudio: True,
+    ...InitialVideo: True,
+    ...InitialAudioName: "audio",
+    ...InitialVideoName: "video",
+    ...MutableContents: True,
+  }])
+ +

The InitialAudio and + InitialVideo properties show that + the call has been started with two contents: one for audio + streaming and one for video streaming. The + InitialAudioName and + InitialVideoName properties also + show that the aforementioned audio and video contents have names + "audio" and "video".

+ +

Once the handler has notified the local user that there is an + incoming call waiting for acceptance, the handler should call + SetRinging to let the CM know. + The new channel should also be given to telepathy-farsight to + work out how the two participants will connect together. + telepathy-farsight will call the appropriate methods on the call's + Content.DRAFTs + to negotiate codecs and transports.

+ +

To pick up the call, the handler should call + Accept. The + CallState property changes to + Call_State_Accepted and once media is + being transferred, telepathy-farsight will notify the + handler of a new pad to be shown to the local user in the + UI

+ +

To reject the call, the handler should call the + Hangup method. The + CallState property will change to + Call_State_Ended and the + CallStateReason property will + change to (self handle, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Rejected").

+ +

Ongoing calls

+ +
Adding and removing contents
+ +

When a call is open, new contents can be added as long as the + CM supports it. The + MutableContents property will let + the handler know whether further contents can be added or + existing contents removed. An example of this is starting a + voice call between a contact and then adding a video content. + To do this, the should call + AddContent like this:

+ +
+ 
AddContent("video",
+           Media_Stream_Type_Video)
+
+ +

Assuming no errors, the new video content will be added to + the call. telepathy-farsight will pick up the new content and + perform the transport and codec negotiation automatically. + telpathy-farsight will signal when the video is ready to + show in the handler's user interface.

+ +

A similar method is used for removing contents from a call, + except that the Remove method + is on the Content.DRAFT object.

+ +
Ending the call
+ +

To end the call, the handler should call the + Hangup method. The + CallState property will change to + Call_State_Ended and + CallStateReason will change + to (self handle, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Cancelled").

+ +

If the other participant hangs up first then the + CallState property will change to + Call_State_Ended and + CallStateReason will change + to (remote contact, + Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Terminated").

+ +

Multi-party calls

+ + [TODO] + +

Call states

+ +

There are many combinations of the + CallState and + CallStateReason properties which + mean different things. Here is a table to try to make these + meanings clearer:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RequestedCallStateCallStateReasonMeaning
ActorReasonDBus_Reason
TrueCall_State_Pending_InitiatorSelf handleCall_State_Change_Reason_User_Requested""The outgoing call channel is waiting for the local user to call Accept.
TrueCall_State_Pending_ReceiverSelf handleCall_State_Change_Reason_User_Requested""The outgoing call is waiting for the remote contact to pick up the call.
FalseCall_State_Pending_Receiver0Call_State_Change_Reason_Unknown""The incoming call is waiting for the local user to call Accept on the call.
TrueCall_State_AcceptedRemote contact handleCall_State_Change_Reason_User_Requested""The remote contact accepted the outgoing call.
FalseCall_State_AcceptedSelf handleCall_State_Change_Reason_User_Requested""The local user accepted the incoming call.
True or FalseCall_State_EndedSelf handleCall_State_Change_Reason_User_RequestedCancelledThe local user hung up the incoming or outgoing call.
True or FalseCall_State_EndedRemote contact handleCall_State_Change_Reason_User_RequestedTerminatedThe remote contact hung up the incoming or outgoing call.
TrueCall_State_EndedRemote contact handleCall_State_Change_Reason_No_Answer""The outgoing call was not picked up and the call ended.
FalseCall_State_EndedRemote contact handleCall_State_Change_Reason_User_RequestedPickedUpElsewhereThe incoming call was ended because it was picked up elsewhere.
+ +

Requestable channel classes

+ +

The RequestableChannelClasses + for Call.DRAFT channels + can be:

+ +
+ 
+[( Fixed = { ...ChannelType: ...Call.DRAFT,
+            ...TargetHandleType: Contact,
+            ...InitialVideo: True
+          },
+  Allowed = [ ...InitialVideoName,
+              ...InitialAudio,
+              ...InitialAudioName
+            ]
+),
+( Fixed = { ...ChannelType: ...Call.DRAFT,
+            ...TargetHandleType: Contact,
+            ...InitialAudio: True
+          },
+  Allowed = [ ...InitialAudioName,
+              ...InitialVideo,
+              ...InitialVideoName
+            ]
+)]
+ +

Clients aren't allowed to make outgoing calls that have + neither initial audio nor initial video. Clearly, CMs + which don't support video should leave out the first class and + omit InitialVideo from the second + class, and vice versa for CMs without audio support.

+ +

Handlers should not close Call.DRAFT channels + without first calling Hangup on + the channel. If a Call handler crashes, the ChannelDispatcher will call + Close on the + channel which SHOULD also imply a call to + Hangup(Call_State_Change_Reason_User_Requested, + "org.freedesktop.Telepathy.Error.Terminated", "") before + actually closing the channel.

+ + + + + renamed from Ringing + +

Indicate that the local user has been alerted about the incoming + call.

+ +

This method is only useful if the + channel's Requested + property is False, and + the CallState is + Call_State_Pending_Receiver (an incoming + call waiting on the local user to pick up). While this is + the case, this method SHOULD change the + CallFlags to include + Call_Flags_Locally_Ringing, and notify the + remote contact that the local user has been alerted (if the + protocol implements this); repeated calls to this method + SHOULD succeed, but have no further effect.

+ +

In all other states, this method SHOULD fail with the error + NotAvailable.

+ + + + + + The call was Requested, so ringing does not make sense. + + + + + The call is no longer in state + Call_State_Pending_Receiver. + + + + + + + +

For incoming calls in state + Call_State_Pending_Receiver, accept the + incoming call; this changes the + CallState to + Call_State_Accepted.

+ +

For outgoing calls in state + Call_State_Pending_Initiator, actually + call the remote contact; this changes the + CallState to + Call_State_Pending_Receiver.

+ +

Otherwise, this method SHOULD fail with the error NotAvailable.

+ +

This method should be called exactly once per Call, by whatever + client (user interface) is handling the channel.

+ +

When this method is called, for each Content.DRAFT whose + Disposition is + Call_Content_Disposition_Initial, any + streams where the LocalSendingState + is Sending_State_Pending_Send will be + moved to Sending_State_Sending as if + SetSending(True) had been called.

+ + + + + + The call is not in one of the states where this method makes sense. + + + + + + + + Request that the call is ended. All contents will be removed + from the Call so that the + Contents property will be the + empty list. + + + + + A generic hangup reason. + + + + + + A more specific reason for the call hangup, if one is available, or + an empty string otherwise. + + + + + + A human-readable message to be sent to the remote contact(s). + + + XMPP Jingle allows calls to be terminated with a human-readable + message. + + + + + + + + The call has already been ended. + + + + + + + + Request that a new Content.DRAFT of type + Content_Type is added to the Call. Handlers should check the + value of the MutableContents + property before trying to add another content as it might not + be allowed. + + + +

The suggested name of the content to add.

+ + + The content name property should be meaningful, so should + be given a name which is significant to the user. The name + could be a localized "audio", "video" or perhaps include + some string identifying the source, such as a webcam + identifier. + + +

If there is already a content with the same name as this + property then a sensible suffix should be added. For example, + if this argument is "audio" but a content of the same name + already exists, a sensible suffix such as " (1)" is appended + to name the new content "audio (1)". A further content with the + name "audio" would then be named "audio (2)".

+ + + + + + The media stream type of the content to be added to the + call. + + + + + Path to the newly-created Call.Content.DRAFT object. + + + + + + + The media stream type given is invalid. + + + + + The media stream type requested is not implemented by the + CM. + + + + + The content type requested cannot be added to this + call. Examples of why this might be the case include + because a second video stream cannot be added, or a + content cannot be added when the content set isn't + mutable. + + + + + + + +

Emitted when a new Content.DRAFT is added to the call.

+ + + + Path to the newly-created Content.DRAFT object. + + + + + + +

Emitted when a Content.DRAFT is removed from the call.

+ + + + The Content.DRAFT which was removed. + + + + + + +

The list of Content.DRAFT objects that + are part of this call. Change notification is via the + ContentAdded and + ContentRemoved signals. +

+ + + + + +

The state of a call, as a whole.

+ +

The allowed transitions are:

+ +
    +
  • Pending_Initiator → Pending_Receiver (for outgoing calls, + when Accept is called)
    • +
  • Pending_Receiver → Accepted (for incoming calls, when + Accept 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)
    • +
  • Accepted → Pending_Receiver (when transferred to another + contact)
    • +
  • any state → Ended (when the call is terminated normally, or + when an error occurs)
    • +
+ +

Clients MAY consider unknown values from this enum to be an + error - additional values will not be defined after the Call + specification is declared to be stable.

+ + + + + The call state is not known. This call state MUST NOT appear as a + value of the CallState property, but + MAY be used by client code to represent calls whose state is as yet + unknown. + + + + + 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 + user has not yet sent any signalling messages to the remote user(s), + and will not do so until Accept is + called. + + + + + The receiver (the contact being called) hasn't accepted the call yet. + + + + + The contact being called has accepted the call. + + + + + The call has ended, either via normal termination or an error. + + + + + + + A set of flags representing the status of the call as a whole, + providing more specific information than the + CallState. Many of these flags only make + sense in a particular state. + + + + + 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 Call_State_Pending_Receiver. It SHOULD + be set when SetRinging is + called successfully, and unset when the state changes. + + + + + + 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 Call_State_Pending_Receiver. It SHOULD be + set or unset according to informational messages from other + contacts. + + + + + + The call has been put on hold by the local user, e.g. using + the Hold 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 + Call_State_Pending_Receiver + or Call_State_Accepted. + + + Otherwise, in transient situations where some but not all contents + are on hold, UIs would falsely indicate that the call as a whole + 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! + + + + + + + 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 + Call_State_Pending_Receiver or + Call_State_Accepted. It SHOULD be set or unset + according to informational messages from other contacts. + + + + + + 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 + Call_State_Pending_Receiver, and SHOULD be set + or unset according to informational messages from servers, gateways + and other infrastructure. + + + + + + This flag only occurs when the CallState is Ended. The call with + this flag set has ended, but not all resources corresponding to the + call have been freed yet. + + Depending on the protocol there might be some audible feedback while + the clearing flag is set. + + + In calls following the ITU-T Q.931 standard there is a period of + time between the call ending and the underlying channel being + completely free for re-use. + + + + + + + The call has been muted by the local user, e.g. using the + Mute.DRAFT 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 + Call_State_Pending_Receiver or + Call_State_Accepted. + + + + + + +

A map used to provide optional extensible details for the + CallState, + CallFlags and/or + CallStateReason.

+ +

Well-known keys and their corresponding value types include:

+ +
+
hangup-message - s
+
An optional human-readable message sent when the call was ended, + corresponding to the Message argument to the + Hangup method. This is only + applicable when the call state is Call_State_Ended. + + XMPP Jingle can send such messages. + +
+ +
queue-message - s
+
An optional human-readable message sent when the local contact + is being held in a queue. This is only applicable when + Call_Flags_Queued is in the call flags. + + SIP 182 notifications can have human-readable messages attached. + +
+ +
debug-message - s
+
A message giving further details of any error indicated by the + CallStateReason. This will not + normally be localized or suitable for display to users, and is only + applicable when the call state is + Call_State_Ended.
+
+ + + + + +

The current high-level state of this call. The + CallFlags provide additional + information, and the CallStateReason + and CallStateDetails explain the + reason for the current values for those properties.

+ +

Note that when in a conference call, this property is + purely to show your state in joining the call. The receiver + (or remote contact) in this context is the conference server + itself. The property does not change when other call members' + states change.

+ +

Clients MAY consider unknown values in this property to be an + error.

+ + + + + +

Flags representing the status of the call as a whole, + providing more specific information than the + CallState.

+ +

Clients are expected to ignore unknown flags in this property, + without error.

+ +

When an ongoing call is active and not on hold or has any + other problems, this property will be 0.

+ + + + + + A simple representation of the reason for a change in the call's + state, which may be used by simple clients, or used as a fallback + when the DBus_Reason member of a Call_State_Reason + struct is not understood. + + + + + We just don't know. Unknown values of this enum SHOULD also be + treated like this. + + + + + +

The change was requested by the contact indicated by the Actor + member of a Call_State_Reason struct.

+ +

If the Actor is the local user, the DBus_Reason SHOULD be the + empty string.

+ +

If the Actor is a remote user, the DBus_Reason SHOULD be the empty + string if the call was terminated normally, but MAY be a non-empty + error name to indicate error-like call termination reasons (call + rejected as busy, kicked from a conference by a moderator, etc.).

+ + + + + +

The call was forwarded. If known, the handle of the contact + the call was forwarded to will be indicated by the Actor member + of a Call_State_Reason struct.

+ + + + + + +

The CallState changed from + Call_State_Pending_Receiver to + Call_State_Ended because the initiator + ended the call before the receiver accepted it. With an + incoming call this state change reason signifies a missed + call.

+ + + + + + +

A description of the reason for a change to the + CallState and/or + CallFlags.

+ + + + + The contact responsible for the change, or 0 if no contact was + responsible. + + + + + + The reason, chosen from a limited set of possibilities defined by + the Telepathy specification. If + Call_State_Change_Reason_User_Requested then + the Actor member will dictate whether it was the local user or + a remote contact responsible. + + + + + +

A specific reason for the change, which may be a D-Bus error in + the Telepathy namespace, a D-Bus error in any other namespace + (for implementation-specific errors), or the empty string to + indicate that the state change was not an error.

+ +

This SHOULD be an empty string for changes to any state other + than Ended.

+ +

The errors Cancelled and Terminated SHOULD NOT be used here; + an empty string SHOULD be used instead.

+ + +

Those error names are used to indicate normal call + termination by the local user or another user, respectively, + in contexts where a D-Bus error name must appear.

+ + + + + + + +

The reason for the last change to the + CallState and/or + CallFlags. The + CallStateDetails MAY provide additional + information.

+ + + + + +

Emitted when the state of the call as a whole changes.

+ +

This signal is emitted for any change in the properties + corresponding to its arguments, even if the other properties + referenced remain unchanged.

+ + + + + The new value of the CallState + property. + + + + + + The new value of the CallFlags + property. + + + + + + The new value of the CallStateReason + property. + + + + + + The new value of the CallStateDetails + property. + + + + + + +

If this property is True, all of the media streaming is done by some + mechanism outside the scope of Telepathy.

+ + +

A connection manager might be intended for a specialized hardware + device, which will take care of the audio streaming (e.g. + telepathy-yafono, which uses GSM hardware which does the actual + audio streaming for the call).

+ + +

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 Media.DRAFT interface, to communicate the necessary + information to a streaming implementation. Connection managers SHOULD + operate like this, if possible.

+ + +

Many connection managers (such as telepathy-gabble) only do the + call signalling, and expect the client to do the actual streaming + using something like + Farsight, to improve + latency and allow better UI integration.

+ + + + + + +

A set of flags representing the status of a remote contact in a + call.

+ +

It is protocol- and client-specific whether a particular contact + will ever have a particular flag set on them, and Telepathy clients + SHOULD NOT assume that a flag will ever be set.

+ + +

180 Ringing in SIP, and its equivalent in XMPP, are optional + informational messages, and implementations are not required + to send them. The same applies to the messages used to indicate + hold state.

+ + + + + +

The remote contact's client has told us that the contact has been + alerted about the call but has not responded.

+ + +

This is a flag per member, not a flag for the call as a whole, + because in Muji conference calls, you could invite someone and + have their state be "ringing" for a while.

+ + + + + + +

The call member has put this call on hold.

+ + +

This is a flag per member, not a flag for the call as a whole, + because in conference calls, any member could put the conference + on hold.

+ + + + + + + This contact has merged this call into a conference. Note that GSM + provides a notification when the remote party merges a call into a + conference, but not when it is split out again; thus, this flag can + only indicate that the call has been part of a conference at some + point. If a GSM connection manager receives a notification that a + call has been merged into a conference a second time, it SHOULD + represent this by clearing and immediately re-setting this flag on + the remote contact. + + + + + + A mapping from handles to their current state in the call. + + + + + + + + Emitted when the CallMembers property + changes in any way, either because contacts have been added to the + call, contacts have been removed from the call, or contacts' flags + have changed. + + + + + A map from members of the call to their new call member flags, + including at least the members who have been added to + CallMembers, and the members whose + flags have changed. + + + + + A list of members who have left the call, i.e. keys to be removed + from CallMembers. + + + + + + +

A mapping from the remote contacts that are part of this call to flags + describing their status. This mapping never has the local user's handle + as a key.

+ +

When the call ends, this property should be an empty list, + and notified with + CallMembersChanged

+ +

If the Call implements + Group and the Group members are + channel-specific handles, then this call SHOULD also use + channel-specific handles.

+ +

Anonymous members are exposed as channel-specific handles + with no owner.

+ + + + + +

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 the empty string, in particular, on CMs with + hardware streaming.

+ + + When implementing a voip gateway one wants the outgoing leg of the + gatewayed to have the same transport as the incoming leg. This + property allows the gateway to request a Call with the right + transport from the CM. + + + + + + +

If set to True in a channel request that will create a new channel, + the connection manager should immediately attempt to establish an + audio stream to the remote contact, making it unnecessary for the + client to call AddContent.

+ +

If this property, or InitialVideo, is passed to EnsureChannel + (as opposed to CreateChannel), the connection manager SHOULD ignore + these properties when checking whether it can return an existing + channel as suitable; these properties only become significant when + the connection manager has decided to create a new channel.

+ +

If True on a requested channel, this indicates that the audio + stream has already been requested and the client does not need to + call RequestStreams, although it MAY still do so.

+ +

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 + Contents).

+ +

The name of this new content can be decided by using the + InitialAudioName property.

+ +

Connection managers that support the ContactCapabilities + interface SHOULD represent the capabilities of receiving audio + and/or video calls by including a channel class in + a contact's capabilities with ChannelType = Call + in the fixed properties dictionary, and InitialAudio and/or + InitialVideo in the allowed properties list. Clients wishing to + discover whether a particular contact is likely to be able to + receive audio and/or video calls SHOULD use this information.

+ + +

Not all clients support video calls, and it would also be + possible (although unlikely) to have a client which could only + stream video, not audio.

+ + +

Clients that are willing to receive audio and/or video calls + SHOULD include the following among their channel classes if + calling UpdateCapabilities + (clients of a ChannelDispatcher + SHOULD instead arrange for the ChannelDispatcher to do this, + by including the filters in their HandlerChannelFilter + properties):

+ +
    +
  • { ChannelType = Call }
    • +
  • { ChannelType = Call, InitialAudio = True } + if receiving calls with audio is supported
    • +
  • { ChannelType = Call, InitialVideo = True } + if receiving calls with video is supported
    • +
+ + +

Connection managers for protocols with capability discovery, + like XMPP, need this information to advertise the appropriate + capabilities for their protocol.

+ + + + + + +

The same as InitialAudio, but for + a video stream. This property is immutable (cannot change).

+ +

In particular, note that if this property is False, this does not + imply that an active video stream has not been added, only that no + video stream was active at the time the channel appeared.

+ +

This property is the correct way to discover whether connection + managers, contacts etc. support video calls; it appears in + capabilities structures in the same way as InitialAudio.

+ + + + + + +

If InitialAudio is set to + True, then this property will name the intial audio content + with the value of this property.

+ + +

Content names are meant to be significant, but if no name + can be given to initial audio content, then its name cannot + be meaningful or even localized.

+ + +

If this property is empty or missing from the channel + request and InitialAudio is True, then the CM must come up + with a sensible for the content, such as "audio".

+ +

If the protocol has no concept of stream names then this + property will not show up in the allowed properties list of + the Requestable Channel Classes for call channels.

+ + + + + + +

The same as + InitialAudioName, but for a + video stream created by setting + InitialVideo to True. This + property is immutable and so cannot change.

+ + + + + +

If True, a stream of a different content type can be added + after the Channel has been requested

+ +

If this property is missing, clients SHOULD assume that it is False, + and thus that the channel's streams cannot be changed once the call + has started.

+ +

If this property isn't present in the "allowed" set in any of the + Call entries contact capabilities, then user interfaces MAY choose to + show a separate "call" option for each class of call.

+ + +

For example, once an audio-only Google Talk call has started, + it is not possible to add a video stream; both audio and video + 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 + video once the call has started for contacts without this flag. +

+ + + + + + +

This client supports audio calls.

+ + + + + +

This client supports video calls.

+ + + + + +

The client can implement streaming for streams whose Transport + property is Stream_Transport_Type_GTalk_P2P.

+ + + + + +

The client can implement streaming for streams whose Transport + property is Stream_Transport_Type_ICE.

+ + + + + +

The client can implement streaming for streams whose Transport + property is Stream_Transport_Type_WLM_2009.

+ + + + + +

The client can implement streaming for streams whose Transport + property is Stream_Transport_Type_SHM.

+ + + + + +

The client supports media streaming with H264 (etc.).

+ +

This handler capability token is a one of a family + of similar tokens: for any other audio or video codec whose MIME + type is audio/subtype or video/subtype, a handler + capability token of this form may exist (the subtype MUST appear + in lower case in this context). Clients MAY support more + codecs than they explicitly advertise support for; clients SHOULD + explicitly advertise support for their preferred codec(s), and + for codecs like H264 that are, in practice, significant in codec + negotiation.

+ + +

For instance, the XMPP capability used by the Google Video + Chat web client to determine whether a client is compatible + with it requires support for H264 video, so an XMPP + connection manager that supports this version of Jingle should + not advertise the Google Video Chat capability unless there + is at least one installed client that declares that it supports + video/h264 on Call channels.

+ + +

For example, a client could advertise support for audio and video + calls using Speex, Theora and H264 by having five handler capability + tokens in its Capabilities + property:

+ +
    +
  • org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio
    • +
  • org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex
    • +
  • org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video
    • +
  • org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora
    • +
  • org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264
    • +
+ +

Clients MAY have media signalling abilities without explicitly + supporting any particular codec, and connection managers SHOULD + support this usage.

+ + +

This is necessary to support gatewaying between two Telepathy + connections, in which case the available codecs might not be + known to the gatewaying process.

+ + + + + + + diff --git a/spec/Makefile.am b/spec/Makefile.am new file mode 100644 index 0000000..f0d43af --- /dev/null +++ b/spec/Makefile.am @@ -0,0 +1,9 @@ +EXTRA_DIST = \ + Call_Content_Codec_Offer.xml \ + Call_Content_Interface_Media.xml \ + Call_Content_Interface_Mute.xml \ + Call_Content.xml \ + Call_Stream_Endpoint.xml \ + Call_Stream_Interface_Media.xml \ + Call_Stream.xml \ + Channel_Type_Call.xml -- cgit v1.2.3