diff --git a/documentation/extensions/filetransfer.md b/documentation/extensions/filetransfer.md index dab858215..42c8d601e 100644 --- a/documentation/extensions/filetransfer.md +++ b/documentation/extensions/filetransfer.md @@ -6,7 +6,7 @@ File Transfer The file transfer extension allows the user to transmit and receive files. * Send a file to another user - * Recieving a file from another user + * Receiving a file from another user * Monitoring the progress of a file transfer **XEP related:** [XEP-95](http://www.xmpp.org/extensions/xep-0095.html) [XEP-96](http://www.xmpp.org/extensions/xep-0096.html) [XEP-65](http://www.xmpp.org/extensions/xep-0065.html) [XEP-47](http://www.xmpp.org/extensions/xep-0047.html) @@ -17,20 +17,22 @@ 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 acception, rejecting, or ignoring the users request. Smack provides a -simple interface in order to enable the user to easily send a file. **Usage** +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)_ +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 recieve the file transfer. +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)**. @@ -43,6 +45,7 @@ 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: @@ -51,47 +54,48 @@ 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("romeo@montague.net"); +OutgoingFileTransfer transfer = manager.createOutgoingFileTransfer(entityFullJid); // Send the file transfer.sendFile(new File("shakespeare_complete_works.txt"), "You won't believe this!"); ``` -Recieving a file from another user +Receiving a file from another user ---------------------------------- **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 +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 recieve a file you must first construct an instance of the -**_FileTransferManager_** class. This class has one constructor with one +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)_ +you should call _FileTransferManager.getInstanceFor(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 +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()**, this method will create an +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 thefile transfer is saved. +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 **_IncomingFileTransfer_**. +**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 recieve a file are also provided as part of the +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: @@ -103,7 +107,7 @@ final FileTransferManager manager = FileTransferManager.getInstanceFor(connectio manager.addFileTransferListener(new FileTransferListener() { public void fileTransferRequest(FileTransferRequest request) { // Check to see if the request should be accepted - if(shouldAccept(request)) { + if (shouldAccept(request)) { // Accept it IncomingFileTransfer transfer = request.accept(); transfer.recieveFile(new File("shakespeare_complete_works.txt")); @@ -129,16 +133,18 @@ 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, canceled, 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. + * **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 occured. **Examples** + * **getError()** - If there is an error during the file transfer this method will return the type of error that occured. + + **Examples** In this example we can see how to monitor a file transfer: ``` while(!transfer.isDone()) { - if(transfer.getStatus().equals(Status.ERROR)) { + if (transfer.getStatus().equals(Status.error)) { System.out.println("ERROR!!! " + transfer.getError()); } else { System.out.println(transfer.getStatus());