com.cryptshare.api

Interface IClient

All Known Implementing Classes:

Client

public interface IClient

Central client that is used to carry out request and operations on the Cryptshare Server, as a specified user.

Method Summary

Modifier and Type	Method and Description
void	applyQuickActivationCode(java.lang.String recoveryCode) Applies a QUICK activation code to activate QUICK access for the user on this client.
void	beginTransfer(Transfer transfer, IUploadProgressChangedHandler uploadProgressChangedCallback, IUploadCompleteHandler uploadCompleteCallback, IUploadInterruptedHandler uploadInterruptedCallback, IUploadCancelledHandler uploadCancelledCallback, int pollingTimer) Performs a transfer asynchronously in a separate thread.
void	cancelTransfer() Cancels a currently ongoing transfer.
boolean	checkCompatibility() Performs a compatibility check of this API against the Cryptshare Server.
boolean	checkCompatibility(java.lang.String minimumServerVersion) Performs a compatibility check against the Cryptshare Server.
PasswordCheckResult	checkPassword(java.lang.String password) Checks the given password against the password policy defined on the server.
CheckVerificationResult	checkVerification() Requests information about the verification configuration on the server and the current verification state of the user on this client.
void	confirmQuickConnection(java.lang.String metaId, java.lang.String password) Confirms/activates the QUICK connection that has been offered with a transfer.
void	confirmSenderVerification(java.lang.String verificationCode) Completes the sender verification process by confirming it with the the received verification code.
void	enableVerificationForQuick() Enables the verification of the user for QUICK so that it can be used to send and retrieve QUICK transfers.
java.lang.String	generateQuickActivationCode() Generates a activation code for client activation.
java.lang.String	getClientId() Returns the identifier if the client, which is generated automatically together with the store file.
java.lang.String	getServerUrl() Returns the Cryptshare Server URL that is set for this client.
java.lang.String	getUserEmailAddress() Returns the email address of the user that is set for this client.
java.util.Locale	getUserLanguage() Returns the language/region that is set for this client.
java.lang.String	getVerificationToken() Returns the verification token for the user that is set for this client.
void	performTransfer(Transfer transfer, IUploadProgressChangedHandler uploadProgressChangedCallback, IUploadCompleteHandler uploadCompleteCallback, IUploadInterruptedHandler uploadInterruptedCallback, IUploadCancelledHandler uploadCancelledCallback, int pollingTimer) Performs a transfer synchronously in the current thread.
void	performTransfer(Transfer transfer, IUploadProgressChangedHandler uploadProgressChangedCallback, IUploadCompleteHandler uploadCompleteCallback, IUploadInterruptedHandler uploadInterruptedCallback, IUploadCancelledHandler uploadCancelledCallback, int pollingTimer, IUploadFilesFinishedHandler uploadFilesFinishedHandler) Performs a transfer synchronously in the current thread.
java.util.Map<java.lang.String,java.lang.String>	requestActiveTransfers() Requests all active transfers where this client's sender address is a recipient.
void	requestClientVerification() Requests a client verification.
java.util.Map<java.util.List<java.lang.String>,java.lang.String>	requestEmailTemplate(java.lang.String templateName, java.util.Map<java.util.Set<java.lang.String>,java.util.Set<TemplateReplacement>> replacements, java.util.Locale language, EmailFormat mailFormat) Requests several resolved template content strings at once.
java.lang.String	requestGeneratedPassword(int length) Requests a generated password with the given length from the Cryptshare Server.
byte[]	requestLanguagePackFile(java.lang.String path, java.util.Locale locale) Downloads a single language pack resource.
java.util.List<LanguagePack>	requestLanguagePacks() Requests info about the language packs that are available on the server.
LicenseInfo	requestLicenseInfo() Requests the license info for the Cryptshare server and this product.
PasswordPolicy	requestPasswordPolicy() Requests the password policy from the server.
Policy	requestPolicy(java.util.Collection<java.lang.String> recipients) Request the policy rules that applies to the combination of the current user as sender, and the specified recipients.
java.util.Map<java.lang.String,QuickConnectionState>	requestQuickConnectionStates(java.util.List<java.lang.String> userEmailAddresses) Requests the QuickConnectionState for each of the specified recipients.
RecipientQuickState	requestRecipientQuickState(java.lang.String metaId) Requests information about the QUICK state of a transfer recipient.
void	requestSenderVerification() Requests a sender verification.
ServerData	requestServerData() Requests the general server settings from the Cryptshare server.
TermsOfUse	requestTermsOfUse() Requests the Terms of Use from the server.
void	resetQuickState() Resets the QUICK state of the user on the Cryptshare server.
void	revokeTransfer(java.lang.String trackingId) Revokes the transfer with the given trackingId such that its files are no longer accessible.
void	revokeTransfer(java.lang.String trackingId, boolean notifyRecipient, boolean notifySender) Revokes the transfer with the given trackingId such that its files are no longer accessible.
void	revokeTransfer(java.lang.String trackingId, boolean notifyRecipient, boolean notifySender, java.lang.String message) Revokes the transfer with the given trackingId such that its files are no longer accessible.
void	revokeTransfer(java.lang.String trackingId, java.lang.String message) Revokes the transfer with the given trackingId such that its files are no longer accessible.
void	setUserLanguage(java.util.Locale userLanguage) Sets the language/region for this client.
void	updateTransferError(java.lang.String trackingId, TransferError transferError) Updates the error status for the Transfer with the given tracking ID.

