# `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, 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, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  > 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