draft-ietf-xmpp-im-21.txt

pwlib源码库

   to one contact (not those from whom an error was received or to whom
   the user sent directed presence):

   <presence
       from='[e-mail]/orchard'
       to='[e-mail]'
       xml:lang='en'>
     <show>away</show>
     <status>I shall return!</status>
     <priority>1</priority>
   </presence>

   Example 9: Contact's server delivers updated presence information to
   all of the contact's available resources:

   [to "balcony" resource...]
   <presence
       from='[e-mail]/orchard'
       to='[e-mail]'
       xml:lang='en'>
     <show>away</show>
     <status>I shall return!</status>
     <priority>1</priority>
   </presence>

   [to "chamber" resource...]
   <presence
       from='[e-mail]/orchard'
       to='[e-mail]'
       xml:lang='en'>
     <show>away</show>



Saint-Andre (ed.)      Expires September 19, 2004              [Page 25]

Internet-Draft                  XMPP IM                       March 2004


     <status>I shall return!</status>
     <priority>1</priority>
   </presence>

   Example 10: One of the contact's resources broadcasts final presence:

   <presence from='[e-mail]/balcony' type='unavailable'/>

   Example 11: Contact's server sends unavailable presence information
   to user:

   <presence
       type='unavailable'
       from='[e-mail]/balcony'
       to='[e-mail]/orchard'/>

   Example 12: User sends final presence:

   <presence from='[e-mail]/orchard'
             type='unavailable'
             xml:lang='en'>
     <status>gone home</status>
   </presence>

   Example 13: User's server broadcasts unavailable presence information
   to contact as well as to the person to whom the user sent directed
   presence:

   <presence
       type='unavailable'
       from='[e-mail]/orchard'
       to='[e-mail]'
       xml:lang='en'>
     <status>gone home</status>
   </presence>

   <presence
       from='[e-mail]/orchard'
       to='[e-mail]'
       xml:lang='en'>
     <status>gone home</status>
   </presence>


6. Managing Subscriptions

   In order to protect the privacy of instant messaging users and any
   other entities, presence and availability information is disclosed



Saint-Andre (ed.)      Expires September 19, 2004              [Page 26]

Internet-Draft                  XMPP IM                       March 2004


   only to other entities that the user has approved.  When a user has
   agreed that another entity may view its presence, the entity is said
   to have a subscription to the user's presence information.  A
   subscription lasts across sessions; indeed, it lasts until the
   subscriber unsubscribes or the subscribee cancels the
   previously-granted subscription.  Subscriptions are managed within
   XMPP by sending presence stanzas containing specially-defined
   attributes.

   Note: There are important interactions between subscriptions and
   rosters; these are defined under Integration of Roster Items and
   Presence Subscriptions (Section 8), and the reader must refer to that
   section for a complete understanding of presence subscriptions.

6.1 Requesting a Subscription

   A request to subscribe to another entity's presence is made by
   sending a presence stanza of type "subscribe".

   Example: Sending a subscription request:

   <presence to='[e-mail]' type='subscribe'/>

   For client and server responsibilities regarding presence
   subscription requests, refer to Presence Subscriptions (Section
   5.1.6).

6.2 Handling a Subscription Request

   When a client receives a subscription request from another entity, it
   MUST either approve the request by sending a presence stanza of type
   "subscribed" or refuse the request by sending a presence stanza of
   type "unsubscribed".

   Example: Approving a subscription request:

   <presence to='[e-mail]' type='subscribed'/>

   Example: Refusing a presence subscription request:

   <presence to='[e-mail]' type='unsubscribed'/>


6.3 Cancelling a Subscription from Another Entity

   If a user would like to cancel a previously-granted subscription
   request, it sends a presence stanza of type "unsubscribed".




Saint-Andre (ed.)      Expires September 19, 2004              [Page 27]

Internet-Draft                  XMPP IM                       March 2004


   Example: Cancelling a previously granted subscription request:

   <presence to='[e-mail]' type='unsubscribed'/>


6.4 Unsubscribing from Another Entity's Presence

   If a user would like to unsubscribe from the presence of another
   entity, it sends a presence stanza of type "unsubscribe".

   Example: Unsubscribing from an entity's presence:

   <presence to='[e-mail]' type='unsubscribe'/>


7. Roster Management

   In XMPP, one's contact list is called a roster, which consists of any
   number of specific roster items, each roster item being identified by
   a unique JID (usually of the form <contact@domain>).  A user's roster
   is stored by the user's server on the user's behalf so that the user
   may access roster information from any resource.

   Note: There are important interactions between rosters and
   subscriptions; these are defined under Integration of Roster Items
   and Presence Subscriptions (Section 8), and the reader must refer to
   that section for a complete understanding of roster management.