Method Detail

getClientId

java.lang.String getClientId()
                      throws ClientException

Returns the identifier if the client, which is generated automatically together with the store file.

Throws:

ClientException

getUserEmailAddress

java.lang.String getUserEmailAddress()

Returns the email address of the user that is set for this client.

Returns:

The email address.

getVerificationToken

java.lang.String getVerificationToken()

Returns the verification token for the user that is set for this client.

Returns:

The verification token.

getServerUrl

java.lang.String getServerUrl()

Returns the Cryptshare Server URL that is set for this client.

Returns:

The Cryptshare Server URL.

getUserLanguage

java.util.Locale getUserLanguage()

Returns the language/region that is set for this client.

Returns:

The language/region as Locale.

setUserLanguage

void setUserLanguage(java.util.Locale userLanguage)

Sets the language/region for this client.

Parameters:

userLanguage - The language/region as Locale.

requestSenderVerification

void requestSenderVerification()
                        throws CryptshareServerException,
                               ClientException

Requests a sender verification. This triggers the server to send an email to the user's email address with a verification code. The verification code then has to be provided using confirmSenderVerification(String).

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestClientVerification

void requestClientVerification()
                        throws CryptshareServerException,
                               ClientException

Requests a client verification. This automatically verifies the user, if client verification is enabled on the Cryptshare Server and the client ID has been added to the list of allowed clients.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

checkVerification

CheckVerificationResult checkVerification()
                                   throws CryptshareServerException,
                                          ClientException

Requests information about the verification configuration on the server and the current verification state of the user on this client.

Returns:

A CheckVerificationResult object that contains information about the verification state and configuration.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

confirmSenderVerification

void confirmSenderVerification(java.lang.String verificationCode)
                        throws CryptshareServerException,
                               ClientException

Completes the sender verification process by confirming it with the the received verification code.

Parameters:

verificationCode - The verification code that has been received after calling requestSenderVerification()

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

applyQuickActivationCode

void applyQuickActivationCode(java.lang.String recoveryCode)
                       throws CryptshareServerException,
                              ClientException

Applies a QUICK activation code to activate QUICK access for the user on this client.

Parameters:

recoveryCode - The activation code.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

generateQuickActivationCode

java.lang.String generateQuickActivationCode()
                                      throws CryptshareServerException,
                                             ClientException

Generates a activation code for client activation. It is required that the client user is already verified and enabled for the use of QUICK on this client.

Returns:

The generated activation code.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

checkCompatibility

boolean checkCompatibility()
                    throws CryptshareServerException,
                           ClientException

Performs a compatibility check of this API against the Cryptshare Server.

Returns:

true, if the configured Cryptshare server is compatible to this version of the API.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

checkCompatibility

boolean checkCompatibility(java.lang.String minimumServerVersion)
                    throws CryptshareServerException,
                           ClientException

