path: root/spec/Channel.xml

<?xml version="1.0" ?>
<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright © 2011 Intel Corp.</tp:copyright>
  <tp:license xmlns="http://www.w3.org/1999/xhtml">
    <p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.</p>

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

<p>You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
  </tp:license>
  <interface name="org.freedesktop.ytstenut.xpmn.Channel">
    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>

    <tp:simple-type name="Message_Body" type="s" array-name="Message_Body">
      <tp:docstring>
        The UTF-8 encoded XML body of a Ytstenut message.
      </tp:docstring>
    </tp:simple-type>

    <tp:mapping name="Message_Attrs" array-name="Message_Attrs_List">
      <tp:member type="s" name="Name">
        <tp:docstring>The name of the attribute.</tp:docstring>
      </tp:member>
      <tp:member type="s" name="Value">
        <tp:docstring>The value of the attribute.</tp:docstring>
      </tp:member>
      <tp:docstring>
        A list of attributes present on a Ytstenut message.
      </tp:docstring>
    </tp:mapping>

    <property name="RequestType" access="read" tp:type="Request_Type"
      tp:name-for-bindings="Request_Type" type="u"
      tp:immutable='yes' tp:requestable='yes'>
      <tp:docstring>
        The &lt;iq&gt; type of the request message.
      </tp:docstring>
    </property>

    <property name="RequestAttributes" access="read" tp:type="Message_Attrs"
      tp:name-for-bindings="Request_Attributes" type="a{ss}"
      tp:immutable='yes' tp:requestable='yes'>
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The attributes present on the Ytstenut request message.</p>
        <p>The exact attributes specified depend on the type and intent of
          the Ytstenut message being sent. Some examples are the
          <tt>capability</tt>, <tt>activity</tt> or <tt>time</tt> attributes.
          For more details see the Ytstenut specification.</p>
      </tp:docstring>
    </property>

    <property name="RequestBody" access="read" tp:type="Message_Body"
      tp:name-for-bindings="Request_Body" type="s"
      tp:immutable='yes' tp:requestable='yes'>
      <tp:docstring>
        The UTF-8 encoded XML body of the Ytstenut request message. The
          top level element must have the name 'message' and be of the namespace
          'urn:ytstenut:message'. Any attributes in the
          <tp:member-ref>RequestAttributes</tp:member-ref> property will
          override any attributes of the same names on the top level element. If
          an empty string is used as the
          <tp:member-ref>RequestBody</tp:member-ref> then a default body will be
          used instead.
      </tp:docstring>
    </property>

    <property name="TargetService" access="read"
      tp:name-for-bindings="Target_Service" type="s"
      tp:immutable='yes' tp:requestable='yes'>
      <tp:docstring>
        The name of the target Ytstenut service that this channel is targetted
        at.
      </tp:docstring>
    </property>

    <property name="InitiatorService" access="read"
      tp:name-for-bindings="Initiator_Service" type="s"
      tp:immutable='yes' tp:requestable='yes'>
      <tp:docstring>
        The name of the Ytstenut service which initiated this channel.
      </tp:docstring>
    </property>

    <signal name="Replied" tp:name-for-bindings="Replied">
      <arg name="Attributes" type="a{ss}" tp:type="Message_Attrs">
        <tp:docstring>
          The attributes present on the Ytstenut result message.
        </tp:docstring>
      </arg>
      <arg name="Body" type="s" tp:type="Message_Body">
        <tp:docstring>
          The UTF-8 encoded XML body of the Ytstenut result message, including
          the attributes in the 'Attributes' argument.
        </tp:docstring>
      </arg>
      <tp:docstring>
        This signal is emitted when a &lt;iq type='result'&gt; is received in
        response to a request sent on this channel. This signal is only
        emitted on the initiating side of the channel.
      </tp:docstring>
    </signal>

    <signal name="Failed" tp:name-for-bindings="Failed">
      <arg name="ErrorType" tp:type="Error_Type"
        tp:name-for-bindings="Error_Type" type="u">
        <tp:docstring>
          The type of error which defines the appropriate action to take.
        </tp:docstring>
      </arg>
      <arg name="StanzaErrorName" type="s"
        tp:name-for-bindings="Stanza_Error_Name">
        <tp:docstring>
          The name of the specific error.
        </tp:docstring>
      </arg>
      <arg name="YtstenutErrorName" type="s"
        tp:name-for-bindings="Ytstenut_Error_Name">
        <tp:docstring>
          A more detailed Ytstenut error name.
        </tp:docstring>
      </arg>
      <arg name="Text" type="s" tp:name-for-bindings="Text">
        <tp:docstring>
          Textual details of the error.
        </tp:docstring>
      </arg>
      <tp:docstring>
        This signal is emitted when a error is received. This signal is only
        emitted on the initiating side of the channel.
      </tp:docstring>
    </signal>

    <method name="Request" tp:name-for-bindings="Request">
      <tp:docstring>
        Send the Ytstenut request (represented by the
        <tp:member-ref>RequestType</tp:member-ref>,
        <tp:member-ref>RequestAttributes</tp:member-ref> and
        <tp:member-ref>RequestBody</tp:member-ref>) properties to the other
        side of this channel.
      </tp:docstring>
    </method>

    <method name="Reply" tp:name-for-bindings="Reply">
      <arg direction="in" name="Attributes" type="a{ss}"
        tp:type="Message_Attrs">
        <tp:docstring>
          The attributes to set on the Ytstenut reply message.
        </tp:docstring>
      </arg>
      <arg direction="in" name="Body" tp:type="Message_Body" type="s">
        <tp:docstring>
          Optional UTF-8 encoded XML body of the Ytstenut reply
          message. The top level element must have the name 'message'
          and be of the namespace 'urn:ytstenut:message'. Any
          attributes in the Attributes argument will override any
          attributes of the same names on the top level element. If an
          empty string is used as the 'Body' then a default body will
          be created instead.
        </tp:docstring>
      </arg>
      <tp:docstring>
        Send an &lt;iq&gt; result to the Ytstenut request.
      </tp:docstring>
    </method>

    <method name="Fail" tp:name-for-bindings="Fail">
      <arg name="ErrorType" tp:type="Error_Type" direction="in"
        tp:name-for-bindings="Error_Type" type="u">
        <tp:docstring>
          The type of error which defines the appropriate action to take.
        </tp:docstring>
      </arg>
      <arg name="StanzaErrorName" type="s" direction="in"
        tp:name-for-bindings="Stanza_Error_Name">
        <tp:docstring>
          The name of the specific error.
        </tp:docstring>
      </arg>
      <arg name="YtstenutErrorName" type="s" direction="in"
        tp:name-for-bindings="Ytstenut_Error_Name">
        <tp:docstring>
          A more detailed Ytstenut error name.
        </tp:docstring>
      </arg>
      <arg name="Text" type="s" tp:name-for-bindings="Text" direction="in">
        <tp:docstring>
          Textual details of the error.
        </tp:docstring>
      </arg>
    </method>

    <tp:enum name="Request_Type" type="u">
      <tp:enumvalue suffix="Get" value="1">
        <tp:docstring>The iq request is of type 'get'</tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Set" value="2">
        <tp:docstring>The iq request is of type 'set'</tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:enum name="Reply_Type" type="u">
      <tp:enumvalue suffix="Result" value="1">
        <tp:docstring>The iq reply is of type 'result'</tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Error" value="2">
        <tp:docstring>The iq reply is of type 'error'</tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:enum name="Error_Type" type="u">
      <tp:enumvalue suffix="Cancel" value="1">
        <tp:docstring>Do not retry (the error is unrecoverable)</tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Continue" value="2">
        <tp:docstring>Proceed (the condition was only a warning)</tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Modify" value="3">
        <tp:docstring>Retry after changing the data sent</tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Auth" value="4">
        <tp:docstring>Retry after providing credentials</tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue suffix="Wait" value="5">
        <tp:docstring>Retry after waiting (the error is temporary)</tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>This channel represents Ytstenut commands being sent to or from a
      remote service.</p>
      <p>To send a command to a remote service, request a channel of
      this type, specifying TargetHandleType as Contact, the TargetID
      of the target contact (which may be the local user's own JID),
      plus the <tp:member-ref>InitiatorService</tp:member-ref>,
      <tp:member-ref>TargetService</tp:member-ref>,
      <tp:member-ref>RequestType</tp:member-ref>,
      <tp:member-ref>RequestAttributes</tp:member-ref>,
      and (optionally) <tp:member-ref>RequestBody</tp:member-ref> properties.
      Connect to the <tp:member-ref>Replied</tp:member-ref> and
      <tp:member-ref>Failed</tp:member-ref> signals on the resulting channel,
      and then call <tp:member-ref>Request</tp:member-ref>; one of the two
      signals will be emitted when the target replies, after which point the
      channel may be closed.</p>
      <p>Services which handle incoming commands should have an entry in
      HandlerChannelFilter as follows:</p>
      <pre>
      { ChannelType: ...,
        TargetHandleType: Contact,
        TargetService: com.example.myservice
      }</pre>
      <p>Upon being handed an incoming channel, the handler should process the
      request and call one of <tp:member-ref>Reply</tp:member-ref> or
      <tp:member-ref>Fail</tp:member-ref>, after which point it may close the
      channel.</p>
    </tp:docstring>

  </interface>
</node>