Dropbox API for Delphi

	Dropbox API for Delphi

The Dropbox API library for Delphi allows working with Dropbox directory using official Dropbox API v2.

The library includes a powerful OAuth 2.0 support with a consistent interface. You can use the Dropbox API for Delphi to download and upload files, manage files and folders on Dropbox directory.

This article describes how connect to Dropbox account in Delphi, download and upload files programmatically, create remote folders and save an URL into a file in user's Dropbox.

Join our Mailing List and stay tuned: SUBSCRIBE

Introduction

The usage of Dropbox API for Delphi is simple and is similar to Dropbox for .NET and Dropbox for Java. Dropbox API for Delphi implements a set of HTTP endpoints that help your app integrate with Dropbox. The structure and members of classes from Dropbox API for Delphi helps you to easily migrate an existing .NET or Java code to Delphi.

Dropbox API utilizes JSON objects for exchanging data with connected users. The library provides a set of object types for specifying command parameters and reading responses from Dropbox service. JSON serialization is implemented using custom attributes and Delphi RTTI. To learn more on how it works, please check the JSON object serializer for Delphi article.

The object structure provides basic abstract service classes that allow you to implement any solution for HTTP, OAUTH and JSON functionality. You are free to implement any available solution, including open source libraries, such as Indy.

By default, we used the Internet components from Clever Internet Suite, since it provides all required features, works fast and stable and can be flexibly customized to meet individual non-standard requirements.

Download and upload files

Dropbox API for Delphi provides two levels of communication with Dropbox service: API objects and functions that are similar to standard Dropbox for .NET and Dropbox for Java libraries and a special DropboxManager object that implements simplified interface for commonly used Dropbox tasks: connect to the user's Dropbox, download and upload files, create folders, etc. in a single line of source code.

// [Delphi]
DropboxManager1.Download('/testfile.txt', stream);
DropboxManager1.Upload(stream, '/testfile.txt');

If you want more options or more flexible control when working with Dropbox service, you can use the DropboxClient API object and all related objects from the Dropbox API for Delphi library.

// [Delphi]
procedure TForm1.Download(const ASourceFile: string; ADestination: TStream);
var
args: TDownloadArg;
res: TFileMetadata;
begin
args := nil; res := nil;
try
  args := TDownloadArg.Create();
  args.Path := APath;

  res := FDropboxClient.Files.Download(args, ADestination);
finally
  res.Free();
  args.Free();
end;
end;

Manage files and folders

There are several Dropbox commands for managing files and folders on the user's Dropbox: copy, move, delete, create_folder, list_folder, etc. Each command uses its own RPC (Remote Procedure Call) end-point. To create a new folder you need to fill the request parameters, that are provided by the TCreateFolderArg object and call to the CreateFolder method of the DropboxClient's Files route:

// [Delphi]
procedure TForm1.CreateFolder(const APath: string);
var
args: TCreateFolderArg;
res: TFolderMetadata;
begin
args := nil; res := nil;
try
  args := TCreateFolderArg.Create();
  args.Path := APath;

  res := FDropboxClient.Files.CreateFolder(args);
finally
  res.Free();
  args.Free();
end;
end;

The same command can be easily performed in a single line of source code using the DropboxManager object:

// [Delphi]
DropboxManager1.CreateFolder('/TestFolder');

When you need to list the specific Dropbox folder, you need to use the ListFolder method. The DropboxClient API provides an advanced ability to manage large number of files within the folder. You can handle portions of listing with both ListFolder and ListFolderContinue methods. This allows you to stop file listing and provide your UI application with the progress information, etc. The TListFolderArg parameter allows you to set up the desired listing parameters:

// [Delphi]
procedure TForm1.ListFolder(const APath: string; AList: TStrings);
var
args: TListFolderArg;
continueArgs: TListFolderContinueArg;
res: TListFolderResult;
begin
AList.Clear();
args := nil; continueArgs := nil; res := nil;
try
  args := TListFolderArg.Create();
  args.Path := APath;
  continueArgs := TListFolderContinueArg.Create();

  res := FDropboxClient.Files.ListFolder(args);
  CollectFolderList(res, AList);//enumerate the res.Entries array and get the file and folder information

  while (res.HasMore) do
begin
continueArgs.Cursor := res.Cursor;

FreeAndNil(res);
res := FDropboxClient.Files.ListFolderContinue(continueArgs);
CollectFolderList(res, AList);
end;
finally
  res.Free();
  args.Free();
end;
end;

The usage of this method is relatively complicated. You can use the simplified DropboxManager object for listing files and directories on user's Dropbox:

