1d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen/** 2d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); 3d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * you may not use this file except in compliance with the License. 4d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * You may obtain a copy of the License at 5d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 6d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * http://www.apache.org/licenses/LICENSE-2.0 7d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 8d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Unless required by applicable law or agreed to in writing, software 9d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * distributed under the License is distributed on an "AS IS" BASIS, 10d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * See the License for the specific language governing permissions and 12d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * limitations under the License. 13d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 14d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chenpackage org.jivesoftware.smackx.bytestreams; 15d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 16d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chenimport java.io.IOException; 17d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 18d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chenimport org.jivesoftware.smack.XMPPException; 19d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chenimport org.jivesoftware.smackx.bytestreams.ibb.InBandBytestreamManager; 20d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chenimport org.jivesoftware.smackx.bytestreams.socks5.Socks5BytestreamManager; 21d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 22d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen/** 23d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * BytestreamManager provides a generic interface for bytestream managers. 24d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * <p> 25d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * There are two implementations of the interface. See {@link Socks5BytestreamManager} and 26d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * {@link InBandBytestreamManager}. 27d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 28d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @author Henning Staib 29d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 30d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chenpublic interface BytestreamManager { 31d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 32d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen /** 33d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Adds {@link BytestreamListener} that is called for every incoming bytestream request unless 34d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * there is a user specific {@link BytestreamListener} registered. 35d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * <p> 36d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * See {@link Socks5BytestreamManager#addIncomingBytestreamListener(BytestreamListener)} and 37d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * {@link InBandBytestreamManager#addIncomingBytestreamListener(BytestreamListener)} for further 38d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * details. 39d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 40d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param listener the listener to register 41d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 42d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen public void addIncomingBytestreamListener(BytestreamListener listener); 43d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 44d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen /** 45d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Removes the given listener from the list of listeners for all incoming bytestream requests. 46d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 47d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param listener the listener to remove 48d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 49d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen public void removeIncomingBytestreamListener(BytestreamListener listener); 50d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 51d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen /** 52d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Adds {@link BytestreamListener} that is called for every incoming bytestream request unless 53d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * there is a user specific {@link BytestreamListener} registered. 54d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * <p> 55d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Use this method if you are awaiting an incoming bytestream request from a specific user. 56d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * <p> 57d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * See {@link Socks5BytestreamManager#addIncomingBytestreamListener(BytestreamListener, String)} 58d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * and {@link InBandBytestreamManager#addIncomingBytestreamListener(BytestreamListener, String)} 59d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * for further details. 60d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 61d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param listener the listener to register 62d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param initiatorJID the JID of the user that wants to establish a bytestream 63d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 64d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen public void addIncomingBytestreamListener(BytestreamListener listener, String initiatorJID); 65d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 66d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen /** 67d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Removes the listener for the given user. 68d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 69d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param initiatorJID the JID of the user the listener should be removed 70d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 71d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen public void removeIncomingBytestreamListener(String initiatorJID); 72d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 73d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen /** 74d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Establishes a bytestream with the given user and returns the session to send/receive data 75d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * to/from the user. 76d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * <p> 77d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Use this method to establish bytestreams to users accepting all incoming bytestream requests 78d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * since this method doesn't provide a way to tell the user something about the data to be sent. 79d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * <p> 80d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * To establish a bytestream after negotiation the kind of data to be sent (e.g. file transfer) 81d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * use {@link #establishSession(String, String)}. 82d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * <p> 83d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * See {@link Socks5BytestreamManager#establishSession(String)} and 84d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * {@link InBandBytestreamManager#establishSession(String)} for further details. 85d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 86d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param targetJID the JID of the user a bytestream should be established 87d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @return the session to send/receive data to/from the user 88d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @throws XMPPException if an error occurred while establishing the session 89d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @throws IOException if an IO error occurred while establishing the session 90d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @throws InterruptedException if the thread was interrupted while waiting in a blocking 91d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * operation 92d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 93d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen public BytestreamSession establishSession(String targetJID) throws XMPPException, IOException, 94d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen InterruptedException; 95d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 96d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen /** 97d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * Establishes a bytestream with the given user and returns the session to send/receive data 98d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * to/from the user. 99d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * <p> 100d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * See {@link Socks5BytestreamManager#establishSession(String)} and 101d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * {@link InBandBytestreamManager#establishSession(String)} for further details. 102d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * 103d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param targetJID the JID of the user a bytestream should be established 104d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @param sessionID the session ID for the bytestream request 105d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @return the session to send/receive data to/from the user 106d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @throws XMPPException if an error occurred while establishing the session 107d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @throws IOException if an IO error occurred while establishing the session 108d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * @throws InterruptedException if the thread was interrupted while waiting in a blocking 109d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen * operation 110d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen */ 111d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen public BytestreamSession establishSession(String targetJID, String sessionID) 112d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen throws XMPPException, IOException, InterruptedException; 113d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen 114d7955ce24d294fb2014c59d11fca184471056f44Shuyi Chen} 115