XEP-0012: Last Activity

Внимание Этот текст не является официальным переводом документа XEP-0196: User Game и может не соответствовать оригиналу. Для разработки программ используйте официальный текст.

Эта спецификация определяет расширение XMPP, используемое для передачи информации о времени последней активности пользователя, связанной с XMPP. Клиент отправляет информацию об активности пользователя на сервер.

Информация о документе

• Автор: Jeremie Miller, Thomas Muldowney, Peter Saint-Andre
• Авторское право: © 1999 - 2010 XMPP Standards Foundation.
• Статус: Окончательный
• Тип: Основное расширение
• Версия: 2.0
• Последнее обновление: 2008-11-26

ВНИМАНИЕ: расширение, определенное в настоящем документе, окончательное и может использоваться для реализации в программах.

Введение

Иногда бывает полезным узнать время последней активности пользователя. Для получения этой информации используется пространство имён «jabber:iq:last». Также можно узнать длительность подключения пользователя к серверу.

Протокол

Для запроса последней информации об активности пользователя отправляется IQ-запрос типа "get" с указанием пространства имён «jabber:iq:last»:

Пример 1. Запрос

<iq from='romeo@montague.net/orchard' 
   id='last1'
   to='juliet@capulet.com'
   type='get'>
 <query xmlns='jabber:iq:last'/>
</iq>

Ответ должен иметь тип 'result' или 'error'. При ответе отправляется <iq/>-строфа типа 'result' с элементом <query/> с обязательным параметром 'seconds'.

Пример 2. Ответ

<iq from='juliet@capulet.com' 
   id='last1'
   to='romeo@montague.net/orchard'
   type='result'>
 <query xmlns='jabber:iq:last' seconds='903'/>
</iq>

Ответ может интерпретироваться по-разному:

1. Время существования на сервере JID вида <localpart@domain.tld>.
2. Длительность подключения определённого ресурса, JID вида <localpart@domain.tld/resource>.
3. Время работы сервера, JID вида <domain.tld>.

Ниже всё это описано подробнее.

Запрос у отключенного пользователя

Ответ содержит время, в течение которого пользователь находится не в сети.

Пример 3. Запрос

<iq from='romeo@montague.net/orchard' 
   id='last1'
   to='juliet@capulet.com'
   type='get'>
 <query xmlns='jabber:iq:last'/>
</iq>

As specified in XMPP Core and XMPP IM, an IQ stanza of type "get" sent to a bare JID <localpart@domain.tld> is handled by the user's server on the user's behalf, not delivered to one or more connected or available resources.

If the requesting entity is not authorized to view the user's presence information (normally via a presence subscription as defined in XMPP-IM), the user's server MUST NOT return last activity information but instead MUST return a <forbidden/> error in response to the last activity request.

Пример 4. Requesting Entity is Not Authorized to Retrieve Last Activity Information

<iq from='juliet@capulet.com' 
   id='last1'
   to='romeo@montague.net/orchard' 
   type='result'>
 <error type='auth'>
   <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
 </error>
</iq>

Если пользователь, отправивший запрос, имеет подписку на пользователя (presence), сервер возвращает информацию о последних действиях пользователя.

Пример 5. Ответ

<iq from='juliet@capulet.com'
   id='last1'
   to='romeo@montague.net/orchard'
   type='result'>
 <query xmlns='jabber:iq:last' seconds='903'>Heading Home</query>
</iq>

В этом примере пользователь отключился 15 минут и 3 секунды назад, при отключении был отправлен текст в статусе "Heading Home". Если же во время отправки запроса пользователь был подключен, то сервер возвращает в элементе <query/> значение 'seconds', равное '0'.

Запрос у подключенного пользователя

В данном случае отправляется запрос с полным JID <localpart@domain.tld/resource>.

Пример 6. Запрос с полным JID

<iq from='romeo@montague.net/orchard'
   id='last2'
   to='juliet@capulet.com/balcony'
   type='get'>
 <query xmlns='jabber:iq:last'/>
</iq>

В данном случае запрос отправляется на подключенный ресурс, и ответ придёт от него. Если пользователь, отправивший запрос, не имеет подписки на пользователя, то в ответе вместо этой информации сервер должен отправить ошибку <forbidden/>.

Пример 7. Requesting Entity is Not Authorized to Retrieve Last Activity Information

<iq from='juliet@capulet.com' 
   id='last1'
   to='romeo@montague.net/orchard'
   type='result'>
 <error type='auth'>
   <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
 </error>
