Table of Contents

Managing and sharing

Beyond browsing and transferring, TTMSFNCCloudBox manages the account's structure and exposes Box's sharing and account features: create and delete folders, move and rename items, search, request shared links, and read account quota. Like every Box request these are asynchronous and report through events. This chapter covers organising items, finding and sharing them, and reading account info.

Creating, renaming, moving and deleting

CreateFolder adds a folder (pass nil as the parent for the root) and reports the new item in OnCreateFolder. RenameFile, MoveFile (and MoveFileToRoot) and Delete act on an existing item.

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

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

procedure TForm1.RenameMoveDelete(AItem, ATargetFolder: TTMSFNCCloudItem);
begin
  TMSFNCCloudBox1.RenameFile(AItem, 'Q4-final.pdf');
  TMSFNCCloudBox1.MoveFile(AItem, ATargetFolder);
  TMSFNCCloudBox1.Delete(AItem);
end;

Searching and sharing

SearchList (or Search for a folder-scoped, filtered query) finds items and returns them in OnSearch. GetLink requests a direct link and GetShare a shared URL, delivered through OnGetLink / OnGetShare.

procedure TForm1.FindAndShare;
begin
  TMSFNCCloudBox1.OnSearch := BoxSearchDone;
  TMSFNCCloudBox1.OnGetLink := BoxLinkReady;
  TMSFNCCloudBox1.SearchList('budget', False, nil);   // nil folder = whole account
end;

procedure TForm1.BoxSearchDone(Sender: TObject;
  const ASearchResults: TTMSFNCCloudBoxItems;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if not ARequestResult.Success then
    Exit;

  if ASearchResults.Count > 0 then
    TMSFNCCloudBox1.GetLink(ASearchResults.Items[0]);
end;

procedure TForm1.BoxLinkReady(Sender: TObject; const ALink: string;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add('Shared link: ' + ALink);
end;

Account information

GetAccountInfo retrieves the connected user and quota into a TTMSFNCCloudBoxInfo, reported by OnGetCurrentAccount; GetDriveInfo / OnGetSpaceUsage report storage usage.

procedure TForm1.ShowAccount;
begin
  TMSFNCCloudBox1.OnGetCurrentAccount := BoxAccount;
  TMSFNCCloudBox1.GetAccountInfo;
end;

procedure TForm1.BoxAccount(Sender: TObject; const AInfo: TTMSFNCCloudBoxInfo;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add(Format('%s (%s) — %.0f of %.0f bytes used',
      [AInfo.UserName, AInfo.Email, AInfo.QuotaUsed, AInfo.Quota]));
end;

Combining create, move and share

Chaining the create, move and share events builds a small workflow — create a folder, move a file into it once it exists, then request a share URL for the moved file:

procedure TForm1.OrganiseAndShare(AFile: TTMSFNCCloudItem);
begin
  FPendingFile := AFile;     // remember the file to move once the folder exists
  TMSFNCCloudBox1.OnCreateFolder := FolderReadyMoveFile;
  TMSFNCCloudBox1.OnMoveFile := MovedNowShare;
  TMSFNCCloudBox1.OnGetShare := SharedReady;
  TMSFNCCloudBox1.CreateFolder(nil, 'Shared');
end;

procedure TForm1.FolderReadyMoveFile(Sender: TObject; const AFolder: TTMSFNCCloudItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    TMSFNCCloudBox1.MoveFile(FPendingFile, AFolder);
end;

procedure TForm1.MovedNowShare(Sender: TObject; const AFile: TTMSFNCCloudItem;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    TMSFNCCloudBox1.GetShare(AFile as TTMSFNCCloudBoxItem);
end;

procedure TForm1.SharedReady(Sender: TObject; const AShare: string;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
begin
  if ARequestResult.Success then
    Memo1.Lines.Add('Share URL: ' + AShare);
end;

Common mistakes

  • Sharing a base TTMSFNCCloudItem. GetLink / GetShare take a TTMSFNCCloudBoxItem; cast items that arrive typed as the base TTMSFNCCloudItem (search results are already Box items).
  • Deleting by stale reference. Delete the item returned by a current listing or search, not a cached one whose ID may have changed.
  • TTMSFNCCloudBox — CreateFolder, RenameFile, MoveFile, Delete, SearchList, GetLink, GetShare, GetAccountInfo

See also