Update spec/ to current telepathy-spec HEAD

20071113140503-53eee-178e466d1831fdfd00e9d5a34b0e50ad4e4387cc.gz

1 files changed, 120 insertions, 30 deletions

diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml
index 773b5081e..428e76a13 100644
--- a/spec/Channel_Type_Tubes.xml
+++ b/spec/Channel_Type_Tubes.xml
@@ -18,7 +18,7 @@ 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.Tubes" tp:name-const="CHANNEL_TYPE_TUBES">
+  <interface name="org.freedesktop.Telepathy.Channel.Type.Tubes">
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>A "tube" is a mechanism for arbitrary data transfer. Two types of
@@ -37,7 +37,83 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
          Socket_Address_Type and the v is dependent on the type of address.</p>
     </tp:docstring>
 
-    <tp:enum name="Tube_Type">
+    <tp:simple-type name="Tube_ID" type="u">
+      <tp:docstring>An identifier for a tube. These are local to a Tubes
+        channel, and may not be assumed to be the same as the other
+        participants' idea of the tube identifier.</tp:docstring>
+    </tp:simple-type>
+
+    <tp:struct name="Tube_Info" array-name="Tube_Info_List">
+      <tp:docstring>A struct (tube ID, initiator handle, tube type,
+        service name, parameters, state) representing a tube, as returned
+        by ListTubes on the Tubes channel type.</tp:docstring>
+      <tp:member type="u" name="Tube_ID"/>
+      <tp:member type="u" tp:type="Contact_Handle" name="Initiator"/>
+      <tp:member type="u" tp:type="Tube_Type" name="Type"/>
+      <tp:member type="s" name="Service"/>
+      <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/>
+      <tp:member type="u" tp:type="Tube_State" name="State"/>
+    </tp:struct>
+
+    <tp:struct name="DBus_Tube_Member" array-name="DBus_Tube_Member_List">
+      <tp:docstring>A struct (handle, unique name) representing a participant
+        in a D-Bus tube, as returned by GetDBusNames on the Tubes channel
+        type, and as seen in the DBusNamesChanged signal.</tp:docstring>
+      <tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
+      <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"/>
+    </tp:struct>
+
+    <tp:struct name="Socket_Address_IPv4">
+      <tp:docstring>An IPv4 address and port.</tp:docstring>
+      <tp:member type="s" name="Address">
+        <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal
+          numbers, each between 0 and 255 inclusive, e.g.
+          "192.168.0.1".</tp:docstring>
+      </tp:member>
+      <tp:member type="q" name="Port">
+        <tp:docstring>The TCP or UDP port number.</tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:struct name="Socket_Address_IPv6">
+      <tp:docstring>An IPv6 address and port.</tp:docstring>
+      <tp:member type="s" name="Address">
+        <tp:docstring>An IPv6 address literal as specified by RFC2373
+          section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring>
+      </tp:member>
+      <tp:member type="q" name="Port">
+        <tp:docstring>The TCP or UDP port number.</tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:struct name="Socket_Netmask_IPv4">
+      <tp:docstring>An IPv4 network or subnet.</tp:docstring>
+      <tp:member type="s" name="Address">
+        <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal
+          numbers, each between 0 and 255 inclusive, e.g.
+          "192.168.0.1".</tp:docstring>
+      </tp:member>
+      <tp:member type="y" name="Prefix_Length">
+        <tp:docstring>The number of leading bits of the address that must
+          match, for this netmask to be considered to match an
+          address.</tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:struct name="Socket_Netmask_IPv6">
+      <tp:docstring>An IPv6 network or subnet.</tp:docstring>
+      <tp:member type="s" name="Address">
+        <tp:docstring>An IPv6 address literal as specified by RFC2373
+          section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring>
+      </tp:member>
+      <tp:member type="y" name="Prefix_Length">
+        <tp:docstring>The number of leading bits of the address that must
+          match, for this netmask to be considered to match an
+          address.</tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:enum name="Tube_Type" type="u">
       <tp:enumvalue suffix="DBus" value="0">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>An ordered reliable transport, for transporting D-Bus
