XMPP Component Protocol

From OLPC
Revision as of 21:20, 30 November 2007 by RobertMcQueen (talk | contribs) (add information about how the component finds this stuff, and enforce properties living in their own namespace, and enhance the examples)
Jump to navigation Jump to search

Information about the protocol for the OLPC-specific XMPP server component.

Data Acquisition

Currently buddy properties and activity properties and are implemented using PEP nodes. It's intended that the buddy properties continue using PEP nodes, and that activity properties are changed to be propagated within a MUC using a simple MUC <presence> based protocol.

This server component shall appear as a JID which can be found using service discovery, which when subscribed to, will subscribe to your presence (and hence PEP notifications), and therefore be privy to your buddy properties and make them available for others to search and be notified of changes. If this is undesirable for privacy reasons, the component JID should simply be removed from the roster.

The component JID can also be invited into activities in order to be made aware of the activity's existence, properties and current membership (by observing the <presence> stanzas of the MUC members). This information is then made available for others to search and be notified of changes.

Laptops still receive information about their buddies' current activity (FIXME: maybe?) and properties directly from them using PEP notifications.

Protocol Overview

Laptops query the server component about activities and buddies. For both kinds of query, there is at most one result set active at any given time. Result sets are managed using the Result Set Management (RSM) XMPP extension, as described in XEP-0059.

The component sends notifications to clients based on their currently visible result sets.

Activity Protocol

Namespace: http://laptop.org/xmpp/activity

Query

Return all activities matching the properties given.

Example: XO searches for all instances of the "Connect" activity.

 <iq type="get" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <activity>
       <properties xmlns="...">
         <property type="str" name="type">org.laptop.Connect</property>
       </properties>
     </activity>
   </query>
 </iq>

Example: XO searches for an activity by ID.

 <iq type="get" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <activity jid="abcde123@conference.example.org" />
   </query>
 </iq>

Example: XO can search for a union of activities matching different search criteria (to be subscribed to changes of multiple activities)

 <iq type="get" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <activity>
       <properties xmlns="...">
         <property type="str" name="type">org.laptop.Connect</property>
       </properties>
     </activity>
     <activity jid="abcde123@conference.example.org" />
   </query>
 </iq>

Search results contain information about the matching activities, including their properties and their current members.

Example: component replies to query:

 <iq type="result" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <activity jid="connect4@conference.jabber.laptop.org">
       <properties xmlns="...">
         <property type="str" name="type">org.laptop.Connect</property>
       </properties>
       <buddy jid="alice@jabber.laptop.org" />
       <buddy jid="bob@jabber.laptop.org" />
       ...
     </activity>
     <activity jid="abcde123@conference.example.org">
       <properties xmlns="...">
         ...
       </properties>
       ...
     </activity>
     ...
   </query>
 </iq>

Any buddies who are known by the component, and not currently visible in the XO's buddy result set, will have their properties included in full.

Example: component replies to query with supplemental buddy information.

 <iq type="get" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <activity jid="...">
       <properties xmlns="...">
         <property type="str" name="type">org.laptop.Connect</property>
       </properties>
       <buddy jid="alice@jabber.laptop.org" />
       <buddy jid="bob@jabber.laptop.org">
         <properties xmlns="...">
           <property type="str" name="color">#005FE4,#00A0FF</property>
           ...
         </properties>
       </buddy>
       ...
     </activity>
     ...
   </query>
 </iq>


Change announcement

Example: component notifies client about change in activity properties:

 <message type="notice" from="index.jabber.laptop.org" to="joe@jabber.laptop.org">
   <change xmlns="...">
     <properties xmlns="..." activity="abcde123">
       <property type="str" name="tags">news, france</property>
     </properties>
   </change>
 </message>

Join announcement

Component tells XO that somebody has joined an activity.

 <message type="notice" from="index.jabber.laptop.org" to="joe@jabber.laptop.org">
   <activity xmlns="..." activity="abcde123"">
     <joined jid="bob@jabber.laptop.org" />
   </activity>
 </message>

Departure announcement

Component tells XO that someone has departed an actvitiy.

 <message type="notice" from="index.jabber.laptop.org" to="joe@jabber.laptop.org">
   <activity xmlns="..." activity="abcde123"">
     <left jid="bob@jabber.laptop.org" />
   </activity>
 </message>

Closed

Component tells XO that all participants have departed an activity.

 <message type="notice" from="index.jabber.laptop.org" to="joe@jabber.laptop.org">
   <activity xmlns="..." activity="abcde123"">
     <closed/>
   </activity>
 </message>

Buddy Protocol

Namespace: http://laptop.org/xmpp/buddy

Query

Fetch information about buddies. Similar to activity querying.

By JID:

 <iq type="get" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <buddy jid="bob@jabber.laptop.org" />
   </query>
 </iq>

Changed

 <message type="notice" from="index.jabber.laptop.org" to="joe@jabber.laptop.org">
   <change xmlns="..." jid="bob@jabber.laptop.org">
     <properties xmlns="...">
       <property type="str" name="color">#005FE4,#00A0FF</property>
     </properties>
   </change>
 </message>