Table of Contents

Uploading

TTMSFNCCloudDropBox uploads a local file into a Dropbox folder, reporting completion through an event. Large files are switched to Dropbox's resumable, chunked upload session automatically — no separate method call is needed. This chapter covers a normal upload and what changes for large files.

Uploading a file

Upload sends a local file to a Dropbox folder. Use the folder-name overload for a path, or the folder-item overload when you already hold the target folder. OnUploadFile reports the created item. UploadMode controls the conflict behavior when an item with the same name already exists at the destination.

procedure TForm1.UploadReport;
begin
  TMSFNCCloudDropBox1.OnUploadFile := DropBoxUploaded;
  // Folder path; pass an empty string for the root.
  TMSFNCCloudDropBox1.Upload('/Reports', 'C:\local\Q4.pdf');
end;

procedure TForm1.DropBoxUploaded(Sender: TObject; const AUploadItem: TTMSFNCCloudItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    ShowMessage('Uploaded as ' + AUploadItem.FileName)
  else
    ShowMessage('Upload failed: ' + ARequestResult.ResultString);
end;

Resumable uploads for large files

When a file's remaining content no longer fits in a single request, the component switches to Dropbox's resumable upload session and sends the file in chunks. OnUploadResumableFile reports each chunk as it completes, OnUploadResumableFileFinished reports the final chunk, and OnUploadResumableFileFailed reports a failed chunk. You call Upload exactly as you would for a small file — the chunking is transparent:

procedure TForm1.UploadLargeFile;
begin
  TMSFNCCloudDropBox1.OnUploadResumableFile := DropBoxChunkUploaded;
  TMSFNCCloudDropBox1.OnUploadResumableFileFinished := DropBoxUploadFinished;
  TMSFNCCloudDropBox1.OnUploadResumableFileFailed := DropBoxUploadFailed;
  // The same call as a small upload; Dropbox's resumable session kicks in
  // automatically once the remaining content no longer fits a single request.
  TMSFNCCloudDropBox1.Upload('/Backups', 'C:\local\database-backup.bak');
end;

procedure TForm1.DropBoxChunkUploaded(Sender: TObject; const ACloudFile: TTMSFNCCloudFile;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    ProgressBar1.Value := Round(ACloudFile.Position / ACloudFile.GetFileSize * 100);
end;

procedure TForm1.DropBoxUploadFinished(Sender: TObject; const ACloudFile: TTMSFNCCloudFile;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    ShowMessage('Upload complete: ' + ACloudFile.FilePath);
end;

procedure TForm1.DropBoxUploadFailed(Sender: TObject; const ACloudFile: TTMSFNCCloudFile;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  ShowMessage('Upload failed: ' + ARequestResult.ResultString);
end;

Combining a normal upload with resumable progress

Because a file only switches to the resumable session once it is too large for a single request, code that handles files of unpredictable size wires both OnUploadFile and the resumable events on the same call — whichever path Dropbox takes, one of the handlers reports the outcome:

procedure TForm1.UploadFileOfAnySize(const ALocalFile: string);
begin
  TMSFNCCloudDropBox1.OnUploadFile := DropBoxUploadFileDone;
  TMSFNCCloudDropBox1.OnUploadResumableFileFinished := DropBoxUploadResumableDone;
  TMSFNCCloudDropBox1.OnUploadResumableFileFailed := DropBoxUploadResumableFailed;
  TMSFNCCloudDropBox1.Upload('/Backups', ALocalFile);
end;

procedure TForm1.DropBoxUploadFileDone(Sender: TObject; const AUploadItem: TTMSFNCCloudItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  // A small file completes here; a large file never reaches this handler.
  if ARequestResult.Success then
    ShowMessage('Uploaded as ' + AUploadItem.FileName);
end;

procedure TForm1.DropBoxUploadResumableDone(Sender: TObject; const ACloudFile: TTMSFNCCloudFile;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  // A large file completes here instead, once every chunk has been sent.
  if ARequestResult.Success then
    ShowMessage('Uploaded (resumable): ' + ACloudFile.FilePath);
end;

procedure TForm1.DropBoxUploadResumableFailed(Sender: TObject; const ACloudFile: TTMSFNCCloudFile;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  ShowMessage('Resumable upload failed: ' + ARequestResult.ResultString);
end;

Common mistakes

  • Assuming Upload is synchronous. Upload returns before the transfer finishes; act on the result in OnUploadFile (or the resumable events for a large file).
  • Only handling OnUploadFile. A large file never fires OnUploadFile on its own — it completes through OnUploadResumableFileFinished instead, so handle both if your code deals with files of unpredictable size.
  • TTMSFNCCloudDropBox — Upload, UploadMode, OnUploadFile, OnUploadResumableFile, OnUploadResumableFileFinished, OnUploadResumableFileFailed

See also