update spec to 0.15.1

20070413025837-418b8-300ca0c310d71b3a89a07c7451dd7deefc5d9f3c.gz

8 files changed, 145 insertions, 30 deletions

diff --git a/lib/spec/Channel_Interface_DTMF.xml b/lib/spec/Channel_Interface_DTMF.xml
index 54f0803c9..e393ab1bc 100644
--- a/lib/spec/Channel_Interface_DTMF.xml
+++ b/lib/spec/Channel_Interface_DTMF.xml
@@ -19,39 +19,113 @@ License along with this library; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA</p>
   </tp:license>
   <interface name="org.freedesktop.Telepathy.Channel.Interface.DTMF">
-    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
-    <signal name="ReceivedDTMF">
-      <arg name="signal" type="u">
-        <tp:docstring>A numeric signal number</tp:docstring>
+    <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+    <method name="StartTone">
+      <arg direction="in" name="stream_id" type="u">
+        <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring>
       </arg>
-      <arg name="duration" type="u">
-        <tp:docstring>A numeric duration in milliseconds</tp:docstring>
+      <arg direction="in" name="event" type="u">
+        <tp:docstring>A numeric event code from the DTMF_Event enum.</tp:docstring>
       </arg>
       <tp:docstring>
-        Signals that this channel received a DTMF tone.
+        Start sending a DTMF tone on this stream. Where possible, the tone
+        will continue until StopTone is called. On certain protocols, it may
+        only be possible to send events with a predetermined length. In this
+        case, the implementation may emit a fixed-length tone, and the StopTone
+        method call should return NotAvailable.
       </tp:docstring>
-    </signal>
-    <method name="SendDTMF">
-      <arg direction="in" name="signal" type="u">
-        <tp:docstring>A numeric signal number</tp:docstring>
-      </arg>
-      <arg direction="in" name="duration" type="u">
-        <tp:docstring>A numeric duration in milliseconds</tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The given stream ID was invalid.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            The requested event is not available on this stream.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+    <method name="StopTone">
+      <arg direction="in" name="stream_id" type="u">
+        <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring>
       </arg>
       <tp:docstring>
-        Requests that a DTMF tone is sent.
+        Stop sending any DTMF tone which has been started using the StartTone
+        method. If there is no current tone, this method will do nothing.
       </tp:docstring>
       <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The given stream ID was invalid.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            Continuous tones are not supported by this stream.
+          </tp:docstring>
+        </tp:error>
       </tp:possible-errors>
     </method>
-    <tp:docstring>
-      An interface that gives a Channel the ability to send or receive DTMF
-    signalling tones. This usually only makes sense for channels transporting
-    audio.
+    <tp:enum name="DTMF_Event" type="u">
+      <tp:enumvalue suffix="Digit_0" value="0">
+        <tp:docstring>0</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_1" value="1">
+        <tp:docstring>1</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_2" value="2">
+        <tp:docstring>2</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_3" value="3">
+        <tp:docstring>3</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_4" value="4">
+        <tp:docstring>4</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_5" value="5">
+        <tp:docstring>5</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_6" value="6">
+        <tp:docstring>6</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_7" value="7">
+        <tp:docstring>7</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_8" value="8">
+        <tp:docstring>8</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Digit_9" value="9">
+        <tp:docstring>9</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Asterisk" value="10">
+        <tp:docstring>*</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Hash" value="11">
+        <tp:docstring>#</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Letter_A" value="12">
+        <tp:docstring>A</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Letter_B" value="13">
+        <tp:docstring>B</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Letter_C" value="14">
+        <tp:docstring>C</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Letter_D" value="15">
+        <tp:docstring>D</tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      An interface that gives a Channel the ability to send DTMF events over
+      audio streams which have been established using the StreamedMedia channel
+      type. The event codes used are in common with those defined in <a
+      href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are
+      listed in the DTMF_Event enumeration.
     </tp:docstring>
   </interface>
 </node>
diff --git a/lib/spec/Channel_Interface_Group.xml b/lib/spec/Channel_Interface_Group.xml
index 6582acbac..4b3f04fa6 100644
--- a/lib/spec/Channel_Interface_Group.xml
+++ b/lib/spec/Channel_Interface_Group.xml
@@ -185,6 +185,13 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA</p>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            This channel doesn't have the CHANNEL_SPECIFIC_HANDLES flag,
+            so handles in this channel are globally meaningful and calling
+            this method is not necessary
+          </tp:docstring>
+        </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
           <tp:docstring>
             One of the given handles is not a member
diff --git a/lib/spec/Channel_Type_Streamed_Media.xml b/lib/spec/Channel_Type_Streamed_Media.xml
index dcd5d36b7..a750b7ea5 100644
--- a/lib/spec/Channel_Type_Streamed_Media.xml
+++ b/lib/spec/Channel_Type_Streamed_Media.xml
@@ -22,12 +22,10 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA</p>
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
     <tp:enum name="Media_Stream_Type">
       <tp:enumvalue suffix="Audio" value="0">
-        An audio stream
-        <tp:docstring></tp:docstring>
+        <tp:docstring>An audio stream</tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Video" value="1">
-        A video stream
-        <tp:docstring></tp:docstring>
+        <tp:docstring>A video stream</tp:docstring>
       </tp:enumvalue>
     </tp:enum>
     <tp:enum name="Media_Stream_State">
diff --git a/lib/spec/Connection.xml b/lib/spec/Connection.xml
index c21a44b1d..f5c62115a 100644
--- a/lib/spec/Connection.xml
+++ b/lib/spec/Connection.xml
@@ -49,6 +49,9 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA</p>
       <tp:docstring>
         Get the optional interfaces supported by this connection.
       </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+      </tp:possible-errors>
     </method>
     <method name="GetProtocol">
       <arg direction="out" type="s">
