+ +The file transfer extension allows the user to transmit and receive files. + +
+ +Description
+ +A user may wish to send a file to another user. The other user has the option of acception, +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. This class has one constructor with one parameter which is your XMPPConnection. +In order to instantiate the manager you should call new FileTransferManager(connection)
+ +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 recieve 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 recieve 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 = new FileTransferManager(connection);
+
+ // Create the outgoing file transfer
+ OutgoingFileTransfer transfer = manager.createOutgoingFileTransfer("romeo@montague.net");
+
+ // Send the file
+ transfer.sendFile(new File("shakespeare_complete_works.txt"), "You won't believe this!");
+
+
+
+
++ +Description
+ +The user may wish to recieve files from another user. The process of recieving a file is event driven, +new file transfer requests are recieved from other users via a listener registered with the file transfer +manager.
+ +Usage+ +In order to recieve a file you must first construct an instance of the FileTransferManager +class. This class has one constructor with one parameter which is your XMPPConnection. +In order to instantiate the manager you should call new FileTransferManager(connection)
+ +Once you have your FileTransferManager you will need to register a listener +with it. The FileTransferListner interface has one method, fileTransferRequest(request). +When a request is recieved 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(), +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 thefile transfer is saved.
+ +Finally, to reject the file transfer the only method you need to call is reject() +on the IncomingFileTransfer.
+ +For information on monitoring the progress of a file transfer see the monitoring progress +section of this document.
+ +Other means to recieve 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 = new FileTransferManager(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();
+ }
+ }
+ });
+
+
+
++ +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:
+
+
+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);
+ }
+
+
+
+
+
diff --git a/documentation/extensions/intro.html b/documentation/extensions/intro.html
index 2005966e1..f97de3e0e 100644
--- a/documentation/extensions/intro.html
+++ b/documentation/extensions/intro.html
@@ -64,7 +64,12 @@