ibb — In-Band Bytestreams (XEP-0047)

This subpackage provides support for in-band bytestreams. The bytestreams are exposed as instances of asyncio.Transport, which allows to speak any protocol implemented as asyncio.Protocol over them.

class aioxmpp.ibb.IBBService(client, **kwargs)

A service implementing in-band bytestreams.

Methods for establishing sessions:

expect_session(protocol_factory, peer_jid, sid)

Whitelist the session with peer_jid and the session id sid and return it when it is established. This is meant to be used with signalling protocols like Jingle and is the counterpart to open_session().

Returns

an awaitable object, whose result is the tuple (transport, protocol)

async open_session(protocol_factory, peer_jid, *, stanza_type=<IBBStanzaType.IQ: 'iq'>, block_size=4096, sid=None)

Establish an in-band bytestream session with peer_jid and return the transport and protocol.

Parameters

• protocol_factory (a nullary callable returning an asyncio.Protocol instance) – the protocol factory

• peer_jid (aioxmpp.JID) – the JID with which to establish the byte-stream.

• stanza_type (class:~aioxmpp.ibb.IBBStanzaType) – the stanza type to use

• block_size (int) – the maximal size of blocks to transfer

• sid (str (must be a valid NMTOKEN)) – the session id to use

Returns

the transport and protocol

Return type

a tuple of aioxmpp.ibb.service.IBBTransport and asyncio.Protocol

The following attributes control the establishment of sessions due to a received request, that was not announced to the service by expect_session():

session_limit = 0

The maximal number of sessions to be accepted. If there are that many or more active sessions, no new sessions are accepted, unless they are whitelisted by expect_session(). (This means, that by default only expected sessions are accepted!).

default_protocol_factory

The protocol factory to be used when an unexpected connection is established. This must be set when changing session_limit to a non-zero value.

signal on_session_accepted(transport, protocol)

Fires when a session is established due to a received open request that was not expected (compare expect_session()). This can only happen when session_limit is set to another value than its default value.

The following attributes control how the IBB sessions react to errors of type wait:

max_retries = 5

The number of times it is tried to resend a data stanza, when a XMPPWaitError is received. When max_retries have been tried, the session is closed. connection_lost of the protocol receives an asyncio.TimeoutError.

initial_wait_time = timedelta(seconds=1)

The time to wait when receiving a XMPPWaitError for the first time.

wait_backoff_factor = 1.2

The factor by which the wait time is prolonged on each successive wait error.

class aioxmpp.ibb.IBBStanzaType(value)

Enumeration of the the two stanza types supported by IBB for transporting data.

IQ

Send the in-band bytestream data using IQ stanzas. This is recommended and default. The reply mechanism of IQ allows tracking the connectivitiy and implements basic rate limiting, since we wait for the reply to the previous message before sending a new one.

MESSAGE

Send the in-band bytestream data using Message stanzas. This is not recommended since lost packages due to intermittent connectivity failures will not be obvious.

class aioxmpp.ibb.service.IBBTransport

The transport for IBB sessions.

Note

Never instantiate this class directly, all instances of this class are created the methods open_session() and expect_session() of IBBService.

The following keys are supported for get_extra_info():

block_size

The maximal block size of data in a IBB stanza.

peer_jid

The JID of the peer.

sid

The session id of the unerlying IBB session.

stanza_type

The used stanza type.

For serializing and deserializing data payloads carried by Message stanzas, a descriptor is added to them:

aioxmpp.Message.xep0047_data