diff --git a/lib/spec/Connection_Manager.xml b/lib/spec/Connection_Manager.xml
index e402b0f88..ee84ae970 100644
--- a/lib/spec/Connection_Manager.xml
+++ b/lib/spec/Connection_Manager.xml
@@ -196,6 +196,11 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA</p>
 
       <dt>s:fullname</dt><dd>The user's full name if the service requires this
         when authenticating or registering.</dd>
+
+      <dt>s:stun-server</dt><dd>The IP address or FQDN of a STUN server to use
+        for NAT traversal, without any ":port" suffix.</dd>
+      <dt>q:stun-port</dt><dd>The UDP port number on the stun-server to use for
+        STUN. Only significant if the stun-server is also supplied.</dd>
         </dl>
 
         <p>Every successful RequestConnection call will cause the emission of a
diff --git a/lib/spec/Media_Stream_Handler.xml b/lib/spec/Media_Stream_Handler.xml
index 1fad5c55f..8e8eaa846 100644
--- a/lib/spec/Media_Stream_Handler.xml
+++ b/lib/spec/Media_Stream_Handler.xml
@@ -92,8 +92,12 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA</p>
       </tp:docstring>
     </method>
     <tp:enum name="Media_Stream_Base_Proto">
-      <tp:enumvalue suffix="UDP" value="0"/>
-      <tp:enumvalue suffix="TCP" value="1"/>
+      <tp:enumvalue suffix="UDP" value="0">
+        <tp:docstring>UDP (User Datagram Protocol)</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="TCP" value="1">
+        <tp:docstring>TCP (Transmission Control Protocol)</tp:docstring>
+      </tp:enumvalue>
     </tp:enum>
     <method name="NewNativeCandidate">
       <arg direction="in" name="candidate_id" type="s">
@@ -221,6 +225,28 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA</p>
         the stream sends to the remote end.
       </tp:docstring>
     </signal>
+    <signal name="StartTelephonyEvent">
+      <arg name="event" type="u">
+        <tp:docstring>
+          A telephony event code as defined by RFC 4733.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Request that a telephony event (as defined by RFC 4733) is transmitted
+        over this stream until StopTelephonyEvent is called.
+      </tp:docstring>
+    </signal>
+    <signal name="StopTelephonyEvent">
+      <arg name="event" type="u">
+        <tp:docstring>
+          A telephony event code as defined by RFC 4733.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Request that any ongoing telephony events (as defined by RFC 4733)
+        being transmitted over this stream are stopped.
+      </tp:docstring>
+    </signal>
     <method name="StreamState">
       <arg direction="in" name="state" type="u"/>
       <tp:docstring>
diff --git a/lib/spec/all.xml b/lib/spec/all.xml
index 80377248a..8fefa8ae7 100644
--- a/lib/spec/all.xml
+++ b/lib/spec/all.xml
@@ -2,7 +2,7 @@
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
-<tp:version>0.15.0</tp:version>
+<tp:version>0.15.1</tp:version>
 
 <tp:copyright>Copyright (C) 2005, 2006, 2007 Collabora Limited</tp:copyright>
 <tp:copyright>Copyright (C) 2005, 2006, 2007 Nokia Corporation</tp:copyright>
@@ -41,6 +41,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA</p>
 <xi:include href="Channel_Type_Streamed_Media.xml"/>
 <xi:include href="Channel_Type_Room_List.xml"/>
 <xi:include href="Channel_Type_Text.xml"/>
+
 <xi:include href="Channel_Interface_Chat_State.xml"/>
 <xi:include href="Channel_Interface_DTMF.xml"/>
 <xi:include href="Channel_Interface_Group.xml"/>
diff --git a/lib/spec/spec-gen.am b/lib/spec/spec-gen.am
index e75335ca0..7b8ce05e7 100644
--- a/lib/spec/spec-gen.am
+++ b/lib/spec/spec-gen.am
@@ -1 +1,2 @@
+SPEC_INTERFACES = Connection_Manager Connection Connection_Interface_Aliasing Connection_Interface_Avatars Connection_Interface_Capabilities Connection_Interface_Contact_Info Connection_Interface_Forwarding Connection_Interface_Presence Connection_Interface_Privacy Connection_Interface_Renaming Channel Channel_Type_Contact_List Channel_Type_Contact_Search Channel_Type_Streamed_Media Channel_Type_Room_List Channel_Type_Text Channel_Interface_Chat_State Channel_Interface_DTMF Channel_Interface_Group Channel_Interface_Hold Channel_Interface_Password Channel_Interface_Transfer Channel_Interface_Media_Signalling Media_Session_Handler Media_Stream_Handler Properties_Interface
 SPEC_INTERFACE_XMLS = Connection_Manager.xml Connection.xml Connection_Interface_Aliasing.xml Connection_Interface_Avatars.xml Connection_Interface_Capabilities.xml Connection_Interface_Contact_Info.xml Connection_Interface_Forwarding.xml Connection_Interface_Presence.xml Connection_Interface_Privacy.xml Connection_Interface_Renaming.xml Channel.xml Channel_Type_Contact_List.xml Channel_Type_Contact_Search.xml Channel_Type_Streamed_Media.xml Channel_Type_Room_List.xml Channel_Type_Text.xml Channel_Interface_Chat_State.xml Channel_Interface_DTMF.xml Channel_Interface_Group.xml Channel_Interface_Hold.xml Channel_Interface_Password.xml Channel_Interface_Transfer.xml Channel_Interface_Media_Signalling.xml Media_Session_Handler.xml Media_Stream_Handler.xml Properties_Interface.xml