<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>File Transfer</title> <link rel="stylesheet" type="text/css" href="style.css" /> </head> <body> <div class="header">File Transfer</div><p> The file transfer extension allows the user to transmit and receive files. <ul> <li><a href="#sendfile">Send a file to another user</a></li> <li><a href="#recievefile">Recieving a file from another user</a></li> <li><a href="#monitorprogress">Monitoring the progress of a file transfer</a></li> </ul> <b>JEP related:</b> <a href="http://www.jabber.org/jeps/jep-0095.html">JEP-95</a> <a href="http://www.jabber.org/jeps/jep-0096.html">JEP-96</a> <a href="http://www.jabber.org/jeps/jep-0065.html">JEP-65</a> <a href="http://www.jabber.org/jeps/jep-0047.html">JEP-47</a> <hr> <div class="subheader"><a name="sendfile">Send a file to another user</a></div><p> <b>Description</b><p> 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. <b>Usage</b><p> In order to send a file you must first construct an instance of the <b><i>FileTransferManager</i></b> class. This class has one constructor with one parameter which is your XMPPConnection. In order to instantiate the manager you should call <i>new FileTransferManager(connection)</i> <p>Once you have your <b><i>FileTransferManager</i></b> you will need to create an outgoing file transfer to send a file. The method to use on the <b><i>FileTransferManager</i></b> is the <b>createOutgoingFileTransfer(userID)</b> 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. <p>Now that you have your <b><i>OutgoingFileTransfer</i></b> instance you will want to send the file. The method to send a file is <b>sendFile(file, description)</b>. 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. <p>For information on monitoring the progress of a file transfer see the <a href="#monitorprogress">monitoring progress</a> section of this document. <p>Other means to send a file are also provided as part of the <b><i>OutgoingFileTransfer</i></b>. Please consult the Javadoc for more information. <b>Examples</b><p> In this example we can see how to send a file: <br> <blockquote> <pre> <font color="#3f7f5f">// Create the file transfer manager</font> FileTransferManager manager = new FileTransferManager(connection); <font color="#3f7f5f">// Create the outgoing file transfer</font> OutgoingFileTransfer transfer = manager.createOutgoingFileTransfer(<font color="#0000FF">"romeo@montague.net"</font>); <font color="#3f7f5f">// Send the file</font> transfer.sendFile(new File(<font color="#0000FF">"shakespeare_complete_works.txt"</font>), <font color="#0000FF">"You won't believe this!"</font>); </pre> </blockquote> <hr> <div class="subheader"><a name="recievefile">Recieving a file from another user</a></div><p> <b>Description</b><p> 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.</p> <b>Usage</b><p> In order to recieve a file you must first construct an instance of the <b><i>FileTransferManager</i></b> class. This class has one constructor with one parameter which is your XMPPConnection. In order to instantiate the manager you should call <i>new FileTransferManager(connection)</i> <p>Once you have your <b><i>FileTransferManager</i></b> you will need to register a listener with it. The FileTransferListner interface has one method, <b>fileTransferRequest(request)</b>. 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 <b><i>FileTransferRequest</i></b> class that return information about the transfer request. <p>To accept the file transfer, call the <b>accept()</b>, this method will create an <b><i>IncomingFileTransfer</i></b>. After you have the file transfer you may start to transfer the file by calling the <b>recieveFile(file)</b> method. The file provided to this method will be where the data from thefile transfer is saved.</p> <p>Finally, to reject the file transfer the only method you need to call is <b>reject()</b> on the <b><i>IncomingFileTransfer</i></b>. <p>For information on monitoring the progress of a file transfer see the <a href="#monitorprogress">monitoring progress</a> section of this document. <p>Other means to recieve a file are also provided as part of the <b><i>IncomingFileTransfer</i></b>. Please consult the Javadoc for more information. <b>Examples</b><p> In this example we can see how to approve or reject a file transfer request: <br> <blockquote> <pre> <font color="#3f7f5f">// Create the file transfer manager</font> final FileTransferManager manager = new FileTransferManager(connection); <font color="#3f7f5f">// Create the listener</font> manager.addFileTransferListener(new FileTransferListener() { public void fileTransferRequest(FileTransferRequest request) { <font color="#3f7f5f">// Check to see if the request should be accepted</font> if(shouldAccept(request)) { <font color="#3f7f5f">// Accept it</font> IncomingFileTransfer transfer = request.accept(); transfer.recieveFile(new File(<font color="#0000FF">"shakespeare_complete_works.txt"</font>)); } else { <font color="#3f7f5f">// Reject it</font> request.reject(); } } }); </pre> </blockquote> <hr> <div class="subheader"><a name="monitorprogress">Monitoring the progress of a file transfer</a></div><p> <b>Description</b><p> While a file transfer is in progress you may wish to monitor the progress of a file transfer.</p> <b>Usage</b><p> <p>Both the <b><i>IncomingFileTransfer</i></b> and the <b><i>OutgoingFileTransfer</i></b> extend the <b><i>FileTransfer</i></b> class which provides several methods to monitor how a file transfer is progressing: <ul> <li><b>getStatus()</b> - The file transfer can be in several states, negotiating, rejected, canceled, in progress, error, and complete. This method will return which state the file transfer is currently in. <li><b>getProgress()</b> - 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. <li><b>isDone()</b> - Similar to getProgress() except it returns a <i>boolean</i>. If the state is rejected, canceled, error, or complete then true will be returned and false otherwise. <li><b>getError()</b> - If there is an error during the file transfer this method will return the type of error that occured. </ul> <b>Examples</b><p> In this example we can see how to monitor a file transfer: <br> <blockquote> <pre> while(!transfer.isDone()) { if(transfer.getStatus().equals(Status.ERROR)) { System.out.println(<font color="#0000FF">"ERROR!!! "</font> + transfer.getError()); } else { System.out.println(transfer.getStatus()); System.out.println(transfer.getProgress()); } sleep(1000); } </pre> </blockquote> </body> </html>