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