7.1 Syntax and Semantics

   Rosters are managed using IQ stanzas, specifically by means of a
   <query/> child element qualified by the 'jabber:iq:roster' namespace.
   The <query/> element MAY contain one or more <item/> children, each
   describing a unique roster item or "contact".

   The "key" or unique identifier for each roster item is a JID,
   encapsulated in the 'jid' attribute of the <item/> element (which is
   REQUIRED).  The value of the 'jid' attribute SHOULD be of the form
   <user@domain> if the item is associated with another (human) instant
   messaging user.

   The state of the presence subscription in relation to a roster item
   is captured in the 'subscription' attribute of the <item/> element.
   Allowable values for this attribute are:

   o  "none" -- the user does not have a subscription to the contact's
      presence information, and the contact does not have a subscription
      to the user's presence information



Saint-Andre (ed.)      Expires September 19, 2004              [Page 28]

Internet-Draft                  XMPP IM                       March 2004


   o  "to" -- the user has a subscription to the contact's presence
      information, but the contact does not have a subscription to the
      user's presence information

   o  "from" -- the contact has a subscription to the user's presence
      information, but the user does not have a subscription to the
      contact's presence information

   o  "both" -- both the user and the contact have subscriptions to each
      other's presence information

   Each <item/> element MAY contain a 'name' attribute, which sets the
   "nickname" to be associated with the JID, as determined by the user
   (not the contact).  The value of the 'name' attribute is opaque.

   Each <item/> element MAY contain one or more <group/> child elements,
   for use in collecting roster items into various categories.  The XML
   character data of the <group/> element is opaque.

7.2 Business Rules

   A server MUST ignore any 'to' address on a roster "set", and MUST
   treat any roster "set" as applying to the sender.  For added safety,
   a client SHOULD check the "from" address of a "roster push" (incoming
   IQ of type "set" containing a roster item) to ensure that it is from
   a trusted source; specifically, the stanza MUST either have no 'from'
   attribute (i.e., implicitly from the server) or have a 'from'
   attribute whose value matches the user's bare JID (of the form
   <user@domain>) or full JID (of the form <user@domain/resource>);
   otherwise, the client SHOULD ignore the "roster push".

7.3 Retrieving One's Roster on Login

   Upon connecting to the server and sending available presence, a
   client SHOULD request the roster before sending initial presence
   (however, because receiving the roster may not be desirable for all
   resources, e.g., a connection with limited bandwidth, the client's
   request for the roster is OPTIONAL).  If an available resource does
   not request the roster during a session, the server MUST NOT send it
   presence subscriptions and associated roster updates.  If an
   unavailable resource requests the roster, the server SHOULD return an
   <unexpected-request/> error to the resource.

   Example: Client requests current roster from server:

   <iq from='[e-mail]/balcony' type='get' id='roster_1'>
     <query xmlns='jabber:iq:roster'/>
   </iq>



Saint-Andre (ed.)      Expires September 19, 2004              [Page 29]

Internet-Draft                  XMPP IM                       March 2004


   Example: Client receives roster from server:

   <iq to='[e-mail]/balcony' type='result' id='roster_1'>
     <query xmlns='jabber:iq:roster'>
       <item jid='[e-mail]'
             name='Romeo'
             subscription='both'>
         <group>Friends</group>
       </item>
       <item jid='[e-mail]'
             name='Mercutio'
             subscription='from'>
         <group>Friends</group>
       </item>
       <item jid='[e-mail]'
             name='Benvolio'
             subscription='both'>
         <group>Friends</group>
       </item>
     </query>
   </iq>


7.4 Adding a Roster Item

   At any time, a user MAY add an item to his or her roster.

   Example: Client adds a new item:

   <iq from='[e-mail]/balcony' type='set' id='roster_2'>
     <query xmlns='jabber:iq:roster'>
       <item jid='[e-mail]'
             name='Nurse'>
         <group>Servants</group>
       </item>
     </query>
   </iq>

   The server MUST update the roster information in persistent storage,
   and also push the change out to all of the user's available resources
   that have requested the roster.  This "roster push" consists of an IQ
   stanza of type "set" from the server to the client and enables all
   available resources to remain in sync with the server-based roster
   information.

   Example: Server (1) pushes the updated roster information to all
   available resources that have requested the roster and (2) replies
   with an IQ result to the sending resource:



Saint-Andre (ed.)      Expires September 19, 2004              [Page 30]

Internet-Draft                  XMPP IM                       March 2004


   <iq to='[e-mail]/balcony'
       type='set'
       id='a78b4q6ha463'>
     <query xmlns='jabber:iq:roster'>
       <item jid='[e-mail]'
             name='Nurse'
             subscription='none'>
         <group>Servants</group>
       </item>
     </query>
   </iq>

   <iq to='[e-mail]/chamber'
       type='set'
       id='a78b4q6ha464'>
     <query xmlns='jabber:iq:roster'>
       <item jid='[e-mail]'