Package org.jivesoftware.smackx.bytestreams.socks5

Class Socks5BytestreamManager

  • All Implemented Interfaces:
    BytestreamManager
    public final class Socks5BytestreamManager
extends Manager
implements BytestreamManager
    The Socks5BytestreamManager class handles establishing SOCKS5 Bytestreams as specified in the XEP-0065.

    A SOCKS5 Bytestream is negotiated partly over the XMPP XML stream and partly over a separate socket. The actual transfer though takes place over a separately created socket.

    A SOCKS5 Bytestream generally has three parties, the initiator, the target, and the stream host. The stream host is a specialized SOCKS5 proxy setup on a server, or, the initiator can act as the stream host.

    To establish a SOCKS5 Bytestream invoke the establishSession(Jid) method. This will negotiate a SOCKS5 Bytestream with the given target JID and return a socket.

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

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

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

    If no Socks5BytestreamListeners are registered, all incoming SOCKS5 Bytestream requests will be rejected by returning a <not-acceptable/> error to the initiator.

    • Method Detail

      • getBytestreamManager

        public static Socks5BytestreamManager getBytestreamManager​(XMPPConnection connection)
        Returns the Socks5BytestreamManager to handle SOCKS5 Bytestreams for a given XMPPConnection.

        If no manager exists a new is created and initialized.

        Parameters:
        connection - the XMPP connection or null if given connection is null
        Returns:
        the Socks5BytestreamManager for the given XMPP connection

      • addIncomingBytestreamListener

        public void addIncomingBytestreamListener​(BytestreamListener listener,
                                          Jid initiatorJID)
        Adds BytestreamListener that is called for every incoming SOCKS5 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 SOCKS5 Bytestream request are rejected with a <not-acceptable/> error.

        Note that the registered BytestreamListener 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 a SOCKS5 Bytestream

      • ignoreBytestreamRequestOnce

        public void ignoreBytestreamRequestOnce​(java.lang.String sessionID)
        Use this method to ignore the next incoming SOCKS5 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 a SOCKS5 Bytestream request as a reply to another stanza (e.g. file transfer).

        Parameters:
        sessionID - to be ignored

      • disableService

        public void disableService()
        Disables the SOCKS5 Bytestream manager by removing the SOCKS5 Bytestream feature from the service discovery, disabling the listener for SOCKS5 Bytestream initiation requests and resetting its internal state, which includes removing this instance from the managers map.

        To re-enable the SOCKS5 Bytestream feature invoke getBytestreamManager(XMPPConnection). Using the file transfer API will automatically re-enable the SOCKS5 Bytestream feature.

      • getTargetResponseTimeout

        public int getTargetResponseTimeout()
        Returns the timeout to wait for the response to the SOCKS5 Bytestream initialization request. Default is 10000ms.
        Returns:
        the timeout to wait for the response to the SOCKS5 Bytestream initialization request

      • setTargetResponseTimeout

        public void setTargetResponseTimeout​(int targetResponseTimeout)
        Sets the timeout to wait for the response to the SOCKS5 Bytestream initialization request. Default is 10000ms.
        Parameters:
        targetResponseTimeout - the timeout to set

      • getProxyConnectionTimeout

        public int getProxyConnectionTimeout()
        Returns the timeout for connecting to the SOCKS5 proxy selected by the target. Default is 10000ms.
        Returns:
        the timeout for connecting to the SOCKS5 proxy selected by the target

      • setProxyConnectionTimeout

        public void setProxyConnectionTimeout​(int proxyConnectionTimeout)
        Sets the timeout for connecting to the SOCKS5 proxy selected by the target. Default is 10000ms.
        Parameters:
        proxyConnectionTimeout - the timeout to set

      • isProxyPrioritizationEnabled

        public boolean isProxyPrioritizationEnabled()
        Returns if the prioritization of the last working SOCKS5 proxy on successive SOCKS5 Bytestream connections is enabled. Default is true.
        Returns:
        true if prioritization is enabled, false otherwise

      • setProxyPrioritizationEnabled

        public void setProxyPrioritizationEnabled​(boolean proxyPrioritizationEnabled)
        Enable/disable the prioritization of the last working SOCKS5 proxy on successive SOCKS5 Bytestream connections.
        Parameters:
        proxyPrioritizationEnabled - enable/disable the prioritization of the last working SOCKS5 proxy

      • isAnnouncingLocalStreamHostEnabled

        public boolean isAnnouncingLocalStreamHostEnabled()
        Returns if the bytestream manager will announce the local stream host(s), i.e. the local SOCKS5 proxy.

        Local stream hosts will be announced if this option is enabled and at least one is running.

        Returns:
        true if
        Since:
        4.4.0

      • setAnnounceLocalStreamHost

        public void setAnnounceLocalStreamHost​(boolean announceLocalStreamHost)
        Set whether or not the bytestream manager will annouce the local stream host(s), i.e. the local SOCKS5 proxy.
        Parameters:
        announceLocalStreamHost - TODO javadoc me please
        Since:
        4.4.0
        See Also:
        isAnnouncingLocalStreamHostEnabled()

      • establishSession

        public Socks5BytestreamSession establishSession​(Jid targetJID)
                                         throws XMPPException,
                                                java.io.IOException,
                                                java.lang.InterruptedException,
                                                SmackException
        Establishes a SOCKS5 Bytestream with the given user and returns the Socket to send/receive data to/from the user.

        Use this method to establish SOCKS5 Bytestreams to users accepting all incoming Socks5 bytestream requests since this method doesn't provide a way to tell the user something about the data to be sent.

        To establish a SOCKS5 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 a SOCKS5 Bytestream should be established
        Returns:
        the Socket to send/receive data to/from the user
        Throws:
        XMPPException - if the user doesn't support or accept SOCKS5 Bytestreams, if no Socks5 Proxy could be found, if the user couldn't connect to any of the SOCKS5 Proxies
        java.io.IOException - if the bytestream could not be established
        java.lang.InterruptedException - if the current thread was interrupted while waiting
        SmackException - if there was no response from the server.

      • getLocalStreamHost

        public java.util.List<Bytestream.StreamHost> getLocalStreamHost()
        Returns the stream host information of the local SOCKS5 proxy containing the IP address and the port. The returned list may be empty if the local SOCKS5 proxy is not running.
        Returns:
        the stream host information of the local SOCKS5 proxy

      • replyRejectPacket

        protected void replyRejectPacket​(IQ packet)
                          throws SmackException.NotConnectedException,
                                 java.lang.InterruptedException
        Responses to the given packet's sender with an XMPP error that a SOCKS5 Bytestream is not accepted.

        Specified in XEP-65 5.3.1 (Example 13)

        Parameters:
        packet - 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.

      • getUserListener

        protected BytestreamListener getUserListener​(Jid initiator)
        Returns the BytestreamListener that should be informed if a SOCKS5 Bytestream request from the given initiator JID is received.
        Parameters:
        initiator - the initiator's JID
        Returns:
        the listener

      • 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