@@ -86,7 +162,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:enumvalue>
     </tp:enum>
 
-    <tp:enum name="Tube_State">
+    <tp:enum name="Tube_State" type="u">
       <tp:enumvalue suffix="Local_Pending" value="0">
         <tp:docstring>
           The tube is waiting to be accepted/closed locally.
@@ -104,7 +180,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:enumvalue>
     </tp:enum>
 
-    <tp:enum name="Socket_Address_Type">
+    <tp:enum name="Socket_Address_Type" type="u">
       <tp:enumvalue suffix="Unix" value="0">
         <tp:docstring>
           A Unix socket. The variant contains a byte-array, signature 'ay',
@@ -122,7 +198,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
       <tp:enumvalue suffix="IPv4" value="2">
         <tp:docstring>
-          An IPv4 socket. The variant contains a struct with signature (sq)
+          An IPv4 socket. The variant contains a Socket_Address_IPv4,
+          i.e. a structure with signature (sq)
           in which the string is an IPv4 dotted-quad address literal
           (and must not be a DNS name), while the 16-bit unsigned integer is
           the port number.
@@ -131,7 +208,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
       <tp:enumvalue suffix="IPv6" value="3">
         <tp:docstring>
-          An IPv6 socket. The variant contains a struct with signature (sq)
+          An IPv6 socket. The variant contains a Socket_Address_IPv6,
+          i.e. a structure with signature (sq)
           in which the string is an IPv6 address literal as specified in
           RFC2373 (and must not be a DNS name), while the 16-bit unsigned
           integer is the port number.
@@ -140,7 +218,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
     </tp:enum>
 
