diff options
| -rw-r--r-- | doc/templates/interface.html | 22 | ||||
| -rw-r--r-- | spec/Channel_Type_Contact_Search.xml | 29 | ||||
| -rw-r--r-- | spec/Connection_Interface_Contact_Info.xml | 30 | ||||
| -rw-r--r-- | tools/specparser.py | 6 |
4 files changed, 69 insertions, 18 deletions
diff --git a/doc/templates/interface.html b/doc/templates/interface.html index 53b27b0c..26650b41 100644 --- a/doc/templates/interface.html +++ b/doc/templates/interface.html @@ -337,18 +337,32 @@ </div> #end if - #if $property.requestable: + #if $property.sometimes_requestable: + <div class="annotation requestable">Depending on the protocol, this + property may be <strong>requestable</strong>, which means that it may be + allowed in the properties hash of a channel request such as in the + <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.CreateChannel">CreateChannel</a> + and + <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.EnsureChannel">EnsureChannel</a> + methods + on <a href="Connection_Interface_Requests.html">Requests</a> + and <a href="Channel_Dispatcher.html">ChannelDispatcher</a>. + If supported on this protocol, the property should appear in either the + Fixed_Properties or Allowed_Properties of + a <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.RequestableChannelClasses">RequestableChannelClass</a> + advertised by the CM.</div> + #elif $property.requestable: <div class="annotation requestable">This property - is <strong>requestable</strong> which means that it is allowed + is <strong>requestable</strong>, which means that it is allowed in the properties hash of a channel request such as in the - the <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.CreateChannel">CreateChannel</a> + <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.CreateChannel">CreateChannel</a> and <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.EnsureChannel">EnsureChannel</a> methods on <a href="Connection_Interface_Requests.html">Requests</a> and <a href="Channel_Dispatcher.html">ChannelDispatcher</a>. The property should also appear in either the Fixed_Properties - or Allowed_Properties lists of + or Allowed_Properties of a <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.RequestableChannelClasses">RequestableChannelClass</a> advertised by the CM.</div> #end if diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml index 335c71fb..fefa77a2 100644 --- a/spec/Channel_Type_Contact_Search.xml +++ b/spec/Channel_Type_Contact_Search.xml @@ -31,7 +31,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>A channel type for searching server-stored user directories. A new channel should be requested by a client for each search attempt, and closed when the search is completed or the required result has been - found.</p> + found. Channels of this type should have <tp:dbus-ref + namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> + <code>None</code> (and hence <tp:dbus-ref + namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref> <code>0</code> and + <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref> + <code>""</code>). Requests for channels of this type need only + optionally specify the <tp:member-ref>Server</tp:member-ref> property + (if it is an allowed property in the connection's <tp:dbus-ref + namespace='ofdT.Connection.Interface.Requests'>RequestableChannelClasses</tp:dbus-ref>).</p> <p>Before searching, the <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be @@ -240,8 +248,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:simple-type> - <property name="Limit" type="u" access="read" - tp:name-for-bindings="Limit"> + <property name="Limit" type="u" access="read" tp:name-for-bindings="Limit" + tp:immutable='yes' tp:requestable='sometimes'> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If supported by the protocol, the maximum number of results that should be returned, where <code>0</code> represents no limit. If the @@ -254,23 +262,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <code>2</code>, the search service SHOULD only return <i>Antonius</i> and <i>Bridget</i>.</p> - <p>This property cannot change during the lifetime of the channel. - This property SHOULD be in the Allowed_Properties of a - <tp:type>Requestable_Channel_Class</tp:type> if and only if the - protocol supports specifying a limit; implementations SHOULD use + <p>This property SHOULD be requestable if and only if the protocol + supports specifying a limit; implementations SHOULD use <code>0</code> as the default if possible, or a protocol-specific sensible default otherwise.</p> </tp:docstring> </property> <property name="AvailableSearchKeys" type="as" access="read" - tp:name-for-bindings="Available_Search_Keys"> + tp:name-for-bindings="Available_Search_Keys" tp:immutable='yes'> <tp:docstring> The set of search keys supported by this channel. Example values include [""] (for protocols where several address fields are implicitly searched) or ["x-n-given", "x-n-family", "nickname", "email"] (for XMPP XEP-0055, without extensibility via Data Forms). - This property cannot change during the lifetime of a channel. <tp:rationale> It can be in the <tp:dbus-ref @@ -426,7 +431,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </signal> <property name="Server" tp:name-for-bindings="Server" - type="s" access="read"> + type="s" access="read" tp:requestable='sometimes' tp:immutable='yes'> <tp:docstring> <p>For protocols which support searching for contacts on multiple servers with different DNS names (like XMPP), the DNS name of the @@ -439,9 +444,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ User Directory").</p> </tp:rationale> - <p>This property cannot change during the lifetime of the channel. - This property SHOULD be in the Allowed_Properties of a - <tp:type>Requestable_Channel_Class</tp:type> if and only if the + <p>This property SHOULD be requestable if and only if the protocol supports querying multiple different servers; implementations SHOULD use a sensible default if possible if this property is not specified in a channel request.</p> diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml index ce77a56a..527d3252 100644 --- a/spec/Connection_Interface_Contact_Info.xml +++ b/spec/Connection_Interface_Contact_Info.xml @@ -470,6 +470,36 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ any parameters may be used.</p> </tp:docstring> </tp:flag> + + <tp:flag suffix="Overwritten_By_Nickname" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Indicates that this field will be overwritten when the user's alias + is changed with <tp:dbus-ref + namespace="ofdT.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref> + or when the Account's <tp:dbus-ref + namespace="ofdT.Account">Nickname</tp:dbus-ref> + is updated. Clients that allow the editing of the Alias and the + ContactInfo in the same location should hide fields with this flag.</p> + <tp:rationale> + <p>If a client allowed the user to edit both the nickname and the + ContactInfo field at the same time, the user could set them to two + different values even though they map to the same property. This + would result in surprising behavior where the second value would + win over the first.</p> + </tp:rationale> + <p>In addition to hiding this field when editing ContactInfo together + with the user's nickname, it is recommended that clients call + <tp:member-ref>SetContactInfo</tp:member-ref> before setting the + user's nickname.</p> + <tp:rationale> + <p>This ensures that if the user changes the nickname, the correct + value will get set even if the stale nickname is mistakenly sent + along with <tp:member-ref>SetContactInfo</tp:member-ref>.</p> + </tp:rationale> + <p>If used, this flag typically appears on either the 'nickname' or + 'fn' field.</p> + </tp:docstring> + </tp:flag> </tp:flags> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/tools/specparser.py b/tools/specparser.py index d9a596a8..beff6385 100644 --- a/tools/specparser.py +++ b/tools/specparser.py @@ -563,6 +563,7 @@ class Property(DBusConstruct, Typed): requestable = dom.getAttributeNS(XMLNS_TP, 'requestable') self.requestable = requestable != '' + self.sometimes_requestable = requestable == 'sometimes' def get_access(self): if self.access & self.ACCESS_READ and self.access & self.ACCESS_WRITE: @@ -577,7 +578,10 @@ class Property(DBusConstruct, Typed): if self.immutable: descriptions.append("Immutable") - if self.requestable: + + if self.sometimes_requestable: + descriptions.append("Sometimes requestable") + elif self.requestable: descriptions.append("Requestable") return ', '.join(descriptions) |