Before you can perform a transfer, you have to create a Transfer object with the sender's contact details, the password mode, the message that is to be included in the transfer, the recipients, the languages of the notification emails, the storage duration, and, of course, the files that will be transferred.
If a recipient is not allowed for the transfer, based on the server's policy settings, an exception will be thrown when trying to perform the transfer. To avoid this, you can check the Policy Rules before attempting to perform a transfer.
The password mode used for the transfer must be one of the allowed password modes defined in the Policy Rules.
About the Password Modes
If the password mode is PasswordMode.MANUAL, then you have to explicitly set a password for the transfer. You can check the password to make sure that it fulfills the requirements of the Password Policy by using the functions described in Password Functions. The recipient will then have to contact the sender of the transfer to find out what the password is, before any files can be downloaded.
For password mode PasswordMode.GENERATED, the Client will request a server-generated password and automatically set it for the transfer. The password will be included in the transfer message, so that the recipients do not need to explicitly contact the sender to learn the password.
When using PasswordMode.NONE, you do not have to define a password. The server will automatically generate a password and include it in the download link, so that the recipient does not need to explicitly enter a password to download the files. This is obviously the least secure method, and should thus be used sparingly.
You can specify the languages to use for the default recipient and sender email notifications. The languages are specified with their language code, e.g. "en" or "en_GB". You can only specify languages for which there are language packs installed on the server. See Language Resources.
You can also set a custom message and subject for the notification emails. The Transfer object has setters for the message and subject fields that take either a String, or an InputStream as a parameter, so you can either directly set a text as the message or subject, or give the setter method an InputStream containing the text, and the text will be automatically read from the stream. The encoding of the stream has to be UTF-8, to ensure that the text can be read in correctly. Once the text is read from the InputStream, the stream will automatically be closed. Your message text can also include HTML markup. For the subject text, only plain text is supported, so using HTML tags in the subject line may lead to unexpected results.
If allowed by the Policy, you may also choose to include a confidential message to the recipients of the transfer. Setting the confidential message and subject is similar to setting the custom notification message on the Transfer object. The parameters for the setter methods of the Transfer object's confidentialMessage and confidentialSubject fields are either a String or an InputStream, so the same rules apply as described above for the custom message and subject.
When specifiying an expiration date for the transferred files, make sure that it is still within the maximum allowed storage duration as specified in the Policy Rules. The transferred files will only be available for download until the specified expiration date.
Once the Transfer object has been initialized as described in the example here, it can be used for performing the transfer either synchronously or asynchronously as described in the sections Perform a Synchronous Transfer and Perform an Asynchronous Transfer below.
Performing a Transfer
Once you have the Transfer object initialized as described in the example Preparing a Transfer above, you can use it to perform a synchronous transfer. A synchronous transfer is performed by calling the Client's method performTransfer(Transfer, TransferUploadListener). The method requires a Transfer object containing all the necessary transfer data, as well as a TransferUploadListener that will be informed about the upload progress and any errors encountered during the upload. As this is a synchronous operation, the method will block until all files in the transfer have been uploaded and the transfer is completed.
To perform a transfer asynchronously, initialize the Transfer object as described in the example Preparing a Transfer above, and call the Client's method beginTransfer(Transfer, TransferUploadListener), giving it the initialized Transfer object containing all the necessary transfer data, as well as a TransferUploadListener that will be informed about the upload progress, the completion of the upload, and any errors encountered during the upload. The method will return immediately after starting a new Thread in the background which will perform the actual transfer. Once the upload completes in the background, the TransferUploadListener's handleUploadCompleted(UploadCompletedEvent) method will be called.
Cancelling a Transfer
If you wish to cancel an ongoing transfer, you may do so by calling the Client's method cancelTransfer(). This method stops the current file upload process and cancels the transfer. A transfer can only be cancelled while it is still in the process of uploading the files. Once all files of a transfer have been uploaded to the server, the transfer will be complete and cannot be cancelled using the API. A transfer that has already been completed from the Client's point of view, can only be cancelled on server side by the Cryptshare system administrator.