Package org.jivesoftware.smackx.bytestreams.socks5

Class Socks5BytestreamManager

java.lang.Object
org.jivesoftware.smack.Manager
org.jivesoftware.smackx.bytestreams.socks5.Socks5BytestreamManager
All Implemented Interfaces:
BytestreamManager
public final class Socks5BytestreamManager extends org.jivesoftware.smack.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 Summary

    Modifier and Type
    Method
    Description
    void
    addIncomingBytestreamListener(BytestreamListener listener)
    Adds BytestreamListener that is called for every incoming SOCKS5 Bytestream request unless there is a user specific BytestreamListener registered.
    void
    addIncomingBytestreamListener(BytestreamListener listener, org.jxmpp.jid.Jid initiatorJID)
    Adds BytestreamListener that is called for every incoming SOCKS5 Bytestream request from the given user.
    List<org.jxmpp.jid.Jid>
    determineProxies()
    Returns a list of JIDs of SOCKS5 proxies by querying the XMPP server.
    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.
    Socks5BytestreamSession
    establishSession(org.jxmpp.jid.Jid targetJID)
    Establishes a SOCKS5 Bytestream with the given user and returns the Socket to send/receive data to/from the user.
    Socks5BytestreamSession
    establishSession(org.jxmpp.jid.Jid targetJID, String sessionID)
    Establishes a SOCKS5 Bytestream with the given user using the given session ID and returns the Socket to send/receive data to/from the user.
    static Socks5BytestreamManager
    getBytestreamManager(org.jivesoftware.smack.XMPPConnection connection)
    Returns the Socks5BytestreamManager to handle SOCKS5 Bytestreams for a given XMPPConnection.
    List<Bytestream.StreamHost>
    getLocalStreamHost()
    Returns the stream host information of the local SOCKS5 proxy containing the IP address and the port.
    int
    getProxyConnectionTimeout()
    Returns the timeout for connecting to the SOCKS5 proxy selected by the target.
    int
    getTargetResponseTimeout()
    Returns the timeout to wait for the response to the SOCKS5 Bytestream initialization request.
    void
    ignoreBytestreamRequestOnce(String sessionID)
    Use this method to ignore the next incoming SOCKS5 Bytestream request containing the given session ID.
    boolean
    isAnnouncingLocalStreamHostEnabled()
    Returns if the bytestream manager will announce the local stream host(s), i.e.
    boolean
    isProxyPrioritizationEnabled()
    Returns if the prioritization of the last working SOCKS5 proxy on successive SOCKS5 Bytestream connections is enabled.
    void
    removeIncomingBytestreamListener(BytestreamListener listener)
    Removes the given listener from the list of listeners for all incoming SOCKS5 Bytestream requests.
    void
    removeIncomingBytestreamListener(org.jxmpp.jid.Jid initiatorJID)
    Removes the listener for the given user.
    void
    setAnnounceLocalStreamHost(boolean announceLocalStreamHost)
    Set whether the bytestream manager will announce the local stream host(s), i.e.
    void
    setProxyConnectionTimeout(int proxyConnectionTimeout)
    Sets the timeout for connecting to the SOCKS5 proxy selected by the target.
    void
    setProxyPrioritizationEnabled(boolean proxyPrioritizationEnabled)
    Enable/disable the prioritization of the last working SOCKS5 proxy on successive SOCKS5 Bytestream connections.
    void
    setTargetResponseTimeout(int targetResponseTimeout)
    Sets the timeout to wait for the response to the SOCKS5 Bytestream initialization request.

    Methods inherited from class org.jivesoftware.smack.Manager

    connection, getAuthenticatedConnectionOrThrow, schedule, schedule, scheduleBlocking

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • getBytestreamManager

      public static Socks5BytestreamManager getBytestreamManager(org.jivesoftware.smack.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)
      Adds BytestreamListener that is called for every incoming SOCKS5 Bytestream request unless there is a user specific BytestreamListener registered.

      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

    • removeIncomingBytestreamListener

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

    • addIncomingBytestreamListener

      public void addIncomingBytestreamListener(BytestreamListener listener, org.jxmpp.jid.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

    • removeIncomingBytestreamListener

      public void removeIncomingBytestreamListener(org.jxmpp.jid.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 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 the bytestream manager will announce the local stream host(s), i.e. the local SOCKS5 proxy.
      Parameters:
      announceLocalStreamHost - TODO javadoc me please
      Since:
      4.4.0
      See Also:

    • establishSession

      public Socks5BytestreamSession establishSession(org.jxmpp.jid.Jid targetJID) throws org.jivesoftware.smack.XMPPException, IOException, InterruptedException, org.jivesoftware.smack.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:
      org.jivesoftware.smack.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
      IOException - if the bytestream could not be established
      InterruptedException - if the current thread was interrupted while waiting
      org.jivesoftware.smack.SmackException - if there was no response from the server.

    • establishSession

      public Socks5BytestreamSession establishSession(org.jxmpp.jid.Jid targetJID, String sessionID) throws IOException, InterruptedException, org.jivesoftware.smack.XMPPException, org.jivesoftware.smack.SmackException.NoResponseException, org.jivesoftware.smack.SmackException.NotConnectedException, org.jivesoftware.smack.SmackException.SmackMessageException, org.jivesoftware.smack.SmackException.FeatureNotSupportedException
      Establishes a SOCKS5 Bytestream with the given user using the given session ID and returns the Socket to send/receive data to/from the user.
      Specified by:
      establishSession in interface BytestreamManager
      Parameters:
      targetJID - the JID of the user a SOCKS5 Bytestream should be established
      sessionID - the session ID for the SOCKS5 Bytestream request
      Returns:
      the Socket to send/receive data to/from the user
      Throws:
      IOException - if the bytestream could not be established
      InterruptedException - if the current thread was interrupted while waiting
      org.jivesoftware.smack.XMPPException - if an XMPP protocol error was received.
      org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
      org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
      org.jivesoftware.smack.SmackException.SmackMessageException - if there was an error.
      org.jivesoftware.smack.SmackException.FeatureNotSupportedException - if a requested feature is not supported by the remote entity.

    • determineProxies

      public List<org.jxmpp.jid.Jid> determineProxies() throws org.jivesoftware.smack.SmackException.NoResponseException, org.jivesoftware.smack.XMPPException.XMPPErrorException, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException
      Returns a list of JIDs of SOCKS5 proxies by querying the XMPP server. The SOCKS5 proxies are in the same order as returned by the XMPP server.
      Returns:
      list of JIDs of SOCKS5 proxies
      Throws:
      org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an error querying the XMPP server for SOCKS5 proxies
      org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the server.
      org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.

    • getLocalStreamHost

      public 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