Performs a compatibility check against the Cryptshare Server. The Cryptshare Server reports compatible, if the current Cryptshare Server version has no breaking changes compared to the requested Cryptshare Server version. This method can be used by API integration products, that require a certain minimum Cryptshare Server version. To check the compatibility of the API itself, use checkCompatibility() instead.

Parameters:

minimumServerVersion - The minimum server version.

Returns:

true, if the configured Cryptshare Server is compatible with the specified version of the API.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestPolicy

Policy requestPolicy(java.util.Collection<java.lang.String> recipients)
              throws CryptshareServerException,
                     ClientException

Request the policy rules that applies to the combination of the current user as sender, and the specified recipients.

Parameters:

recipients - The email addresses of the recipients

Returns:

The Policy containing the policy rules

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestQuickConnectionStates

java.util.Map<java.lang.String,QuickConnectionState> requestQuickConnectionStates(java.util.List<java.lang.String> userEmailAddresses)
                                                                           throws CryptshareServerException,
                                                                                  ClientException

Requests the QuickConnectionState for each of the specified recipients.

Parameters:

userEmailAddresses - A collection of email addresses to request the QUICK connection state for.

Returns:

A map with the email addresses as keys, and the respective QuickConnectionState"/> as values.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestEmailTemplate

java.util.Map<java.util.List<java.lang.String>,java.lang.String> requestEmailTemplate(java.lang.String templateName,
                                                                                      java.util.Map<java.util.Set<java.lang.String>,java.util.Set<TemplateReplacement>> replacements,
                                                                                      java.util.Locale language,
                                                                                      EmailFormat mailFormat)
                                                                               throws CryptshareServerException,
                                                                                      ClientException

Requests several resolved template content strings at once. Each set of different replacements (a certain Set with TemplateReplacements) has a corresponing Set of identifiers (e.g. recipients), to which the replacements belong. The result will return the distinct and (partially) resolved templates with all identifiers that led to that certain template result.

Parameters:

templateName - The name of the template, for example "recipient" or "sender"

replacements - Associations between a list of identifiers (e.g. recipients) and replacements.

language - The Locale for which the template is requested

mailFormat - The email format of the template as EmailFormat.

Returns:

the Map containing the email template variants for each set of identifiers.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestLanguagePacks

java.util.List<LanguagePack> requestLanguagePacks()
                                           throws CryptshareServerException,
                                                  ClientException

Requests info about the language packs that are available on the server. Uses the default language pack major version of the Client, as defined when creating the CryptshareConnection.

Returns:

A list of languages that are available on the server

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestLanguagePackFile

byte[] requestLanguagePackFile(java.lang.String path,
                               java.util.Locale locale)
                        throws CryptshareServerException,
                               ClientException

Downloads a single language pack resource. Uses the default language pack major version of the Client, as defined when creating the CryptshareConnection.

Parameters:

path - The path to the resource, relative to the language pack root.

locale - The Locale of the requested language pack file

Returns:

The raw bytes of the language pack file.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestTermsOfUse

TermsOfUse requestTermsOfUse()
                      throws CryptshareServerException,
                             ClientException

Requests the Terms of Use from the server.

Returns:

A TermsOfUse object containing a list of key/value entries where the key is the locale, and the value is the actual text of the Terms of Use for that language.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestLicenseInfo

LicenseInfo requestLicenseInfo()
                        throws CryptshareServerException,
                               ClientException

Requests the license info for the Cryptshare server and this product.

Returns:

A LicenseInfo object containing the license information

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestActiveTransfers

java.util.Map<java.lang.String,java.lang.String> requestActiveTransfers()
                                                                 throws CryptshareServerException,
                                                                        ClientException

Requests all active transfers where this client's sender address is a recipient. This operation will fail if the client is not yet verified.

Returns:

A map where the keys are the transfer meta ids, and the values are the download URLs of the these transfers, without the password.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

updateTransferError

void updateTransferError(java.lang.String trackingId,
                         TransferError transferError)
                  throws CryptshareServerException,
                         ClientException

Updates the error status for the Transfer with the given tracking ID.

Parameters:

