Programming XMPP Clients

'''This page is very old. (READ RFC 6120 / RFC 6121 / RFC 6122)'''

Basic Notes
You must know there is:
 * 1)  - for command exchanges
 * 2) - to transfer messages ;)
 * 3) - to exchange presence information

You can send these items only within a XML stream. Usually these items should also contain:
 * 1) to - where the item should be delivered (example: to='user2@server2.com' or to='service3.server4.org')
 * 2) id - as identification for this item (important for iq)
 * 3) type - in example get, set, result, error as the basic types in a iq

Sounds complicate? Nah, it is not ;) You will know when the time comes...

In case an item does not contain a to the item will be delivered to user's own XMPP server!

Connecting to a server
Usually a XMPP server listens on port 5222 (TCP). As soon as you have connected and established a XML stream the server expects authentification as a user. Depending on server settings an option to create a new account is offered, too.

For a normal TCP socket the stream is established like this (RFC 3920 Section 4.8.):

C:   S:   ... encryption, authentication, and resource binding ... C:   C:    Art thou not Romeo, and a Montague? C:     S:    S:    Neither, fair saint, if either thee dislike. S:     C:  S: 
 * A basic "session":

C:   S:   ... encryption, authentication, and resource binding ... C:  Bad XML, no closing body tag! S:   </stream:error> S: </stream:stream>
 * A "session" gone bad:

Secure connections

 * Note, there are two layers of security to consider:
 * Client <-> Server (encryption of the TCP connection; TLS and SASL should be used)
 * Client <-> Client (data exchange between clients, in example an instant message; this should be done with GnuPG)

Creating a new account
Currently there is no official standard about how to create or delete an account. Anyway the existing servers still support the old way.

To create an account the client must not be authenticated.


 * 1) Request the required information.
 * 2) Register.

C: <iq type='get' id='reg1'> <query xmlns='jabber:iq:register'/> </iq> S: <iq type='result' id='reg1'> <query xmlns='jabber:iq:register'> </iq> C: <iq type='set' id='reg2'> <query xmlns='jabber:iq:register'> hax0r god </iq>
 * Example for registering a new account:

The Server might respond with success... S: <iq type='result' id='reg2'> <query xmlns='jabber:iq:register'/> </iq>

or with an error: S: <iq type='error' id='reg2'> <query xmlns='jabber:iq:register'> edrin pwd <error code='409'> Username Not Available </iq>

Sorry, I don't remember right now
 * To delete an account the client must be authenticated - of course - and send:

The log-in-process (aka authentication with a server or service)
NOTE: This section is out of date! XMPP uses SASL for authentication, as described in RFC 6120. The stanzas described here are a legacy protocol that is discontinued in many servers today.

More details are described in XEP-0078: Non-SASL Authentication.

Under some circumstances you might want to provide the password as a digest; see XEP-0078: Non-SASL Authentication for more details about this.

For authentication with XMPP servers and services the jabber:iq:auth namespace must be used:
 * 1) Client requests required fields from server.
 * 2) Client authentication.

C: <iq type='get' to='shakespeare.lit' id='auth1'> <query xmlns='jabber:iq:auth'> bill </iq>
 * Example:

S: <iq type='result' id='auth1'> <query xmlns='jabber:iq:auth'> </iq>

C: <iq type='set' id='auth2'> <query xmlns='jabber:iq:auth'> bill Calli0pe office </iq>

On success server will respond with: S: <iq type='result' id='auth2'/>

Server Informs Client of Failed Authentication (Incorrect Credentials): S: <iq type='error' id='auth2'> <error code='401' type='auth'> <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> </iq>

Server Informs Client of Failed Authentication (Resource Conflict): S: <iq type='error' id='auth2'> <error code='409' type='cancel'> <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> </iq>

Server Informs Client of Failed Authentication (Required Information Not Provided). S: <iq type='error' id='auth2'> <error code='406' type='modify'> <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> </iq>

Sending a message
The information provided here conforms to RFC 3921 Section 4.

First lets take a look at the most complex situation.

C: <message to='romeo@example.net' from='juliet@example.com/balcony' type='chat' xml:lang='en'> I implore you! <subject xml:lang='cz'>&#x00DA;p&#x011B;nliv&#x011B; prosim! Wherefore art thou, Romeo? <body xml:lang='cz'>Pro&#x010D;e&#x017D; jsi ty, Romeo? e0ffe42b28561960c6b12b944a092794b9683a38
 * A message with all message features in use:

Ok, here is the explaination;
 * 1) to - specifies the receiver - of course it should be required.
 * 2) from - the server routing your message should fill this for you; just leave away.
 * 3) type - specifies how romeo's client should handle the messag.
 * 4) normal or left away - a small message window should pop up.
 * 5) chat - a chat window should pop up.
 * 6) headline - message should be handled as a news feed - no response is expected.
 * 7) groupchat - for multi-user chat environment; see the according section in this guide.
 * 8) error - well, an error message; for details regarding stanza error syntax, refer to RFC 3920.
 * 9) xml:lang - the default language of text in this message; this is not supported by any client I know of yet.
 * 10) subject - useful especially for type 'normal' and type 'headline'; not supported in combination with type 'chat' in most clients.
 * 11) body - yes, this is the message text ;)
 * 12) thread - a very optional thing, clients could have several message/chat sessions at the same time; usually this is not really required, many clients are even ignoring this thing but they should not of course!

C: <message to='juliet@example.com'> I love you! Meet at six? ;) Romeo
 * And here a very basic message: