vanitasvitae/Smack
1
0
Fork 0
mirror of https://github.com/vanitasvitae/Smack.git synced 2024-11-29 07:22:07 +01:00
Code Issues Releases Wiki Activity

Merge pull request #225 from fuentesj11/update-filetransfer-doc

Browse source 
Update filetransfer.md
This commit is contained in:
Florian Schmaus 2018-04-04 14:48:04 +02:00 committed by GitHub
commit fe157b1a2a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 30 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
documentation/extensions/filetransfer.md
View file

@ -6,7 +6,7 @@ File Transfer
The file transfer extension allows the user to transmit and receive files. The file transfer extension allows the user to transmit and receive files.
* Send a file to another user * 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 * 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) **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** **Description**
A user may wish to send a file to another user. The other user has the option 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 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** 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 In order to send a file you must first construct an instance of the
**_FileTransferManager_** class. In order to instantiate the manager **_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 Once you have your **_FileTransferManager_** you will need to create an
outgoing file transfer to send a file. The method to use on the outgoing file transfer to send a file. The method to use on the
**_FileTransferManager_** is the **createOutgoingFileTransfer(userID)** **_FileTransferManager_** is the **createOutgoingFileTransfer(userID)**
method. The userID you provide to this method is the fully-qualified jabber ID 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 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 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. resource in order to be able to receive the file transfer.
Now that you have your **_OutgoingFileTransfer_** instance you will want to Now that you have your **_OutgoingFileTransfer_** instance you will want to
send the file. The method to send a file is **sendFile(file, description)**. 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 Other means to send a file are also provided as part of the
**_OutgoingFileTransfer_**. Please consult the Javadoc for more information. **_OutgoingFileTransfer_**. Please consult the Javadoc for more information.
**Examples** **Examples**
In this example we can see how to send a file: 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 // Create the file transfer manager
FileTransferManager manager = FileTransferManager.getInstanceFor(connection); FileTransferManager manager = FileTransferManager.getInstanceFor(connection);
// Create the outgoing file transfer // Create the outgoing file transfer
OutgoingFileTransfer transfer = manager.createOutgoingFileTransfer("romeo@montague.net"); OutgoingFileTransfer transfer = manager.createOutgoingFileTransfer(entityFullJid);
// Send the file // Send the file
transfer.sendFile(new File("shakespeare_complete_works.txt"), "You won't believe this!"); 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** **Description**
The user may wish to recieve files from another user. The process of recieving The user may wish to receive files from another user. The process of receiving
a file is event driven, new file transfer requests are recieved from other a file is event driven, new file transfer requests are received from other
users via a listener registered with the file transfer manager. users via a listener registered with the file transfer manager.
**Usage** **Usage**
In order to recieve a file you must first construct an instance of the In order to receive a file you must first construct an instance of the
**_FileTransferManager_** class. This class has one constructor with one **_FileTransferManager_** class. This class has one static factory method with one
parameter which is your XMPPConnection. In order to instantiate the manager 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 Once you have your **_FileTransferManager_** you will need to register a
listener with it. The FileTransferListner interface has one method, listener with it. The FileTransferListener interface has one method,
**fileTransferRequest(request)**. When a request is recieved through this **fileTransferRequest(request)**. When a request is received through this
method, you can either accept or reject the request. To help you make your method, you can either accept or reject the request. To help you make your
decision there are several methods in the **_FileTransferRequest_** class that decision there are several methods in the **_FileTransferRequest_** class that
return information about the transfer request. 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 **_IncomingFileTransfer_**. After you have the file transfer you may start to
transfer the file by calling the **recieveFile(file)** method. The file 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 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 For information on monitoring the progress of a file transfer see the
monitoring progress section of this document. 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. **_IncomingFileTransfer_**. Please consult the Javadoc for more information.
**Examples** **Examples**
In this example we can see how to approve or reject a file transfer request: 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() { manager.addFileTransferListener(new FileTransferListener() {
public void fileTransferRequest(FileTransferRequest request) { public void fileTransferRequest(FileTransferRequest request) {
// Check to see if the request should be accepted // Check to see if the request should be accepted
if(shouldAccept(request)) { if (shouldAccept(request)) {
// Accept it // Accept it
IncomingFileTransfer transfer = request.accept(); IncomingFileTransfer transfer = request.accept();
transfer.recieveFile(new File("shakespeare_complete_works.txt")); 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 the **_FileTransfer_** class which provides several methods to monitor how a
file transfer is progressing: 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. * **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. * **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. * **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: In this example we can see how to monitor a file transfer:
``` ```
while(!transfer.isDone()) { while(!transfer.isDone()) {
if(transfer.getStatus().equals(Status.ERROR)) { if (transfer.getStatus().equals(Status.error)) {
System.out.println("ERROR!!! " + transfer.getError()); System.out.println("ERROR!!! " + transfer.getError());
} else { } else {
System.out.println(transfer.getStatus()); System.out.println(transfer.getStatus());