trackingId - The tracking ID of the transfer whose error status is to be updated

transferError - The error information. For this webservice call, TransferError.isAllNotificationsFailed(), TransferError.isEmlCreationFailed(), TransferError.isSenderNotificationFailed() flags and TransferError.getFailedRecipients() is updated.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestGeneratedPassword

java.lang.String requestGeneratedPassword(int length)
                                   throws CryptshareServerException,
                                          ClientException

Requests a generated password with the given length from the Cryptshare Server. The server assures that the generated password fulfils the policy.

Parameters:

length - The length of the password to generate.

Returns:

The generated password.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

checkPassword

PasswordCheckResult checkPassword(java.lang.String password)
                           throws CryptshareServerException,
                                  ClientException

Checks the given password against the password policy defined on the server.

Parameters:

password - String with password to check

Returns:

A PasswordPolicy object containing the password policy information and a security rating for the password.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestPasswordPolicy

PasswordPolicy requestPasswordPolicy()
                              throws CryptshareServerException,
                                     ClientException

Requests the password policy from the server.

Returns:

PasswordPolicy with the current password policy from the server.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestServerData

ServerData requestServerData()
                      throws CryptshareServerException,
                             ClientException

Requests the general server settings from the Cryptshare server.

Returns:

A ServerData object containing the server settings.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

enableVerificationForQuick

void enableVerificationForQuick()
                         throws CryptshareServerException,
                                ClientException

Enables the verification of the user for QUICK so that it can be used to send and retrieve QUICK transfers.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

confirmQuickConnection

void confirmQuickConnection(java.lang.String metaId,
                            java.lang.String password)
                     throws CryptshareServerException,
                            ClientException

Confirms/activates the QUICK connection that has been offered with a transfer.

Parameters:

metaId - The recipient's meta ID of the transfer.

password - The password to retrieve the transfer.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

requestRecipientQuickState

RecipientQuickState requestRecipientQuickState(java.lang.String metaId)
                                        throws CryptshareServerException,
                                               ClientException

Requests information about the QUICK state of a transfer recipient.

Parameters:

metaId - The recipient's meta ID of the transfer.

Returns:

A RecipientQuickState object with further information.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

resetQuickState

void resetQuickState()
              throws CryptshareServerException,
                     ClientException

Resets the QUICK state of the user on the Cryptshare server. As a last resort, this allows the use of QUICK again if the access is lost and no recovery options are available. Caution: This will remove all established and pending QUICK connections to other users, and may lead to transfers that can't be retrieved anymore.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

cancelTransfer

void cancelTransfer()

Cancels a currently ongoing transfer.

beginTransfer

void beginTransfer(Transfer transfer,
                   IUploadProgressChangedHandler uploadProgressChangedCallback,
                   IUploadCompleteHandler uploadCompleteCallback,
                   IUploadInterruptedHandler uploadInterruptedCallback,
                   IUploadCancelledHandler uploadCancelledCallback,
                   int pollingTimer)

Performs a transfer asynchronously in a separate thread. The method returns immediately, and the transfer progress is signalled by the various callbacks.

Parameters:

transfer - The transfer to be performed asynchronously

uploadProgressChangedCallback - This callback is called regularly with current information about the progress.

uploadCompleteCallback - This callback is called when the transfer completes without cancellation.

uploadInterruptedCallback - This callback is called when the transfer is interrupted due to exceptions.

uploadCancelledCallback - This callback is called when the user cancelled the transfer.

pollingTimer - The time in milliseconds between two checks of transfer state during the pre-processing.

performTransfer

void performTransfer(Transfer transfer,
                     IUploadProgressChangedHandler uploadProgressChangedCallback,
                     IUploadCompleteHandler uploadCompleteCallback,
                     IUploadInterruptedHandler uploadInterruptedCallback,
                     IUploadCancelledHandler uploadCancelledCallback,
                     int pollingTimer)
              throws CryptshareServerException,
                     ClientException

Performs a transfer synchronously in the current thread. The transfer progress is signalled by the various callbacks.

Parameters:

transfer - The transfer to be performed synchronously

uploadProgressChangedCallback - This callback is called regularly with current information about the progress.

