001/** 002 * 003 * Copyright the original author or authors 004 * 005 * Licensed under the Apache License, Version 2.0 (the "License"); 006 * you may not use this file except in compliance with the License. 007 * You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.jivesoftware.smackx.bytestreams; 018 019import java.io.IOException; 020 021import org.jivesoftware.smack.SmackException; 022import org.jivesoftware.smack.XMPPException; 023import org.jivesoftware.smackx.bytestreams.ibb.InBandBytestreamManager; 024import org.jivesoftware.smackx.bytestreams.socks5.Socks5BytestreamManager; 025import org.jxmpp.jid.Jid; 026 027/** 028 * BytestreamManager provides a generic interface for bytestream managers. 029 * <p> 030 * There are two implementations of the interface. See {@link Socks5BytestreamManager} and 031 * {@link InBandBytestreamManager}. 032 * 033 * @author Henning Staib 034 */ 035public interface BytestreamManager { 036 037 /** 038 * Adds {@link BytestreamListener} that is called for every incoming bytestream request unless 039 * there is a user specific {@link BytestreamListener} registered. 040 * <p> 041 * See {@link Socks5BytestreamManager#addIncomingBytestreamListener(BytestreamListener)} and 042 * {@link InBandBytestreamManager#addIncomingBytestreamListener(BytestreamListener)} for further 043 * details. 044 * 045 * @param listener the listener to register 046 */ 047 public void addIncomingBytestreamListener(BytestreamListener listener); 048 049 /** 050 * Removes the given listener from the list of listeners for all incoming bytestream requests. 051 * 052 * @param listener the listener to remove 053 */ 054 public void removeIncomingBytestreamListener(BytestreamListener listener); 055 056 /** 057 * Adds {@link BytestreamListener} that is called for every incoming bytestream request unless 058 * there is a user specific {@link BytestreamListener} registered. 059 * <p> 060 * Use this method if you are awaiting an incoming bytestream request from a specific user. 061 * <p> 062 * See {@link Socks5BytestreamManager#addIncomingBytestreamListener(BytestreamListener, Jid)} 063 * and {@link InBandBytestreamManager#addIncomingBytestreamListener(BytestreamListener, Jid)} 064 * for further details. 065 * 066 * @param listener the listener to register 067 * @param initiatorJID the JID of the user that wants to establish a bytestream 068 */ 069 public void addIncomingBytestreamListener(BytestreamListener listener, Jid initiatorJID); 070 071 /** 072 * Removes the listener for the given user. 073 * 074 * @param initiatorJID the JID of the user the listener should be removed 075 */ 076 public void removeIncomingBytestreamListener(String initiatorJID); 077 078 /** 079 * Establishes a bytestream with the given user and returns the session to send/receive data 080 * to/from the user. 081 * <p> 082 * Use this method to establish bytestreams to users accepting all incoming bytestream requests 083 * since this method doesn't provide a way to tell the user something about the data to be sent. 084 * <p> 085 * To establish a bytestream after negotiation the kind of data to be sent (e.g. file transfer) 086 * use {@link #establishSession(Jid, String)}. 087 * <p> 088 * See {@link Socks5BytestreamManager#establishSession(Jid)} and 089 * {@link InBandBytestreamManager#establishSession(Jid)} for further details. 090 * 091 * @param targetJID the JID of the user a bytestream should be established 092 * @return the session to send/receive data to/from the user 093 * @throws XMPPException if an error occurred while establishing the session 094 * @throws IOException if an IO error occurred while establishing the session 095 * @throws InterruptedException if the thread was interrupted while waiting in a blocking 096 * operation 097 */ 098 public BytestreamSession establishSession(Jid targetJID) throws XMPPException, IOException, 099 InterruptedException, SmackException; 100 101 /** 102 * Establishes a bytestream with the given user and returns the session to send/receive data 103 * to/from the user. 104 * <p> 105 * See {@link Socks5BytestreamManager#establishSession(Jid)} and 106 * {@link InBandBytestreamManager#establishSession(Jid)} for further details. 107 * 108 * @param targetJID the JID of the user a bytestream should be established 109 * @param sessionID the session ID for the bytestream request 110 * @return the session to send/receive data to/from the user 111 * @throws XMPPException if an error occurred while establishing the session 112 * @throws IOException if an IO error occurred while establishing the session 113 * @throws InterruptedException if the thread was interrupted while waiting in a blocking 114 * operation 115 */ 116 public BytestreamSession establishSession(Jid targetJID, String sessionID) 117 throws XMPPException, IOException, InterruptedException, SmackException; 118 119}