Table of Contents

Search and download

Beyond browsing folder by folder, TTMSFNCCloudDropBox can search the account directly and pull down a whole folder as a single archive. Both are useful when you already know roughly what you are looking for and want to skip walking the folder tree yourself — a search narrows a large account down to a handful of candidates, and a ZIP download turns a folder full of files into one local transfer instead of many. This chapter covers the two search variants and downloading a folder as a ZIP file.

Searching

Search looks inside one folder for items matching a query, optionally restricted to a list of file extensions and to file-name-only matches. SearchList searches from a given folder (or the root) across the whole subtree; it always delegates to Search internally. Both are asynchronous like every other Dropbox operation — read the result from OnSearch, not from the method's return value.

procedure TForm1.SearchForInvoices;
begin
  TMSFNCCloudDropBox1.OnSearch := DropBoxSearchResults;
  // Search the root for PDF files whose name contains "invoice".
  TMSFNCCloudDropBox1.Search('', 'invoice', ['pdf']);
end;

procedure TForm1.DropBoxSearchResults(Sender: TObject;
  const ASearchResults: TTMSFNCCloudDropBoxItems;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
var
  i: Integer;
begin
  if not ARequestResult.Success then
    Exit;

  for i := 0 to ASearchResults.Count - 1 do
    Memo1.Lines.Add(ASearchResults[i].FullPath);
end;

Downloading a folder as a ZIP archive

DownloadFolderAsZip downloads an entire folder and its contents as a single ZIP file to a local path, saving you from listing and downloading every item individually. It reports completion through the same OnDownloadFile event used by a regular file download.

procedure TForm1.DownloadFolderArchive(AFolder: TTMSFNCCloudItem);
begin
  TMSFNCCloudDropBox1.OnDownloadFile := DropBoxFolderZipDownloaded;
  TMSFNCCloudDropBox1.DownloadFolderAsZip(AFolder, 'C:\local\reports-archive.zip');
end;

procedure TForm1.DropBoxFolderZipDownloaded(Sender: TObject;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    ShowMessage('Folder archive downloaded')
  else
    ShowMessage('Download failed: ' + ARequestResult.ResultString);
end;

Combining a search with a folder download

Searching first lets you confirm you have the right folder before downloading its full contents — here a search resolves a folder by name, and the first matching folder result is downloaded as a ZIP archive once the search completes:

procedure TForm1.SearchAndArchiveFolder(const AFolderQuery: string);
begin
  TMSFNCCloudDropBox1.OnSearch := DropBoxSearchThenDownload;
  TMSFNCCloudDropBox1.OnDownloadFile := DropBoxSearchedFolderDownloaded;
  TMSFNCCloudDropBox1.Search('', AFolderQuery, nil, True);
end;

procedure TForm1.DropBoxSearchThenDownload(Sender: TObject;
  const ASearchResults: TTMSFNCCloudDropBoxItems;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
var
  i: Integer;
begin
  if not ARequestResult.Success then
    Exit;

  for i := 0 to ASearchResults.Count - 1 do
  begin
    if ASearchResults[i].ItemType = ciFolder then
    begin
      TMSFNCCloudDropBox1.DownloadFolderAsZip(ASearchResults[i], 'C:\local\search-result.zip');
      Break;
    end;
  end;
end;

procedure TForm1.DropBoxSearchedFolderDownloaded(Sender: TObject;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    ShowMessage('Matching folder downloaded as ZIP');
end;

Common mistakes

  • Reading the return value of Search/SearchList. Like every other Dropbox operation, both execute asynchronously — the returned collection is not guaranteed to be populated yet. Use OnSearch.
  • Passing a file item to DownloadFolderAsZip. The method expects a folder item; downloading a single file uses Download instead.
  • Downloading a very large folder as a ZIP. Dropbox generates the archive server-side before streaming it back; an extremely large folder can take a long time or exceed Dropbox's own ZIP-generation limits. Prefer per-file downloads for very large folders.

See also