Client Guidelines

The Jabber.org Project
Revision History
Revision 32000/03/21
Grammatical / clarification edits.
Revision 22000/03/18
Keith Minkler - Fleshed this out a bit.
Revision 12000/02/21
First draft for review.

Provides Jabber client authors with a quick rundown of suggested requirements for a complete and fully functional client.


Roster List


Optional Actions

  • Fetch and display the roster.

  • Add/Delete/Modify roster items.


Suggested Actions

  • Display Roster items in a way that shows the users presence ([un]available), show (normal | chat | dnd | away | xa), and subscription type ([un]subscribed)

  • Roster items should be displayed using friendly names, that are set by the client user.


Details

A roster item has the following attributes:

  • jid - The users' Jabber identification.

  • name - A user set "friendly name" for this user.

  • subscription - Either 'none' 'to' 'from' or 'both' to identify what type of subscrption you have with this user.

  • ask - A marker identifying what type of subscription you are waiting for.

  • group tags - A roster item/ contains group/ tags that show the groups that this item is a part of.


Login Sequence

Required Actions

Log in as either a user, or an anonymous account.


Optional Actions

  • Get roster.

  • Send presence.

  • Get list of agents.


Suggested Actions

  • If the client has a roster display, the client should fetch the user's roster. Note that the user will not recieve any subscription presence if the roster is not fetched.

  • If the client supports presence, the client needs to send the user's available presence. Note: the client will not receive messages or normal presence if the user's presence is not sent.


Details

The two methods of login are Plain Text, and Digest Authentication. Either of these can be done through a SSL connection with the server.

  • In the Plain Text method, a user sends his username, password and a desired resource to the server in plain text.

  • In the Digest Authentication method, the client creates a digest, consisting of the server generated key plus the password and SHA1's the whole string.


Adding/Deleting/Modifying Users

Required Actions

None (if the client does not support rosters).


Optional Actions

  • Add a roster item.

  • Delete a roster item.

  • Subscribe to the users presence.


Suggested Actions

  • If the client supports the roster, it will have to support the Optional Actions.

  • Users should have easy access to the roster item's information and be able to change roster items at will.


Details

Roster items can be added in two ways. The first is when the client sends the server iq type="set"/ (xmnls="jabber:iq:roster"). The server will add the user to the roster automatically.

The server will add a user in the roster under the following conditions (assuming the user doesn't already exist in the roster):

  • An incoming/outgoing presence was sent from/to a user not in the current roster.

  • The user is subscribed to a group agent that manages certain groups automatically.

Adding a user takes the following steps:

  • (Client adds a user to roster with iq type="set"/) -> Server

  • Client <- (Server responds with an OK result)

  • Client <- (Server responds with a roster push with the new item)

  • (Client sends out a presence subscribe to that user) -> Server

  • Client <- (Server pushes an update to client with ask="subscribe" set)

  • Client <- (Remote user OK's subscription request)

  • Client <- (Server pushes a new item with the correct subscription="" set, and removes the ask="")

Removing an item before it is confirmed, or sending a presence type="unsubscribed"/ cancels the request.


Presenting Incoming Presence Subscriptions


Optional Actions

Display incoming presence subscriptions to the user.


Suggested Actions

Roster list should also be updated to reflect the subscription to the user.


Details

What incoming subscription presence means:

subscribe

A user wants to see the user's presence, the user can either accept or deny the request. Users may also be given the option to "auto-accept" or "auto-deny" requests.

unsubscribe

A user no longer wishes to see the user's presence. There is nothing the client can do to stop this. The client may offer to unsubscribe as well, and/or remove the item from the roster.

subscribed

If the user sends out a subscription request, subscribed tells the user that it was approved.

unsubscribed

If the user sent out a subscription request, this is a messaging telling the user that it was denied by the receiver. If the user sent out a request to unsubscribe, this message from the server telling the user that the request has been processed.


Message Items


Optional Actions

Support messages of type "normal|chat|groupchat" with appropriate interfaces.

vCard?

Threads?

Subjects?


Details

Message type="normal"

ICQ style messages.

Message type="chat"

AIM style chat messages.

Message type="groupchat"

IRC style chat with a group list (list of participants).


Legal Information

Document

Copyright (c) 2000, The Jabber.org Project.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to

The Free Software Foundation, Inc.,
59 Temple Place - Suite 330,
BostonMA 02111-1307,
USA


Code

Copyright (C) 2000, The Jabber.org Project.

All sample code included in this document is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program 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 General Public License for more details. You may obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

The Free Software Foundation, Inc.,
59 Temple Place - Suite 330,
BostonMA 02111-1307,
USA