| TOC |
|
This is a collection of new protocol extensions (and updates) for Jabber. These have been discussed and agreed to (at least in concept) by much of the Jabber Team.
| TOC |
| TOC |
These materials are in first-draft format, don't take it as the final protocol, although the final shouldn't vary significantly from what you see here.
If you notice anything that strikes you as odd and isn't explained, please tell someone.
| TOC |
The basic idea is this: the jabber world is a diverse place, with lots of services, transports, software agents, users, groupchat rooms, translators, headline tickers and just about anything that might interact on a real-time basis with conversational messages or presence. Every jid is a node that can be interacted with for messages, presence, and special purpose iq namespaces. Some jids are parents (transports), and often many jids have relationships with other jids (a user to their resources, server to it's services, etc). We need a far better way to structure and manage this culture of jid stew. The answer: BROWSING
People are comfortable identifying file types with "mime-types", in the format category/subtype. The first concept in browsing is a "jid-type", or simple similiar heirarchy for identifying the role of any Jabber ID. A jid-type, after discovered, is to be used in the same way that a mime-type would be for a file, to alter the UI representing that jid or provide alternative functionality for interacting with it (either automatically or UI-driven). The following is a first-pass at a list of the possible categories and subtypes. Additional type extensions can always be specified as category/x-subtype.
service/ To identify which "world" they map into, often another IM network or messaging gateway service/jabber Jabber Server service/icq ICQ Transport service/aim AIM Transport service/msn MSN Transport service/yahoo Yahoo! Transport service/irc IRC Gateway (user) service/smtp SMTP Gateway service/pager Pager Gateway service/jud Jabber User Directory conference/ To identify the type of conference server or characteristics of a specific conference. conference/private Private dynamically-generated conference rooms conference/irc IRC Rooms conference/topic Topic-based conferences conference/url URL/Web-based conferences conference/list Mailing list style conference user/ Users user/client Client Connection user/forward Forwarding alias user/device Portable or other device user/inbox Alternate inbox user/voice Phone or voice access application/ Specific applications running on a user@host/resource id application/calendar Calendaring/Scheduling Service application/whiteboard Whiteboard Tool application/editor Collaborative Editor application/game Multiplayer Game application/fileserver Files Available application/bot Automated Conversations headline/ Recognize different sources of headlines, gui hints headline/rss Rich Site Summary (cumulative/replaceable) headline/stock Stock symbol (ticker) headline/logger Log Messages (scrolling) headline/notice Alerts/Warnings (popups) render/ Automated translation services (YTBD) render/en2fr English to French render/*2* Other standard *lang to *lang render/jive Jive Style render/tts Text To Speech render/grammer Grammer Checker render/spell Spell Tool keyword/ Keyword Lookup Services keyword/dictionary Dictionary Lookups keyword/thesaurus Thesaurus Lookups keyword/faq FAQ Bot keyword/web Web search keyword/software Software search keyword/dns DNS resolver keyword/whois Whois Query
There is a new namespace containing the browsing data: jabber:iq:browse. The elements within this namespace are identified by the categories listed above, with a few generic attributes. For example: <user jid="jer@jabber.org" name="jer"> <user jid="jer@jabber.org/home" type="client" name="Home Desktop"/> <application jid="jer@jabber.org/chess" type="game" name="XChess"/> </user>
The required jid attribute is the full Jabber ID of the entity described. Type is the subtype for the category as defined above, and is required. Name is a friendly name that may be used in a GUI, and is optional. (uri="" for web links?) Any element may contain any other element as a child, describing the relationship between the two. This relationship my be represented as a "link" in a wizard or page-based GUI, or as a branch in a tree as it's expanded. When a jid is browsed to, the result may contain children or be empty. An empty result means there is no further relationships or links for that jid, a dead-end, which may be represented as a page that contains a list of functions available for it (vcard, message, register, etc). When the result contains children, they may also be empty (as in the example above). An empty child does not mean anything, and to determine if there are more children of it it must be browsed to directly.
Ontop of the browsing framework, a simple form of "feature advertisement" can be built. This allows any entity to advertise which features they support, based on namespaces. An additional allowed element within a browse result is <ns/>. This element contains a single namespace that the entity supports, and multiple ns elements can be included in any result. For a connected client this might be <ns>jabber:iq:oob</ns>, or for a service <ns>jabber:iq:search</ns>. This list of namespaces should be used to present available options for a user, or for an application to automatically locate functionality.
The children of a browse result may pro-actively contain a few ns elements (such as the result of the service request to the home server), which advertises the features that particular service supports. This list may not be complete, and the jid should be browsed to for a complete list, it is only for first-pass filtering by simpler clients.
Clients should answer incoming browsing requests to advertise which namespaces they support, such as file transfers (jabber:iq:oob), crypto/signatures, xhtml, etc.
The first important use of jabber:iq:browse is to replace the iq:agents namespace. When a client connects, it may optionally browse to the server it connected to to retrieve a list of available services. The resulting iq might look like: <service type="jabber" jid="jabber.org" name="Jabber.org Public Development Server"> <service type="icq" jid="icq.jabber.org" name="ICQ Transport"> <ns>jabber:iq:register</ns> <ns>jabber:iq:search</ns> <ns>jabber:iq:gateway</ns> </service> <conference type="private" jid="conference.jabber.org" name="Private Chatrooms"/> <application type="bot" jid="jabber.org/help" name="Assistance Agent"/> </service> To determine any further details from this list, each individual child would have to be browsed to. The elements within the icq service are only hints for a client when building GUI menu items or in wizzards, icq.jabber.org would still need to be browsed to to determine any relationships or additional namespaces. This top-level list is the master "services" list available from the server, and should be used for any default functionality when available. This list may also serve as the "home page" for a page-based browsing GUI.
It is also useful to arrange entities hierarchially, which implies nodes or parents that don't really exist except to be browsed to and contain a list of children or relationships. These generic nodes are simply items, and represented by a <item jid="server/abc/def" name="DEF Zone"/>. It has no sub-type, and is a special purpose entity that is only for arranging browsing in a heirarchy. They can be used whenever the type of jid isn't pre-set (and needs to be browsed to directly), or serve as a placeholder for a node in a heirarchy of other jids. This is most useful for representing unknown jids, arranging a company directory, list of chat rooms, or browsing any heirarchially-arranged jabber entities.
This is Jabber, it's a real-time platform, and browsing is a relatively static activity. So to take full advantage of browsing within Jabber, browse data can be live and pushed similiar to presence. This is useful for any browseable data that might change regularly (participants in a conference, bluetooth devices, or custom application uses) which can be tracked in real time and have updates pushed out to all those interested in receiving them. To enable this, send presence to the jid before doing an iq get for the browse data. Subsequent iq:browse sets from that jid will contain additional children or updates to existing children (type="remove" removes a child like in editing below).
Any jid may be stored in the roster. The roster's role for storing jid's a user is interested in, can expand into a bookmark role not only storing them for presence information but also for browsing. This would expand the namespace of the roster to include the standard jid-types. Additionally to an "item" element, any of the above categories could be stored as an element in the roster with an optional type attribute. The name and all other roster/presence related attributes apply equally as if it were an item, but intelligent clients can use the jid-type to make additional user-stored bookmarks available. The client could store favorite chat rooms, always-enabled renders, headlines, or special remote transports that you want made available in addition to the default server ones. In a GUI, clients could optionally merge this list from the roster with the list from the server, or make it available as part of the roster directly.
When an iq set is used, and when there are sufficient priveleges (such as a user to thier jid), the included browse namespace data should be stored (or replace) for that jid. When setting, a single child will not replace the entire contents of the parent, but simply be inserted. To remove any child, set it's jid with a type="remove".
A client shouldn't just blindly follow browse-to-jids and keep requesting, but instead it should maintain an internal list of all the returned browse results for a jid for efficiency. Any display or use of the browse data should then be returned from the internal list. This is a similiar model to presence. All jids should always have the following options: message/chat, browse Hostname jids should also always have the options: time, vcard, last, version Users should also have: vcard, last User resources should have: time, version, oob
| TOC |
The new conferencing protocol replaces the old "groupchat" protocol. It is a framework in which messages are broadcast to multiple recipients via a third party, and that third party manages the list of recipients, traffic, and identities of all the participants. There may be numerous different types of conferencing services, private ones created on the fly by any user with their friends, IRC rooms, shared-location (URL), topic, or content based, and so on. The design of the new protocol makes use of the new browsing functionality.
The conference namespace is a simple mechanism for obtaining the characteristics of a conference and negotiating participation.
The iq get will allow anyone to view a list of required fields and the current topic.
Getting List: <iq type='get' to='grp@gserv'><query xmlns='jabber:iq:conference'/></iq> <iq type='result' from='grp@gserv'><query xmlns='jabber:iq:conference'><nick/><secret/><presence/><topic>The Room's Topic!</topic></query></iq>"nick" indicates that the user should select a nickname. "secret" indicates that a password is required to participate. "presence" indicates that available presence must be sent prior to participation. The topic is a general description, or the most recent set topic of the conference.
The iq set is used to enter or join a conference, and contains the required fields and some additional flags.
<presence to="grp@gserv"/> <iq type='set' to='grp@gserv'><query xmlns='jabber:iq:conference'><secret>foo</secret><nick>dude</nick><nick>dude_</nick><privacy/><messages/></query></iq> <iq type='result' from='grp@gserv'><query xmlns='jabber:iq:conference'><id>grp@gserv/a32d...</id><nick>dude</nick></query></iq>The secret and nick are required as indicated by the get request. Multiple nicks may be included in case the first is taken. "privacy" will indicate the server should hide your real jid. "messages" will turn message traffic on and off. The result will contain the selected or assigned nick, and the id assigned to you. Any further iq get requests should return the same result as this set, and any further iq set requests will modify the flags or attempt to change the nick.
The participants in a room are available by browsing to that room. A room will create temporary identities for all participants such as "grp@gserv/1c38...", and use that as the sending jid for that participant. The current nickname is the name attribute on the browse result. The participant list may be available before entering the room (if it's not protected) and the real jid of the participant may be accessible by browsing to their temporary room jid (if not protected when they joined). If available presence was sent, any changes in the browsed participant list will be pushed to the participants. <iq type='get' to='grp@gserv'><query xmlns='jabber:iq:browse'/></iq> <iq type='result' from='grp@gserv'> <conference type='private' xmlns='jabber:iq:browse'> <user jid="grp@gserv/d351..." name="jer"/> <user jid="grp@gserv/a32d..." name="dude"/> </conference> </iq> Messages and Presence sent to a conference will be broadcast out to all participants, and the from="" will be rewritten as the local jid assigned to that participant. Recipients should translate that sender to the appropriate node in the browse data, and use that name="" for display purposes.
| TOC |
Anyone can query the uptime of a server or any service.
Request: <iq type="get"><query xmlns='jabber:iq:last'/></iq> Result: <iq type='result' to='jer@home.jeremie.com/home' from='home.jeremie.com'><query xmlns='jabber:iq:last' stamp='20010107T06:43:50'/></iq>
The same query, when sent to a user@host account, if supported by the server will return the last time the user logged out. It also includes the last-known unavailable status message. Clients should support the ability to send a "logout" or signoff message, which is the status of an unavailable presence sent before disconnecting. Not only is this broadcast to the subscriptions as a more descriptive action, but it is stored for future reference in the last namespace. This can be used for extended disconnects such as "Going on vacation, back on the 14th", or simple messages like "going home early today".
Request: <iq type="get" to="foo@home.jeremie.com"><query xmlns='jabber:iq:last'/></iq> Result: <iq type='result' to='jer@home.jeremie.com/home' from='foo@home.jeremie.com'><query xmlns='jabber:iq:last' stamp='20010107T06:53:24'>I'm gone for the weekend skiing!</query></iq>
| TOC |
These namespaces are used to sign and encrypt messages and presence for end-to-end security. They are most secure when performed at the client level, but could optionally be supported and used by a trusted server. The crypto information is contained in the jabber:x:signed or jabber:x:encrypted namespaces. The contents are the armor'd output from GPG or PGP, and have all of the header and wrapper text removed (it serves no purpose within this context). Any future additional encryption schemes other than PGP/GPG should utilize their own namespace(s) to exchange data.
The status element of presence is the CDATA that is signed: <presence from='pgmillard@jabber.org/wj_dev2' to='jer@jabber.org'> <show>online</show> <status>Online</status> <x xmlns='jabber:x:signed'>iQA/AwUBOjU5dnol3d88qZ77EQI2JACfRngLJ045brNnaCX78ykKNUZaTIoAoPHI 2uJxPMGR73EBIvEpcv0LRSy+ =45f8</x> </presence>
A signed message would look/work the same as presence above, but the CDATA would be the contents of the body element. An example encrypted message, containing the word "Hi": <message to='reatmon@jabber.org/jarl' from='pgmillard@jabber.org/wj_dev2'> <body>This message is encrypted.</body> <x xmlns='jabber:x:encrypted'>qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA w7R61cCPt8KSd8Vcl8K+StqOMZ5wkhosVjUqvEu8uJ9RupdpB/4m9E3gOQZCBsmq OsX4/jJhn2wIsfYYWdqkbNKnuYoKCnwrlmn6I+wX72p0R8tTv8peNCwK9bEtL/XS mhn4bCxoUkCITv3k8a+Jdvbov9ucduKSFuCBq4/l0fpHmPhHQjkFofxmaWJveFfF 619NXyYyCfoLTmWk2AaTHVCjtKdf1WmwcTa0vFfk8BuFHkdah6kJJiJ7w/yNwa/E O6CMymuZTr/LpcKKWrWCt+SErxqmq8ekPI8h7oNwMxZBYAa7OJ1rXWKNgL9pDtNI 824Mf0mXj7q5N1eMHvX1QEoKLAda/Ae3TTEevOyeUK1DEgvxfM2KRZ11RzU+XtIE My/bJk7EycAw8P/QKyeNlO1fxP58VEd6Gb8NCPqKOYn/LKh1O+c20ZNVEPFM4bNV XA4hB4UtFF7Ao8kpdlrUqdKyw4lEtnmdemYQ6+iIIVPEarWl9PxOMY90KAnZrSAq bt9uRY/1rPgelRaWblMKvxgpRO8++Y8VjdEyGgMOXxOiE851Ve72ftGzkSxDH8mW TgY3pf2aATmBp3lagQ1COkGS/xupovT5AQPA3RzbCxDvc6s6eGYKmVVQVj5vmSj1 WULad5MB9KT1DzCm6FOSy063nWGBYYMWiejRvGLpo1j4eAnj0qOt7rTWmgv3RkYF Oin0vDOhW7aC =CvnG</x> </message>
| TOC |
The jabber:iq:private namespace is the old way of storing any XML in another namespace on the server, such as client preferences. It is still supported and used to store any "private" XML, but the server now supports similiar public XML storage. If the client does an iq set in any XML namespace to the server, it is stored on that users account. That XML is then accessible to anyone doing an iq get with the same namespace to that user account. The server will also include a respective ns element in that users browse data.
Generic XML may also be stored public or private on a specific resource. When the recipient of the iq set is a resource of that user, the namespace is stored only on that resource and that resource then referenced in the main users browse data.
...
| TOC |
Message Events are for notifications of "message delivered" or "user is composing a reply" sorts of things. These are not required and only enabled on demand, only when the originating client requests this feature and the recipient client supports it.
There are currently four event types: offline (stored), delivered (to client), composing (the reply), and displayed (made visible to the recipient). The recipient server determines the offline event, and the recipient client determines the delivered, composing, and displayed events. If the sending client supports any of these events in it's GUI and wants to receive them for a particular message, it should include the extension in that message. If the recipient server/client supports the extension, it should respond appropriately as shown below. It would be inappropriate to respond or generate events when not requested.
The composing event is generated when the user is actively typing a reply to the message. If the user never completes/sends the reply (or after an idle timeout), an empty jabber:x:event (just contains the id element) should be sent to "clear" the outstanding composing event.
Original Message (requests that the offline and displayed events should be sent if/when they occur): <message to="foo@bar.org" from="bar@foo.org" id="MSG_31"> <body>foo bar</body> <x xmlns="jabber:x:event"><offline/><displayed/></x> </message> Return Event (the id element flags that it is a return event): <message to="bar@foo.org" from="foo@bar.org"> <x xmlns="jabber:x:event"><displayed/><id>MSG_31</id></x> </message>
| TOC |
This is a new simple namespace to assist clients in their add-user functionality. The results of the get are used for the GUI strings and user entry instructions. The set of what the user entered will return the correct jid for subsequent actions.
...
| TOC |
XHTML allows clients to support simple styled text (colors and fonts) or full blown xhtml support. It is a standard alternate body namespace, to be used if supported. A simple example:<message><body>hi</body><html xmlns="http://www.w3.org/1999/xhtml"><body><h1>hi</h1></body></html></message>.
All of the textual content must always be represented as best as possible in the normal body for non-supporting clients. If after sending xhtml with a thread in a conversation, and the thread being returned without an xhtml alternate body, the client should stop sending the xhtml (because a client supporting xhtml would return the thread in the next message and use xhtml). If the other client returns a browse request and doesn't include the xhtml namespace, it should default to off for that user, and vice-versa if included. This detection logic isn't required, but is highly suggested.
From x-virge:
Using XHTML and Styling Messages in Jabber
XHTML-Basic in Jabber
Nothing is really "required" in any sense, but if you would like to claim full conformance with this document, you must follow everything marked required, and should do some of the recommended stuffs...
required:
<html xmlns="http://www.w3.org/1999/xhtml"> - must be the root element
<body> - must be inside <html>
<blockquote> - indent or italicize or somehow indicate that this text is a quote, but a large one, usually a paragraph or more
<br/> - Clients should recognize that this is /n, and should be used instead of /n within the <html> portion of <message>
<div> - at least understand that this divides into paragraphs. Basic support for the various align types would be nice
<em> - This generally means italics
<h1> through <h6> - The general headings, h1 is usually displayed with largest font size. Client should also understand that a /n is implied after a heading
<p> - Client should understand this is a paragraph, and be sure to end with a </p>
<q> - At absolute least, translate <q> to " and </q> to ", so things will appear in quotes. A proper client will also understand nested quoting
<strong> - Most clients should recognize this as bold
<a> - Clients should recognize at least http:// links (should they support jabber: as meaning a jabber user?), with optional support for mailto:. Relative links should be supported at the client's discresion
optional, but recommended:
<img> - If the image is pointing somewhere that the client can find it, feel free to display it. This might be useful for clients which wish to be more graphical - they can ship with standard images, and somehow the UI can allow users to select them and display to each other. It is recommended that clients be able to display the alt text for images. (Not necessarily the images themselves)
<code> - this is used to designate a fragment of computer code - perhaps make this in a fixed font. It would be nice to see computer code exchanged with things like this instead of with quotations around it
<ul> - Understand that this means text should be indented, and that its children, <li> are unordered (be sure to close the <li>'s)
<ol> - Understand that this means text should be indented, and that its children, <li>, are ordered, usually this means with numbers, optional support for type numbering styles
optional:
<address> - If you want to do something special to an address
<abbr> and <acronym> - if you wish to expand the title's of these on mouseover
<cite> - "Contains a citation or a reference to other sources. "
<dfn> - "Indicates that this is the defining instance of the enclosed term. "
<kbd> - "Indicates text to be entered by the user."
<pre> - pre-formatted text. If possible, do not wrap text within <pre>, as it should have its own wrapping
<samp> - "Designates sample output from programs, scripts, etc."
<var> - "Indicates an instance of a variable or program argument."
<dl> and its buddies <dt> and <dd> - these are used for definition lists. Not that much more useful than <ul> and <ol>...
not needed:
<form> <input> <label> <select> <option> <textarea> - None of the input types or forms are needed.
<table> <caption> <td> <th> <tr> - Most clients will not render tables properly, and they aren't worth the effort for an IM system
<title> - This should not supercede the <message><subject>
<head> - There is nothing within <head> which is needed
<span> - There is no need when we don't support styles
<meta> - If your client does have a good use for this, feel free
<link> - Style sheets are not supported, they are too difficult
<base> - absolutely no need
Styles in Jabber XHTML
Required:
font-size
color
background-color
Optional, but reccomended:
text-decoration
font-family
Optional:
text-align
background-image
An example of absolute minimal support, requiring only the parsing of 3 CSS attributes on any element:
<message>
<body>hi</body>
<html xmlns="http://www.w3.org/1999/xhtml">
<body style="color:red;background-color:green;font-size:large">hi</body>
</html>
</message>
| TOC |
start offering uri's that are included in reg/search/etc requests as alternative or option?
different display modes, browsing, ...
suggested use, updated docu...
point to update spec
check in mass's docu and point to it
...
The IETF vCard XML work seems to have stopped. It's unfortunate that the namespace we use is "vcard-temp", as it seems that it's now permanent and the most widespread vCard XML format. Due to this, we've decided to add a few elements to it that we've needed. desc? x-jabber-id?
DESC: free-form user entered description or about text JABBER: Jabber ID (primarily for use outside of Jabber)
A new ns element for jabber:iq:filter will match incoming iq requtests to that namespace. Not all actions will work. Roster/group conditions.
...