Package org.jivesoftware.smackx.bytestreams.ibb

Class InBandBytestreamManager

  • All Implemented Interfaces:
    BytestreamManager
    public final class InBandBytestreamManager
extends Manager
implements BytestreamManager
    The InBandBytestreamManager class handles establishing In-Band Bytestreams as specified in the XEP-0047.

    The In-Band Bytestreams (IBB) enables two entities to establish a virtual bytestream over which they can exchange Base64-encoded chunks of data over XMPP itself. It is the fall-back mechanism in case the Socks5 bytestream method of transferring data is not available.

    There are two ways to send data over an In-Band Bytestream. It could either use IQ stanzas to send data packets or message stanzas. If IQ stanzas are used every data stanza is acknowledged by the receiver. This is the recommended way to avoid possible rate-limiting penalties. Message stanzas are not acknowledged because most XMPP server implementation don't support stanza flow-control method like Advanced Message Processing. To set the stanza that should be used invoke setStanza(StanzaType).

    To establish an In-Band Bytestream invoke the establishSession(Jid) method. This will negotiate an in-band bytestream with the given target JID and return a session.

    If a session ID for the In-Band Bytestream was already negotiated (e.g. while negotiating a file transfer) invoke establishSession(Jid, String).

    To handle incoming In-Band Bytestream requests add an InBandBytestreamListener to the manager. There are two ways to add this listener. If you want to be informed about incoming In-Band Bytestreams from a specific user add the listener by invoking addIncomingBytestreamListener(BytestreamListener, Jid). If the listener should respond to all In-Band Bytestream requests invoke addIncomingBytestreamListener(BytestreamListener).

    Note that the registered InBandBytestreamListener will NOT be notified on incoming In-Band bytestream requests sent in the context of XEP-0096 file transfer. (See FileTransferManager)

    If no InBandBytestreamListeners are registered, all incoming In-Band bytestream requests will be rejected by returning a <not-acceptable/> error to the initiator.

    • Method Detail

      • addIncomingBytestreamListener

        public void addIncomingBytestreamListener​(BytestreamListener listener,
                                          Jid initiatorJID)
        Adds InBandBytestreamListener that is called for every incoming in-band bytestream request from the given user.

        Use this method if you are awaiting an incoming Socks5 bytestream request from a specific user.

        If no listeners are registered all In-Band Bytestream request are rejected with a <not-acceptable/> error.

        Note that the registered InBandBytestreamListener will NOT be notified on incoming Socks5 bytestream requests sent in the context of XEP-0096 file transfer. (See FileTransferManager)

        Specified by:
        addIncomingBytestreamListener in interface BytestreamManager
        Parameters:
        listener - the listener to register
        initiatorJID - the JID of the user that wants to establish an In-Band Bytestream

      • ignoreBytestreamRequestOnce

        public void ignoreBytestreamRequestOnce​(java.lang.String sessionID)
        Use this method to ignore the next incoming In-Band Bytestream request containing the given session ID. No listeners will be notified for this request and and no error will be returned to the initiator.

        This method should be used if you are awaiting an In-Band Bytestream request as a reply to another stanza (e.g. file transfer).

        Parameters:
        sessionID - to be ignored

      • getDefaultBlockSize

        public int getDefaultBlockSize()
        Returns the default block size that is used for all outgoing in-band bytestreams for this connection.

        The recommended default block size is 4096 bytes. See XEP-0047 Section 5.

        Returns:
        the default block size

      • setDefaultBlockSize

        public void setDefaultBlockSize​(int defaultBlockSize)
        Sets the default block size that is used for all outgoing in-band bytestreams for this connection.

        The default block size must be between 1 and 65535 bytes. The recommended default block size is 4096 bytes. See XEP-0047 Section 5.

        Parameters:
        defaultBlockSize - the default block size to set

      • getMaximumBlockSize

        public int getMaximumBlockSize()
        Returns the maximum block size that is allowed for In-Band Bytestreams for this connection.

        Incoming In-Band Bytestream open request will be rejected with an <resource-constraint/> error if the block size is greater then the maximum allowed block size.

        The default maximum block size is 65535 bytes.

        Returns:
        the maximum block size

      • setMaximumBlockSize

        public void setMaximumBlockSize​(int maximumBlockSize)
        Sets the maximum block size that is allowed for In-Band Bytestreams for this connection.

        The maximum block size must be between 1 and 65535 bytes.

        Incoming In-Band Bytestream open request will be rejected with an <resource-constraint/> error if the block size is greater then the maximum allowed block size.

        Parameters:
        maximumBlockSize - the maximum block size to set

      • establishSession

        public InBandBytestreamSession establishSession​(Jid targetJID)
                                         throws XMPPException,
                                                SmackException,
                                                java.lang.InterruptedException
        Establishes an In-Band Bytestream with the given user and returns the session to send/receive data to/from the user.

        Use this method to establish In-Band Bytestreams to users accepting all incoming In-Band Bytestream requests since this method doesn't provide a way to tell the user something about the data to be sent.

        To establish an In-Band Bytestream after negotiation the kind of data to be sent (e.g. file transfer) use establishSession(Jid, String).

        Specified by:
        establishSession in interface BytestreamManager
        Parameters:
        targetJID - the JID of the user an In-Band Bytestream should be established
        Returns:
        the session to send/receive data to/from the user
        Throws:
        XMPPException - if the user doesn't support or accept in-band bytestreams, or if the user prefers smaller block sizes
        SmackException - if there was no response from the server.
        java.lang.InterruptedException - if the calling thread was interrupted.

      • replyRejectPacket

        protected void replyRejectPacket​(IQ request)
                          throws SmackException.NotConnectedException,
                                 java.lang.InterruptedException
        Responses to the given IQ packet's sender with an XMPP error that an In-Band Bytestream is not accepted.
        Parameters:
        request - IQ stanza that should be answered with a not-acceptable error
        Throws:
        SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.

      • replyItemNotFoundPacket

        protected void replyItemNotFoundPacket​(IQ request)
                                throws SmackException.NotConnectedException,
                                       java.lang.InterruptedException
        Responses to the given IQ packet's sender with an XMPP error that an In-Band Bytestream session could not be found.
        Parameters:
        request - IQ stanza that should be answered with a item-not-found error
        Throws:
        SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.

      • getIgnoredBytestreamRequests

        protected java.util.List<java.lang.String> getIgnoredBytestreamRequests()
        Returns the list of session IDs that should be ignored by the InitialtionListener
        Returns:
        list of session IDs