uploadCompleteCallback - This callback is called when the transfer completes without cancellation.

uploadInterruptedCallback - This callback is called when the transfer is interrupted due to exceptions.

uploadCancelledCallback - This callback is called when the user cancelled the transfer.

pollingTimer - The time in milliseconds between two checks of transfer state during the pre-processing.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

performTransfer

void performTransfer(Transfer transfer,
                     IUploadProgressChangedHandler uploadProgressChangedCallback,
                     IUploadCompleteHandler uploadCompleteCallback,
                     IUploadInterruptedHandler uploadInterruptedCallback,
                     IUploadCancelledHandler uploadCancelledCallback,
                     int pollingTimer,
                     IUploadFilesFinishedHandler uploadFilesFinishedHandler)
              throws CryptshareServerException,
                     ClientException

Performs a transfer synchronously in the current thread. The transfer progress is signalled by the various callbacks.

Parameters:

transfer - The transfer to be performed synchronously

uploadProgressChangedCallback - This callback is called regularly with current information about the progress.

uploadCompleteCallback - This callback is called when the transfer completes without cancellation.

uploadInterruptedCallback - This callback is called when the transfer is interrupted due to exceptions.

uploadCancelledCallback - This callback is called when the user cancelled the transfer.

pollingTimer - The time in milliseconds between two checks of transfer state during the pre-processing.

uploadFilesFinishedHandler - This callback is called when the file upload is finished, but before they are processed by the server.

Throws:

CryptshareServerException - If the Cryptshare Server failed to process the request.

ClientException - If the API failed to process the request.

revokeTransfer

void revokeTransfer(java.lang.String trackingId)
             throws ClientException,
                    CryptshareServerException

Revokes the transfer with the given trackingId such that its files are no longer accessible.

Parameters:

trackingId - The tracking ID of the transfer to revoke.

Throws:

CryptshareServerException - CryptshareServerException indicating: Either no transfer matching the given trackingId was found, The requesting user is not the sender of the transfer Failed to delete transfer files. Failed to send email notification to recipients.

ClientException - If the API failed to process the request.

revokeTransfer

void revokeTransfer(java.lang.String trackingId,
                    boolean notifyRecipient,
                    boolean notifySender)
             throws ClientException,
                    CryptshareServerException

Revokes the transfer with the given trackingId such that its files are no longer accessible.

Parameters:

trackingId - The tracking ID of the transfer to revoke.

notifyRecipient - Whether the recipient receives an email notification.

notifySender - Whether the sender receives an email notification.

Throws:

CryptshareServerException - CryptshareServerException indicating:

• No transfer matching the given trackingId was found.
• The requesting user is not the sender of the transfer.
• Failed to delete transfer files.
• Failed to send email notification to recipients.

ClientException - If the API failed to process the request.

revokeTransfer

void revokeTransfer(java.lang.String trackingId,
                    java.lang.String message)
             throws ClientException,
                    CryptshareServerException

Revokes the transfer with the given trackingId such that its files are no longer accessible.

Parameters:

trackingId - The tracking ID of the transfer to revoke.

message - The email notification message. If a default message is set..

Throws:

CryptshareServerException - CryptshareServerException indicating:

• No transfer matching the given trackingId was found.
• The requesting user is not the sender of the transfer.
• Failed to delete transfer files.
• Failed to send email notification to recipients.

ClientException - If the API failed to process the request.

revokeTransfer

void revokeTransfer(java.lang.String trackingId,
                    boolean notifyRecipient,
                    boolean notifySender,
                    java.lang.String message)
             throws ClientException,
                    CryptshareServerException

Revokes the transfer with the given trackingId such that its files are no longer accessible.

Parameters:

trackingId - The tracking ID of the transfer to revoke.

notifyRecipient - Whether the recipient receives an email notification.

notifySender - Whether the sender receives an email notification.

message - The email notification message. If a default message is set..

Throws:

CryptshareServerException - CryptshareServerException indicating:

• No transfer matching the given trackingId was found.
• The requesting user is not the sender of the transfer.
• Failed to delete transfer files.
• Failed to send email notification to recipients.

ClientException - If the API failed to process the request.