Channels ▼
RSS

Open Source

Working with Dropbox


Client Query

A query is perhaps the most common task for the custom Dropbox client. Through a query, the client can find out whether the user account has a given item. It can get a list of items inside a specific folder or details about a specific item.

Queries are made with the instance method loadMetadata:.This method takes one argument: the path of the target item. The path is an instance of NSString and follows POSIX conventions.

To demonstrate, this sample snippet queries the target folder

FooDrop:
tPth = [NSString stringWithString:@"/FooDrop"];
[self.dboxClient loadMetadata:tPth];

This snippet queries the file foo.text inside the folder Public:

tPth = [NSString stringWithString:@"/Public/foo.text"];
[self.dboxClient loadMetadata:tPth];

And this one queries the whole user account:

tPth = [NSString stringWithString:@"/"];
[self.dboxClient loadMetadata:tPth];

After the client sends its query, it may invoke one of two delegate methods (Figure 5).


Figure 5.

When the query succeeds, the client invokes restClient:loadedMetadata:. This method gets two input arguments: the DBRestClient instance and the query results as a DBMetadata object.

- (void)restClient:(DBRestClient*)aSrc 
	loadedMetadata:(DBMetadata*)aDat
{
// Handle the retrieved metadata…
}

When the query fails, the client invokes restClient:loadMetadataFailedWithError:. This one also gets the same aforementioned DBRestClient instance. And it gets an NSError object describing the cause of the failure.

- (void)restClient:(DBRestClient*)aSrc 
	loadMetadataFailedWithError:(NSError*)aErr 
{
// Handle the query error…
}

In Figure 6 is the structure of the DBMetadata object.


Figure 6.

The first five properties describe the target item, be it a file or folder. The path property holds the absolute path to the item. The root property holds the folder wherein the item lies. If the item is on the root level, this property gets a value of '/'. The property totalBytes gives the item size in bytes. The property humanReadableSize gives the same size, but formatted into readable text. And the isDirectory property returns a YES for a folder item, NO for a file.

The next five properties describe the item's archival state. The thumbnailExists property holds a YES if the item is an image and has an available thumbnail. The icon property is the thumbnail itself, serialized as a byte string. The isDeleted property holds a YES if the item was deleted recently.

The revision property holds a unique ID, assigned to the item by Dropbox. The hash property also holds a unique ID. But this one is made by a mapping function. Its value varies with respect to the item's data content.

Finally, the contents property holds a list of items held by a target folder. Each list entry is an instance of DBMetadata, while the list itself is an NSArray object. If the target folder is empty, the list will have zero entries. If the target is a file, the list will be a nil.

From Client to Account

To store a file into the user's account, the custom client uses the instance method uploadFile:toPath:. The method takes two arguments: the absolute path of the target file, the path of the destination folder. This snippet, for example, uploads the file foo.text into the folder FooDrop:

tTgt = [NSString stringWithString:@"/Users/Shared/foo.text"];
tDst = [NSString stringWithString:@"FooDrop"];
[self.dboxClient uploadFile:tTgt toPath:tDst];

Both paths are NSString objects and follow POSIX conventions. If the destination is the account's root level, the path is the string '/'.

The client makes a copy of the file and sends it to Dropbox for storage (Figure 7).


Figure 7.

Afterwards, it invokes one of two delegate methods from DBRestClientDelegate. If Dropbox wrote the file into the user's account, the client invokes restClient:uploadedFile:from:. This method gets three input arguments: the usual DBRestClient instance, the name of the uploaded file, and the location of that file. The last two arguments are passed as NSString objects.

- (void)restClient:(DBRestClient*)aSrc 
	uploadedFile:(NSString*)aDst from:(NSString*)aDir 
{
// Handle the uploaded file…
}

If Dropbox failed to write the file, the client invokes restClient:uploadFileFailedWithError:. Like the previous two methods, this one gets the same DBRestClient instance and an NSError object.

- (void)restClient:(DBRestClient*)aSrc 
	uploadFileFailedWithError:(NSError*)anErr
{
// Handle the upload error…
}

From Account to Client

To retrieve a file from the user's account, the client uses the instance method loadFile:intoPath:. This method also takes two arguments: the path of the file on the user's account and the destination folder on the client platform. So, this sample snippet retrieves the file bar.text from the FooDrop folder and saves it into the folder Bar in the user's home directory.

tTgt = [NSString stringWithString:@"/FooDrop/bar.text"];
tDst = [NSString stringWithString:@"Bar"];
[self.dboxClient loadFile:tTgt intoPath:tDst];

Again, both arguments are NSString objects, and they both follow POSIX file conventions. Also, both target file and destination folder must exist at their respective locations. Once the client performs the download, it invokes one of two delegate methods shown in Figure 8.


Figure 8.

If the download succeeded, the client invokes the method restClient:loadedFile:. The delegate gets two input arguments: the DBRestClient instance and the path of the downloaded file as an NSString.

- (void)restClient:(DBRestClient*)aSrc 
	loadedFile:(NSString*)aPth 
{
// Handle the downloaded file…
}

Conversely, if the download failed, the client invokes restClient:loadFileFailedWithError:. Here, too, the arguments are the same DBRestClient instance and an NSError object.

- (void)restClient:(DBRestClient*)aSrc 
	loadFileFailedWithError:(NSError*)anErr 
{
// Handle the download error…
}

Client Does Remove

Finally, the custom client can remove an item from the user's account by using the instance method deletePath:. The method takes one input argument: the path of the target item as an NSString. This sample snippet, for instance, removes the file bar.text from the directory FooDrop.

tTgt = [NSString stringWithString:@"/FooDrop/bar.text"];
[self.dboxClient deletePath:tTgt];

When Dropbox gets the removal request, it makes a copy of the item and places the copy in its archive. Only then does it remove the original item (Figure 9).


Figure 9.

Afterwards, the client invokes one of two delegate methods. The method restClient:deletedPath: runs when the removal succeeded. It gets two input arguments: the usual DBRestClient instance and the path of the deleted item as an NSString.

- (void)restClient:(DBRestClient*) aSrc 
	deletedPath:(NSString *)aPth
{
// Handle the deletion result…
}

The method restClient:deletePathFailedWithError: runs when the removal failed. As usual, it gets a DBRestClient instance and an NSError object for input.

- (void)restClient:(DBRestClient*) aSrc 
	deletePathFailedWithError:(NSError*)anErr
{
// Handle the deletion error…
}

One caveat — if the target item is a folder, make sure to remove any items it contains first. Otherwise, Dropbox could refuse the request. This may change, however, once Dropbox supports recursive removal.

Conclusion

The Dropbox service gives its users a place to store their files online. It lets them access those same documents from any platform, be it a desktop, a Linux system, or an iOS mobile device. Access is done via a Web browser or a software client.

In this article, we looked at the benefits that Dropbox brings to its users. We studied its software clients and learned their inherent shortcomings. Next, we examined its SDK, which is available for most major languages. We learned how to get the necessary developer keys, how to prepare a shared session, and how to log into a user's account. We studied how to add a folder to the account and how to do a query. We studied how to store a file into said account, and how to retrieve it afterwards. We learned how to remove a file or folder, and we learned the delegate methods invoked by each task.

References

Dropbox.com's Dropbox for Developers. 2011.

Apple Developer Connection. Delegates and Data Sources. Cocoa Fundamentals Guide. MacOS X Developer Library. [PDF]. 2010.

Wikipedia, Dropbox Service. 2011.


JoséR. C. Cruz is a freelance engineering writer based in British Columbia. He frequently contributes articles to MacTech, REALStudio Developer, and Dr Dobb's.


Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 

Video