Files and folders

Once connected, TTMSFNCCloudBox browses the account's files and folders. Every request is asynchronous: you call a method, the component performs the HTTP request in the background, and the result arrives in a completion event carrying a TTMSFNCCloudBaseRequestResult. This chapter covers listing folders, reading item metadata, and the event-driven result model you will use throughout the component.

The async result model

No Box method blocks waiting for the network. Each one has a matching On... event that fires when the request finishes; check ARequestResult.Success first, and read ARequestResult.ResultString for the raw response or error detail. Returned items are TTMSFNCCloudItem objects exposing FileName, Size, ID, ParentID, CreationDate and ModifiedDate.

Listing a folder

GetFolderList lists a folder — pass nil (or no argument) for the account root, or a folder item to list its contents. The items arrive in OnGetFolderList; FileLimit caps how many a single listing returns.

List a Box folderPascalC++

procedure TForm1.ListRootFolder;
begin
  TMSFNCCloudBox1.OnGetFolderList := BoxFolderListed;
  TMSFNCCloudBox1.FileLimit := 1000;   // cap items per listing (default 10000)
  TMSFNCCloudBox1.GetFolderList;        // pass nil / no argument for the root
end;

procedure TForm1.BoxFolderListed(Sender: TObject;
  const AFolderList: TTMSFNCCloudItems;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
var
  i: Integer;
begin
  if not ARequestResult.Success then
  begin
    ShowMessage('Box error: ' + ARequestResult.ResultString);
    Exit;
  end;

  ListBox1.Clear;
  for i := 0 to AFolderList.Count - 1 do
    ListBox1.Items.Add(AFolderList[i].FileName);
end;

void __fastcall TForm1::ListRootFolder()
{
  TMSFNCCloudBox1->OnGetFolderList = BoxFolderListed;
  TMSFNCCloudBox1->FileLimit = 1000;   // cap items per listing (default 10000)
  TMSFNCCloudBox1->GetFolderList();     // pass nullptr / no argument for the root
}

void __fastcall TForm1::BoxFolderListed(TObject *Sender,
  Fmx::Tmsfnccloudstorage::TTMSFNCCloudItems *AFolderList,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (!ARequestResult->Success)
  {
    ShowMessage("Box error: " + ARequestResult->ResultString);
    return;
  }

  ListBox1->Clear();
  for (int i = 0; i < AFolderList->Count; i++)
    ListBox1->Items->Add(AFolderList->Items[i]->FileName);
}

For a recursive tree, GetFolderListHierarchical walks subfolders and reports completion through OnGetFolderListComplete. GetFileByID resolves a single item directly and synchronously — unlike every other lookup on this component — when you already hold its Box ID, with no completion event to wait for.

Resolve a Box item by IDPascalC++

function TForm1.GetItemNameByID(const AItemID: string): string;
var
  it: TTMSFNCCloudItem;
begin
  Result := '';
  it := TMSFNCCloudBox1.GetFileByID(AItemID);
  if Assigned(it) then
    Result := it.FileName;
end;

System::UnicodeString __fastcall TForm1::GetItemNameByID(const System::UnicodeString AItemID)
{
  System::UnicodeString Result = "";
  Fmx::Tmsfnccloudstorage::TTMSFNCCloudItem *it = TMSFNCCloudBox1->GetFileByID(AItemID);
  if (it != nullptr)
    Result = it->FileName;
  return Result;
}

Reading item metadata

GetFileInfo (and GetFolderInfo) request metadata for one item by name or path; the result arrives in OnGetFileInfo as a TTMSFNCCloudBoxItem.

Get metadata for a Box filePascalC++

procedure TForm1.ShowFileInfo;
begin
  TMSFNCCloudBox1.OnGetFileInfo := BoxFileInfo;
  TMSFNCCloudBox1.GetFileInfo('/Reports/Q4.pdf');
end;

procedure TForm1.BoxFileInfo(Sender: TObject; const AFile: TTMSFNCCloudBoxItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add(Format('%s — %d bytes, id %s',
      [AFile.FileName, AFile.Size, AFile.ID]));
end;

void __fastcall TForm1::ShowFileInfo()
{
  TMSFNCCloudBox1->OnGetFileInfo = BoxFileInfo;
  TMSFNCCloudBox1->GetFileInfo("/Reports/Q4.pdf");
}

void __fastcall TForm1::BoxFileInfo(TObject *Sender, TTMSFNCCloudBoxItem *AFile,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (ARequestResult->Success)
    Memo1->Lines->Add(Format("%s - %d bytes, id %s",
      ARRAYOFCONST((AFile->FileName, (int)AFile->Size, AFile->ID))));
}

Combining a listing with a follow-up request

Because each step is event-driven, you chain operations by starting the next one from the previous completion event. This lists the root, then requests info for the first item once the listing arrives:

List a folder, then fetch info for the first filePascalC++

procedure TForm1.BrowseAndInspect;
begin
  TMSFNCCloudBox1.OnGetFolderList := ListThenInspect;
  TMSFNCCloudBox1.OnGetFileInfo := BoxFileInfo;
  TMSFNCCloudBox1.GetFolderList;   // root
end;

procedure TForm1.ListThenInspect(Sender: TObject;
  const AFolderList: TTMSFNCCloudItems;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if not ARequestResult.Success then
    Exit;

  // Drill into the first returned item once the listing arrives.
  if AFolderList.Count > 0 then
    TMSFNCCloudBox1.GetFileInfo(AFolderList[0].FileName);
end;

procedure TForm1.BoxFileInfo(Sender: TObject; const AFile: TTMSFNCCloudBoxItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add(AFile.FileName + ' — ' + IntToStr(AFile.Size) + ' bytes');
end;

void __fastcall TForm1::BrowseAndInspect()
{
  TMSFNCCloudBox1->OnGetFolderList = ListThenInspect;
  TMSFNCCloudBox1->OnGetFileInfo = BoxFileInfo;
  TMSFNCCloudBox1->GetFolderList();   // root
}

void __fastcall TForm1::ListThenInspect(TObject *Sender,
  Fmx::Tmsfnccloudstorage::TTMSFNCCloudItems *AFolderList,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (!ARequestResult->Success)
    return;

  // Drill into the first returned item once the listing arrives.
  if (AFolderList->Count > 0)
    TMSFNCCloudBox1->GetFileInfo(AFolderList->Items[0]->FileName);
}

void __fastcall TForm1::BoxFileInfo(TObject *Sender, TTMSFNCCloudBoxItem *AFile,
  TTMSFNCCloudBaseRequestResult *ARequestResult)
{
  if (ARequestResult->Success)
    Memo1->Lines->Add(AFile->FileName + " - " + IntToStr((int)AFile->Size) + " bytes");
}

Common mistakes

Reading results outside the event. A method returns before the network call completes — use the On... event, not the method's return value, for the data.
Ignoring ARequestResult.Success. A failed request still fires the event; always check Success before using the payload.

TTMSFNCCloudBox — GetFolderList, GetFolderListHierarchical, GetFileInfo, GetFileByID, FileLimit, OnGetFolderList