mirror of
https://codeberg.org/Mercury-IM/Smack
synced 2024-12-24 05:27:56 +01:00
178 lines
8 KiB
HTML
178 lines
8 KiB
HTML
<!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>
|