Skip to main content
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.

Search a Dropbox accountPascalC++
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.Items[i].FullPath);
end;

void __fastcall TForm1::SearchForInvoices()
{
  TMSFNCCloudDropBox1->OnSearch = DropBoxSearchResults;
  // Search the root for PDF files whose name contains "invoice".
  Fmx::Tmsfnccloudstorage::TStringArray Extensions;
  Extensions.Length = 1;
  Extensions[0] = "pdf";
  TMSFNCCloudDropBox1->Search("", "invoice", Extensions);
}

void __fastcall TForm1::DropBoxSearchResults(TObject *Sender,
  TTMSFNCCloudDropBoxItems *ASearchResults,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (!ARequestResult->Success)
    return;

  for (int i = 0; i < ASearchResults->Count; i++)
    Memo1->Lines->Add(ASearchResults->Items[i]->FullPath());
}

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.

Download a Dropbox folder as a ZIP archivePascalC++
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;

void __fastcall TForm1::DownloadFolderArchive(Fmx::Tmsfnccloudstorage::TTMSFNCCloudItem *AFolder)
{
  TMSFNCCloudDropBox1->OnDownloadFile = DropBoxFolderZipDownloaded;
  TMSFNCCloudDropBox1->DownloadFolderAsZip(AFolder, "C:\\local\\reports-archive.zip");
}

void __fastcall TForm1::DropBoxFolderZipDownloaded(TObject *Sender,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (ARequestResult->Success)
    ShowMessage("Folder archive downloaded");
  else
    ShowMessage("Download failed: " + ARequestResult->ResultString);
}

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:

Search for a folder, then download it as a ZIPPascalC++
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;

void __fastcall TForm1::SearchAndArchiveFolder(const System::UnicodeString AFolderQuery)
{
  TMSFNCCloudDropBox1->OnSearch = DropBoxSearchThenDownload;
  TMSFNCCloudDropBox1->OnDownloadFile = DropBoxSearchedFolderDownloaded;
  TMSFNCCloudDropBox1->Search("", AFolderQuery, Fmx::Tmsfnccloudstorage::TStringArray(), true);
}

void __fastcall TForm1::DropBoxSearchThenDownload(TObject *Sender,
  TTMSFNCCloudDropBoxItems *ASearchResults,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (!ARequestResult->Success)
    return;

  for (int i = 0; i < ASearchResults->Count; i++)
  {
    if (ASearchResults->Items[i]->ItemType == Fmx::Tmsfnccloudstorage::ciFolder)
    {
      TMSFNCCloudDropBox1->DownloadFolderAsZip(ASearchResults->Items[i], "C:\\local\\search-result.zip");
      break;
    }
  }
}

void __fastcall TForm1::DropBoxSearchedFolderDownloaded(TObject *Sender,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (ARequestResult->Success)
    ShowMessage("Matching folder downloaded as ZIP");
}

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