Package org.jivesoftware.smackx.bytestreams.ibb

Class InBandBytestreamManager

java.lang.Object
org.jivesoftware.smack.Manager
org.jivesoftware.smackx.bytestreams.ibb.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.

  • Field Details

  • Method Details

    • getByteStreamManager

      public static InBandBytestreamManager getByteStreamManager(XMPPConnection connection)
      Returns the InBandBytestreamManager to handle In-Band Bytestreams for a given XMPPConnection.
      Parameters:
      connection - the XMPP connection
      Returns:
      the InBandBytestreamManager for the given XMPP connection

    • addIncomingBytestreamListener

      public void addIncomingBytestreamListener(BytestreamListener listener)
      Adds InBandBytestreamListener that is called for every incoming in-band bytestream request unless there is a user specific InBandBytestreamListener registered.

      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

    • removeIncomingBytestreamListener

      public void removeIncomingBytestreamListener(BytestreamListener listener)
      Removes the given listener from the list of listeners for all incoming In-Band Bytestream requests.
      Specified by:
      removeIncomingBytestreamListener in interface BytestreamManager
      Parameters:
      listener - the listener to remove

    • 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

    • removeIncomingBytestreamListener

      public void removeIncomingBytestreamListener(Jid initiatorJID)
      Removes the listener for the given user.
      Specified by:
      removeIncomingBytestreamListener in interface BytestreamManager
      Parameters:
      initiatorJID - the JID of the user the listener should be removed

    • ignoreBytestreamRequestOnce

      public void ignoreBytestreamRequestOnce(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

    • getStanza

      public InBandBytestreamManager.StanzaType getStanza()
      Returns the stanza used to send data packets.

      Default is InBandBytestreamManager.StanzaType.IQ. See XEP-0047 Section 4.

      Returns:
      the stanza used to send data packets

    • setStanza

      public void setStanza(InBandBytestreamManager.StanzaType stanza)
      Sets the stanza used to send data packets.

      The use of InBandBytestreamManager.StanzaType.IQ is recommended. See XEP-0047 Section 4.

      Parameters:
      stanza - the stanza to set

    • establishSession

      public InBandBytestreamSession establishSession(Jid targetJID) throws XMPPException, SmackException, 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.
      InterruptedException - if the calling thread was interrupted.

    • establishSession

      public InBandBytestreamSession establishSession(Jid targetJID, String sessionID) throws SmackException.NoResponseException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException
      Establishes an In-Band Bytestream with the given user using the given session ID and returns the session to send/receive data to/from the user.
      Specified by:
      establishSession in interface BytestreamManager
      Parameters:
      targetJID - the JID of the user an In-Band Bytestream should be established
      sessionID - the session ID for the In-Band Bytestream request
      Returns:
      the session to send/receive data to/from the user
      Throws:
      XMPPException.XMPPErrorException - if the user doesn't support or accept in-band bytestreams, or if the user prefers smaller block sizes
      SmackException.NoResponseException - if there was no response from the server.
      SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.