Documentation

Connecting to the XMPP server

In this section

Establishing the server connection

The application must connect to port 5222 on the server push.xmpp.yandex.ru.

If port 5222 is not available, port 443 can be used instead; for this port, an encrypted connection is required, so the server connection must start with a TLS handshake (step 3).

Steps for connecting to the XMPP server:

  1. Handshake.

    The application requests to create a stream:

    <?xml version="1.0"?>
    <stream:stream xmlns:stream="http://etherx.jabber.org/streams" version="1.0" xmlns="jabber:client" to="ya.ru" xml:lang="en" xmlns:xml="http://www.w3.org/XML/1998/namespace">

    The server returns the stream ID and information about available features (encryption, ZLIB compression, and SASL authorization):

    <?xml version='1.0'?>
    <stream:stream xmlns='jabber:client' xmlns:stream='http://etherx.jabber.org/streams' id='4235063168' from='ya.ru' version='1.0' xml:lang='en'>
    
    <stream:features>
      <starttls xmlns="urn:ietf:params:xml:ns:xmpp-tls"/>
      <compression xmlns="http://jabber.org/features/compress">
        <method>zlib</method>
      </compression>
      <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>
    </stream:features>
  2. Establishing an encrypted connection (TLS).

    The application sends the encryption request stanza:

    <starttls xmlns="urn:ietf:params:xml:ns:xmpp-tls"/>

    The server confirms the encrypted connection:

    <proceed xmlns="urn:ietf:params:xml:ns:xmpp-tls"/>
  3. TLS handshake. The application repeats the request to create a stream (see step 1), using an encrypted connection.

  4. If necessary, the application may request to compress the stream in ZLIB format. In the XMPP protocol, compression is described as an extension of the standard protocol: XEP-0138.
  5. Authorization. The application passes the server a Base64-encoded authorization token. The token must be formed from the user's login and the OAuth token, separating them with a zero byte, for example: test\00c4181a7c2cf4521964a72ff57a34a07.

    <auth xmlns="urn:ietf:params:xml:ns:xmpp-sasl" mechanism="X-YANDEX-OAUTH">dGVzdABjNDE4MWE3YzJjZjQ1MjE5NjRhNzJmZjU3YTM0YTA3</auth>

    When authorization is successful, the server responds with:

    <success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>
  6. Authorized handshake. The application requests to create a stream (see step 1). The server lists the features that are available after authorization.

  7. Setting up the resource. The application passes the resource name in the following stanza:

    <iq type="set" id="bind_1">
      <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind">
        <resource>YaDisk-client</resource>
      </bind>
    </iq>

    The server returns the JID assigned to the application, which should be used in the following requests:

    <iq xmlns="jabber:client" type="result" id="bind_1">
      <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind">
        <jid>test@ya.ru/YaDisk-client</jid>
      </bind>
    </iq>
  8. Opening a session. The application requests to open a session:

    <iq type="set" id="session_1">
      <session xmlns="urn:ietf:params:xml:ns:xmpp-session"/>
    </iq>

    The server responds with the result of opening the session:

    <iq type="result" id="session_1">
    <session xmlns="urn:ietf:params:xml:ns:xmpp-session"/>
    </iq>
  9. Request for the client version (XEP-0092).

    After the session is opened, the server requests the version of the client application:

    <iq from="ya.ru" type="get" to="test@ya.ru/YaDisk-client" id="ask_version">
    <query xmlns="jabber:iq:version"/>
    </iq>

    The application should return its own name, the application version number and, optionally, the OS version:

    <iq type="result" to="ya.ru" id="ask_version">
      <query xmlns="jabber:iq:version">
        <name>YaDiskClient</name>
        <version>1.1</version>
        <os>Mac OS X</os>
      </query>
    </iq>

After the connection has been established, the server periodically checks the connection with the application by sending the following types of requests:

<iq from="ya.ru" type="get" to="test@ya.ru/YaDisk-client" id="ping_1">
  <ping xmlns="urn:xmpp:ping"/>
</iq>

The application should respond in the following way, copying the value of the id attribute from the server request to its response:

<iq type="result" to="ya.ru" id="ping_1"/>

Closing a connection

When finished, the application should close the XMPP stream by sending the server the closing string:

</stream:stream>