-    <tp:enum name="Socket_Access_Control">
+    <tp:enum name="Socket_Access_Control" type="u">
       <tp:enumvalue suffix="Localhost" value="0">
         <tp:docstring>
           The IP or Unix socket can be accessed by any local user (e.g.
@@ -152,16 +230,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <tp:enumvalue suffix="Port" value="1">
         <tp:docstring>
           May only be used on IP sockets. The associated variant must contain
-          a struct with signature (sq) containing the string form of an
-          IP address of the appropriate version, and a port number.
-          The socket can only be accessed if the connecting process has that
-          address and port number; all other connections will be rejected.
+          a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
+          containing the string form of an IP address of the appropriate
+          version, and a port number. The socket can only be accessed if the
+          connecting process has that address and port number; all other
+          connections will be rejected.
         </tp:docstring>
       </tp:enumvalue>
       <tp:enumvalue suffix="Netmask" value="2">
         <tp:docstring>
           May only be used on IP sockets. The associated variant must contain
-          a struct with signature (sy) containing the string form of an
+          a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with
+          signature (sy), containing the string form of an
           IP address of the appropriate version, and a prefix length "n".
           The socket can only be accessed if the first n bits of the
           connecting address match the first n bits of the given address.
@@ -185,10 +265,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       </tp:enumvalue>
     </tp:enum>
 
+    <tp:mapping name="Supported_Socket_Map">
+      <tp:docstring>The supported socket address and access-control types
+        for tubes. See GetAvailableStreamTubeTypes.</tp:docstring>
+      <tp:member name="Address_Type" type="u" tp:type="Socket_Address_Type"/>
+      <tp:member name="Access_Control" type="au"
+        tp:type="Socket_Access_Control[]"/>
+    </tp:mapping>
+
     <method name="GetAvailableStreamTubeTypes">
       <tp:docstring>List the available address types and access-control types
         for stream tubes.</tp:docstring>
-      <arg direction="out" type="a{uau}">
+      <arg direction="out" type="a{uau}" tp:type="Supported_Socket_Map">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>A mapping from address types (members of Socket_Address_Type) to
           arrays of access-control type (members of Socket_Access_Control)
@@ -224,7 +312,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
     </method>
 
     <method name="ListTubes">
-      <arg direction="out" type="a(uuusa{sv}u)">
+      <arg direction="out" type="a(uuusa{sv}u)" tp:type="Tube_Info[]">
         <tp:docstring>
          Return an array of tuples, each representing a tube, with the
          following members:
@@ -253,7 +341,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           com.example.ServiceName.
         </tp:docstring>
       </arg>
-      <arg direction="in" name="parameters" type="a{sv}">
+      <arg direction="in" name="parameters" type="a{sv}"
+        tp:type="String_Variant_Map">
         <tp:docstring>
           A dictionary of properties for the new tube; the allowable keys,
           types and values are defined by the service. Connection managers
@@ -296,7 +385,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           "rsync" or "daap".
         </tp:docstring>
       </arg>
-      <arg direction="in" name="parameters" type="a{sv}">
+      <arg direction="in" name="parameters" type="a{sv}"
+        tp:type="String_Variant_Map">
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>A dictionary of properties for the new tube; the allowable keys,
           types and values are defined by the service. Connection managers
@@ -357,7 +447,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <tp:docstring>
         Emitted when a tube is created.
       </tp:docstring>
-      <arg name="id" type="u">
+      <arg name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the new tube.
         </tp:docstring>
@@ -377,7 +467,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           A string representing the service that will be used over the tube.
         </tp:docstring>
       </arg>
-      <arg name="parameters" type="a{sv}">
+      <arg name="parameters" type="a{sv}" tp:type="String_Variant_Map">
         <tp:docstring>
           The new tube's properties.
         </tp:docstring>
@@ -396,7 +486,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         the "local pending" state until the TubeStateChanged signal is
         emitted.
       </tp:docstring>
-      <arg direction="in" name="id" type="u">
+      <arg direction="in" name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the tube to accept.
         </tp:docstring>
@@ -424,7 +514,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         the "local pending" state until the TubeStateChanged signal is
         emitted.
       </tp:docstring>
-      <arg direction="in" name="id" type="u">
+      <arg direction="in" name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the tube to accept.
         </tp:docstring>
@@ -473,7 +563,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <tp:docstring>
         Emitted when the state of a tube changes.
       </tp:docstring>
-      <arg name="id" type="u">
+      <arg name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the tube that changed state.
         </tp:docstring>
@@ -489,7 +579,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <tp:docstring>
         Close a tube.
       </tp:docstring>
-      <arg direction="in" name="id" type="u">
+      <arg direction="in" name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the tube to close.
         </tp:docstring>
@@ -504,7 +594,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
        Emitted when a tube has been closed. The ID of a closed tube is no
        longer valid. The ID may later be reused for a new tube.
       </tp:docstring>
-      <arg name="id" type="u">
+      <arg name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the tube that was closed.
         </tp:docstring>
@@ -516,7 +606,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         For a D-Bus tube, return a string describing the address of the
         private bus.
       </tp:docstring>
-      <arg direction="in" name="id" type="u">
+      <arg direction="in" name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the tube to get an address for.
         </tp:docstring>
@@ -545,12 +635,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping
         between contact handles and their unique bus names on this tube.
       </tp:docstring>
-      <arg direction="in" name="id" type="u">
+      <arg direction="in" name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the tube to get names for.
         </tp:docstring>
       </arg>
-      <arg direction="out" type="a(us)">
+      <arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]">
         <tp:docstring>
           An array of structures, each containing a contact handle and a D-Bus
           bus name.
@@ -575,12 +665,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a
         participant opens or closes the tube.
       </tp:docstring>
-      <arg name="id" type="u">
+      <arg name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the tube whose names have changed.
         </tp:docstring>
       </arg>
-      <arg name="added" type="a(us)">
+      <arg name="added" type="a(us)" tp:type="DBus_Tube_Member[]">
         <tp:docstring>
           Array of handles and D-Bus names of new participants.
         </tp:docstring>
@@ -597,7 +687,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         For a stream tube, obtain the address of the socket used to
         communicate over this tube.
       </tp:docstring>
-      <arg direction="in" name="id" type="u">
+      <arg direction="in" name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the stream tube to get the socket for.
         </tp:docstring>
@@ -633,7 +723,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         Emitted on a stream tube when a participant opens a new connection
         to its socket.
       </tp:docstring>
-      <arg name="id" type="u">
+      <arg name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the tube
         </tp:docstring>