Package org.jivesoftware.smackx.filetransfer
- Send a file to another user
- Receiving a file from another user
- Monitoring the progress of a file transfer
Send a file to another user
Description
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.
Usage
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.
Examples
In this example we can see how to send a file:
// 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!");
Receiving a file from another user
Description
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.
Usage
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.
Examples
In this example we can see how to approve or reject a file transfer request:
// 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();
}
}
});
Monitoring the progress of a file transfer
Description
While a file transfer is in progress you may wish to monitor the progress of a file transfer.
Usage
Both the **_IncomingFileTransfer_** and the **_OutgoingFileTransfer_** extend the **_FileTransfer_** class which provides several methods to monitor how a file transfer is progressing:
- **getStatus()** - The file transfer can be in several states, negotiating, rejected, cancelled, in progress, error, and complete. This method will return which state the file transfer is currently in.
- **getProgress()** - If the status of the file transfer is in progress this method will return a number between 0 and 1, 0 being the transfer has not yet started and 1 being the transfer is complete. It may also return a -1 if the transfer is not in progress.
- **isDone()** - Similar to getProgress() except it returns a _boolean_. If the state is rejected, canceled, error, or complete then true will be returned and false otherwise.
- **getError()** - If there is an error during the file transfer this method will return the type of error that occurred.
Examples
In this example we can see how to monitor a file transfer:
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);
}
-
ClassDescriptionContains the generic file information and progress related to a particular file transfer.A class to represent the current status of the file transfer.File transfers can cause several events to be raised.The file transfer manager class handles the sending and receiving of files.Manages the negotiation of file transfers according to XEP-0096.A request to send a file received from another user.The In-Band Bytestream file transfer method, or IBB for short, transfers the file over the same XML Stream used by XMPP.An incoming file transfer is created when the
FileTransferManager.createIncomingFileTransfer(FileTransferRequest)method is invoked.Handles the sending of a file to another user.A callback class to retrieve the status of an outgoing transfer negotiation process.Negotiates a SOCKS5 Bytestream to be used for file transfers.After the file transfer negotiation process is completed according to XEP-0096, the negotiation process is passed off to a particular stream negotiator.