mirror of
https://codeberg.org/Mercury-IM/Smack
synced 2024-11-22 06:12:05 +01:00
Update filetransfer.md
This commit is contained in:
parent
a9ca1a0989
commit
2e4e593a97
1 changed files with 30 additions and 24 deletions
|
@ -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 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:
|
||||
|
@ -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());
|
||||
|
|
Loading…
Reference in a new issue