// [Delphi]
DropboxManager1.ListFolder('/TestFolder', list); //returns a list of file and folder names

Save URL to Dropbox

The library presents the following two functions for saving the specific URL to the user's Dropbox: SaveUrl and SaveUrlCheckJobStatus. This command is asynchronous. The SaveUrl function initiates an asynchronous task at the Dropbox service, that downloads and stores the URL resource in a background, You can check the status of this asyncrhonous task using the SaveUrlCheckJobStatus method. The SaveUrl returns the async_job_id parameter, that can be used when checking the task status with the SaveUrlCheckJobStatus method:

// [Delphi]
function TForm1.SaveUrl(const APath, AUrl: string): string;
var
args: TSaveUrlArg;
res: TSaveUrlResult;
begin
Result := '';
args := nil; res := nil;
try
  args := TSaveUrlArg.Create();
  args.Path := APath;
args.Url := AUrl;

  res := FDropboxClient.Files.SaveUrl(args);
  if (res is TSaveUrlResultAsyncJobId) then
Result := (res as TSaveUrlResultAsyncJobId).AsyncJobId;
finally
  res.Free();
  args.Free();
end;
end;

// [Delphi]
function TForm1.SaveUrlCheckStatus(const AsyncJobId: string): string;
var
args: TPollArg;
res: TSaveUrlJobStatus;
begin
args := nil; res := nil;
try
  args := TPollArg.Create();
  args.AsyncJobId := AsyncJobId;

  res := FDropboxClient.Files.SaveUrlCheckJobStatus(args);
  if (res is TSaveUrlJobStatusInProgress) then
Result := 'in progress'
else if (res is TSaveUrlJobStatusComplete) then
Result := 'complete'
else
Result := 'Failed';
finally
  res.Free();
  args.Free();
end;
end;

The DropboxManager object provides the SaveUrl and SaveUrlCheckStatus methods correspondingly.

Service initialization

To work with Dropbox API you need first to create the DropboxClient instance and set up the OAuth credentials. Your application must send an OAuth 2.0 token with any request that accesses private user data. Open your Dropbox My apps section and set up the desired App name, App key, secret and Redirect URIs that are necessary to generate OAuth 2.0 credentials for your application. The Dropbox Service initialization code may look like the following:

// [Delphi]
function TForm1.GetClient: TDropboxClient;
var
credential: TDropboxOAuthCredential;
initializer: TServiceInitializer;
begin
if (FClient = nil) then
begin
   credential := TDropboxOAuthCredential.Create();
   initializer := TDropboxServiceInitializer.Create(credential, 'Clever Disk Manager');
   FClient := TDropboxClient.Create(initializer);

   credential.ClientID := 'x0hh..........';
   credential.ClientSecret := 'xrk............';
   credential.RedirectURL := 'http://localhost:55896';
end;
Result := FClient;
end;

In case of using of the DropboxManager object, the process of initialization is implemented in three lines of code:

// [Delphi]
DropboxManager1.ClientID := 'x0hh..........';
DropboxManager1.ClientSecret := 'xrk............';
DropboxManager1.RedirectURL := 'http://localhost:55896';

Supported compiler versions

Dropbox API for Delphi can be used in RAD Studio XE3 and later. If you modify the sources and remove all references to the RAD Studio namespaces in the 'uses' sections, you can use the library in RAD Studio 2009, 2010, XE and XE2 as well.

Download source code

The library is distributed under the terms of the GNU Lesser General Public License version 3, GNU General Public License

Name	Download
Dropbox API for Delphi	Download on GitHub
Json Serializer	Download on GitHub
Internet Components - Clever Internet Suite	Download

The current version of Dropbox API for Delphi needs for the non-free library Clever Internet Suite. This is a drawback, and we suggest the task of changing the program so that it does the same job without the non-free library. Anyone who thinks of doing substantial further work on the program, first may free it from dependence on the non-free library. The class structure allows you to easily replace the Clever Internet Suite Http and Oauth components with any other third-party free and non-free software.

The current Dropbox API for Delphi implementation supports only the Auth and Files routes of the Dropbox API v2 interface. The following routes are not yet implemented: Paper, Sharing and Users. Also, the following commands are implemented for the Files route: Copy, CreateFolder, Delete, Download, ListFolder, ListFolderContinue, Move, SaveUrl, SaveUrlCheckJobStatus, Search and Upload. We still are working on this library. The updated version will be available in the next article.

Sergey Shirokov
Clever Components team
www.clevercomponents.com