CSDNCurrent en:File Transfer
You can perform both synchronous, as well as asynchronous Cryptshare file transfers using the API. A transfer can contain one or more files that will be encrypted, uploaded to the Cryptshare Server, and then made available to the transfer's recipients for download. Depending on your transfer settings, the recipients and/or sender of the transfer will then be notified by email when the transfer is complete and the files are available for download.
Before you can perform a transfer, you have to configure the transfer settings, define the recipients and select the files you wish to include in the transfer (see Preparing a Transfer). Then you can either Perform a Synchronous Transfer or Perform an Asynchronous Transfer.
Preparing a Transfer
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.
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 e-mail 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 .
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 a string as a parameter. 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.
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.
Example: Preparing a Transfer Object
// Create a new Transfer object
Transfer transfer = new Transfer();
// Set the name of the sender
transfer.senderName = "John Adams";
// Set the sender's phone number
transfer.senderPhone = "234 5467";
// Set the message text of the mail that is to be included in the transfer.
// The Transfer object's message property takes a text string containing
// the e-mail message.
try
{
// In this example, we will just read it in from a file.
string message = File.ReadAllText(@"C:\temp\message.txt", System.Text.Encoding.UTF8);
transfer.message = message;
}
catch (Exception e)
{
// there was an error reading the text file, so show an error message
Console.Error.WriteLine("Error reading the message file!", e);
}
// Set the subject text of the mail that is to be included in the transfer.
transfer.subject = "Subject of the Transfer";
// Define the recipients
string[] recipients = new string[]
{
"jane.doe@abc.com",
"jack.smith@xyz.com"
};
// Get the policy rule from the server for the given recipients, so we can
// check to make sure they are allowed
Policy policy = client.RequestPolicy(recipients);
// Check to make sure the recipients are allowed and only add them
// to the transfer if they are
if (policy.FailedAddresses != null && policy.FailedAddresses.Count() > 0)
{
List<string> validRecipients = new List<string>();
foreach (string recipient in recipients)
{
if (!policy.FailedAddresses.Contains(recipient))
{
validRecipients.Add(recipient);
}
else
{
Console.WriteLine("The recipient is invalid: " + recipient);
}
}
transfer.recipients(validRecipients.ToArray());
}
else
{
// all recipients are valid
transfer.recipients(recipients);
}
// If allowed by the policy, we can also send a confidential message to the
// recipients
if (policy.AllowConfidentialMessage)
{
transfer.confidentialSubject = "Subject of the confidential message";
transfer.confidentialMessage = "This is the text of the confidential message.";
}
// Only continue if we have at least one valid recipient for the transfer
// if (transfer.getRecipientsList() == null || transfer.getRecipients().isEmpty())
if (transfer.getRecipientList() == null || transfer.getRecipientList().Count == 0)
{
throw new Exception("No valid recipients defined, aborting transfer.");
}
// Set the password mode that will be used for this transfer.
// Must be one of the password modes allowed by the policy.
// We will just pick the most secure mode allowed by the policy
passwordMode pm;
if (policy.PasswordMode.Any(x => x == passwordMode.generated))
{
pm = passwordMode.generated;
}
else if (policy.PasswordMode.Any(x => x == passwordMode.manual))
{
pm = passwordMode.manual;
}
else
{
pm = passwordMode.none;
}
transfer.passwordMode = pm;
// If password mode is MANUAL, we have to set a password
if (pm.Equals(passwordMode.manual)) {
// we have to manually set a password for this transfer
transfer.password = "p4$$w0rd";
}
// Define if the file names should be shown in the recipient's
// notification e-mail
transfer.showFilenames = true;
// Define if the sender should be notified when the recpients
// download the files
transfer.InformAboutDownload = true;
// Set the language for the recipient notification email
transfer.recipientLanguage = "en";
// Set the expiration date of the files
// (how long the files will be available for download)
// We'll just set it to the maximum allowed storage duration
int storageDuration = policy.StorageDuration;
DateTime expiration = DateTime.Now.AddDays(storageDuration);
transfer.expirationDate = expiration.ToString("yyyy-MM-dd");
// Add the files from the file system, specified as a complete file path:
transfer.Files = new List<string>()
{
@"C:\temp\transfer_file_01.txt"
};
// Now we can use this transfer object to perform the transfer
// either synchronously or asynchronously
// ...
Performing a Transfer
Synchronous
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, ... several callbacks). The method requires a Transfer object containing all the necessary transfer data, as well as several callbacks 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.
Example: Performing a Synchronous Transfer
private static void PerformTransferSynchronous()
{
// First create the Client instance
// Create a WebServiceUri for your Cryptshare Server
WebServiceUri serviceUri = new WebServiceUri("https://cryptshare.server.com");
// Create a CryptshareConnection instance for your WebServiceUri
CryptshareConnection connection = new CryptshareConnection(serviceUri);
// Create the Client instance with the sender's email address,
// the CryptshareConnection, and the path to the verification store.
Client client = new Client("sender-email@server.co", connection, @"C:\temp");
// Prepare the transfer object as described in the example above
Transfer transfer = ...
// Perform a synchronous transfer with four event handlers.
// Method will block until the transfer is completed.
client.PerformTransfer(
transfer,
UploadProgressChangedHandler,
UploadCompleteCallback,
UploadInterruptedCallback,
UploadCanceledCallback,
uploadFilesFinishedCallback: UploadFilesFinishedCallback
);
}
private static void UploadProgressChangedHandler(string currentFileNo, string currentFileName, double bytesUploaded, double bytesTotal, long bytesPerSecond)
{
// This method is called repeatedly with the current upload data
// Our upload listener will just output the current progress to the console
double percent = (((double) bytesUploaded / bytesTotal) * 100.0);
Console.WriteLine("Transfer progress ... " + ((int)percent) + "%");
}
private static void UploadCompleteCallback(Dictionary<string, string> urlMappings, Dictionary<string, string> smtpMappings, string serverGenPassword, TransferError transferError, string trackingID)
{
// This method is called when all files of the transfer have been uploaded
Console.WriteLine("Upload completed!");
}
private static void UploadInterruptedCallback(CryptshareException exception)
{
// this method is called when an exception occurs during the file upload
Console.Error.WriteLine("An exception occurred during the upload: " + exception);
}
private static void UploadCanceledCallback()
{
// This method is called when the transfer has been canceled
// using the CancelTransfer() method
Console.WriteLine("The transfer has been canceled!");
}
private static void UploadFilesFinishedCallback()
{
// This method is called when the file upload is finished and the Cryptshare Server
// is about to process the files.
Console.WriteLine("The file upload is finished!");
}
Asynchronous
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, ... several callbacks), giving it the initialized Transfer object containing all the necessary transfer data, as well as several callbacks 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 uploadCompleteCallback method will be called.
Canceling 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 canceled 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 canceled using the API. A transfer that has already been completed from the Client's point of view can only be canceled on server side by the Cryptshare system administrator.
Example: Performing an Asynchronous Transfer
private static void PerformTransferAsynchronous()
{
// First create the Client instance
// Create a WebServiceUri for your Cryptshare Server
WebServiceUri serviceUri = new WebServiceUri("https://cryptshare.server.com");
// Create a CryptshareConnection instance for your WebServiceUri
CryptshareConnection connection = new CryptshareConnection(serviceUri);
// Create the Client instance with the sender's email address,
// the CryptshareConnection, and the path to the verification store.
Client client = new Client("sender-email@server.co", connection, @"C:\temp");
// Prepare the transfer object as described in the example above
Transfer transfer = ...
// Perform an asynchronous transfer with four event handlers.
// Method will return immediately.
client.BeginTransfer(
transfer,
UploadProgressChangedHandler,
UploadCompleteCallback,
UploadInterruptedCallback,
UploadCanceledCallback,
uploadFilesFinishedCallback: UploadFilesFinishedCallback
);
}
private static void UploadProgressChangedHandler(string currentFileNo, string currentFileName, double bytesUploaded, double bytesTotal, long bytesPerSecond)
{
// This method is called repeatedly with the current upload data
// Our upload listener will just output the current progress to the console
double percent = (((double) bytesUploaded / bytesTotal) * 100.0);
Console.WriteLine("Transfer progress ... " + ((int)percent) + "%");
}
private static void UploadCompleteCallback(Dictionary<string, string> urlMappings, Dictionary<string, string> smtpMappings, string serverGenPassword, TransferError transferError, string trackingID)
{
// This method is called when all files of the transfer have been uploaded
Console.WriteLine("Upload completed!");
}
private static void UploadInterruptedCallback(CryptshareException exception)
{
// this method is called when an exception occurs during the file upload
Console.Error.WriteLine("An exception occurred during the upload: " + exception);
}
private static void UploadCanceledCallback()
{
// This method is called when the transfer has been canceled
// using the CancelTransfer() method
Console.WriteLine("The transfer has been canceled!");
}
private static void UploadFilesFinishedCallback()
{
// This method is called when the file upload is finished and the Cryptshare Server
// is about to process the files.
Console.WriteLine("The file upload is finished!");
}