[Telepathy-commits] [telepathy-spec/master] Tubes: document whether properties may, must, or must not be requested in CreateChannel.

[Alban Crequy]

20080807153111-a41c0-5d297300c873b71b36e8e61800e52f35c7f5dc46.gz
---
 spec/Channel_Interface_Tube.xml  |   15 ++++++++++++++-
 spec/Channel_Type_DBusTube.xml   |   16 +++-------------
 spec/Channel_Type_StreamTube.xml |   26 +++++++-------------------
 3 files changed, 24 insertions(+), 33 deletions(-)

diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index 93e87db..415b805 100644
--- a/spec/Channel_Interface_Tube.xml
+++ b/spec/Channel_Interface_Tube.xml
@@ -35,21 +35,34 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
     <property name="Initiator" type="u" tp:type="Contact_Handle" access="read">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Initiator handle.</p>
+        <p>When requesting a channel with 
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.DRAFT.CreateChannel</tp:dbus-ref>,
+          this property MUST NOT be included in the request.</p>
       </tp:docstring>
     </property>
 
     <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
-              access="read">
+              access="readwrite">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Each tube has a dictionary of arbitrary parameters. Parameters are
           commonly used for bootstrap information such as usernames and
           passwords.</p>
+        <p>When requesting a channel with 
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.DRAFT.CreateChannel</tp:dbus-ref>,
+          this property MAY be included in the request. If it is not included in
+          the request, the connection manager MUST consider the property to be
+          empty. This property MAY be changed after the channel creation when
+          the tube is in the state Not_Offered. If the tube is in another
+          state, changing this property MUST fail without side effect.</p>
       </tp:docstring>
     </property>
 
     <property name="Status" type="u" tp:type="Tube_Channel_State" access="read">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Status of the tube in this channel.</p>
+        <p>When requesting a channel with 
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.DRAFT.CreateChannel</tp:dbus-ref>,
+          this property MUST NOT be included in the request.</p>
       </tp:docstring>
     </property>
 
diff --git a/spec/Channel_Type_DBusTube.xml b/spec/Channel_Type_DBusTube.xml
index c94af2a..cf17437 100644
--- a/spec/Channel_Type_DBusTube.xml
+++ b/spec/Channel_Type_DBusTube.xml
@@ -51,19 +51,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         and each participant receives all messages sent by the other
         participant.</p>
 
-      <p>When creating a channel of this type, some properties are
-        mandatory:</p>
-
-        <ul>
-          <li>service</li>
-        </ul>
-
-      <p>Some properties are optional:</p>
-
-        <ul>
-          <li>parameters</li>
-        </ul>
-
     </tp:docstring>
 
     <tp:struct name="DBus_Tube_Member" array-name="DBus_Tube_Member_List">
@@ -196,6 +183,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         <p>A string representing the service name that will be used over the
           tube. It should be a well-known D-Bus service name, of the form
           com.example.ServiceName.</p>
+        <p>When requesting a channel with 
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.DRAFT.CreateChannel</tp:dbus-ref>,
+          this property MUST be included in the request.</p>
       </tp:docstring>
     </property>
 
diff --git a/spec/Channel_Type_StreamTube.xml b/spec/Channel_Type_StreamTube.xml
index 06f2e16..2cc8a2d 100644
--- a/spec/Channel_Type_StreamTube.xml
+++ b/spec/Channel_Type_StreamTube.xml
@@ -30,25 +30,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         connection to its local socket. Both sides can then use this pair
         of sockets to communicate together.</p>
 
-      <p>When creating a channel of this type, some properties are
-        mandatory:</p>
-
-        <ul>
-          <li>service: A string representing the service name that will be used
-          over the tube. It should be a well-known TCP service name as defined
-          by <a href="http://www.iana.org/assignments/port-numbers">
-            http://www.iana.org/assignments/port-numbers</a> or
-          <a href="http://www.dns-sd.org/ServiceTypes.html">
-            http://www.dns-sd.org/ServiceTypes.html</a>, for instance
-          "rsync" or "daap".</li>
-        </ul>
-
-      <p>Some properties are optional:</p>
-
-        <ul>
-          <li>parameters</li>
-        </ul>
-
     </tp:docstring>
 
     <tp:struct name="Socket_Address_IPv4">
@@ -345,6 +326,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           <a href="http://www.dns-sd.org/ServiceTypes.html">
             http://www.dns-sd.org/ServiceTypes.html</a>, for instance
           "rsync" or "daap".</p>
+        <p>When requesting a channel with 
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.DRAFT.CreateChannel</tp:dbus-ref>,
+          this property MUST be included in the request.</p>
       </tp:docstring>
     </property>
 
@@ -372,6 +356,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         <p>If stream tubes are not supported, this will be an empty
           dictionary.</p>
 
+        <p>When requesting a channel with 
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.DRAFT.CreateChannel</tp:dbus-ref>,
+          this property MUST NOT be included in the request.</p>
+
       </tp:docstring>
     </property>
 
-- 
1.5.6.5