Table of Contents

Folder and file operations

Once connected, TTMSFNCCloudDropBox organises the account's structure: listing folders, creating new ones, and moving, renaming or deleting existing items. Every request is asynchronous — a method returns immediately and the outcome arrives in a matching On... event carrying a TTMSFNCCloudBaseRequestResult. This chapter covers listing, creating, and managing items, and how to chain those steps together.

The async result model

No Dropbox method blocks waiting for the network. Check ARequestResult.Success first, and read ARequestResult.ResultString for the raw response or error detail on failure. Returned items are TTMSFNCCloudDropBoxItem objects (a TTMSFNCCloudItem descendant) exposing FileName, Size, ID, Path, ParentPath and FullPath.

Listing a folder

GetFolderList lists a folder — pass nil (or no argument) for the account root, or a folder item to list its contents. Dropbox returns folders in pages: items arrive incrementally in OnGetFolderList, and OnGetFolderListComplete fires once with the full listing when every page has been retrieved. FileLimit caps how many items a single listing returns.

procedure TForm1.ListRootFolder;
begin
  TMSFNCCloudDropBox1.OnGetFolderListComplete := RootFolderListed;
  TMSFNCCloudDropBox1.GetFolderList; // nil / no argument = account root
end;

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

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

For a recursive tree, GetFolderListHierarchical walks subfolders. To resolve a single item you already know the provider ID for, GetFileByID returns it directly without listing its parent folder; the returned TTMSFNCCloudDropBoxItem.ParentPath gives you the path of the folder that contains it.

function TForm1.ShowParentOfItem(const AItemID: string): string;
var
  it: TTMSFNCCloudItem;
begin
  Result := '';
  it := TMSFNCCloudDropBox1.GetFileByID(AItemID);
  if Assigned(it) and (it is TTMSFNCCloudDropBoxItem) then
    Result := TTMSFNCCloudDropBoxItem(it).ParentPath;
end;

Creating, moving, renaming and deleting

CreateFolder adds a folder (pass nil as the parent for the root) and reports the new item in OnCreateFolder. MoveFile moves an item into a target folder, MoveFileToRoot moves it back to the account root, and RenameFile changes its name — each raises OnMoveFile / OnRenameFile. Delete removes an item, by reference or by full path.

procedure TForm1.CreateReportsFolder;
begin
  TMSFNCCloudDropBox1.OnCreateFolder := DropBoxFolderCreated;
  TMSFNCCloudDropBox1.CreateFolder(nil, 'Reports'); // nil parent = root
end;

procedure TForm1.DropBoxFolderCreated(Sender: TObject; const AFolder: TTMSFNCCloudItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add('Created folder ' + AFolder.FileName);
end;

procedure TForm1.MoveRenameDeleteItem(AItem, ATargetFolder: TTMSFNCCloudItem);
begin
  TMSFNCCloudDropBox1.OnMoveFile := DropBoxFileMoved;
  TMSFNCCloudDropBox1.OnRenameFile := DropBoxFileRenamed;
  TMSFNCCloudDropBox1.OnDeleteItem := DropBoxItemDeleted;

  TMSFNCCloudDropBox1.MoveFile(AItem, ATargetFolder);
  TMSFNCCloudDropBox1.RenameFile(AItem, 'Q4-final.pdf');
  TMSFNCCloudDropBox1.Delete(AItem);
end;

procedure TForm1.DropBoxFileMoved(Sender: TObject; const AFile: TTMSFNCCloudItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add('Moved to ' + AFile.FileName);
end;

procedure TForm1.DropBoxFileRenamed(Sender: TObject; const AFile: TTMSFNCCloudItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add('Renamed to ' + AFile.FileName);
end;

procedure TForm1.DropBoxItemDeleted(Sender: TObject;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add('Item deleted');
end;

Combining create, move and rename

Because each step is event-driven, you chain operations by starting the next one from the previous completion event. This creates a folder, then moves a file into it and renames it once the folder exists:

// Assumes a private field: FItemToArchive: TTMSFNCCloudItem;
// (needed to carry the item across the CreateFolder -> MoveFile event chain).
procedure TForm1.ArchiveItem(AItem: TTMSFNCCloudItem);
begin
  FItemToArchive := AItem;
  TMSFNCCloudDropBox1.OnCreateFolder := DropBoxArchiveFolderCreated;
  TMSFNCCloudDropBox1.OnMoveFile := DropBoxArchiveFileMoved;
  TMSFNCCloudDropBox1.CreateFolder(nil, 'Archive');
end;

procedure TForm1.DropBoxArchiveFolderCreated(Sender: TObject; const AFolder: TTMSFNCCloudItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    TMSFNCCloudDropBox1.MoveFile(FItemToArchive, AFolder);
end;

procedure TForm1.DropBoxArchiveFileMoved(Sender: TObject; const AFile: TTMSFNCCloudItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    TMSFNCCloudDropBox1.RenameFile(AFile, 'archived-' + AFile.FileName);
end;

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.
  • Deleting by a stale reference. Delete the item returned by a current listing or search, not a cached one whose path may have changed after a rename or move.
  • Assuming GetFolderList is complete after OnGetFolderList. That event fires per page; wait for OnGetFolderListComplete before treating the listing as final.

See also