</iq>

В противном случае клиент отправляет ответ, содержащий время, которое пользователь неактивен (например, время, которое не взаимодействовал с клиентом).

Пример 8. Ответ от клиента

<iq from='juliet@capulet.com/balcony' 
   id='last2'
   to='romeo@montague.net/orchard' 
   type='result'>
 <query xmlns='jabber:iq:last' seconds='123'/>
</iq>

Здесь пользователь неактивен две минуты.

Такой ответ не является обязательным. Если клиент не поддерживает эту функцию или не хочет отправлять эту информацию, должен отправить ошибку <service-unavailable/>.

Пример 9. Клиент возвращает ошибку

<iq from='juliet@capulet.com/balcony' 
   id='last2'
   to='romeo@montague.net/orchard'
   type='error'>
 <error type='cancel'>
   <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
 </error>
</iq>

Если ресурс, указанный в запросе, не подключен, сервер должен следовать правилам, XMPP чат для того, чтобы определить, какие ошибки строфы вернуться. (the server MUST follow the rules in XMPP IM in order to determine what error stanza to return.)

Запрос к серверу

Если запрос направлен серверу, то возвращается время его работы без падений (с последнего перезапуска). The <query/> element SHOULD NOT contain XML character data.

Пример 10. Запрос у сервера

<iq from='romeo@montague.net/orchard' 
   id='last3'
   to='capulet.com' 
   type='get'>
 <query xmlns='jabber:iq:last'/>
</iq>

Пример 11. Ответ

<iq from='capulet.com' 
   id='last3'
   to='romeo@montague.net/orchard'
   type='result'>
 <query xmlns='jabber:iq:last' seconds='123456'/>
</iq>

Здесь сервер работает 34 часа.

Поддержка

Если сервер или клиент поддерживает описанное здесь расширение, то он должен отправлять информацию о поддержке в Service Discovery (“disco#info”).

Пример 12. Запрос диско у сервера

<iq from='stpeter@jabber.org/roundabout'
   id='disco1'
   to='jabber.org'
   type='get'>
 <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

Пример 13. Ответ с поддержкой jabber:iq:last

<iq from='jabber.org'
   id='disco1'
   to='stpeter@jabber.org/roundabout'
   type='result'>
 <query xmlns='http://jabber.org/protocol/disco#info'>
   <feature var='jabber:iq:last'/>
 </query>
</iq>

In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in Entity Capabilities. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.

Примечание

Информация, содержащаяся в ответе IQ для этого пространства имен, неоднозначна. В частности, для голого JID <localpart@domain.tld> это время с последнего подключения, для полного JID <localpart@domain.tld/resource> время, которое пользователь неактивен, а для сервера - время бесперебойной работы сервера или компонента.

Безопасность

Серверу недопустимо отправлять информацию об активности пользователя чужим пользователям, если в запросе JID вида <localpart@domain.tld> или <localpart@domain.tld/resource>. Иначе возможны «утечки», как описано в rfc3920bis. То есть, информация об активности может быть отправлена только тем лицам, которые имеют подписку на данного пользователя. Клиент должен предоставлять возможность отключать отправку информации об активности.

IANA

Этот документ не требует взаимодействия с Internet Assigned Numbers Authority (IANA).

XMPP

Никаких действий со стороны XMPP Секретаря не нужно, поскольку в этом документе, так как «jabber:iq:last» уже зарегистрировано в протоколе имен реестра находится в <http://xmpp.org/registrar/namespaces.html>. (No action on the part of the XMPP Registrar is necessary as a result of this document, since 'jabber:iq:last' is already registered in the protocol namespaces registry located at <http://xmpp.org/registrar/namespaces.html>.)

Схема XML

<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
   xmlns:xs='http://www.w3.org/2001/XMLSchema'
   targetNamespace='jabber:iq:last'
   xmlns='jabber:iq:last'
   elementFormDefault='qualified'>
 <xs:annotation>
   <xs:documentation>
     The protocol documented by this schema is defined in
     XEP-0012: http://www.xmpp.org/extensions/xep-0012.html
   </xs:documentation>
 </xs:annotation>
 <xs:element name='query'>
   <xs:complexType>
     <xs:simpleContent>
       <xs:extension base='xs:string'>
         <xs:attribute
             name='seconds'
             type='xs:unsignedLong'
             use='optional'/>
       </xs:extension>
     </xs:simpleContent>
   </xs:complexType>
 </xs:element>