<?xml version="1.0" ?>
<node name="/Account_Interface_Conditions" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:copyright>Copyright (C) 2008 Nokia Corporation</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="com.nokia.Account.Interface.Conditions">
    <tp:requires interface="org.freedesktop.Telepathy.Account"/>
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>The Conditions interface specifies under what conditions an account
      can be put online. When the conditions are met and the
      ConnectAutomatically property on the account is set to True, then the
      account will automatically try to connect. On the other hand, if the
      conditions are not met, the account won't attempt to connect, not even if
      requested so.</p>

      <tp:rationale>
      <p>The main goal is to bind accounts to connectivity: most TCP and UDP
      based protocols require a network route to be present, while link-local
      does not; some protocol might be specifically designed to work only over
      bluetooth, in which case we don't want to attempt a connection if
      bluetooth is not available. Then, some accounts might work only in certain
      VPNs.</p>

      <p>There is also the case of user preferences: one might want to activate
      a certain account only when he is at home (in that case, he could set a
      rule on the network ESSID) or when he is not at work (this requires the
      possibility of negating rules).</p>

      <p>The proposed format of a rule is (name, value), where name is a string
      (which is typically a connectivity parameter, such as "ip-address",
       "vpn-name", "essid", maybe prefixed with some namespacing convention)
      and value is the value the parameter must assume for the rule to be met.
      The value, it will be specified as a string, but we want to be
      able to specify multiple alternatives (for instance a rule might be
      "connect if ESSID is HOME or WORK"), as well as negative matches. The
      proposed syntax is simple yet expressive enough.</p>

      </tp:rationale>

      <p>Conditions consists of a list of rules, which take the form of a
      struct <code>(name, value)</code>, where:</p>
      <ul>
        <li><code>name</code> is a string which names the rule</li>
        <li><code>value</code> is the value</li>
      </ul>
    </tp:docstring>

    <property name="Condition" type="a{ss}" tp:type="String_String_Map"
      access="readwrite">
      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
        <p>The condition is a list of rules, consisting of a name and of a value,
        both strings.
        The syntax for the value is:</p>
        <code>
        value ::= [logic] (":" singlevalue | "[" listvalue)<br />
        logic ::= ("!" | &lt;possibly other operators&gt;)<br />
        singlevalue ::= &lt;possibly any ASCII string&gt;<br />
        listvalue ::= separator list<br />
        separator ::= &lt;any non-blank ASCII character&gt;<br />
        list ::= singlevaluenonsep (separator singlevaluenonsep)*<br />
        singlevaluenonsep ::= &lt;ASCII string not containing the separator character&gt;<br />
        </code>

        <p>Some examples of values:</p>
        <code>
        :my_essid_name<br />
        !:my_essid_name<br />
        [,my_essid_name,his_essid_name<br />
        ![,my_essid_name,his_essid_name<br />
        </code>

        <tp:rationale>
        <p>
        Questions:</p>
        <ul>
          <li>Should it be a(ss) or a{ss}?</li>
          <li>Should we specify namespacing rules for the name?</li>
          <li>Should we allow wildcards in the values?</li>
        </ul>
        </tp:rationale>
      </tp:docstring>
    </property>

  </interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
