/** * * Copyright 2015-2022 Florian Schmaus * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * Smack's API for File Transfers. The file transfer extension allows the user to transmit and receive files. *
* A user may wish to send a file to another user. The other user has the option of accepting, rejecting, or ignoring * the users request. Smack provides a simple interface in order to enable the user to easily send a file. *
** In order to send a file you must first construct an instance of the _FileTransferManager_** class. In order to * instantiate the manager you should call _FileTransferManager.getInstanceFor(connection)_, where connection is an * XMPPConnection instance. *
** Once you have your **_FileTransferManager_** you will need to create an outgoing file transfer to send a file. The * method to use on the _FileTransferManager_** is the **createOutgoingFileTransfer(userID)** method. The userID you * provide to this method is the fully-qualified jabber ID of the user you wish to send the file to. A fully-qualified * jabber ID consists of a node, a domain, and a resource. The user must be connected to the resource in order to be * able to receive the file transfer. *
** Now that you have your **_OutgoingFileTransfer_** instance you will want to send the file. The method to send a file * is **sendFile(file, description)**. The file you provide to this method should be a readable file on the local file * system, and the description is a short description of the file to help the user decide whether or not they would like * to receive the file. *
** For information on monitoring the progress of a file transfer see the monitoring progress section of this document. *
** Other means to send a file are also provided as part of the _OutgoingFileTransfer_**. Please consult the Javadoc for * more information. *
** In this example we can see how to send a file: *
* *{@code * // Create the file transfer manager * FileTransferManager manager = FileTransferManager.getInstanceFor(connection); * // Create the outgoing file transfer * OutgoingFileTransfer transfer = manager.createOutgoingFileTransfer(entityFullJid); * // Send the file * transfer.sendFile(new File("shakespeare_complete_works.txt"), "You won't believe this!"); * }* *
* The user may wish to receive files from another user. The process of receiving a file is event driven, new file * transfer requests are received from other users via a listener registered with the file transfer manager. *
** In order to receive a file you must first construct an instance of the _FileTransferManager_** class. This class has * one static factory method with one parameter which is your XMPPConnection. In order to instantiate the manager you * should call _FileTransferManager.getInstanceFor(connection)_. *
** Once you have your **_FileTransferManager_** you will need to register a listener with it. The FileTransferListener * interface has one method, fileTransferRequest(request)**. When a request is received through this method, you can * either accept or reject the request. To help you make your decision there are several methods in the * **_FileTransferRequest_** class that return information about the transfer request. *
** To accept the file transfer, call the **accept()** method. This method will create an _IncomingFileTransfer_**. After * you have the file transfer you may start to transfer the file by calling the **recieveFile(file)** method. The file * provided to this method will be where the data from the file transfer is saved. *
** Finally, to reject the file transfer the only method you need to call is reject()** on the **_FileTransferRequest_**. *
** For information on monitoring the progress of a file transfer see the monitoring progress section of this document. *
** Other means to receive a file are also provided as part of the _IncomingFileTransfer_**. Please consult the Javadoc * for more information. *
** In this example we can see how to approve or reject a file transfer request: *
* *{@code * // Create the file transfer manager * final FileTransferManager manager = FileTransferManager.getInstanceFor(connection); * // Create the listener * manager.addFileTransferListener(new FileTransferListener() { * public void fileTransferRequest(FileTransferRequest request) { * // Check to see if the request should be accepted * if (shouldAccept(request)) { * // Accept it * IncomingFileTransfer transfer = request.accept(); * transfer.recieveFile(new File("shakespeare_complete_works.txt")); * } else { * // Reject it * request.reject(); * } * } * }); * }* *
* While a file transfer is in progress you may wish to monitor the progress of a file transfer. *
** Both the **_IncomingFileTransfer_** and the **_OutgoingFileTransfer_** extend the **_FileTransfer_** class which * provides several methods to monitor how a file transfer is progressing: *
** In this example we can see how to monitor a file transfer: *
* *{@code * while (!transfer.isDone()) { * if (transfer.getStatus().equals(Status.error)) { * System.out.println("ERROR!!! " + transfer.getError()); * } else { * System.out.println(transfer.getStatus()); * System.out.println(transfer.getProgress()); * } * sleep(1000); * } * }* * @see XEP-0047: In-Band Bytestreams * @see XEP-0065: SOCKS5 Bytestreams * * @see XEP-0095: Stream Initiation * * @see XEP-0096: SI File Transfer * */ package org.jivesoftware.smackx.filetransfer;